diff options
author | Shane Lontis <shane.lontis@oracle.com> | 2020-05-26 13:53:07 +1000 |
---|---|---|
committer | Shane Lontis <shane.lontis@oracle.com> | 2020-05-26 13:53:07 +1000 |
commit | b8086652650c0782bc8d63b620663e04a3c6a3a7 (patch) | |
tree | 831362a2004a3b79808f04eb4e387b7e649177ab /doc | |
parent | f32af93c924dca25728d8e7b85b8e4b660154e12 (diff) |
Update core_names.h fields and document most fields.
Renamed some values in core_names i.e Some DH specific names were changed to use DH instead of FFC.
Added some strings values related to RSA keys.
Moved set_params related docs out of EVP_PKEY_CTX_ctrl.pod into its own file.
Updated Keyexchange and signature code and docs.
Moved some common DSA/DH docs into a shared EVP_PKEY-FFC.pod.
Moved Ed25519.pod into EVP_SIGNATURE-ED25519.pod and reworked it.
Added some usage examples. As a result of the usage examples the following change was also made:
ec allows OSSL_PKEY_PARAM_USE_COFACTOR_ECDH as a settable gen parameter.
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11610)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/EVP_KDF.pod | 12 | ||||
-rw-r--r-- | doc/man3/EVP_MAC.pod | 3 | ||||
-rw-r--r-- | doc/man3/EVP_PKEY_CTX_ctrl.pod | 58 | ||||
-rw-r--r-- | doc/man3/EVP_PKEY_CTX_set_params.pod | 95 | ||||
-rw-r--r-- | doc/man7/EVP_KEYEXCH-DH.pod | 98 | ||||
-rw-r--r-- | doc/man7/EVP_KEYEXCH-ECDH.pod | 133 | ||||
-rw-r--r-- | doc/man7/EVP_KEYEXCH-X25519.pod | 50 | ||||
-rw-r--r-- | doc/man7/EVP_PKEY-DH.pod | 229 | ||||
-rw-r--r-- | doc/man7/EVP_PKEY-DSA.pod | 259 | ||||
-rw-r--r-- | doc/man7/EVP_PKEY-EC.pod | 69 | ||||
-rw-r--r-- | doc/man7/EVP_PKEY-FFC.pod | 199 | ||||
-rw-r--r-- | doc/man7/EVP_PKEY-RSA.pod | 13 | ||||
-rw-r--r-- | doc/man7/EVP_PKEY-X25519.pod | 4 | ||||
-rw-r--r-- | doc/man7/EVP_SIGNATURE-DSA.pod | 58 | ||||
-rw-r--r-- | doc/man7/EVP_SIGNATURE-ECDSA.pod | 57 | ||||
-rw-r--r-- | doc/man7/EVP_SIGNATURE-ED25519.pod (renamed from doc/man7/Ed25519.pod) | 49 | ||||
-rw-r--r-- | doc/man7/EVP_SIGNATURE-RSA.pod | 112 | ||||
-rw-r--r-- | doc/man7/OSSL_PROVIDER-FIPS.pod | 14 | ||||
-rw-r--r-- | doc/man7/OSSL_PROVIDER-default.pod | 4 | ||||
-rw-r--r-- | doc/man7/OSSL_PROVIDER-legacy.pod | 4 | ||||
-rw-r--r-- | doc/man7/provider-base.pod | 46 | ||||
-rw-r--r-- | doc/man7/provider-keyexch.pod | 64 | ||||
-rw-r--r-- | doc/man7/provider-signature.pod | 15 |
23 files changed, 1260 insertions, 385 deletions
diff --git a/doc/man3/EVP_KDF.pod b/doc/man3/EVP_KDF.pod index 2d7fe49c16..bceee3f500 100644 --- a/doc/man3/EVP_KDF.pod +++ b/doc/man3/EVP_KDF.pod @@ -68,6 +68,9 @@ EVP_KDF_fetch() fetches an implementation of a KDF I<algorithm>, given a library context I<libctx> and a set of I<properties>. See L<provider(7)/Fetching algorithms> for further information. +See L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> for the lists of +algorithms supported by the default provider. + The returned value must eventually be freed with L<EVP_KDF_free(3)>. @@ -248,14 +251,7 @@ supported by the KDF algorithm. =head1 SEE ALSO -L<EVP_KDF-SCRYPT(7)> -L<EVP_KDF-TLS1_PRF(7)> -L<EVP_KDF-PBKDF2(7)> -L<EVP_KDF-HKDF(7)> -L<EVP_KDF-SS(7)> -L<EVP_KDF-SSHKDF(7)> -L<EVP_KDF-X963(7)> -L<EVP_KDF-X942(7)> +L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> =head1 HISTORY diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod index 1b961d4978..c98c8d873a 100644 --- a/doc/man3/EVP_MAC.pod +++ b/doc/man3/EVP_MAC.pod @@ -82,6 +82,9 @@ EVP_MAC_fetch() fetches an implementation of a MAC I<algorithm>, given a library context I<libctx> and a set of I<properties>. See L<provider(7)/Fetching algorithms> for further information. +See L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)> for the list +of algorithms supported by the default provider. + The returned value must eventually be freed with L<EVP_MAC_free(3)>. diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod index 039073cacf..db91f01038 100644 --- a/doc/man3/EVP_PKEY_CTX_ctrl.pod +++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod @@ -2,10 +2,6 @@ =head1 NAME -EVP_PKEY_CTX_get_params, -EVP_PKEY_CTX_gettable_params, -EVP_PKEY_CTX_set_params, -EVP_PKEY_CTX_settable_params, EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_CTX_ctrl_uint64, @@ -78,11 +74,6 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len #include <openssl/evp.h> - int EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params); - const OSSL_PARAM *EVP_PKEY_CTX_gettable_params(EVP_PKEY_CTX *ctx); - int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params); - const OSSL_PARAM *EVP_PKEY_CTX_settable_params(EVP_PKEY_CTX *ctx); - int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, int cmd, int p1, void *p2); int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype, @@ -186,49 +177,6 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len =head1 DESCRIPTION -The EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() functions get and -send arbitrary parameters from and to the algorithm implementation respectively. -Not all parameters may be supported by all providers. -See L<OSSL_PROVIDER(3)> for more information on providers. -See L<OSSL_PARAM(3)> for more information on parameters. -These functions must only be called after the EVP_PKEY_CTX has been initialised -for use in an operation. - -The parameters currently supported by the default provider are: - -=over 4 - -=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer> - -Sets the DH padding mode. -If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the shared secret is padded with zeros -up to the size of the DH prime I<p>. -If B<OSSL_EXCHANGE_PARAM_PAD> is zero (the default) then no padding is -performed. - -=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string> - -Gets and sets the name of the digest algorithm used for the input to the -signature functions. - -=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer> - -Gets and sets the output size of the digest algorithm used for the input to the -signature functions. -The length of the "digest-size" parameter should not exceed that of a B<size_t>. -The internal algorithm that supports this parameter is DSA. - -=back - -EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() gets a -constant B<OSSL_PARAM> array that describes the gettable and -settable parameters for the current algorithm implementation, i.e. parameters -that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() -respectively. -See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. -These functions must only be called after the EVP_PKEY_CTX has been initialised -for use in an operation. - The function EVP_PKEY_CTX_ctrl() sends a control operation to the context I<ctx>. The key type used must match I<keytype> if it is not -1. The parameter I<optype> is a mask indicating which operations the control can be applied to. @@ -662,17 +610,13 @@ allocate adequate memory space for the I<id> before calling EVP_PKEY_CTX_get1_id =head1 RETURN VALUES -EVP_PKEY_CTX_set_params() returns 1 for success or 0 otherwise. -EVP_PKEY_CTX_settable_params() returns an OSSL_PARAM array on success or NULL on -error. -It may also return NULL if there are no settable parameters available. - All other functions and macros described on this page return a positive value 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_set_params(3)>, L<EVP_PKEY_CTX_new(3)>, L<EVP_PKEY_encrypt(3)>, L<EVP_PKEY_decrypt(3)>, diff --git a/doc/man3/EVP_PKEY_CTX_set_params.pod b/doc/man3/EVP_PKEY_CTX_set_params.pod new file mode 100644 index 0000000000..b4959c6f44 --- /dev/null +++ b/doc/man3/EVP_PKEY_CTX_set_params.pod @@ -0,0 +1,95 @@ +=pod + +=head1 NAME + +EVP_PKEY_CTX_set_params, +EVP_PKEY_CTX_settable_params, +EVP_PKEY_CTX_get_params, +EVP_PKEY_CTX_gettable_params +- provider parameter passing operations + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params); + const OSSL_PARAM *EVP_PKEY_CTX_settable_params(EVP_PKEY_CTX *ctx); + int EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params); + const OSSL_PARAM *EVP_PKEY_CTX_gettable_params(EVP_PKEY_CTX *ctx); + +=head1 DESCRIPTION + +The EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() functions allow +transfer of arbitrary key parameters to and from providers. +Not all parameters may be supported by all providers. +See L<OSSL_PROVIDER(3)> for more information on providers. +See L<OSSL_PARAM(3)> for more information on parameters. +These functions must only be called after the EVP_PKEY_CTX has been initialised +for use in an operation. +These methods replace the EVP_PKEY_CTX_ctrl() mechanism. (EVP_PKEY_CTX_ctrl now +calls these methods internally to interact with providers). + +EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() get a +constant B<OSSL_PARAM> array that describes the gettable and +settable parameters for the current algorithm implementation, i.e. parameters +that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() +respectively. +See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. +These functions must only be called after the EVP_PKEY_CTX has been initialised +for use in an operation. + +=head2 Parameters + +Examples of EVP_PKEY parameters include the following: + +L<provider-keymgmt(7)/Common parameters> +L<provider-keyexch(7)/Key Exchange parameters> +L<provider-signature(7)/Signature parameters> + +L<EVP_PKEY-RSA(7)/Common RSA parameters> +L<EVP_PKEY-RSA(7)/RSA key generation parameters> +L<EVP_PKEY-FFC(7)/FFC parameters> +L<EVP_PKEY-FFC(7)/FFC key generation parameters> +L<EVP_PKEY-DSA(7)/DSA parameters> +L<EVP_PKEY-DSA(7)/DSA key generation parameters> +L<EVP_PKEY-DH(7)/DH parameters> +L<EVP_PKEY-DH(7)/DH key generation parameters> +L<EVP_PKEY-EC(7)/Common EC parameters> +L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters> + +=head1 RETURN VALUES + +EVP_PKEY_CTX_set_params() returns 1 for success or 0 otherwise. +EVP_PKEY_CTX_settable_params() returns an OSSL_PARAM array on success or NULL on +error. +It may also return NULL if there are no settable parameters available. + +All other functions and macros described on this page return a positive value +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_encrypt(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)>, +L<EVP_PKEY_keygen(3)> + +=head1 HISTORY + +All functions were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2020 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 diff --git a/doc/man7/EVP_KEYEXCH-DH.pod b/doc/man7/EVP_KEYEXCH-DH.pod new file mode 100644 index 0000000000..9e9cee7dce --- /dev/null +++ b/doc/man7/EVP_KEYEXCH-DH.pod @@ -0,0 +1,98 @@ +=pod + +=head1 NAME + +EVP_KEYEXCH-DH +- DH Key Exchange algorithm support + +=head1 DESCRIPTION + +Key exchange support for the B<DH> key type. + +=head2 DH key exchange parameters + +=over 4 + +=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer> + +See L<provider-keyexch(7)/Common Key Exchange parameters>. + +=back + +=head1 EXAMPLES + +The examples assume a host and peer both generate keys using the same +named group (or domain parameters). See L<EVP_PKEY-DH(7)/Examples>. +Both the host and peer transfer their public key to each other. + +To convert the peer's generated key pair to a public key in DER format in order +to transfer to the host: + + EVP_PKEY *peer_key; /* It is assumed this contains the peers generated key */ + unsigned char *peer_pub_der = NULL; + int peer_pub_der_len; + + peer_pub_der_len = i2d_PUBKEY(peer_key, &peer_pub_der); + ... + OPENSSL_free(peer_pub_der); + +To convert the received peer's public key from DER format on the host: + + const unsigned char *pd = peer_pub_der; + EVP_PKEY *peer_pub_key = d2i_PUBKEY(NULL, &pd, peer_pub_der_len); + ... + EVP_PKEY_free(peer_pub_key); + +To derive a shared secret on the host using the host's key and the peer's public +key: + /* It is assumed that the host_key and peer_pub_key are set up */ + void derive_secret(EVP_KEY *host_key, EVP_PKEY *peer_pub_key) + { + unsigned int pad = 1; + OSSL_PARAM params[2]; + unsigned char *secret = NULL; + size_t secret_len = 0; + EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL); + + EVP_PKEY_derive_init(dctx); + + /* Optionally set the padding */ + params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad); + params[1] = OSSL_PARAM_construct_end(); + EVP_PKEY_CTX_set_params(dctx, params); + + EVP_PKEY_derive_set_peer(dctx, peer_pub_key); + + /* Get the size by passing NULL as the buffer */ + EVP_PKEY_derive(dctx, NULL, &secret_len); + secret = OPENSSL_zalloc(secret_len); + + EVP_PKEY_derive(dctx, secret, &secret_len); + ... + OPENSSL_clear_free(secret, secret_len); + EVP_PKEY_CTX_free(dctx); + } + +Very similar code can be used by the peer to derive the same shared secret +using the host's public key and the peer's generated key pair. + +=head1 SEE ALSO + +L<EVP_PKEY-DH(7)>, +L<EVP_PKEY-FFC(7)>, +L<EVP_PKEY(3)>, +L<provider-keyexch(7)>, +L<provider-keymgmt(7)>, +L<OSSL_PROVIDER-default(7)>, +L<OSSL_PROVIDER-FIPS(7)>, + +=head1 COPYRIGHT + +Copyright 2020 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 diff --git a/doc/man7/EVP_KEYEXCH-ECDH.pod b/doc/man7/EVP_KEYEXCH-ECDH.pod new file mode 100644 index 0000000000..1add4b7100 --- /dev/null +++ b/doc/man7/EVP_KEYEXCH-ECDH.pod @@ -0,0 +1,133 @@ +=pod + +=head1 NAME + +EVP_KEYEXCH-ECDH - ECDH Key Exchange algorithm support + +=head1 DESCRIPTION + +Key exchange support for the B<ECDH> key type. + +=head2 ECDH Key Exchange parameters + +=over 4 + +=item "ecdh-cofactor-mode" (B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE>) <integer> + +Sets or gets the ECDH mode of operation for the associated key exchange ctx. + +In the context of an Elliptic Curve Diffie-Hellman key exchange, this parameter +can be used to select between the plain Diffie-Hellman (DH) or Cofactor +Diffie-Hellman (CDH) variants of the key exchange algorithm. + +When setting, the value should be 1, 0 or -1, respectively forcing cofactor mode +on, off, or resetting it to the default for the private key associated with the +given key exchange ctx. + +When getting, the value should be either 1 or 0, respectively signaling if the +cofactor mode is on or off. + +See also L<provider-keymgmt(7)> for the related +B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> parameter that can be set on a +per-key basis. + +=item "kdf-type" (B<OSSL_EXCHANGE_PARAM_KDF_TYPE>) <utf8_string> + +Sets or gets the Key Derivation Function type to apply within the associated key +exchange ctx. + +=item "kdf-digest" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST>) <utf8_string> + +Sets or gets the Digest algorithm to be used as part of the Key Derivation Function +associated with the given key exchange ctx. + +=item "kdf-digest-props" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS>) <utf8_string> + +Sets properties to be used upon look up of the implementation for the selected +Digest algorithm for the Key Derivation Function associated with the given key +exchange ctx. + +=item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <size_t> + +Sets or gets the desired size for the output of the chosen Key Derivation Function +associated with the given key exchange ctx. + +=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string> + +Sets the User Key Material to be used as part of the selected Key Derivation +Function associated with the given key exchange ctx. + +=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string_ptr> + +Gets a pointer to the User Key Material to be used as part of the selected +Key Derivation Function associated with the given key exchange ctx. + +=item "kdf-ukm-len" (B<OSSL_EXCHANGE_PARAM_KDF_UKM_LEN>) <size_t> + +Gets the size of the User Key Material to be used as part of the selected +Key Derivation Function associated with the given key exchange ctx. + +=back + +=head1 EXAMPLES + +Keys for the host and peer must be generated as shown in +L<EVP_PKEY-EC(7)/Examples> using the same curve name. + +The code to generate a shared secret for the normal case is identical to +L<EVP_KEYEXCH-DH(7)/Examples>. + +To derive a shared secret on the host using the host's key and the peer's public +key but also using X963KDF with a user key material: + + /* It is assumed that the host_key, peer_pub_key and ukm are set up */ + void derive_secret(EVP_PKEY *host_key, EVP_PKEY *peer_key, + unsigned char *ukm, size_t ukm_len) + { + unsigned char secret[64]; + size_t out_len = sizeof(secret); + size_t secret_len = out_len; + unsigned int pad = 1; + OSSL_PARAM params[6]; + EVP_PKET_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL); + + EVP_PKEY_derive_init(dctx); + + params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad); + params[1] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_TYPE, + "X963KDF", 0); + params[2] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_DIGEST, + "SHA1", 0); + params[3] = OSSL_PARAM_construct_size_t(OSSL_EXCHANGE_PARAM_KDF_OUTLEN, + &out_len); + params[4] = OSSL_PARAM_construct_octet_string(OSSL_EXCHANGE_PARAM_KDF_UKM, + ukm, ukm_len); + params[5] = OSSL_PARAM_construct_end(); + EVP_PKEY_CTX_set_params(dctx, params); + + EVP_PKEY_derive_set_peer(dctx, peer_pub_key); + EVP_PKEY_derive(dctx, secret, &secret_len); + ... + OPENSSL_clear_free(secret, secret_len); + EVP_PKEY_CTX_free(dctx); + } + +=head1 SEE ALSO + +L<EVP_PKEY-EC(7)> +L<EVP_PKEY(3)>, +L<provider-keyexch(7)>, +L<provider-keymgmt(7)>, +L<OSSL_PROVIDER-default(7)>, +L<OSSL_PROVIDER-FIPS(7)>, + +=head1 COPYRIGHT + +Copyright 2020 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 diff --git a/doc/man7/EVP_KEYEXCH-X25519.pod b/doc/man7/EVP_KEYEXCH-X25519.pod new file mode 100644 index 0000000000..6140c56196 --- /dev/null +++ b/doc/man7/EVP_KEYEXCH-X25519.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +EVP_KEYEXCH-X25519, +EVP_KEYEXCH-X448 +- X25519 and X448 Key Exchange algorithm support + +=head1 DESCRIPTION + +Key exchange support for the B<X25519> and B<X448> key types. + +=head2 Key exchange parameters + +=over 4 + +=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer> + +See L<provider-keyexch(7)/Common Key Exchange parameters>. + +=back + +=head1 EXAMPLES + +Keys for the host and peer can be generated as shown in +L<EVP_PKEY-X25519(7)/Examples>. + +The code to generate a shared secret is identical to +L<EVP_KEYEXCH-DH(7)/Examples>. + +=head1 SEE ALSO + +L<EVP_PKEY-FFC(7)>, +L<EVP_PKEY-DH(7)> +L<EVP_PKEY(3)>, +L<provider-keyexch(7)>, +L<provider-keymgmt(7)>, +L<OSSL_PROVIDER-default(7)>, +L<OSSL_PROVIDER-FIPS(7)>, + +=head1 COPYRIGHT + +Copyright 2020 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 diff --git a/doc/man7/EVP_PKEY-DH.pod b/doc/man7/EVP_PKEY-DH.pod new file mode 100644 index 0000000000..33b19a74f9 --- /dev/null +++ b/doc/man7/EVP_PKEY-DH.pod @@ -0,0 +1,229 @@ +=pod + +=head1 NAME + +EVP_PKEY-DH, EVP_KEYMGMT-DH - EVP_PKEY DH keytype and algorithm support + +=head1 DESCRIPTION + +For B<DH> FFC key agreement, two classes of domain parameters can be used: +"safe" domain parameters that are associated with approved named safe-prime +groups, and a class of "FIPS 186-type" domain parameters. FIPS 186-type domain +parameters should only be used for backward compatibility with existing +applications that cannot be upgraded to use the approved safe-prime groups. + +See L<EVP_PKEY-FFC(7)> for more information about FFC keys. + +For B<DH> that is not a named group) the FIPS186-4 standard specifies that the +values used for FFC parameter generation are also required for parameter +validation. This means that optional FFC domain parameter values for +I<seed>, I<pcounter> and I<gindex> may need to be stored for validation purposes. +For B<DH> the I<seed> and I<pcounter> can be stored in ASN1 data +(but the I<gindex> is not). + +=head2 DH parameters + +In addition to the common FCC parameters that all FFC keytypes should support +(see L<EVP_PKEY-FFC(7)/FFC parameters>)) the B<DH> keytype +implementation supports the following: + +=over 4 + +=item "group" (B<OSSL_PKEY_PARAM_DH_GROUP>) <UTF8 string> + +Set or gets a string that associates a B<DH> named safe prime group with known +values for I<p>, I<q> and I<g>. + +The following values can be used by the OpenSSL's default and FIPS providers: +"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192", +"modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192". + +The following additional values can also be used by OpenSSL's default provider: +"modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256". + +DH named groups can be easily validated since the parameters are well known. +For protocols that only transfer I<p> and I<g> the value of I<q> can also be +retrieved. + +=item "safeprime-generator" (B<OSSL_PKEY_PARAM_DH_GENERATOR>) <integer> + +Used for DH generation of safe primes using the old generator code. +It is recommended to use a named safe prime group instead, if domain parameter +validation is required. The default value is 2. + +These are not named safe prime groups so setting this value for the OpenSSL FIPS +provider will instead choose a named safe prime group based on the size of I<p>. + +=back + +=head2 DH domain parameter / key generation parameters + +In addition to the common FCC key generation parameters that all FFC key types +should support (see L<EVP_PKEY-FFC(7)/FFC key generation parameters>)) the +B<DH> keytype implementation supports the following: + +=over 4 + +=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string> + +Sets the type of parameter generation. For B<DH> valid values are: + +=over 4 + +=item "fips186_4" + +=item "default" + +=item "fips186_2" + +These are described in L<EVP_PKEY-FFC(7)/FFC key generation parameters> + +=item "group" + +This specifies that a named safe prime name will be chosen using the "pbits" +type. + +=item "generator" + +A safe prime generator. See the "safeprime-generator" type above. + +=back + +=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer> + +Sets the size (in bits) of the prime 'p'. + +For "fips186_4" this must be 2048. +For "fips186_2" this must be 1024. +For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192. + +=item "priv_len" (B<OSSL_PKEY_PARAM_DH_PRIV_LEN>) <integer> + +An optional value to set the maximum length of the generated private key. +The default valure used if this is not set is the maximum value of +BN_num_bits(I<q>)). The minimum value that this can be set to is 2 * s. +Where s is the security strength of the key which has values of +112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192. + +=back + +=head1 EXAMPLES + +An B<EVP_PKEY> context can be obtained by calling: + + EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); + +An B<DH> key can be generated with a named safe prime group by calling: + + int priv_len = 2 * 112; + OSSL_PARAM params[3]; + EVP_PKEY *pkey = NULL; + EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); + + params[0] = OSSL_PARAM_construct_utf8_string("group", "ffdhe2048", 0); + /* "priv_len" is optional */ + params[1] = OSSL_PARAM_construct_int("priv_len", &priv_len); + params[2] = OSSL_PARAM_construct_end(); + + EVP_PKEY_keygen_init(pctx); + EVP_PKEY_CTX_set_params(pctx, params); + EVP_PKEY_gen(pctx, &pkey); + ... + EVP_PKEY_free(key); + EVP_PKEY_CTX_free(pctx); + +Legacy B<DH> domain parameters can be generated by calling: + unsigned int pbits = 2048; + unsigned int qbits = 256; + int gindex = 1; + OSSL_PARAM params[5]; + EVP_PKEY *param_key = NULL; + EVP_PKEY_CTX *pctx = NULL; + + pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); + EVP_PKEY_paramgen_init(pctx); + + params[0] = OSSL_PARAM_construct_uint("pbits", &pbits); + params[1] = OSSL_PARAM_construct_uint("qbits", &qbits); + params[2] = OSSL_PARAM_construct_int("gindex", &gindex); + params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0); + params[4] = OSSL_PARAM_construct_end(); + EVP_PKEY_CTX_set_params(pctx, params); + + EVP_PKEY_gen(pctx, ¶m_key); + + EVP_PKEY_print_params(bio_out, param_key, 0, NULL); + ... + EVP_PKEY_free(param_key); + EVP_PKEY_CTX_free(pctx); + +An B<DH> key can be generated using domain parameters by calling: + + EVP_PKEY *key = NULL; + EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL); + + EVP_PKEY_keygen_init(gctx); + EVP_PKEY_gen(gctx, &key); + EVP_PKEY_print_private(bio_out, key, 0, NULL); + ... + EVP_PKEY_free(key); + EVP_PKEY_CTX_free(gctx); + +=for comment TODO(3.0): To validate domain parameters, additional values used +during generation may be required to be set into the key. + +=head1 CONFORMING TO + +=over 4 + +=item RFC 7919 (TLS ffdhe named safe prime groups) + +=item RFC 3526 (IKE modp named safe prime groups) + +=item RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224" + and "dh_2048_256"). + +=back + +The following sections of SP800-56Ar3: + +=over 4 + +=item 5.5.1.1 FFC Domain Parameter Selection/Generation + +=item Appendix D: FFC Safe-prime Groups + +=back + +The following sections of FIPS 186-4: + +=over 4 + +=item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function. + +=item A.2.3 Generation of canonical generator g. + +=item A.2.1 Unverifiable Generation of the Generator g. + +=back + +=head1 SEE ALSO + +L<EVP_PKEY-FFC(7)>, +L<EVP_KEYEXCH-DH(7)> +L<EVP_PKEY(3)>, +L<provider-keymgmt(7)>, +L<EVP_KEYMGMT(3)>, +L<OSSL_PROVIDER-default(7)>, +L<OSSL_PROVIDER-FIPS(7)> + +=head1 COPYRIGHT + +Copyright 2020 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 diff --git a/doc/man7/EVP_PKEY-DSA.pod b/doc/man7/EVP_PKEY-DSA.pod index ccb34a9f93..680717b140 100644 --- a/doc/man7/EVP_PKEY-DSA.pod +++ b/doc/man7/EVP_PKEY-DSA.pod @@ -2,240 +2,77 @@ =head1 NAME -EVP_PKEY-DSA, EVP_KEYMGMT-DSA, EVP_PKEY-DH, EVP_KEYMGMT-DH -- EVP_PKEY DSA and DH keytype and algorithm support +EVP_PKEY-DSA, EVP_KEYMGMT-DSA - EVP_PKEY DSA keytype and algorithm support =head1 DESCRIPTION -The B<DSA> and B<DH> keytypes are implemented in OpenSSL's default and FIPS -providers. -The implementations support the basic DSA and DH keys, containing the public -and private keys I<pub> and I<priv> as well as the three main domain parameters -I<p>, I<q> and I<g>. - -Finite field cryptography (FFC) is a method of implementing discrete logarithm -cryptography using finite field mathematics. DSA is an example of FFC and -Diffie-Hellman key establishment algorithms specified in SP800-56A can also be -implemented as FFC. - -For B<DH> FFC key agreement, two classes of domain parameters can be used: -"safe" domain parameters that are associated with approved named safe-prime -groups, and a class of "FIPS 186-type" domain parameters. FIPS 186-type domain -parameters should only be used for backward compatibility with existing -applications that cannot be upgraded to use the approved safe-prime grou |