diff options
author | Pauli <paul.dale@oracle.com> | 2020-10-20 13:31:43 +1000 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2020-12-17 21:09:54 +0100 |
commit | d6fff343c85b1fd1c144690b881bf89aa6d049e6 (patch) | |
tree | d9d43d8508211cf664be7916cef618b6c7bfb8d7 | |
parent | b36d6a5ef857a9e08b1fdb80ed5aa0bdbcec9aae (diff) |
dsa: documentation deprecation changes
Fixes #13121
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13638)
-rw-r--r-- | doc/man3/DSA_SIG_new.pod | 4 | ||||
-rw-r--r-- | doc/man3/DSA_get0_pqg.pod | 11 | ||||
-rw-r--r-- | doc/man3/DSA_new.pod | 12 | ||||
-rw-r--r-- | doc/man3/DSA_size.pod | 14 | ||||
-rw-r--r-- | doc/man3/d2i_RSAPrivateKey.pod | 47 | ||||
-rw-r--r-- | doc/man3/d2i_X509.pod | 17 |
6 files changed, 78 insertions, 27 deletions
diff --git a/doc/man3/DSA_SIG_new.pod b/doc/man3/DSA_SIG_new.pod index ba925ef726..1f532d3000 100644 --- a/doc/man3/DSA_SIG_new.pod +++ b/doc/man3/DSA_SIG_new.pod @@ -43,8 +43,8 @@ DSA_SIG_set0() returns 1 on success or 0 on failure. =head1 SEE ALSO -L<DSA_new(3)>, L<ERR_get_error(3)>, -L<DSA_do_sign(3)> +L<EVP_PKEY_new(3)>, L<EVP_PKEY_free(3)>, L<EVP_PKEY_get_bn_param(3)>, +L<ERR_get_error(3)> =head1 COPYRIGHT diff --git a/doc/man3/DSA_get0_pqg.pod b/doc/man3/DSA_get0_pqg.pod index 5aa2c75714..3542a771e9 100644 --- a/doc/man3/DSA_get0_pqg.pod +++ b/doc/man3/DSA_get0_pqg.pod @@ -13,6 +13,10 @@ setting data in a DSA object #include <openssl/dsa.h> +Deprecated since OpenSSL 3.0, can be hidden entirely by defining +B<OPENSSL_API_COMPAT> with a suitable version value, see +L<openssl_user_macros(7)>: + void DSA_get0_pqg(const DSA *d, const BIGNUM **p, const BIGNUM **q, const BIGNUM **g); int DSA_set0_pqg(DSA *d, BIGNUM *p, BIGNUM *q, BIGNUM *g); @@ -31,6 +35,9 @@ setting data in a DSA object =head1 DESCRIPTION +All of the functions described on this page are deprecated. +Applications should instead use L<EVP_PKEY_get_bn_param(3)>. + A DSA object contains the parameters B<p>, B<q> and B<g>. It also contains a public key (B<pub_key>) and (optionally) a private key (B<priv_key>). @@ -94,13 +101,15 @@ has been set. =head1 SEE ALSO +L<EVP_PKEY_get_bn_param(3)>, L<DSA_new(3)>, L<DSA_new(3)>, L<DSA_generate_parameters(3)>, L<DSA_generate_key(3)>, L<DSA_dup_DH(3)>, L<DSA_do_sign(3)>, L<DSA_set_method(3)>, L<DSA_SIG_new(3)>, L<DSA_sign(3)>, L<DSA_size(3)>, L<DSA_meth_new(3)> =head1 HISTORY -The functions described here were added in OpenSSL 1.1.0. +The functions described here were added in OpenSSL 1.1.0 and deprecated in +OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man3/DSA_new.pod b/doc/man3/DSA_new.pod index 830c9938b6..0993071d18 100644 --- a/doc/man3/DSA_new.pod +++ b/doc/man3/DSA_new.pod @@ -8,12 +8,19 @@ DSA_new, DSA_free - allocate and free DSA objects #include <openssl/dsa.h> +Deprecated since OpenSSL 3.0, can be hidden entirely by defining +B<OPENSSL_API_COMPAT> with a suitable version value, see +L<openssl_user_macros(7)>: + DSA* DSA_new(void); void DSA_free(DSA *dsa); =head1 DESCRIPTION +All of the functions described on this page are deprecated. +Applications should instead use L<EVP_PKEY_new(3)> and L<EVP_PKEY_free(3)>. + DSA_new() allocates and initializes a B<DSA> structure. It is equivalent to calling DSA_new_method(NULL). @@ -32,10 +39,15 @@ DSA_free() returns no value. =head1 SEE ALSO +L<EVP_PKEY_new(3)>, L<EVP_PKEY_free(3)>, L<DSA_new(3)>, L<ERR_get_error(3)>, L<DSA_generate_parameters(3)>, L<DSA_generate_key(3)> +=head1 HISTORY + +All of these functions were deprecated in OpenSSL 3.0. + =head1 COPYRIGHT Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/DSA_size.pod b/doc/man3/DSA_size.pod index 992357c4e0..b904845447 100644 --- a/doc/man3/DSA_size.pod +++ b/doc/man3/DSA_size.pod @@ -8,25 +8,25 @@ DSA_size, DSA_bits, DSA_security_bits - get DSA signature size, key bits or secu #include <openssl/dsa.h> - int DSA_bits(const DSA *dsa); - Deprecated since OpenSSL 3.0, can be hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, see L<openssl_user_macros(7)>: + int DSA_bits(const DSA *dsa); + int DSA_size(const DSA *dsa); int DSA_security_bits(const DSA *dsa); =head1 DESCRIPTION +All of the functions described on this page are deprecated. +Applications should instead use L<EVP_PKEY_bits(3)>, +L<EVP_PKEY_security_bits(3)> and L<EVP_PKEY_size(3)>. + DSA_bits() returns the number of bits in key I<dsa>: this is the number of bits in the I<p> parameter. -The remaining functions described on this page are deprecated. -Applications should instead use L<EVP_PKEY_security_bits(3)> and -L<EVP_PKEY_size(3)>. - DSA_size() returns the maximum size of an ASN.1 encoded DSA signature for key I<dsa> in bytes. It can be used to determine how much memory must be allocated for a DSA signature. @@ -54,7 +54,7 @@ L<DSA_new(3)>, L<DSA_sign(3)> =head1 HISTORY -The DSA_size() and DSA_security_bits() functions were deprecated in OpenSSL 3.0. +All of these functions were deprecated in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man3/d2i_RSAPrivateKey.pod b/doc/man3/d2i_RSAPrivateKey.pod index 7827b3cef4..7375f1bab3 100644 --- a/doc/man3/d2i_RSAPrivateKey.pod +++ b/doc/man3/d2i_RSAPrivateKey.pod @@ -8,6 +8,14 @@ Any deprecated keypair/params d2i or i2d functions are collected on this page. =head1 NAME +d2i_DSAPrivateKey, +d2i_DSAPrivateKey_bio, +d2i_DSAPrivateKey_fp, +d2i_DSAPublicKey, +d2i_DSA_PUBKEY, +d2i_DSA_PUBKEY_bio, +d2i_DSA_PUBKEY_fp, +d2i_DSAparams, d2i_RSAPrivateKey, d2i_RSAPrivateKey_bio, d2i_RSAPrivateKey_fp, @@ -215,6 +223,45 @@ The following sample code does the rest of the work: =for comment TODO: a similar section on OSSL_DECODER is to be added +=head1 NOTES + +The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for +"internal" (that is, an internal C structure) and "DER" respectively. +So B<i2d_I<TYPE>>() converts from internal to DER. + +The functions can also understand B<BER> forms. + +The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid +populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an +empty structure such as that returned by TYPE_new(). + +The encoded data is in binary form and may contain embedded zeros. +Therefore, any FILE pointers or BIOs should be opened in binary mode. +Functions such as strlen() will B<not> return the correct length +of the encoded structure. + +The ways that I<*ppin> and I<*ppout> are incremented after the operation +can trap the unwary. See the B<WARNINGS> section for some common +errors. +The reason for this-auto increment behaviour is to reflect a typical +usage of ASN1 functions: after one structure is encoded or decoded +another will be processed after it. + +The following points about the data types might be useful: + +=over 4 + +=item B<DSA_PUBKEY> + +Represents a DSA public key using a B<SubjectPublicKeyInfo> structure. + +=item B<DSAPublicKey>, B<DSAPrivateKey> + +Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>, +L<PEM_write_PrivateKey(3)>, or similar instead. + +=back + =head1 RETURN VALUES B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod index 0b3414ba8f..d5c684e31d 100644 --- a/doc/man3/d2i_X509.pod +++ b/doc/man3/d2i_X509.pod @@ -51,15 +51,7 @@ d2i_DIRECTORYSTRING, d2i_DISPLAYTEXT, d2i_DIST_POINT, d2i_DIST_POINT_NAME, -d2i_DSAPrivateKey, -d2i_DSAPrivateKey_bio, -d2i_DSAPrivateKey_fp, -d2i_DSAPublicKey, -d2i_DSA_PUBKEY, -d2i_DSA_PUBKEY_bio, -d2i_DSA_PUBKEY_fp, d2i_DSA_SIG, -d2i_DSAparams, d2i_ECDSA_SIG, d2i_ECPKParameters, d2i_ECParameters, @@ -488,15 +480,6 @@ Represents a PKCS#3 DH parameters structure. Represents an ANSI X9.42 DH parameters structure. -=item B<DSA_PUBKEY> - -Represents a DSA public key using a B<SubjectPublicKeyInfo> structure. - -=item B<DSAPublicKey>, B<DSAPrivateKey> - -Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>, -L<PEM_write_PrivateKey(3)>, or similar instead. - =item B<ECDSA_SIG> Represents an ECDSA signature. |