Latest update

doc/man7/EVP_KDF_PBKDF2.pod

@@ -10,7 +10,7 @@ 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
+derivation function, as described in SP800-132; it derives a key from a password
 using a salt and iteration count.
 
 =head2 Numeric identity
@@ -30,13 +30,38 @@ The supported controls are:
 
 =item B<EVP_KDF_CTRL_SET_ITER>
 
+This control has a default value of 2048.
+
 =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.
+=item B<EVP_KDF_CTRL_SET_PBKDF2_PKCS5_MODE>
+
+This control expects one argument: C<int mode>
+
+This control can be used to enable or disable SP800-132 compliance checks.
+
+Setting the mode to 0 enables the compliance checks.
+
+The checks performed are:
+
+=over 4
+
+=item - the iteration count is at least 1000.
+
+=item - the salt length is at least 128 bits.
+
+=item - the derived key length is at least 112 bits.
+
+=back
+
+The default provider uses a default mode of 1 for backwards compatibility,
+and the fips provider uses a default mode of 0.
+
+EVP_KDF_ctrl_str() type string: "pkcs5"
+
+The value string is expected to be a decimal number 0 or 1.
 
 =back
 
@@ -55,7 +80,7 @@ byte sequence.
 
 =head1 CONFORMING TO
 
-RFC 2898
+SP800-132
 
 =head1 SEE ALSO
 
@@ -66,9 +91,13 @@ L<EVP_KDF_ctrl(3)>,
 L<EVP_KDF_derive(3)>,
 L<EVP_KDF_CTX(3)/CONTROLS>
 
+=head1 HISTORY
+
+This functionality was added to OpenSSL 3.0.0.
+
 =head1 COPYRIGHT
 
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2018-2019 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

doc/man7/EVP_KDF_SS.pod

@@ -11,7 +11,7 @@ SSKDF derives a key using input such as a shared secret key (that was generated
 during the execution of a key establishment scheme) and fixedinfo.
 SSKDF is also informally referred to as 'Concat KDF'.
 
-=head2 Auxilary function
+=head2 Auxiliary function
 
 The implementation uses a selectable auxiliary function H, which can be one of:
 

doc/man7/EVP_KDF_SSHKDF.pod

@@ -68,12 +68,12 @@ Sets the type for the SSHHKDF operation. There are six supported types:
 
 =over 4
 
-=item EVP_KDF_SSHKDF_TYPE_ININITAL_IV_CLI_TO_SRV
+=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV
 
 The Initial IV from client to server.
 A single char of value 65 (ASCII char 'A').
 
-=item EVP_KDF_SSHKDF_TYPE_ININITAL_IV_SRV_TO_CLI
+=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI
 
 The Initial IV from server to client
 A single char of value 66 (ASCII char 'B').
@@ -103,7 +103,7 @@ A single char of value 70 (ASCII char 'F').
 EVP_KDF_ctrl_str() type string: "type"
 
 The value is a string of length one character. The only valid values
-are the numerical values of the ASCII caracters: "A" (65) to "F" (70).
+are the numerical values of the ASCII characters: "A" (65) to "F" (70).
 
 =back
 
@@ -142,7 +142,7 @@ This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
  if (EVP_KDF_CTX_set1_sshkdf_session_id(kctx, session_id, 32) <= 0)
      /* Error */
  if (EVP_KDF_CTX_set_sshkdf_type(kctx,
-                    EVP_KDF_SSHKDF_TYPE_ININITAL_IV_CLI_TO_SRV) <= 0)
+                    EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV) <= 0)
      /* Error */
  if (EVP_KDF_derive(kctx, out, &outlen) <= 0)
      /* Error */

doc/man7/EVP_KDF_X942.pod

