Latest update

doc/man7/EVP_KDF_HKDF.pod

@@ -0,0 +1,180 @@
+=pod
+
+=head1 NAME
+
+EVP_KDF_HKDF - The HKDF EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+Support for computing the B<HKDF> KDF through the B<EVP_KDF> API.
+
+The EVP_KDF_HKDF algorithm implements the HKDF key derivation function.
+HKDF follows the "extract-then-expand" paradigm, where the KDF logically
+consists of two modules. The first stage takes the input keying material
+and "extracts" from it a fixed-length pseudorandom key K. The second stage
+"expands" the key K into several additional pseudorandom keys (the output
+of the KDF).
+
+=head2 Numeric identity
+
+B<EVP_KDF_HKDF> is the numeric identity for this implementation; it
+can be used with the EVP_KDF_CTX_new_id() function.
+
+=head2 Supported controls
+
+The supported controls are:
+
+=over 4
+
+=item B<EVP_KDF_CTRL_SET_SALT>
+
+=item B<EVP_KDF_CTRL_SET_MD>
+
+=item B<EVP_KDF_CTRL_SET_KEY>
+
+These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
+
+=item B<EVP_KDF_CTRL_RESET_HKDF_INFO>
+
+This control does not expect any arguments.
+
+Resets the context info buffer to zero length.
+
+=item B<EVP_KDF_CTRL_ADD_HKDF_INFO>
+
+This control expects two arguments: C<unsigned char *info>, C<size_t infolen>
+
+Sets the info value to the first B<infolen> bytes of the buffer B<info>.  If a
+value is already set, the contents of the buffer are appended to the existing
+value.
+
+The total length of the context info buffer cannot exceed 1024 bytes;
+this should be more than enough for any normal use of HKDF.
+
+EVP_KDF_ctrl_str() takes two type strings for this control:
+
+=over 4
+
+=item "info"
+
+The value string is used as is.
+
+=item "hexinfo"
+
+The value string is expected to be a hexadecimal number, which will be
+decoded before being passed on as the control value.
+
+=back
+
+=item B<EVP_KDF_CTRL_SET_HKDF_MODE>
+
+This control expects one argument: C<int mode>
+
+Sets the mode for the HKDF operation. There are three modes that are currently
+defined:
+
+=over 4
+
+=item EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND
+
+This is the default mode.  Calling L<EVP_KDF_derive(3)> on an EVP_KDF_CTX set
+up for HKDF will perform an extract followed by an expand operation in one go.
+The derived key returned will be the result after the expand operation. The
+intermediate fixed-length pseudorandom key K is not returned.
+
+In this mode the digest, key, salt and info values must be set before a key is
+derived otherwise an error will occur.
+
+=item EVP_KDF_HKDF_MODE_EXTRACT_ONLY
+
+In this mode calling L<EVP_KDF_derive(3)> will just perform the extract
+operation. The value returned will be the intermediate fixed-length pseudorandom
+key K.  The C<keylen> parameter must match the size of K, which can be looked
+up by calling EVP_KDF_size() after setting the mode and digest.
+
+The digest, key and salt values must be set before a key is derived otherwise
+an error will occur.
+
+=item EVP_KDF_HKDF_MODE_EXPAND_ONLY
+
+In this mode calling L<EVP_KDF_derive(3)> will just perform the expand
+operation. The input key should be set to the intermediate fixed-length
+pseudorandom key K returned from a previous extract operation.
+
+The digest, key and info values must be set before a key is derived otherwise
+an error will occur.
+
+=back
+
+EVP_KDF_ctrl_str() type string: "mode"
+
+The value string is expected to be one of: "EXTRACT_AND_EXPAND", "EXTRACT_ONLY"
+or "EXPAND_ONLY".
+
+=back
+
+=head1 NOTES
+
+A context for HKDF can be obtained by calling:
+
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
+
+The output length of an HKDF expand operation is specified via the C<keylen>
+parameter to the L<EVP_KDF_derive(3)> function.  When using
+EVP_KDF_HKDF_MODE_EXTRACT_ONLY the C<keylen> parameter must equal the size of
+the intermediate fixed-length pseudorandom key otherwise an error will occur.
+For that mode, the fixed output size can be looked up by calling EVP_KDF_size()
+after setting the mode and digest on the C<EVP_KDF_CTX>.
+
+=head1 EXAMPLE
+
+This example derives 10 bytes using SHA-256 with the secret key "secret",
+salt value "salt" and info value "label":
+
+ EVP_KDF_CTX *kctx;
+ unsigned char out[10];
+
+ kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
+
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
+     error("EVP_KDF_CTRL_SET_MD");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
+     error("EVP_KDF_CTRL_SET_SALT");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
+     error("EVP_KDF_CTRL_SET_KEY");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_HKDF_INFO, "label", (size_t)5) <= 0) {
+     error("EVP_KDF_CTRL_ADD_HKDF_INFO");
+ }
+ if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+     error("EVP_KDF_derive");
+ }
+
+ EVP_KDF_CTX_free(kctx);
+
+=head1 CONFORMING TO
+
+RFC 5869
+
+=head1 SEE ALSO
+
+L<EVP_KDF_CTX>,
+L<EVP_KDF_CTX_new_id(3)>,
+L<EVP_KDF_CTX_free(3)>,
+L<EVP_KDF_ctrl(3)>,
+L<EVP_KDF_size(3)>,
+L<EVP_KDF_derive(3)>,
+L<EVP_KDF_CTX(3)/CONTROLS>
+
+=head1 COPYRIGHT
+
+Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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

