| 1 | .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20) |
| 2 | .\" |
| 3 | .\" Standard preamble: |
| 4 | .\" ======================================================================== |
| 5 | .de Sp \" Vertical space (when we can't use .PP) |
| 6 | .if t .sp .5v |
| 7 | .if n .sp |
| 8 | .. |
| 9 | .de Vb \" Begin verbatim text |
| 10 | .ft CW |
| 11 | .nf |
| 12 | .ne \\$1 |
| 13 | .. |
| 14 | .de Ve \" End verbatim text |
| 15 | .ft R |
| 16 | .fi |
| 17 | .. |
| 18 | .\" Set up some character translations and predefined strings. \*(-- will |
| 19 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
| 20 | .\" double quote, and \*(R" will give a right double quote. \*(C+ will |
| 21 | .\" give a nicer C++. Capital omega is used to do unbreakable dashes and |
| 22 | .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, |
| 23 | .\" nothing in troff, for use with C<>. |
| 24 | .tr \(*W- |
| 25 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
| 26 | .ie n \{\ |
| 27 | . ds -- \(*W- |
| 28 | . ds PI pi |
| 29 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
| 30 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
| 31 | . ds L" "" |
| 32 | . ds R" "" |
| 33 | . ds C` "" |
| 34 | . ds C' "" |
| 35 | 'br\} |
| 36 | .el\{\ |
| 37 | . ds -- \|\(em\| |
| 38 | . ds PI \(*p |
| 39 | . ds L" `` |
| 40 | . ds R" '' |
| 41 | 'br\} |
| 42 | .\" |
| 43 | .\" Escape single quotes in literal strings from groff's Unicode transform. |
| 44 | .ie \n(.g .ds Aq \(aq |
| 45 | .el .ds Aq ' |
| 46 | .\" |
| 47 | .\" If the F register is turned on, we'll generate index entries on stderr for |
| 48 | .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 49 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
| 50 | .\" output yourself in some meaningful fashion. |
| 51 | .ie \nF \{\ |
| 52 | . de IX |
| 53 | . tm Index:\\$1\t\\n%\t"\\$2" |
| 54 | .. |
| 55 | . nr % 0 |
| 56 | . rr F |
| 57 | .\} |
| 58 | .el \{\ |
| 59 | . de IX |
| 60 | .. |
| 61 | .\} |
| 62 | .\" |
| 63 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
| 64 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
| 65 | . \" fudge factors for nroff and troff |
| 66 | .if n \{\ |
| 67 | . ds #H 0 |
| 68 | . ds #V .8m |
| 69 | . ds #F .3m |
| 70 | . ds #[ \f1 |
| 71 | . ds #] \fP |
| 72 | .\} |
| 73 | .if t \{\ |
| 74 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
| 75 | . ds #V .6m |
| 76 | . ds #F 0 |
| 77 | . ds #[ \& |
| 78 | . ds #] \& |
| 79 | .\} |
| 80 | . \" simple accents for nroff and troff |
| 81 | .if n \{\ |
| 82 | . ds ' \& |
| 83 | . ds ` \& |
| 84 | . ds ^ \& |
| 85 | . ds , \& |
| 86 | . ds ~ ~ |
| 87 | . ds / |
| 88 | .\} |
| 89 | .if t \{\ |
| 90 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
| 91 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
| 92 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
| 93 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
| 94 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
| 95 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
| 96 | .\} |
| 97 | . \" troff and (daisy-wheel) nroff accents |
| 98 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
| 99 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
| 100 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
| 101 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
| 102 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
| 103 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
| 104 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
| 105 | .ds ae a\h'-(\w'a'u*4/10)'e |
| 106 | .ds Ae A\h'-(\w'A'u*4/10)'E |
| 107 | . \" corrections for vroff |
| 108 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
| 109 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
| 110 | . \" for low resolution devices (crt and lpr) |
| 111 | .if \n(.H>23 .if \n(.V>19 \ |
| 112 | \{\ |
| 113 | . ds : e |
| 114 | . ds 8 ss |
| 115 | . ds o a |
| 116 | . ds d- d\h'-1'\(ga |
| 117 | . ds D- D\h'-1'\(hy |
| 118 | . ds th \o'bp' |
| 119 | . ds Th \o'LP' |
| 120 | . ds ae ae |
| 121 | . ds Ae AE |
| 122 | .\} |
| 123 | .rm #[ #] #H #V #F C |
| 124 | .\" ======================================================================== |
| 125 | .\" |
| 126 | .IX Title "EVP_EncryptInit 3" |
| 127 | .TH EVP_EncryptInit 3 "2014-06-05" "1.0.1h" "OpenSSL" |
| 128 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 129 | .\" way too many mistakes in technical documents. |
| 130 | .if n .ad l |
| 131 | .nh |
| 132 | .SH "NAME" |
| 133 | EVP_CIPHER_CTX_init, EVP_EncryptInit_ex, EVP_EncryptUpdate, |
| 134 | EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptUpdate, |
| 135 | EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherUpdate, |
| 136 | EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length, |
| 137 | EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_cleanup, EVP_EncryptInit, |
| 138 | EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal, |
| 139 | EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname, |
| 140 | EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid, |
| 141 | EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length, |
| 142 | EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, |
| 143 | EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, |
| 144 | EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data, |
| 145 | EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags, |
| 146 | EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param, |
| 147 | EVP_CIPHER_CTX_set_padding \- EVP cipher routines |
| 148 | .SH "SYNOPSIS" |
| 149 | .IX Header "SYNOPSIS" |
| 150 | .Vb 1 |
| 151 | \& #include <openssl/evp.h> |
| 152 | \& |
| 153 | \& void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a); |
| 154 | \& |
| 155 | \& int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 156 | \& ENGINE *impl, unsigned char *key, unsigned char *iv); |
| 157 | \& int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, |
| 158 | \& int *outl, unsigned char *in, int inl); |
| 159 | \& int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, |
| 160 | \& int *outl); |
| 161 | \& |
| 162 | \& int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 163 | \& ENGINE *impl, unsigned char *key, unsigned char *iv); |
| 164 | \& int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, |
| 165 | \& int *outl, unsigned char *in, int inl); |
| 166 | \& int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, |
| 167 | \& int *outl); |
| 168 | \& |
| 169 | \& int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 170 | \& ENGINE *impl, unsigned char *key, unsigned char *iv, int enc); |
| 171 | \& int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, |
| 172 | \& int *outl, unsigned char *in, int inl); |
| 173 | \& int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, |
| 174 | \& int *outl); |
| 175 | \& |
| 176 | \& int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 177 | \& unsigned char *key, unsigned char *iv); |
| 178 | \& int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, |
| 179 | \& int *outl); |
| 180 | \& |
| 181 | \& int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 182 | \& unsigned char *key, unsigned char *iv); |
| 183 | \& int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, |
| 184 | \& int *outl); |
| 185 | \& |
| 186 | \& int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 187 | \& unsigned char *key, unsigned char *iv, int enc); |
| 188 | \& int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, |
| 189 | \& int *outl); |
| 190 | \& |
| 191 | \& int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding); |
| 192 | \& int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen); |
| 193 | \& int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr); |
| 194 | \& int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a); |
| 195 | \& |
| 196 | \& const EVP_CIPHER *EVP_get_cipherbyname(const char *name); |
| 197 | \& #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a)) |
| 198 | \& #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a)) |
| 199 | \& |
| 200 | \& #define EVP_CIPHER_nid(e) ((e)\->nid) |
| 201 | \& #define EVP_CIPHER_block_size(e) ((e)\->block_size) |
| 202 | \& #define EVP_CIPHER_key_length(e) ((e)\->key_len) |
| 203 | \& #define EVP_CIPHER_iv_length(e) ((e)\->iv_len) |
| 204 | \& #define EVP_CIPHER_flags(e) ((e)\->flags) |
| 205 | \& #define EVP_CIPHER_mode(e) ((e)\->flags) & EVP_CIPH_MODE) |
| 206 | \& int EVP_CIPHER_type(const EVP_CIPHER *ctx); |
| 207 | \& |
| 208 | \& #define EVP_CIPHER_CTX_cipher(e) ((e)\->cipher) |
| 209 | \& #define EVP_CIPHER_CTX_nid(e) ((e)\->cipher\->nid) |
| 210 | \& #define EVP_CIPHER_CTX_block_size(e) ((e)\->cipher\->block_size) |
| 211 | \& #define EVP_CIPHER_CTX_key_length(e) ((e)\->key_len) |
| 212 | \& #define EVP_CIPHER_CTX_iv_length(e) ((e)\->cipher\->iv_len) |
| 213 | \& #define EVP_CIPHER_CTX_get_app_data(e) ((e)\->app_data) |
| 214 | \& #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)\->app_data=(char *)(d)) |
| 215 | \& #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c)) |
| 216 | \& #define EVP_CIPHER_CTX_flags(e) ((e)\->cipher\->flags) |
| 217 | \& #define EVP_CIPHER_CTX_mode(e) ((e)\->cipher\->flags & EVP_CIPH_MODE) |
| 218 | \& |
| 219 | \& int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); |
| 220 | \& int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); |
| 221 | .Ve |
| 222 | .SH "DESCRIPTION" |
| 223 | .IX Header "DESCRIPTION" |
| 224 | The \s-1EVP\s0 cipher routines are a high level interface to certain |
| 225 | symmetric ciphers. |
| 226 | .PP |
| 227 | \&\fIEVP_CIPHER_CTX_init()\fR initializes cipher contex \fBctx\fR. |
| 228 | .PP |
| 229 | \&\fIEVP_EncryptInit_ex()\fR sets up cipher context \fBctx\fR for encryption |
| 230 | with cipher \fBtype\fR from \s-1ENGINE\s0 \fBimpl\fR. \fBctx\fR must be initialized |
| 231 | before calling this function. \fBtype\fR is normally supplied |
| 232 | by a function such as \fIEVP_des_cbc()\fR. If \fBimpl\fR is \s-1NULL\s0 then the |
| 233 | default implementation is used. \fBkey\fR is the symmetric key to use |
| 234 | and \fBiv\fR is the \s-1IV\s0 to use (if necessary), the actual number of bytes |
| 235 | used for the key and \s-1IV\s0 depends on the cipher. It is possible to set |
| 236 | all parameters to \s-1NULL\s0 except \fBtype\fR in an initial call and supply |
| 237 | the remaining parameters in subsequent calls, all of which have \fBtype\fR |
| 238 | set to \s-1NULL\s0. This is done when the default cipher parameters are not |
| 239 | appropriate. |
| 240 | .PP |
| 241 | \&\fIEVP_EncryptUpdate()\fR encrypts \fBinl\fR bytes from the buffer \fBin\fR and |
| 242 | writes the encrypted version to \fBout\fR. This function can be called |
| 243 | multiple times to encrypt successive blocks of data. The amount |
| 244 | of data written depends on the block alignment of the encrypted data: |
| 245 | as a result the amount of data written may be anything from zero bytes |
| 246 | to (inl + cipher_block_size \- 1) so \fBoutl\fR should contain sufficient |
| 247 | room. The actual number of bytes written is placed in \fBoutl\fR. |
| 248 | .PP |
| 249 | If padding is enabled (the default) then \fIEVP_EncryptFinal_ex()\fR encrypts |
| 250 | the \*(L"final\*(R" data, that is any data that remains in a partial block. |
| 251 | It uses standard block padding (aka \s-1PKCS\s0 padding). The encrypted |
| 252 | final data is written to \fBout\fR which should have sufficient space for |
| 253 | one cipher block. The number of bytes written is placed in \fBoutl\fR. After |
| 254 | this function is called the encryption operation is finished and no further |
| 255 | calls to \fIEVP_EncryptUpdate()\fR should be made. |
| 256 | .PP |
| 257 | If padding is disabled then \fIEVP_EncryptFinal_ex()\fR will not encrypt any more |
| 258 | data and it will return an error if any data remains in a partial block: |
| 259 | that is if the total data length is not a multiple of the block size. |
| 260 | .PP |
| 261 | \&\fIEVP_DecryptInit_ex()\fR, \fIEVP_DecryptUpdate()\fR and \fIEVP_DecryptFinal_ex()\fR are the |
| 262 | corresponding decryption operations. \fIEVP_DecryptFinal()\fR will return an |
| 263 | error code if padding is enabled and the final block is not correctly |
| 264 | formatted. The parameters and restrictions are identical to the encryption |
| 265 | operations except that if padding is enabled the decrypted data buffer \fBout\fR |
| 266 | passed to \fIEVP_DecryptUpdate()\fR should have sufficient room for |
| 267 | (\fBinl\fR + cipher_block_size) bytes unless the cipher block size is 1 in |
| 268 | which case \fBinl\fR bytes is sufficient. |
| 269 | .PP |
| 270 | \&\fIEVP_CipherInit_ex()\fR, \fIEVP_CipherUpdate()\fR and \fIEVP_CipherFinal_ex()\fR are |
| 271 | functions that can be used for decryption or encryption. The operation |
| 272 | performed depends on the value of the \fBenc\fR parameter. It should be set |
| 273 | to 1 for encryption, 0 for decryption and \-1 to leave the value unchanged |
| 274 | (the actual value of 'enc' being supplied in a previous call). |
| 275 | .PP |
| 276 | \&\fIEVP_CIPHER_CTX_cleanup()\fR clears all information from a cipher context |
| 277 | and free up any allocated memory associate with it. It should be called |
| 278 | after all operations using a cipher are complete so sensitive information |
| 279 | does not remain in memory. |
| 280 | .PP |
| 281 | \&\fIEVP_EncryptInit()\fR, \fIEVP_DecryptInit()\fR and \fIEVP_CipherInit()\fR behave in a |
| 282 | similar way to \fIEVP_EncryptInit_ex()\fR, EVP_DecryptInit_ex and |
| 283 | \&\fIEVP_CipherInit_ex()\fR except the \fBctx\fR parameter does not need to be |
| 284 | initialized and they always use the default cipher implementation. |
| 285 | .PP |
| 286 | \&\fIEVP_EncryptFinal()\fR, \fIEVP_DecryptFinal()\fR and \fIEVP_CipherFinal()\fR behave in a |
| 287 | similar way to \fIEVP_EncryptFinal_ex()\fR, \fIEVP_DecryptFinal_ex()\fR and |
| 288 | \&\fIEVP_CipherFinal_ex()\fR except \fBctx\fR is automatically cleaned up |
| 289 | after the call. |
| 290 | .PP |
| 291 | \&\fIEVP_get_cipherbyname()\fR, \fIEVP_get_cipherbynid()\fR and \fIEVP_get_cipherbyobj()\fR |
| 292 | return an \s-1EVP_CIPHER\s0 structure when passed a cipher name, a \s-1NID\s0 or an |
| 293 | \&\s-1ASN1_OBJECT\s0 structure. |
| 294 | .PP |
| 295 | \&\fIEVP_CIPHER_nid()\fR and \fIEVP_CIPHER_CTX_nid()\fR return the \s-1NID\s0 of a cipher when |
| 296 | passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR structure. The actual \s-1NID\s0 |
| 297 | value is an internal value which may not have a corresponding \s-1OBJECT\s0 |
| 298 | \&\s-1IDENTIFIER\s0. |
| 299 | .PP |
| 300 | \&\fIEVP_CIPHER_CTX_set_padding()\fR enables or disables padding. By default |
| 301 | encryption operations are padded using standard block padding and the |
| 302 | padding is checked and removed when decrypting. If the \fBpad\fR parameter |
| 303 | is zero then no padding is performed, the total amount of data encrypted |
| 304 | or decrypted must then be a multiple of the block size or an error will |
| 305 | occur. |
| 306 | .PP |
| 307 | \&\fIEVP_CIPHER_key_length()\fR and \fIEVP_CIPHER_CTX_key_length()\fR return the key |
| 308 | length of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR |
| 309 | structure. The constant \fB\s-1EVP_MAX_KEY_LENGTH\s0\fR is the maximum key length |
| 310 | for all ciphers. Note: although \fIEVP_CIPHER_key_length()\fR is fixed for a |
| 311 | given cipher, the value of \fIEVP_CIPHER_CTX_key_length()\fR may be different |
| 312 | for variable key length ciphers. |
| 313 | .PP |
| 314 | \&\fIEVP_CIPHER_CTX_set_key_length()\fR sets the key length of the cipher ctx. |
| 315 | If the cipher is a fixed length cipher then attempting to set the key |
| 316 | length to any value other than the fixed value is an error. |
| 317 | .PP |
| 318 | \&\fIEVP_CIPHER_iv_length()\fR and \fIEVP_CIPHER_CTX_iv_length()\fR return the \s-1IV\s0 |
| 319 | length of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR. |
| 320 | It will return zero if the cipher does not use an \s-1IV\s0. The constant |
| 321 | \&\fB\s-1EVP_MAX_IV_LENGTH\s0\fR is the maximum \s-1IV\s0 length for all ciphers. |
| 322 | .PP |
| 323 | \&\fIEVP_CIPHER_block_size()\fR and \fIEVP_CIPHER_CTX_block_size()\fR return the block |
| 324 | size of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR |
| 325 | structure. The constant \fB\s-1EVP_MAX_IV_LENGTH\s0\fR is also the maximum block |
| 326 | length for all ciphers. |
| 327 | .PP |
| 328 | \&\fIEVP_CIPHER_type()\fR and \fIEVP_CIPHER_CTX_type()\fR return the type of the passed |
| 329 | cipher or context. This \*(L"type\*(R" is the actual \s-1NID\s0 of the cipher \s-1OBJECT\s0 |
| 330 | \&\s-1IDENTIFIER\s0 as such it ignores the cipher parameters and 40 bit \s-1RC2\s0 and |
| 331 | 128 bit \s-1RC2\s0 have the same \s-1NID\s0. If the cipher does not have an object |
| 332 | identifier or does not have \s-1ASN1\s0 support this function will return |
| 333 | \&\fBNID_undef\fR. |
| 334 | .PP |
| 335 | \&\fIEVP_CIPHER_CTX_cipher()\fR returns the \fB\s-1EVP_CIPHER\s0\fR structure when passed |
| 336 | an \fB\s-1EVP_CIPHER_CTX\s0\fR structure. |
| 337 | .PP |
| 338 | \&\fIEVP_CIPHER_mode()\fR and \fIEVP_CIPHER_CTX_mode()\fR return the block cipher mode: |
| 339 | \&\s-1EVP_CIPH_ECB_MODE\s0, \s-1EVP_CIPH_CBC_MODE\s0, \s-1EVP_CIPH_CFB_MODE\s0 or |
| 340 | \&\s-1EVP_CIPH_OFB_MODE\s0. If the cipher is a stream cipher then |
| 341 | \&\s-1EVP_CIPH_STREAM_CIPHER\s0 is returned. |
| 342 | .PP |
| 343 | \&\fIEVP_CIPHER_param_to_asn1()\fR sets the AlgorithmIdentifier \*(L"parameter\*(R" based |
| 344 | on the passed cipher. This will typically include any parameters and an |
| 345 | \&\s-1IV\s0. The cipher \s-1IV\s0 (if any) must be set when this call is made. This call |
| 346 | should be made before the cipher is actually \*(L"used\*(R" (before any |
| 347 | \&\fIEVP_EncryptUpdate()\fR, \fIEVP_DecryptUpdate()\fR calls for example). This function |
| 348 | may fail if the cipher does not have any \s-1ASN1\s0 support. |
| 349 | .PP |
| 350 | \&\fIEVP_CIPHER_asn1_to_param()\fR sets the cipher parameters based on an \s-1ASN1\s0 |
| 351 | AlgorithmIdentifier \*(L"parameter\*(R". The precise effect depends on the cipher |
| 352 | In the case of \s-1RC2\s0, for example, it will set the \s-1IV\s0 and effective key length. |
| 353 | This function should be called after the base cipher type is set but before |
| 354 | the key is set. For example \fIEVP_CipherInit()\fR will be called with the \s-1IV\s0 and |
| 355 | key set to \s-1NULL\s0, \fIEVP_CIPHER_asn1_to_param()\fR will be called and finally |
| 356 | \&\fIEVP_CipherInit()\fR again with all parameters except the key set to \s-1NULL\s0. It is |
| 357 | possible for this function to fail if the cipher does not have any \s-1ASN1\s0 support |
| 358 | or the parameters cannot be set (for example the \s-1RC2\s0 effective key length |
| 359 | is not supported. |
| 360 | .PP |
| 361 | \&\fIEVP_CIPHER_CTX_ctrl()\fR allows various cipher specific parameters to be determined |
| 362 | and set. Currently only the \s-1RC2\s0 effective key length and the number of rounds of |
| 363 | \&\s-1RC5\s0 can be set. |
| 364 | .SH "RETURN VALUES" |
| 365 | .IX Header "RETURN VALUES" |
| 366 | \&\fIEVP_EncryptInit_ex()\fR, \fIEVP_EncryptUpdate()\fR and \fIEVP_EncryptFinal_ex()\fR |
| 367 | return 1 for success and 0 for failure. |
| 368 | .PP |
| 369 | \&\fIEVP_DecryptInit_ex()\fR and \fIEVP_DecryptUpdate()\fR return 1 for success and 0 for failure. |
| 370 | \&\fIEVP_DecryptFinal_ex()\fR returns 0 if the decrypt failed or 1 for success. |
| 371 | .PP |
| 372 | \&\fIEVP_CipherInit_ex()\fR and \fIEVP_CipherUpdate()\fR return 1 for success and 0 for failure. |
| 373 | \&\fIEVP_CipherFinal_ex()\fR returns 0 for a decryption failure or 1 for success. |
| 374 | .PP |
| 375 | \&\fIEVP_CIPHER_CTX_cleanup()\fR returns 1 for success and 0 for failure. |
| 376 | .PP |
| 377 | \&\fIEVP_get_cipherbyname()\fR, \fIEVP_get_cipherbynid()\fR and \fIEVP_get_cipherbyobj()\fR |
| 378 | return an \fB\s-1EVP_CIPHER\s0\fR structure or \s-1NULL\s0 on error. |
| 379 | .PP |
| 380 | \&\fIEVP_CIPHER_nid()\fR and \fIEVP_CIPHER_CTX_nid()\fR return a \s-1NID\s0. |
| 381 | .PP |
| 382 | \&\fIEVP_CIPHER_block_size()\fR and \fIEVP_CIPHER_CTX_block_size()\fR return the block |
| 383 | size. |
| 384 | .PP |
| 385 | \&\fIEVP_CIPHER_key_length()\fR and \fIEVP_CIPHER_CTX_key_length()\fR return the key |
| 386 | length. |
| 387 | .PP |
| 388 | \&\fIEVP_CIPHER_CTX_set_padding()\fR always returns 1. |
| 389 | .PP |
| 390 | \&\fIEVP_CIPHER_iv_length()\fR and \fIEVP_CIPHER_CTX_iv_length()\fR return the \s-1IV\s0 |
| 391 | length or zero if the cipher does not use an \s-1IV\s0. |
| 392 | .PP |
| 393 | \&\fIEVP_CIPHER_type()\fR and \fIEVP_CIPHER_CTX_type()\fR return the \s-1NID\s0 of the cipher's |
| 394 | \&\s-1OBJECT\s0 \s-1IDENTIFIER\s0 or NID_undef if it has no defined \s-1OBJECT\s0 \s-1IDENTIFIER\s0. |
| 395 | .PP |
| 396 | \&\fIEVP_CIPHER_CTX_cipher()\fR returns an \fB\s-1EVP_CIPHER\s0\fR structure. |
| 397 | .PP |
| 398 | \&\fIEVP_CIPHER_param_to_asn1()\fR and \fIEVP_CIPHER_asn1_to_param()\fR return 1 for |
| 399 | success or zero for failure. |
| 400 | .SH "CIPHER LISTING" |
| 401 | .IX Header "CIPHER LISTING" |
| 402 | All algorithms have a fixed key length unless otherwise stated. |
| 403 | .IP "\fIEVP_enc_null()\fR" 4 |
| 404 | .IX Item "EVP_enc_null()" |
| 405 | Null cipher: does nothing. |
| 406 | .IP "EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void)" 4 |
| 407 | .IX Item "EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void)" |
| 408 | \&\s-1DES\s0 in \s-1CBC\s0, \s-1ECB\s0, \s-1CFB\s0 and \s-1OFB\s0 modes respectively. |
| 409 | .IP "EVP_des_ede_cbc(void), \fIEVP_des_ede()\fR, EVP_des_ede_ofb(void), EVP_des_ede_cfb(void)" 4 |
| 410 | .IX Item "EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), EVP_des_ede_cfb(void)" |
| 411 | Two key triple \s-1DES\s0 in \s-1CBC\s0, \s-1ECB\s0, \s-1CFB\s0 and \s-1OFB\s0 modes respectively. |
| 412 | .IP "EVP_des_ede3_cbc(void), \fIEVP_des_ede3()\fR, EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void)" 4 |
| 413 | .IX Item "EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void)" |
| 414 | Three key triple \s-1DES\s0 in \s-1CBC\s0, \s-1ECB\s0, \s-1CFB\s0 and \s-1OFB\s0 modes respectively. |
| 415 | .IP "EVP_desx_cbc(void)" 4 |
| 416 | .IX Item "EVP_desx_cbc(void)" |
| 417 | \&\s-1DESX\s0 algorithm in \s-1CBC\s0 mode. |
| 418 | .IP "EVP_rc4(void)" 4 |
| 419 | .IX Item "EVP_rc4(void)" |
| 420 | \&\s-1RC4\s0 stream cipher. This is a variable key length cipher with default key length 128 bits. |
| 421 | .IP "EVP_rc4_40(void)" 4 |
| 422 | .IX Item "EVP_rc4_40(void)" |
| 423 | \&\s-1RC4\s0 stream cipher with 40 bit key length. This is obsolete and new code should use \fIEVP_rc4()\fR |
| 424 | and the \fIEVP_CIPHER_CTX_set_key_length()\fR function. |
| 425 | .IP "\fIEVP_idea_cbc()\fR EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void)" 4 |
| 426 | .IX Item "EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void)" |
| 427 | \&\s-1IDEA\s0 encryption algorithm in \s-1CBC\s0, \s-1ECB\s0, \s-1CFB\s0 and \s-1OFB\s0 modes respectively. |
| 428 | .IP "EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void)" 4 |
| 429 | .IX Item "EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void)" |
| 430 | \&\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 |
| 431 | length cipher with an additional parameter called \*(L"effective key bits\*(R" or \*(L"effective key length\*(R". |
| 432 | By default both are set to 128 bits. |
| 433 | .IP "EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void)" 4 |
| 434 | .IX Item "EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void)" |
| 435 | \&\s-1RC2\s0 algorithm in \s-1CBC\s0 mode with a default key length and effective key length of 40 and 64 bits. |
| 436 | These are obsolete and new code should use \fIEVP_rc2_cbc()\fR, \fIEVP_CIPHER_CTX_set_key_length()\fR and |
| 437 | \&\fIEVP_CIPHER_CTX_ctrl()\fR to set the key length and effective key length. |
| 438 | .IP "EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void);" 4 |
| 439 | .IX Item "EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void);" |
| 440 | Blowfish encryption algorithm in \s-1CBC\s0, \s-1ECB\s0, \s-1CFB\s0 and \s-1OFB\s0 modes respectively. This is a variable key |
| 441 | length cipher. |
| 442 | .IP "EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void)" 4 |
| 443 | .IX Item "EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void)" |
| 444 | \&\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 |
| 445 | length cipher. |
| 446 | .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 |
| 447 | .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)" |
| 448 | \&\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 |
| 449 | cipher with an additional \*(L"number of rounds\*(R" parameter. By default the key length is set to 128 |
| 450 | bits and 12 rounds. |
| 451 | .SH "NOTES" |
| 452 | .IX Header "NOTES" |
| 453 | Where possible the \fB\s-1EVP\s0\fR interface to symmetric ciphers should be used in |
| 454 | preference to the low level interfaces. This is because the code then becomes |
| 455 | transparent to the cipher used and much more flexible. Additionally, the |
| 456 | \&\fB\s-1EVP\s0\fR interface will ensure the use of platform specific cryptographic |
| 457 | acceleration such as AES-NI (the low level interfaces do not provide the |
| 458 | guarantee). |
| 459 | .PP |
| 460 | \&\s-1PKCS\s0 padding works by adding \fBn\fR padding bytes of value \fBn\fR to make the total |
| 461 | length of the encrypted data a multiple of the block size. Padding is always |
| 462 | added so if the data is already a multiple of the block size \fBn\fR will equal |
| 463 | the block size. For example if the block size is 8 and 11 bytes are to be |
| 464 | encrypted then 5 padding bytes of value 5 will be added. |
| 465 | .PP |
| 466 | When decrypting the final block is checked to see if it has the correct form. |
| 467 | .PP |
| 468 | Although the decryption operation can produce an error if padding is enabled, |
| 469 | it is not a strong test that the input data or key is correct. A random block |
| 470 | has better than 1 in 256 chance of being of the correct format and problems with |
| 471 | the input data earlier on will not produce a final decrypt error. |
| 472 | .PP |
| 473 | If padding is disabled then the decryption operation will always succeed if |
| 474 | the total amount of data decrypted is a multiple of the block size. |
| 475 | .PP |
| 476 | The functions \fIEVP_EncryptInit()\fR, \fIEVP_EncryptFinal()\fR, \fIEVP_DecryptInit()\fR, |
| 477 | \&\fIEVP_CipherInit()\fR and \fIEVP_CipherFinal()\fR are obsolete but are retained for |
| 478 | compatibility with existing code. New code should use \fIEVP_EncryptInit_ex()\fR, |
| 479 | \&\fIEVP_EncryptFinal_ex()\fR, \fIEVP_DecryptInit_ex()\fR, \fIEVP_DecryptFinal_ex()\fR, |
| 480 | \&\fIEVP_CipherInit_ex()\fR and \fIEVP_CipherFinal_ex()\fR because they can reuse an |
| 481 | existing context without allocating and freeing it up on each call. |
| 482 | .SH "BUGS" |
| 483 | .IX Header "BUGS" |
| 484 | For \s-1RC5\s0 the number of rounds can currently only be set to 8, 12 or 16. This is |
| 485 | a limitation of the current \s-1RC5\s0 code rather than the \s-1EVP\s0 interface. |
| 486 | .PP |
| 487 | \&\s-1EVP_MAX_KEY_LENGTH\s0 and \s-1EVP_MAX_IV_LENGTH\s0 only refer to the internal ciphers with |
| 488 | default key lengths. If custom ciphers exceed these values the results are |
| 489 | unpredictable. This is because it has become standard practice to define a |
| 490 | generic key as a fixed unsigned char array containing \s-1EVP_MAX_KEY_LENGTH\s0 bytes. |
| 491 | .PP |
| 492 | The \s-1ASN1\s0 code is incomplete (and sometimes inaccurate) it has only been tested |
| 493 | for certain common S/MIME ciphers (\s-1RC2\s0, \s-1DES\s0, triple \s-1DES\s0) in \s-1CBC\s0 mode. |
| 494 | .SH "EXAMPLES" |
| 495 | .IX Header "EXAMPLES" |
| 496 | Get the number of rounds used in \s-1RC5:\s0 |
| 497 | .PP |
| 498 | .Vb 2 |
| 499 | \& int nrounds; |
| 500 | \& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds); |
| 501 | .Ve |
| 502 | .PP |
| 503 | Get the \s-1RC2\s0 effective key length: |
| 504 | .PP |
| 505 | .Vb 2 |
| 506 | \& int key_bits; |
| 507 | \& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits); |
| 508 | .Ve |
| 509 | .PP |
| 510 | Set the number of rounds used in \s-1RC5:\s0 |
| 511 | .PP |
| 512 | .Vb 2 |
| 513 | \& int nrounds; |
| 514 | \& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL); |
| 515 | .Ve |
| 516 | .PP |
| 517 | Set the effective key length used in \s-1RC2:\s0 |
| 518 | .PP |
| 519 | .Vb 2 |
| 520 | \& int key_bits; |
| 521 | \& EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL); |
| 522 | .Ve |
| 523 | .PP |
| 524 | Encrypt a string using blowfish: |
| 525 | .PP |
| 526 | .Vb 10 |
| 527 | \& int do_crypt(char *outfile) |
| 528 | \& { |
| 529 | \& unsigned char outbuf[1024]; |
| 530 | \& int outlen, tmplen; |
| 531 | \& /* Bogus key and IV: we\*(Aqd normally set these from |
| 532 | \& * another source. |
| 533 | \& */ |
| 534 | \& unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; |
| 535 | \& unsigned char iv[] = {1,2,3,4,5,6,7,8}; |
| 536 | \& char intext[] = "Some Crypto Text"; |
| 537 | \& EVP_CIPHER_CTX ctx; |
| 538 | \& FILE *out; |
| 539 | \& EVP_CIPHER_CTX_init(&ctx); |
| 540 | \& EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv); |
| 541 | \& |
| 542 | \& if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext))) |
| 543 | \& { |
| 544 | \& /* Error */ |
| 545 | \& return 0; |
| 546 | \& } |
| 547 | \& /* Buffer passed to EVP_EncryptFinal() must be after data just |
| 548 | \& * encrypted to avoid overwriting it. |
| 549 | \& */ |
| 550 | \& if(!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen)) |
| 551 | \& { |
| 552 | \& /* Error */ |
| 553 | \& return 0; |
| 554 | \& } |
| 555 | \& outlen += tmplen; |
| 556 | \& EVP_CIPHER_CTX_cleanup(&ctx); |
| 557 | \& /* Need binary mode for fopen because encrypted data is |
| 558 | \& * binary data. Also cannot use strlen() on it because |
| 559 | \& * it wont be null terminated and may contain embedded |
| 560 | \& * nulls. |
| 561 | \& */ |
| 562 | \& out = fopen(outfile, "wb"); |
| 563 | \& fwrite(outbuf, 1, outlen, out); |
| 564 | \& fclose(out); |
| 565 | \& return 1; |
| 566 | \& } |
| 567 | .Ve |
| 568 | .PP |
| 569 | The ciphertext from the above example can be decrypted using the \fBopenssl\fR |
| 570 | utility with the command line: |
| 571 | .PP |
| 572 | .Vb 1 |
| 573 | \& S<openssl bf \-in cipher.bin \-K 000102030405060708090A0B0C0D0E0F \-iv 0102030405060708 \-d> |
| 574 | .Ve |
| 575 | .PP |
| 576 | General encryption, decryption function example using \s-1FILE\s0 I/O and \s-1RC2\s0 with an |
| 577 | 80 bit key: |
| 578 | .PP |
| 579 | .Vb 10 |
| 580 | \& int do_crypt(FILE *in, FILE *out, int do_encrypt) |
| 581 | \& { |
| 582 | \& /* Allow enough space in output buffer for additional block */ |
| 583 | \& inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; |
| 584 | \& int inlen, outlen; |
| 585 | \& /* Bogus key and IV: we\*(Aqd normally set these from |
| 586 | \& * another source. |
| 587 | \& */ |
| 588 | \& unsigned char key[] = "0123456789"; |
| 589 | \& unsigned char iv[] = "12345678"; |
| 590 | \& /* Don\*(Aqt set key or IV because we will modify the parameters */ |
| 591 | \& EVP_CIPHER_CTX_init(&ctx); |
| 592 | \& EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt); |
| 593 | \& EVP_CIPHER_CTX_set_key_length(&ctx, 10); |
| 594 | \& /* We finished modifying parameters so now we can set key and IV */ |
| 595 | \& EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt); |
| 596 | \& |
| 597 | \& for(;;) |
| 598 | \& { |
| 599 | \& inlen = fread(inbuf, 1, 1024, in); |
| 600 | \& if(inlen <= 0) break; |
| 601 | \& if(!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, inlen)) |
| 602 | \& { |
| 603 | \& /* Error */ |
| 604 | \& EVP_CIPHER_CTX_cleanup(&ctx); |
| 605 | \& return 0; |
| 606 | \& } |
| 607 | \& fwrite(outbuf, 1, outlen, out); |
| 608 | \& } |
| 609 | \& if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen)) |
| 610 | \& { |
| 611 | \& /* Error */ |
| 612 | \& EVP_CIPHER_CTX_cleanup(&ctx); |
| 613 | \& return 0; |
| 614 | \& } |
| 615 | \& fwrite(outbuf, 1, outlen, out); |
| 616 | \& |
| 617 | \& EVP_CIPHER_CTX_cleanup(&ctx); |
| 618 | \& return 1; |
| 619 | \& } |
| 620 | .Ve |
| 621 | .SH "SEE ALSO" |
| 622 | .IX Header "SEE ALSO" |
| 623 | \&\fIevp\fR\|(3) |
| 624 | .SH "HISTORY" |
| 625 | .IX Header "HISTORY" |
| 626 | \&\fIEVP_CIPHER_CTX_init()\fR, \fIEVP_EncryptInit_ex()\fR, \fIEVP_EncryptFinal_ex()\fR, |
| 627 | \&\fIEVP_DecryptInit_ex()\fR, \fIEVP_DecryptFinal_ex()\fR, \fIEVP_CipherInit_ex()\fR, |
| 628 | \&\fIEVP_CipherFinal_ex()\fR and \fIEVP_CIPHER_CTX_set_padding()\fR appeared in |
| 629 | OpenSSL 0.9.7. |