QuasarApp/openssl
4
0
Fork 0
mirror of https://github.com/QuasarApp/openssl.git synced 2025-05-02 20:49:39 +00:00
Code Issues Projects Releases Wiki Activity

Make OSSL_PARAM descriptions uniformly formatted.

Browse Source 
=item B<MACRO> ("name") <type>

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10024)
This commit is contained in:
Pauli 2019-09-26 12:14:00 +10:00
parent 318e074e1f
commit d56eba1fd1
5 changed files with 48 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
doc/man7/provider-cipher.pod
View File

@ -197,18 +197,18 @@ parameters are relevant to, or are understood by all ciphers:
=over 4 =over 4
=item B<OSSL_CIPHER_PARAM_PADDING> (uint) =item B<OSSL_CIPHER_PARAM_PADDING> ("padding") <unsigned integer>
Sets the padding mode for the associated cipher ctx. Sets the padding mode for the associated cipher ctx.
Setting a value of 1 will turn padding on. Setting a value of 1 will turn padding on.
Setting a value of 0 will turn padding off. Setting a value of 0 will turn padding off.
=item B<OSSL_CIPHER_PARAM_MODE> (uint) =item B<OSSL_CIPHER_PARAM_MODE> ("mode") <unsigned integer>
Gets the mode for the associated cipher algorithm. Gets the mode for the associated cipher algorithm.
See L<EVP_CIPHER_mode(3)> for a list of valid modes. See L<EVP_CIPHER_mode(3)> for a list of valid modes.
=item B<OSSL_CIPHER_PARAM_BLOCK_SIZE> (size_t) =item B<OSSL_CIPHER_PARAM_BLOCK_SIZE> ("blocksize") <unsigned integer>
Gets the block size for the associated cipher algorithm. Gets the block size for the associated cipher algorithm.
The block size should be 1 for stream ciphers. 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. the underlying encryption/decryption primitive.
For example AES in CTR mode has a block size of 1 (because it operates like a 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. 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 B<OSSL_CIPHER_PARAM_FLAGS> ("flags") <unsigned integer>
Gets any flags for the associated cipher algorithm. Gets any flags for the associated cipher algorithm.
See L<EVP_CIPHER_meth_set_flags(3)> for a list of currently defined cipher See L<EVP_CIPHER_meth_set_flags(3)> for a list of currently defined cipher
flags. 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 B<OSSL_CIPHER_PARAM_KEYLEN> ("keylen") <unsigned integer>
Gets the key length for the associated cipher algorithm. 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 This can also be used to get or set the key length for the associated cipher
ctx. 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 B<OSSL_CIPHER_PARAM_IVLEN> ("ivlen") <unsigned integer>
Gets the IV length for the associated cipher algorithm. 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 B<OSSL_CIPHER_PARAM_IV> ("iv") <octet string OR octet ptr>
Gets the IV for the associated cipher ctx. Gets the IV for the associated cipher ctx.
=item B<OSSL_CIPHER_PARAM_NUM> (uint) =item B<OSSL_CIPHER_PARAM_NUM> ("num") <unsigned integer>
Gets or sets the cipher specific "num" parameter for the associated cipher ctx. 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 Built-in ciphers typically use this to track how much of the current underlying
block has been "used" already. block has been "used" already.
=item B<OSSL_CIPHER_PARAM_AEAD_TAG> (octet_string) =item B<OSSL_CIPHER_PARAM_AEAD_TAG> ("tag") <octet string>
Gets or sets the AEAD tag for the associated cipher ctx. Gets or sets the AEAD tag for the associated cipher ctx.
See L<EVP_EncryptInit(3)/AEAD Interface>. See L<EVP_EncryptInit(3)/AEAD Interface>.
=item B<OSSL_CIPHER_PARAM_AEAD_TAGLEN> (size_t) =item B<OSSL_CIPHER_PARAM_AEAD_TAGLEN> ("taglen") <unsigned integer>
Gets the tag length to be used for an AEAD cipher for the associated cipher ctx. 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. 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 B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD> ("tlsaad") <octet string>
=for comment TODO(3.0): Consider changing this interface so that all ciphers =for comment TODO(3.0): Consider changing this interface so that all ciphers
use the standard AEAD interface - rather than having this special purpose 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 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. "additional_data" field described in section 6.2.3.3 of RFC5246.
=item B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD> (size_t) =item B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD> ("tlsaadpad") <unsigned integer>
Gets the length of the tag that will be added to a TLS record for the AEAD Gets the length of the tag that will be added to a TLS record for the AEAD
tag for the associated cipher ctx. 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 B<OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED> ("tlsivfixed") <octet string>
=for comment TODO(3.0): This interface needs completely redesigning! =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 OP_cipher_cipher call should be the length of the payload excluding the explicit
IV length and the tag length. IV length and the tag length.
=item B<OSSL_CIPHER_PARAM_AEAD_IVLEN> (size_t) =item B<OSSL_CIPHER_PARAM_AEAD_IVLEN> ("ivlen") <unsigned integer>
Sets the IV length to be used for an AEAD cipher for the associated cipher ctx. 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 B<OSSL_CIPHER_PARAM_RANDOM_KEY> ("randkey") <octet string>
Gets a implementation specific randomly generated key for the associated Gets a implementation specific randomly generated key for the associated
cipher ctx. This is currently only supported by 3DES (which sets the key to cipher ctx. This is currently only supported by 3DES (which sets the key to

19
doc/man7/provider-digest.pod
View File

@ -164,15 +164,17 @@ by all digests:
=over 4 =over 4
=item B<OSSL_DIGEST_PARAM_BLOCK_SIZE> (size_t) =item B<OSSL_DIGEST_PARAM_BLOCK_SIZE> ("blocksize") <unsigned integer>
The digest block size. 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 B<OSSL_DIGEST_PARAM_SIZE> ("size") <unsigned integer>
The digest output size. 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 B<OSSL_DIGEST_PARAM_FLAGS> ("flags") <unsigned integer>
Diverse flags that describe exceptional behaviour for the digest: Diverse flags that describe exceptional behaviour for the digest:
@ -208,6 +210,9 @@ Currently unused.
=back =back
The length of the "flags" parameter should equal that of an
B<unsigned long int>.
=back =back
=head2 Digest Context Parameters =head2 Digest Context Parameters
@ -227,12 +232,12 @@ parameters are relevant to, or are understood by all digests:
=over 4 =over 4
=item B<OSSL_DIGEST_PARAM_XOFLEN> (unsigned integer) =item B<OSSL_DIGEST_PARAM_XOFLEN> ("xoflen") <unsigned integer>
Sets the digest length for extendable output functions. Sets the digest length for extendable output functions.
The length of the "xoflen" parameter should not exceed that of a B<size_t>. 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 B<OSSL_DIGEST_PARAM_SSL3_MS> ("ssl3-ms") <octet string>
This parameter is set by libssl in order to calculate a signature hash for an This parameter is set by libssl in order to calculate a signature hash for an
SSLv3 CertificateVerify message as per RFC6101. 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(). The next call after setting this parameter will be OP_digest_final().
This is only relevant for implementations of SHA1 or MD5_SHA1. This is only relevant for implementations of SHA1 or MD5_SHA1.
=item B<OSSL_DIGEST_PARAM_PAD_TYPE> (unsigned integer) =item B<OSSL_DIGEST_PARAM_PAD_TYPE> ("pad_type") <unsigned integer>
Sets the pad type to be used. Sets the pad type to be used.
The only built-in digest that uses this is MDC2. 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 If the pad type is set to 2 then the final block is padded with 0x80 followed by
0s. 0s.
=item B<OSSL_DIGEST_PARAM_MICALG> (UTF8 string) =item B<OSSL_DIGEST_PARAM_MICALG> ("micalg") <UTF8 string>
Gets the digest Message Integrity Check algorithm string. Gets the digest Message Integrity Check algorithm string.
This is used when creating S/MIME multipart/signed messages, as specified in This is used when creating S/MIME multipart/signed messages, as specified in

2
doc/man7/provider-keyexch.pod
View File

@ -139,7 +139,7 @@ algorithms:
=over 4 =over 4
=item B<OSSL_EXCHANGE_PARAM_PAD> (uint) =item B<OSSL_EXCHANGE_PARAM_PAD> ("pad") <unsigned integer>
Sets the padding mode for the associated key exchange ctx. Sets the padding mode for the associated key exchange ctx.
Setting a value of 1 will turn padding on. Setting a value of 1 will turn padding on.

20
doc/man7/provider-mac.pod
View File

@ -151,47 +151,47 @@ parameters are relevant to, or are understood by all macs:
=over 4 =over 4
=item B<OSSL_MAC_PARAM_KEY> (octet string) =item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
Sets the key in the associated MAC ctx. Sets the key in the associated MAC ctx.
=item B<OSSL_MAC_PARAM_IV> (octet string) =item B<OSSL_MAC_PARAM_IV> ("iv") <octet string>
Sets the IV of the underlying cipher, when applicable. Sets the IV of the underlying cipher, when applicable.
=item B<OSSL_MAC_PARAM_CUSTOM> (UTF8 string) =item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <UTF8 string>
Sets the custom string in the associated MAC ctx. Sets the custom string in the associated MAC ctx.
=item B<OSSL_MAC_PARAM_SALT> (octet string) =item B<OSSL_MAC_PARAM_SALT> ("salt") <octet string>
Sets the salt of the underlying cipher, when applicable. Sets the salt of the underlying cipher, when applicable.
=item B<OSSL_MAC_PARAM_BLOCK_XOF> (integer) =item B<OSSL_MAC_PARAM_BLOCK_XOF> ("xof") <integer>
Sets XOF mode in the associated MAC ctx. Sets XOF mode in the associated MAC ctx.
0 means no XOF mode, 1 means XOF mode. 0 means no XOF mode, 1 means XOF mode.
=item B<OSSL_MAC_PARAM_FLAGS> (integer) =item B<OSSL_MAC_PARAM_FLAGS> ("flags") <integer>
Gets flags associated with the MAC. Gets flags associated with the MAC.
=for comment We need to investigate if this is the right approach =for comment We need to investigate if this is the right approach
=item B<OSSL_MAC_PARAM_CIPHER> (UTF8 string) =item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <UTF8 string>
=item B<OSSL_MAC_PARAM_DIGEST> (UTF8 string) =item B<OSSL_MAC_PARAM_DIGEST> ("digest") <UTF8 string>
Sets the name of the underlying cipher or digest to be used. 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. It must name a suitable algorithm for the MAC that's being used.
=item B<OSSL_MAC_PARAM_PROPERTIES> (UTF8 string) =item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <UTF8 string>
Sets the properties to be queried when trying to fetch the underlying algorithm. 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 This must be given together with the algorithm naming parameter to be
considered valid. considered valid.
=item B<OSSL_MAC_PARAM_SIZE> (integer) =item B<OSSL_MAC_PARAM_SIZE> ("size") <integer>
Can be used to get the resulting MAC size. Can be used to get the resulting MAC size.

4
doc/man7/provider-signature.pod
View File

@ -194,12 +194,12 @@ algorithms:
=over 4 =over 4
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string> =item B<OSSL_SIGNATURE_PARAM_DIGEST> ("digest") <UTF8 string>
Get or sets the name of the digest algorithm used for the input to the signature Get or sets the name of the digest algorithm used for the input to the signature
functions. functions.
=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer> =item B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE> ("digest-size") <unsigned integer>
Gets or sets the output size of the digest algorithm used for the input to the Gets or sets the output size of the digest algorithm used for the input to the
signature functions. signature functions.