doc/man7/EVP_KDF_PBKDF2.pod

@@ -0,0 +1,78 @@
+=pod
+
+=head1 NAME
+
+EVP_KDF_PBKDF2 - The PBKDF2 EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+Support for computing the B<PBKDF2> password-based KDF through the B<EVP_KDF>
+API.
+
+The EVP_KDF_PBKDF2 algorithm implements the PBKDF2 password-based key
+derivation function, as described in RFC 2898; it derives a key from a password
+using a salt and iteration count.
+
+=head2 Numeric identity
+
+B<EVP_KDF_PBKDF2> is the numeric identity for this implementation; it
+can be used with the EVP_KDF_CTX_new_id() function.
+
+=head2 Supported controls
+
+The supported controls are:
+
+=over 4
+
+=item B<EVP_KDF_CTRL_SET_PASS>
+
+=item B<EVP_KDF_CTRL_SET_SALT>
+
+=item B<EVP_KDF_CTRL_SET_ITER>
+
+=item B<EVP_KDF_CTRL_SET_MD>
+
+These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
+
+B<iter> is the iteration count and its value should be greater than or equal to
+1. RFC 2898 suggests an iteration count of at least 1000.  The default value is
+2048.  Any B<iter> less than 1 is treated as a single iteration.
+
+=back
+
+=head1 NOTES
+
+A typical application of this algorithm is to derive keying material for an
+encryption algorithm from a password in the B<pass>, a salt in B<salt>,
+and an iteration count.
+
+Increasing the B<iter> parameter slows down the algorithm which makes it
+harder for an attacker to perform a brute force attack using a large number
+of candidate passwords.
+
+No assumption is made regarding the given password; it is simply treated as a
+byte sequence.
+
+=head1 CONFORMING TO
+
+RFC 2898
+
+=head1 SEE ALSO
+
+L<EVP_KDF_CTX>,
+L<EVP_KDF_CTX_new_id(3)>,
+L<EVP_KDF_CTX_free(3)>,
+L<EVP_KDF_ctrl(3)>,
+L<EVP_KDF_derive(3)>,
+L<EVP_KDF_CTX(3)/CONTROLS>
+
+=head1 COPYRIGHT
+
+Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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

doc/man7/EVP_KDF_SCRYPT.pod

@@ -2,11 +2,14 @@
 
 =head1 NAME
 
-scrypt - EVP_PKEY scrypt KDF support
+EVP_KDF_SCRYPT - The scrypt EVP_KDF implementation
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_SCRYPT algorithm implements the scrypt password based key
+Support for computing the B<scrypt> password-based KDF through the B<EVP_KDF>
+API.
+
+The EVP_KDF_SCRYPT algorithm implements the scrypt password-based key
 derivation function, as described in RFC 7914.  It is memory-hard in the sense
 that it deliberately requires a significant amount of RAM for efficient
 computation. The intention of this is to render brute forcing of passwords on
@@ -26,49 +29,82 @@ computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N =
 2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for
 this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5
 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
+they default to 1048576, 8, and 1, respectively. The maximum amount of RAM that
 may be used by scrypt defaults to 1025 MiB.
 
