[openssl-commits] [openssl] master update
Richard Levitte
levitte at openssl.org
Fri Apr 13 09:55:22 UTC 2018
The branch master has been updated
via a8ca496ddb532d7f7dc356fd2b026697388d2384 (commit)
from 76fd7a1d61924ba5ee45224454cc3754b672efbf (commit)
- Log -----------------------------------------------------------------
commit a8ca496ddb532d7f7dc356fd2b026697388d2384
Author: Richard Levitte <levitte at openssl.org>
Date: Fri Apr 13 10:14:40 2018 +0200
Split the scrypt and RSA-PSS into man3 and man7 pages
The scrypt and RSA-PSS documents were a mixture of section 3 and
section 7 material. With pre-1.1.1 OpenSSL, this is understandable,
since we had a different directory layout. With 1.1.1, we've moved to
the typical man-page directory layout, and the documents need to be
updated accordingly.
Also, the scrypt document contained a description of
EVP_PKEY_CTX_set1_pbe_pass(), which is a generic function rather than
an scrypt specific function, and therefore should be documented
separately.
Fixes #5802
Reviewed-by: Matt Caswell <matt at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5942)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/EVP_PKEY_CTX_set1_pbe_pass.pod | 70 ++++++++++++++++++
.../EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod} | 47 ++++--------
doc/man3/EVP_PKEY_CTX_set_scrypt_N.pod | 86 ++++++++++++++++++++++
doc/man7/RSA-PSS.pod | 68 +++--------------
doc/man7/scrypt.pod | 59 ++-------------
util/private.num | 9 +++
6 files changed, 197 insertions(+), 142 deletions(-)
create mode 100644 doc/man3/EVP_PKEY_CTX_set1_pbe_pass.pod
copy doc/{man7/RSA-PSS.pod => man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod} (61%)
create mode 100644 doc/man3/EVP_PKEY_CTX_set_scrypt_N.pod
diff --git a/doc/man3/EVP_PKEY_CTX_set1_pbe_pass.pod b/doc/man3/EVP_PKEY_CTX_set1_pbe_pass.pod
new file mode 100644
index 0000000..1e740f4
--- /dev/null
+++ b/doc/man3/EVP_PKEY_CTX_set1_pbe_pass.pod
@@ -0,0 +1,70 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY_CTX_set1_pbe_pass
+- generic KDF support functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/kdf.h>
+
+ int EVP_PKEY_CTX_set1_pbe_pass(EVP_PKEY_CTX *pctx, unsigned char *pass,
+ int passlen);
+
+=head1 DESCRIPTION
+
+These functions are generic support functions for all KDF algorithms.
+
+EVP_PKEY_CTX_set1_pbe_pass() sets the password to the B<passlen> first
+bytes from B<pass>.
+
+=begin comment
+
+We really should have a few more, such as EVP_PKEY_CTX_set1_kdf_salt,
+EVP_PKEY_CTX_set1_kdf_key (to be used by the algorithms that use a
+key, such as hkdf), EVP_PKEY_CTX_set1_kdf_md (same thing here).
+
+=end comment
+
+=head1 STRING CTRLS
+
+There is also support for string based control operations via
+L<EVP_PKEY_CTX_ctrl_str(3)>.
+The B<password> can be directly specified using the B<type> parameter
+"pass" or given in hex encoding using the "hexpass" parameter.
+
+=begin comment
+
+Just as for the function description, the strings "salt", "hexsalt",
+"key", "hexkey" and "md" should be generically specified, and
+supported by the algorithms that use them.
+
+=end comment
+
+=head1 NOTES
+
+All these functions are implemented as macros.
+
+=head1 RETURN VALUES
+
+All these functions return 1 for success and 0 or a negative value for failure.
+In particular a return value of -2 indicates the operation is not supported by
+the public key algorithm.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_CTX_ctrl_str(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/RSA-PSS.pod b/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod
similarity index 61%
copy from doc/man7/RSA-PSS.pod
copy to doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod
index b608561..bd1193e 100644
--- a/doc/man7/RSA-PSS.pod
+++ b/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod
@@ -2,7 +2,10 @@
=head1 NAME
-RSA-PSS - EVP_PKEY RSA-PSS algorithm support
+EVP_PKEY_CTX_set_rsa_pss_keygen_md,
+EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md,
+EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen
+- EVP_PKEY RSA-PSS algorithm support functions
=head1 SYNOPSIS
@@ -17,23 +20,9 @@ RSA-PSS - EVP_PKEY RSA-PSS algorithm support
=head1 DESCRIPTION
-The B<RSA-PSS> EVP_PKEY implementation is a restricted version of the RSA
-algorithm which only supports signing, verification and key generation
-using PSS padding modes with optional parameter restrictions.
+These are the functions that implement L<RSA-PSS(7)>.
-It has associated private key and public key formats.
-
-This algorithm shares several control operations with the B<RSA> algorithm
-but with some restrictions described below.
-
-=head1 SIGNING AND VERIFICATION
-
-Signing and verification is similar to the B<RSA> algorithm except the
-padding mode is always PSS. If the key in use has parameter restrictions then
-the corresponding signature parameters are set to the restrictions:
-for example, if the key can only be used with digest SHA256, MGF1 SHA256
-and minimum salt length 32 then the digest, MGF1 digest and salt length
-will be set to SHA256, SHA256 and 32 respectively.
+=head2 Signing and Verification
The macro EVP_PKEY_CTX_set_rsa_padding() is supported but an error is
returned if an attempt is made to set the padding mode to anything other
@@ -52,19 +41,18 @@ usage restrictions then an error is returned if an attempt is made to set the
digest to anything other than the restricted value. Otherwise these are
similar to the B<RSA> versions.
-=head1 KEY GENERATION
+=head2 Key Generation
As with RSA key generation the EVP_PKEY_CTX_set_rsa_rsa_keygen_bits()
and EVP_PKEY_CTX_set_rsa_keygen_pubexp() macros are supported for RSA-PSS:
they have exactly the same meaning as for the RSA algorithm.
-Optional parameter restrictions can be specified when generating a PSS key. By
-default no parameter restrictions are placed on the generated key. If any
-restrictions are set (using the macros described below) then B<all> parameters
-are restricted. For example, setting a minimum salt length also restricts the
-digest and MGF1 algorithms. If any restrictions are in place then they are
-reflected in the corresponding parameters of the public key when (for example)
-a certificate request is signed.
+Optional parameter restrictions can be specified when generating a PSS key.
+If any restrictions are set (using the macros described below) then B<all>
+parameters are restricted. For example, setting a minimum salt length also
+restricts the digest and MGF1 algorithms. If any restrictions are in place
+then they are reflected in the corresponding parameters of the public key
+when (for example) a certificate request is signed.
EVP_PKEY_CTX_set_rsa_pss_keygen_md() restricts the digest algorithm the
generated key can use to B<md>.
@@ -81,12 +69,6 @@ A context for the B<RSA-PSS> algorithm can be obtained by calling:
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA_PSS, NULL);
-The public key format is documented in RFC4055.
-
-The PKCS#8 private key format used for RSA-PSS keys is similar to the RSA
-format except it uses the B<id-RSASSA-PSS> OID and the parameters field, if
-present, restricts the key parameters in the same way as the public key.
-
=head1 RETURN VALUES
All these functions return 1 for success and 0 or a negative value for failure.
@@ -95,13 +77,14 @@ the public key algorithm.
=head1 SEE ALSO
+L<RSA-PSS(7)>,
L<EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_CTX_ctrl_str(3)>,
L<EVP_PKEY_derive(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/EVP_PKEY_CTX_set_scrypt_N.pod b/doc/man3/EVP_PKEY_CTX_set_scrypt_N.pod
new file mode 100644
index 0000000..4e2a4ea
--- /dev/null
+++ b/doc/man3/EVP_PKEY_CTX_set_scrypt_N.pod
@@ -0,0 +1,86 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY_CTX_set1_scrypt_salt,
+EVP_PKEY_CTX_set_scrypt_N,
+EVP_PKEY_CTX_set_scrypt_r,
+EVP_PKEY_CTX_set_scrypt_p,
+EVP_PKEY_CTX_set_scrypt_maxmem_bytes
+- EVP_PKEY scrypt KDF support functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/kdf.h>
+
+ int EVP_PKEY_CTX_set1_scrypt_salt(EVP_PKEY_CTX *pctx, unsigned char *salt,
+ int saltlen);
+
+ int EVP_PKEY_CTX_set_scrypt_N(EVP_PKEY_CTX *pctx, uint64_t N);
+
+ int EVP_PKEY_CTX_set_scrypt_r(EVP_PKEY_CTX *pctx, uint64_t r);
+
+ int EVP_PKEY_CTX_set_scrypt_p(EVP_PKEY_CTX *pctx, uint64_t p);
+
+ int EVP_PKEY_CTX_set_scrypt_maxmem_bytes(EVP_PKEY_CTX *pctx,
+ uint64_t maxmem);
+
+=head1 DESCRIPTION
+
+These functions are used to set up the necessary data to use the
+scrypt KDF.
+For more information on scrypt, see L<scrypt(7)>.
+
+EVP_PKEY_CTX_set1_scrypt_salt() sets the B<saltlen> bytes long salt
+value.
+
+EVP_PKEY_CTX_set_scrypt_N(), EVP_PKEY_CTX_set_scrypt_r() and
+EVP_PKEY_CTX_set_scrypt_p() configure the work factors N, r and p.
+
+EVP_PKEY_CTX_set_scrypt_maxmem_bytes() sets how much RAM key
+derivation may maximally use, given in bytes.
+If RAM is exceeded because the load factors are chosen too high, the
+key derivation will fail.
+
+=head1 STRING CTRLS
+
+scrypt also supports string based control operations via
+L<EVP_PKEY_CTX_ctrl_str(3)>.
+Similarly, the B<salt> can either be specified using the B<type>
+parameter "salt" or in hex encoding by using the "hexsalt" parameter.
+The work factors B<N>, B<r> and B<p> as well as B<maxmem_bytes> can be
+set by using the parameters "N", "r", "p" and "maxmem_bytes",
+respectively.
+
+=head1 NOTES
+
+The scrypt KDF also uses EVP_PKEY_CTX_set1_pbe_pass() as well as
+the value from the string controls "pass" and "hexpass".
+See L<EVP_PKEY_CTX_set1_pbe_pass(3)>.
+
+All the functions described here are implemented as macros.
+
+=head1 RETURN VALUES
+
+All these functions return 1 for success and 0 or a negative value for
+failure.
+In particular a return value of -2 indicates the operation is not
+supported by the public key algorithm.
+
+=head1 SEE ALSO
+
+L<scrypt(7)>,
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_CTX_ctrl_str(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/RSA-PSS.pod b/doc/man7/RSA-PSS.pod
index b608561..29775d8 100644
--- a/doc/man7/RSA-PSS.pod
+++ b/doc/man7/RSA-PSS.pod
@@ -4,17 +4,6 @@
RSA-PSS - EVP_PKEY RSA-PSS algorithm support
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- int EVP_PKEY_CTX_set_rsa_pss_keygen_md(EVP_PKEY_CTX *pctx,
- const EVP_MD *md);
- int EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(EVP_PKEY_CTX *pctx,
- const EVP_MD *md);
- int EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(EVP_PKEY_CTX *pctx,
- int saltlen);
-
=head1 DESCRIPTION
The B<RSA-PSS> EVP_PKEY implementation is a restricted version of the RSA
@@ -26,7 +15,7 @@ It has associated private key and public key formats.
This algorithm shares several control operations with the B<RSA> algorithm
but with some restrictions described below.
-=head1 SIGNING AND VERIFICATION
+=head2 Signing and Verification
Signing and verification is similar to the B<RSA> algorithm except the
padding mode is always PSS. If the key in use has parameter restrictions then
@@ -35,73 +24,34 @@ for example, if the key can only be used with digest SHA256, MGF1 SHA256
and minimum salt length 32 then the digest, MGF1 digest and salt length
will be set to SHA256, SHA256 and 32 respectively.
-The macro EVP_PKEY_CTX_set_rsa_padding() is supported but an error is
-returned if an attempt is made to set the padding mode to anything other
-than B<PSS>. It is otherwise similar to the B<RSA> version.
-
-The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro is used to set the salt length.
-If the key has usage restrictions then an error is returned if an attempt is
-made to set the salt length below the minimum value. It is otherwise similar
-to the B<RSA> operation except detection of the salt length (using
-RSA_PSS_SALTLEN_AUTO is not supported for verification if the key has
-usage restrictions.
-
-The EVP_PKEY_CTX_set_signature_md() and EVP_PKEY_CTX_set_rsa_mgf1_md() macros
-are used to set the digest and MGF1 algorithms respectively. If the key has
-usage restrictions then an error is returned if an attempt is made to set the
-digest to anything other than the restricted value. Otherwise these are
-similar to the B<RSA> versions.
-
-=head1 KEY GENERATION
+=head2 Key Generation
-As with RSA key generation the EVP_PKEY_CTX_set_rsa_rsa_keygen_bits()
-and EVP_PKEY_CTX_set_rsa_keygen_pubexp() macros are supported for RSA-PSS:
-they have exactly the same meaning as for the RSA algorithm.
-
-Optional parameter restrictions can be specified when generating a PSS key. By
-default no parameter restrictions are placed on the generated key. If any
-restrictions are set (using the macros described below) then B<all> parameters
-are restricted. For example, setting a minimum salt length also restricts the
-digest and MGF1 algorithms. If any restrictions are in place then they are
-reflected in the corresponding parameters of the public key when (for example)
-a certificate request is signed.
-
-EVP_PKEY_CTX_set_rsa_pss_keygen_md() restricts the digest algorithm the
-generated key can use to B<md>.
-
-EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md() restricts the MGF1 algorithm the
-generated key can use to B<md>.
-
-EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen() restricts the minimum salt length
-to B<saltlen>.
+By default no parameter restrictions are placed on the generated key.
=head1 NOTES
-A context for the B<RSA-PSS> algorithm can be obtained by calling:
-
- EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA_PSS, NULL);
-
The public key format is documented in RFC4055.
The PKCS#8 private key format used for RSA-PSS keys is similar to the RSA
format except it uses the B<id-RSASSA-PSS> OID and the parameters field, if
present, restricts the key parameters in the same way as the public key.
-=head1 RETURN VALUES
+=head1 CONFORMING TO
-All these functions return 1 for success and 0 or a negative value for failure.
-In particular a return value of -2 indicates the operation is not supported by
-the public key algorithm.
+RFC 4055
=head1 SEE ALSO
+L<EVP_PKEY_CTX_set_rsa_pss_keygen_md(3)>,
+L<EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(3)>,
+L<EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(3)>,
L<EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_CTX_ctrl_str(3)>,
L<EVP_PKEY_derive(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man7/scrypt.pod b/doc/man7/scrypt.pod
index 4de0c72..aabb6c9 100644
--- a/doc/man7/scrypt.pod
+++ b/doc/man7/scrypt.pod
@@ -4,24 +4,6 @@
scrypt - EVP_PKEY scrypt KDF support
-=head1 SYNOPSIS
-
- #include <openssl/kdf.h>
-
- int EVP_PKEY_CTX_set1_pbe_pass(EVP_PKEY_CTX *pctx, unsigned char *pass,
- int passlen);
-
- int EVP_PKEY_CTX_set1_scrypt_salt(EVP_PKEY_CTX *pctx, unsigned char *salt,
- int saltlen);
-
- int EVP_PKEY_CTX_set_scrypt_N(EVP_PKEY_CTX *pctx, uint64_t N);
-
- int EVP_PKEY_CTX_set_scrypt_r(EVP_PKEY_CTX *pctx, uint64_t r);
-
- int EVP_PKEY_CTX_set_scrypt_p(EVP_PKEY_CTX *pctx, uint64_t p);
-
- int EVP_PKEY_CTX_set_scrypt_maxmem_bytes(EVP_PKEY_CTX *pctx, uint64_t maxmem);
-
=head1 DESCRIPTION
The EVP_PKEY_SCRYPT algorithm implements the scrypt password based key
@@ -47,44 +29,14 @@ GHz), this computation takes about 3 seconds. When N, r or p are not specified,
they default to 1048576, 8, and 1, respectively. The default amount of RAM that
may be used by scrypt defaults to 1025 MiB.
-EVP_PKEY_CTX_set1_pbe_pass() sets the B<passlen> bytes long password.
-
-EVP_PKEY_CTX_set1_scrypt_salt() sets the B<saltlen> bytes long salt value.
-
-EVP_PKEY_CTX_set_scrypt_N(), EVP_PKEY_CTX_set_scrypt_r() and
-EVP_PKEY_CTX_set_scrypt_p() configure the work factors N, r and p.
-
-EVP_PKEY_CTX_set_scrypt_maxmem_bytes() sets how much RAM key derivation may
-maximally use, given in bytes. If RAM is exceeded because the load factors are
-chosen too high, the key derivation will fail.
-
-=head1 STRING CTRLS
-
-scrypt also supports string based control operations via
-L<EVP_PKEY_CTX_ctrl_str(3)>.
-The B<password> can be directly specified using the B<type> parameter "pass" or
-given in hex encoding using the "hexpass" parameter. Similarly, the B<salt> can
-either be specified using the B<type> parameter "salt" or in hex encoding by
-using the "hexsalt" parameter. The work factors B<N>, B<r> and B<p> as well as
-B<maxmem_bytes> can be set by using the parameters "N", "r", "p" and
-"maxmem_bytes", respectively.
-
=head1 NOTES
-All these functions are implemented as macros.
-
A context for scrypt can be obtained by calling:
EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_SCRYPT, NULL);
-The output length of an scrypt key derivation is specified via the length
-parameter to the L<EVP_PKEY_derive(3)> function.
-
-=head1 RETURN VALUES
-
-All these functions return 1 for success and 0 or a negative value for failure.
-In particular a return value of -2 indicates the operation is not supported by
-the public key algorithm.
+The output length of an scrypt key derivation is specified via the
+length parameter to the L<EVP_PKEY_derive(3)> function.
=head1 EXAMPLE
@@ -142,13 +94,18 @@ RFC 7914
=head1 SEE ALSO
+L<EVP_PKEY_CTX_set1_scrypt_salt(3)>,
+L<EVP_PKEY_CTX_set_scrypt_N(3)>,
+L<EVP_PKEY_CTX_set_scrypt_r(3)>,
+L<EVP_PKEY_CTX_set_scrypt_p(3)>,
+L<EVP_PKEY_CTX_set_scrypt_maxmem_bytes(3)>,
L<EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_CTX_ctrl_str(3)>,
L<EVP_PKEY_derive(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/util/private.num b/util/private.num
index 706da80..8a461ac 100644
--- a/util/private.num
+++ b/util/private.num
@@ -187,6 +187,8 @@ EVP_PKEY_CTX_get_signature_md define
EVP_PKEY_CTX_hkdf_mode define
EVP_PKEY_CTX_set1_hkdf_key define
EVP_PKEY_CTX_set1_hkdf_salt define
+EVP_PKEY_CTX_set1_pbe_pass define
+EVP_PKEY_CTX_set1_scrypt_salt define
EVP_PKEY_CTX_set1_tls1_prf_secret define
EVP_PKEY_CTX_set_dh_paramgen_generator define
EVP_PKEY_CTX_set_dh_paramgen_prime_len define
@@ -199,7 +201,14 @@ EVP_PKEY_CTX_set_hkdf_md define
EVP_PKEY_CTX_set_mac_key define
EVP_PKEY_CTX_set_rsa_keygen_pubexp define
EVP_PKEY_CTX_set_rsa_padding define
+EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md define
+EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen define
+EVP_PKEY_CTX_set_rsa_pss_keygen_md define
EVP_PKEY_CTX_set_rsa_pss_saltlen define
+EVP_PKEY_CTX_set_scrypt_N define
+EVP_PKEY_CTX_set_scrypt_r define
+EVP_PKEY_CTX_set_scrypt_maxmem_bytes define
+EVP_PKEY_CTX_set_scrypt_p define
EVP_PKEY_CTX_set_signature_md define
EVP_PKEY_CTX_set_tls1_prf_md define
EVP_PKEY_assign_DH define
More information about the openssl-commits
mailing list