Fix documentation of parameters for DH and ECDH KEX

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
(Merged from https://github.com/openssl/openssl/pull/17859)

diff --git a/doc/man7/EVP_KEYEXCH-DH.pod b/doc/man7/EVP_KEYEXCH-DH.pod
index 44811f1e37e7b8b9ac33e14c8ca964a9111dc207..566e02fc7543b54f311930def77b70085b3cb39d 100644 (file)
--- a/doc/man7/EVP_KEYEXCH-DH.pod
+++ b/doc/man7/EVP_KEYEXCH-DH.pod
@@ -15,20 +15,40 @@ Key exchange support for the B<DH> key type.
 
 =item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
 
+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<OSSL_KDF_NAME_X942KDF_ASN1>).
+
+=item "kdf-type" (B<OSSL_EXCHANGE_PARAM_KDF_TYPE>) <UTF8 string>
+
+See L<provider-keyexch(7)/Common Key Exchange parameters>.
+
+=item "kdf-digest" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST>) <UTF8 string>
+
+See L<provider-keyexch(7)/Common Key Exchange parameters>.
+
+=item "kdf-digest-props" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS>) <UTF8 string>
+
+See L<provider-keyexch(7)/Common Key Exchange parameters>.
+
+=item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <unsigned integer>
+
 See L<provider-keyexch(7)/Common Key Exchange parameters>.
 
 =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.
+See L<provider-keyexch(7)/Common Key Exchange parameters>.
 
-=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet string ptr>
+=item "cekalg" (B<OSSL_KDF_PARAM_CEK_ALG>) <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. 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<provider-kdf(7)/KDF Parameters>.
 
 =back
 

diff --git a/doc/man7/EVP_KEYEXCH-ECDH.pod b/doc/man7/EVP_KEYEXCH-ECDH.pod
index 69d0d87b3537d17a29d06e4a8d5984bd860d42ec..47ba2bd6031b7eddfdf34e26c93be0e7538bbfc8 100644 (file)
--- 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<OSSL_EXCHANGE_PARAM_KDF_TYPE>) <UTF8 string>
 
-Sets or gets the Key Derivation Function type to apply within the associated key
-exchange ctx.
+See L<provider-keyexch(7)/Common Key Exchange parameters>.
 
 =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.
+See L<provider-keyexch(7)/Common Key Exchange parameters>.
 
 =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.
+See L<provider-keyexch(7)/Common Key Exchange parameters>.
 
 =item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <unsigned integer>
 
-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<size_t>.
+See L<provider-keyexch(7)/Common Key Exchange parameters>.
 
 =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. 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<provider-keyexch(7)/Common Key Exchange parameters>.
 
 =back
 

diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod
index f85f3cac5081738ef35aa1fe06e05792feb1d0ee..e722c8ed26a24386f24355046accf6a36b8ccf81 100644 (file)
--- a/doc/man7/provider-keyexch.pod
+++ b/doc/man7/provider-keyexch.pod
@@ -170,16 +170,40 @@ as follows.
 
 =over 4
 
-=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
-
-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<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>) <unsigned integer>
+
+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<size_t>.
+
+=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. 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