+=head2 Numeric identity
+
+B<EVP_KDF_SCRYPT> is the numeric identity for this implementation; it
+can be used with the EVP_KDF_CTX_new_id() function.
+
+=head2 Supported controls
+
+The supported controls are:
+
+=over 4
+
+=item B<EVP_KDF_CTRL_SET_PASS>
+
+=item B<EVP_KDF_CTRL_SET_SALT>
+
+These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
+
+=item B<EVP_KDF_CTRL_SET_SCRYPT_N>
+
+=item B<EVP_KDF_CTRL_SET_SCRYPT_R>
+
+=item B<EVP_KDF_CTRL_SET_SCRYPT_P>
+
+B<EVP_KDF_CTRL_SET_SCRYPT_N> expects one argument: C<uint64_t N>
+
+B<EVP_KDF_CTRL_SET_SCRYPT_R> expects one argument: C<uint32_t r>
+
+B<EVP_KDF_CTRL_SET_SCRYPT_P> expects one argument: C<uint32_t p>
+
+These controls configure the scrypt work factors N, r and p.
+
+EVP_KDF_ctrl_str() type strings: "N", "r" and "p", respectively.
+
+The corresponding value strings are expected to be decimal numbers.
+
+=back
+
 =head1 NOTES
 
 A context for scrypt can be obtained by calling:
 
- EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL);
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SCRYPT);
 
 The output length of an scrypt key derivation is specified via the
-length parameter to the L<EVP_PKEY_derive(3)> function.
+B<keylen> parameter to the L<EVP_KDF_derive(3)> function.
 
 =head1 EXAMPLE
 
-This example derives a 64-byte long test vector using scrypt using the password
+This example derives a 64-byte long test vector using scrypt with the password
 "password", salt "NaCl" and N = 1024, r = 8, p = 16.
 
- EVP_PKEY_CTX *pctx;
+ EVP_KDF_CTX *kctx;
  unsigned char out[64];
 
- size_t outlen = sizeof(out);
- pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL);
+ kctx = EVP_KDF_CTX_new_id(EVP_KDF_SCRYPT);
 
- if (EVP_PKEY_derive_init(pctx) <= 0) {
-     error("EVP_PKEY_derive_init");
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_PASS, "password", (size_t)8) <= 0) {
+     error("EVP_KDF_CTRL_SET_PASS");
  }
- if (EVP_PKEY_CTX_set1_pbe_pass(pctx, "password", 8) <= 0) {
-     error("EVP_PKEY_CTX_set1_pbe_pass");
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "NaCl", (size_t)4) <= 0) {
+     error("EVP_KDF_CTRL_SET_SALT");
  }
- if (EVP_PKEY_CTX_set1_scrypt_salt(pctx, "NaCl", 4) <= 0) {
-     error("EVP_PKEY_CTX_set1_scrypt_salt");
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_N, (uint64_t)1024) <= 0) {
+     error("EVP_KDF_CTRL_SET_SCRYPT_N");
  }
- if (EVP_PKEY_CTX_set_scrypt_N(pctx, 1024) <= 0) {
-     error("EVP_PKEY_CTX_set_scrypt_N");
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_R, (uint32_t)8) <= 0) {
+     error("EVP_KDF_CTRL_SET_SCRYPT_R");
  }
- if (EVP_PKEY_CTX_set_scrypt_r(pctx, 8) <= 0) {
-     error("EVP_PKEY_CTX_set_scrypt_r");
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_P, (uint32_t)16) <= 0) {
+     error("EVP_KDF_CTRL_SET_SCRYPT_P");
  }
- if (EVP_PKEY_CTX_set_scrypt_p(pctx, 16) <= 0) {
-     error("EVP_PKEY_CTX_set_scrypt_p");
- }
- if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) {
-     error("EVP_PKEY_derive");
+ if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+     error("EVP_KDF_derive");
  }
 
  {
@@ -86,7 +122,7 @@ This example derives a 64-byte long test vector using scrypt using the password
      assert(!memcmp(out, expected, sizeof(out)));
  }
 
- EVP_PKEY_CTX_free(pctx);
+ EVP_KDF_CTX_free(kctx);
 
 =head1 CONFORMING TO
 
@@ -94,14 +130,12 @@ 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)>
+L<EVP_KDF_CTX>,
+L<EVP_KDF_CTX_new_id(3)>,
+L<EVP_KDF_CTX_free(3)>,
+L<EVP_KDF_ctrl(3)>,
+L<EVP_KDF_derive(3)>,
+L<EVP_KDF_CTX(3)/CONTROLS>
 
 =head1 COPYRIGHT
 

doc/man7/EVP_KDF_TLS1_PRF.pod

