diff options
Diffstat (limited to 'secure/lib/libcrypto/man/EVP_EncryptInit.3')
| -rw-r--r-- | secure/lib/libcrypto/man/EVP_EncryptInit.3 | 644 |
1 files changed, 0 insertions, 644 deletions
diff --git a/secure/lib/libcrypto/man/EVP_EncryptInit.3 b/secure/lib/libcrypto/man/EVP_EncryptInit.3 deleted file mode 100644 index 7b1e9ba394da..000000000000 --- a/secure/lib/libcrypto/man/EVP_EncryptInit.3 +++ /dev/null @@ -1,644 +0,0 @@ -.\" Automatically generated by Pod::Man version 1.15 -.\" Wed Feb 19 16:42:53 2003 -.\" -.\" Standard preamble: -.\" ====================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Ip \" List item -.br -.ie \\n(.$>=3 .ne \\$3 -.el .ne 3 -.IP "\\$1" \\$2 -.. -.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. | will give a -.\" real vertical bar. \*(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-|\(bv\*(Tr -.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" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr -.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and -.\" index entries marked with X<> in POD. Of course, you'll have to process -.\" the output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it -.\" makes way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -.bd B 3 -. \" 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 "0.9.7a" "2003-02-19" "OpenSSL" -.UC -.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 \- \s-1EVP\s0 cipher routines -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <openssl/evp.h> -.Ve -.Vb 1 -\& int EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a); -.Ve -.Vb 6 -\& 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); -.Ve -.Vb 6 -\& 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); -.Ve -.Vb 6 -\& 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); -.Ve -.Vb 4 -\& 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); -.Ve -.Vb 4 -\& 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); -.Ve -.Vb 4 -\& 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); -.Ve -.Vb 4 -\& 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); -.Ve -.Vb 3 -\& 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)) -.Ve -.Vb 7 -\& #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); -.Ve -.Vb 10 -\& #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) -.Ve -.Vb 2 -\& 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_des_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 \fBoutl\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 paramter 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\s0 -\&\s-1IDENTIFIER\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\s0 -\&\s-1IDENTIFIER\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\s0, \s-1EVP_CIPH_CBC_MODE\s0, \s-1EVP_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. Currently only the \s-1RC2\s0 effective key length and the number of rounds of -\&\s-1RC5\s0 can be set. -.SH "RETURN VALUES" -.IX Header "RETURN VALUES" -EVP_CIPHER_CTX_init, \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\s0 \s-1IDENTIFIER\s0 or NID_undef if it has no defined \s-1OBJECT\s0 \s-1IDENTIFIER\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\s0, \s-1ECB\s0, \s-1CFB\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\s0, \s-1ECB\s0, \s-1CFB\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\s0, \s-1ECB\s0, \s-1CFB\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), EVP_idea_cbc(void)" 4 -.IX Item "EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void)" -\&\s-1IDEA\s0 encryption algorithm in \s-1CBC\s0, \s-1ECB\s0, \s-1CFB\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\s0, \s-1ECB\s0, \s-1CFB\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\s0, \s-1ECB\s0, \s-1CFB\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\s0, \s-1ECB\s0, \s-1CFB\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\s0, \s-1ECB\s0, \s-1CFB\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. -.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. -.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\s0, \s-1DES\s0, triple \s-1DES\s0) in \s-1CBC\s0 mode. -.SH "EXAMPLES" -.IX Header "EXAMPLES" -Get the number of rounds used in \s-1RC5:\s0 -.PP -.Vb 2 -\& int nrounds; -\& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds); -.Ve -Get the \s-1RC2\s0 effective key length: -.PP -.Vb 2 -\& int key_bits; -\& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits); -.Ve -Set the number of rounds used in \s-1RC5:\s0 -.PP -.Vb 2 -\& int nrounds; -\& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL); -.Ve -Set the effective key length used in \s-1RC2:\s0 -.PP -.Vb 2 -\& int key_bits; -\& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL); -.Ve -Encrypt a string using blowfish: -.PP -.Vb 14 -\& 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}; -\& 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); -.Ve -.Vb 25 -\& 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 -The ciphertext from the above example can be decrypted using the \fBopenssl\fR -utility with the command line: -.PP -.Vb 1 -\& S<openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -d> -.Ve -General encryption, decryption function example using \s-1FILE\s0 I/O and \s-1RC2\s0 with an -80 bit key: -.PP -.Vb 16 -\& 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); -.Ve -.Vb 17 -\& for(;;) -\& { -\& inlen = fread(inbuf, 1, 1024, in); -\& if(inlen <= 0) break; -\& if(!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, inlen)) -\& { -\& /* Error */ -\& return 0; -\& } -\& fwrite(outbuf, 1, outlen, out); -\& } -\& if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen)) -\& { -\& /* Error */ -\& return 0; -\& } -\& fwrite(outbuf, 1, outlen, out); -.Ve -.Vb 3 -\& EVP_CIPHER_CTX_cleanup(&ctx); -\& return 1; -\& } -.Ve -.SH "SEE ALSO" -.IX Header "SEE ALSO" -evp(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. |