diff options
author | Tomas Mraz <tomas@openssl.org> | 2022-03-10 13:13:40 +0100 |
---|---|---|
committer | Tomas Mraz <tomas@openssl.org> | 2022-03-14 10:07:05 +0100 |
commit | 76396ebbd7b67db90a31bb7b017eb2fcfb1c61c9 (patch) | |
tree | ffc75908301a82ff9a29786871d08063f7965c93 /doc | |
parent | 01b18775676115945956f4de0eb0cafedaf027ab (diff) |
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)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man7/EVP_KEYEXCH-DH.pod | 36 | ||||
-rw-r--r-- | doc/man7/EVP_KEYEXCH-ECDH.pod | 25 | ||||
-rw-r--r-- | doc/man7/provider-keyexch.pod | 44 |
3 files changed, 67 insertions, 38 deletions
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<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 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<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 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<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 |