1 files changed, 939 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/EVP_EncryptInit.3 b/src/lib/libcrypto/man/EVP_EncryptInit.3
new file mode 100644
index 0000000000..44967f863f
--- /dev/null
+++ b/src/lib/libcrypto/man/EVP_EncryptInit.3
@@ -0,0 +1,939 @@
+.Dd $Mdocdate: November 3 2016 $
+.Dt EVP_ENCRYPTINIT 3
+.Os
+.Sh NAME
+.Nm EVP_CIPHER_CTX_init ,
+.Nm EVP_EncryptInit_ex ,
+.Nm EVP_EncryptUpdate ,
+.Nm EVP_EncryptFinal_ex ,
+.Nm EVP_DecryptInit_ex ,
+.Nm EVP_DecryptUpdate ,
+.Nm EVP_DecryptFinal_ex ,
+.Nm EVP_CipherInit_ex ,
+.Nm EVP_CipherUpdate ,
+.Nm EVP_CipherFinal_ex ,
+.Nm EVP_CIPHER_CTX_set_key_length ,
+.Nm EVP_CIPHER_CTX_ctrl ,
+.Nm EVP_CIPHER_CTX_cleanup ,
+.Nm EVP_EncryptInit ,
+.Nm EVP_EncryptFinal ,
+.Nm EVP_DecryptInit ,
+.Nm EVP_DecryptFinal ,
+.Nm EVP_CipherInit ,
+.Nm EVP_CipherFinal ,
+.Nm EVP_get_cipherbyname ,
+.Nm EVP_get_cipherbynid ,
+.Nm EVP_get_cipherbyobj ,
+.Nm EVP_CIPHER_nid ,
+.Nm EVP_CIPHER_block_size ,
+.Nm EVP_CIPHER_key_length ,
+.Nm EVP_CIPHER_iv_length ,
+.Nm EVP_CIPHER_flags ,
+.Nm EVP_CIPHER_mode ,
+.Nm EVP_CIPHER_type ,
+.Nm EVP_CIPHER_CTX_cipher ,
+.Nm EVP_CIPHER_CTX_nid ,
+.Nm EVP_CIPHER_CTX_block_size ,
+.Nm EVP_CIPHER_CTX_key_length ,
+.Nm EVP_CIPHER_CTX_iv_length ,
+.Nm EVP_CIPHER_CTX_get_app_data ,
+.Nm EVP_CIPHER_CTX_set_app_data ,
+.Nm EVP_CIPHER_CTX_type ,
+.Nm EVP_CIPHER_CTX_flags ,
+.Nm EVP_CIPHER_CTX_mode ,
+.Nm EVP_CIPHER_param_to_asn1 ,
+.Nm EVP_CIPHER_asn1_to_param ,
+.Nm EVP_CIPHER_CTX_set_padding ,
+.Nm EVP_enc_null ,
+.Nm EVP_des_cbc ,
+.Nm EVP_des_ecb ,
+.Nm EVP_des_cfb ,
+.Nm EVP_des_ofb ,
+.Nm EVP_des_ede_cbc ,
+.Nm EVP_des_ede ,
+.Nm EVP_des_ede_ofb ,
+.Nm EVP_des_ede_cfb ,
+.Nm EVP_des_ede3_cbc ,
+.Nm EVP_des_ede3 ,
+.Nm EVP_des_ede3_ofb ,
+.Nm EVP_des_ede3_cfb ,
+.Nm EVP_desx_cbc ,
+.Nm EVP_rc4 ,
+.Nm EVP_rc4_40 ,
+.Nm EVP_idea_cbc ,
+.Nm EVP_idea_ecb ,
+.Nm EVP_idea_cfb ,
+.Nm EVP_idea_ofb ,
+.Nm EVP_idea_cbc ,
+.Nm EVP_rc2_cbc ,
+.Nm EVP_rc2_ecb ,
+.Nm EVP_rc2_cfb ,
+.Nm EVP_rc2_ofb ,
+.Nm EVP_rc2_40_cbc ,
+.Nm EVP_rc2_64_cbc ,
+.Nm EVP_bf_cbc ,
+.Nm EVP_bf_ecb ,
+.Nm EVP_bf_cfb ,
+.Nm EVP_bf_ofb ,
+.Nm EVP_cast5_cbc ,
+.Nm EVP_cast5_ecb ,
+.Nm EVP_cast5_cfb ,
+.Nm EVP_cast5_ofb ,
+.Nm EVP_aes_128_gcm ,
+.Nm EVP_aes_192_gcm ,
+.Nm EVP_aes_256_gcm ,
+.Nm EVP_aes_128_ccm ,
+.Nm EVP_aes_192_ccm ,
+.Nm EVP_aes_256_ccm ,
+.Nm EVP_rc5_32_12_16_cbc ,
+.Nm EVP_rc5_32_12_16_cfb ,
+.Nm EVP_rc5_32_12_16_ecb ,
+.Nm EVP_rc5_32_12_16_ofb
+.Nd EVP cipher routines
+.Sh SYNOPSIS
+.In openssl/evp.h
+.Ft void
+.Fo EVP_CIPHER_CTX_init
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fc
+.Ft int
+.Fo EVP_EncryptInit_ex
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "const EVP_CIPHER *type"
+.Fa "ENGINE *impl"
+.Fa "unsigned char *key"
+.Fa "unsigned char *iv"
+.Fc
+.Ft int
+.Fo EVP_EncryptUpdate
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "unsigned char *out"
+.Fa "int *outl"
+.Fa "unsigned char *in"
+.Fa "int inl"
+.Fc
+.Ft int
+.Fo EVP_EncryptFinal_ex
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "unsigned char *out"
+.Fa "int *outl"
+.Fc
+.Ft int
+.Fo EVP_DecryptInit_ex
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "const EVP_CIPHER *type"
+.Fa "ENGINE *impl"
+.Fa "unsigned char *key"
+.Fa "unsigned char *iv"
+.Fc
+.Ft int
+.Fo EVP_DecryptUpdate
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "unsigned char *out"
+.Fa "int *outl"
+.Fa "unsigned char *in"
+.Fa "int inl"
+.Fc
+.Ft int
+.Fo EVP_DecryptFinal_ex
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "unsigned char *outm"
+.Fa "int *outl"
+.Fc
+.Ft int
+.Fo EVP_CipherInit_ex
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "const EVP_CIPHER *type"
+.Fa "ENGINE *impl"
+.Fa "unsigned char *key"
+.Fa "unsigned char *iv"
+.Fa "int enc"
+.Fc
+.Ft int
+.Fo EVP_CipherUpdate
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "unsigned char *out"
+.Fa "int *outl"
+.Fa "unsigned char *in"
+.Fa "int inl"
+.Fc
+.Ft int
+.Fo EVP_CipherFinal_ex
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "unsigned char *outm"
+.Fa "int *outl"
+.Fc
+.Ft int
+.Fo EVP_EncryptInit
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "const EVP_CIPHER *type"
+.Fa "unsigned char *key"
+.Fa "unsigned char *iv"
+.Fc
+.Ft int
+.Fo EVP_EncryptFinal
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "unsigned char *out"
+.Fa "int *outl"
+.Fc
+.Ft int
+.Fo EVP_DecryptInit
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "const EVP_CIPHER *type"
+.Fa "unsigned char *key"
+.Fa "unsigned char *iv"
+.Fc
+.Ft int
+.Fo EVP_DecryptFinal
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "unsigned char *outm"
+.Fa "int *outl"
+.Fc
+.Ft int
+.Fo EVP_CipherInit
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "const EVP_CIPHER *type"
+.Fa "unsigned char *key"
+.Fa "unsigned char *iv"
+.Fa "int enc"
+.Fc
+.Ft int
+.Fo EVP_CipherFinal
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "unsigned char *outm"
+.Fa "int *outl"
+.Fc
+.Ft int
+.Fo EVP_CIPHER_CTX_set_padding
+.Fa "EVP_CIPHER_CTX *x"
+.Fa "int padding"
+.Fc
+.Ft int
+.Fo EVP_CIPHER_CTX_set_key_length
+.Fa "EVP_CIPHER_CTX *x"
+.Fa "int keylen"
+.Fc
+.Ft int
+.Fo EVP_CIPHER_CTX_ctrl
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "int type"
+.Fa "int arg"
+.Fa "void *ptr"
+.Fc
+.Ft int
+.Fo EVP_CIPHER_CTX_cleanup
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fc
+.Ft const EVP_CIPHER *
+.Fo EVP_get_cipherbyname
+.Fa "const char *name"
+.Fc
+.Fd #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a))
+.Fd #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a))
+.Fd #define EVP_CIPHER_nid(e)           ((e)->nid)
+.Fd #define EVP_CIPHER_block_size(e)    ((e)->block_size)
+.Fd #define EVP_CIPHER_key_length(e)    ((e)->key_len)
+.Fd #define EVP_CIPHER_iv_length(e)             ((e)->iv_len)
+.Fd #define EVP_CIPHER_flags(e)         ((e)->flags)
+.Fd #define EVP_CIPHER_mode(e)          ((e)->flags) & EVP_CIPH_MODE)
+.Ft int
+.Fo EVP_CIPHER_type
+.Fa "const EVP_CIPHER *ctx"
+.Fc
+.Fd #define EVP_CIPHER_CTX_cipher(e)    ((e)->cipher)
+.Fd #define EVP_CIPHER_CTX_nid(e)               ((e)->cipher->nid)
+.Fd #define EVP_CIPHER_CTX_block_size(e)        ((e)->cipher->block_size)
+.Fd #define EVP_CIPHER_CTX_key_length(e)        ((e)->key_len)
+.Fd #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len)
+.Fd #define EVP_CIPHER_CTX_get_app_data(e)      ((e)->app_data)
+.Fd #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d))
+.Fd #define EVP_CIPHER_CTX_type(c)         EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c))
+.Fd #define EVP_CIPHER_CTX_flags(e)             ((e)->cipher->flags)
+.Fd #define EVP_CIPHER_CTX_mode(e)              ((e)->cipher->flags & EVP_CIPH_MODE)
+.Ft int
+.Fo EVP_CIPHER_param_to_asn1
+.Fa "EVP_CIPHER_CTX *c"
+.Fa "ASN1_TYPE *type"
+.Fc
+.Ft int
+.Fo EVP_CIPHER_asn1_to_param
+.Fa "EVP_CIPHER_CTX *c"
+.Fa "ASN1_TYPE *type"
+.Fc
+.Sh DESCRIPTION
+The EVP cipher routines are a high level interface to certain symmetric
+ciphers.
+.Pp
+.Fn EVP_CIPHER_CTX_init
+initializes the cipher context
+.Fa ctx .
+.Pp
+.Fn EVP_EncryptInit_ex
+sets up the cipher context
+.Fa ctx
+for encryption with cipher
+.Fa type
+from
+.Vt ENGINE
+.Fa impl .
+.Fa ctx
+must be initialized before calling this function.
+.Fa type
+is normally supplied by a function such as
+.Fn EVP_aes_256_cbc .
+If
+.Fa impl
+is
+.Dv NULL ,
+then the default implementation is used.
+.Fa key
+is the symmetric key to use and
+.Fa iv
+is the IV to use (if necessary), the actual number of bytes used for the
+key and IV depends on the cipher.
+It is possible to set all parameters to
+.Dv NULL
+except
+.Fa type
+in an initial call and supply the remaining parameters in subsequent
+calls, all of which have
+.Fa type
+set to
+.Dv NULL .
+This is done when the default cipher parameters are not appropriate.
+.Pp
+.Fn EVP_EncryptUpdate
+encrypts
+.Fa inl
+bytes from the buffer
+.Fa in
+and writes the encrypted version to
+.Fa 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 (inl + cipher_block_size - 1) so
+.Fa outl
+should contain sufficient room.
+The actual number of bytes written is placed in
+.Fa outl .
+.Pp
+If padding is enabled (the default) then
+.Fn EVP_EncryptFinal_ex
+encrypts 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
+.Fa out
+which should have sufficient space for one cipher block.
+The number of bytes written is placed in
+.Fa outl .
+After this function is called the encryption operation is finished and
+no further calls to
+.Fn EVP_EncryptUpdate
+should be made.
+.Pp
+If padding is disabled then
+.Fn 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.
+.Pp
+.Fn EVP_DecryptInit_ex ,
+.Fn EVP_DecryptUpdate ,
+and
+.Fn EVP_DecryptFinal_ex
+are the corresponding decryption operations.
+.Fn 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
+.Fa out
+passed to
+.Fn EVP_DecryptUpdate
+should have sufficient room for (inl + cipher_block_size) bytes
+unless the cipher block size is 1 in which case
+.Fa inl
+bytes is sufficient.
+.Pp
+.Fn EVP_CipherInit_ex ,
+.Fn EVP_CipherUpdate ,
+and
+.Fn EVP_CipherFinal_ex
+are functions that can be used for decryption or encryption.
+The operation performed depends on the value of the
+.Fa enc
+parameter.
+It should be set to 1 for encryption, 0 for decryption and -1 to leave
+the value unchanged (the actual value of
+.Fa enc
+being supplied in a previous call).
+.Pp
+.Fn EVP_CIPHER_CTX_cleanup
+clears all information from a cipher context and free up any allocated
+memory associate with it.
+It should be called after all operations using a cipher are complete so
+sensitive information does not remain in memory.
+.Pp
+.Fn EVP_EncryptInit ,
+.Fn EVP_DecryptInit ,
+and
+.Fn EVP_CipherInit
+behave in a similar way to
+.Fn EVP_EncryptInit_ex ,
+.Fn EVP_DecryptInit_ex ,
+and
+.Fn EVP_CipherInit_ex
+except the
+.Fa ctx
+parameter does not need to be initialized and they always use the
+default cipher implementation.
+.Pp
+.Fn EVP_EncryptFinal ,
+.Fn EVP_DecryptFinal ,
+and
+.Fn EVP_CipherFinal
+are identical to
+.Fn EVP_EncryptFinal_ex ,
+.Fn EVP_DecryptFinal_ex ,
+and
+.Fn EVP_CipherFinal_ex .
+In previous releases of OpenSSL, they also used to clean up the
+.Fa ctx ,
+but this is no longer done and
+.Fn EVP_CIPHER_CTX_cleanup
+must be called to free any context resources.
+.Pp
+.Fn EVP_get_cipherbyname ,
+.Fn EVP_get_cipherbynid ,
+and
+.Fn EVP_get_cipherbyobj
+return an
+.Vt EVP_CIPHER
+structure when passed a cipher name, a NID or an
+.Vt ASN1_OBJECT
+structure.
+.Pp
+.Fn EVP_CIPHER_nid
+and
+.Fn EVP_CIPHER_CTX_nid
+return the NID of a cipher when passed an
+.Vt EVP_CIPHER
+or
+.Vt EVP_CIPHER_CTX
+structure.
+The actual NID value is an internal value which may not have a
+corresponding OBJECT IDENTIFIER.
+.Pp
+.Fn EVP_CIPHER_CTX_set_padding
+enables or disables padding.
+By default encryption operations are padded using standard block padding
+and the padding is checked and removed when decrypting.
+If the
+.Sy padding
+parameter is zero, then no padding is performed, the total amount of data
+encrypted or decrypted must then be a multiple of the block size or an
+error will occur.
+.Pp
+.Fn EVP_CIPHER_key_length
+and
+.Fn EVP_CIPHER_CTX_key_length
+return the key length of a cipher when passed an
+.Vt EVP_CIPHER
+or
+.Vt EVP_CIPHER_CTX
+structure.
+The constant
+.Dv EVP_MAX_KEY_LENGTH
+is the maximum key length for all ciphers.
+Note: although
+.Fn EVP_CIPHER_key_length
+is fixed for a given cipher, the value of
+.Fn EVP_CIPHER_CTX_key_length
+may be different for variable key length ciphers.
+.Pp
+.Fn EVP_CIPHER_CTX_set_key_length
+sets the key length of the cipher ctx.
+If the cipher is a fixed length cipher, then attempting to set the key
+length to any value other than the fixed value is an error.
+.Pp
+.Fn EVP_CIPHER_iv_length
+and
+.Fn EVP_CIPHER_CTX_iv_length
+return the IV length of a cipher when passed an
+.Vt EVP_CIPHER
+or
+.Vt EVP_CIPHER_CTX .
+It will return zero if the cipher does not use an IV.
+The constant
+.Dv EVP_MAX_IV_LENGTH
+is the maximum IV length for all ciphers.
+.Pp
+.Fn EVP_CIPHER_block_size
+and
+.Fn EVP_CIPHER_CTX_block_size
+return the block size of a cipher when passed an
+.Vt EVP_CIPHER
+or
+.Vt EVP_CIPHER_CTX
+structure.
+The constant
+.Dv EVP_MAX_IV_LENGTH
+is also the maximum block length for all ciphers.
+.Pp
+.Fn EVP_CIPHER_type
+and
+.Fn EVP_CIPHER_CTX_type
+return the type of the passed cipher or context.
+This "type" is the actual NID of the cipher OBJECT IDENTIFIER as such it
+ignores the cipher parameters and 40 bit RC2 and 128 bit RC2 have the
+same NID. If the cipher does not have an object identifier or does not
+have ASN1 support this function will return
+.Dv NID_undef .
+.Pp
+.Fn EVP_CIPHER_CTX_cipher
+returns the
+.Vt EVP_CIPHER
+structure when passed an
+.Vt EVP_CIPHER_CTX
+structure.
+.Pp
+.Fn EVP_CIPHER_mode
+and
+.Fn EVP_CIPHER_CTX_mode
+return the block cipher mode:
+.Dv EVP_CIPH_ECB_MODE ,
+.Dv EVP_CIPH_CBC_MODE ,
+.Dv EVP_CIPH_CFB_MODE ,
+or
+.Dv EVP_CIPH_OFB_MODE .
+If the cipher is a stream cipher then
+.Dv EVP_CIPH_STREAM_CIPHER
+is returned.
+.Pp
+.Fn EVP_CIPHER_param_to_asn1
+sets the AlgorithmIdentifier "parameter" based on the passed cipher.
+This will typically include any parameters and an IV.
+The cipher IV (if any) must be set when this call is made.
+This call should be made before the cipher is actually "used" (before any
+.Fn EVP_EncryptUpdate ,
+.Fn EVP_DecryptUpdate
+calls for example).
+This function may fail if the cipher does not have any ASN1 support.
+.Pp
+.Fn EVP_CIPHER_asn1_to_param
+sets the cipher parameters based on an ASN1 AlgorithmIdentifier
+"parameter".
+The precise effect depends on the cipher.
+In the case of RC2, for example, it will set the IV and effective
+key length.
+This function should be called after the base cipher type is set but
+before the key is set.
+For example
+.Fn EVP_CipherInit
+will be called with the IV and key set to
+.Dv NULL ,
+.Fn EVP_CIPHER_asn1_to_param
+will be called and finally
+.Fn EVP_CipherInit
+again with all parameters except the key set to
+.Dv NULL .
+It is possible for this function to fail if the cipher does not
+have any ASN1 support or the parameters cannot be set (for example
+the RC2 effective key length is not supported).
+.Pp
+.Fn EVP_CIPHER_CTX_ctrl
+allows various cipher specific parameters to be determined and set.
+Currently only the RC2 effective key length and the number of rounds of
+RC5 can be set.
+.Sh RETURN VALUES
+.Fn EVP_EncryptInit_ex ,
+.Fn EVP_EncryptUpdate ,
+and
+.Fn EVP_EncryptFinal_ex
+return 1 for success and 0 for failure.
+.Pp
+.Fn EVP_DecryptInit_ex
+and
+.Fn EVP_DecryptUpdate
+return 1 for success and 0 for failure.
+.Fn EVP_DecryptFinal_ex
+returns 0 if the decrypt failed or 1 for success.
+.Pp
+.Fn EVP_CipherInit_ex
+and
+.Fn EVP_CipherUpdate
+return 1 for success and 0 for failure.
+.Fn EVP_CipherFinal_ex
+returns 0 for a decryption failure or 1 for success.
+.Pp
+.Fn EVP_CIPHER_CTX_cleanup
+returns 1 for success and 0 for failure.
+.Pp
+.Fn EVP_get_cipherbyname ,
+.Fn EVP_get_cipherbynid ,
+and
+.Fn EVP_get_cipherbyobj
+return an
+.Vt EVP_CIPHER
+structure or
+.Dv NULL
+on error.
+.Pp
+.Fn EVP_CIPHER_nid
+and
+.Fn EVP_CIPHER_CTX_nid
+return a NID.
+.Pp
+.Fn EVP_CIPHER_block_size
+and
+.Fn EVP_CIPHER_CTX_block_size
+return the block size.
+.Pp
+.Fn EVP_CIPHER_key_length
+and
+.Fn EVP_CIPHER_CTX_key_length
+return the key length.
+.Pp
+.Fn EVP_CIPHER_CTX_set_padding
+always returns 1.
+.Pp
+.Fn EVP_CIPHER_iv_length
+and
+.Fn EVP_CIPHER_CTX_iv_length
+return the IV length or zero if the cipher does not use an IV.
+.Pp
+.Fn EVP_CIPHER_type
+and
+.Fn EVP_CIPHER_CTX_type
+return the NID of the cipher's OBJECT IDENTIFIER or
+.Dv NID_undef
+if it has no defined OBJECT IDENTIFIER.
+.Pp
+.Fn EVP_CIPHER_CTX_cipher
+returns an
+.Vt EVP_CIPHER
+structure.
+.Pp
+.Fn EVP_CIPHER_param_to_asn1
+and
+.Fn EVP_CIPHER_asn1_to_param
+return 1 for success or 0 for failure.
+.Pp
+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.
+.Pp
+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.
+.Pp
+When decrypting the final block is checked to see if it has the correct
+form.
+.Pp
+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.
+.Pp
+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.
+.Pp
+The functions
+.Fn EVP_EncryptInit ,
+.Fn EVP_EncryptFinal ,
+.Fn EVP_DecryptInit ,
+.Fn EVP_CipherInit ,
+and
+.Fn EVP_CipherFinal
+are obsolete but are retained for compatibility with existing code.
+New code should use
+.Fn EVP_EncryptInit_ex ,
+.Fn EVP_EncryptFinal_ex ,
+.Fn EVP_DecryptInit_ex ,
+.Fn EVP_DecryptFinal_ex ,
+.Fn EVP_CipherInit_ex ,
+and
+.Fn EVP_CipherFinal_ex
+because they can reuse an existing context without allocating and
+freeing it up on each call.
+.Sh CIPHER LISTING
+All algorithms have a fixed key length unless otherwise stated.
+.Bl -tag -width Ds
+.It Fn EVP_enc_null void
+Null cipher: does nothing.
+.It Xo
+.Fn EVP_aes_128_cbc void ,
+.Fn EVP_aes_128_ecb void ,
+.Fn EVP_aes_128_cfb void ,
+.Fn EVP_aes_128_ofb void
+.Xc
+128-bit AES in CBC, ECB, CFB and OFB modes respectively.
+.It Xo
+.Fn EVP_aes_192_cbc void ,
+.Fn EVP_aes_192_ecb void ,
+.Fn EVP_aes_192_cfb void ,
+.Fn EVP_aes_192_ofb void
+.Xc
+192-bit AES in CBC, ECB, CFB and OFB modes respectively.
+.It Xo
+.Fn EVP_aes_256_cbc void ,
+.Fn EVP_aes_256_ecb void ,
+.Fn EVP_aes_256_cfb void ,
+.Fn EVP_aes_256_ofb void
+.Xc
+256-bit AES in CBC, ECB, CFB and OFB modes respectively.
+.It Xo
+.Fn EVP_des_cbc void ,
+.Fn EVP_des_ecb void ,
+.Fn EVP_des_cfb void ,
+.Fn EVP_des_ofb void
+.Xc
+DES in CBC, ECB, CFB and OFB modes respectively.
+.It Xo
+.Fn EVP_des_ede_cbc void ,
+.Fn EVP_des_ede void ,
+.Fn EVP_des_ede_ofb void ,
+.Fn EVP_des_ede_cfb void
+.Xc
+Two key triple DES in CBC, ECB, CFB and OFB modes respectively.
+.It Xo
+.Fn EVP_des_ede3_cbc void ,
+.Fn EVP_des_ede3 void ,
+.Fn EVP_des_ede3_ofb void ,
+.Fn EVP_des_ede3_cfb void
+.Xc
+Three key triple DES in CBC, ECB, CFB and OFB modes respectively.
+.It Fn EVP_desx_cbc void
+DESX algorithm in CBC mode.
+.It Fn EVP_rc4 void
+RC4 stream cipher.
+This is a variable key length cipher with default key length 128 bits.
+.It Fn EVP_rc4_40 void
+RC4 stream cipher with 40 bit key length.
+This is obsolete and new code should use
+.Fn EVP_rc4
+and the
+.Fn EVP_CIPHER_CTX_set_key_length
+function.
+.It Xo
+.Fn EVP_idea_cbc void ,
+.Fn EVP_idea_ecb void ,
+.Fn EVP_idea_cfb void ,
+.Fn EVP_idea_ofb void
+.Xc
+IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
+.It Xo
+.Fn EVP_rc2_cbc void ,
+.Fn EVP_rc2_ecb void ,
+.Fn EVP_rc2_cfb void ,
+.Fn EVP_rc2_ofb void
+.Xc
+RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
+This is a variable key length cipher with an additional parameter called
+"effective key bits" or "effective key length".
+By default both are set to 128 bits.
+.It Xo
+.Fn EVP_rc2_40_cbc void ,
+.Fn EVP_rc2_64_cbc void
+.Xc
+RC2 algorithm in CBC mode with a default key length and effective key
+length of 40 and 64 bits.
+These are obsolete and new code should use
+.Fn EVP_rc2_cbc ,
+.Fn EVP_CIPHER_CTX_set_key_length ,
+and
+.Fn EVP_CIPHER_CTX_ctrl
+to set the key length and effective key length.
+.It Xo
+.Fn EVP_bf_cbc void ,
+.Fn EVP_bf_ecb void ,
+.Fn EVP_bf_cfb void ,
+.Fn EVP_bf_ofb void
+.Xc
+Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes
+respectively.
+This is a variable key length cipher.
+.It Xo
+.Fn EVP_cast5_cbc void ,
+.Fn EVP_cast5_ecb void ,
+.Fn EVP_cast5_cfb void ,
+.Fn EVP_cast5_ofb void
+.Xc
+CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
+This is a variable key length cipher.
+.It Xo
+.Fn EVP_rc5_32_12_16_cbc void ,
+.Fn EVP_rc5_32_12_16_ecb void ,
+.Fn EVP_rc5_32_12_16_cfb void ,
+.Fn EVP_rc5_32_12_16_ofb void
+.Xc
+RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
+This is a variable key length cipher with an additional "number of
+rounds" parameter.
+By default the key length is set to 128 bits and 12 rounds.
+.El
+.Sh EXAMPLES
+Get the number of rounds used in RC5:
+.Bd -literal
+int nrounds;
+EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds);
+.Ed
+.Pp
+Get the RC2 effective key length:
+.Bd -literal
+int key_bits;
+EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits);
+.Ed
+.Pp
+Set the number of rounds used in RC5:
+.Bd -literal
+int nrounds;
+EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL);
+.Ed
+.Pp
+Set the effective key length used in RC2:
+.Bd -literal
+int key_bits;
+EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL);
+.Ed
+.Pp
+Encrypt a string using blowfish:
+.Bd -literal
+int
+do_crypt(char *outfile)
+{
+        unsigned char outbuf[1024];
+        int outlen, tmplen;
+        /*
+         * 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 intext[] = "Some Crypto Text";
+        EVP_CIPHER_CTX ctx;
+        FILE *out;
+        EVP_CIPHER_CTX_init(&ctx);
+        EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv);
+
+        if (!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext,
+            strlen(intext))) {
+                /* Error */
+                return 0;
+        }
+        /*
+         * Buffer passed to EVP_EncryptFinal() must be after data just
+         * encrypted to avoid overwriting it.
+         */
+        if (!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen)) {
+                /* Error */
+                return 0;
+        }
+        outlen += tmplen;
+        EVP_CIPHER_CTX_cleanup(&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 = fopen(outfile, "wb");
+        fwrite(outbuf, 1, outlen, out);
+        fclose(out);
+        return 1;
+}
+.Ed
+.Pp
+The ciphertext from the above example can be decrypted using the
+.Xr openssl 1
+utility with the command line:
+.Bd -literal
+openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F \e
+           -iv 0102030405060708 -d
+.Ed
+.Pp
+General encryption, decryption function example using FILE I/O and RC2
+with an 80 bit key:
+.Bd -literal
+int
+do_crypt(FILE *in, FILE *out, int do_encrypt)
+{
+        /* Allow enough space in output buffer for additional block */
+        inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
+        int inlen, outlen;
+        /*
+         * Bogus key and IV: we'd normally set these from
+         * another source.
+         */
+        unsigned char key[] = "0123456789";
+        unsigned char iv[] = "12345678";
+
+        /* Don't set key or IV because we will modify the parameters */
+        EVP_CIPHER_CTX_init(&ctx);
+        EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt);
+        EVP_CIPHER_CTX_set_key_length(&ctx, 10);
+        /* We finished modifying parameters so now we can set key and IV */
+        EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
+
+        for(;;) {
+                inlen = fread(inbuf, 1, 1024, in);
+                if (inlen <= 0)
+                        break;
+                if (!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf,
+                    inlen)) {
+                        /* Error */
+                        EVP_CIPHER_CTX_cleanup(&ctx);
+                        return 0;
+                }
+                fwrite(outbuf, 1, outlen, out);
+        }
+        if (!EVP_CipherFinal_ex(&ctx, outbuf, &outlen)) {
+                /* Error */
+                EVP_CIPHER_CTX_cleanup(&ctx);
+                return 0;
+        }
+        fwrite(outbuf, 1, outlen, out);
+
+        EVP_CIPHER_CTX_cleanup(&ctx);
+        return 1;
+}
+.Ed
+.Sh SEE ALSO
+.Xr evp 3
+.Sh HISTORY
+.Fn EVP_CIPHER_CTX_init ,
+.Fn EVP_EncryptInit_ex ,
+.Fn EVP_EncryptFinal_ex ,
+.Fn EVP_DecryptInit_ex ,
+.Fn EVP_DecryptFinal_ex ,
+.Fn EVP_CipherInit_ex ,
+.Fn EVP_CipherFinal_ex ,
+and
+.Fn EVP_CIPHER_CTX_set_padding
+appeared in OpenSSL 0.9.7.
+.Sh BUGS
+For RC5 the number of rounds can currently only be set to 8, 12 or 16.
+This is a limitation of the current RC5 code rather than the EVP
+interface.
+.Pp
+.Dv EVP_MAX_KEY_LENGTH
+and
+.Dv EVP_MAX_IV_LENGTH
+only refer to the internal ciphers with default key lengths.
+If custom ciphers exceed these values the results are unpredictable.
+This is because it has become standard practice to define a generic key
+as a fixed unsigned char array containing
+.Dv EVP_MAX_KEY_LENGTH
+bytes.
+.Pp
+The ASN1 code is incomplete (and sometimes inaccurate) it has only been
+tested for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC
+mode.