diff options
Diffstat (limited to 'secure/lib/libcrypto/man/EVP_EncryptInit.3')
| -rw-r--r-- | secure/lib/libcrypto/man/EVP_EncryptInit.3 | 715 |
1 files changed, 715 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/EVP_EncryptInit.3 b/secure/lib/libcrypto/man/EVP_EncryptInit.3 new file mode 100644 index 0000000..5b6e418 --- /dev/null +++ b/secure/lib/libcrypto/man/EVP_EncryptInit.3 @@ -0,0 +1,715 @@ +.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{ +. if \nF \{ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "EVP_EncryptInit 3" +.TH EVP_EncryptInit 3 "2015-12-03" "1.0.2e" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +EVP_CIPHER_CTX_init, 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_CIPHER_CTX_set_key_length, +EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_cleanup, EVP_EncryptInit, +EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal, +EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname, +EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid, +EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length, +EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, +EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, +EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data, +EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags, +EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param, +EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_des_cbc, EVP_des_ecb, +EVP_des_cfb, EVP_des_ofb, EVP_des_ede_cbc, EVP_des_ede, EVP_des_ede_ofb, +EVP_des_ede_cfb, EVP_des_ede3_cbc, EVP_des_ede3, EVP_des_ede3_ofb, +EVP_des_ede3_cfb, EVP_desx_cbc, EVP_rc4, EVP_rc4_40, EVP_idea_cbc, +EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_rc2_cbc, +EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc, +EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc, +EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, EVP_rc5_32_12_16_cbc, +EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb, +EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ccm, +EVP_aes_192_ccm, EVP_aes_256_ccm \- EVP cipher routines +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/evp.h> +\& +\& void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a); +\& +\& int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& ENGINE *impl, unsigned char *key, unsigned char *iv); +\& int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, +\& int *outl, 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, unsigned char *key, unsigned char *iv); +\& int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, +\& int *outl, 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, unsigned char *key, unsigned char *iv, int enc); +\& int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, +\& int *outl, unsigned char *in, int inl); +\& int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, +\& int *outl); +\& +\& int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& unsigned char *key, unsigned char *iv); +\& int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, +\& int *outl); +\& +\& int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& unsigned char *key, unsigned char *iv); +\& int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, +\& int *outl); +\& +\& int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& unsigned char *key, unsigned char *iv, int enc); +\& int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, +\& int *outl); +\& +\& int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding); +\& int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen); +\& int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr); +\& int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a); +\& +\& const EVP_CIPHER *EVP_get_cipherbyname(const char *name); +\& #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a)) +\& #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a)) +\& +\& #define EVP_CIPHER_nid(e) ((e)\->nid) +\& #define EVP_CIPHER_block_size(e) ((e)\->block_size) +\& #define EVP_CIPHER_key_length(e) ((e)\->key_len) +\& #define EVP_CIPHER_iv_length(e) ((e)\->iv_len) +\& #define EVP_CIPHER_flags(e) ((e)\->flags) +\& #define EVP_CIPHER_mode(e) ((e)\->flags) & EVP_CIPH_MODE) +\& int EVP_CIPHER_type(const EVP_CIPHER *ctx); +\& +\& #define EVP_CIPHER_CTX_cipher(e) ((e)\->cipher) +\& #define EVP_CIPHER_CTX_nid(e) ((e)\->cipher\->nid) +\& #define EVP_CIPHER_CTX_block_size(e) ((e)\->cipher\->block_size) +\& #define EVP_CIPHER_CTX_key_length(e) ((e)\->key_len) +\& #define EVP_CIPHER_CTX_iv_length(e) ((e)\->cipher\->iv_len) +\& #define EVP_CIPHER_CTX_get_app_data(e) ((e)\->app_data) +\& #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)\->app_data=(char *)(d)) +\& #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c)) +\& #define EVP_CIPHER_CTX_flags(e) ((e)\->cipher\->flags) +\& #define EVP_CIPHER_CTX_mode(e) ((e)\->cipher\->flags & EVP_CIPH_MODE) +\& +\& int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); +\& int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1EVP\s0 cipher routines are a high level interface to certain +symmetric ciphers. +.PP +\&\fIEVP_CIPHER_CTX_init()\fR initializes cipher contex \fBctx\fR. +.PP +\&\fIEVP_EncryptInit_ex()\fR sets up cipher context \fBctx\fR for encryption +with cipher \fBtype\fR from \s-1ENGINE \s0\fBimpl\fR. \fBctx\fR must be initialized +before calling this function. \fBtype\fR is normally supplied +by a function such as \fIEVP_aes_256_cbc()\fR. If \fBimpl\fR is \s-1NULL\s0 then the +default implementation is used. \fBkey\fR is the symmetric key to use +and \fBiv\fR is the \s-1IV\s0 to use (if necessary), the actual number of bytes +used for the key and \s-1IV\s0 depends on the cipher. It is possible to set +all parameters to \s-1NULL\s0 except \fBtype\fR in an initial call and supply +the remaining parameters in subsequent calls, all of which have \fBtype\fR +set to \s-1NULL.\s0 This is done when the default cipher parameters are not +appropriate. +.PP +\&\fIEVP_EncryptUpdate()\fR encrypts \fBinl\fR bytes from the buffer \fBin\fR and +writes the encrypted version to \fBout\fR. 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 \fBout\fR should contain sufficient +room. The actual number of bytes written is placed in \fBoutl\fR. +.PP +If padding is enabled (the default) then \fIEVP_EncryptFinal_ex()\fR encrypts +the \*(L"final\*(R" data, that is any data that remains in a partial block. +It uses standard block padding (aka \s-1PKCS\s0 padding). The encrypted +final data is written to \fBout\fR which should have sufficient space for +one cipher block. The number of bytes written is placed in \fBoutl\fR. After +this function is called the encryption operation is finished and no further +calls to \fIEVP_EncryptUpdate()\fR should be made. +.PP +If padding is disabled then \fIEVP_EncryptFinal_ex()\fR 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 +\&\fIEVP_DecryptInit_ex()\fR, \fIEVP_DecryptUpdate()\fR and \fIEVP_DecryptFinal_ex()\fR are the +corresponding decryption operations. \fIEVP_DecryptFinal()\fR 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 \fBout\fR +passed to \fIEVP_DecryptUpdate()\fR should have sufficient room for +(\fBinl\fR + cipher_block_size) bytes unless the cipher block size is 1 in +which case \fBinl\fR bytes is sufficient. +.PP +\&\fIEVP_CipherInit_ex()\fR, \fIEVP_CipherUpdate()\fR and \fIEVP_CipherFinal_ex()\fR are +functions that can be used for decryption or encryption. The operation +performed depends on the value of the \fBenc\fR 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). +.PP +\&\fIEVP_CIPHER_CTX_cleanup()\fR 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 +\&\fIEVP_EncryptInit()\fR, \fIEVP_DecryptInit()\fR and \fIEVP_CipherInit()\fR behave in a +similar way to \fIEVP_EncryptInit_ex()\fR, EVP_DecryptInit_ex and +\&\fIEVP_CipherInit_ex()\fR except the \fBctx\fR parameter does not need to be +initialized and they always use the default cipher implementation. +.PP +\&\fIEVP_EncryptFinal()\fR, \fIEVP_DecryptFinal()\fR and \fIEVP_CipherFinal()\fR behave in a +similar way to \fIEVP_EncryptFinal_ex()\fR, \fIEVP_DecryptFinal_ex()\fR and +\&\fIEVP_CipherFinal_ex()\fR except \fBctx\fR is automatically cleaned up +after the call. +.PP +\&\fIEVP_get_cipherbyname()\fR, \fIEVP_get_cipherbynid()\fR and \fIEVP_get_cipherbyobj()\fR +return an \s-1EVP_CIPHER\s0 structure when passed a cipher name, a \s-1NID\s0 or an +\&\s-1ASN1_OBJECT\s0 structure. +.PP +\&\fIEVP_CIPHER_nid()\fR and \fIEVP_CIPHER_CTX_nid()\fR return the \s-1NID\s0 of a cipher when +passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR structure. The actual \s-1NID\s0 +value is an internal value which may not have a corresponding \s-1OBJECT +IDENTIFIER.\s0 +.PP +\&\fIEVP_CIPHER_CTX_set_padding()\fR 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 \fBpad\fR 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 +\&\fIEVP_CIPHER_key_length()\fR and \fIEVP_CIPHER_CTX_key_length()\fR return the key +length of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR +structure. The constant \fB\s-1EVP_MAX_KEY_LENGTH\s0\fR is the maximum key length +for all ciphers. Note: although \fIEVP_CIPHER_key_length()\fR is fixed for a +given cipher, the value of \fIEVP_CIPHER_CTX_key_length()\fR may be different +for variable key length ciphers. +.PP +\&\fIEVP_CIPHER_CTX_set_key_length()\fR 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 +\&\fIEVP_CIPHER_iv_length()\fR and \fIEVP_CIPHER_CTX_iv_length()\fR return the \s-1IV\s0 +length of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR. +It will return zero if the cipher does not use an \s-1IV. \s0 The constant +\&\fB\s-1EVP_MAX_IV_LENGTH\s0\fR is the maximum \s-1IV\s0 length for all ciphers. +.PP +\&\fIEVP_CIPHER_block_size()\fR and \fIEVP_CIPHER_CTX_block_size()\fR return the block +size of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR +structure. The constant \fB\s-1EVP_MAX_IV_LENGTH\s0\fR is also the maximum block +length for all ciphers. +.PP +\&\fIEVP_CIPHER_type()\fR and \fIEVP_CIPHER_CTX_type()\fR return the type of the passed +cipher or context. This \*(L"type\*(R" is the actual \s-1NID\s0 of the cipher \s-1OBJECT +IDENTIFIER\s0 as such it ignores the cipher parameters and 40 bit \s-1RC2\s0 and +128 bit \s-1RC2\s0 have the same \s-1NID.\s0 If the cipher does not have an object +identifier or does not have \s-1ASN1\s0 support this function will return +\&\fBNID_undef\fR. +.PP +\&\fIEVP_CIPHER_CTX_cipher()\fR returns the \fB\s-1EVP_CIPHER\s0\fR structure when passed +an \fB\s-1EVP_CIPHER_CTX\s0\fR structure. +.PP +\&\fIEVP_CIPHER_mode()\fR and \fIEVP_CIPHER_CTX_mode()\fR return the block cipher mode: +\&\s-1EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE\s0 or +\&\s-1EVP_CIPH_OFB_MODE.\s0 If the cipher is a stream cipher then +\&\s-1EVP_CIPH_STREAM_CIPHER\s0 is returned. +.PP +\&\fIEVP_CIPHER_param_to_asn1()\fR sets the AlgorithmIdentifier \*(L"parameter\*(R" based +on the passed cipher. This will typically include any parameters and an +\&\s-1IV.\s0 The cipher \s-1IV \s0(if any) must be set when this call is made. This call +should be made before the cipher is actually \*(L"used\*(R" (before any +\&\fIEVP_EncryptUpdate()\fR, \fIEVP_DecryptUpdate()\fR calls for example). This function +may fail if the cipher does not have any \s-1ASN1\s0 support. +.PP +\&\fIEVP_CIPHER_asn1_to_param()\fR sets the cipher parameters based on an \s-1ASN1\s0 +AlgorithmIdentifier \*(L"parameter\*(R". The precise effect depends on the cipher +In the case of \s-1RC2,\s0 for example, it will set the \s-1IV\s0 and effective key length. +This function should be called after the base cipher type is set but before +the key is set. For example \fIEVP_CipherInit()\fR will be called with the \s-1IV\s0 and +key set to \s-1NULL,\s0 \fIEVP_CIPHER_asn1_to_param()\fR will be called and finally +\&\fIEVP_CipherInit()\fR again with all parameters except the key set to \s-1NULL.\s0 It is +possible for this function to fail if the cipher does not have any \s-1ASN1\s0 support +or the parameters cannot be set (for example the \s-1RC2\s0 effective key length +is not supported. +.PP +\&\fIEVP_CIPHER_CTX_ctrl()\fR allows various cipher specific parameters to be determined +and set. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fIEVP_EncryptInit_ex()\fR, \fIEVP_EncryptUpdate()\fR and \fIEVP_EncryptFinal_ex()\fR +return 1 for success and 0 for failure. +.PP +\&\fIEVP_DecryptInit_ex()\fR and \fIEVP_DecryptUpdate()\fR return 1 for success and 0 for failure. +\&\fIEVP_DecryptFinal_ex()\fR returns 0 if the decrypt failed or 1 for success. +.PP +\&\fIEVP_CipherInit_ex()\fR and \fIEVP_CipherUpdate()\fR return 1 for success and 0 for failure. +\&\fIEVP_CipherFinal_ex()\fR returns 0 for a decryption failure or 1 for success. +.PP +\&\fIEVP_CIPHER_CTX_cleanup()\fR returns 1 for success and 0 for failure. +.PP +\&\fIEVP_get_cipherbyname()\fR, \fIEVP_get_cipherbynid()\fR and \fIEVP_get_cipherbyobj()\fR +return an \fB\s-1EVP_CIPHER\s0\fR structure or \s-1NULL\s0 on error. +.PP +\&\fIEVP_CIPHER_nid()\fR and \fIEVP_CIPHER_CTX_nid()\fR return a \s-1NID.\s0 +.PP +\&\fIEVP_CIPHER_block_size()\fR and \fIEVP_CIPHER_CTX_block_size()\fR return the block +size. +.PP +\&\fIEVP_CIPHER_key_length()\fR and \fIEVP_CIPHER_CTX_key_length()\fR return the key +length. +.PP +\&\fIEVP_CIPHER_CTX_set_padding()\fR always returns 1. +.PP +\&\fIEVP_CIPHER_iv_length()\fR and \fIEVP_CIPHER_CTX_iv_length()\fR return the \s-1IV\s0 +length or zero if the cipher does not use an \s-1IV.\s0 +.PP +\&\fIEVP_CIPHER_type()\fR and \fIEVP_CIPHER_CTX_type()\fR return the \s-1NID\s0 of the cipher's +\&\s-1OBJECT IDENTIFIER\s0 or NID_undef if it has no defined \s-1OBJECT IDENTIFIER.\s0 +.PP +\&\fIEVP_CIPHER_CTX_cipher()\fR returns an \fB\s-1EVP_CIPHER\s0\fR structure. +.PP +\&\fIEVP_CIPHER_param_to_asn1()\fR and \fIEVP_CIPHER_asn1_to_param()\fR return 1 for +success or zero for failure. +.SH "CIPHER LISTING" +.IX Header "CIPHER LISTING" +All algorithms have a fixed key length unless otherwise stated. +.IP "\fIEVP_enc_null()\fR" 4 +.IX Item "EVP_enc_null()" +Null cipher: does nothing. +.IP "EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void)" 4 +.IX Item "EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void)" +\&\s-1DES\s0 in \s-1CBC, ECB, CFB\s0 and \s-1OFB\s0 modes respectively. +.IP "EVP_des_ede_cbc(void), \fIEVP_des_ede()\fR, EVP_des_ede_ofb(void), EVP_des_ede_cfb(void)" 4 +.IX Item "EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), EVP_des_ede_cfb(void)" +Two key triple \s-1DES\s0 in \s-1CBC, ECB, CFB\s0 and \s-1OFB\s0 modes respectively. +.IP "EVP_des_ede3_cbc(void), \fIEVP_des_ede3()\fR, EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void)" 4 +.IX Item "EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void)" +Three key triple \s-1DES\s0 in \s-1CBC, ECB, CFB\s0 and \s-1OFB\s0 modes respectively. +.IP "EVP_desx_cbc(void)" 4 +.IX Item "EVP_desx_cbc(void)" +\&\s-1DESX\s0 algorithm in \s-1CBC\s0 mode. +.IP "EVP_rc4(void)" 4 +.IX Item "EVP_rc4(void)" +\&\s-1RC4\s0 stream cipher. This is a variable key length cipher with default key length 128 bits. +.IP "EVP_rc4_40(void)" 4 +.IX Item "EVP_rc4_40(void)" +\&\s-1RC4\s0 stream cipher with 40 bit key length. This is obsolete and new code should use \fIEVP_rc4()\fR +and the \fIEVP_CIPHER_CTX_set_key_length()\fR function. +.IP "\fIEVP_idea_cbc()\fR EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void)" 4 +.IX Item "EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void)" +\&\s-1IDEA\s0 encryption algorithm in \s-1CBC, ECB, CFB\s0 and \s-1OFB\s0 modes respectively. +.IP "EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void)" 4 +.IX Item "EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void)" +\&\s-1RC2\s0 encryption algorithm in \s-1CBC, ECB, CFB\s0 and \s-1OFB\s0 modes respectively. This is a variable key +length cipher with an additional parameter called \*(L"effective key bits\*(R" or \*(L"effective key length\*(R". +By default both are set to 128 bits. +.IP "EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void)" 4 +.IX Item "EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void)" +\&\s-1RC2\s0 algorithm in \s-1CBC\s0 mode with a default key length and effective key length of 40 and 64 bits. +These are obsolete and new code should use \fIEVP_rc2_cbc()\fR, \fIEVP_CIPHER_CTX_set_key_length()\fR and +\&\fIEVP_CIPHER_CTX_ctrl()\fR to set the key length and effective key length. +.IP "EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void);" 4 +.IX Item "EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void);" +Blowfish encryption algorithm in \s-1CBC, ECB, CFB\s0 and \s-1OFB\s0 modes respectively. This is a variable key +length cipher. +.IP "EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void)" 4 +.IX Item "EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void)" +\&\s-1CAST\s0 encryption algorithm in \s-1CBC, ECB, CFB\s0 and \s-1OFB\s0 modes respectively. This is a variable key +length cipher. +.IP "EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void)" 4 +.IX Item "EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void)" +\&\s-1RC5\s0 encryption algorithm in \s-1CBC, ECB, CFB\s0 and \s-1OFB\s0 modes respectively. This is a variable key length +cipher with an additional \*(L"number of rounds\*(R" parameter. By default the key length is set to 128 +bits and 12 rounds. +.IP "EVP_aes_128_gcm(void), EVP_aes_192_gcm(void), EVP_aes_256_gcm(void)" 4 +.IX Item "EVP_aes_128_gcm(void), EVP_aes_192_gcm(void), EVP_aes_256_gcm(void)" +\&\s-1AES\s0 Galois Counter Mode (\s-1GCM\s0) for 128, 192 and 256 bit keys respectively. +These ciphers require additional control operations to function correctly: see +\&\*(L"\s-1GCM\s0 mode\*(R" section below for details. +.IP "EVP_aes_128_ccm(void), EVP_aes_192_ccm(void), EVP_aes_256_ccm(void)" 4 +.IX Item "EVP_aes_128_ccm(void), EVP_aes_192_ccm(void), EVP_aes_256_ccm(void)" +\&\s-1AES\s0 Counter with CBC-MAC Mode (\s-1CCM\s0) for 128, 192 and 256 bit keys respectively. +These ciphers require additional control operations to function correctly: see +\&\s-1CCM\s0 mode section below for details. +.SH "GCM Mode" +.IX Header "GCM Mode" +For \s-1GCM\s0 mode ciphers the behaviour of the \s-1EVP\s0 interface is subtly altered and +several \s-1GCM\s0 specific ctrl operations are supported. +.PP +To specify any additional authenticated data (\s-1AAD\s0) a call to \fIEVP_CipherUpdate()\fR, +\&\fIEVP_EncryptUpdate()\fR or \fIEVP_DecryptUpdate()\fR should be made with the output +parameter \fBout\fR set to \fB\s-1NULL\s0\fR. +.PP +When decrypting the return value of \fIEVP_DecryptFinal()\fR or \fIEVP_CipherFinal()\fR +indicates if the operation was successful. If it does not indicate success +the authentication operation has failed and any output data \fB\s-1MUST NOT\s0\fR +be used as it is corrupted. +.PP +The following ctrls are supported in \s-1GCM\s0 mode: +.PP +.Vb 1 +\& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, ivlen, NULL); +.Ve +.PP +Sets the \s-1GCM IV\s0 length: this call can only be made before specifying an \s-1IV.\s0 If +not called a default \s-1IV\s0 length is used (96 bits for \s-1AES\s0). +.PP +.Vb 1 +\& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, taglen, tag); +.Ve +.PP +Writes \fBtaglen\fR bytes of the tag value to the buffer indicated by \fBtag\fR. +This call can only be made when encrypting data and \fBafter\fR all data has been +processed (e.g. after an \fIEVP_EncryptFinal()\fR call). +.PP +.Vb 1 +\& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, taglen, tag); +.Ve +.PP +Sets the expected tag to \fBtaglen\fR bytes from \fBtag\fR. This call is only legal +when decrypting data and must be made \fBbefore\fR any data is processed (e.g. +before any \fIEVP_DecryptUpdate()\fR call). +.PP +See \s-1EXAMPLES\s0 below for an example of the use of \s-1GCM\s0 mode. +.SH "CCM Mode" +.IX Header "CCM Mode" +The behaviour of \s-1CCM\s0 mode ciphers is similar to \s-1CCM\s0 mode but with a few +additional requirements and different ctrl values. +.PP +Like \s-1GCM\s0 mode any additional authenticated data (\s-1AAD\s0) is passed by calling +\&\fIEVP_CipherUpdate()\fR, \fIEVP_EncryptUpdate()\fR or \fIEVP_DecryptUpdate()\fR with the output +parameter \fBout\fR set to \fB\s-1NULL\s0\fR. Additionally the total plaintext or ciphertext +length \fB\s-1MUST\s0\fR be passed to \fIEVP_CipherUpdate()\fR, \fIEVP_EncryptUpdate()\fR or +\&\fIEVP_DecryptUpdate()\fR with the output and input parameters (\fBin\fR and \fBout\fR) +set to \fB\s-1NULL\s0\fR and the length passed in the \fBinl\fR parameter. +.PP +The following ctrls are supported in \s-1CCM\s0 mode: +.PP +.Vb 1 +\& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, taglen, tag); +.Ve +.PP +This call is made to set the expected \fB\s-1CCM\s0\fR tag value when decrypting or +the length of the tag (with the \fBtag\fR parameter set to \s-1NULL\s0) when encrypting. +The tag length is often referred to as \fBM\fR. If not set a default value is +used (12 for \s-1AES\s0). +.PP +.Vb 1 +\& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL); +.Ve +.PP +Sets the \s-1CCM \s0\fBL\fR value. If not set a default is used (8 for \s-1AES\s0). +.PP +.Vb 1 +\& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, ivlen, NULL); +.Ve +.PP +Sets the \s-1CCM\s0 nonce (\s-1IV\s0) length: this call can only be made before specifying +an nonce value. The nonce length is given by \fB15 \- L\fR so it is 7 by default +for \s-1AES.\s0 +.SH "NOTES" +.IX Header "NOTES" +Where possible the \fB\s-1EVP\s0\fR 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. Additionally, the +\&\fB\s-1EVP\s0\fR interface will ensure the use of platform specific cryptographic +acceleration such as AES-NI (the low level interfaces do not provide the +guarantee). +.PP +\&\s-1PKCS\s0 padding works by adding \fBn\fR padding bytes of value \fBn\fR 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 \fBn\fR 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 \fIEVP_EncryptInit()\fR, \fIEVP_EncryptFinal()\fR, \fIEVP_DecryptInit()\fR, +\&\fIEVP_CipherInit()\fR and \fIEVP_CipherFinal()\fR are obsolete but are retained for +compatibility with existing code. New code should use \fIEVP_EncryptInit_ex()\fR, +\&\fIEVP_EncryptFinal_ex()\fR, \fIEVP_DecryptInit_ex()\fR, \fIEVP_DecryptFinal_ex()\fR, +\&\fIEVP_CipherInit_ex()\fR and \fIEVP_CipherFinal_ex()\fR because they can reuse an +existing context without allocating and freeing it up on each call. +.SH "BUGS" +.IX Header "BUGS" +For \s-1RC5\s0 the number of rounds can currently only be set to 8, 12 or 16. This is +a limitation of the current \s-1RC5\s0 code rather than the \s-1EVP\s0 interface. +.PP +\&\s-1EVP_MAX_KEY_LENGTH\s0 and \s-1EVP_MAX_IV_LENGTH\s0 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 \s-1EVP_MAX_KEY_LENGTH\s0 bytes. +.PP +The \s-1ASN1\s0 code is incomplete (and sometimes inaccurate) it has only been tested +for certain common S/MIME ciphers (\s-1RC2, DES,\s0 triple \s-1DES\s0) in \s-1CBC\s0 mode. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +Encrypt a string using \s-1IDEA:\s0 +.PP +.Vb 12 +\& int do_crypt(char *outfile) +\& { +\& unsigned char outbuf[1024]; +\& int outlen, tmplen; +\& /* Bogus key and IV: we\*(Aqd 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}; +\& char intext[] = "Some Crypto Text"; +\& EVP_CIPHER_CTX ctx; +\& FILE *out; +\& +\& EVP_CIPHER_CTX_init(&ctx); +\& EVP_EncryptInit_ex(&ctx, EVP_idea_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 wont be null terminated and may contain embedded +\& * nulls. +\& */ +\& out = fopen(outfile, "wb"); +\& fwrite(outbuf, 1, outlen, out); +\& fclose(out); +\& return 1; +\& } +.Ve +.PP +The ciphertext from the above example can be decrypted using the \fBopenssl\fR +utility with the command line (shown on two lines for clarity): +.PP +.Vb 2 +\& openssl idea \-d <filename +\& \-K 000102030405060708090A0B0C0D0E0F \-iv 0102030405060708 +.Ve +.PP +General encryption and decryption function example using \s-1FILE I/O\s0 and \s-1AES128\s0 +with a 128\-bit key: +.PP +.Vb 11 +\& int do_crypt(FILE *in, FILE *out, int do_encrypt) +\& { +\& /* Allow enough space in output buffer for additional block */ +\& unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; +\& int inlen, outlen; +\& EVP_CIPHER_CTX ctx; +\& /* Bogus key and IV: we\*(Aqd normally set these from +\& * another source. +\& */ +\& unsigned char key[] = "0123456789abcdeF"; +\& unsigned char iv[] = "1234567887654321"; +\& +\& /* Don\*(Aqt set key or IV right away; we want to check lengths */ +\& EVP_CIPHER_CTX_init(&ctx); +\& EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, +\& do_encrypt); +\& 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); +\& +\& 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; +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIevp\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fIEVP_CIPHER_CTX_init()\fR, \fIEVP_EncryptInit_ex()\fR, \fIEVP_EncryptFinal_ex()\fR, +\&\fIEVP_DecryptInit_ex()\fR, \fIEVP_DecryptFinal_ex()\fR, \fIEVP_CipherInit_ex()\fR, +\&\fIEVP_CipherFinal_ex()\fR and \fIEVP_CIPHER_CTX_set_padding()\fR appeared in +OpenSSL 0.9.7. +.PP +\&\s-1IDEA\s0 appeared in OpenSSL 0.9.7 but was often disabled due to +patent concerns; the last patents expired in 2012. |
