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_free,
EVP_EncryptInit_ex,
EVP_EncryptInit_ex2,
EVP_EncryptUpdate,
EVP_EncryptFinal_ex,
EVP_DecryptInit_ex,
EVP_DecryptInit_ex2,
EVP_DecryptUpdate,
EVP_DecryptFinal_ex,
EVP_CipherInit_ex,
EVP_CipherInit_ex2,
EVP_CipherUpdate,
EVP_CipherFinal_ex,
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,
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 *outl, const unsigned char *in, int inl);
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,
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 *outl, const unsigned char *in, int inl);
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,
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 *outl, const unsigned char *in, int inl);
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
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
with cipher B<type>. B<type> is typically supplied by a function such
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:
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
corresponding decryption operations. EVP_DecryptFinal() will return an
error code if padding is enabled and the final block is not correctly
formatted. The parameters and restrictions are identical to the encryption
operations except that if padding is enabled the decrypted data buffer B<out>
passed to EVP_DecryptUpdate() should have sufficient room for
(B<inl> + cipher_block_size) bytes unless the cipher block size is 1 in
which case B<inl> bytes is sufficient.
EVP_DecryptInit_ex2(), EVP_DecryptInit_ex(), EVP_DecryptUpdate()
and EVP_DecryptFinal_ex() are the corresponding decryption
operations. EVP_DecryptFinal() will return an error code if padding is
enabled and the final block is not correctly formatted. The parameters
and restrictions are identical to the encryption operations except
that if padding is enabled the decrypted data buffer B<out> passed
to EVP_DecryptUpdate() should have sufficient room for (B<inl> +
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
functions that can be used for decryption or encryption. The operation
performed depends on the value of the B<enc> parameter. It should be set
to 1 for encryption, 0 for decryption and -1 to leave the value unchanged
(the actual value of 'enc' being supplied in a previous call).
EVP_CipherInit_ex2(), EVP_CipherInit_ex(), EVP_CipherUpdate() and
EVP_CipherFinal_ex() are functions that can be used for decryption or
encryption. The operation performed depends on the value of the B<enc>
parameter. It should be set to 1 for encryption, 0 for decryption and -1
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
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
function should be called after the context is set up for encryption
or decryption with EVP_EncryptInit_ex(), EVP_DecryptInit_ex() or
EVP_CipherInit_ex(). By default encryption operations are padded using
or decryption with EVP_EncryptInit_ex2(), EVP_DecryptInit_ex2() or
EVP_CipherInit_ex2(). By default encryption operations are padded using
standard block padding and the padding is checked and removed when
decrypting. If the B<pad> parameter is zero then no padding is
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
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.
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_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_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
the total amount of data decrypted is a multiple of the block size.
The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(),
EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for
compatibility with existing code. New code should use EVP_EncryptInit_ex(),
EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(),
EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an
existing context without allocating and freeing it up on each call.
The functions EVP_EncryptInit(), EVP_EncryptInit_ex1(),
EVP_EncryptFinal(), EVP_DecryptInit(), EVP_DecryptInit_ex1(),
EVP_CipherInit(), EVP_CipherInit_ex1() and EVP_CipherFinal() are obsolete
but are retained for compatibility with existing code. New code should
use EVP_EncryptInit_ex2(), EVP_EncryptFinal_ex(), EVP_DecryptInit_ex2(),
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
EVP_CipherInit_ex(), significant in some circumstances. EVP_CipherInit() fills
@ -740,7 +770,7 @@ Encrypt a string using IDEA:
FILE *out;
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))) {
/* Error */
@ -798,13 +828,13 @@ with a 128-bit key:
/* Don't set key or IV right away; we want to check lengths */
ctx = EVP_CIPHER_CTX_new();
EVP_CipherInit_ex(ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
do_encrypt);
EVP_CipherInit_ex2(ctx, EVP_aes_128_cbc(), NULL, NULL,
do_encrypt, NULL);
OPENSSL_assert(EVP_CIPHER_CTX_key_length(ctx) == 16);
OPENSSL_assert(EVP_CIPHER_CTX_iv_length(ctx) == 16);
/* 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 (;;) {
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)
goto err;
if (!EVP_CipherInit_ex(ctx, cipher, NULL, key, iv, encrypt))
goto err;
/*
* The default is "CS1" so this is not really needed,
* 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,
"CS1", 0);
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;
/* 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
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_CTX_get_params(), EVP_CIPHER_gettable_params(),
EVP_CIPHER_settable_ctx_params(), EVP_CIPHER_gettable_ctx_params(),