@@ -0,0 +1,142 @@
+=pod
+
+=head1 NAME
+
+EVP_KDF_TLS1_PRF - The TLS1 PRF EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+Support for computing the B<TLS1> PRF through the B<EVP_KDF> API.
+
+The EVP_KDF_TLS1_PRF algorithm implements the PRF used by TLS versions up to
+and including TLS 1.2.
+
+=head2 Numeric identity
+
+B<EVP_KDF_TLS1_PRF> is the numeric identity for this implementation; it
+can be used with the EVP_KDF_CTX_new_id() function.
+
+=head2 Supported controls
+
+The supported controls are:
+
+=over 4
+
+=item B<EVP_KDF_CTRL_SET_MD>
+
+This control works as described in L<EVP_KDF_CTX(3)/CONTROLS>.
+
+The C<EVP_KDF_CTRL_SET_MD> control is used to set the message digest associated
+with the TLS PRF.  EVP_md5_sha1() is treated as a special case which uses the
+PRF algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1.
+
+=item B<EVP_KDF_CTRL_SET_TLS_SECRET>
+
+This control expects two arguments: C<unsigned char *sec>, C<size_t seclen>
+
+Sets the secret value of the TLS PRF to B<seclen> bytes of the buffer B<sec>.
+Any existing secret value is replaced.
+
+EVP_KDF_ctrl_str() takes two type strings for this control:
+
+=over 4
+
+=item "secret"
+
+The value string is used as is.
+
+=item "hexsecret"
+
+The value string is expected to be a hexadecimal number, which will be
+decoded before being passed on as the control value.
+
+=back
+
+=item B<EVP_KDF_CTRL_RESET_TLS_SEED>
+
+This control does not expect any arguments.
+
+Resets the context seed buffer to zero length.
+
+=item B<EVP_KDF_CTRL_ADD_TLS_SEED>
+
+This control expects two arguments: C<unsigned char *seed>, C<size_t seedlen>
+
+Sets the seed to B<seedlen> bytes of B<seed>.  If a seed is already set it is
+appended to the existing value.
+
+The total length of the context seed buffer cannot exceed 1024 bytes;
+this should be more than enough for any normal use of the TLS PRF.
+
+EVP_KDF_ctrl_str() takes two type strings for this control:
+
+=over 4
+
+=item "seed"
+
+The value string is used as is.
+
+=item "hexseed"
+
+The value string is expected to be a hexadecimal number, which will be
+decoded before being passed on as the control value.
+
+=back
+
+=back
+
+=head1 NOTES
+
+A context for the TLS PRF can be obtained by calling:
+
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF, NULL);
+
+The digest, secret value and seed must be set before a key is derived otherwise
+an error will occur.
+
+The output length of the PRF is specified by the C<keylen> parameter to the
+EVP_KDF_derive() function.
+
+=head1 EXAMPLE
+
+This example derives 10 bytes using SHA-256 with the secret key "secret"
+and seed value "seed":
+
+ EVP_KDF_CTX *kctx;
+ unsigned char out[10];
+
+ kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF);
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
+     error("EVP_KDF_CTRL_SET_MD");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_TLS_SECRET,
+                  "secret", (size_t)6) <= 0) {
+     error("EVP_KDF_CTRL_SET_TLS_SECRET");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_TLS_SEED, "seed", (size_t)4) <= 0) {
+     error("EVP_KDF_CTRL_ADD_TLS_SEED");
+ }
+ if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+     error("EVP_KDF_derive");
+ }
+ EVP_KDF_CTX_free(kctx);
+
+=head1 SEE ALSO
+
+L<EVP_KDF_CTX>,
+L<EVP_KDF_CTX_new_id(3)>,
+L<EVP_KDF_CTX_free(3)>,
+L<EVP_KDF_ctrl(3)>,
+L<EVP_KDF_derive(3)>,
+L<EVP_KDF_CTX(3)/CONTROLS>
+
+=head1 COPYRIGHT
+
+Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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

doc/man7/openssl_user_macros.pod.in

@@ -19,7 +19,7 @@ user defined macros.
 
 =head2 The macros
 
-=over
+=over 4
 
 =item B<OPENSSL_API_COMPAT>
 
@@ -30,7 +30,7 @@ be declared.
 
 The version number assigned to this macro can take one of two forms:
 
-=over
+=over 4
 
 =item C<0xMNNFF000L>
 
@@ -43,7 +43,7 @@ Any version number may be given, but these numbers are
 the current known major deprecation points, making them the most
 meaningful:
 
-=over
+=over 4
 
 =item C<0x00908000L> (version 0.9.8)
 
@@ -63,7 +63,7 @@ This form is a simple number that represents the major version number
 and is supported for version 3.0.0 and up.  For extra convenience,
 these numbers are also available:
 
-=over
+=over 4
 
 =item Z<>0 (C<0x00908000L>, i.e. version 0.9.8)