From 76396ebbd7b67db90a31bb7b017eb2fcfb1c61c9 Mon Sep 17 00:00:00 2001 From: Tomas Mraz Date: Thu, 10 Mar 2022 13:13:40 +0100 Subject: Fix documentation of parameters for DH and ECDH KEX Reviewed-by: Shane Lontis Reviewed-by: Dmitry Belyavskiy (Merged from https://github.com/openssl/openssl/pull/17859) --- doc/man7/EVP_KEYEXCH-DH.pod | 36 +++++++++++++++++++++++++++-------- doc/man7/EVP_KEYEXCH-ECDH.pod | 25 +++++------------------- doc/man7/provider-keyexch.pod | 44 +++++++++++++++++++++++++++++++++---------- 3 files changed, 67 insertions(+), 38 deletions(-) (limited to 'doc/man7') diff --git a/doc/man7/EVP_KEYEXCH-DH.pod b/doc/man7/EVP_KEYEXCH-DH.pod index 44811f1e37..566e02fc75 100644 --- a/doc/man7/EVP_KEYEXCH-DH.pod +++ b/doc/man7/EVP_KEYEXCH-DH.pod @@ -15,20 +15,40 @@ Key exchange support for the B key type. =item "pad" (B) +Sets the padding mode for the associated key exchange ctx. +Setting a value of 1 will turn padding on. +Setting a value of 0 will turn padding off. +If padding is off then the derived shared secret may be smaller than the +largest possible secret size. +If padding is on then the derived shared secret will have its first bytes +filled with zeros where necessary to make the shared secret the same size as +the largest possible secret size. +The padding mode parameter is ignored (and padding implicitly enabled) when +the KDF type is set to "X942KDF-ASN1" (B). + +=item "kdf-type" (B) + +See L. + +=item "kdf-digest" (B) + +See L. + +=item "kdf-digest-props" (B) + +See L. + +=item "kdf-outlen" (B) + See L. =item "kdf-ukm" (B) -Sets the User Key Material to be used as part of the selected Key Derivation -Function associated with the given key exchange ctx. +See L. -=item "kdf-ukm" (B) +=item "cekalg" (B) -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. Providers -usually do not need to support this gettable parameter as its sole purpose -is to support functionality of the deprecated EVP_PKEY_CTX_get0_dh_kdf_ukm() -function. +See L. =back diff --git a/doc/man7/EVP_KEYEXCH-ECDH.pod b/doc/man7/EVP_KEYEXCH-ECDH.pod index 69d0d87b35..47ba2bd603 100644 --- a/doc/man7/EVP_KEYEXCH-ECDH.pod +++ b/doc/man7/EVP_KEYEXCH-ECDH.pod @@ -33,38 +33,23 @@ per-key basis. =item "kdf-type" (B) -Sets or gets the Key Derivation Function type to apply within the associated key -exchange ctx. +See L. =item "kdf-digest" (B) -Sets or gets the Digest algorithm to be used as part of the Key Derivation Function -associated with the given key exchange ctx. +See L. =item "kdf-digest-props" (B) -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. +See L. =item "kdf-outlen" (B) -Sets or gets the desired size for the output of the chosen Key Derivation Function -associated with the given key exchange ctx. -The length of the "kdf-outlen" parameter should not exceed that of a B. +See L. =item "kdf-ukm" (B) -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) - -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. Providers -usually do not need to support this gettable parameter as its sole purpose -is to support functionality of the deprecated EVP_PKEY_CTX_get0_ecdh_kdf_ukm() -function. +See L. =back diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod index f85f3cac50..e722c8ed26 100644 --- a/doc/man7/provider-keyexch.pod +++ b/doc/man7/provider-keyexch.pod @@ -170,16 +170,40 @@ as follows. =over 4 -=item "pad" (B) - -Sets the padding mode for the associated key exchange ctx. -Setting a value of 1 will turn padding on. -Setting a value of 0 will turn padding off. -If padding is off then the derived shared secret may be smaller than the largest -possible secret size. -If padding is on then the derived shared secret will have its first bytes filled -with 0s where necessary to make the shared secret the same size as the largest -possible secret size. +=item "kdf-type" (B) + +Sets or gets the Key Derivation Function type to apply within the associated key +exchange ctx. + +=item "kdf-digest" (B) + +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) + +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) + +Sets or gets the desired size for the output of the chosen Key Derivation Function +associated with the given key exchange ctx. +The length of the "kdf-outlen" parameter should not exceed that of a B. + +=item "kdf-ukm" (B) + +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) + +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. Providers +usually do not need to support this gettable parameter as its sole purpose +is to support functionality of the deprecated EVP_PKEY_CTX_get0_ecdh_kdf_ukm() +and EVP_PKEY_CTX_get0_dh_kdf_ukm() functions. =back -- cgit v1.2.3