mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-01-18 13:44:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

doc: update cipher documentation to include the new init functions with params

Browse Source 
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/14383)
This commit is contained in:
Pauli 2021-03-03 10:59:18 +10:00
parent 83da94ffa8
commit 1036bb64a7
1 changed files with 62 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
doc/man3/EVP_EncryptInit.pod
View File

@ -9,12 +9,15 @@ EVP_CIPHER_CTX_new,
EVP_CIPHER_CTX_reset, EVP_CIPHER_CTX_reset,
EVP_CIPHER_CTX_free, EVP_CIPHER_CTX_free,
EVP_EncryptInit_ex, EVP_EncryptInit_ex,
EVP_EncryptInit_ex2,
EVP_EncryptUpdate, EVP_EncryptUpdate,
EVP_EncryptFinal_ex, EVP_EncryptFinal_ex,
EVP_DecryptInit_ex, EVP_DecryptInit_ex,
EVP_DecryptInit_ex2,
EVP_DecryptUpdate, EVP_DecryptUpdate,
EVP_DecryptFinal_ex, EVP_DecryptFinal_ex,
EVP_CipherInit_ex, EVP_CipherInit_ex,
EVP_CipherInit_ex2,
EVP_CipherUpdate, EVP_CipherUpdate,
EVP_CipherFinal_ex, EVP_CipherFinal_ex,
EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_set_key_length,
@ -84,18 +87,27 @@ EVP_CIPHER_do_all_provided
int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
ENGINE *impl, const unsigned char *key, const unsigned char *iv); ENGINE *impl, const unsigned char *key, const unsigned char *iv);
int EVP_EncryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
const unsigned char *key, const unsigned char *iv,
const OSSL_PARAM params[]);
int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, const unsigned char *in, int inl); int *outl, const unsigned char *in, int inl);
int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
ENGINE *impl, const unsigned char *key, const unsigned char *iv); ENGINE *impl, const unsigned char *key, const unsigned char *iv);
int EVP_DecryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
const unsigned char *key, const unsigned char *iv,
const OSSL_PARAM params[]);
int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, const unsigned char *in, int inl); int *outl, const unsigned char *in, int inl);
int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc); ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc);
int EVP_CipherInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
const unsigned char *key, const unsigned char *iv,
int enc, const OSSL_PARAM params[]);
int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, const unsigned char *in, int inl); int *outl, const unsigned char *in, int inl);
int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
@ -196,6 +208,20 @@ itself. This function should be called after all operations using a
cipher are complete so sensitive information does not remain in cipher are complete so sensitive information does not remain in
memory. memory.
EVP_EncryptInit_ex2() sets up cipher context B<ctx> for encryption
with cipher B<type>. B<type> is typically supplied by a function such
as EVP_aes_256_cbc(), or a value explicitly fetched with
EVP_CIPHER_fetch(). B<key> is the symmetric key to use
and B<iv> is the IV to use (if necessary), the actual number of bytes
used for the key and IV depends on the cipher. The parameters B<params> will
be set on the context after initialisation. It is possible to set
all parameters to NULL except B<type> in an initial call and supply
the remaining parameters in subsequent calls, all of which have B<type>
set to NULL. This is done when the default cipher parameters are not
appropriate.
For EVP_CIPH_GCM_MODE the IV will be generated internally if it is not
specified.
EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
with cipher B<type>. B<type> is typically supplied by a function such with cipher B<type>. B<type> is typically supplied by a function such
as EVP_aes_256_cbc(), or a value explicitly fetched with as EVP_aes_256_cbc(), or a value explicitly fetched with
@ -239,20 +265,22 @@ If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more
data and it will return an error if any data remains in a partial block: data and it will return an error if any data remains in a partial block:
that is if the total data length is not a multiple of the block size. that is if the total data length is not a multiple of the block size.
EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the EVP_DecryptInit_ex2(), EVP_DecryptInit_ex(), EVP_DecryptUpdate()
corresponding decryption operations. EVP_DecryptFinal() will return an and EVP_DecryptFinal_ex() are the corresponding decryption
error code if padding is enabled and the final block is not correctly operations. EVP_DecryptFinal() will return an error code if padding is
formatted. The parameters and restrictions are identical to the encryption enabled and the final block is not correctly formatted. The parameters
operations except that if padding is enabled the decrypted data buffer B<out> and restrictions are identical to the encryption operations except
passed to EVP_DecryptUpdate() should have sufficient room for that if padding is enabled the decrypted data buffer B<out> passed
(B<inl> + cipher_block_size) bytes unless the cipher block size is 1 in to EVP_DecryptUpdate() should have sufficient room for (B<inl> +
which case B<inl> bytes is sufficient. cipher_block_size) bytes unless the cipher block size is 1 in which case
B<inl> bytes is sufficient.
EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are EVP_CipherInit_ex2(), EVP_CipherInit_ex(), EVP_CipherUpdate() and
functions that can be used for decryption or encryption. The operation EVP_CipherFinal_ex() are functions that can be used for decryption or
performed depends on the value of the B<enc> parameter. It should be set encryption. The operation performed depends on the value of the B<enc>
to 1 for encryption, 0 for decryption and -1 to leave the value unchanged parameter. It should be set to 1 for encryption, 0 for decryption and -1
(the actual value of 'enc' being supplied in a previous call). to leave the value unchanged (the actual value of 'enc' being supplied
in a previous call).
EVP_CIPHER_CTX_reset() clears all information from a cipher context EVP_CIPHER_CTX_reset() clears all information from a cipher context
and free up any allocated memory associate with it, except the B<ctx> and free up any allocated memory associate with it, except the B<ctx>
@ -290,8 +318,8 @@ IDENTIFIER.
EVP_CIPHER_CTX_set_padding() enables or disables padding. This EVP_CIPHER_CTX_set_padding() enables or disables padding. This
function should be called after the context is set up for encryption function should be called after the context is set up for encryption
or decryption with EVP_EncryptInit_ex(), EVP_DecryptInit_ex() or or decryption with EVP_EncryptInit_ex2(), EVP_DecryptInit_ex2() or
EVP_CipherInit_ex(). By default encryption operations are padded using EVP_CipherInit_ex2(). By default encryption operations are padded using
standard block padding and the padding is checked and removed when standard block padding and the padding is checked and removed when
decrypting. If the B<pad> parameter is zero then no padding is decrypting. If the B<pad> parameter is zero then no padding is
performed, the total amount of data encrypted or decrypted must then performed, the total amount of data encrypted or decrypted must then
@ -436,13 +464,13 @@ EVP_CIPHER_up_ref() returns 1 for success or 0 otherwise.
EVP_CIPHER_CTX_new() returns a pointer to a newly created EVP_CIPHER_CTX_new() returns a pointer to a newly created
B<EVP_CIPHER_CTX> for success and B<NULL> for failure. B<EVP_CIPHER_CTX> for success and B<NULL> for failure.
EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex() EVP_EncryptInit_ex2(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
return 1 for success and 0 for failure. return 1 for success and 0 for failure.
EVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0 for failure. EVP_DecryptInit_ex2() and EVP_DecryptUpdate() return 1 for success and 0 for failure.
EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success. EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success.
EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for failure. EVP_CipherInit_ex2() and EVP_CipherUpdate() return 1 for success and 0 for failure.
EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success. EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success.
EVP_Cipher() returns the amount of encrypted / decrypted bytes, or -1 EVP_Cipher() returns the amount of encrypted / decrypted bytes, or -1
@ -692,12 +720,14 @@ the input data earlier on will not produce a final decrypt error.
If padding is disabled then the decryption operation will always succeed if If padding is disabled then the decryption operation will always succeed if
the total amount of data decrypted is a multiple of the block size. the total amount of data decrypted is a multiple of the block size.
The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(), The functions EVP_EncryptInit(), EVP_EncryptInit_ex1(),
EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for EVP_EncryptFinal(), EVP_DecryptInit(), EVP_DecryptInit_ex1(),
compatibility with existing code. New code should use EVP_EncryptInit_ex(), EVP_CipherInit(), EVP_CipherInit_ex1() and EVP_CipherFinal() are obsolete
EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), but are retained for compatibility with existing code. New code should
EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an use EVP_EncryptInit_ex2(), EVP_EncryptFinal_ex(), EVP_DecryptInit_ex2(),
existing context without allocating and freeing it up on each call. EVP_DecryptFinal_ex(), EVP_CipherInit_ex2() and EVP_CipherFinal_ex()
because they can reuse an existing context without allocating and freeing
it up on each call.
There are some differences between functions EVP_CipherInit() and There are some differences between functions EVP_CipherInit() and
EVP_CipherInit_ex(), significant in some circumstances. EVP_CipherInit() fills EVP_CipherInit_ex(), significant in some circumstances. EVP_CipherInit() fills
@ -740,7 +770,7 @@ Encrypt a string using IDEA:
FILE *out; FILE *out;
ctx = EVP_CIPHER_CTX_new(); ctx = EVP_CIPHER_CTX_new();
EVP_EncryptInit_ex(ctx, EVP_idea_cbc(), NULL, key, iv); EVP_EncryptInit_ex2(ctx, EVP_idea_cbc(), key, iv, NULL);
if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) { if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) {
/* Error */ /* Error */
@ -798,13 +828,13 @@ with a 128-bit key:
/* Don't set key or IV right away; we want to check lengths */ /* Don't set key or IV right away; we want to check lengths */
ctx = EVP_CIPHER_CTX_new(); ctx = EVP_CIPHER_CTX_new();
EVP_CipherInit_ex(ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, EVP_CipherInit_ex2(ctx, EVP_aes_128_cbc(), NULL, NULL,
do_encrypt); do_encrypt, NULL);
OPENSSL_assert(EVP_CIPHER_CTX_key_length(ctx) == 16); OPENSSL_assert(EVP_CIPHER_CTX_key_length(ctx) == 16);
OPENSSL_assert(EVP_CIPHER_CTX_iv_length(ctx) == 16); OPENSSL_assert(EVP_CIPHER_CTX_iv_length(ctx) == 16);
/* Now we can set key and IV */ /* Now we can set key and IV */
EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt); EVP_CipherInit_ex2(ctx, NULL, key, iv, do_encrypt, NULL);
for (;;) { for (;;) {
inlen = fread(inbuf, 1, 1024, in); inlen = fread(inbuf, 1, 1024, in);
@ -849,8 +879,6 @@ Encryption using AES-CBC with a 256-bit key with "CS1" ciphertext stealing.
if (ctx == NULL || cipher == NULL) if (ctx == NULL || cipher == NULL)
goto err; goto err;
if (!EVP_CipherInit_ex(ctx, cipher, NULL, key, iv, encrypt))
goto err;
/* /*
* The default is "CS1" so this is not really needed, * The default is "CS1" so this is not really needed,
* but would be needed to set either "CS2" or "CS3". * but would be needed to set either "CS2" or "CS3".
@ -858,7 +886,8 @@ Encryption using AES-CBC with a 256-bit key with "CS1" ciphertext stealing.
params[0] = OSSL_PARAM_construct_utf8_string(OSSL_CIPHER_PARAM_CTS_MODE, params[0] = OSSL_PARAM_construct_utf8_string(OSSL_CIPHER_PARAM_CTS_MODE,
"CS1", 0); "CS1", 0);
params[1] = OSSL_PARAM_construct_end(); params[1] = OSSL_PARAM_construct_end();
if (!EVP_CIPHER_CTX_set_params(ctx, params))
if (!EVP_CipherInit_ex2(ctx, cipher, key, iv, encrypt, params))
goto err; goto err;
/* NOTE: CTS mode does not support multiple calls to EVP_CipherUpdate() */ /* NOTE: CTS mode does not support multiple calls to EVP_CipherUpdate() */
@ -903,7 +932,8 @@ EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup()
disappeared. EVP_CIPHER_CTX_init() remains as an alias for disappeared. EVP_CIPHER_CTX_init() remains as an alias for
EVP_CIPHER_CTX_reset(). EVP_CIPHER_CTX_reset().
The EVP_CIPHER_fetch(), EVP_CIPHER_free(), EVP_CIPHER_up_ref(), The EVP_EncryptInit_ex2(), EVP_DecryptInit_ex2(), EVP_CipherInit_ex2(),
EVP_CIPHER_fetch(), EVP_CIPHER_free(), EVP_CIPHER_up_ref(),
EVP_CIPHER_get_params(), EVP_CIPHER_CTX_set_params(), EVP_CIPHER_get_params(), EVP_CIPHER_CTX_set_params(),
EVP_CIPHER_CTX_get_params(), EVP_CIPHER_gettable_params(), EVP_CIPHER_CTX_get_params(), EVP_CIPHER_gettable_params(),
EVP_CIPHER_settable_ctx_params(), EVP_CIPHER_gettable_ctx_params(), EVP_CIPHER_settable_ctx_params(), EVP_CIPHER_gettable_ctx_params(),