| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "EVP_ENCRYPTINIT 3SSL" |
| 58 |
.TH EVP_ENCRYPTINIT 3SSL 2026-04-07 3.6.2 OpenSSL |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
EVP_CIPHER_fetch, |
| 65 |
EVP_CIPHER_up_ref, |
| 66 |
EVP_CIPHER_free, |
| 67 |
EVP_CIPHER_CTX_new, |
| 68 |
EVP_CIPHER_CTX_reset, |
| 69 |
EVP_CIPHER_CTX_free, |
| 70 |
EVP_CIPHER_CTX_dup, |
| 71 |
EVP_CIPHER_CTX_copy, |
| 72 |
EVP_EncryptInit_ex, |
| 73 |
EVP_EncryptInit_ex2, |
| 74 |
EVP_EncryptUpdate, |
| 75 |
EVP_EncryptFinal_ex, |
| 76 |
EVP_DecryptInit_ex, |
| 77 |
EVP_DecryptInit_ex2, |
| 78 |
EVP_DecryptUpdate, |
| 79 |
EVP_DecryptFinal_ex, |
| 80 |
EVP_CipherInit_ex, |
| 81 |
EVP_CipherInit_ex2, |
| 82 |
EVP_CipherInit_SKEY, |
| 83 |
EVP_CipherUpdate, |
| 84 |
EVP_CipherFinal_ex, |
| 85 |
EVP_CIPHER_CTX_set_key_length, |
| 86 |
EVP_CIPHER_CTX_ctrl, |
| 87 |
EVP_EncryptInit, |
| 88 |
EVP_EncryptFinal, |
| 89 |
EVP_DecryptInit, |
| 90 |
EVP_DecryptFinal, |
| 91 |
EVP_CipherInit, |
| 92 |
EVP_CipherFinal, |
| 93 |
EVP_Cipher, |
| 94 |
EVP_CIPHER_can_pipeline, |
| 95 |
EVP_CipherPipelineEncryptInit, |
| 96 |
EVP_CipherPipelineDecryptInit, |
| 97 |
EVP_CipherPipelineUpdate, |
| 98 |
EVP_CipherPipelineFinal, |
| 99 |
EVP_get_cipherbyname, |
| 100 |
EVP_get_cipherbynid, |
| 101 |
EVP_get_cipherbyobj, |
| 102 |
EVP_CIPHER_is_a, |
| 103 |
EVP_CIPHER_get0_name, |
| 104 |
EVP_CIPHER_get0_description, |
| 105 |
EVP_CIPHER_names_do_all, |
| 106 |
EVP_CIPHER_get0_provider, |
| 107 |
EVP_CIPHER_get_nid, |
| 108 |
EVP_CIPHER_get_params, |
| 109 |
EVP_CIPHER_gettable_params, |
| 110 |
EVP_CIPHER_get_block_size, |
| 111 |
EVP_CIPHER_get_key_length, |
| 112 |
EVP_CIPHER_get_iv_length, |
| 113 |
EVP_CIPHER_get_flags, |
| 114 |
EVP_CIPHER_get_mode, |
| 115 |
EVP_CIPHER_get_type, |
| 116 |
EVP_CIPHER_CTX_cipher, |
| 117 |
EVP_CIPHER_CTX_get0_cipher, |
| 118 |
EVP_CIPHER_CTX_get1_cipher, |
| 119 |
EVP_CIPHER_CTX_get0_name, |
| 120 |
EVP_CIPHER_CTX_get_nid, |
| 121 |
EVP_CIPHER_CTX_get_params, |
| 122 |
EVP_CIPHER_gettable_ctx_params, |
| 123 |
EVP_CIPHER_CTX_gettable_params, |
| 124 |
EVP_CIPHER_CTX_set_params, |
| 125 |
EVP_CIPHER_settable_ctx_params, |
| 126 |
EVP_CIPHER_CTX_settable_params, |
| 127 |
EVP_CIPHER_CTX_get_block_size, |
| 128 |
EVP_CIPHER_CTX_get_key_length, |
| 129 |
EVP_CIPHER_CTX_get_iv_length, |
| 130 |
EVP_CIPHER_CTX_get_tag_length, |
| 131 |
EVP_CIPHER_CTX_flags, |
| 132 |
EVP_CIPHER_CTX_set_flags, |
| 133 |
EVP_CIPHER_CTX_clear_flags, |
| 134 |
EVP_CIPHER_CTX_test_flags, |
| 135 |
EVP_CIPHER_CTX_get_type, |
| 136 |
EVP_CIPHER_CTX_get_mode, |
| 137 |
EVP_CIPHER_CTX_get_num, |
| 138 |
EVP_CIPHER_CTX_set_num, |
| 139 |
EVP_CIPHER_CTX_is_encrypting, |
| 140 |
EVP_CIPHER_param_to_asn1, |
| 141 |
EVP_CIPHER_asn1_to_param, |
| 142 |
EVP_CIPHER_CTX_set_padding, |
| 143 |
EVP_enc_null, |
| 144 |
EVP_CIPHER_do_all_provided, |
| 145 |
EVP_CIPHER_nid, |
| 146 |
EVP_CIPHER_name, |
| 147 |
EVP_CIPHER_block_size, |
| 148 |
EVP_CIPHER_key_length, |
| 149 |
EVP_CIPHER_iv_length, |
| 150 |
EVP_CIPHER_flags, |
| 151 |
EVP_CIPHER_mode, |
| 152 |
EVP_CIPHER_type, |
| 153 |
EVP_CIPHER_CTX_encrypting, |
| 154 |
EVP_CIPHER_CTX_nid, |
| 155 |
EVP_CIPHER_CTX_block_size, |
| 156 |
EVP_CIPHER_CTX_key_length, |
| 157 |
EVP_CIPHER_CTX_iv_length, |
| 158 |
EVP_CIPHER_CTX_tag_length, |
| 159 |
EVP_CIPHER_CTX_num, |
| 160 |
EVP_CIPHER_CTX_type, |
| 161 |
EVP_CIPHER_CTX_mode |
| 162 |
\&\- EVP cipher routines |
| 163 |
.SH SYNOPSIS |
| 164 |
.IX Header "SYNOPSIS" |
| 165 |
.Vb 1 |
| 166 |
\& #include <openssl/evp.h> |
| 167 |
\& |
| 168 |
\& EVP_CIPHER *EVP_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, |
| 169 |
\& const char *properties); |
| 170 |
\& int EVP_CIPHER_up_ref(EVP_CIPHER *cipher); |
| 171 |
\& void EVP_CIPHER_free(EVP_CIPHER *cipher); |
| 172 |
\& EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void); |
| 173 |
\& int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx); |
| 174 |
\& void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx); |
| 175 |
\& EVP_CIPHER_CTX *EVP_CIPHER_CTX_dup(const EVP_CIPHER_CTX *in); |
| 176 |
\& int EVP_CIPHER_CTX_copy(EVP_CIPHER_CTX *out, const EVP_CIPHER_CTX *in); |
| 177 |
\& |
| 178 |
\& int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 179 |
\& ENGINE *impl, const unsigned char *key, const unsigned char *iv); |
| 180 |
\& int EVP_EncryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 181 |
\& const unsigned char *key, const unsigned char *iv, |
| 182 |
\& const OSSL_PARAM params[]); |
| 183 |
\& int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, |
| 184 |
\& int *outl, const unsigned char *in, int inl); |
| 185 |
\& int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); |
| 186 |
\& |
| 187 |
\& int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 188 |
\& ENGINE *impl, const unsigned char *key, const unsigned char *iv); |
| 189 |
\& int EVP_DecryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 190 |
\& const unsigned char *key, const unsigned char *iv, |
| 191 |
\& const OSSL_PARAM params[]); |
| 192 |
\& int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, |
| 193 |
\& int *outl, const unsigned char *in, int inl); |
| 194 |
\& int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); |
| 195 |
\& |
| 196 |
\& int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 197 |
\& ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc); |
| 198 |
\& int EVP_CipherInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 199 |
\& const unsigned char *key, const unsigned char *iv, |
| 200 |
\& int enc, const OSSL_PARAM params[]); |
| 201 |
\& int EVP_CipherInit_SKEY(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher, |
| 202 |
\& EVP_SKEY *skey, const unsigned char *iv, size_t iv_len, |
| 203 |
\& int enc, const OSSL_PARAM params[]); |
| 204 |
\& int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, |
| 205 |
\& int *outl, const unsigned char *in, int inl); |
| 206 |
\& int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); |
| 207 |
\& |
| 208 |
\& int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 209 |
\& const unsigned char *key, const unsigned char *iv); |
| 210 |
\& int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); |
| 211 |
\& |
| 212 |
\& int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 213 |
\& const unsigned char *key, const unsigned char *iv); |
| 214 |
\& int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); |
| 215 |
\& |
| 216 |
\& int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
| 217 |
\& const unsigned char *key, const unsigned char *iv, int enc); |
| 218 |
\& int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); |
| 219 |
\& |
| 220 |
\& int EVP_Cipher(EVP_CIPHER_CTX *ctx, unsigned char *out, |
| 221 |
\& const unsigned char *in, unsigned int inl); |
| 222 |
\& |
| 223 |
\& int EVP_CIPHER_can_pipeline(const EVP_CIPHER *cipher, int enc); |
| 224 |
\& int EVP_CipherPipelineEncryptInit(EVP_CIPHER_CTX *ctx, |
| 225 |
\& const EVP_CIPHER *cipher, |
| 226 |
\& const unsigned char *key, size_t keylen, |
| 227 |
\& size_t numpipes, |
| 228 |
\& const unsigned char **iv, size_t ivlen); |
| 229 |
\& int EVP_CipherPipelineDecryptInit(EVP_CIPHER_CTX *ctx, |
| 230 |
\& const EVP_CIPHER *cipher, |
| 231 |
\& const unsigned char *key, size_t keylen, |
| 232 |
\& size_t numpipes, |
| 233 |
\& const unsigned char **iv, size_t ivlen); |
| 234 |
\& int EVP_CipherPipelineUpdate(EVP_CIPHER_CTX *ctx, |
| 235 |
\& unsigned char **out, size_t *outl, |
| 236 |
\& const size_t *outsize, |
| 237 |
\& const unsigned char **in, const size_t *inl); |
| 238 |
\& int EVP_CipherPipelineFinal(EVP_CIPHER_CTX *ctx, |
| 239 |
\& unsigned char **outm, size_t *outl, |
| 240 |
\& const size_t *outsize); |
| 241 |
\& |
| 242 |
\& int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding); |
| 243 |
\& int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen); |
| 244 |
\& int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int cmd, int p1, void *p2); |
| 245 |
\& int EVP_CIPHER_CTX_rand_key(EVP_CIPHER_CTX *ctx, unsigned char *key); |
| 246 |
\& void EVP_CIPHER_CTX_set_flags(EVP_CIPHER_CTX *ctx, int flags); |
| 247 |
\& void EVP_CIPHER_CTX_clear_flags(EVP_CIPHER_CTX *ctx, int flags); |
| 248 |
\& int EVP_CIPHER_CTX_test_flags(const EVP_CIPHER_CTX *ctx, int flags); |
| 249 |
\& |
| 250 |
\& const EVP_CIPHER *EVP_get_cipherbyname(const char *name); |
| 251 |
\& const EVP_CIPHER *EVP_get_cipherbynid(int nid); |
| 252 |
\& const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a); |
| 253 |
\& |
| 254 |
\& int EVP_CIPHER_get_nid(const EVP_CIPHER *e); |
| 255 |
\& int EVP_CIPHER_is_a(const EVP_CIPHER *cipher, const char *name); |
| 256 |
\& int EVP_CIPHER_names_do_all(const EVP_CIPHER *cipher, |
| 257 |
\& void (*fn)(const char *name, void *data), |
| 258 |
\& void *data); |
| 259 |
\& const char *EVP_CIPHER_get0_name(const EVP_CIPHER *cipher); |
| 260 |
\& const char *EVP_CIPHER_get0_description(const EVP_CIPHER *cipher); |
| 261 |
\& const OSSL_PROVIDER *EVP_CIPHER_get0_provider(const EVP_CIPHER *cipher); |
| 262 |
\& int EVP_CIPHER_get_block_size(const EVP_CIPHER *e); |
| 263 |
\& int EVP_CIPHER_get_key_length(const EVP_CIPHER *e); |
| 264 |
\& int EVP_CIPHER_get_iv_length(const EVP_CIPHER *e); |
| 265 |
\& unsigned long EVP_CIPHER_get_flags(const EVP_CIPHER *e); |
| 266 |
\& unsigned long EVP_CIPHER_get_mode(const EVP_CIPHER *e); |
| 267 |
\& int EVP_CIPHER_get_type(const EVP_CIPHER *cipher); |
| 268 |
\& |
| 269 |
\& const EVP_CIPHER *EVP_CIPHER_CTX_get0_cipher(const EVP_CIPHER_CTX *ctx); |
| 270 |
\& EVP_CIPHER *EVP_CIPHER_CTX_get1_cipher(const EVP_CIPHER_CTX *ctx); |
| 271 |
\& int EVP_CIPHER_CTX_get_nid(const EVP_CIPHER_CTX *ctx); |
| 272 |
\& const char *EVP_CIPHER_CTX_get0_name(const EVP_CIPHER_CTX *ctx); |
| 273 |
\& |
| 274 |
\& int EVP_CIPHER_get_params(EVP_CIPHER *cipher, OSSL_PARAM params[]); |
| 275 |
\& int EVP_CIPHER_CTX_set_params(EVP_CIPHER_CTX *ctx, const OSSL_PARAM params[]); |
| 276 |
\& int EVP_CIPHER_CTX_get_params(EVP_CIPHER_CTX *ctx, OSSL_PARAM params[]); |
| 277 |
\& const OSSL_PARAM *EVP_CIPHER_gettable_params(const EVP_CIPHER *cipher); |
| 278 |
\& const OSSL_PARAM *EVP_CIPHER_settable_ctx_params(const EVP_CIPHER *cipher); |
| 279 |
\& const OSSL_PARAM *EVP_CIPHER_gettable_ctx_params(const EVP_CIPHER *cipher); |
| 280 |
\& const OSSL_PARAM *EVP_CIPHER_CTX_settable_params(EVP_CIPHER_CTX *ctx); |
| 281 |
\& const OSSL_PARAM *EVP_CIPHER_CTX_gettable_params(EVP_CIPHER_CTX *ctx); |
| 282 |
\& int EVP_CIPHER_CTX_get_block_size(const EVP_CIPHER_CTX *ctx); |
| 283 |
\& int EVP_CIPHER_CTX_get_key_length(const EVP_CIPHER_CTX *ctx); |
| 284 |
\& int EVP_CIPHER_CTX_get_iv_length(const EVP_CIPHER_CTX *ctx); |
| 285 |
\& int EVP_CIPHER_CTX_get_tag_length(const EVP_CIPHER_CTX *ctx); |
| 286 |
\& int EVP_CIPHER_CTX_get_type(const EVP_CIPHER_CTX *ctx); |
| 287 |
\& int EVP_CIPHER_CTX_get_mode(const EVP_CIPHER_CTX *ctx); |
| 288 |
\& int EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx); |
| 289 |
\& int EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num); |
| 290 |
\& int EVP_CIPHER_CTX_is_encrypting(const EVP_CIPHER_CTX *ctx); |
| 291 |
\& |
| 292 |
\& int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); |
| 293 |
\& int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); |
| 294 |
\& |
| 295 |
\& void EVP_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx, |
| 296 |
\& void (*fn)(EVP_CIPHER *cipher, void *arg), |
| 297 |
\& void *arg); |
| 298 |
\& |
| 299 |
\& #define EVP_CIPHER_nid EVP_CIPHER_get_nid |
| 300 |
\& #define EVP_CIPHER_name EVP_CIPHER_get0_name |
| 301 |
\& #define EVP_CIPHER_block_size EVP_CIPHER_get_block_size |
| 302 |
\& #define EVP_CIPHER_key_length EVP_CIPHER_get_key_length |
| 303 |
\& #define EVP_CIPHER_iv_length EVP_CIPHER_get_iv_length |
| 304 |
\& #define EVP_CIPHER_flags EVP_CIPHER_get_flags |
| 305 |
\& #define EVP_CIPHER_mode EVP_CIPHER_get_mode |
| 306 |
\& #define EVP_CIPHER_type EVP_CIPHER_get_type |
| 307 |
\& #define EVP_CIPHER_CTX_encrypting EVP_CIPHER_CTX_is_encrypting |
| 308 |
\& #define EVP_CIPHER_CTX_nid EVP_CIPHER_CTX_get_nid |
| 309 |
\& #define EVP_CIPHER_CTX_block_size EVP_CIPHER_CTX_get_block_size |
| 310 |
\& #define EVP_CIPHER_CTX_key_length EVP_CIPHER_CTX_get_key_length |
| 311 |
\& #define EVP_CIPHER_CTX_iv_length EVP_CIPHER_CTX_get_iv_length |
| 312 |
\& #define EVP_CIPHER_CTX_tag_length EVP_CIPHER_CTX_get_tag_length |
| 313 |
\& #define EVP_CIPHER_CTX_num EVP_CIPHER_CTX_get_num |
| 314 |
\& #define EVP_CIPHER_CTX_type EVP_CIPHER_CTX_get_type |
| 315 |
\& #define EVP_CIPHER_CTX_mode EVP_CIPHER_CTX_get_mode |
| 316 |
.Ve |
| 317 |
.PP |
| 318 |
The following function has been deprecated since OpenSSL 3.0, and can be |
| 319 |
hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, |
| 320 |
see \fBopenssl_user_macros\fR\|(7): |
| 321 |
.PP |
| 322 |
.Vb 1 |
| 323 |
\& const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx); |
| 324 |
.Ve |
| 325 |
.PP |
| 326 |
The following function has been deprecated since OpenSSL 1.1.0, and can be |
| 327 |
hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, |
| 328 |
see \fBopenssl_user_macros\fR\|(7): |
| 329 |
.PP |
| 330 |
.Vb 1 |
| 331 |
\& int EVP_CIPHER_CTX_flags(const EVP_CIPHER_CTX *ctx); |
| 332 |
.Ve |
| 333 |
.SH DESCRIPTION |
| 334 |
.IX Header "DESCRIPTION" |
| 335 |
The EVP cipher routines are a high-level interface to certain |
| 336 |
symmetric ciphers. |
| 337 |
.PP |
| 338 |
The \fBEVP_CIPHER\fR type is a structure for cipher method implementation. |
| 339 |
.IP \fBEVP_CIPHER_fetch()\fR 4 |
| 340 |
.IX Item "EVP_CIPHER_fetch()" |
| 341 |
Fetches the cipher implementation for the given \fIalgorithm\fR from any provider |
| 342 |
offering it, within the criteria given by the \fIproperties\fR. |
| 343 |
See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information. |
| 344 |
.Sp |
| 345 |
The returned value must eventually be freed with \fBEVP_CIPHER_free()\fR. |
| 346 |
.Sp |
| 347 |
Fetched \fBEVP_CIPHER\fR structures are reference counted. |
| 348 |
.IP \fBEVP_CIPHER_up_ref()\fR 4 |
| 349 |
.IX Item "EVP_CIPHER_up_ref()" |
| 350 |
Increments the reference count for an \fBEVP_CIPHER\fR structure. |
| 351 |
.IP \fBEVP_CIPHER_free()\fR 4 |
| 352 |
.IX Item "EVP_CIPHER_free()" |
| 353 |
Decrements the reference count for the fetched \fBEVP_CIPHER\fR structure. |
| 354 |
If the reference count drops to 0 then the structure is freed. |
| 355 |
If the argument is NULL, nothing is done. |
| 356 |
.IP \fBEVP_CIPHER_CTX_new()\fR 4 |
| 357 |
.IX Item "EVP_CIPHER_CTX_new()" |
| 358 |
Allocates and returns a cipher context. |
| 359 |
.IP \fBEVP_CIPHER_CTX_free()\fR 4 |
| 360 |
.IX Item "EVP_CIPHER_CTX_free()" |
| 361 |
Clears all information from a cipher context and frees any allocated memory |
| 362 |
associated with it, including \fIctx\fR itself. This function should be called |
| 363 |
after all operations using a cipher are complete so sensitive information does |
| 364 |
not remain in memory. If the argument is NULL, nothing is done. |
| 365 |
.IP \fBEVP_CIPHER_CTX_dup()\fR 4 |
| 366 |
.IX Item "EVP_CIPHER_CTX_dup()" |
| 367 |
Can be used to duplicate the cipher state from \fIin\fR. This is useful |
| 368 |
to avoid multiple \fBEVP_CIPHER_fetch()\fR calls or if large amounts of data are to be |
| 369 |
fed which only differ in the last few bytes. |
| 370 |
.IP \fBEVP_CIPHER_CTX_copy()\fR 4 |
| 371 |
.IX Item "EVP_CIPHER_CTX_copy()" |
| 372 |
Can be used to copy the cipher state from \fIin\fR to \fIout\fR. |
| 373 |
.IP \fBEVP_CIPHER_CTX_ctrl()\fR 4 |
| 374 |
.IX Item "EVP_CIPHER_CTX_ctrl()" |
| 375 |
\&\fIThis is a legacy method.\fR \fBEVP_CIPHER_CTX_set_params()\fR and |
| 376 |
\&\fBEVP_CIPHER_CTX_get_params()\fR is the mechanism that should be used to set and get |
| 377 |
parameters that are used by providers. |
| 378 |
.Sp |
| 379 |
Performs cipher-specific control actions on context \fIctx\fR. The control command |
| 380 |
is indicated in \fIcmd\fR and any additional arguments in \fIp1\fR and \fIp2\fR. |
| 381 |
\&\fBEVP_CIPHER_CTX_ctrl()\fR must be called after \fBEVP_CipherInit_ex2()\fR. Other restrictions |
| 382 |
may apply depending on the control type and cipher implementation. |
| 383 |
.Sp |
| 384 |
If this function happens to be used with a fetched \fBEVP_CIPHER\fR, it will |
| 385 |
translate the controls that are known to OpenSSL into \fBOSSL_PARAM\fR\|(3) |
| 386 |
parameters with keys defined by OpenSSL and call \fBEVP_CIPHER_CTX_get_params()\fR or |
| 387 |
\&\fBEVP_CIPHER_CTX_set_params()\fR as is appropriate for each control command. |
| 388 |
.Sp |
| 389 |
See "CONTROLS" below for more information, including what translations are |
| 390 |
being done. |
| 391 |
.IP \fBEVP_CIPHER_get_params()\fR 4 |
| 392 |
.IX Item "EVP_CIPHER_get_params()" |
| 393 |
Retrieves the requested list of algorithm \fIparams\fR from a CIPHER \fIcipher\fR. |
| 394 |
See "PARAMETERS" below for more information. |
| 395 |
.IP \fBEVP_CIPHER_CTX_get_params()\fR 4 |
| 396 |
.IX Item "EVP_CIPHER_CTX_get_params()" |
| 397 |
Retrieves the requested list of \fIparams\fR from CIPHER context \fIctx\fR. |
| 398 |
See "PARAMETERS" below for more information. |
| 399 |
.IP \fBEVP_CIPHER_CTX_set_params()\fR 4 |
| 400 |
.IX Item "EVP_CIPHER_CTX_set_params()" |
| 401 |
Sets the list of \fIparams\fR into a CIPHER context \fIctx\fR. |
| 402 |
See "PARAMETERS" below for more information. |
| 403 |
.IP \fBEVP_CIPHER_gettable_params()\fR 4 |
| 404 |
.IX Item "EVP_CIPHER_gettable_params()" |
| 405 |
Get a constant \fBOSSL_PARAM\fR\|(3) array that describes the retrievable parameters |
| 406 |
that can be used with \fBEVP_CIPHER_get_params()\fR. |
| 407 |
.IP "\fBEVP_CIPHER_gettable_ctx_params()\fR and \fBEVP_CIPHER_CTX_gettable_params()\fR" 4 |
| 408 |
.IX Item "EVP_CIPHER_gettable_ctx_params() and EVP_CIPHER_CTX_gettable_params()" |
| 409 |
Get a constant \fBOSSL_PARAM\fR\|(3) array that describes the retrievable parameters |
| 410 |
that can be used with \fBEVP_CIPHER_CTX_get_params()\fR. |
| 411 |
\&\fBEVP_CIPHER_gettable_ctx_params()\fR returns the parameters that can be retrieved |
| 412 |
from the algorithm, whereas \fBEVP_CIPHER_CTX_gettable_params()\fR returns the |
| 413 |
parameters that can be retrieved in the context's current state. |
| 414 |
.IP "\fBEVP_CIPHER_settable_ctx_params()\fR and \fBEVP_CIPHER_CTX_settable_params()\fR" 4 |
| 415 |
.IX Item "EVP_CIPHER_settable_ctx_params() and EVP_CIPHER_CTX_settable_params()" |
| 416 |
Get a constant \fBOSSL_PARAM\fR\|(3) array that describes the settable parameters |
| 417 |
that can be used with \fBEVP_CIPHER_CTX_set_params()\fR. |
| 418 |
\&\fBEVP_CIPHER_settable_ctx_params()\fR returns the parameters that can be set from the |
| 419 |
algorithm, whereas \fBEVP_CIPHER_CTX_settable_params()\fR returns the parameters that |
| 420 |
can be set in the context's current state. |
| 421 |
.IP \fBEVP_EncryptInit_ex2()\fR 4 |
| 422 |
.IX Item "EVP_EncryptInit_ex2()" |
| 423 |
Sets up cipher context \fIctx\fR for encryption with cipher \fItype\fR. \fIctx\fR \fBMUST NOT\fR be NULL. |
| 424 |
\&\fItype\fR is typically supplied by calling \fBEVP_CIPHER_fetch()\fR. \fItype\fR may also be set |
| 425 |
using legacy functions such as \fBEVP_aes_256_cbc()\fR, but this is not recommended |
| 426 |
for new applications. \fIkey\fR is the symmetric key to use and \fIiv\fR is the IV to |
| 427 |
use (if necessary), the actual number of bytes used for the key and IV depends |
| 428 |
on the cipher. The parameters \fIparams\fR will be set on the context after |
| 429 |
initialisation. It is possible to set all parameters to NULL except \fItype\fR in |
| 430 |
an initial call and supply the remaining parameters in subsequent calls, all of |
| 431 |
which have \fItype\fR set to NULL. This is done when the default cipher parameters |
| 432 |
are not appropriate. |
| 433 |
For \fBEVP_CIPH_GCM_MODE\fR the IV will be generated internally if it is not |
| 434 |
specified. |
| 435 |
.IP \fBEVP_EncryptInit_ex()\fR 4 |
| 436 |
.IX Item "EVP_EncryptInit_ex()" |
| 437 |
This legacy function is similar to \fBEVP_EncryptInit_ex2()\fR when \fIimpl\fR is NULL. |
| 438 |
The implementation of the \fItype\fR from the \fIimpl\fR engine will be used if it |
| 439 |
exists. |
| 440 |
.IP \fBEVP_EncryptUpdate()\fR 4 |
| 441 |
.IX Item "EVP_EncryptUpdate()" |
| 442 |
Encrypts \fIinl\fR bytes from the buffer \fIin\fR and writes the encrypted version to |
| 443 |
\&\fIout\fR. The pointers \fIout\fR and \fIin\fR may point to the same location, in which |
| 444 |
case the encryption will be done in-place. However, in-place encryption is |
| 445 |
guaranteed to work only if the encryption context (\fIctx\fR) has processed data in |
| 446 |
multiples of the block size. If the context contains an incomplete data block |
| 447 |
from previous operations, in-place encryption will fail. \fIctx\fR \fBMUST NOT\fR be NULL. |
| 448 |
.Sp |
| 449 |
If \fIout\fR and \fIin\fR point to different locations, the two buffers must be |
| 450 |
disjoint, otherwise the operation might fail or the outcome might be undefined. |
| 451 |
.Sp |
| 452 |
This function can be called multiple times to encrypt successive blocks |
| 453 |
of data. The amount of data written depends on the block alignment of the |
| 454 |
encrypted data. |
| 455 |
For most ciphers and modes, the amount of data written can be anything |
| 456 |
from zero bytes to (inl + cipher_block_size \- 1) bytes. |
| 457 |
For wrap cipher modes, the amount of data written can be anything |
| 458 |
from zero bytes to (inl + cipher_block_size) bytes. |
| 459 |
For stream ciphers, the amount of data written can be anything from zero |
| 460 |
bytes to inl bytes. |
| 461 |
Thus, the buffer pointed to by \fIout\fR must contain sufficient room for the |
| 462 |
operation being performed. |
| 463 |
The actual number of bytes written is placed in \fIoutl\fR. |
| 464 |
.Sp |
| 465 |
If padding is enabled (the default) then \fBEVP_EncryptFinal_ex()\fR encrypts |
| 466 |
the "final" data, that is any data that remains in a partial block. |
| 467 |
It uses standard block padding (aka PKCS padding) as described in |
| 468 |
the NOTES section, below. The encrypted |
| 469 |
final data is written to \fIout\fR which should have sufficient space for |
| 470 |
one cipher block. The number of bytes written is placed in \fIoutl\fR. After |
| 471 |
this function is called the encryption operation is finished and no further |
| 472 |
calls to \fBEVP_EncryptUpdate()\fR should be made. |
| 473 |
.Sp |
| 474 |
If padding is disabled then \fBEVP_EncryptFinal_ex()\fR will not encrypt any more |
| 475 |
data and it will return an error if any data remains in a partial block: |
| 476 |
that is if the total data length is not a multiple of the block size. |
| 477 |
.IP "\fBEVP_DecryptInit_ex2()\fR, \fBEVP_DecryptInit_ex()\fR, \fBEVP_DecryptUpdate()\fR and \fBEVP_DecryptFinal_ex()\fR" 4 |
| 478 |
.IX Item "EVP_DecryptInit_ex2(), EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex()" |
| 479 |
These functions are the corresponding decryption operations. |
| 480 |
\&\fBEVP_DecryptFinal()\fR will return an error code if padding is enabled and the |
| 481 |
final block is not correctly formatted. The parameters and restrictions are |
| 482 |
identical to the encryption operations. \fIctx\fR \fBMUST NOT\fR be NULL. |
| 483 |
.IP "\fBEVP_CipherInit_ex2()\fR, \fBEVP_CipherInit_ex()\fR, \fBEVP_CipherUpdate()\fR and \fBEVP_CipherFinal_ex()\fR" 4 |
| 484 |
.IX Item "EVP_CipherInit_ex2(), EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex()" |
| 485 |
These functions can be used for decryption or encryption. The operation |
| 486 |
performed depends on the value of the \fIenc\fR parameter. It should be set to 1 |
| 487 |
for encryption, 0 for decryption and \-1 to leave the value unchanged |
| 488 |
(the actual value of 'enc' being supplied in a previous call). |
| 489 |
.IP \fBEVP_CipherInit_SKEY()\fR 4 |
| 490 |
.IX Item "EVP_CipherInit_SKEY()" |
| 491 |
This function is similar to \fBEVP_CipherInit_ex2()\fR but accepts a |
| 492 |
symmetric key object of type \fIEVP_SKEY\fR as a key. |
| 493 |
.IP \fBEVP_CIPHER_CTX_reset()\fR 4 |
| 494 |
.IX Item "EVP_CIPHER_CTX_reset()" |
| 495 |
Clears all information from a cipher context and free up any allocated memory |
| 496 |
associated with it, except the \fIctx\fR itself. This function should be called |
| 497 |
anytime \fIctx\fR is reused by another |
| 498 |
\&\fBEVP_CipherInit()\fR / \fBEVP_CipherUpdate()\fR / \fBEVP_CipherFinal()\fR series of calls. |
| 499 |
.IP "\fBEVP_EncryptInit()\fR, \fBEVP_DecryptInit()\fR and \fBEVP_CipherInit()\fR" 4 |
| 500 |
.IX Item "EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit()" |
| 501 |
Behave in a similar way to \fBEVP_EncryptInit_ex()\fR, \fBEVP_DecryptInit_ex()\fR and |
| 502 |
\&\fBEVP_CipherInit_ex()\fR except if the \fItype\fR is not a fetched cipher they use the |
| 503 |
default implementation of the \fItype\fR. |
| 504 |
.IP "\fBEVP_EncryptFinal()\fR, \fBEVP_DecryptFinal()\fR and \fBEVP_CipherFinal()\fR" 4 |
| 505 |
.IX Item "EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal()" |
| 506 |
Identical to \fBEVP_EncryptFinal_ex()\fR, \fBEVP_DecryptFinal_ex()\fR and |
| 507 |
\&\fBEVP_CipherFinal_ex()\fR. In previous releases they also cleaned up |
| 508 |
the \fIctx\fR, but this is no longer done and \fBEVP_CIPHER_CTX_cleanup()\fR |
| 509 |
must be called to free any context resources. |
| 510 |
.IP \fBEVP_Cipher()\fR 4 |
| 511 |
.IX Item "EVP_Cipher()" |
| 512 |
Encrypts or decrypts a maximum \fIinl\fR amount of bytes from \fIin\fR and leaves the |
| 513 |
result in \fIout\fR. |
| 514 |
.Sp |
| 515 |
For legacy ciphers \- If the cipher doesn't have the flag |
| 516 |
\&\fBEVP_CIPH_FLAG_CUSTOM_CIPHER\fR set, then \fIinl\fR must be a multiple of |
| 517 |
\&\fBEVP_CIPHER_get_block_size()\fR. If it isn't, the result is undefined. If the cipher |
| 518 |
has that flag set, then \fIinl\fR can be any size. |
| 519 |
.Sp |
| 520 |
Due to the constraints of the API contract of this function it shouldn't be used |
| 521 |
in applications, please consider using \fBEVP_CipherUpdate()\fR and |
| 522 |
\&\fBEVP_CipherFinal_ex()\fR instead. |
| 523 |
.IP \fBEVP_CIPHER_can_pipeline()\fR 4 |
| 524 |
.IX Item "EVP_CIPHER_can_pipeline()" |
| 525 |
This function checks if a \fBEVP_CIPHER\fR fetched using \fBEVP_CIPHER_fetch()\fR supports |
| 526 |
cipher pipelining. If the cipher supports pipelining, it returns 1, otherwise 0. |
| 527 |
This function will return 0 for non-fetched ciphers such as \fBEVP_aes_128_gcm()\fR. |
| 528 |
There are currently no built-in ciphers that support pipelining. |
| 529 |
.Sp |
| 530 |
Cipher pipelining support allows an application to submit multiple chunks of |
| 531 |
data in one set of \fBEVP_CipherUpdate()\fR/EVP_CipherFinal calls, thereby allowing |
| 532 |
the provided implementation to take advantage of parallel computing. This is |
| 533 |
beneficial for hardware accelerators as pipeline amortizes the latency over |
| 534 |
multiple chunks. |
| 535 |
.Sp |
| 536 |
For non-fetched ciphers, \fBEVP_CipherPipelineEncryptInit()\fR or |
| 537 |
\&\fBEVP_CipherPipelineDecryptInit()\fR may be directly called, which will perform a |
| 538 |
fetch and return an error if a pipeline supported implementation is not found. |
| 539 |
.IP "\fBEVP_CipherPipelineEncryptInit()\fR, \fBEVP_CipherPipelineDecryptInit()\fR, \fBEVP_CipherPipelineUpdate()\fR and \fBEVP_CipherPipelineFinal()\fR" 4 |
| 540 |
.IX Item "EVP_CipherPipelineEncryptInit(), EVP_CipherPipelineDecryptInit(), EVP_CipherPipelineUpdate() and EVP_CipherPipelineFinal()" |
| 541 |
These functions can be used to perform multiple encryption or decryption |
| 542 |
operations in parallel. \fBEVP_CIPHER_can_pipeline()\fR may be called to check if the |
| 543 |
cipher supports pipelining. These functions are analogous to |
| 544 |
\&\fBEVP_EncryptInit_ex2()\fR, \fBEVP_DecryptInit_ex2()\fR, \fBEVP_CipherUpdate()\fR and |
| 545 |
\&\fBEVP_CipherFinal()\fR but take an array of pointers for iv, input and output buffers. |
| 546 |
.Sp |
| 547 |
The \fIkey\fR, of length \fIkeylen\fR, is the symmetric key to use. The \fInumpipes\fR |
| 548 |
parameter specifies the number of parallel operations to perform. The |
| 549 |
\&\fInumpipes\fR cannot exceed \fBEVP_MAX_PIPES\fR. The \fIiv\fR parameter is an array of |
| 550 |
buffer pointers, containing IVs. The array size must be equal to \fInumpipes\fR. |
| 551 |
The size of each IV buffer must be equal to \fIivlen\fR. When IV is not provided, |
| 552 |
\&\fIiv\fR must be NULL, rather than an array of NULL pointers. The \fIin\fR |
| 553 |
parameters takes an array of buffer pointers, each pointing to a buffer |
| 554 |
containing the input data. The buffers can be of different sizes. The \fIinl\fR |
| 555 |
parameter is an array of size_t, each specifying the size of the corresponding |
| 556 |
input buffer. The \fIout\fR and \fIoutm\fR parameters are arrays of buffer pointers, |
| 557 |
each pointing to a buffer where the output data will be written. The \fIoutsize\fR |
| 558 |
parameter is an array of size_t, each specifying the size of the corresponding |
| 559 |
output buffer. The \fIoutl\fR parameter is an array of size_t which will be updated |
| 560 |
with the size of the output data written to the corresponding output buffer. |
| 561 |
For size requirement of the output buffers, see the description of \fBEVP_CipherUpdate()\fR. |
| 562 |
.Sp |
| 563 |
The \fBEVP_CipherPipelineUpdate()\fR function can be called multiple times to encrypt |
| 564 |
successive blocks of data. For AAD data, the \fIout\fR, and \fIoutsize\fR parameter |
| 565 |
should be NULL, rather than an array of NULL pointers. |
| 566 |
.IP "\fBEVP_get_cipherbyname()\fR, \fBEVP_get_cipherbynid()\fR and \fBEVP_get_cipherbyobj()\fR" 4 |
| 567 |
.IX Item "EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()" |
| 568 |
Returns an \fBEVP_CIPHER\fR structure when passed a cipher name, a cipher \fBNID\fR or |
| 569 |
an \fBASN1_OBJECT\fR structure respectively. |
| 570 |
.Sp |
| 571 |
\&\fBEVP_get_cipherbyname()\fR will return NULL for algorithms such as "AES\-128\-SIV", |
| 572 |
"AES\-128\-CBC\-CTS" and "CAMELLIA\-128\-CBC\-CTS" which were previously only |
| 573 |
accessible via low level interfaces. |
| 574 |
.Sp |
| 575 |
The \fBEVP_get_cipherbyname()\fR function is present for backwards compatibility with |
| 576 |
OpenSSL prior to version 3 and is different to the \fBEVP_CIPHER_fetch()\fR function |
| 577 |
since it does not attempt to "fetch" an implementation of the cipher. |
| 578 |
Additionally, it only knows about ciphers that are built-in to OpenSSL and have |
| 579 |
an associated NID. Similarly \fBEVP_get_cipherbynid()\fR and \fBEVP_get_cipherbyobj()\fR |
| 580 |
also return objects without an associated implementation. |
| 581 |
.Sp |
| 582 |
When the cipher objects returned by these functions are used (such as in a call |
| 583 |
to \fBEVP_EncryptInit_ex()\fR) an implementation of the cipher will be implicitly |
| 584 |
fetched from the loaded providers. This fetch could fail if no suitable |
| 585 |
implementation is available. Use \fBEVP_CIPHER_fetch()\fR instead to explicitly fetch |
| 586 |
the algorithm and an associated implementation from a provider. |
| 587 |
.Sp |
| 588 |
See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for more information about fetching. |
| 589 |
.Sp |
| 590 |
The cipher objects returned from these functions do not need to be freed with |
| 591 |
\&\fBEVP_CIPHER_free()\fR. |
| 592 |
.IP "\fBEVP_CIPHER_get_nid()\fR and \fBEVP_CIPHER_CTX_get_nid()\fR" 4 |
| 593 |
.IX Item "EVP_CIPHER_get_nid() and EVP_CIPHER_CTX_get_nid()" |
| 594 |
Return the NID of a cipher when passed an \fBEVP_CIPHER\fR or \fBEVP_CIPHER_CTX\fR |
| 595 |
structure. The actual NID value is an internal value which may not have a |
| 596 |
corresponding OBJECT IDENTIFIER. NID_undef is returned in the event that the |
| 597 |
nid is unknown or if the cipher has not been properly initialized via a call to |
| 598 |
\&\fBEVP_CipherInit\fR. |
| 599 |
.IP "\fBEVP_CIPHER_CTX_set_flags()\fR, \fBEVP_CIPHER_CTX_clear_flags()\fR and \fBEVP_CIPHER_CTX_test_flags()\fR" 4 |
| 600 |
.IX Item "EVP_CIPHER_CTX_set_flags(), EVP_CIPHER_CTX_clear_flags() and EVP_CIPHER_CTX_test_flags()" |
| 601 |
Sets, clears and tests \fIctx\fR flags. See "FLAGS" below for more information. |
| 602 |
.Sp |
| 603 |
For provided ciphers \fBEVP_CIPHER_CTX_set_flags()\fR should be called only after the |
| 604 |
fetched cipher has been assigned to the \fIctx\fR. It is recommended to use |
| 605 |
"PARAMETERS" instead. |
| 606 |
.IP \fBEVP_CIPHER_CTX_set_padding()\fR 4 |
| 607 |
.IX Item "EVP_CIPHER_CTX_set_padding()" |
| 608 |
Enables or disables padding. This function should be called after the context |
| 609 |
is set up for encryption or decryption with \fBEVP_EncryptInit_ex2()\fR, |
| 610 |
\&\fBEVP_DecryptInit_ex2()\fR, \fBEVP_CipherInit_ex2()\fR, or \fBEVP_CipherInit_SKEY()\fR. By |
| 611 |
default encryption operations are padded using standard block padding and the |
| 612 |
padding is checked and removed when decrypting. If the \fIpad\fR parameter is zero |
| 613 |
then no padding is performed, the total amount of data encrypted or decrypted |
| 614 |
must then be a multiple of the block size or an error will occur. \fIx\fR \fBMUST |
| 615 |
NOT\fR be NULL. |
| 616 |
.IP "\fBEVP_CIPHER_get_key_length()\fR and \fBEVP_CIPHER_CTX_get_key_length()\fR" 4 |
| 617 |
.IX Item "EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length()" |
| 618 |
Return the key length of a cipher when passed an \fBEVP_CIPHER\fR or |
| 619 |
\&\fBEVP_CIPHER_CTX\fR structure. The constant \fBEVP_MAX_KEY_LENGTH\fR is the maximum |
| 620 |
key length for all ciphers. Note: although \fBEVP_CIPHER_get_key_length()\fR is fixed for |
| 621 |
a given cipher, the value of \fBEVP_CIPHER_CTX_get_key_length()\fR may be different for |
| 622 |
variable key length ciphers. |
| 623 |
.IP \fBEVP_CIPHER_CTX_set_key_length()\fR 4 |
| 624 |
.IX Item "EVP_CIPHER_CTX_set_key_length()" |
| 625 |
Sets the key length of the cipher context. |
| 626 |
If the cipher is a fixed length cipher then attempting to set the key |
| 627 |
length to any value other than the fixed value is an error. |
| 628 |
.IP "\fBEVP_CIPHER_get_iv_length()\fR and \fBEVP_CIPHER_CTX_get_iv_length()\fR" 4 |
| 629 |
.IX Item "EVP_CIPHER_get_iv_length() and EVP_CIPHER_CTX_get_iv_length()" |
| 630 |
Return the IV length of a cipher when passed an \fBEVP_CIPHER\fR or |
| 631 |
\&\fBEVP_CIPHER_CTX\fR. It will return zero if the cipher does not use an IV, if |
| 632 |
the cipher has not yet been initialized within the \fBEVP_CIPHER_CTX\fR, or if the |
| 633 |
passed cipher is NULL. The constant \fBEVP_MAX_IV_LENGTH\fR is the maximum IV |
| 634 |
length for all ciphers. |
| 635 |
.IP \fBEVP_CIPHER_CTX_get_tag_length()\fR 4 |
| 636 |
.IX Item "EVP_CIPHER_CTX_get_tag_length()" |
| 637 |
Returns the tag length of an AEAD cipher when passed a \fBEVP_CIPHER_CTX\fR. It will |
| 638 |
return zero if the cipher does not support a tag. It returns a default value if |
| 639 |
the tag length has not been set. |
| 640 |
.IP "\fBEVP_CIPHER_get_block_size()\fR and \fBEVP_CIPHER_CTX_get_block_size()\fR" 4 |
| 641 |
.IX Item "EVP_CIPHER_get_block_size() and EVP_CIPHER_CTX_get_block_size()" |
| 642 |
Return the block size of a cipher when passed an \fBEVP_CIPHER\fR or |
| 643 |
\&\fBEVP_CIPHER_CTX\fR structure. The constant \fBEVP_MAX_BLOCK_LENGTH\fR is also the |
| 644 |
maximum block length for all ciphers. |
| 645 |
A value of 0 is returned if, with \fBEVP_CIPHER_get_block_size()\fR, the cipher |
| 646 |
\&\fIe\fR is NULL, or, with \fBEVP_CIPHER_CTX_get_block_size()\fR, the context |
| 647 |
\&\fIctx\fR is NULL or has not been properly initialized with a call to |
| 648 |
\&\fBEVP_CipherInit\fR. |
| 649 |
.IP "\fBEVP_CIPHER_get_type()\fR and \fBEVP_CIPHER_CTX_get_type()\fR" 4 |
| 650 |
.IX Item "EVP_CIPHER_get_type() and EVP_CIPHER_CTX_get_type()" |
| 651 |
Return the type of the passed cipher or context. This "type" is the actual NID |
| 652 |
of the cipher OBJECT IDENTIFIER and as such it ignores the cipher parameters |
| 653 |
(40 bit RC2 and 128 bit RC2 have the same NID). If the cipher does not have an |
| 654 |
object identifier or does not have ASN1 support this function will return |
| 655 |
\&\fBNID_undef\fR. |
| 656 |
.IP \fBEVP_CIPHER_is_a()\fR 4 |
| 657 |
.IX Item "EVP_CIPHER_is_a()" |
| 658 |
Returns 1 if \fIcipher\fR is an implementation of an algorithm that's identifiable |
| 659 |
with \fIname\fR, otherwise 0. If \fIcipher\fR is a legacy cipher (it's the return |
| 660 |
value from the likes of \fBEVP_aes128()\fR rather than the result of an |
| 661 |
\&\fBEVP_CIPHER_fetch()\fR), only cipher names registered with the default library |
| 662 |
context (see \fBOSSL_LIB_CTX\fR\|(3)) will be considered. |
| 663 |
.IP "\fBEVP_CIPHER_get0_name()\fR and \fBEVP_CIPHER_CTX_get0_name()\fR" 4 |
| 664 |
.IX Item "EVP_CIPHER_get0_name() and EVP_CIPHER_CTX_get0_name()" |
| 665 |
Return the name of the passed cipher or context. For fetched ciphers with |
| 666 |
multiple names, only one of them is returned. See also \fBEVP_CIPHER_names_do_all()\fR. |
| 667 |
\&\fIcipher\fR \fBMUST NOT\fR be NULL. |
| 668 |
.IP \fBEVP_CIPHER_names_do_all()\fR 4 |
| 669 |
.IX Item "EVP_CIPHER_names_do_all()" |
| 670 |
Traverses all names for the \fIcipher\fR, and calls \fIfn\fR with each name and |
| 671 |
\&\fIdata\fR. This is only useful with fetched \fBEVP_CIPHER\fRs. |
| 672 |
.IP \fBEVP_CIPHER_get0_description()\fR 4 |
| 673 |
.IX Item "EVP_CIPHER_get0_description()" |
| 674 |
Returns a description of the cipher, meant for display and human consumption. |
| 675 |
The description is at the discretion of the cipher implementation. |
| 676 |
.IP \fBEVP_CIPHER_get0_provider()\fR 4 |
| 677 |
.IX Item "EVP_CIPHER_get0_provider()" |
| 678 |
Returns an \fBOSSL_PROVIDER\fR pointer to the provider that implements the given |
| 679 |
\&\fBEVP_CIPHER\fR. |
| 680 |
.IP \fBEVP_CIPHER_CTX_get0_cipher()\fR 4 |
| 681 |
.IX Item "EVP_CIPHER_CTX_get0_cipher()" |
| 682 |
Returns the \fBEVP_CIPHER\fR structure when passed an \fBEVP_CIPHER_CTX\fR structure. |
| 683 |
\&\fBEVP_CIPHER_CTX_get1_cipher()\fR is the same except the ownership is passed to |
| 684 |
the caller. Both functions return NULL on error. |
| 685 |
.IP "\fBEVP_CIPHER_get_mode()\fR and \fBEVP_CIPHER_CTX_get_mode()\fR" 4 |
| 686 |
.IX Item "EVP_CIPHER_get_mode() and EVP_CIPHER_CTX_get_mode()" |
| 687 |
Return the block cipher mode: |
| 688 |
EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, |
| 689 |
EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, |
| 690 |
EVP_CIPH_WRAP_MODE, EVP_CIPH_OCB_MODE or EVP_CIPH_SIV_MODE. |
| 691 |
If the cipher is a stream cipher then EVP_CIPH_STREAM_CIPHER is returned. |
| 692 |
.IP \fBEVP_CIPHER_get_flags()\fR 4 |
| 693 |
.IX Item "EVP_CIPHER_get_flags()" |
| 694 |
Returns any flags associated with the cipher. See "FLAGS" |
| 695 |
for a list of currently defined flags. |
| 696 |
.IP "\fBEVP_CIPHER_CTX_get_num()\fR and \fBEVP_CIPHER_CTX_set_num()\fR" 4 |
| 697 |
.IX Item "EVP_CIPHER_CTX_get_num() and EVP_CIPHER_CTX_set_num()" |
| 698 |
Gets or sets the cipher specific "num" parameter for the associated \fIctx\fR. |
| 699 |
Built-in ciphers typically use this to track how much of the current underlying block |
| 700 |
has been "used" already. |
| 701 |
.IP \fBEVP_CIPHER_CTX_is_encrypting()\fR 4 |
| 702 |
.IX Item "EVP_CIPHER_CTX_is_encrypting()" |
| 703 |
Reports whether the \fIctx\fR is being used for encryption or decryption. |
| 704 |
.IP \fBEVP_CIPHER_CTX_flags()\fR 4 |
| 705 |
.IX Item "EVP_CIPHER_CTX_flags()" |
| 706 |
A deprecated macro calling \f(CW\*(C`EVP_CIPHER_get_flags(EVP_CIPHER_CTX_get0_cipher(ctx))\*(C'\fR. |
| 707 |
Do not use. |
| 708 |
.IP \fBEVP_CIPHER_param_to_asn1()\fR 4 |
| 709 |
.IX Item "EVP_CIPHER_param_to_asn1()" |
| 710 |
Sets the AlgorithmIdentifier "parameter" based on the passed cipher. This will |
| 711 |
typically include any parameters and an IV. The cipher IV (if any) must be set |
| 712 |
when this call is made. This call should be made before the cipher is actually |
| 713 |
"used" (before any \fBEVP_EncryptUpdate()\fR, \fBEVP_DecryptUpdate()\fR calls for example). |
| 714 |
This function may fail if the cipher does not have any ASN1 support, or if an |
| 715 |
uninitialized cipher is passed to it. |
| 716 |
.IP \fBEVP_CIPHER_asn1_to_param()\fR 4 |
| 717 |
.IX Item "EVP_CIPHER_asn1_to_param()" |
| 718 |
Sets the cipher parameters based on an ASN1 AlgorithmIdentifier "parameter". |
| 719 |
The precise effect depends on the cipher. In the case of \fBRC2\fR, for example, |
| 720 |
it will set the IV and effective key length. |
| 721 |
This function should be called after the base cipher type is set but before |
| 722 |
the key is set. For example \fBEVP_CipherInit()\fR will be called with the IV and |
| 723 |
key set to NULL, \fBEVP_CIPHER_asn1_to_param()\fR will be called and finally |
| 724 |
\&\fBEVP_CipherInit()\fR again with all parameters except the key set to NULL. It is |
| 725 |
possible for this function to fail if the cipher does not have any ASN1 support |
| 726 |
or the parameters cannot be set (for example the RC2 effective key length |
| 727 |
is not supported. |
| 728 |
.IP \fBEVP_CIPHER_CTX_rand_key()\fR 4 |
| 729 |
.IX Item "EVP_CIPHER_CTX_rand_key()" |
| 730 |
Generates a random key of the appropriate length based on the cipher context. |
| 731 |
The \fBEVP_CIPHER\fR can provide its own random key generation routine to support |
| 732 |
keys of a specific form. \fIkey\fR must point to a buffer at least as big as the |
| 733 |
value returned by \fBEVP_CIPHER_CTX_get_key_length()\fR. |
| 734 |
.IP \fBEVP_CIPHER_do_all_provided()\fR 4 |
| 735 |
.IX Item "EVP_CIPHER_do_all_provided()" |
| 736 |
Traverses all ciphers implemented by all activated providers in the given |
| 737 |
library context \fIlibctx\fR, and for each of the implementations, calls the given |
| 738 |
function \fIfn\fR with the implementation method and the given \fIarg\fR as argument. |
| 739 |
.SH PARAMETERS |
| 740 |
.IX Header "PARAMETERS" |
| 741 |
See \fBOSSL_PARAM\fR\|(3) for information about passing parameters. |
| 742 |
.SS "Gettable EVP_CIPHER parameters" |
| 743 |
.IX Subsection "Gettable EVP_CIPHER parameters" |
| 744 |
When \fBEVP_CIPHER_fetch()\fR is called it internally calls \fBEVP_CIPHER_get_params()\fR |
| 745 |
and caches the results. |
| 746 |
.PP |
| 747 |
\&\fBEVP_CIPHER_get_params()\fR can be used with the following \fBOSSL_PARAM\fR\|(3) keys: |
| 748 |
.IP """mode"" (\fBOSSL_CIPHER_PARAM_MODE\fR) <unsigned integer>" 4 |
| 749 |
.IX Item """mode"" (OSSL_CIPHER_PARAM_MODE) <unsigned integer>" |
| 750 |
Gets the mode for the associated cipher algorithm \fIcipher\fR. |
| 751 |
See "\fBEVP_CIPHER_get_mode()\fR and \fBEVP_CIPHER_CTX_get_mode()\fR" for a list of valid modes. |
| 752 |
Use \fBEVP_CIPHER_get_mode()\fR to retrieve the cached value. |
| 753 |
.IP """keylen"" (\fBOSSL_CIPHER_PARAM_KEYLEN\fR) <unsigned integer>" 4 |
| 754 |
.IX Item """keylen"" (OSSL_CIPHER_PARAM_KEYLEN) <unsigned integer>" |
| 755 |
Gets the key length for the associated cipher algorithm \fIcipher\fR. |
| 756 |
Use \fBEVP_CIPHER_get_key_length()\fR to retrieve the cached value. |
| 757 |
.IP """ivlen"" (\fBOSSL_CIPHER_PARAM_IVLEN\fR) <unsigned integer>" 4 |
| 758 |
.IX Item """ivlen"" (OSSL_CIPHER_PARAM_IVLEN) <unsigned integer>" |
| 759 |
Gets the IV length for the associated cipher algorithm \fIcipher\fR. |
| 760 |
Use \fBEVP_CIPHER_get_iv_length()\fR to retrieve the cached value. |
| 761 |
.IP """blocksize"" (\fBOSSL_CIPHER_PARAM_BLOCK_SIZE\fR) <unsigned integer>" 4 |
| 762 |
.IX Item """blocksize"" (OSSL_CIPHER_PARAM_BLOCK_SIZE) <unsigned integer>" |
| 763 |
Gets the block size for the associated cipher algorithm \fIcipher\fR. |
| 764 |
The block size should be 1 for stream ciphers. |
| 765 |
Note that the block size for a cipher may be different to the block size for |
| 766 |
the underlying encryption/decryption primitive. |
| 767 |
For example AES in CTR mode has a block size of 1 (because it operates like a |
| 768 |
stream cipher), even though AES has a block size of 16. |
| 769 |
Use \fBEVP_CIPHER_get_block_size()\fR to retrieve the cached value. |
| 770 |
.IP """aead"" (\fBOSSL_CIPHER_PARAM_AEAD\fR) <integer>" 4 |
| 771 |
.IX Item """aead"" (OSSL_CIPHER_PARAM_AEAD) <integer>" |
| 772 |
Gets 1 if this is an AEAD cipher algorithm, otherwise it gets 0. |
| 773 |
Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_AEAD_CIPHER) to retrieve the |
| 774 |
cached value. |
| 775 |
.IP """custom-iv"" (\fBOSSL_CIPHER_PARAM_CUSTOM_IV\fR) <integer>" 4 |
| 776 |
.IX Item """custom-iv"" (OSSL_CIPHER_PARAM_CUSTOM_IV) <integer>" |
| 777 |
Gets 1 if the cipher algorithm \fIcipher\fR has a custom IV, otherwise it gets 0. |
| 778 |
Storing and initializing the IV is left entirely to the implementation, if a |
| 779 |
custom IV is used. |
| 780 |
Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_CUSTOM_IV) to retrieve the |
| 781 |
cached value. |
| 782 |
.IP """cts"" (\fBOSSL_CIPHER_PARAM_CTS\fR) <integer>" 4 |
| 783 |
.IX Item """cts"" (OSSL_CIPHER_PARAM_CTS) <integer>" |
| 784 |
Gets 1 if the cipher algorithm \fIcipher\fR uses ciphertext stealing, |
| 785 |
otherwise it gets 0. |
| 786 |
This is currently used to indicate that the cipher is a one shot that only |
| 787 |
allows a single call to \fBEVP_CipherUpdate()\fR. |
| 788 |
Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_CTS) to retrieve the |
| 789 |
cached value. |
| 790 |
.IP """tls-multi"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK\fR) <integer>" 4 |
| 791 |
.IX Item """tls-multi"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK) <integer>" |
| 792 |
Gets 1 if the cipher algorithm \fIcipher\fR supports interleaving of crypto blocks, |
| 793 |
otherwise it gets 0. The interleaving is an optimization only applicable to certain |
| 794 |
TLS ciphers. |
| 795 |
Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK) to retrieve the |
| 796 |
cached value. |
| 797 |
.IP """has-randkey"" (\fBOSSL_CIPHER_PARAM_HAS_RANDKEY\fR) <integer>" 4 |
| 798 |
.IX Item """has-randkey"" (OSSL_CIPHER_PARAM_HAS_RANDKEY) <integer>" |
| 799 |
Gets 1 if the cipher algorithm \fIcipher\fR supports the gettable EVP_CIPHER_CTX |
| 800 |
parameter \fBOSSL_CIPHER_PARAM_RANDOM_KEY\fR. Only DES and 3DES set this to 1, |
| 801 |
all other OpenSSL ciphers return 0. |
| 802 |
.IP """decrypt-only"" (\fBOSSL_CIPHER_PARAM_DECRYPT_ONLY) <integer\fR" 4 |
| 803 |
.IX Item """decrypt-only"" (OSSL_CIPHER_PARAM_DECRYPT_ONLY) <integer" |
| 804 |
Gets 1 if the cipher algorithm \fIcipher\fR implementation supports only |
| 805 |
the decryption operation such as the 3DES ciphers in the fips provider. |
| 806 |
Otherwise gets 0 or the parameter might not be present at all. |
| 807 |
.SS "Gettable and Settable EVP_CIPHER_CTX parameters" |
| 808 |
.IX Subsection "Gettable and Settable EVP_CIPHER_CTX parameters" |
| 809 |
The following \fBOSSL_PARAM\fR\|(3) keys can be used with both \fBEVP_CIPHER_CTX_get_params()\fR |
| 810 |
and \fBEVP_CIPHER_CTX_set_params()\fR. |
| 811 |
.IP """padding"" (\fBOSSL_CIPHER_PARAM_PADDING\fR) <unsigned integer>" 4 |
| 812 |
.IX Item """padding"" (OSSL_CIPHER_PARAM_PADDING) <unsigned integer>" |
| 813 |
Gets or sets the padding mode for the cipher context \fIctx\fR. |
| 814 |
Padding is enabled if the value is 1, and disabled if the value is 0. |
| 815 |
See also \fBEVP_CIPHER_CTX_set_padding()\fR. |
| 816 |
.IP """num"" (\fBOSSL_CIPHER_PARAM_NUM\fR) <unsigned integer>" 4 |
| 817 |
.IX Item """num"" (OSSL_CIPHER_PARAM_NUM) <unsigned integer>" |
| 818 |
Gets or sets the cipher specific "num" parameter for the cipher context \fIctx\fR. |
| 819 |
Built-in ciphers typically use this to track how much of the current underlying |
| 820 |
block has been "used" already. |
| 821 |
See also \fBEVP_CIPHER_CTX_get_num()\fR and \fBEVP_CIPHER_CTX_set_num()\fR. |
| 822 |
.IP """keylen"" (\fBOSSL_CIPHER_PARAM_KEYLEN\fR) <unsigned integer>" 4 |
| 823 |
.IX Item """keylen"" (OSSL_CIPHER_PARAM_KEYLEN) <unsigned integer>" |
| 824 |
Gets or sets the key length for the cipher context \fIctx\fR. |
| 825 |
The length of the "keylen" parameter should not exceed that of a \fBsize_t\fR. |
| 826 |
See also \fBEVP_CIPHER_CTX_get_key_length()\fR and \fBEVP_CIPHER_CTX_set_key_length()\fR. |
| 827 |
.IP """tag"" (\fBOSSL_CIPHER_PARAM_AEAD_TAG\fR) <octet string>" 4 |
| 828 |
.IX Item """tag"" (OSSL_CIPHER_PARAM_AEAD_TAG) <octet string>" |
| 829 |
Gets or sets the AEAD tag for the associated cipher context \fIctx\fR. |
| 830 |
See "AEAD INTERFACE" in \fBEVP_EncryptInit\fR\|(3). |
| 831 |
.IP """pipeline-tag"" (\fBOSSL_CIPHER_PARAM_PIPELINE_AEAD_TAG\fR) <octet ptr>" 4 |
| 832 |
.IX Item """pipeline-tag"" (OSSL_CIPHER_PARAM_PIPELINE_AEAD_TAG) <octet ptr>" |
| 833 |
Gets or sets the AEAD tag when using cipher pipelining. The pointer must |
| 834 |
point to an array of buffers, where the aead tag will be read from or written to. |
| 835 |
The array size must be equal to \fInumpipes\fR used in |
| 836 |
\&\fBEVP_CipherPipelineEncryptInit()\fR or \fBEVP_CipherPipelineDecryptInit()\fR. |
| 837 |
.IP """keybits"" (\fBOSSL_CIPHER_PARAM_RC2_KEYBITS\fR) <unsigned integer>" 4 |
| 838 |
.IX Item """keybits"" (OSSL_CIPHER_PARAM_RC2_KEYBITS) <unsigned integer>" |
| 839 |
Gets or sets the effective keybits used for a RC2 cipher. |
| 840 |
The length of the "keybits" parameter should not exceed that of a \fBsize_t\fR. |
| 841 |
.IP """rounds"" (\fBOSSL_CIPHER_PARAM_ROUNDS\fR) <unsigned integer>" 4 |
| 842 |
.IX Item """rounds"" (OSSL_CIPHER_PARAM_ROUNDS) <unsigned integer>" |
| 843 |
Gets or sets the number of rounds to be used for a cipher. |
| 844 |
This is used by the RC5 cipher. |
| 845 |
.IP """algorithm-id"" (\fBOSSL_CIPHER_PARAM_ALGORITHM_ID\fR) <octet string>" 4 |
| 846 |
.IX Item """algorithm-id"" (OSSL_CIPHER_PARAM_ALGORITHM_ID) <octet string>" |
| 847 |
Used to get the DER encoded AlgorithmIdentifier from the cipher |
| 848 |
implementation. Functions like \fBEVP_PKEY_CTX_get_algor\fR\|(3) use this |
| 849 |
parameter. |
| 850 |
.IP """algorithm-id-params"" (\fBOSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS\fR) <octet string>" 4 |
| 851 |
.IX Item """algorithm-id-params"" (OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS) <octet string>" |
| 852 |
Used to pass the DER encoded AlgorithmIdentifier parameter to or from |
| 853 |
the cipher implementation. |
| 854 |
Functions like \fBEVP_CIPHER_CTX_set_algor_params\fR\|(3) and |
| 855 |
\&\fBEVP_CIPHER_CTX_get_algor_params\fR\|(3) use this parameter. |
| 856 |
.IP """alg_id_params"" (\fBOSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS_OLD\fR) <octet string>" 4 |
| 857 |
.IX Item """alg_id_params"" (OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS_OLD) <octet string>" |
| 858 |
An deprecated alias for "algorithm-id-params", only used by |
| 859 |
\&\fBEVP_CIPHER_param_to_asn1\fR\|(3) and \fBEVP_CIPHER_asn1_to_param\fR\|(3). |
| 860 |
.IP """cts_mode"" (\fBOSSL_CIPHER_PARAM_CTS_MODE\fR) <UTF8 string>" 4 |
| 861 |
.IX Item """cts_mode"" (OSSL_CIPHER_PARAM_CTS_MODE) <UTF8 string>" |
| 862 |
Gets or sets the cipher text stealing mode. For all modes the output size is the |
| 863 |
same as the input size. The input length must be greater than or equal to the |
| 864 |
block size. (The block size for AES and CAMELLIA is 16 bytes). |
| 865 |
.Sp |
| 866 |
Valid values for the mode are: |
| 867 |
.RS 4 |
| 868 |
.IP """CS1""" 4 |
| 869 |
.IX Item """CS1""" |
| 870 |
The NIST variant of cipher text stealing. |
| 871 |
For input lengths that are multiples of the block size it is equivalent to |
| 872 |
using a "AES-XXX-CBC" or "CAMELLIA-XXX-CBC" cipher otherwise the second last |
| 873 |
cipher text block is a partial block. |
| 874 |
.IP """CS2""" 4 |
| 875 |
.IX Item """CS2""" |
| 876 |
For input lengths that are multiples of the block size it is equivalent to |
| 877 |
using a "AES-XXX-CBC" or "CAMELLIA-XXX-CBC" cipher, otherwise it is the same as |
| 878 |
"CS3" mode. |
| 879 |
.IP """CS3""" 4 |
| 880 |
.IX Item """CS3""" |
| 881 |
The Kerberos5 variant of cipher text stealing which always swaps the last |
| 882 |
cipher text block with the previous block (which may be a partial or full block |
| 883 |
depending on the input length). If the input length is exactly one full block |
| 884 |
then this is equivalent to using a "AES-XXX-CBC" or "CAMELLIA-XXX-CBC" cipher. |
| 885 |
.RE |
| 886 |
.RS 4 |
| 887 |
.Sp |
| 888 |
The default is "CS1". |
| 889 |
This is only supported for "AES\-128\-CBC\-CTS", "AES\-192\-CBC\-CTS", "AES\-256\-CBC\-CTS", |
| 890 |
"CAMELLIA\-128\-CBC\-CTS", "CAMELLIA\-192\-CBC\-CTS" and "CAMELLIA\-256\-CBC\-CTS". |
| 891 |
.RE |
| 892 |
.IP """tls1multi_interleave"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\fR) <unsigned integer>" 4 |
| 893 |
.IX Item """tls1multi_interleave"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE) <unsigned integer>" |
| 894 |
Sets or gets the number of records being sent in one go for a tls1 multiblock |
| 895 |
cipher operation (either 4 or 8 records). |
| 896 |
.SS "Gettable EVP_CIPHER_CTX parameters" |
| 897 |
.IX Subsection "Gettable EVP_CIPHER_CTX parameters" |
| 898 |
The following \fBOSSL_PARAM\fR\|(3) keys can be used with \fBEVP_CIPHER_CTX_get_params()\fR: |
| 899 |
.IP """ivlen"" (\fBOSSL_CIPHER_PARAM_IVLEN\fR and <\fBOSSL_CIPHER_PARAM_AEAD_IVLEN\fR) <unsigned integer>" 4 |
| 900 |
.IX Item """ivlen"" (OSSL_CIPHER_PARAM_IVLEN and <OSSL_CIPHER_PARAM_AEAD_IVLEN) <unsigned integer>" |
| 901 |
Gets the IV length for the cipher context \fIctx\fR. |
| 902 |
The length of the "ivlen" parameter should not exceed that of a \fBsize_t\fR. |
| 903 |
See also \fBEVP_CIPHER_CTX_get_iv_length()\fR. |
| 904 |
.IP """iv"" (\fBOSSL_CIPHER_PARAM_IV\fR) <octet string OR octet ptr>" 4 |
| 905 |
.IX Item """iv"" (OSSL_CIPHER_PARAM_IV) <octet string OR octet ptr>" |
| 906 |
Gets the IV used to initialize the associated cipher context \fIctx\fR. |
| 907 |
See also \fBEVP_CIPHER_CTX_get_original_iv()\fR. |
| 908 |
.IP """updated-iv"" (\fBOSSL_CIPHER_PARAM_UPDATED_IV\fR) <octet string OR octet ptr>" 4 |
| 909 |
.IX Item """updated-iv"" (OSSL_CIPHER_PARAM_UPDATED_IV) <octet string OR octet ptr>" |
| 910 |
Gets the updated pseudo-IV state for the associated cipher context, e.g., |
| 911 |
the previous ciphertext block for CBC mode or the iteratively encrypted IV |
| 912 |
value for OFB mode. Note that octet pointer access is deprecated and is |
| 913 |
provided only for backwards compatibility with historical libcrypto APIs. |
| 914 |
See also \fBEVP_CIPHER_CTX_get_updated_iv()\fR. |
| 915 |
.IP """randkey"" (\fBOSSL_CIPHER_PARAM_RANDOM_KEY\fR) <octet string>" 4 |
| 916 |
.IX Item """randkey"" (OSSL_CIPHER_PARAM_RANDOM_KEY) <octet string>" |
| 917 |
Gets an implementation specific randomly generated key for the associated |
| 918 |
cipher context \fIctx\fR. This is currently only supported by DES and 3DES (which set |
| 919 |
the key to odd parity). |
| 920 |
.IP """taglen"" (\fBOSSL_CIPHER_PARAM_AEAD_TAGLEN\fR) <unsigned integer>" 4 |
| 921 |
.IX Item """taglen"" (OSSL_CIPHER_PARAM_AEAD_TAGLEN) <unsigned integer>" |
| 922 |
Gets the tag length to be used for an AEAD cipher for the associated cipher |
| 923 |
context \fIctx\fR. It gets a default value if it has not been set. |
| 924 |
The length of the "taglen" parameter should not exceed that of a \fBsize_t\fR. |
| 925 |
See also \fBEVP_CIPHER_CTX_get_tag_length()\fR. |
| 926 |
.IP """tlsaadpad"" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD\fR) <unsigned integer>" 4 |
| 927 |
.IX Item """tlsaadpad"" (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD) <unsigned integer>" |
| 928 |
Gets the length of the tag that will be added to a TLS record for the AEAD |
| 929 |
tag for the associated cipher context \fIctx\fR. |
| 930 |
The length of the "tlsaadpad" parameter should not exceed that of a \fBsize_t\fR. |
| 931 |
.IP """tlsivgen"" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN\fR) <octet string>" 4 |
| 932 |
.IX Item """tlsivgen"" (OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN) <octet string>" |
| 933 |
Gets the invocation field generated for encryption. |
| 934 |
Can only be called after "tlsivfixed" is set. |
| 935 |
This is only used for GCM mode. |
| 936 |
.IP """tls1multi_enclen"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN\fR) <unsigned integer>" 4 |
| 937 |
.IX Item """tls1multi_enclen"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN) <unsigned integer>" |
| 938 |
Get the total length of the record returned from the "tls1multi_enc" operation. |
| 939 |
.IP """tls1multi_maxbufsz"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE\fR) <unsigned integer>" 4 |
| 940 |
.IX Item """tls1multi_maxbufsz"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE) <unsigned integer>" |
| 941 |
Gets the maximum record length for a TLS1 multiblock cipher operation. |
| 942 |
The length of the "tls1multi_maxbufsz" parameter should not exceed that of a \fBsize_t\fR. |
| 943 |
.IP """tls1multi_aadpacklen"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN\fR) <unsigned integer>" 4 |
| 944 |
.IX Item """tls1multi_aadpacklen"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN) <unsigned integer>" |
| 945 |
Gets the result of running the "tls1multi_aad" operation. |
| 946 |
.IP """tls-mac"" (\fBOSSL_CIPHER_PARAM_TLS_MAC\fR) <octet ptr>" 4 |
| 947 |
.IX Item """tls-mac"" (OSSL_CIPHER_PARAM_TLS_MAC) <octet ptr>" |
| 948 |
Used to pass the TLS MAC data. |
| 949 |
.IP """fips-indicator"" (\fBOSSL_CIPHER_PARAM_FIPS_APPROVED_INDICATOR\fR) <integer>" 4 |
| 950 |
.IX Item """fips-indicator"" (OSSL_CIPHER_PARAM_FIPS_APPROVED_INDICATOR) <integer>" |
| 951 |
This option is used by the OpenSSL FIPS provider. |
| 952 |
.Sp |
| 953 |
A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. |
| 954 |
This may be used after calling a cipher final operation such as |
| 955 |
\&\fBEVP_EncryptFinal_ex()\fR. It may return 0 if the "encrypt-check" option is set to 0. |
| 956 |
.IP """iv-generated"" (\fBOSSL_CIPHER_PARAM_AEAD_IV_GENERATED\fR) <unsigned integer>" 4 |
| 957 |
.IX Item """iv-generated"" (OSSL_CIPHER_PARAM_AEAD_IV_GENERATED) <unsigned integer>" |
| 958 |
An indicator that returns 1 if an IV was generated internally during encryption, |
| 959 |
or O otherwise. |
| 960 |
This may be used by GCM ciphers after calling a cipher final operation such |
| 961 |
as \fBEVP_EncryptFinal_ex()\fR. |
| 962 |
GCM should generate an IV internally if the IV is not specified during a |
| 963 |
cipher initialisation call such as \fBEVP_CipherInit_ex()\fR. |
| 964 |
See FIPS 140\-3 IG C.H for information related to IV requirements. |
| 965 |
.SS "Settable EVP_CIPHER_CTX parameters" |
| 966 |
.IX Subsection "Settable EVP_CIPHER_CTX parameters" |
| 967 |
The following \fBOSSL_PARAM\fR\|(3) keys can be used with \fBEVP_CIPHER_CTX_set_params()\fR: |
| 968 |
.IP """mackey"" (\fBOSSL_CIPHER_PARAM_AEAD_MAC_KEY\fR) <octet string>" 4 |
| 969 |
.IX Item """mackey"" (OSSL_CIPHER_PARAM_AEAD_MAC_KEY) <octet string>" |
| 970 |
Sets the MAC key used by composite AEAD ciphers such as AES\-CBC\-HMAC\-SHA256. |
| 971 |
.IP """speed"" (\fBOSSL_CIPHER_PARAM_SPEED\fR) <unsigned integer>" 4 |
| 972 |
.IX Item """speed"" (OSSL_CIPHER_PARAM_SPEED) <unsigned integer>" |
| 973 |
Sets the speed option for the associated cipher context. This is only supported |
| 974 |
by AES SIV ciphers which disallow multiple operations by default. |
| 975 |
Setting "speed" to 1 allows another encrypt or decrypt operation to be |
| 976 |
performed. This is used for performance testing. |
| 977 |
.IP """use-bits"" (\fBOSSL_CIPHER_PARAM_USE_BITS\fR) <unsigned integer>" 4 |
| 978 |
.IX Item """use-bits"" (OSSL_CIPHER_PARAM_USE_BITS) <unsigned integer>" |
| 979 |
Determines if the input length \fIinl\fR passed to \fBEVP_EncryptUpdate()\fR, |
| 980 |
\&\fBEVP_DecryptUpdate()\fR and \fBEVP_CipherUpdate()\fR is the number of bits or number of bytes. |
| 981 |
Setting "use-bits" to 1 uses bits. The default is in bytes. |
| 982 |
This is only used for \fBCFB1\fR ciphers. |
| 983 |
.Sp |
| 984 |
This can be set using EVP_CIPHER_CTX_set_flags(ctx, EVP_CIPH_FLAG_LENGTH_BITS). |
| 985 |
.IP """tls-version"" (\fBOSSL_CIPHER_PARAM_TLS_VERSION\fR) <integer>" 4 |
| 986 |
.IX Item """tls-version"" (OSSL_CIPHER_PARAM_TLS_VERSION) <integer>" |
| 987 |
Sets the TLS version. |
| 988 |
.IP """tls-mac-size"" (\fBOSSL_CIPHER_PARAM_TLS_MAC_SIZE\fR) <unsigned integer>" 4 |
| 989 |
.IX Item """tls-mac-size"" (OSSL_CIPHER_PARAM_TLS_MAC_SIZE) <unsigned integer>" |
| 990 |
Set the TLS MAC size. |
| 991 |
.IP """tlsaad"" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_AAD\fR) <octet string>" 4 |
| 992 |
.IX Item """tlsaad"" (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD) <octet string>" |
| 993 |
Sets TLSv1.2 AAD information for the associated cipher context \fIctx\fR. |
| 994 |
TLSv1.2 AAD information is always 13 bytes in length and is as defined for the |
| 995 |
"additional_data" field described in section 6.2.3.3 of RFC5246. |
| 996 |
.IP """tlsivfixed"" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED\fR) <octet string>" 4 |
| 997 |
.IX Item """tlsivfixed"" (OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED) <octet string>" |
| 998 |
Sets the fixed portion of an IV for an AEAD cipher used in a TLS record |
| 999 |
encryption/ decryption for the associated cipher context. |
| 1000 |
TLS record encryption/decryption always occurs "in place" so that the input and |
| 1001 |
output buffers are always the same memory location. |
| 1002 |
AEAD IVs in TLSv1.2 consist of an implicit "fixed" part and an explicit part |
| 1003 |
that varies with every record. |
| 1004 |
Setting a TLS fixed IV changes a cipher to encrypt/decrypt TLS records. |
| 1005 |
TLS records are encrypted/decrypted using a single OSSL_FUNC_cipher_cipher call per |
| 1006 |
record. |
| 1007 |
For a record decryption the first bytes of the input buffer will be the explicit |
| 1008 |
part of the IV and the final bytes of the input buffer will be the AEAD tag. |
| 1009 |
The length of the explicit part of the IV and the tag length will depend on the |
| 1010 |
cipher in use and will be defined in the RFC for the relevant ciphersuite. |
| 1011 |
In order to allow for "in place" decryption the plaintext output should be |
| 1012 |
written to the same location in the output buffer that the ciphertext payload |
| 1013 |
was read from, i.e. immediately after the explicit IV. |
| 1014 |
.Sp |
| 1015 |
When encrypting a record the first bytes of the input buffer should be empty to |
| 1016 |
allow space for the explicit IV, as will the final bytes where the tag will |
| 1017 |
be written. |
| 1018 |
The length of the input buffer will include the length of the explicit IV, the |
| 1019 |
payload, and the tag bytes. |
| 1020 |
The cipher implementation should generate the explicit IV and write it to the |
| 1021 |
beginning of the output buffer, do "in place" encryption of the payload and |
| 1022 |
write that to the output buffer, and finally add the tag onto the end of the |
| 1023 |
output buffer. |
| 1024 |
.Sp |
| 1025 |
Whether encrypting or decrypting the value written to \fI*outl\fR in the |
| 1026 |
OSSL_FUNC_cipher_cipher call should be the length of the payload excluding the explicit |
| 1027 |
IV length and the tag length. |
| 1028 |
.IP """tlsivinv"" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV\fR) <octet string>" 4 |
| 1029 |
.IX Item """tlsivinv"" (OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV) <octet string>" |
| 1030 |
Sets the invocation field used for decryption. |
| 1031 |
Can only be called after "tlsivfixed" is set. |
| 1032 |
This is only used for GCM mode. |
| 1033 |
.IP """tls1multi_enc"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC\fR) <octet string>" 4 |
| 1034 |
.IX Item """tls1multi_enc"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC) <octet string>" |
| 1035 |
Triggers a multiblock TLS1 encrypt operation for a TLS1 aware cipher that |
| 1036 |
supports sending 4 or 8 records in one go. |
| 1037 |
The cipher performs both the MAC and encrypt stages and constructs the record |
| 1038 |
headers itself. |
| 1039 |
"tls1multi_enc" supplies the output buffer for the encrypt operation, |
| 1040 |
"tls1multi_encin" & "tls1multi_interleave" must also be set in order to supply |
| 1041 |
values to the encrypt operation. |
| 1042 |
.IP """tls1multi_encin"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN\fR) <octet string>" 4 |
| 1043 |
.IX Item """tls1multi_encin"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN) <octet string>" |
| 1044 |
Supplies the data to encrypt for a TLS1 multiblock cipher operation. |
| 1045 |
.IP """tls1multi_maxsndfrag"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT\fR) <unsigned integer>" 4 |
| 1046 |
.IX Item """tls1multi_maxsndfrag"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT) <unsigned integer>" |
| 1047 |
Sets the maximum send fragment size for a TLS1 multiblock cipher operation. |
| 1048 |
It must be set before using "tls1multi_maxbufsz". |
| 1049 |
The length of the "tls1multi_maxsndfrag" parameter should not exceed that of a \fBsize_t\fR. |
| 1050 |
.IP """tls1multi_aad"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD\fR) <octet string>" 4 |
| 1051 |
.IX Item """tls1multi_aad"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD) <octet string>" |
| 1052 |
Sets the authenticated additional data used by a TLS1 multiblock cipher operation. |
| 1053 |
The supplied data consists of 13 bytes of record data containing: |
| 1054 |
Bytes 0\-7: The sequence number of the first record |
| 1055 |
Byte 8: The record type |
| 1056 |
Byte 9\-10: The protocol version |
| 1057 |
Byte 11\-12: Input length (Always 0) |
| 1058 |
.Sp |
| 1059 |
"tls1multi_interleave" must also be set for this operation. |
| 1060 |
.IP """xts_standard"" (\fBOSSL_CIPHER_PARAM_XTS_STANDARD\fR) <UTF8 string>" 4 |
| 1061 |
.IX Item """xts_standard"" (OSSL_CIPHER_PARAM_XTS_STANDARD) <UTF8 string>" |
| 1062 |
Sets the XTS standard to use with SM4\-XTS algorithm. XTS mode has two |
| 1063 |
implementations, one is standardized in IEEE Std. 1619\-2007 and has |
| 1064 |
been widely used (e.g., XTS AES), the other is proposed recently |
| 1065 |
(GB/T 17964\-2021 implemented in May 2022) and is currently only used |
| 1066 |
in SM4. |
| 1067 |
.Sp |
| 1068 |
The main difference between them is the multiplication by the |
| 1069 |
primitive element α to calculate the tweak values. The IEEE |
| 1070 |
Std 1619\-2007 noted that the multiplication "is a left shift of each |
| 1071 |
byte by one bit with carry propagating from one byte to the next |
| 1072 |
one", which means that in each byte, the leftmost bit is the most |
| 1073 |
significant bit. But in GB/T 17964\-2021, the rightmost bit is the |
| 1074 |
most significant bit, thus the multiplication becomes a right shift |
| 1075 |
of each byte by one bit with carry propagating from one byte to the |
| 1076 |
next one. |
| 1077 |
.Sp |
| 1078 |
Valid values for the mode are: |
| 1079 |
.RS 4 |
| 1080 |
.IP """GB""" 4 |
| 1081 |
.IX Item """GB""" |
| 1082 |
The GB/T 17964\-2021 variant of SM4\-XTS algorithm. |
| 1083 |
.IP """IEEE""" 4 |
| 1084 |
.IX Item """IEEE""" |
| 1085 |
The IEEE Std. 1619\-2007 variant of SM4\-XTS algorithm. |
| 1086 |
.RE |
| 1087 |
.RS 4 |
| 1088 |
.Sp |
| 1089 |
The default value is "GB". |
| 1090 |
.RE |
| 1091 |
.IP """encrypt-check"" (\fBOSSL_CIPHER_PARAM_FIPS_ENCRYPT_CHECK\fR) <integer>" 4 |
| 1092 |
.IX Item """encrypt-check"" (OSSL_CIPHER_PARAM_FIPS_ENCRYPT_CHECK) <integer>" |
| 1093 |
This option is used by the OpenSSL FIPS provider. |
| 1094 |
.Sp |
| 1095 |
If required this parameter should be set early via an cipher encrypt init |
| 1096 |
function such as \fBEVP_EncryptInit_ex2()\fR. |
| 1097 |
The default value of 1 causes an error when an encryption operation is triggered. |
| 1098 |
Setting this to 0 will ignore the error and set the approved "fips-indicator" to |
| 1099 |
0. |
| 1100 |
This option breaks FIPS compliance if it causes the approved "fips-indicator" |
| 1101 |
to return 0. |
| 1102 |
.SH CONTROLS |
| 1103 |
.IX Header "CONTROLS" |
| 1104 |
The Mappings from \fBEVP_CIPHER_CTX_ctrl()\fR identifiers to PARAMETERS are listed |
| 1105 |
in the following section. See the "PARAMETERS" section for more details. |
| 1106 |
.PP |
| 1107 |
\&\fBEVP_CIPHER_CTX_ctrl()\fR can be used to send the following standard controls: |
| 1108 |
.IP "EVP_CTRL_AEAD_SET_IVLEN and EVP_CTRL_GET_IVLEN" 4 |
| 1109 |
.IX Item "EVP_CTRL_AEAD_SET_IVLEN and EVP_CTRL_GET_IVLEN" |
| 1110 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR and |
| 1111 |
\&\fBEVP_CIPHER_CTX_get_params()\fR get called with an \fBOSSL_PARAM\fR\|(3) item with the |
| 1112 |
key "ivlen" (\fBOSSL_CIPHER_PARAM_IVLEN\fR). |
| 1113 |
.IP EVP_CTRL_AEAD_SET_IV_FIXED 4 |
| 1114 |
.IX Item "EVP_CTRL_AEAD_SET_IV_FIXED" |
| 1115 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called |
| 1116 |
with an \fBOSSL_PARAM\fR\|(3) item with the key "tlsivfixed" |
| 1117 |
(\fBOSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED\fR). |
| 1118 |
.IP EVP_CTRL_AEAD_SET_MAC_KEY 4 |
| 1119 |
.IX Item "EVP_CTRL_AEAD_SET_MAC_KEY" |
| 1120 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called |
| 1121 |
with an \fBOSSL_PARAM\fR\|(3) item with the key "mackey" |
| 1122 |
(\fBOSSL_CIPHER_PARAM_AEAD_MAC_KEY\fR). |
| 1123 |
.IP "EVP_CTRL_AEAD_SET_TAG and EVP_CTRL_AEAD_GET_TAG" 4 |
| 1124 |
.IX Item "EVP_CTRL_AEAD_SET_TAG and EVP_CTRL_AEAD_GET_TAG" |
| 1125 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR and |
| 1126 |
\&\fBEVP_CIPHER_CTX_get_params()\fR get called with an \fBOSSL_PARAM\fR\|(3) item with the |
| 1127 |
key "tag" (\fBOSSL_CIPHER_PARAM_AEAD_TAG\fR). |
| 1128 |
.IP EVP_CTRL_CCM_SET_L 4 |
| 1129 |
.IX Item "EVP_CTRL_CCM_SET_L" |
| 1130 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called |
| 1131 |
with an \fBOSSL_PARAM\fR\|(3) item with the key "ivlen" (\fBOSSL_CIPHER_PARAM_IVLEN\fR) |
| 1132 |
with a value of (15 \- L) |
| 1133 |
.IP EVP_CTRL_COPY 4 |
| 1134 |
.IX Item "EVP_CTRL_COPY" |
| 1135 |
There is no OSSL_PARAM mapping for this. Use \fBEVP_CIPHER_CTX_copy()\fR instead. |
| 1136 |
.IP EVP_CTRL_GCM_SET_IV_INV 4 |
| 1137 |
.IX Item "EVP_CTRL_GCM_SET_IV_INV" |
| 1138 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called |
| 1139 |
with an \fBOSSL_PARAM\fR\|(3) item with the key "tlsivinv" |
| 1140 |
(\fBOSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV\fR). |
| 1141 |
.IP EVP_CTRL_RAND_KEY 4 |
| 1142 |
.IX Item "EVP_CTRL_RAND_KEY" |
| 1143 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called |
| 1144 |
with an \fBOSSL_PARAM\fR\|(3) item with the key "randkey" |
| 1145 |
(\fBOSSL_CIPHER_PARAM_RANDOM_KEY\fR). |
| 1146 |
.IP EVP_CTRL_SET_KEY_LENGTH 4 |
| 1147 |
.IX Item "EVP_CTRL_SET_KEY_LENGTH" |
| 1148 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called |
| 1149 |
with an \fBOSSL_PARAM\fR\|(3) item with the key "keylen" (\fBOSSL_CIPHER_PARAM_KEYLEN\fR). |
| 1150 |
.IP "EVP_CTRL_SET_RC2_KEY_BITS and EVP_CTRL_GET_RC2_KEY_BITS" 4 |
| 1151 |
.IX Item "EVP_CTRL_SET_RC2_KEY_BITS and EVP_CTRL_GET_RC2_KEY_BITS" |
| 1152 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR and |
| 1153 |
\&\fBEVP_CIPHER_CTX_get_params()\fR get called with an \fBOSSL_PARAM\fR\|(3) item with the |
| 1154 |
key "keybits" (\fBOSSL_CIPHER_PARAM_RC2_KEYBITS\fR). |
| 1155 |
.IP "EVP_CTRL_SET_RC5_ROUNDS and EVP_CTRL_GET_RC5_ROUNDS" 4 |
| 1156 |
.IX Item "EVP_CTRL_SET_RC5_ROUNDS and EVP_CTRL_GET_RC5_ROUNDS" |
| 1157 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR and |
| 1158 |
\&\fBEVP_CIPHER_CTX_get_params()\fR get called with an \fBOSSL_PARAM\fR\|(3) item with the |
| 1159 |
key "rounds" (\fBOSSL_CIPHER_PARAM_ROUNDS\fR). |
| 1160 |
.IP EVP_CTRL_SET_SPEED 4 |
| 1161 |
.IX Item "EVP_CTRL_SET_SPEED" |
| 1162 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called |
| 1163 |
with an \fBOSSL_PARAM\fR\|(3) item with the key "speed" (\fBOSSL_CIPHER_PARAM_SPEED\fR). |
| 1164 |
.IP EVP_CTRL_GCM_IV_GEN 4 |
| 1165 |
.IX Item "EVP_CTRL_GCM_IV_GEN" |
| 1166 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_get_params()\fR gets called |
| 1167 |
with an \fBOSSL_PARAM\fR\|(3) item with the key |
| 1168 |
"tlsivgen" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN\fR). |
| 1169 |
.IP EVP_CTRL_AEAD_TLS1_AAD 4 |
| 1170 |
.IX Item "EVP_CTRL_AEAD_TLS1_AAD" |
| 1171 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR get called |
| 1172 |
with an \fBOSSL_PARAM\fR\|(3) item with the key |
| 1173 |
"tlsaad" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_AAD\fR) |
| 1174 |
followed by \fBEVP_CIPHER_CTX_get_params()\fR with a key of |
| 1175 |
"tlsaadpad" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD\fR). |
| 1176 |
.IP EVP_CTRL_TLS1_1_MULTIBLOCK_MAX_BUFSIZE 4 |
| 1177 |
.IX Item "EVP_CTRL_TLS1_1_MULTIBLOCK_MAX_BUFSIZE" |
| 1178 |
When used with a fetched \fBEVP_CIPHER\fR, |
| 1179 |
\&\fBEVP_CIPHER_CTX_set_params()\fR gets called with an \fBOSSL_PARAM\fR\|(3) item with the |
| 1180 |
key OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT |
| 1181 |
followed by \fBEVP_CIPHER_CTX_get_params()\fR with a key of |
| 1182 |
"tls1multi_maxbufsz" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE\fR). |
| 1183 |
.IP EVP_CTRL_TLS1_1_MULTIBLOCK_AAD 4 |
| 1184 |
.IX Item "EVP_CTRL_TLS1_1_MULTIBLOCK_AAD" |
| 1185 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called |
| 1186 |
with \fBOSSL_PARAM\fR\|(3) items with the keys |
| 1187 |
"tls1multi_aad" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD\fR) and |
| 1188 |
"tls1multi_interleave" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\fR) |
| 1189 |
followed by \fBEVP_CIPHER_CTX_get_params()\fR with keys of |
| 1190 |
"tls1multi_aadpacklen" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN\fR) and |
| 1191 |
"tls1multi_interleave" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\fR). |
| 1192 |
.IP EVP_CTRL_TLS1_1_MULTIBLOCK_ENCRYPT 4 |
| 1193 |
.IX Item "EVP_CTRL_TLS1_1_MULTIBLOCK_ENCRYPT" |
| 1194 |
When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called |
| 1195 |
with \fBOSSL_PARAM\fR\|(3) items with the keys |
| 1196 |
"tls1multi_enc" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC\fR), |
| 1197 |
"tls1multi_encin" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN\fR) and |
| 1198 |
"tls1multi_interleave" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\fR), |
| 1199 |
followed by \fBEVP_CIPHER_CTX_get_params()\fR with a key of |
| 1200 |
"tls1multi_enclen" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN\fR). |
| 1201 |
.SH FLAGS |
| 1202 |
.IX Header "FLAGS" |
| 1203 |
\&\fBEVP_CIPHER_CTX_set_flags()\fR, \fBEVP_CIPHER_CTX_clear_flags()\fR and \fBEVP_CIPHER_CTX_test_flags()\fR. |
| 1204 |
can be used to manipulate and test these \fBEVP_CIPHER_CTX\fR flags: |
| 1205 |
.IP EVP_CIPH_NO_PADDING 4 |
| 1206 |
.IX Item "EVP_CIPH_NO_PADDING" |
| 1207 |
Used by \fBEVP_CIPHER_CTX_set_padding()\fR. |
| 1208 |
.Sp |
| 1209 |
See also "Gettable and Settable EVP_CIPHER_CTX parameters" "padding" |
| 1210 |
.IP EVP_CIPH_FLAG_LENGTH_BITS 4 |
| 1211 |
.IX Item "EVP_CIPH_FLAG_LENGTH_BITS" |
| 1212 |
See "Settable EVP_CIPHER_CTX parameters" "use-bits". |
| 1213 |
.IP EVP_CIPHER_CTX_FLAG_WRAP_ALLOW 4 |
| 1214 |
.IX Item "EVP_CIPHER_CTX_FLAG_WRAP_ALLOW" |
| 1215 |
Used for Legacy purposes only. This flag needed to be set to indicate the |
| 1216 |
cipher handled wrapping. |
| 1217 |
.PP |
| 1218 |
\&\fBEVP_CIPHER_flags()\fR uses the following flags that |
| 1219 |
have mappings to "Gettable EVP_CIPHER parameters": |
| 1220 |
.IP EVP_CIPH_FLAG_AEAD_CIPHER 4 |
| 1221 |
.IX Item "EVP_CIPH_FLAG_AEAD_CIPHER" |
| 1222 |
See "Gettable EVP_CIPHER parameters" "aead". |
| 1223 |
.IP EVP_CIPH_CUSTOM_IV 4 |
| 1224 |
.IX Item "EVP_CIPH_CUSTOM_IV" |
| 1225 |
See "Gettable EVP_CIPHER parameters" "custom-iv". |
| 1226 |
.IP EVP_CIPH_FLAG_CTS 4 |
| 1227 |
.IX Item "EVP_CIPH_FLAG_CTS" |
| 1228 |
See "Gettable EVP_CIPHER parameters" "cts". |
| 1229 |
.IP EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK; 4 |
| 1230 |
.IX Item "EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK;" |
| 1231 |
See "Gettable EVP_CIPHER parameters" "tls-multi". |
| 1232 |
.IP EVP_CIPH_RAND_KEY 4 |
| 1233 |
.IX Item "EVP_CIPH_RAND_KEY" |
| 1234 |
See "Gettable EVP_CIPHER parameters" "has-randkey". |
| 1235 |
.PP |
| 1236 |
\&\fBEVP_CIPHER_flags()\fR uses the following flags for legacy purposes only: |
| 1237 |
.IP EVP_CIPH_VARIABLE_LENGTH 4 |
| 1238 |
.IX Item "EVP_CIPH_VARIABLE_LENGTH" |
| 1239 |
.PD 0 |
| 1240 |
.IP EVP_CIPH_FLAG_CUSTOM_CIPHER 4 |
| 1241 |
.IX Item "EVP_CIPH_FLAG_CUSTOM_CIPHER" |
| 1242 |
.IP EVP_CIPH_ALWAYS_CALL_INIT 4 |
| 1243 |
.IX Item "EVP_CIPH_ALWAYS_CALL_INIT" |
| 1244 |
.IP EVP_CIPH_CTRL_INIT 4 |
| 1245 |
.IX Item "EVP_CIPH_CTRL_INIT" |
| 1246 |
.IP EVP_CIPH_CUSTOM_KEY_LENGTH 4 |
| 1247 |
.IX Item "EVP_CIPH_CUSTOM_KEY_LENGTH" |
| 1248 |
.IP EVP_CIPH_CUSTOM_COPY 4 |
| 1249 |
.IX Item "EVP_CIPH_CUSTOM_COPY" |
| 1250 |
.IP EVP_CIPH_FLAG_DEFAULT_ASN1 4 |
| 1251 |
.IX Item "EVP_CIPH_FLAG_DEFAULT_ASN1" |
| 1252 |
.PD |
| 1253 |
See \fBEVP_CIPHER_meth_set_flags\fR\|(3) for further information related to the above |
| 1254 |
flags. |
| 1255 |
.SH "RETURN VALUES" |
| 1256 |
.IX Header "RETURN VALUES" |
| 1257 |
\&\fBEVP_CIPHER_fetch()\fR returns a pointer to a \fBEVP_CIPHER\fR for success |
| 1258 |
and NULL for failure. |
| 1259 |
.PP |
| 1260 |
\&\fBEVP_CIPHER_up_ref()\fR returns 1 for success or 0 otherwise. |
| 1261 |
.PP |
| 1262 |
\&\fBEVP_CIPHER_CTX_new()\fR returns a pointer to a newly created |
| 1263 |
\&\fBEVP_CIPHER_CTX\fR for success and NULL for failure. |
| 1264 |
.PP |
| 1265 |
\&\fBEVP_CIPHER_CTX_dup()\fR returns a new EVP_CIPHER_CTX if successful or NULL on failure. |
| 1266 |
.PP |
| 1267 |
\&\fBEVP_CIPHER_CTX_copy()\fR returns 1 if successful or 0 for failure. |
| 1268 |
.PP |
| 1269 |
\&\fBEVP_EncryptInit_ex2()\fR, \fBEVP_EncryptUpdate()\fR and \fBEVP_EncryptFinal_ex()\fR |
| 1270 |
return 1 for success and 0 for failure. |
| 1271 |
.PP |
| 1272 |
\&\fBEVP_DecryptInit_ex2()\fR and \fBEVP_DecryptUpdate()\fR return 1 for success and 0 for failure. |
| 1273 |
\&\fBEVP_DecryptFinal_ex()\fR returns 0 if the decrypt failed or 1 for success. |
| 1274 |
.PP |
| 1275 |
\&\fBEVP_CipherInit_ex2()\fR, \fBEVP_CipherInit_SKEY()\fR and \fBEVP_CipherUpdate()\fR return 1 for |
| 1276 |
success and 0 for failure. |
| 1277 |
\&\fBEVP_CipherFinal_ex()\fR returns 0 for an encryption/decryption failure or 1 for |
| 1278 |
success. |
| 1279 |
.PP |
| 1280 |
\&\fBEVP_Cipher()\fR returns 1 on success and <= 0 on failure, if the flag |
| 1281 |
\&\fBEVP_CIPH_FLAG_CUSTOM_CIPHER\fR is not set for the cipher, or if the cipher has |
| 1282 |
not been initialized via a call to \fBEVP_CipherInit_ex2\fR. |
| 1283 |
\&\fBEVP_Cipher()\fR returns the number of bytes written to \fIout\fR for |
| 1284 |
encryption/decryption, or the number of bytes authenticated in a call specifying |
| 1285 |
AAD for an AEAD cipher, if the flag \fBEVP_CIPH_FLAG_CUSTOM_CIPHER\fR is set for |
| 1286 |
the cipher. |
| 1287 |
.PP |
| 1288 |
\&\fBEVP_CIPHER_can_pipeline()\fR returns 1 if the cipher can be used in a pipeline, 0 otherwise. |
| 1289 |
.PP |
| 1290 |
\&\fBEVP_CipherPipelineEncryptInit()\fR and \fBEVP_CipherPipelineDecryptInit()\fR |
| 1291 |
return 1 for success and 0 for failure. |
| 1292 |
.PP |
| 1293 |
\&\fBEVP_CipherPipelineUpdate()\fR and \fBEVP_CipherPipelineFinal()\fR |
| 1294 |
return 1 for success and 0 for failure. |
| 1295 |
.PP |
| 1296 |
\&\fBEVP_CIPHER_CTX_reset()\fR returns 1 for success and 0 for failure. |
| 1297 |
.PP |
| 1298 |
\&\fBEVP_get_cipherbyname()\fR, \fBEVP_get_cipherbynid()\fR and \fBEVP_get_cipherbyobj()\fR |
| 1299 |
return an \fBEVP_CIPHER\fR structure or NULL on error. |
| 1300 |
.PP |
| 1301 |
\&\fBEVP_CIPHER_get_nid()\fR and \fBEVP_CIPHER_CTX_get_nid()\fR return a NID. |
| 1302 |
.PP |
| 1303 |
\&\fBEVP_CIPHER_get_block_size()\fR and \fBEVP_CIPHER_CTX_get_block_size()\fR return the |
| 1304 |
block size, or 0 on error. |
| 1305 |
.PP |
| 1306 |
\&\fBEVP_CIPHER_get_key_length()\fR and \fBEVP_CIPHER_CTX_get_key_length()\fR return the key |
| 1307 |
length. |
| 1308 |
.PP |
| 1309 |
\&\fBEVP_CIPHER_CTX_set_padding()\fR always returns 1. |
| 1310 |
.PP |
| 1311 |
\&\fBEVP_CIPHER_get_iv_length()\fR and \fBEVP_CIPHER_CTX_get_iv_length()\fR return the IV |
| 1312 |
length, zero if the cipher does not use an IV and a negative value on error. |
| 1313 |
.PP |
| 1314 |
\&\fBEVP_CIPHER_CTX_get_tag_length()\fR return the tag length or zero if the cipher |
| 1315 |
does not use a tag. |
| 1316 |
.PP |
| 1317 |
\&\fBEVP_CIPHER_get_type()\fR and \fBEVP_CIPHER_CTX_get_type()\fR return the NID of the |
| 1318 |
cipher's OBJECT IDENTIFIER or NID_undef if it has no defined |
| 1319 |
OBJECT IDENTIFIER. |
| 1320 |
.PP |
| 1321 |
\&\fBEVP_CIPHER_CTX_cipher()\fR returns an \fBEVP_CIPHER\fR structure. |
| 1322 |
.PP |
| 1323 |
\&\fBEVP_CIPHER_CTX_get_num()\fR returns a nonnegative num value or |
| 1324 |
\&\fBEVP_CTRL_RET_UNSUPPORTED\fR if the implementation does not support the call |
| 1325 |
or on any other error. |
| 1326 |
.PP |
| 1327 |
\&\fBEVP_CIPHER_CTX_set_num()\fR returns 1 on success and 0 if the implementation |
| 1328 |
does not support the call or on any other error. |
| 1329 |
.PP |
| 1330 |
\&\fBEVP_CIPHER_CTX_is_encrypting()\fR returns 1 if the \fIctx\fR is set up for encryption |
| 1331 |
0 otherwise. |
| 1332 |
.PP |
| 1333 |
\&\fBEVP_CIPHER_param_to_asn1()\fR and \fBEVP_CIPHER_asn1_to_param()\fR return greater |
| 1334 |
than zero for success and zero or a negative number on failure. |
| 1335 |
.PP |
| 1336 |
\&\fBEVP_CIPHER_CTX_rand_key()\fR returns 1 for success and zero or a negative number |
| 1337 |
for failure. |
| 1338 |
.PP |
| 1339 |
\&\fBEVP_CIPHER_names_do_all()\fR returns 1 if the callback was called for all names. |
| 1340 |
A return value of 0 means that the callback was not called for any names. |
| 1341 |
.PP |
| 1342 |
\&\fBEVP_CIPHER_get_params()\fR, \fBEVP_CIPHER_CTX_get_params()\fR and |
| 1343 |
\&\fBEVP_CIPHER_CTX_set_params()\fR return 1 for success and 0 for failure. |
| 1344 |
.SH "CIPHER LISTING" |
| 1345 |
.IX Header "CIPHER LISTING" |
| 1346 |
All algorithms have a fixed key length unless otherwise stated. |
| 1347 |
.PP |
| 1348 |
Refer to "SEE ALSO" for the full list of ciphers available through the EVP |
| 1349 |
interface. |
| 1350 |
.IP \fBEVP_enc_null()\fR 4 |
| 1351 |
.IX Item "EVP_enc_null()" |
| 1352 |
Null cipher: does nothing. |
| 1353 |
.SH "AEAD INTERFACE" |
| 1354 |
.IX Header "AEAD INTERFACE" |
| 1355 |
The EVP interface for Authenticated Encryption with Associated Data (AEAD) |
| 1356 |
modes are subtly altered and several additional \fIctrl\fR operations are supported |
| 1357 |
depending on the mode specified. |
| 1358 |
.PP |
| 1359 |
To specify additional authenticated data (AAD), a call to \fBEVP_CipherUpdate()\fR, |
| 1360 |
\&\fBEVP_EncryptUpdate()\fR or \fBEVP_DecryptUpdate()\fR should be made with the output |
| 1361 |
parameter \fIout\fR set to NULL. In this case, on success, the parameter |
| 1362 |
\&\fIoutl\fR is set to the number of AAD bytes processed in that call |
| 1363 |
(that is, the value of \fIinl\fR), and does not include any plaintext |
| 1364 |
or ciphertext bytes processed by other calls. |
| 1365 |
.PP |
| 1366 |
If no AAD is used, this call can be omitted. See the mode-specific notes |
| 1367 |
below for any exceptions. |
| 1368 |
.PP |
| 1369 |
When decrypting, the return value of \fBEVP_DecryptFinal()\fR or \fBEVP_CipherFinal()\fR |
| 1370 |
indicates whether the operation was successful. If it does not indicate success, |
| 1371 |
the authentication operation has failed and any output data \fBMUST NOT\fR be used |
| 1372 |
as it is corrupted. |
| 1373 |
.PP |
| 1374 |
Please note that the number of authenticated bytes returned by |
| 1375 |
\&\fBEVP_CipherUpdate()\fR depends on the cipher used. Stream ciphers, such as ChaCha20 |
| 1376 |
or ciphers in GCM mode, can handle 1 byte at a time, resulting in an effective |
| 1377 |
"block" size of 1. Conversely, ciphers in OCB mode must process data one block |
| 1378 |
at a time, and the block size is returned. |
| 1379 |
.PP |
| 1380 |
Regardless of the returned size, it is safe to pass unpadded data to an |
| 1381 |
\&\fBEVP_CipherUpdate()\fR call in a single operation. |
| 1382 |
.SS "GCM and OCB Modes" |
| 1383 |
.IX Subsection "GCM and OCB Modes" |
| 1384 |
The following \fIctrl\fRs are supported in GCM and OCB modes. |
| 1385 |
.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" 4 |
| 1386 |
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" |
| 1387 |
Sets the IV length. This call can only be made before specifying an IV. If |
| 1388 |
not called a default IV length is used. |
| 1389 |
.Sp |
| 1390 |
For GCM AES and OCB AES the default is 12 (i.e. 96 bits). For OCB mode the |
| 1391 |
maximum is 15. |
| 1392 |
.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)" 4 |
| 1393 |
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)" |
| 1394 |
Writes \f(CW\*(C`taglen\*(C'\fR bytes of the tag value to the buffer indicated by \f(CW\*(C`tag\*(C'\fR. |
| 1395 |
This call can only be made when encrypting data and \fBafter\fR all data has been |
| 1396 |
processed (e.g. after an \fBEVP_EncryptFinal()\fR call). |
| 1397 |
.Sp |
| 1398 |
For OCB, \f(CW\*(C`taglen\*(C'\fR must either be 16 or the value previously set via |
| 1399 |
\&\fBEVP_CTRL_AEAD_SET_TAG\fR. |
| 1400 |
.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)" 4 |
| 1401 |
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)" |
| 1402 |
When decrypting, this call sets the expected tag to \f(CW\*(C`taglen\*(C'\fR bytes from \f(CW\*(C`tag\*(C'\fR. |
| 1403 |
\&\f(CW\*(C`taglen\*(C'\fR must be between 1 and 16 inclusive. |
| 1404 |
The tag must be set prior to any call to \fBEVP_DecryptFinal()\fR or |
| 1405 |
\&\fBEVP_DecryptFinal_ex()\fR. |
| 1406 |
.Sp |
| 1407 |
For GCM, this call is only valid when decrypting data. |
| 1408 |
.Sp |
| 1409 |
For OCB, this call is valid when decrypting data to set the expected tag, |
| 1410 |
and when encrypting to set the desired tag length. |
| 1411 |
.Sp |
| 1412 |
In OCB mode, calling this with \f(CW\*(C`tag\*(C'\fR set to \f(CW\*(C`NULL\*(C'\fR sets the tag length. |
| 1413 |
The tag length can only be set before specifying an IV. If this is not called |
| 1414 |
prior to setting the IV, then a default tag length is used. |
| 1415 |
.Sp |
| 1416 |
For OCB AES, the default tag length is 16 (i.e. 128 bits). It is also the |
| 1417 |
maximum tag length for OCB. |
| 1418 |
.SS "CCM Mode" |
| 1419 |
.IX Subsection "CCM Mode" |
| 1420 |
The EVP interface for CCM mode is similar to that of the GCM mode but with a |
| 1421 |
few additional requirements and different \fIctrl\fR values. |
| 1422 |
.PP |
| 1423 |
For CCM mode, the total plaintext or ciphertext length \fBMUST\fR be passed to |
| 1424 |
\&\fBEVP_CipherUpdate()\fR, \fBEVP_EncryptUpdate()\fR or \fBEVP_DecryptUpdate()\fR with the output |
| 1425 |
and input parameters (\fIin\fR and \fIout\fR) set to NULL and the length passed in |
| 1426 |
the \fIinl\fR parameter. |
| 1427 |
.PP |
| 1428 |
The following \fIctrl\fRs are supported in CCM mode. |
| 1429 |
.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)" 4 |
| 1430 |
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)" |
| 1431 |
This call is made to set the expected \fBCCM\fR tag value when decrypting or |
| 1432 |
the length of the tag (with the \f(CW\*(C`tag\*(C'\fR parameter set to NULL) when encrypting. |
| 1433 |
The tag length is often referred to as \fBM\fR. If not set a default value is |
| 1434 |
used (12 for AES). When decrypting, the tag needs to be set before passing |
| 1435 |
in data to be decrypted, but as in GCM and OCB mode, it can be set after |
| 1436 |
passing additional authenticated data (see "AEAD INTERFACE"). |
| 1437 |
.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)" 4 |
| 1438 |
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)" |
| 1439 |
Sets the CCM \fBL\fR value. If not set a default is used (8 for AES). |
| 1440 |
.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" 4 |
| 1441 |
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" |
| 1442 |
Sets the CCM nonce (IV) length. This call can only be made before specifying a |
| 1443 |
nonce value. The nonce length is given by \fB15 \- L\fR so it is 7 by default for |
| 1444 |
AES. |
| 1445 |
.SS "SIV Mode" |
| 1446 |
.IX Subsection "SIV Mode" |
| 1447 |
Both the AES-SIV and AES-GCM-SIV ciphers fall under this mode. |
| 1448 |
.PP |
| 1449 |
For SIV mode ciphers the behaviour of the EVP interface is subtly |
| 1450 |
altered and several additional ctrl operations are supported. |
| 1451 |
.PP |
| 1452 |
To specify any additional authenticated data (AAD) and/or a Nonce, a call to |
| 1453 |
\&\fBEVP_CipherUpdate()\fR, \fBEVP_EncryptUpdate()\fR or \fBEVP_DecryptUpdate()\fR should be made |
| 1454 |
with the output parameter \fIout\fR set to NULL. |
| 1455 |
.PP |
| 1456 |
RFC5297 states that the Nonce is the last piece of AAD before the actual |
| 1457 |
encrypt/decrypt takes place. The API does not differentiate the Nonce from |
| 1458 |
other AAD. |
| 1459 |
.PP |
| 1460 |
When decrypting the return value of \fBEVP_DecryptFinal()\fR or \fBEVP_CipherFinal()\fR |
| 1461 |
indicates if the operation was successful. If it does not indicate success |
| 1462 |
the authentication operation has failed and any output data \fBMUST NOT\fR |
| 1463 |
be used as it is corrupted. |
| 1464 |
.PP |
| 1465 |
The API does not store the SIV (Synthetic Initialization Vector) in |
| 1466 |
the cipher text. Instead, it is stored as the tag within the EVP_CIPHER_CTX. |
| 1467 |
The SIV must be retrieved from the context after encryption, and set into |
| 1468 |
the context before decryption. |
| 1469 |
.PP |
| 1470 |
This differs from RFC5297 in that the cipher output from encryption, and |
| 1471 |
the cipher input to decryption, does not contain the SIV. This also means |
| 1472 |
that the plain text and cipher text lengths are identical. |
| 1473 |
.PP |
| 1474 |
The following ctrls are supported in SIV mode, and are used to get and set |
| 1475 |
the Synthetic Initialization Vector: |
| 1476 |
.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);" 4 |
| 1477 |
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);" |
| 1478 |
Writes \fItaglen\fR bytes of the tag value (the Synthetic Initialization Vector) |
| 1479 |
to the buffer indicated by \fItag\fR. This call can only be made when encrypting |
| 1480 |
data and \fBafter\fR all data has been processed (e.g. after an \fBEVP_EncryptFinal()\fR |
| 1481 |
call). For SIV mode the taglen must be 16. |
| 1482 |
.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);" 4 |
| 1483 |
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);" |
| 1484 |
Sets the expected tag (the Synthetic Initialization Vector) to \fItaglen\fR |
| 1485 |
bytes from \fItag\fR. This call is only legal when decrypting data and must be |
| 1486 |
made \fBbefore\fR any data is processed (e.g. before any \fBEVP_DecryptUpdate()\fR |
| 1487 |
calls). For SIV mode the taglen must be 16. |
| 1488 |
.PP |
| 1489 |
SIV mode makes two passes over the input data, thus, only one call to |
| 1490 |
\&\fBEVP_CipherUpdate()\fR, \fBEVP_EncryptUpdate()\fR or \fBEVP_DecryptUpdate()\fR should be made |
| 1491 |
with \fIout\fR set to a non-NULL value. A call to \fBEVP_DecryptFinal()\fR or |
| 1492 |
\&\fBEVP_CipherFinal()\fR is not required, but will indicate if the update |
| 1493 |
operation succeeded. |
| 1494 |
.SS ChaCha20\-Poly1305 |
| 1495 |
.IX Subsection "ChaCha20-Poly1305" |
| 1496 |
The following \fIctrl\fRs are supported for the ChaCha20\-Poly1305 AEAD algorithm. |
| 1497 |
.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" 4 |
| 1498 |
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" |
| 1499 |
Sets the nonce length. This call is now redundant since the only valid value |
| 1500 |
is the default length of 12 (i.e. 96 bits). |
| 1501 |
Prior to OpenSSL 3.0 a nonce of less than 12 bytes could be used to automatically |
| 1502 |
pad the iv with leading 0 bytes to make it 12 bytes in length. |
| 1503 |
.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)" 4 |
| 1504 |
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)" |
| 1505 |
Writes \f(CW\*(C`taglen\*(C'\fR bytes of the tag value to the buffer indicated by \f(CW\*(C`tag\*(C'\fR. |
| 1506 |
This call can only be made when encrypting data and \fBafter\fR all data has been |
| 1507 |
processed (e.g. after an \fBEVP_EncryptFinal()\fR call). |
| 1508 |
.Sp |
| 1509 |
\&\f(CW\*(C`taglen\*(C'\fR specified here must be 16 (\fBPOLY1305_BLOCK_SIZE\fR, i.e. 128\-bits) or |
| 1510 |
less. |
| 1511 |
.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)" 4 |
| 1512 |
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)" |
| 1513 |
Sets the expected tag to \f(CW\*(C`taglen\*(C'\fR bytes from \f(CW\*(C`tag\*(C'\fR. |
| 1514 |
The tag length can only be set before specifying an IV. |
| 1515 |
\&\f(CW\*(C`taglen\*(C'\fR must be between 1 and 16 (\fBPOLY1305_BLOCK_SIZE\fR) inclusive. |
| 1516 |
This call is only valid when decrypting data. |
| 1517 |
.SH NOTES |
| 1518 |
.IX Header "NOTES" |
| 1519 |
Where possible the \fBEVP\fR interface to symmetric ciphers should be used in |
| 1520 |
preference to the low-level interfaces. This is because the code then becomes |
| 1521 |
transparent to the cipher used and much more flexible. Additionally, the |
| 1522 |
\&\fBEVP\fR interface will ensure the use of platform specific cryptographic |
| 1523 |
acceleration such as AES-NI (the low-level interfaces do not provide the |
| 1524 |
guarantee). |
| 1525 |
.PP |
| 1526 |
PKCS padding works by adding \fBn\fR padding bytes of value \fBn\fR to make the total |
| 1527 |
length of the encrypted data a multiple of the block size. Padding is always |
| 1528 |
added so if the data is already a multiple of the block size \fBn\fR will equal |
| 1529 |
the block size. For example if the block size is 8 and 11 bytes are to be |
| 1530 |
encrypted then 5 padding bytes of value 5 will be added. |
| 1531 |
.PP |
| 1532 |
When decrypting the final block is checked to see if it has the correct form. |
| 1533 |
.PP |
| 1534 |
Although the decryption operation can produce an error if padding is enabled, |
| 1535 |
it is not a strong test that the input data or key is correct. A random block |
| 1536 |
has better than 1 in 256 chance of being of the correct format and problems with |
| 1537 |
the input data earlier on will not produce a final decrypt error. |
| 1538 |
.PP |
| 1539 |
If padding is disabled then the decryption operation will always succeed if |
| 1540 |
the total amount of data decrypted is a multiple of the block size. |
| 1541 |
.PP |
| 1542 |
The functions \fBEVP_EncryptInit()\fR, \fBEVP_EncryptInit_ex()\fR, |
| 1543 |
\&\fBEVP_EncryptFinal()\fR, \fBEVP_DecryptInit()\fR, \fBEVP_DecryptInit_ex()\fR, |
| 1544 |
\&\fBEVP_CipherInit()\fR, \fBEVP_CipherInit_ex()\fR and \fBEVP_CipherFinal()\fR are obsolete |
| 1545 |
but are retained for compatibility with existing code. New code should |
| 1546 |
use \fBEVP_EncryptInit_ex2()\fR, \fBEVP_EncryptFinal_ex()\fR, \fBEVP_DecryptInit_ex2()\fR, |
| 1547 |
\&\fBEVP_DecryptFinal_ex()\fR, \fBEVP_CipherInit_ex2()\fR and \fBEVP_CipherFinal_ex()\fR |
| 1548 |
because they can reuse an existing context without allocating and freeing |
| 1549 |
it up on each call. |
| 1550 |
.PP |
| 1551 |
There are some differences between functions \fBEVP_CipherInit()\fR and |
| 1552 |
\&\fBEVP_CipherInit_ex()\fR, significant in some circumstances. \fBEVP_CipherInit()\fR fills |
| 1553 |
the passed context object with zeros. As a consequence, \fBEVP_CipherInit()\fR does |
| 1554 |
not allow step-by-step initialization of the ctx when the \fIkey\fR and \fIiv\fR are |
| 1555 |
passed in separate calls. It also means that the flags set for the CTX are |
| 1556 |
removed, and it is especially important for the |
| 1557 |
\&\fBEVP_CIPHER_CTX_FLAG_WRAP_ALLOW\fR flag treated specially in |
| 1558 |
\&\fBEVP_CipherInit_ex()\fR. |
| 1559 |
.PP |
| 1560 |
Ignoring failure returns of the \fBEVP_CIPHER_CTX\fR initialization functions can |
| 1561 |
lead to subsequent undefined behavior when calling the functions that update or |
| 1562 |
finalize the context. The only valid calls on the \fBEVP_CIPHER_CTX\fR when |
| 1563 |
initialization fails are calls that attempt another initialization of the |
| 1564 |
context or release the context. |
| 1565 |
.PP |
| 1566 |
\&\fBEVP_get_cipherbynid()\fR, and \fBEVP_get_cipherbyobj()\fR are implemented as macros. |
| 1567 |
.SH BUGS |
| 1568 |
.IX Header "BUGS" |
| 1569 |
\&\fBEVP_MAX_KEY_LENGTH\fR and \fBEVP_MAX_IV_LENGTH\fR only refer to the internal |
| 1570 |
ciphers with default key lengths. If custom ciphers exceed these values the |
| 1571 |
results are unpredictable. This is because it has become standard practice to |
| 1572 |
define a generic key as a fixed unsigned char array containing |
| 1573 |
\&\fBEVP_MAX_KEY_LENGTH\fR bytes. |
| 1574 |
.PP |
| 1575 |
The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested |
| 1576 |
for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. |
| 1577 |
.SH EXAMPLES |
| 1578 |
.IX Header "EXAMPLES" |
| 1579 |
Encrypt a string using IDEA: |
| 1580 |
.PP |
| 1581 |
.Vb 10 |
| 1582 |
\& int do_crypt(char *outfile) |
| 1583 |
\& { |
| 1584 |
\& unsigned char outbuf[1024]; |
| 1585 |
\& int outlen, tmplen; |
| 1586 |
\& /* |
| 1587 |
\& * Bogus key and IV: we\*(Aqd normally set these from |
| 1588 |
\& * another source. |
| 1589 |
\& */ |
| 1590 |
\& unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; |
| 1591 |
\& unsigned char iv[] = {1,2,3,4,5,6,7,8}; |
| 1592 |
\& char intext[] = "Some Crypto Text"; |
| 1593 |
\& EVP_CIPHER_CTX *ctx; |
| 1594 |
\& FILE *out; |
| 1595 |
\& |
| 1596 |
\& ctx = EVP_CIPHER_CTX_new(); |
| 1597 |
\& if (!EVP_EncryptInit_ex2(ctx, EVP_idea_cbc(), key, iv, NULL)) { |
| 1598 |
\& /* Error */ |
| 1599 |
\& EVP_CIPHER_CTX_free(ctx); |
| 1600 |
\& return 0; |
| 1601 |
\& } |
| 1602 |
\& |
| 1603 |
\& if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) { |
| 1604 |
\& /* Error */ |
| 1605 |
\& EVP_CIPHER_CTX_free(ctx); |
| 1606 |
\& return 0; |
| 1607 |
\& } |
| 1608 |
\& /* |
| 1609 |
\& * Buffer passed to EVP_EncryptFinal() must be after data just |
| 1610 |
\& * encrypted to avoid overwriting it. |
| 1611 |
\& */ |
| 1612 |
\& if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) { |
| 1613 |
\& /* Error */ |
| 1614 |
\& EVP_CIPHER_CTX_free(ctx); |
| 1615 |
\& return 0; |
| 1616 |
\& } |
| 1617 |
\& outlen += tmplen; |
| 1618 |
\& EVP_CIPHER_CTX_free(ctx); |
| 1619 |
\& /* |
| 1620 |
\& * Need binary mode for fopen because encrypted data is |
| 1621 |
\& * binary data. Also cannot use strlen() on it because |
| 1622 |
\& * it won\*(Aqt be NUL terminated and may contain embedded |
| 1623 |
\& * NULs. |
| 1624 |
\& */ |
| 1625 |
\& out = fopen(outfile, "wb"); |
| 1626 |
\& if (out == NULL) { |
| 1627 |
\& /* Error */ |
| 1628 |
\& return 0; |
| 1629 |
\& } |
| 1630 |
\& fwrite(outbuf, 1, outlen, out); |
| 1631 |
\& fclose(out); |
| 1632 |
\& return 1; |
| 1633 |
\& } |
| 1634 |
.Ve |
| 1635 |
.PP |
| 1636 |
The ciphertext from the above example can be decrypted using the \fBopenssl\fR |
| 1637 |
utility with the command line (shown on two lines for clarity): |
| 1638 |
.PP |
| 1639 |
.Vb 2 |
| 1640 |
\& openssl idea \-d \e |
| 1641 |
\& \-K 000102030405060708090A0B0C0D0E0F \-iv 0102030405060708 <filename |
| 1642 |
.Ve |
| 1643 |
.PP |
| 1644 |
General encryption and decryption function example using FILE I/O and AES128 |
| 1645 |
with a 128\-bit key: |
| 1646 |
.PP |
| 1647 |
.Vb 12 |
| 1648 |
\& int do_crypt(FILE *in, FILE *out, int do_encrypt) |
| 1649 |
\& { |
| 1650 |
\& /* Allow enough space in output buffer for additional block */ |
| 1651 |
\& unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; |
| 1652 |
\& int inlen, outlen; |
| 1653 |
\& EVP_CIPHER_CTX *ctx; |
| 1654 |
\& /* |
| 1655 |
\& * Bogus key and IV: we\*(Aqd normally set these from |
| 1656 |
\& * another source. |
| 1657 |
\& */ |
| 1658 |
\& unsigned char key[] = "0123456789abcdeF"; |
| 1659 |
\& unsigned char iv[] = "1234567887654321"; |
| 1660 |
\& |
| 1661 |
\& /* Don\*(Aqt set key or IV right away; we want to check lengths */ |
| 1662 |
\& ctx = EVP_CIPHER_CTX_new(); |
| 1663 |
\& if (!EVP_CipherInit_ex2(ctx, EVP_aes_128_cbc(), NULL, NULL, |
| 1664 |
\& do_encrypt, NULL)) { |
| 1665 |
\& /* Error */ |
| 1666 |
\& EVP_CIPHER_CTX_free(ctx); |
| 1667 |
\& return 0; |
| 1668 |
\& } |
| 1669 |
\& OPENSSL_assert(EVP_CIPHER_CTX_get_key_length(ctx) == 16); |
| 1670 |
\& OPENSSL_assert(EVP_CIPHER_CTX_get_iv_length(ctx) == 16); |
| 1671 |
\& |
| 1672 |
\& /* Now we can set key and IV */ |
| 1673 |
\& if (!EVP_CipherInit_ex2(ctx, NULL, key, iv, do_encrypt, NULL)) { |
| 1674 |
\& /* Error */ |
| 1675 |
\& EVP_CIPHER_CTX_free(ctx); |
| 1676 |
\& return 0; |
| 1677 |
\& } |
| 1678 |
\& |
| 1679 |
\& for (;;) { |
| 1680 |
\& inlen = fread(inbuf, 1, 1024, in); |
| 1681 |
\& if (inlen <= 0) |
| 1682 |
\& break; |
| 1683 |
\& if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen)) { |
| 1684 |
\& /* Error */ |
| 1685 |
\& EVP_CIPHER_CTX_free(ctx); |
| 1686 |
\& return 0; |
| 1687 |
\& } |
| 1688 |
\& fwrite(outbuf, 1, outlen, out); |
| 1689 |
\& } |
| 1690 |
\& if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) { |
| 1691 |
\& /* Error */ |
| 1692 |
\& EVP_CIPHER_CTX_free(ctx); |
| 1693 |
\& return 0; |
| 1694 |
\& } |
| 1695 |
\& fwrite(outbuf, 1, outlen, out); |
| 1696 |
\& |
| 1697 |
\& EVP_CIPHER_CTX_free(ctx); |
| 1698 |
\& return 1; |
| 1699 |
\& } |
| 1700 |
.Ve |
| 1701 |
.PP |
| 1702 |
Encryption using AES-CBC with a 256\-bit key with "CS1" ciphertext stealing. |
| 1703 |
.PP |
| 1704 |
.Vb 10 |
| 1705 |
\& int encrypt(const unsigned char *key, const unsigned char *iv, |
| 1706 |
\& const unsigned char *msg, size_t msg_len, unsigned char *out) |
| 1707 |
\& { |
| 1708 |
\& /* |
| 1709 |
\& * This assumes that key size is 32 bytes and the iv is 16 bytes. |
| 1710 |
\& * For ciphertext stealing mode the length of the ciphertext "out" will be |
| 1711 |
\& * the same size as the plaintext size "msg_len". |
| 1712 |
\& * The "msg_len" can be any size >= 16. |
| 1713 |
\& */ |
| 1714 |
\& int ret = 0, encrypt = 1, outlen, len; |
| 1715 |
\& EVP_CIPHER_CTX *ctx = NULL; |
| 1716 |
\& EVP_CIPHER *cipher = NULL; |
| 1717 |
\& OSSL_PARAM params[2]; |
| 1718 |
\& |
| 1719 |
\& ctx = EVP_CIPHER_CTX_new(); |
| 1720 |
\& cipher = EVP_CIPHER_fetch(NULL, "AES\-256\-CBC\-CTS", NULL); |
| 1721 |
\& if (ctx == NULL || cipher == NULL) |
| 1722 |
\& goto err; |
| 1723 |
\& |
| 1724 |
\& /* |
| 1725 |
\& * The default is "CS1" so this is not really needed, |
| 1726 |
\& * but would be needed to set either "CS2" or "CS3". |
| 1727 |
\& */ |
| 1728 |
\& params[0] = OSSL_PARAM_construct_utf8_string(OSSL_CIPHER_PARAM_CTS_MODE, |
| 1729 |
\& "CS1", 0); |
| 1730 |
\& params[1] = OSSL_PARAM_construct_end(); |
| 1731 |
\& |
| 1732 |
\& if (!EVP_CipherInit_ex2(ctx, cipher, key, iv, encrypt, params)) |
| 1733 |
\& goto err; |
| 1734 |
\& |
| 1735 |
\& /* NOTE: CTS mode does not support multiple calls to EVP_CipherUpdate() */ |
| 1736 |
\& if (!EVP_CipherUpdate(ctx, out, &outlen, msg, msg_len)) |
| 1737 |
\& goto err; |
| 1738 |
\& if (!EVP_CipherFinal_ex(ctx, out + outlen, &len)) |
| 1739 |
\& goto err; |
| 1740 |
\& ret = 1; |
| 1741 |
\& err: |
| 1742 |
\& EVP_CIPHER_free(cipher); |
| 1743 |
\& EVP_CIPHER_CTX_free(ctx); |
| 1744 |
\& return ret; |
| 1745 |
\& } |
| 1746 |
.Ve |
| 1747 |
.SH "SEE ALSO" |
| 1748 |
.IX Header "SEE ALSO" |
| 1749 |
\&\fBevp\fR\|(7), |
| 1750 |
\&\fBproperty\fR\|(7), |
| 1751 |
"ALGORITHM FETCHING" in \fBcrypto\fR\|(7), |
| 1752 |
\&\fBprovider\-cipher\fR\|(7), |
| 1753 |
\&\fBlife_cycle\-cipher\fR\|(7) |
| 1754 |
.PP |
| 1755 |
Supported ciphers are listed in: |
| 1756 |
.PP |
| 1757 |
\&\fBEVP_aes_128_gcm\fR\|(3), |
| 1758 |
\&\fBEVP_aria_128_gcm\fR\|(3), |
| 1759 |
\&\fBEVP_bf_cbc\fR\|(3), |
| 1760 |
\&\fBEVP_camellia_128_ecb\fR\|(3), |
| 1761 |
\&\fBEVP_cast5_cbc\fR\|(3), |
| 1762 |
\&\fBEVP_chacha20\fR\|(3), |
| 1763 |
\&\fBEVP_des_cbc\fR\|(3), |
| 1764 |
\&\fBEVP_desx_cbc\fR\|(3), |
| 1765 |
\&\fBEVP_idea_cbc\fR\|(3), |
| 1766 |
\&\fBEVP_rc2_cbc\fR\|(3), |
| 1767 |
\&\fBEVP_rc4\fR\|(3), |
| 1768 |
\&\fBEVP_rc5_32_12_16_cbc\fR\|(3), |
| 1769 |
\&\fBEVP_seed_cbc\fR\|(3), |
| 1770 |
\&\fBEVP_sm4_cbc\fR\|(3), |
| 1771 |
.SH HISTORY |
| 1772 |
.IX Header "HISTORY" |
| 1773 |
Support for OCB mode was added in OpenSSL 1.1.0. |
| 1774 |
.PP |
| 1775 |
\&\fBEVP_CIPHER_CTX\fR was made opaque in OpenSSL 1.1.0. As a result, |
| 1776 |
\&\fBEVP_CIPHER_CTX_reset()\fR appeared and \fBEVP_CIPHER_CTX_cleanup()\fR |
| 1777 |
disappeared. \fBEVP_CIPHER_CTX_init()\fR remains as an alias for |
| 1778 |
\&\fBEVP_CIPHER_CTX_reset()\fR. |
| 1779 |
.PP |
| 1780 |
The \fBEVP_CIPHER_CTX_cipher()\fR function was deprecated in OpenSSL 3.0; use |
| 1781 |
\&\fBEVP_CIPHER_CTX_get0_cipher()\fR instead. |
| 1782 |
.PP |
| 1783 |
The \fBEVP_EncryptInit_ex2()\fR, \fBEVP_DecryptInit_ex2()\fR, \fBEVP_CipherInit_ex2()\fR, |
| 1784 |
\&\fBEVP_CIPHER_fetch()\fR, \fBEVP_CIPHER_free()\fR, \fBEVP_CIPHER_up_ref()\fR, |
| 1785 |
\&\fBEVP_CIPHER_CTX_get0_cipher()\fR, \fBEVP_CIPHER_CTX_get1_cipher()\fR, |
| 1786 |
\&\fBEVP_CIPHER_get_params()\fR, \fBEVP_CIPHER_CTX_set_params()\fR, |
| 1787 |
\&\fBEVP_CIPHER_CTX_get_params()\fR, \fBEVP_CIPHER_gettable_params()\fR, |
| 1788 |
\&\fBEVP_CIPHER_settable_ctx_params()\fR, \fBEVP_CIPHER_gettable_ctx_params()\fR, |
| 1789 |
\&\fBEVP_CIPHER_CTX_settable_params()\fR and \fBEVP_CIPHER_CTX_gettable_params()\fR |
| 1790 |
functions were added in 3.0. |
| 1791 |
.PP |
| 1792 |
The \fBEVP_CIPHER_nid()\fR, \fBEVP_CIPHER_name()\fR, \fBEVP_CIPHER_block_size()\fR, |
| 1793 |
\&\fBEVP_CIPHER_key_length()\fR, \fBEVP_CIPHER_iv_length()\fR, \fBEVP_CIPHER_flags()\fR, |
| 1794 |
\&\fBEVP_CIPHER_mode()\fR, \fBEVP_CIPHER_type()\fR, \fBEVP_CIPHER_CTX_nid()\fR, |
| 1795 |
\&\fBEVP_CIPHER_CTX_block_size()\fR, \fBEVP_CIPHER_CTX_key_length()\fR, |
| 1796 |
\&\fBEVP_CIPHER_CTX_iv_length()\fR, \fBEVP_CIPHER_CTX_tag_length()\fR, |
| 1797 |
\&\fBEVP_CIPHER_CTX_num()\fR, \fBEVP_CIPHER_CTX_type()\fR, and \fBEVP_CIPHER_CTX_mode()\fR |
| 1798 |
functions were renamed to include \f(CW\*(C`get\*(C'\fR or \f(CW\*(C`get0\*(C'\fR in their names in |
| 1799 |
OpenSSL 3.0, respectively. The old names are kept as non-deprecated |
| 1800 |
alias macros. |
| 1801 |
.PP |
| 1802 |
The \fBEVP_CIPHER_CTX_encrypting()\fR function was renamed to |
| 1803 |
\&\fBEVP_CIPHER_CTX_is_encrypting()\fR in OpenSSL 3.0. The old name is kept as |
| 1804 |
non-deprecated alias macro. |
| 1805 |
.PP |
| 1806 |
The \fBEVP_CIPHER_CTX_flags()\fR macro was deprecated in OpenSSL 1.1.0. |
| 1807 |
.PP |
| 1808 |
\&\fBEVP_CIPHER_CTX_dup()\fR was added in OpenSSL 3.2. |
| 1809 |
.PP |
| 1810 |
\&\fBEVP_CipherInit_SKEY()\fR was added in OpenSSL 3.5. |
| 1811 |
.PP |
| 1812 |
Prior to OpenSSL 3.5, passing a NULL \fIctx\fR to |
| 1813 |
\&\fBEVP_CIPHER_CTX_get_block_size()\fR would result in a NULL pointer dereference, |
| 1814 |
rather than a 0 return value indicating an error. |
| 1815 |
.SH COPYRIGHT |
| 1816 |
.IX Header "COPYRIGHT" |
| 1817 |
Copyright 2000\-2026 The OpenSSL Project Authors. All Rights Reserved. |
| 1818 |
.PP |
| 1819 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 1820 |
this file except in compliance with the License. You can obtain a copy |
| 1821 |
in the file LICENSE in the source distribution or at |
| 1822 |
<https://www.openssl.org/source/license.html>. |