The branch master has been updated via 0c452a51a5dfe061e5080ae484f1cd06772d8f47 (commit) via d56eba1fd109faa2c25fcb7cb2d9ee85e62b827f (commit) from 318e074e1f55c556d0ab4f9e3fbdca7c9b284847 (commit)
- Log ----------------------------------------------------------------- commit 0c452a51a5dfe061e5080ae484f1cd06772d8f47 Author: Pauli <paul.d...@oracle.com> Date: Tue Sep 10 18:05:57 2019 +1000 Reformat param description lines Reviewed-by: Richard Levitte <levi...@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10024) commit d56eba1fd109faa2c25fcb7cb2d9ee85e62b827f Author: Pauli <paul.d...@oracle.com> Date: Thu Sep 26 12:14:00 2019 +1000 Make OSSL_PARAM descriptions uniformly formatted. =item B<MACRO> ("name") <type> Reviewed-by: Richard Levitte <levi...@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10024) ----------------------------------------------------------------------- Summary of changes: doc/man3/EVP_DigestInit.pod | 6 +++--- doc/man3/EVP_KDF.pod | 18 +++++++++--------- doc/man3/EVP_MAC.pod | 20 ++++++++++---------- doc/man7/EVP_KDF-HKDF.pod | 12 ++++++------ doc/man7/EVP_KDF-PBKDF2.pod | 12 ++++++------ doc/man7/EVP_KDF-SCRYPT.pod | 10 +++++----- doc/man7/EVP_KDF-SS.pod | 14 +++++++------- doc/man7/EVP_KDF-SSHKDF.pod | 12 ++++++------ doc/man7/EVP_KDF-TLS1_PRF.pod | 8 ++++---- doc/man7/EVP_KDF-X942.pod | 10 +++++----- doc/man7/EVP_KDF-X963.pod | 8 ++++---- doc/man7/EVP_MAC-BLAKE2.pod | 8 ++++---- doc/man7/EVP_MAC-CMAC.pod | 8 ++++---- doc/man7/EVP_MAC-GMAC.pod | 10 +++++----- doc/man7/EVP_MAC-HMAC.pod | 10 +++++----- doc/man7/EVP_MAC-KMAC.pod | 8 ++++---- doc/man7/EVP_MAC-Poly1305.pod | 4 ++-- doc/man7/EVP_MAC-Siphash.pod | 4 ++-- doc/man7/provider-cipher.pod | 38 +++++++++++++++++++++++--------------- doc/man7/provider-digest.pod | 19 ++++++++++++------- doc/man7/provider-keyexch.pod | 2 +- doc/man7/provider-mac.pod | 20 ++++++++++---------- 22 files changed, 137 insertions(+), 124 deletions(-) diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index f4d3e58268..1e37160faa 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -347,13 +347,13 @@ EVP_MD_CTX_set_params() can be used with the following OSSL_PARAM keys: =over 4 -=item OSSL_PARAM_DIGEST_KEY_XOFLEN <unsigned integer> +=item "xoflen" (B<OSSL_PARAM_DIGEST_KEY_XOFLEN>) <unsigned integer> Sets the digest length for extendable output functions. It is used by the SHAKE algorithm and should not exceed what can be given using a B<size_t>. -=item OSSL_PARAM_DIGEST_KEY_PAD_TYPE <integer> +=item "pad_type" (B<OSSL_PARAM_DIGEST_KEY_PAD_TYPE>) <integer> Sets the pad type. It is used by the MDC2 algorithm. @@ -364,7 +364,7 @@ EVP_MD_CTX_get_params() can be used with the following OSSL_PARAM keys: =over 4 -=item OSSL_PARAM_DIGEST_KEY_MICALG <UTF8 string>. +=item "micalg" (B<OSSL_PARAM_DIGEST_KEY_MICALG>) <UTF8 string>. Gets the digest Message Integrity Check algorithm string. This is used when creating S/MIME multipart/signed messages, as specified in RFC 3851. diff --git a/doc/man3/EVP_KDF.pod b/doc/man3/EVP_KDF.pod index 9fa9a17d48..269733123b 100644 --- a/doc/man3/EVP_KDF.pod +++ b/doc/man3/EVP_KDF.pod @@ -144,19 +144,19 @@ The standard parameter names are: =over 4 -=item B<OSSL_KDF_PARAM_PASSWORD> ("pass") <octet string> +=item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string> Some KDF implementations require a password. For those KDF implementations that support it, this parameter sets the password. -=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string> +=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> Some KDF implementations can take a salt. For those KDF implementations that support it, this parameter sets the salt. The default value, if any, is implementation dependent. -=item B<OSSL_KDF_PARAM_ITER> ("iter") <unsigned integer> +=item "iter" (B<OSSL_KDF_PARAM_ITER>) <unsigned integer> Some KDF implementations require an iteration count. For those KDF implementations that support it, this parameter sets the @@ -164,11 +164,11 @@ iteration count. The default value, if any, is implementation dependent. -=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string> +=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> -=item B<OSSL_KDF_PARAM_MAC> ("mac") <UTF8 string> +=item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string> -=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string> +=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> For KDF implementations that use an underlying computation MAC or digest, these parameters set what the algorithm should be. @@ -179,13 +179,13 @@ or the properties. Note that not all algorithms may support all possible underlying implementations. -=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string> +=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> Some KDF implementations require a key. For those KDF implementations that support it, this octet string parameter sets the key. -=item B<OSSL_KDF_PARAM_MAC_SIZE> ("maclen") <unsigned integer> +=item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer> Used by implementations that use a MAC with a variable output size (KMAC). For those KDF implementations that support it, this parameter @@ -194,7 +194,7 @@ sets the MAC output size. The default value, if any, is implementation dependent. The length must never exceed what can be given with a B<size_t>. -=item B<OSSL_KDF_PARAM_SCRYPT_MAXMEM> ("macmaxmem_byteslen") <unsigned integer> +=item "maxmem_bytes" (B<OSSL_KDF_PARAM_SCRYPT_MAXMEM>) <unsigned integer> Memory-hard password-based KDF algorithms, such as scrypt, use an amount of memory that depends on the load factors provided as input. diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod index a995d391c4..b4d5b5bdd8 100644 --- a/doc/man3/EVP_MAC.pod +++ b/doc/man3/EVP_MAC.pod @@ -183,43 +183,43 @@ The standard parameter names are: =over 4 -=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string> +=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string> Its value is the MAC key as an array of bytes. For MACs that use an underlying computation algorithm, the algorithm must be set first, see parameter names "algorithm" below. -=item B<OSSL_MAC_PARAM_IV> ("iv") <octet string> +=item "iv" (B<OSSL_MAC_PARAM_IV>) <octet string> Some MAC implementations require an IV, this parameter sets the IV. -=item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string> +=item "custom" (B<OSSL_MAC_PARAM_CUSTOM>) <octet string> Some MAC implementations (KMAC, BLAKE2) accept a Customization String, this parameter sets the Customization String. The default value is the empty string. -=item B<OSSL_MAC_PARAM_SALT> ("salt") <octet string> +=item "salt" (B<OSSL_MAC_PARAM_SALT>) <octet string> This option is used by BLAKE2 MAC. -=item B<OSSL_MAC_PARAM_XOF> ("xof") <integer> +=item "xof" (B<OSSL_MAC_PARAM_XOF>) <integer> It's a simple flag, the value 0 or 1 are expected. This option is used by KMAC. -=item B<OSSL_MAC_PARAM_FLAGS> ("flags") <integer> +=item "flags" (B<OSSL_MAC_PARAM_FLAGS>) <integer> These will set the MAC flags to the given numbers. Some MACs do not support this option. -=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <UTF8 string> +=item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string> -=item B<OSSL_MAC_PARAM_DIGEST> ("digest") <UTF8 string> +=item "digest" (B<OSSL_MAC_PARAM_DIGEST>) <UTF8 string> -=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <UTF8 string> +=item "cipher" (B<OSSL_MAC_PARAM_CIPHER>) <UTF8 string> For MAC implementations that use an underlying computation cipher or digest, these parameters set what the algorithm should be. @@ -231,7 +231,7 @@ Note that not all algorithms may support all digests. HMAC does not support variable output length digests such as SHAKE128 or SHAKE256. -=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer> +=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer> For MAC implementations that support it, set the output size that EVP_MAC_final() should produce. diff --git a/doc/man7/EVP_KDF-HKDF.pod b/doc/man7/EVP_KDF-HKDF.pod index d68f384034..4da887c007 100644 --- a/doc/man7/EVP_KDF-HKDF.pod +++ b/doc/man7/EVP_KDF-HKDF.pod @@ -26,23 +26,23 @@ The supported parameters are: =over 4 -=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string> +=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> -=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string> +=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> -=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string> +=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> -=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string> +=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. -=item B<OSSL_KDF_PARAM_INFO> ("info") <octet string> +=item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string> This parameter sets the info value. The length of the context info buffer cannot exceed 1024 bytes; this should be more than enough for any normal use of HKDF. -=item B<OSSL_KDF_PARAM_MODE> ("mode") <UTF8 string> or <integer> +=item "mode" (B<OSSL_KDF_PARAM_MODE>) <UTF8 string> or <integer> This parameter sets the mode for the HKDF operation. There are three modes that are currently defined: diff --git a/doc/man7/EVP_KDF-PBKDF2.pod b/doc/man7/EVP_KDF-PBKDF2.pod index d93dff68cc..e18816b544 100644 --- a/doc/man7/EVP_KDF-PBKDF2.pod +++ b/doc/man7/EVP_KDF-PBKDF2.pod @@ -24,21 +24,21 @@ The supported parameters are: =over 4 -=item B<OSSL_KDF_PARAM_PASSWORD> ("pass") <octet string> +=item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string> -=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string> +=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> -=item B<OSSL_KDF_PARAM_ITER> ("iter") <unsigned integer> +=item "iter" (B<OSSL_KDF_PARAM_ITER>) <unsigned integer> This parameter has a default value of 2048. -=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string> +=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> -=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string> +=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. -=item B<OSSL_KDF_PARAM_PKCS5> ("pkcs5") <integer> +=item "pkcs5" (B<OSSL_KDF_PARAM_PKCS5>) <integer> This parameter can be used to enable or disable SP800-132 compliance checks. Setting the mode to 0 enables the compliance checks. diff --git a/doc/man7/EVP_KDF-SCRYPT.pod b/doc/man7/EVP_KDF-SCRYPT.pod index 1372f6d677..940629cb4b 100644 --- a/doc/man7/EVP_KDF-SCRYPT.pod +++ b/doc/man7/EVP_KDF-SCRYPT.pod @@ -43,17 +43,17 @@ The supported parameters are: =over 4 -=item B<OSSL_KDF_PARAM_PASSWORD> ("pass") <octet string> +=item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string> -=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string> +=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. -=item B<OSSL_KDF_PARAM_SCRYPT_N> ("n") <unsigned integer> +=item "n" (B<OSSL_KDF_PARAM_SCRYPT_N>) <unsigned integer> -=item B<OSSL_KDF_PARAM_SCRYPT_R> ("r") <unsigned integer> +=item "r" (B<OSSL_KDF_PARAM_SCRYPT_R>) <unsigned integer> -=item B<OSSL_KDF_PARAM_SCRYPT_P> ("p") <unsigned integer> +=item "p" (B<OSSL_KDF_PARAM_SCRYPT_P>) <unsigned integer> These parameters configure the scrypt work factors N, r and p. N is a parameter of type B<uint64_t>. diff --git a/doc/man7/EVP_KDF-SS.pod b/doc/man7/EVP_KDF-SS.pod index 0ccfe2ed28..fcf423bb45 100644 --- a/doc/man7/EVP_KDF-SS.pod +++ b/doc/man7/EVP_KDF-SS.pod @@ -39,23 +39,23 @@ The supported parameters are: =over 4 -=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string> +=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> -=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string> +=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> -=item B<OSSL_KDF_PARAM_MAC> ("mac") <UTF8 string> +=item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string> -=item B<OSSL_KDF_PARAM_MAC_SIZE> ("maclen") <unsigned integer> +=item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer> -=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string> +=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. -=item B<EVP_KDF_CTRL_SET_KEY> ("key") <octet string> +=item "key" (B<EVP_KDF_CTRL_SET_KEY>) <octet string> This parameter set the shared secret that is used for key derivation. -=item B<OSSL_KDF_PARAM_INFO> ("info") <octet string> +=item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string> This parameter sets an optional value for fixedinfo, also known as otherinfo. diff --git a/doc/man7/EVP_KDF-SSHKDF.pod b/doc/man7/EVP_KDF-SSHKDF.pod index e1350e951b..bcf3ff5f69 100644 --- a/doc/man7/EVP_KDF-SSHKDF.pod +++ b/doc/man7/EVP_KDF-SSHKDF.pod @@ -26,22 +26,22 @@ The supported parameters are: =over 4 -=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string> +=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> -=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string> +=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> -=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string> +=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. -=item B<OSSL_KDF_PARAM_SSHKDF_XCGHASH> ("xcghash") <octet string> +=item "xcghash" (B<OSSL_KDF_PARAM_SSHKDF_XCGHASH>) <octet string> -=item B<OSSL_KDF_PARAM_SSHKDF_SESSION_ID> ("session_id") <octet string> +=item "session_id" (B<OSSL_KDF_PARAM_SSHKDF_SESSION_ID>) <octet string> These parameters set the respective values for the KDF. If a value is already set, the contents are replaced. -=item B<OSSL_KDF_PARAM_SSHKDF_TYPE> ("type") <integer> +=item "type" (B<OSSL_KDF_PARAM_SSHKDF_TYPE>) <integer> This parameter sets the type for the SSHHKDF operation. There are six supported types: diff --git a/doc/man7/EVP_KDF-TLS1_PRF.pod b/doc/man7/EVP_KDF-TLS1_PRF.pod index 58625a769a..0089e07599 100644 --- a/doc/man7/EVP_KDF-TLS1_PRF.pod +++ b/doc/man7/EVP_KDF-TLS1_PRF.pod @@ -22,9 +22,9 @@ The supported parameters are: =over 4 -=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string> +=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> -=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string> +=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. @@ -33,12 +33,12 @@ associated with the TLS PRF. EVP_md5_sha1() is treated as a special case which uses the PRF algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1. -=item B<OSSL_KDF_PARAM_SECRET> ("secret") <octet string> +=item "secret" (B<OSSL_KDF_PARAM_SECRET>) <octet string> This parameter sets the secret value of the TLS PRF. Any existing secret value is replaced. -=item B<OSSL_KDF_PARAM_SEED> ("seed") <octet string> +=item "seed" (B<OSSL_KDF_PARAM_SEED>) <octet string> This parameter sets the context seed. The length of the context seed cannot exceed 1024 bytes; diff --git a/doc/man7/EVP_KDF-X942.pod b/doc/man7/EVP_KDF-X942.pod index 06cafc30ac..1a4ab8131a 100644 --- a/doc/man7/EVP_KDF-X942.pod +++ b/doc/man7/EVP_KDF-X942.pod @@ -22,23 +22,23 @@ The supported parameters are: =over 4 -=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string> +=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> -=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string> +=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. -=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string> +=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> The shared secret used for key derivation. This parameter sets the secret. -=item B<OSSL_KDF_PARAM_UKM> ("ukm") <octet string> +=item "ukm" (B<OSSL_KDF_PARAM_UKM>) <octet string> This parameter is an optional random string that is provided by the sender called "partyAInfo". In CMS this is the user keying material. -=item B<OSSL_KDF_PARAM_CEK_ALG> ("cekalg") <UTF8 string> +=item "cekalg" (B<OSSL_KDF_PARAM_CEK_ALG>) <UTF8 string> This parameter sets the CEK wrapping algorithm name. diff --git a/doc/man7/EVP_KDF-X963.pod b/doc/man7/EVP_KDF-X963.pod index 36dc2bab1c..62a5378938 100644 --- a/doc/man7/EVP_KDF-X963.pod +++ b/doc/man7/EVP_KDF-X963.pod @@ -21,18 +21,18 @@ The supported parameters are: =over 4 -=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string> +=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> -=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string> +=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. -=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string> +=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> The shared secret used for key derivation. This parameter sets the secret. -=item B<OSSL_KDF_PARAM_INFO> ("info") <octet string> +=item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string> This parameter specifies an optional value for shared info. diff --git a/doc/man7/EVP_MAC-BLAKE2.pod b/doc/man7/EVP_MAC-BLAKE2.pod index 15df9ce0cf..99b20bdc76 100644 --- a/doc/man7/EVP_MAC-BLAKE2.pod +++ b/doc/man7/EVP_MAC-BLAKE2.pod @@ -34,24 +34,24 @@ The length of the "size" parameter should not exceed that of a B<size_t>. =over 4 -=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string> +=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string> This may be at most 64 bytes for BLAKE2BMAC or 32 for BLAKE2SMAC and at least 1 byte in both cases. -=item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string> +=item "custom" (B<OSSL_MAC_PARAM_CUSTOM>) <octet string> This is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for BLAKE2SMAC. It is empty by default. -=item B<OSSL_MAC_PARAM_SALT> ("salt") <octet string> +=item "salt" (B<OSSL_MAC_PARAM_SALT>) <octet string> This is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for BLAKE2SMAC. It is empty by default. -=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer> +=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer> When set, this can be any number between between 1 and 32 for EVP_MAC_BLAKE2S or 64 for EVP_MAC_BLAKE2B. diff --git a/doc/man7/EVP_MAC-CMAC.pod b/doc/man7/EVP_MAC-CMAC.pod index 75950617db..af6face8a7 100644 --- a/doc/man7/EVP_MAC-CMAC.pod +++ b/doc/man7/EVP_MAC-CMAC.pod @@ -28,11 +28,11 @@ The following parameter can be set with EVP_MAC_CTX_set_params(): =over 4 -=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string> +=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string> -=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <UTF8 string> +=item "cipher" (B<OSSL_MAC_PARAM_CIPHER>) <UTF8 string> -=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <UTF8 string> +=item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string> =back @@ -41,7 +41,7 @@ EVP_MAC_CTX_get_params(): =over 4 -=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer> +=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer> =back diff --git a/doc/man7/EVP_MAC-GMAC.pod b/doc/man7/EVP_MAC-GMAC.pod index 114322b97c..dbc5fb2570 100644 --- a/doc/man7/EVP_MAC-GMAC.pod +++ b/doc/man7/EVP_MAC-GMAC.pod @@ -28,13 +28,13 @@ The following parameter can be set with EVP_MAC_CTX_set_params(): =over 4 -=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string> +=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string> -=item B<OSSL_MAC_PARAM_IV> ("iv") <octet string> +=item "iv" (B<OSSL_MAC_PARAM_IV>) <octet string> -=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <UTF8 string> +=item "cipher" (B<OSSL_MAC_PARAM_CIPHER>) <UTF8 string> -=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <UTF8 string> +=item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string> =back @@ -43,7 +43,7 @@ EVP_MAC_CTX_get_params(): =over 4 -=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer> +=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer> =back diff --git a/doc/man7/EVP_MAC-HMAC.pod b/doc/man7/EVP_MAC-HMAC.pod index 1b983b2339..cc6c993b7b 100644 --- a/doc/man7/EVP_MAC-HMAC.pod +++ b/doc/man7/EVP_MAC-HMAC.pod @@ -28,13 +28,13 @@ The following parameter can be set with EVP_MAC_CTX_set_params(): =over 4 -=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string> +=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string> -=item B<OSSL_MAC_PARAM_FLAGS> ("flags") <octet string> +=item "flags" (B<OSSL_MAC_PARAM_FLAGS>) <octet string> -=item B<OSSL_MAC_PARAM_DIGEST> ("digest") <UTF8 string> +=item "digest" (B<OSSL_MAC_PARAM_DIGEST>) <UTF8 string> -=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <UTF8 string> +=item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string> =back @@ -45,7 +45,7 @@ EVP_MAC_CTX_get_params(): =over 4 -=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer> +=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer> =back diff --git a/doc/man7/EVP_MAC-KMAC.pod b/doc/man7/EVP_MAC-KMAC.pod index 0aec63100b..ac94f6b5f7 100644 --- a/doc/man7/EVP_MAC-KMAC.pod +++ b/doc/man7/EVP_MAC-KMAC.pod @@ -34,13 +34,13 @@ The length of the "size" parameter should not exceed that of a B<size_t>. =over 4 -=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string> +=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string> -=item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string> +=item "custom" (B<OSSL_MAC_PARAM_CUSTOM>) <octet string> -=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer> +=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer> -=item B<OSSL_MAC_PARAM_XOF> +=item "xof" (B<OSSL_MAC_PARAM_XOF>) <integer> =back diff --git a/doc/man7/EVP_MAC-Poly1305.pod b/doc/man7/EVP_MAC-Poly1305.pod index 6e3bf02b3c..1a998e8ac1 100644 --- a/doc/man7/EVP_MAC-Poly1305.pod +++ b/doc/man7/EVP_MAC-Poly1305.pod @@ -28,7 +28,7 @@ The following parameter can be set with EVP_MAC_CTX_set_params(): =over 4 -=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string> +=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string> =back @@ -37,7 +37,7 @@ EVP_MAC_CTX_get_params(): =over 4 -=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer> +=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer> =back diff --git a/doc/man7/EVP_MAC-Siphash.pod b/doc/man7/EVP_MAC-Siphash.pod index 7738cc0017..40eba8d498 100644 --- a/doc/man7/EVP_MAC-Siphash.pod +++ b/doc/man7/EVP_MAC-Siphash.pod @@ -32,9 +32,9 @@ The length of the "size" parameter should not exceed that of a B<size_t>. =over 4 -=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string> +=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string> -=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer> +=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer> =back diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod index d5d2f13390..89cf07be0c 100644 --- a/doc/man7/provider-cipher.pod +++ b/doc/man7/provider-cipher.pod @@ -197,18 +197,18 @@ parameters are relevant to, or are understood by all ciphers: =over 4 -=item B<OSSL_CIPHER_PARAM_PADDING> (uint) +=item "padding" (B<OSSL_CIPHER_PARAM_PADDING>) <unsigned integer> Sets the padding mode for the associated cipher ctx. Setting a value of 1 will turn padding on. Setting a value of 0 will turn padding off. -=item B<OSSL_CIPHER_PARAM_MODE> (uint) +=item "mode" (B<OSSL_CIPHER_PARAM_MODE>) <unsigned integer> Gets the mode for the associated cipher algorithm. See L<EVP_CIPHER_mode(3)> for a list of valid modes. -=item B<OSSL_CIPHER_PARAM_BLOCK_SIZE> (size_t) +=item "blocksize" (B<OSSL_CIPHER_PARAM_BLOCK_SIZE>) <unsigned integer> Gets the block size for the associated cipher algorithm. The block size should be 1 for stream ciphers. @@ -216,44 +216,50 @@ Note that the block size for a cipher may be different to the block size for the underlying encryption/decryption primitive. For example AES in CTR mode has a block size of 1 (because it operates like a stream cipher), even though AES has a block size of 16. +The length of the "blocksize" parameter should not exceed that of a B<size_t>. -=item B<OSSL_CIPHER_PARAM_FLAGS> (ulong) +=item "flags" (B<OSSL_CIPHER_PARAM_FLAGS>) <unsigned integer> Gets any flags for the associated cipher algorithm. See L<EVP_CIPHER_meth_set_flags(3)> for a list of currently defined cipher flags. +The length of the "flags" parameter should equal that of an +B<unsigned long int>. -=item B<OSSL_CIPHER_PARAM_KEYLEN> (size_t) +=item "keylen" (B<OSSL_CIPHER_PARAM_KEYLEN>) <unsigned integer> Gets the key length for the associated cipher algorithm. This can also be used to get or set the key length for the associated cipher ctx. +The length of the "keylen" parameter should not exceed that of a B<size_t>. -=item B<OSSL_CIPHER_PARAM_IVLEN> (size_t) +=item "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN>) <unsigned integer> Gets the IV length for the associated cipher algorithm. +The length of the "ivlen" parameter should not exceed that of a B<size_t>. -=item B<OSSL_CIPHER_PARAM_IV> (octet_string OR octet_ptr) +=item "iv" (B<OSSL_CIPHER_PARAM_IV>) <octet string OR octet ptr> Gets the IV for the associated cipher ctx. -=item B<OSSL_CIPHER_PARAM_NUM> (uint) +=item "num" (B<OSSL_CIPHER_PARAM_NUM>) <unsigned integer> Gets or sets the cipher specific "num" parameter for the associated cipher ctx. Built-in ciphers typically use this to track how much of the current underlying block has been "used" already. -=item B<OSSL_CIPHER_PARAM_AEAD_TAG> (octet_string) +=item "tag" (B<OSSL_CIPHER_PARAM_AEAD_TAG>) <octet string> Gets or sets the AEAD tag for the associated cipher ctx. See L<EVP_EncryptInit(3)/AEAD Interface>. -=item B<OSSL_CIPHER_PARAM_AEAD_TAGLEN> (size_t) +=item "taglen" (B<OSSL_CIPHER_PARAM_AEAD_TAGLEN>) <unsigned integer> Gets the tag length to be used for an AEAD cipher for the associated cipher ctx. It returns a default value if it has not been set. +The length of the "taglen" parameter should not exceed that of a B<size_t>. -=item B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD> (octet_string) +=item "tlsaad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD>) <octet string> =for comment TODO(3.0): Consider changing this interface so that all ciphers use the standard AEAD interface - rather than having this special purpose @@ -263,12 +269,13 @@ Sets TLSv1.2 AAD information for the associated cipher ctx. TLSv1.2 AAD information is always 13 bytes in length and is as defined for the "additional_data" field described in section 6.2.3.3 of RFC5246. -=item B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD> (size_t) +=item "tlsaadpad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD>) <unsigned integer> Gets the length of the tag that will be added to a TLS record for the AEAD tag for the associated cipher ctx. +The length of the "tlsaadpad" parameter should not exceed that of a B<size_t>. -=item B<OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED> (octet_string) +=item "tlsivfixed" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED>) <octet string> =for comment TODO(3.0): This interface needs completely redesigning! @@ -303,11 +310,12 @@ Whether encrypting or decrypting the value written to B<*outl> in the OP_cipher_cipher call should be the length of the payload excluding the explicit IV length and the tag length. -=item B<OSSL_CIPHER_PARAM_AEAD_IVLEN> (size_t) +=item "ivlen" (B<OSSL_CIPHER_PARAM_AEAD_IVLEN>) <unsigned integer> Sets the IV length to be used for an AEAD cipher for the associated cipher ctx. +The length of the "ivlen" parameter should not exceed that of a B<size_t>. -=item B<OSSL_CIPHER_PARAM_RANDOM_KEY> (octet_string) +=item "randkey" (B<OSSL_CIPHER_PARAM_RANDOM_KEY>) <octet string> Gets a implementation specific randomly generated key for the associated cipher ctx. This is currently only supported by 3DES (which sets the key to diff --git a/doc/man7/provider-digest.pod b/doc/man7/provider-digest.pod index 83989dcf8b..ff388da100 100644 --- a/doc/man7/provider-digest.pod +++ b/doc/man7/provider-digest.pod @@ -164,15 +164,17 @@ by all digests: =over 4 -=item B<OSSL_DIGEST_PARAM_BLOCK_SIZE> (size_t) +=item "blocksize" (B<OSSL_DIGEST_PARAM_BLOCK_SIZE>) <unsigned integer> The digest block size. +The length of the "blocksize" parameter should not exceed that of a B<size_t>. -=item B<OSSL_DIGEST_PARAM_SIZE> (size_t) +=item "size" (B<OSSL_DIGEST_PARAM_SIZE>) <unsigned integer> The digest output size. +The length of the "size" parameter should not exceed that of a B<size_t>. -=item B<OSSL_DIGEST_PARAM_FLAGS> (unsigned long) +=item "flags" (B<OSSL_DIGEST_PARAM_FLAGS>) <unsigned integer> Diverse flags that describe exceptional behaviour for the digest: @@ -208,6 +210,9 @@ Currently unused. =back +The length of the "flags" parameter should equal that of an +B<unsigned long int>. + =back =head2 Digest Context Parameters @@ -227,12 +232,12 @@ parameters are relevant to, or are understood by all digests: =over 4 -=item B<OSSL_DIGEST_PARAM_XOFLEN> (unsigned integer) +=item "xoflen" (B<OSSL_DIGEST_PARAM_XOFLEN>) <unsigned integer> Sets the digest length for extendable output functions. The length of the "xoflen" parameter should not exceed that of a B<size_t>. -=item B<OSSL_DIGEST_PARAM_SSL3_MS> (octet string) +=item "ssl3-ms" (B<OSSL_DIGEST_PARAM_SSL3_MS>) <octet string> This parameter is set by libssl in order to calculate a signature hash for an SSLv3 CertificateVerify message as per RFC6101. @@ -244,7 +249,7 @@ section 5.6.8. The next call after setting this parameter will be OP_digest_final(). This is only relevant for implementations of SHA1 or MD5_SHA1. -=item B<OSSL_DIGEST_PARAM_PAD_TYPE> (unsigned integer) +=item "pad_type" (B<OSSL_DIGEST_PARAM_PAD_TYPE>) <unsigned integer> Sets the pad type to be used. The only built-in digest that uses this is MDC2. @@ -252,7 +257,7 @@ Normally the final MDC2 block is padded with 0s. If the pad type is set to 2 then the final block is padded with 0x80 followed by 0s. -=item B<OSSL_DIGEST_PARAM_MICALG> (UTF8 string) +=item "micalg" (B<OSSL_DIGEST_PARAM_MICALG>) <UTF8 string> Gets the digest Message Integrity Check algorithm string. This is used when creating S/MIME multipart/signed messages, as specified in diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod index 9ef294395c..358e16a0df 100644 --- a/doc/man7/provider-keyexch.pod +++ b/doc/man7/provider-keyexch.pod @@ -139,7 +139,7 @@ algorithms: =over 4 -=item B<OSSL_EXCHANGE_PARAM_PAD> (uint) +=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. diff --git a/doc/man7/provider-mac.pod b/doc/man7/provider-mac.pod index f9d6e35329..70653e37f3 100644 --- a/doc/man7/provider-mac.pod +++ b/doc/man7/provider-mac.pod @@ -151,47 +151,47 @@ parameters are relevant to, or are understood by all macs: =over 4 -=item B<OSSL_MAC_PARAM_KEY> (octet string) +=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string> Sets the key in the associated MAC ctx. -=item B<OSSL_MAC_PARAM_IV> (octet string) +=item "iv" (B<OSSL_MAC_PARAM_IV>) <octet string> Sets the IV of the underlying cipher, when applicable. -=item B<OSSL_MAC_PARAM_CUSTOM> (UTF8 string) +=item "custom" (B<OSSL_MAC_PARAM_CUSTOM>) <UTF8 string> Sets the custom string in the associated MAC ctx. -=item B<OSSL_MAC_PARAM_SALT> (octet string) +=item "salt" (B<OSSL_MAC_PARAM_SALT>) <octet string> Sets the salt of the underlying cipher, when applicable. -=item B<OSSL_MAC_PARAM_BLOCK_XOF> (integer) +=item "xof" (B<OSSL_MAC_PARAM_BLOCK_XOF>) <integer> Sets XOF mode in the associated MAC ctx. 0 means no XOF mode, 1 means XOF mode. -=item B<OSSL_MAC_PARAM_FLAGS> (integer) +=item "flags" (B<OSSL_MAC_PARAM_FLAGS>) <integer> Gets flags associated with the MAC. =for comment We need to investigate if this is the right approach -=item B<OSSL_MAC_PARAM_CIPHER> (UTF8 string) +=item "cipher" (B<OSSL_MAC_PARAM_CIPHER>) <UTF8 string> -=item B<OSSL_MAC_PARAM_DIGEST> (UTF8 string) +=item "digest" (B<OSSL_MAC_PARAM_DIGEST>) <UTF8 string> Sets the name of the underlying cipher or digest to be used. It must name a suitable algorithm for the MAC that's being used. -=item B<OSSL_MAC_PARAM_PROPERTIES> (UTF8 string) +=item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string> Sets the properties to be queried when trying to fetch the underlying algorithm. This must be given together with the algorithm naming parameter to be considered valid. -=item B<OSSL_MAC_PARAM_SIZE> (integer) +=item "size" (B<OSSL_MAC_PARAM_SIZE>) <integer> Can be used to get the resulting MAC size.