From: Pauli Date: Tue, 10 Sep 2019 08:05:57 +0000 (+1000) Subject: Reformat param description lines X-Git-Tag: openssl-3.0.0-alpha1~1269 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=0c452a51a5dfe061e5080ae484f1cd06772d8f47;p=oweals%2Fopenssl.git Reformat param description lines Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/10024) --- 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 +=item "xoflen" (B) 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. -=item OSSL_PARAM_DIGEST_KEY_PAD_TYPE +=item "pad_type" (B) 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 . +=item "micalg" (B) . 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 ("pass") +=item "pass" (B) Some KDF implementations require a password. For those KDF implementations that support it, this parameter sets the password. -=item B ("salt") +=item "salt" (B) 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 ("iter") +=item "iter" (B) 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 ("properties") +=item "properties" (B) -=item B ("mac") +=item "mac" (B) -=item B ("digest") +=item "digest" (B) 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 ("key") +=item "key" (B) Some KDF implementations require a key. For those KDF implementations that support it, this octet string parameter sets the key. -=item B ("maclen") +=item "maclen" (B) 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. -=item B ("macmaxmem_byteslen") +=item "maxmem_bytes" (B) 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 ("key") +=item "key" (B) 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 ("iv") +=item "iv" (B) Some MAC implementations require an IV, this parameter sets the IV. -=item B ("custom") +=item "custom" (B) Some MAC implementations (KMAC, BLAKE2) accept a Customization String, this parameter sets the Customization String. The default value is the empty string. -=item B ("salt") +=item "salt" (B) This option is used by BLAKE2 MAC. -=item B ("xof") +=item "xof" (B) It's a simple flag, the value 0 or 1 are expected. This option is used by KMAC. -=item B ("flags") +=item "flags" (B) These will set the MAC flags to the given numbers. Some MACs do not support this option. -=item B ("properties") +=item "properties" (B) -=item B ("digest") +=item "digest" (B) -=item B ("cipher") +=item "cipher" (B) 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 ("size") +=item "size" (B) 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 ("properties") +=item "properties" (B) -=item B ("digest") +=item "digest" (B) -=item B ("key") +=item "key" (B) -=item B ("salt") +=item "salt" (B) These parameters work as described in L. -=item B ("info") +=item "info" (B) 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 ("mode") or +=item "mode" (B) or 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 ("pass") +=item "pass" (B) -=item B ("salt") +=item "salt" (B) -=item B ("iter") +=item "iter" (B) This parameter has a default value of 2048. -=item B ("properties") +=item "properties" (B) -=item B ("digest") +=item "digest" (B) These parameters work as described in L. -=item B ("pkcs5") +=item "pkcs5" (B) 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 ("pass") +=item "pass" (B) -=item B ("salt") +=item "salt" (B) These parameters work as described in L. -=item B ("n") +=item "n" (B) -=item B ("r") +=item "r" (B) -=item B ("p") +=item "p" (B) These parameters configure the scrypt work factors N, r and p. N is a parameter of type B. 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 ("properties") +=item "properties" (B) -=item B ("digest") +=item "digest" (B) -=item B ("mac") +=item "mac" (B) -=item B ("maclen") +=item "maclen" (B) -=item B ("salt") +=item "salt" (B) These parameters work as described in L. -=item B ("key") +=item "key" (B) This parameter set the shared secret that is used for key derivation. -=item B ("info") +=item "info" (B) 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 ("properties") +=item "properties" (B) -=item B ("digest") +=item "digest" (B) -=item B ("key") +=item "key" (B) These parameters work as described in L. -=item B ("xcghash") +=item "xcghash" (B) -=item B ("session_id") +=item "session_id" (B) These parameters set the respective values for the KDF. If a value is already set, the contents are replaced. -=item B ("type") +=item "type" (B) 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 ("properties") +=item "properties" (B) -=item B ("digest") +=item "digest" (B) These parameters work as described in L. @@ -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 and B as used in TLS 1.0 and 1.1. -=item B ("secret") +=item "secret" (B) This parameter sets the secret value of the TLS PRF. Any existing secret value is replaced. -=item B ("seed") +=item "seed" (B) 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 ("properties") +=item "properties" (B) -=item B ("digest") +=item "digest" (B) These parameters work as described in L. -=item B ("key") +=item "key" (B) The shared secret used for key derivation. This parameter sets the secret. -=item B ("ukm") +=item "ukm" (B) 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 ("cekalg") +=item "cekalg" (B) 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 ("properties") +=item "properties" (B) -=item B ("digest") +=item "digest" (B) These parameters work as described in L. -=item B ("key") +=item "key" (B) The shared secret used for key derivation. This parameter sets the secret. -=item B ("info") +=item "info" (B) 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. =over 4 -=item B ("key") +=item "key" (B) This may be at most 64 bytes for BLAKE2BMAC or 32 for BLAKE2SMAC and at least 1 byte in both cases. -=item B ("custom") +=item "custom" (B) This is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for BLAKE2SMAC. It is empty by default. -=item B ("salt") +=item "salt" (B) This is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for BLAKE2SMAC. It is empty by default. -=item B ("size") +=item "size" (B) 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 ("key") +=item "key" (B) -=item B ("cipher") +=item "cipher" (B) -=item B ("properties") +=item "properties" (B) =back @@ -41,7 +41,7 @@ EVP_MAC_CTX_get_params(): =over 4 -=item B ("size") +=item "size" (B) =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 ("key") +=item "key" (B) -=item B ("iv") +=item "iv" (B) -=item B ("cipher") +=item "cipher" (B) -=item B ("properties") +=item "properties" (B) =back @@ -43,7 +43,7 @@ EVP_MAC_CTX_get_params(): =over 4 -=item B ("size") +=item "size" (B) =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 ("key") +=item "key" (B) -=item B ("flags") +=item "flags" (B) -=item B ("digest") +=item "digest" (B) -=item B ("properties") +=item "properties" (B) =back @@ -45,7 +45,7 @@ EVP_MAC_CTX_get_params(): =over 4 -=item B ("size") +=item "size" (B) =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. =over 4 -=item B ("key") +=item "key" (B) -=item B ("custom") +=item "custom" (B) -=item B ("size") +=item "size" (B) -=item B +=item "xof" (B) =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 ("key") +=item "key" (B) =back @@ -37,7 +37,7 @@ EVP_MAC_CTX_get_params(): =over 4 -=item B ("size") +=item "size" (B) =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. =over 4 -=item B ("key") +=item "key" (B) -=item B ("size") +=item "size" (B) =back diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod index 4753c326a0..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 ("padding") +=item "padding" (B) 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 ("mode") +=item "mode" (B) Gets the mode for the associated cipher algorithm. See L for a list of valid modes. -=item B ("blocksize") +=item "blocksize" (B) Gets the block size for the associated cipher algorithm. The block size should be 1 for stream ciphers. @@ -218,7 +218,7 @@ 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. -=item B ("flags") +=item "flags" (B) Gets any flags for the associated cipher algorithm. See L for a list of currently defined cipher @@ -226,40 +226,40 @@ flags. The length of the "flags" parameter should equal that of an B. -=item B ("keylen") +=item "keylen" (B) 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. -=item B ("ivlen") +=item "ivlen" (B) Gets the IV length for the associated cipher algorithm. The length of the "ivlen" parameter should not exceed that of a B. -=item B ("iv") +=item "iv" (B) Gets the IV for the associated cipher ctx. -=item B ("num") +=item "num" (B) 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 ("tag") +=item "tag" (B) Gets or sets the AEAD tag for the associated cipher ctx. See L. -=item B ("taglen") +=item "taglen" (B) 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. -=item B ("tlsaad") +=item "tlsaad" (B) =for comment TODO(3.0): Consider changing this interface so that all ciphers use the standard AEAD interface - rather than having this special purpose @@ -269,13 +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 ("tlsaadpad") +=item "tlsaadpad" (B) 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. -=item B ("tlsivfixed") +=item "tlsivfixed" (B) =for comment TODO(3.0): This interface needs completely redesigning! @@ -310,12 +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 ("ivlen") +=item "ivlen" (B) 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. -=item B ("randkey") +=item "randkey" (B) 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 4dfa2ee31c..ff388da100 100644 --- a/doc/man7/provider-digest.pod +++ b/doc/man7/provider-digest.pod @@ -164,17 +164,17 @@ by all digests: =over 4 -=item B ("blocksize") +=item "blocksize" (B) The digest block size. The length of the "blocksize" parameter should not exceed that of a B. -=item B ("size") +=item "size" (B) The digest output size. The length of the "size" parameter should not exceed that of a B. -=item B ("flags") +=item "flags" (B) Diverse flags that describe exceptional behaviour for the digest: @@ -232,12 +232,12 @@ parameters are relevant to, or are understood by all digests: =over 4 -=item B ("xoflen") +=item "xoflen" (B) Sets the digest length for extendable output functions. The length of the "xoflen" parameter should not exceed that of a B. -=item B ("ssl3-ms") +=item "ssl3-ms" (B) This parameter is set by libssl in order to calculate a signature hash for an SSLv3 CertificateVerify message as per RFC6101. @@ -249,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 ("pad_type") +=item "pad_type" (B) Sets the pad type to be used. The only built-in digest that uses this is MDC2. @@ -257,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 ("micalg") +=item "micalg" (B) 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 0935155a3d..358e16a0df 100644 --- a/doc/man7/provider-keyexch.pod +++ b/doc/man7/provider-keyexch.pod @@ -139,7 +139,7 @@ algorithms: =over 4 -=item B ("pad") +=item "pad" (B) 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 fc179740fc..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 ("key") +=item "key" (B) Sets the key in the associated MAC ctx. -=item B ("iv") +=item "iv" (B) Sets the IV of the underlying cipher, when applicable. -=item B ("custom") +=item "custom" (B) Sets the custom string in the associated MAC ctx. -=item B ("salt") +=item "salt" (B) Sets the salt of the underlying cipher, when applicable. -=item B ("xof") +=item "xof" (B) Sets XOF mode in the associated MAC ctx. 0 means no XOF mode, 1 means XOF mode. -=item B ("flags") +=item "flags" (B) Gets flags associated with the MAC. =for comment We need to investigate if this is the right approach -=item B ("cipher") +=item "cipher" (B) -=item B ("digest") +=item "digest" (B) 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 ("properties") +=item "properties" (B) 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 ("size") +=item "size" (B) Can be used to get the resulting MAC size. diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod index 81b6feb0a2..777b991cc6 100644 --- a/doc/man7/provider-signature.pod +++ b/doc/man7/provider-signature.pod @@ -194,12 +194,12 @@ algorithms: =over 4 -=item B ("digest") +=item "digest" (B) Get or sets the name of the digest algorithm used for the input to the signature functions. -=item B ("digest-size") +=item "digest-size" (B) Gets or sets the output size of the digest algorithm used for the input to the signature functions.