@@ -0,0 +1,150 @@
+=pod
+
+=head1 NAME
+
+EVP_KDF_X942 - The X9.42-2001 asn1 EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+The EVP_KDF_X942 algorithm implements the key derivation function (X942KDF).
+X942KDF is used by Cryptographic Message Syntax (CMS) for DH KeyAgreement, to
+derive a key using input such as a shared secret key and other info. The other
+info is DER encoded data that contains a 32 bit counter.
+
+=head2 Numeric identity
+
+B<EVP_KDF_X942> 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>.
+
+=item B<EVP_KDF_CTRL_SET_KEY>
+
+This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen>
+
+The shared secret used for key derivation.  This control sets the secret.
+
+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_SET_UKM>
+
+This control expects two arguments: C<unsigned char *ukm>, C<size_t ukmlen>
+
+An optional random string that is provided by the sender called "partyAInfo".
+In CMS this is the user keying material.
+
+EVP_KDF_ctrl_str() takes two type strings for this control:
+
+=over 4
+
+=item "ukm"
+
+The value string is used as is.
+
+=item "hexukm"
+
+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_CEK_ALG>
+
+This control expects one argument: C<char *alg>
+
+The CEK wrapping algorithm name. 
+
+EVP_KDF_ctrl_str() type string: "cekalg"
+
+The value string is used as is.
+
+=back
+
+=head1 NOTES
+
+A context for X942KDF can be obtained by calling:
+
+EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);
+
+The output length of an X942KDF is specified via the C<keylen>
+parameter to the L<EVP_KDF_derive(3)> function.
+
+=head1 EXAMPLE
+
+This example derives 24 bytes, with the secret key "secret" and a random user
+keying material:
+
+  EVP_KDF_CTX *kctx;
+  unsigned char out[192/8];
+  unsignred char ukm[64];
+
+  if (RAND_bytes(ukm, sizeof(ukm)) <= 0)
+      error("RAND_bytes");
+
+  kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);
+  if (kctx == NULL)
+      error("EVP_KDF_CTX_new_id");
+
+  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_KEY, "secret", (size_t)6) <= 0)
+      error("EVP_KDF_CTRL_SET_KEY");
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_UKM, ukm, sizeof(ukm)) <= 0)
+      error("EVP_KDF_CTRL_SET_UKM");
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_CEK_ALG,
+                   SN_id_smime_alg_CMS3DESwrap) <= 0)
+      error("EVP_KDF_CTRL_SET_CEK_ALG");
+  if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0)
+      error("EVP_KDF_derive");
+
+  EVP_KDF_CTX_free(kctx);
+
+=head1 CONFORMING TO
+
+RFC 2631
+
+=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 HISTORY
+
+This functionality was added to OpenSSL 3.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 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_X963.pod

@@ -71,7 +71,7 @@ decoded before being passed on as the control value.
 
 =head1 NOTES
 
-X963KDF is very similar to the SSKDF that uses a digest as the auxilary function,
+X963KDF is very similar to the SSKDF that uses a digest as the auxiliary function,
 X963KDF appends the counter to the secret, whereas SSKDF prepends the counter.
 
 A context for X963KDF can be obtained by calling:

doc/man7/RAND.pod

@@ -28,6 +28,12 @@ As a normal application developer, you do not have to worry about any details,
 just use L<RAND_bytes(3)> to obtain random data.
 Having said that, there is one important rule to obey: Always check the error
 return value of L<RAND_bytes(3)> and do not take randomness for granted.
+Although (re-)seeding is automatic, it can fail because no trusted random source
+is available or the trusted source(s) temporarily fail to provide sufficient
+random seed material.
+In this case the CSPRNG enters an error state and ceases to provide output,
+until it is able to recover from the error by reseeding itself.
+For more details on reseeding and error recovery, see L<RAND_DRBG(7)>.
 
 For values that should remain secret, you can use L<RAND_priv_bytes(3)>
 instead.

doc/man7/property.pod

