mirror of
https://github.com/QuasarApp/openssl.git
synced 2025-05-01 04:04:39 +00:00
Make OSSL_PARAM descriptions uniformly formatted.
=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
parent
318e074e1f
commit
d56eba1fd1
@ -197,18 +197,18 @@ parameters are relevant to, or are understood by all ciphers:
|
||||
|
||||
=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.
|
||||
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 B<OSSL_CIPHER_PARAM_MODE> ("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 B<OSSL_CIPHER_PARAM_BLOCK_SIZE> ("blocksize") <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 B<OSSL_CIPHER_PARAM_FLAGS> ("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 B<OSSL_CIPHER_PARAM_KEYLEN> ("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 B<OSSL_CIPHER_PARAM_IVLEN> ("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 B<OSSL_CIPHER_PARAM_IV> ("iv") <octet string OR octet ptr>
|
||||
|
||||
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.
|
||||
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 B<OSSL_CIPHER_PARAM_AEAD_TAG> ("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 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.
|
||||
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
|
||||
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 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
|
||||
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!
|
||||
|
||||
@ -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 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.
|
||||
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
|
||||
cipher ctx. This is currently only supported by 3DES (which sets the key to
|
||||
|
||||
@ -164,15 +164,17 @@ by all digests:
|
||||
|
||||
=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 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 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:
|
||||
|
||||
@ -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 B<OSSL_DIGEST_PARAM_XOFLEN> ("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 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
|
||||
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 B<OSSL_DIGEST_PARAM_PAD_TYPE> ("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 B<OSSL_DIGEST_PARAM_MICALG> ("micalg") <UTF8 string>
|
||||
|
||||
Gets the digest Message Integrity Check algorithm string.
|
||||
This is used when creating S/MIME multipart/signed messages, as specified in
|
||||
|
||||
@ -139,7 +139,7 @@ algorithms:
|
||||
|
||||
=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.
|
||||
Setting a value of 1 will turn padding on.
|
||||
|
||||
@ -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 B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
|
||||
|
||||
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.
|
||||
|
||||
=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.
|
||||
|
||||
=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.
|
||||
|
||||
=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.
|
||||
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.
|
||||
|
||||
=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.
|
||||
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.
|
||||
This must be given together with the algorithm naming parameter to be
|
||||
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.
|
||||
|
||||
|
||||
@ -194,12 +194,12 @@ algorithms:
|
||||
|
||||
=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
|
||||
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
|
||||
signature functions.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user