From: Pauli Date: Thu, 26 Sep 2019 02:14:00 +0000 (+1000) Subject: Make OSSL_PARAM descriptions uniformly formatted. X-Git-Tag: openssl-3.0.0-alpha1~1270 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=d56eba1fd109faa2c25fcb7cb2d9ee85e62b827f;p=oweals%2Fopenssl.git Make OSSL_PARAM descriptions uniformly formatted. =item B ("name") Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/10024) --- diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod index d5d2f13390..4753c326a0 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 (uint) +=item B ("padding") 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 (uint) +=item B ("mode") Gets the mode for the associated cipher algorithm. See L for a list of valid modes. -=item B (size_t) +=item B ("blocksize") 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. -=item B (ulong) +=item B ("flags") Gets any flags for the associated cipher algorithm. See L for a list of currently defined cipher flags. +The length of the "flags" parameter should equal that of an +B. -=item B (size_t) +=item B ("keylen") 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 (size_t) +=item B ("ivlen") Gets the IV length for the associated cipher algorithm. +The length of the "ivlen" parameter should not exceed that of a B. -=item B (octet_string OR octet_ptr) +=item B ("iv") Gets the IV for the associated cipher ctx. -=item B (uint) +=item B ("num") 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 (octet_string) +=item B ("tag") Gets or sets the AEAD tag for the associated cipher ctx. See L. -=item B (size_t) +=item B ("taglen") 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 (octet_string) +=item B ("tlsaad") =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 (size_t) +=item B ("tlsaadpad") 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 (octet_string) +=item B ("tlsivfixed") =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 (size_t) +=item B ("ivlen") 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 (octet_string) +=item B ("randkey") 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..4dfa2ee31c 100644 --- a/doc/man7/provider-digest.pod +++ b/doc/man7/provider-digest.pod @@ -164,15 +164,17 @@ by all digests: =over 4 -=item B (size_t) +=item B ("blocksize") The digest block size. +The length of the "blocksize" parameter should not exceed that of a B. -=item B (size_t) +=item B ("size") The digest output size. +The length of the "size" parameter should not exceed that of a B. -=item B (unsigned long) +=item B ("flags") 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. + =back =head2 Digest Context Parameters @@ -227,12 +232,12 @@ parameters are relevant to, or are understood by all digests: =over 4 -=item B (unsigned integer) +=item B ("xoflen") Sets the digest length for extendable output functions. The length of the "xoflen" parameter should not exceed that of a B. -=item B (octet string) +=item B ("ssl3-ms") 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 (unsigned integer) +=item B ("pad_type") 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 (UTF8 string) +=item B ("micalg") 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..0935155a3d 100644 --- a/doc/man7/provider-keyexch.pod +++ b/doc/man7/provider-keyexch.pod @@ -139,7 +139,7 @@ algorithms: =over 4 -=item B (uint) +=item B ("pad") 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..fc179740fc 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 (octet string) +=item B ("key") Sets the key in the associated MAC ctx. -=item B (octet string) +=item B ("iv") Sets the IV of the underlying cipher, when applicable. -=item B (UTF8 string) +=item B ("custom") Sets the custom string in the associated MAC ctx. -=item B (octet string) +=item B ("salt") Sets the salt of the underlying cipher, when applicable. -=item B (integer) +=item B ("xof") Sets XOF mode in the associated MAC ctx. 0 means no XOF mode, 1 means XOF mode. -=item B (integer) +=item B ("flags") Gets flags associated with the MAC. =for comment We need to investigate if this is the right approach -=item B (UTF8 string) +=item B ("cipher") -=item B (UTF8 string) +=item B ("digest") 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 (UTF8 string) +=item B ("properties") 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 (integer) +=item B ("size") Can be used to get the resulting MAC size. diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod index 777b991cc6..81b6feb0a2 100644 --- a/doc/man7/provider-signature.pod +++ b/doc/man7/provider-signature.pod @@ -194,12 +194,12 @@ algorithms: =over 4 -=item "digest" (B) +=item B ("digest") Get or sets the name of the digest algorithm used for the input to the signature functions. -=item "digest-size" (B) +=item B ("digest-size") Gets or sets the output size of the digest algorithm used for the input to the signature functions.