@@ -0,0 +1,172 @@
+=pod
+
+=head1 NAME
+
+property - Properties, a selection mechanism for algorithm implementations
+
+=head1 DESCRIPTION
+
+As of OpenSSL 3.0, a new method has been introduced to decide which of
+multiple implementations of an algorithm will be used.
+The method is centered around the concept of properties.
+Each implementation defines a number of properties and when an algorithm
+is being selected, filters based on these properties can be used to
+choose the most appropriate implementation of the algorithm.
+
+Properties are like variables, they are referenced by name and have a value
+assigned.
+
+=head2 Property Names
+
+Property names fall into two categories: those reserved by the OpenSSL
+project and user defined names.
+A I<reserved> property name consists of a single C-style identifier
+(except for leading underscores not being permitted), which begins
+with a letter and can be followed by any number of letters, numbers
+and underscores.
+Property names are case-insensitive, but OpenSSL will only use lowercase
+letters.
+
+A I<user defined> property name is similar, but it B<must> consist of
+two or more C-style identifiers, separated by periods.
+The last identifier in the name can be considered the 'true' property
+name, which is prefixed by some sort of 'namespace'.
+Providers for example could include their name in the prefix and use
+property names like
+
+  <provider_name>.<property_name>
+  <provider_name>.<algorithm_name>.<property_name>
+
+=head2 Properties
+
+A I<property> is a I<name=value> pair.
+A I<property definition> is a sequence of comma separated properties.
+There can be any number of properties in a definition.
+For example: "" defines a null property definition; "my.foo=bar"
+defines a property named I<my.foo> which has a string value I<bar> and
+"iteration.count=3" defines a property named I<iteration.count> which
+has a numeric value of I<3>.
+The full syntax for property definitions appears below.
+
+=head2 Implementations
+
+Each implementation of an algorithm can define any number of
+properties.
+For example, the default provider defines the property I<default=yes>
+for all of its algorithms.
+Likewise, the FIPS provider defines I<fips=yes> and the legacy provider
+defines I<legacy=yes> for all of their algorithms.
+
+=head2 Queries
+
+A I<property query clause> is a single conditional test.
+For example, "fips=yes", "default!=yes" or "?iteration.count!=3".
+The first two represent mandatory clauses, such clauses B<must> match
+for any algorithm to even be under consideration.
+The third clause represents an optional clause.
+Matching such clauses is not a requirement, but any additional optional
+match counts in favor of the algorithm.
+More details about that in the B<Lookups> section.
+A I<property query> is a sequence of comma separated property query clauses.
+The full syntax for property queries appears below, but the available syntactic
+features are:
+
+=over 4
+
+=item *
+
+B<=> is an infix operator providing an equality test.
+
+=item *
+
+B<!=> is an infix operator providing an inequality test.
+
+=item *
+
+B<?> is a prefix operator that means that the following clause is optional
+but preferred.
+
+=item *
+
+B<-> is a prefix operator that means any global query clause involving the
+following property name should be ignored.
+
+=item *
+
+B<"..."> is a quoted string.
+The quotes are not included in the body of the string.
+
+=item *
+
+B<'...'> is a quoted string.
+The quotes are not included in the body of the string.
+
+=back
+
+=head2 Lookups
+
+When an algorithm is looked up, a property query is used to determine
+the best matching algorithm.
+All mandatory query clauses B<must> be present and the implementation
+that additionally has the largest number of matching optional query
+clauses will be used.
+If there is more than one such optimal candidate, the result will be
+chosen from amongst those in an indeterminate way.
+Ordering of optional clauses is not significant.
+
+=head2 Shortcut
+
+In order to permit a more concise expression of boolean properties, there
+is one short cut: a property name alone (e.g. "default") is
+exactly equivalent to "default=yes" in both definitions and queries.
+
+=head2 Global and Local
+
+Two levels of property query are supported.
+A context based property query that applies to all fetch operations and a local
+property query.
+Where both the context and local queries include a clause with the same name,
+the local clause overrides the context clause.
+
+It is possible for a local property query to remove a clause in the context
+property query by preceding the property name with a '-'.
+For example, a context property query that contains "fips=yes" would normally
+result in implementations that have "fips=yes".
+
+However, if the setting of the "fips" property is irrelevant to the
+operations being performed, the local property query can include the
+clause "-fips".
+Note that the local property query could not use "fips=no" because that would
+disallow any implementations with "fips=yes" rather than not caring about the
+setting.
+
+=head1 SYNTAX
+
+The lexical syntax in EBNF is given by:
+
+ Definition     ::= PropertyName ( '=' Value )? 
+                        ( ',' PropertyName ( '=' Value )? )*
+ Query          ::= PropertyQuery ( ',' PropertyQuery )*
+ PropertyQuery  ::= '-' PropertyName
+                  | '?'? ( PropertyName (( '=' | '!=' ) Value)?)
+ Value          ::= NumberLiteral | StringLiteral
+ StringLiteral  ::= QuotedString | UnquotedString
+ QuotedString   ::= '"' [^"]* '"' | "'" [^']* "'"
+ UnquotedString ::= [^{space},]+
+ NumberLiteral  ::= '0' ( [0-7]* | 'x' [0-9A-Fa-f]+ ) | '-'? [1-9] [0-9]+
+ PropertyName   ::= [A-Z] [A-Z0-9_]* ( '.' [A-Z] [A-Z0-9_]* )*
+
+=head1 HISTORY
+
+Properties were added in OpenSSL 3.0
+
+=head1 COPYRIGHT
+
+Copyright 2019 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