--- name: "libressl-EVP_EncryptInit" section: "3" platform: "linux" package: "libressl" version: "4.4.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/libressl-EVP_EncryptInit" --- # libressl-EVP\_EncryptInit(3) EVP cipher routines ## NAME **EVP\_CIPHER\_CTX\_new**, **EVP\_CIPHER\_CTX\_reset**, **EVP\_CIPHER\_CTX\_free**, **EVP\_CIPHER\_CTX\_copy**, **EVP\_EncryptInit\_ex**, **EVP\_EncryptUpdate**, **EVP\_EncryptFinal\_ex**, **EVP\_DecryptInit\_ex**, **EVP\_DecryptUpdate**, **EVP\_DecryptFinal\_ex**, **EVP\_CipherInit\_ex**, **EVP\_CipherUpdate**, **EVP\_CipherFinal\_ex**, **EVP\_EncryptInit**, **EVP\_EncryptFinal**, **EVP\_DecryptInit**, **EVP\_DecryptFinal**, **EVP\_CipherInit**, **EVP\_CipherFinal**, **EVP\_CIPHER\_CTX\_encrypting**, **EVP\_get\_cipherbyname**, **EVP\_get\_cipherbynid**, **EVP\_get\_cipherbyobj**, **EVP\_CIPHER\_CTX\_cipher**, **EVP\_enc\_null**, **EVP\_idea\_cbc**, **EVP\_idea\_ecb**, **EVP\_idea\_cfb64**, **EVP\_idea\_cfb**, **EVP\_idea\_ofb**, **EVP\_bf\_cbc**, **EVP\_bf\_ecb**, **EVP\_bf\_cfb64**, **EVP\_bf\_cfb**, **EVP\_bf\_ofb**, **EVP\_cast5\_cbc**, **EVP\_cast5\_ecb**, **EVP\_cast5\_cfb64**, **EVP\_cast5\_cfb**, **EVP\_cast5\_ofb** – EVP cipher routines ## SYNOPSIS Crypto Library (libcrypto, -lcrypto) **#include \** *EVP\_CIPHER\_CTX* *\**\ **EVP\_CIPHER\_CTX\_new**(*void*); *int*\ **EVP\_CIPHER\_CTX\_reset**(*EVP\_CIPHER\_CTX \*ctx*); *void*\ **EVP\_CIPHER\_CTX\_free**(*EVP\_CIPHER\_CTX \*ctx*); *int*\ **EVP\_CIPHER\_CTX\_copy**(*EVP\_CIPHER\_CTX \*out*, *const EVP\_CIPHER\_CTX \*in*); *int*\ **EVP\_EncryptInit\_ex**(*EVP\_CIPHER\_CTX \*ctx*, *const EVP\_CIPHER \*type*, *ENGINE \*engine*, *const unsigned char \*key*, *const unsigned char \*iv*); *int*\ **EVP\_EncryptUpdate**(*EVP\_CIPHER\_CTX \*ctx*, *unsigned char \*out*, *int \*out\_len*, *const unsigned char \*in*, *int in\_len*); *int*\ **EVP\_EncryptFinal\_ex**(*EVP\_CIPHER\_CTX \*ctx*, *unsigned char \*out*, *int \*out\_len*); *int*\ **EVP\_DecryptInit\_ex**(*EVP\_CIPHER\_CTX \*ctx*, *const EVP\_CIPHER \*type*, *ENGINE \*engine*, *const unsigned char \*key*, *const unsigned char \*iv*); *int*\ **EVP\_DecryptUpdate**(*EVP\_CIPHER\_CTX \*ctx*, *unsigned char \*out*, *int \*out\_len*, *const unsigned char \*in*, *int in\_len*); *int*\ **EVP\_DecryptFinal\_ex**(*EVP\_CIPHER\_CTX \*ctx*, *unsigned char \*out*, *int \*out\_len*); *int*\ **EVP\_CipherInit\_ex**(*EVP\_CIPHER\_CTX \*ctx*, *const EVP\_CIPHER \*type*, *ENGINE \*engine*, *const unsigned char \*key*, *const unsigned char \*iv*, *int enc*); *int*\ **EVP\_CipherUpdate**(*EVP\_CIPHER\_CTX \*ctx*, *unsigned char \*out*, *int \*out\_len*, *const unsigned char \*in*, *int in\_len*); *int*\ **EVP\_CipherFinal\_ex**(*EVP\_CIPHER\_CTX \*ctx*, *unsigned char \*out*, *int \*out\_len*); *int*\ **EVP\_EncryptInit**(*EVP\_CIPHER\_CTX \*ctx*, *const EVP\_CIPHER \*type*, *const unsigned char \*key*, *const unsigned char \*iv*); *int*\ **EVP\_EncryptFinal**(*EVP\_CIPHER\_CTX \*ctx*, *unsigned char \*out*, *int \*out\_len*); *int*\ **EVP\_DecryptInit**(*EVP\_CIPHER\_CTX \*ctx*, *const EVP\_CIPHER \*type*, *const unsigned char \*key*, *const unsigned char \*iv*); *int*\ **EVP\_DecryptFinal**(*EVP\_CIPHER\_CTX \*ctx*, *unsigned char \*out*, *int \*out\_len*); *int*\ **EVP\_CipherInit**(*EVP\_CIPHER\_CTX \*ctx*, *const EVP\_CIPHER \*type*, *const unsigned char \*key*, *const unsigned char \*iv*, *int enc*); *int*\ **EVP\_CipherFinal**(*EVP\_CIPHER\_CTX \*ctx*, *unsigned char \*out*, *int \*out\_len*); *int*\ **EVP\_CIPHER\_CTX\_encrypting**(*const EVP\_CIPHER\_CTX \*ctx*); *const* *EVP\_CIPHER* *\**\ **EVP\_get\_cipherbyname**(*const char \*name*); *const* *EVP\_CIPHER* *\**\ **EVP\_get\_cipherbynid**(*int nid*); *const* *EVP\_CIPHER* *\**\ **EVP\_get\_cipherbyobj**(*const ASN1\_OBJECT \*a*); *const* *EVP\_CIPHER* *\**\ **EVP\_CIPHER\_CTX\_cipher**(*const EVP\_CIPHER\_CTX \*ctx*); ## DESCRIPTION The EVP cipher routines are a high level interface to certain symmetric ciphers. **EVP\_CIPHER\_CTX\_new**() creates a new, empty cipher context. **EVP\_CIPHER\_CTX\_reset**() clears all information from *ctx* and frees all allocated memory associated with it, except the *ctx* object itself, such that it can be reused for another series of calls to **EVP\_CipherInit**(), **EVP\_CipherUpdate**(), and **EVP\_CipherFinal**(). **EVP\_CIPHER\_CTX\_free**() clears all information from *ctx* and frees all allocated memory associated with it, including *ctx* itself. This function should be called after all operations using a cipher are complete, so sensitive information does not remain in memory. If *ctx* is a NULL pointer, no action occurs. **EVP\_CIPHER\_CTX\_copy**() calls **EVP\_CIPHER\_CTX\_reset**() on *out* and copies all the data from *in* to *out*, except that the *EVP\_CIPHER* object used by *in* and any application specific data set with EVP\_CIPHER\_CTX\_set\_app\_data(3) are not copied and *out* will point to the same two objects. The algorithm- and implementation-specific cipher data described in EVP\_CIPHER\_CTX\_get\_cipher\_data(3) is copied with [malloc(3)](/malloc/3.md) and [memcpy(3)](/memcpy/3.md), i.e. assuming that it does not contain pointers to any sub-objects. If the bit EVP\_CIPH\_CUSTOM\_COPY has been set with EVP\_CIPHER\_meth\_set\_flags(3), EVP\_CIPHER\_CTX\_ctrl(3) is called at the end with arguments *in*, EVP\_CTRL\_COPY, 0, and *out* such that the cipher implementation can perform further algorithm- and implementation-specific initializations after the algorithm- and implementation-specific cipher data has been copied. Among the cipher algorithms built into the library, EVP\_CIPH\_CUSTOM\_COPY and EVP\_CTRL\_COPY are used by some of the ciphers documented in the EVP\_aes\_256\_gcm(3) manual page. **EVP\_EncryptInit**() and **EVP\_EncryptInit\_ex**() set up the cipher context *ctx* for encryption with cipher *type*. *type* is normally supplied by a function such as EVP\_aes\_256\_cbc(3). *key* is the symmetric key to use and *iv* is the IV to use (if necessary). The actual number of bytes used for the key and IV depends on the cipher. The *ENGINE*, *\*engine* argument is always ignored and passing NULL is recommended. It is possible to set all parameters to NULL except *type* in an initial call and supply the remaining parameters in subsequent calls, all of which have *type* set to NULL. This is done when the default cipher parameters are not appropriate. **EVP\_EncryptUpdate**() encrypts *in\_len* bytes from the buffer *in* and writes the encrypted version to *out*. This function can be called multiple times to encrypt successive blocks of data. The amount of data written depends on the block alignment of the encrypted data: as a result the amount of data written may be anything from zero bytes to (*in\_len* + cipher\_block\_size - 1) so *out* should contain sufficient room. The actual number of bytes written is placed in \**out\_len*. If padding is enabled (the default) then **EVP\_EncryptFinal**() and **EVP\_EncryptFinal\_ex**(), which behave identically, encrypt the "final" data, that is any data that remains in a partial block. It uses NOTES (aka PKCS padding). The encrypted final data is written to *out* which should have sufficient space for one cipher block. The number of bytes written is placed in \**out\_len*. After this function is called, the encryption operation is finished and no further calls to **EVP\_EncryptUpdate**() should be made. If padding is disabled then **EVP\_EncryptFinal**() and **EVP\_EncryptFinal\_ex**() do not encrypt any more data and 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**(), **EVP\_DecryptInit\_ex**(), **EVP\_DecryptUpdate**(), **EVP\_DecryptFinal**(), and **EVP\_DecryptFinal\_ex**() are the corresponding decryption operations. **EVP\_DecryptFinal**() and **EVP\_DecryptFinal\_ex**() 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 *out* passed to **EVP\_DecryptUpdate**() should have sufficient room for (*in\_len* + cipher\_block\_size) bytes unless the cipher block size is 1 in which case *in\_len* bytes is sufficient. **EVP\_CipherInit**(), **EVP\_CipherInit\_ex**(), **EVP\_CipherUpdate**(), **EVP\_CipherFinal**(), and **EVP\_CipherFinal\_ex**() are functions that can be used for decryption or encryption. The operation performed depends on the value of the *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\_get\_cipherbyname**(), **EVP\_get\_cipherbynid**(), and **EVP\_get\_cipherbyobj**() return an *EVP\_CIPHER* structure when passed a cipher name, a NID or an *ASN1\_OBJECT* structure. **EVP\_CIPHER\_CTX\_cipher**() returns the *EVP\_CIPHER* structure when passed an *EVP\_CIPHER\_CTX* structure. Where possible the EVP interface to symmetric ciphers should be used in preference to the low level interfaces. This is because the code then becomes transparent to the cipher used and much more flexible. PKCS padding works by adding n padding bytes of value n to make the total length of the encrypted data a multiple of the block size. Padding is always added so if the data is already a multiple of the block size n will equal the block size. For example if the block size is 8 and 11 bytes are to be encrypted then 5 padding bytes of value 5 will be added. When decrypting, the final block is checked to see if it has the correct form. Although the decryption operation can produce an error if padding is enabled, it is not a strong test that the input data or key is correct. A random block has better than 1 in 256 chance of being of the correct format and problems with 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. **EVP\_get\_cipherbynid**() and **EVP\_get\_cipherbyobj**() are implemented as macros. ## RETURN VALUES **EVP\_CIPHER\_CTX\_new**() returns a pointer to a newly created *EVP\_CIPHER\_CTX* for success or NULL for failure. **EVP\_CIPHER\_CTX\_reset**(), **EVP\_CIPHER\_CTX\_copy**(), **EVP\_EncryptInit\_ex**(), **EVP\_EncryptUpdate**(), **EVP\_EncryptFinal\_ex**(), **EVP\_DecryptInit\_ex**(), **EVP\_DecryptUpdate**(), **EVP\_DecryptFinal\_ex**(), **EVP\_CipherInit\_ex**(), **EVP\_CipherUpdate**(), **EVP\_CipherFinal\_ex**(), **EVP\_EncryptInit**(), **EVP\_EncryptFinal**(), **EVP\_DecryptInit**(), **EVP\_DecryptFinal**(), **EVP\_CipherInit**(), and **EVP\_CipherFinal**() return 1 for success or 0 for failure. **EVP\_CIPHER\_CTX\_encrypting**() returns 1 if *ctx* is initialized for encryption or 0 otherwise, in which case it may be uninitialized or initialized for decryption. **EVP\_get\_cipherbyname**(), **EVP\_get\_cipherbynid**(), and **EVP\_get\_cipherbyobj**() return an *EVP\_CIPHER* structure or NULL on error. **EVP\_CIPHER\_CTX\_cipher**() returns an *EVP\_CIPHER* structure. ## CIPHER LISTING - **EVP\_enc\_null**() Null cipher: does nothing. - **EVP\_idea\_cbc**(), **EVP\_idea\_ecb**(), **EVP\_idea\_cfb64**(), **EVP\_idea\_ofb**() IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. IDEA is a block cipher operating on 64 bit blocks using a 128 bit *key*. **EVP\_idea\_cfb**() is an alias for **EVP\_idea\_cfb64**(), implemented as a macro. - **EVP\_bf\_cbc**(), **EVP\_bf\_ecb**(), **EVP\_bf\_cfb64**(), **EVP\_bf\_ofb**() Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. Blowfish is a block cipher operating on 64 bit blocks using a variable *key* length. The default key length is 128 bits. **EVP\_bf\_cfb**() is an alias for **EVP\_bf\_cfb64**(), implemented as a macro. - **EVP\_cast5\_cbc**(), **EVP\_cast5\_ecb**(), **EVP\_cast5\_cfb64**(), **EVP\_cast5\_ofb**() CAST-128 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. CAST-128 is a block cipher operating on 64 bit blocks using a variable *key* length. The default and maximum key length is 128 bits. **EVP\_cast5\_cfb**() is an alias for **EVP\_cast5\_cfb64**(), implemented as a macro. Some algorithms are documented in separate manual pages: | | | | | --- | --- | --- | | manual page | block size | *key* size (in bits) | | EVP\_aes\_128\_cbc(3) | 128 | 128, 192, 256 | | EVP\_aes\_128\_ccm(3) | 128 | 128, 192, 256 | | EVP\_aes\_128\_gcm(3) | 128 | 128, 192, 256 | | EVP\_camellia\_128\_cbc(3) | 128 | 128, 192, 256 | | EVP\_chacha20(3) | stream | 256 | | EVP\_des\_cbc(3) | 64 | 64 | | EVP\_rc2\_cbc(3) | 64 | variable, default 128 | | EVP\_rc4(3) | stream | variable, default 128 | | EVP\_sm4\_cbc(3) | 128 | 128 | ## EXAMPLES Encrypt a string using blowfish: ``` int do_crypt(char *out_filename) { unsigned char out_buf[1024]; int out_len, tmp_len; /* * Bogus key and IV: we'd normally set these from * another source. */ unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; unsigned char iv[] = {1,2,3,4,5,6,7,8}; const char in_text[] = "Some Crypto Text"; EVP_CIPHER_CTX *ctx; FILE *out_fileptr; ctx = EVP_CIPHER_CTX_new(); EVP_EncryptInit_ex(ctx, EVP_bf_cbc(), NULL, key, iv); if (!EVP_EncryptUpdate(ctx, out_buf, &out_len, in_text, strlen(in_text))) { /* Error */ EVP_CIPHER_CTX_free(ctx); return 0; } /* * Buffer passed to EVP_EncryptFinal() must be after data just * encrypted to avoid overwriting it. */ if (!EVP_EncryptFinal_ex(ctx, out_buf + out_len, &tmp_len)) { /* Error */ EVP_CIPHER_CTX_free(ctx); return 0; } out_len += tmp_len; EVP_CIPHER_CTX_free(ctx); /* * Need binary mode for fopen because encrypted data is * binary data. Also cannot use strlen() on it because * it won't be NUL terminated and may contain embedded * NULs. */ out_fileptr = fopen(out_filename, "wb"); if (out_fileptr == NULL) { /* Error */ return 0; } fwrite(out_buf, 1, out_len, out_fileptr); fclose(out_fileptr); return 1; } ``` The ciphertext from the above example can be decrypted using the [openssl(1)](/openssl/1.md) utility with the command line: ``` openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F \ -iv 0102030405060708 -d ``` General encryption, decryption function example using FILE I/O and AES128 with a 128-bit key: ``` int do_crypt(FILE *in_fileptr, FILE *out_fileptr, int do_encrypt) { /* Allow enough space in output buffer for additional block */ unsigned char in_buf[1024], out_buf[1024 + EVP_MAX_BLOCK_LENGTH]; int in_len, out_len; EVP_CIPHER_CTX *ctx; /* * Bogus key and IV: we'd normally set these from * another source. */ unsigned char key[] = "0123456789abcdeF"; unsigned char iv[] = "1234567887654321"; ctx = EVP_CIPHER_CTX_new(); EVP_CipherInit_ex(ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, do_encrypt); EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt); for (;;) { in_len = fread(in_buf, 1, 1024, in_fileptr); if (in_len <= 0) break; if (!EVP_CipherUpdate(ctx, out_buf, &out_len, in_buf, in_len)) { /* Error */ EVP_CIPHER_CTX_free(ctx); return 0; } fwrite(out_buf, 1, out_len, out_fileptr); } if (!EVP_CipherFinal_ex(ctx, out_buf, &out_len)) { /* Error */ EVP_CIPHER_CTX_free(ctx); return 0; } fwrite(out_buf, 1, out_len, out_fileptr); EVP_CIPHER_CTX_free(ctx); return 1; } ``` ## SEE ALSO BIO\_f\_cipher(3), evp(3), EVP\_AEAD\_CTX\_init(3), EVP\_aes\_128\_cbc(3), EVP\_aes\_128\_ccm(3), EVP\_aes\_128\_gcm(3), EVP\_camellia\_128\_cbc(3), EVP\_chacha20(3), EVP\_CIPHER\_CTX\_ctrl(3), EVP\_CIPHER\_CTX\_get\_cipher\_data(3), EVP\_CIPHER\_CTX\_init(3), EVP\_CIPHER\_CTX\_set\_flags(3), EVP\_CIPHER\_nid(3), EVP\_des\_cbc(3), EVP\_OpenInit(3), EVP\_rc2\_cbc(3), EVP\_rc4(3), EVP\_SealInit(3), EVP\_sm4\_cbc(3) ## HISTORY **EVP\_EncryptInit**(), **EVP\_EncryptUpdate**(), **EVP\_EncryptFinal**(), **EVP\_DecryptInit**(), **EVP\_DecryptUpdate**(), **EVP\_DecryptFinal**(), **EVP\_CipherInit**(), **EVP\_CipherUpdate**(), **EVP\_CipherFinal**(), **EVP\_get\_cipherbyname**(), **EVP\_idea\_cbc**(), **EVP\_idea\_ecb**(), **EVP\_idea\_cfb**(), and **EVP\_idea\_ofb**() first appeared in SSLeay 0.5.1. **EVP\_bf\_cbc**(), **EVP\_bf\_ecb**(), **EVP\_bf\_cfb**(), and **EVP\_bf\_ofb**() first appeared in SSLeay 0.6.6. **EVP\_get\_cipherbyobj**(), **EVP\_CIPHER\_CTX\_cipher**(), and **EVP\_enc\_null**() first appeared in SSLeay 0.8.0. **EVP\_get\_cipherbynid**() first appeared in SSLeay 0.8.1. All these functions have been available since OpenBSD 2.4. **EVP\_EncryptInit\_ex**(), **EVP\_EncryptFinal\_ex**(), **EVP\_DecryptInit\_ex**(), **EVP\_DecryptFinal\_ex**(), **EVP\_CipherInit\_ex**(), and **EVP\_CipherFinal\_ex**() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2. **EVP\_bf\_cfb64**(), **EVP\_cast5\_cfb64**(), and **EVP\_idea\_cfb64**() first appeared in OpenSSL 0.9.7e and have been available since OpenBSD 3.8. **EVP\_CIPHER\_CTX\_new**() and **EVP\_CIPHER\_CTX\_free**() first appeared in OpenSSL 0.9.8b and have been available since OpenBSD 4.5. **EVP\_CIPHER\_CTX\_copy**() first appeared in OpenSSL 1.0.0 and has been available since OpenBSD 4.9. **EVP\_CIPHER\_CTX\_reset**() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 6.3. **EVP\_CIPHER\_CTX\_encrypting**() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 6.4. ## BUGS **EVP\_CIPHER\_CTX\_copy**() may already have cleared the data in *out* and copied some new data into it even if it fails and returns 0.