1783 lines
92 KiB
Plaintext
1783 lines
92 KiB
Plaintext
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
|
.\" nothing in troff, for use with C<>.
|
|
.tr \(*W-
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
. ds C`
|
|
. ds C'
|
|
'br\}
|
|
.\"
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\"
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
.\" output yourself in some meaningful fashion.
|
|
.\"
|
|
.\" Avoid warning from groff about undefined register 'F'.
|
|
.de IX
|
|
..
|
|
.nr rF 0
|
|
.if \n(.g .if rF .nr rF 1
|
|
.if (\n(rF:(\n(.g==0)) \{
|
|
. if \nF \{
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. if !\nF==2 \{
|
|
. nr % 0
|
|
. nr F 2
|
|
. \}
|
|
. \}
|
|
.\}
|
|
.rr rF
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "EVP_ENCRYPTINIT 3ossl"
|
|
.TH EVP_ENCRYPTINIT 3ossl "2024-01-30" "3.2.1" "OpenSSL"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
.\" way too many mistakes in technical documents.
|
|
.if n .ad l
|
|
.nh
|
|
.SH "NAME"
|
|
EVP_CIPHER_fetch,
|
|
EVP_CIPHER_up_ref,
|
|
EVP_CIPHER_free,
|
|
EVP_CIPHER_CTX_new,
|
|
EVP_CIPHER_CTX_reset,
|
|
EVP_CIPHER_CTX_free,
|
|
EVP_CIPHER_CTX_dup,
|
|
EVP_CIPHER_CTX_copy,
|
|
EVP_EncryptInit_ex,
|
|
EVP_EncryptInit_ex2,
|
|
EVP_EncryptUpdate,
|
|
EVP_EncryptFinal_ex,
|
|
EVP_DecryptInit_ex,
|
|
EVP_DecryptInit_ex2,
|
|
EVP_DecryptUpdate,
|
|
EVP_DecryptFinal_ex,
|
|
EVP_CipherInit_ex,
|
|
EVP_CipherInit_ex2,
|
|
EVP_CipherUpdate,
|
|
EVP_CipherFinal_ex,
|
|
EVP_CIPHER_CTX_set_key_length,
|
|
EVP_CIPHER_CTX_ctrl,
|
|
EVP_EncryptInit,
|
|
EVP_EncryptFinal,
|
|
EVP_DecryptInit,
|
|
EVP_DecryptFinal,
|
|
EVP_CipherInit,
|
|
EVP_CipherFinal,
|
|
EVP_Cipher,
|
|
EVP_get_cipherbyname,
|
|
EVP_get_cipherbynid,
|
|
EVP_get_cipherbyobj,
|
|
EVP_CIPHER_is_a,
|
|
EVP_CIPHER_get0_name,
|
|
EVP_CIPHER_get0_description,
|
|
EVP_CIPHER_names_do_all,
|
|
EVP_CIPHER_get0_provider,
|
|
EVP_CIPHER_get_nid,
|
|
EVP_CIPHER_get_params,
|
|
EVP_CIPHER_gettable_params,
|
|
EVP_CIPHER_get_block_size,
|
|
EVP_CIPHER_get_key_length,
|
|
EVP_CIPHER_get_iv_length,
|
|
EVP_CIPHER_get_flags,
|
|
EVP_CIPHER_get_mode,
|
|
EVP_CIPHER_get_type,
|
|
EVP_CIPHER_CTX_cipher,
|
|
EVP_CIPHER_CTX_get0_cipher,
|
|
EVP_CIPHER_CTX_get1_cipher,
|
|
EVP_CIPHER_CTX_get0_name,
|
|
EVP_CIPHER_CTX_get_nid,
|
|
EVP_CIPHER_CTX_get_params,
|
|
EVP_CIPHER_gettable_ctx_params,
|
|
EVP_CIPHER_CTX_gettable_params,
|
|
EVP_CIPHER_CTX_set_params,
|
|
EVP_CIPHER_settable_ctx_params,
|
|
EVP_CIPHER_CTX_settable_params,
|
|
EVP_CIPHER_CTX_get_block_size,
|
|
EVP_CIPHER_CTX_get_key_length,
|
|
EVP_CIPHER_CTX_get_iv_length,
|
|
EVP_CIPHER_CTX_get_tag_length,
|
|
EVP_CIPHER_CTX_get_app_data,
|
|
EVP_CIPHER_CTX_set_app_data,
|
|
EVP_CIPHER_CTX_flags,
|
|
EVP_CIPHER_CTX_set_flags,
|
|
EVP_CIPHER_CTX_clear_flags,
|
|
EVP_CIPHER_CTX_test_flags,
|
|
EVP_CIPHER_CTX_get_type,
|
|
EVP_CIPHER_CTX_get_mode,
|
|
EVP_CIPHER_CTX_get_num,
|
|
EVP_CIPHER_CTX_set_num,
|
|
EVP_CIPHER_CTX_is_encrypting,
|
|
EVP_CIPHER_param_to_asn1,
|
|
EVP_CIPHER_asn1_to_param,
|
|
EVP_CIPHER_CTX_set_padding,
|
|
EVP_enc_null,
|
|
EVP_CIPHER_do_all_provided,
|
|
EVP_CIPHER_nid,
|
|
EVP_CIPHER_name,
|
|
EVP_CIPHER_block_size,
|
|
EVP_CIPHER_key_length,
|
|
EVP_CIPHER_iv_length,
|
|
EVP_CIPHER_flags,
|
|
EVP_CIPHER_mode,
|
|
EVP_CIPHER_type,
|
|
EVP_CIPHER_CTX_encrypting,
|
|
EVP_CIPHER_CTX_nid,
|
|
EVP_CIPHER_CTX_block_size,
|
|
EVP_CIPHER_CTX_key_length,
|
|
EVP_CIPHER_CTX_iv_length,
|
|
EVP_CIPHER_CTX_tag_length,
|
|
EVP_CIPHER_CTX_num,
|
|
EVP_CIPHER_CTX_type,
|
|
EVP_CIPHER_CTX_mode
|
|
\&\- EVP cipher routines
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 1
|
|
\& #include <openssl/evp.h>
|
|
\&
|
|
\& EVP_CIPHER *EVP_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
|
|
\& const char *properties);
|
|
\& int EVP_CIPHER_up_ref(EVP_CIPHER *cipher);
|
|
\& void EVP_CIPHER_free(EVP_CIPHER *cipher);
|
|
\& EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);
|
|
\& int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);
|
|
\& void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);
|
|
\& EVP_CIPHER_CTX *EVP_CIPHER_CTX_dup(const EVP_CIPHER_CTX *in);
|
|
\& int EVP_CIPHER_CTX_copy(EVP_CIPHER_CTX *out, const EVP_CIPHER_CTX *in);
|
|
\&
|
|
\& int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
|
|
\& ENGINE *impl, const unsigned char *key, const unsigned char *iv);
|
|
\& int EVP_EncryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
|
|
\& const unsigned char *key, const unsigned char *iv,
|
|
\& const OSSL_PARAM params[]);
|
|
\& int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
|
|
\& int *outl, const unsigned char *in, int inl);
|
|
\& int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
|
|
\&
|
|
\& int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
|
|
\& ENGINE *impl, const unsigned char *key, const unsigned char *iv);
|
|
\& int EVP_DecryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
|
|
\& const unsigned char *key, const unsigned char *iv,
|
|
\& const OSSL_PARAM params[]);
|
|
\& int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
|
|
\& int *outl, const unsigned char *in, int inl);
|
|
\& int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
|
|
\&
|
|
\& int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
|
|
\& ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc);
|
|
\& int EVP_CipherInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
|
|
\& const unsigned char *key, const unsigned char *iv,
|
|
\& int enc, const OSSL_PARAM params[]);
|
|
\& int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
|
|
\& int *outl, const unsigned char *in, int inl);
|
|
\& int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
|
|
\&
|
|
\& int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
|
|
\& const unsigned char *key, const unsigned char *iv);
|
|
\& int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
|
|
\&
|
|
\& int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
|
|
\& const unsigned char *key, const unsigned char *iv);
|
|
\& int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
|
|
\&
|
|
\& int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
|
|
\& const unsigned char *key, const unsigned char *iv, int enc);
|
|
\& int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
|
|
\&
|
|
\& int EVP_Cipher(EVP_CIPHER_CTX *ctx, unsigned char *out,
|
|
\& const unsigned char *in, unsigned int inl);
|
|
\&
|
|
\& int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
|
|
\& int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
|
|
\& int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int cmd, int p1, void *p2);
|
|
\& int EVP_CIPHER_CTX_rand_key(EVP_CIPHER_CTX *ctx, unsigned char *key);
|
|
\& void EVP_CIPHER_CTX_set_flags(EVP_CIPHER_CTX *ctx, int flags);
|
|
\& void EVP_CIPHER_CTX_clear_flags(EVP_CIPHER_CTX *ctx, int flags);
|
|
\& int EVP_CIPHER_CTX_test_flags(const EVP_CIPHER_CTX *ctx, int flags);
|
|
\&
|
|
\& const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
|
|
\& const EVP_CIPHER *EVP_get_cipherbynid(int nid);
|
|
\& const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a);
|
|
\&
|
|
\& int EVP_CIPHER_get_nid(const EVP_CIPHER *e);
|
|
\& int EVP_CIPHER_is_a(const EVP_CIPHER *cipher, const char *name);
|
|
\& int EVP_CIPHER_names_do_all(const EVP_CIPHER *cipher,
|
|
\& void (*fn)(const char *name, void *data),
|
|
\& void *data);
|
|
\& const char *EVP_CIPHER_get0_name(const EVP_CIPHER *cipher);
|
|
\& const char *EVP_CIPHER_get0_description(const EVP_CIPHER *cipher);
|
|
\& const OSSL_PROVIDER *EVP_CIPHER_get0_provider(const EVP_CIPHER *cipher);
|
|
\& int EVP_CIPHER_get_block_size(const EVP_CIPHER *e);
|
|
\& int EVP_CIPHER_get_key_length(const EVP_CIPHER *e);
|
|
\& int EVP_CIPHER_get_iv_length(const EVP_CIPHER *e);
|
|
\& unsigned long EVP_CIPHER_get_flags(const EVP_CIPHER *e);
|
|
\& unsigned long EVP_CIPHER_get_mode(const EVP_CIPHER *e);
|
|
\& int EVP_CIPHER_get_type(const EVP_CIPHER *cipher);
|
|
\&
|
|
\& const EVP_CIPHER *EVP_CIPHER_CTX_get0_cipher(const EVP_CIPHER_CTX *ctx);
|
|
\& EVP_CIPHER *EVP_CIPHER_CTX_get1_cipher(const EVP_CIPHER_CTX *ctx);
|
|
\& int EVP_CIPHER_CTX_get_nid(const EVP_CIPHER_CTX *ctx);
|
|
\& const char *EVP_CIPHER_CTX_get0_name(const EVP_CIPHER_CTX *ctx);
|
|
\&
|
|
\& int EVP_CIPHER_get_params(EVP_CIPHER *cipher, OSSL_PARAM params[]);
|
|
\& int EVP_CIPHER_CTX_set_params(EVP_CIPHER_CTX *ctx, const OSSL_PARAM params[]);
|
|
\& int EVP_CIPHER_CTX_get_params(EVP_CIPHER_CTX *ctx, OSSL_PARAM params[]);
|
|
\& const OSSL_PARAM *EVP_CIPHER_gettable_params(const EVP_CIPHER *cipher);
|
|
\& const OSSL_PARAM *EVP_CIPHER_settable_ctx_params(const EVP_CIPHER *cipher);
|
|
\& const OSSL_PARAM *EVP_CIPHER_gettable_ctx_params(const EVP_CIPHER *cipher);
|
|
\& const OSSL_PARAM *EVP_CIPHER_CTX_settable_params(EVP_CIPHER_CTX *ctx);
|
|
\& const OSSL_PARAM *EVP_CIPHER_CTX_gettable_params(EVP_CIPHER_CTX *ctx);
|
|
\& int EVP_CIPHER_CTX_get_block_size(const EVP_CIPHER_CTX *ctx);
|
|
\& int EVP_CIPHER_CTX_get_key_length(const EVP_CIPHER_CTX *ctx);
|
|
\& int EVP_CIPHER_CTX_get_iv_length(const EVP_CIPHER_CTX *ctx);
|
|
\& int EVP_CIPHER_CTX_get_tag_length(const EVP_CIPHER_CTX *ctx);
|
|
\& void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx);
|
|
\& void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data);
|
|
\& int EVP_CIPHER_CTX_get_type(const EVP_CIPHER_CTX *ctx);
|
|
\& int EVP_CIPHER_CTX_get_mode(const EVP_CIPHER_CTX *ctx);
|
|
\& int EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx);
|
|
\& int EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num);
|
|
\& int EVP_CIPHER_CTX_is_encrypting(const EVP_CIPHER_CTX *ctx);
|
|
\&
|
|
\& int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
|
|
\& int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
|
|
\&
|
|
\& void EVP_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx,
|
|
\& void (*fn)(EVP_CIPHER *cipher, void *arg),
|
|
\& void *arg);
|
|
\&
|
|
\& #define EVP_CIPHER_nid EVP_CIPHER_get_nid
|
|
\& #define EVP_CIPHER_name EVP_CIPHER_get0_name
|
|
\& #define EVP_CIPHER_block_size EVP_CIPHER_get_block_size
|
|
\& #define EVP_CIPHER_key_length EVP_CIPHER_get_key_length
|
|
\& #define EVP_CIPHER_iv_length EVP_CIPHER_get_iv_length
|
|
\& #define EVP_CIPHER_flags EVP_CIPHER_get_flags
|
|
\& #define EVP_CIPHER_mode EVP_CIPHER_get_mode
|
|
\& #define EVP_CIPHER_type EVP_CIPHER_get_type
|
|
\& #define EVP_CIPHER_CTX_encrypting EVP_CIPHER_CTX_is_encrypting
|
|
\& #define EVP_CIPHER_CTX_nid EVP_CIPHER_CTX_get_nid
|
|
\& #define EVP_CIPHER_CTX_block_size EVP_CIPHER_CTX_get_block_size
|
|
\& #define EVP_CIPHER_CTX_key_length EVP_CIPHER_CTX_get_key_length
|
|
\& #define EVP_CIPHER_CTX_iv_length EVP_CIPHER_CTX_get_iv_length
|
|
\& #define EVP_CIPHER_CTX_tag_length EVP_CIPHER_CTX_get_tag_length
|
|
\& #define EVP_CIPHER_CTX_num EVP_CIPHER_CTX_get_num
|
|
\& #define EVP_CIPHER_CTX_type EVP_CIPHER_CTX_get_type
|
|
\& #define EVP_CIPHER_CTX_mode EVP_CIPHER_CTX_get_mode
|
|
.Ve
|
|
.PP
|
|
The following function has been deprecated since OpenSSL 3.0, and can be
|
|
hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value,
|
|
see \fIopenssl_user_macros\fR\|(7):
|
|
.PP
|
|
.Vb 1
|
|
\& const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx);
|
|
.Ve
|
|
.PP
|
|
The following function has been deprecated since OpenSSL 1.1.0, and can be
|
|
hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value,
|
|
see \fIopenssl_user_macros\fR\|(7):
|
|
.PP
|
|
.Vb 1
|
|
\& int EVP_CIPHER_CTX_flags(const EVP_CIPHER_CTX *ctx);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
The \s-1EVP\s0 cipher routines are a high-level interface to certain
|
|
symmetric ciphers.
|
|
.PP
|
|
The \fB\s-1EVP_CIPHER\s0\fR type is a structure for cipher method implementation.
|
|
.IP "\fIEVP_CIPHER_fetch()\fR" 4
|
|
.IX Item "EVP_CIPHER_fetch()"
|
|
Fetches the cipher implementation for the given \fIalgorithm\fR from any provider
|
|
offering it, within the criteria given by the \fIproperties\fR.
|
|
See \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fIcrypto\fR\|(7) for further information.
|
|
.Sp
|
|
The returned value must eventually be freed with \fIEVP_CIPHER_free()\fR.
|
|
.Sp
|
|
Fetched \fB\s-1EVP_CIPHER\s0\fR structures are reference counted.
|
|
.IP "\fIEVP_CIPHER_up_ref()\fR" 4
|
|
.IX Item "EVP_CIPHER_up_ref()"
|
|
Increments the reference count for an \fB\s-1EVP_CIPHER\s0\fR structure.
|
|
.IP "\fIEVP_CIPHER_free()\fR" 4
|
|
.IX Item "EVP_CIPHER_free()"
|
|
Decrements the reference count for the fetched \fB\s-1EVP_CIPHER\s0\fR structure.
|
|
If the reference count drops to 0 then the structure is freed.
|
|
.IP "\fIEVP_CIPHER_CTX_new()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_new()"
|
|
Allocates and returns a cipher context.
|
|
.IP "\fIEVP_CIPHER_CTX_free()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_free()"
|
|
Clears all information from a cipher context and frees any allocated memory
|
|
associated with it, including \fIctx\fR itself. This function should be called after
|
|
all operations using a cipher are complete so sensitive information does not
|
|
remain in memory.
|
|
.IP "\fIEVP_CIPHER_CTX_dup()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_dup()"
|
|
Can be used to duplicate the cipher state from \fIin\fR. This is useful
|
|
to avoid multiple \fIEVP_MD_fetch()\fR calls or if large amounts of data are to be
|
|
hashed which only differ in the last few bytes.
|
|
.IP "\fIEVP_CIPHER_CTX_copy()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_copy()"
|
|
Can be used to copy the cipher state from \fIin\fR to \fIout\fR.
|
|
.IP "\fIEVP_CIPHER_CTX_ctrl()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_ctrl()"
|
|
\&\fIThis is a legacy method.\fR \fIEVP_CIPHER_CTX_set_params()\fR and
|
|
\&\fIEVP_CIPHER_CTX_get_params()\fR is the mechanism that should be used to set and get
|
|
parameters that are used by providers.
|
|
.Sp
|
|
Performs cipher-specific control actions on context \fIctx\fR. The control command
|
|
is indicated in \fIcmd\fR and any additional arguments in \fIp1\fR and \fIp2\fR.
|
|
\&\fIEVP_CIPHER_CTX_ctrl()\fR must be called after \fIEVP_CipherInit_ex2()\fR. Other restrictions
|
|
may apply depending on the control type and cipher implementation.
|
|
.Sp
|
|
If this function happens to be used with a fetched \fB\s-1EVP_CIPHER\s0\fR, it will
|
|
translate the controls that are known to OpenSSL into \s-1\fIOSSL_PARAM\s0\fR\|(3)
|
|
parameters with keys defined by OpenSSL and call \fIEVP_CIPHER_CTX_get_params()\fR or
|
|
\&\fIEVP_CIPHER_CTX_set_params()\fR as is appropriate for each control command.
|
|
.Sp
|
|
See \*(L"\s-1CONTROLS\*(R"\s0 below for more information, including what translations are
|
|
being done.
|
|
.IP "\fIEVP_CIPHER_get_params()\fR" 4
|
|
.IX Item "EVP_CIPHER_get_params()"
|
|
Retrieves the requested list of algorithm \fIparams\fR from a \s-1CIPHER \s0\fIcipher\fR.
|
|
See \*(L"\s-1PARAMETERS\*(R"\s0 below for more information.
|
|
.IP "\fIEVP_CIPHER_CTX_get_params()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_get_params()"
|
|
Retrieves the requested list of \fIparams\fR from \s-1CIPHER\s0 context \fIctx\fR.
|
|
See \*(L"\s-1PARAMETERS\*(R"\s0 below for more information.
|
|
.IP "\fIEVP_CIPHER_CTX_set_params()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_set_params()"
|
|
Sets the list of \fIparams\fR into a \s-1CIPHER\s0 context \fIctx\fR.
|
|
See \*(L"\s-1PARAMETERS\*(R"\s0 below for more information.
|
|
.IP "\fIEVP_CIPHER_gettable_params()\fR" 4
|
|
.IX Item "EVP_CIPHER_gettable_params()"
|
|
Get a constant \s-1\fIOSSL_PARAM\s0\fR\|(3) array that describes the retrievable parameters
|
|
that can be used with \fIEVP_CIPHER_get_params()\fR.
|
|
.IP "\fIEVP_CIPHER_gettable_ctx_params()\fR and \fIEVP_CIPHER_CTX_gettable_params()\fR" 4
|
|
.IX Item "EVP_CIPHER_gettable_ctx_params() and EVP_CIPHER_CTX_gettable_params()"
|
|
Get a constant \s-1\fIOSSL_PARAM\s0\fR\|(3) array that describes the retrievable parameters
|
|
that can be used with \fIEVP_CIPHER_CTX_get_params()\fR.
|
|
\&\fIEVP_CIPHER_gettable_ctx_params()\fR returns the parameters that can be retrieved
|
|
from the algorithm, whereas \fIEVP_CIPHER_CTX_gettable_params()\fR returns the
|
|
parameters that can be retrieved in the context's current state.
|
|
.IP "\fIEVP_CIPHER_settable_ctx_params()\fR and \fIEVP_CIPHER_CTX_settable_params()\fR" 4
|
|
.IX Item "EVP_CIPHER_settable_ctx_params() and EVP_CIPHER_CTX_settable_params()"
|
|
Get a constant \s-1\fIOSSL_PARAM\s0\fR\|(3) array that describes the settable parameters
|
|
that can be used with \fIEVP_CIPHER_CTX_set_params()\fR.
|
|
\&\fIEVP_CIPHER_settable_ctx_params()\fR returns the parameters that can be set from the
|
|
algorithm, whereas \fIEVP_CIPHER_CTX_settable_params()\fR returns the parameters that
|
|
can be set in the context's current state.
|
|
.IP "\fIEVP_EncryptInit_ex2()\fR" 4
|
|
.IX Item "EVP_EncryptInit_ex2()"
|
|
Sets up cipher context \fIctx\fR for encryption with cipher \fItype\fR. \fItype\fR is
|
|
typically supplied by calling \fIEVP_CIPHER_fetch()\fR. \fItype\fR may also be set
|
|
using legacy functions such as \fIEVP_aes_256_cbc()\fR, but this is not recommended
|
|
for new applications. \fIkey\fR is the symmetric key to use and \fIiv\fR is the \s-1IV\s0 to
|
|
use (if necessary), the actual number of bytes used for the key and \s-1IV\s0 depends
|
|
on the cipher. The parameters \fIparams\fR will be set on the context after
|
|
initialisation. It is possible to set all parameters to \s-1NULL\s0 except \fItype\fR in
|
|
an initial call and supply the remaining parameters in subsequent calls, all of
|
|
which have \fItype\fR set to \s-1NULL.\s0 This is done when the default cipher parameters
|
|
are not appropriate.
|
|
For \fB\s-1EVP_CIPH_GCM_MODE\s0\fR the \s-1IV\s0 will be generated internally if it is not
|
|
specified.
|
|
.IP "\fIEVP_EncryptInit_ex()\fR" 4
|
|
.IX Item "EVP_EncryptInit_ex()"
|
|
This legacy function is similar to \fIEVP_EncryptInit_ex2()\fR when \fIimpl\fR is \s-1NULL.\s0
|
|
The implementation of the \fItype\fR from the \fIimpl\fR engine will be used if it
|
|
exists.
|
|
.IP "\fIEVP_EncryptUpdate()\fR" 4
|
|
.IX Item "EVP_EncryptUpdate()"
|
|
Encrypts \fIinl\fR bytes from the buffer \fIin\fR and writes the encrypted version to
|
|
\&\fIout\fR. The pointers \fIout\fR and \fIin\fR may point to the same location, in which
|
|
case the encryption will be done in-place. If \fIout\fR and \fIin\fR point to different
|
|
locations, the two buffers must be disjoint, otherwise the operation might fail
|
|
or the outcome might be undefined.
|
|
.Sp
|
|
This function can be called multiple times to encrypt successive blocks
|
|
of data. The amount of data written depends on the block alignment of the
|
|
encrypted data.
|
|
For most ciphers and modes, the amount of data written can be anything
|
|
from zero bytes to (inl + cipher_block_size \- 1) bytes.
|
|
For wrap cipher modes, the amount of data written can be anything
|
|
from zero bytes to (inl + cipher_block_size) bytes.
|
|
For stream ciphers, the amount of data written can be anything from zero
|
|
bytes to inl bytes.
|
|
Thus, the buffer pointed to by \fIout\fR must contain sufficient room for the
|
|
operation being performed.
|
|
The actual number of bytes written is placed in \fIoutl\fR.
|
|
.Sp
|
|
If padding is enabled (the default) then \fIEVP_EncryptFinal_ex()\fR encrypts
|
|
the \*(L"final\*(R" data, that is any data that remains in a partial block.
|
|
It uses standard block padding (aka \s-1PKCS\s0 padding) as described in
|
|
the \s-1NOTES\s0 section, below. The encrypted
|
|
final data is written to \fIout\fR which should have sufficient space for
|
|
one cipher block. The number of bytes written is placed in \fIoutl\fR. After
|
|
this function is called the encryption operation is finished and no further
|
|
calls to \fIEVP_EncryptUpdate()\fR should be made.
|
|
.Sp
|
|
If padding is disabled then \fIEVP_EncryptFinal_ex()\fR will not encrypt any more
|
|
data and it will return an error if any data remains in a partial block:
|
|
that is if the total data length is not a multiple of the block size.
|
|
.IP "\fIEVP_DecryptInit_ex2()\fR, \fIEVP_DecryptInit_ex()\fR, \fIEVP_DecryptUpdate()\fR and \fIEVP_DecryptFinal_ex()\fR" 4
|
|
.IX Item "EVP_DecryptInit_ex2(), EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex()"
|
|
These functions are the corresponding decryption operations.
|
|
\&\fIEVP_DecryptFinal()\fR will return an error code if padding is enabled and the
|
|
final block is not correctly formatted. The parameters and restrictions are
|
|
identical to the encryption operations except that if padding is enabled the
|
|
decrypted data buffer \fIout\fR passed to \fIEVP_DecryptUpdate()\fR should have
|
|
sufficient room for (\fIinl\fR + cipher_block_size) bytes unless the cipher block
|
|
size is 1 in which case \fIinl\fR bytes is sufficient.
|
|
.IP "\fIEVP_CipherInit_ex2()\fR, \fIEVP_CipherInit_ex()\fR, \fIEVP_CipherUpdate()\fR and \fIEVP_CipherFinal_ex()\fR" 4
|
|
.IX Item "EVP_CipherInit_ex2(), EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex()"
|
|
These functions can be used for decryption or encryption. The operation
|
|
performed depends on the value of the \fIenc\fR parameter. It should be set to 1
|
|
for encryption, 0 for decryption and \-1 to leave the value unchanged
|
|
(the actual value of 'enc' being supplied in a previous call).
|
|
.IP "\fIEVP_CIPHER_CTX_reset()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_reset()"
|
|
Clears all information from a cipher context and free up any allocated memory
|
|
associated with it, except the \fIctx\fR itself. This function should be called
|
|
anytime \fIctx\fR is reused by another
|
|
\&\fIEVP_CipherInit()\fR / \fIEVP_CipherUpdate()\fR / \fIEVP_CipherFinal()\fR series of calls.
|
|
.IP "\fIEVP_EncryptInit()\fR, \fIEVP_DecryptInit()\fR and \fIEVP_CipherInit()\fR" 4
|
|
.IX Item "EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit()"
|
|
Behave in a similar way to \fIEVP_EncryptInit_ex()\fR, \fIEVP_DecryptInit_ex()\fR and
|
|
\&\fIEVP_CipherInit_ex()\fR except if the \fItype\fR is not a fetched cipher they use the
|
|
default implementation of the \fItype\fR.
|
|
.IP "\fIEVP_EncryptFinal()\fR, \fIEVP_DecryptFinal()\fR and \fIEVP_CipherFinal()\fR" 4
|
|
.IX Item "EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal()"
|
|
Identical to \fIEVP_EncryptFinal_ex()\fR, \fIEVP_DecryptFinal_ex()\fR and
|
|
\&\fIEVP_CipherFinal_ex()\fR. In previous releases they also cleaned up
|
|
the \fIctx\fR, but this is no longer done and \fIEVP_CIPHER_CTX_cleanup()\fR
|
|
must be called to free any context resources.
|
|
.IP "\fIEVP_Cipher()\fR" 4
|
|
.IX Item "EVP_Cipher()"
|
|
Encrypts or decrypts a maximum \fIinl\fR amount of bytes from \fIin\fR and leaves the
|
|
result in \fIout\fR.
|
|
.Sp
|
|
For legacy ciphers \- If the cipher doesn't have the flag
|
|
\&\fB\s-1EVP_CIPH_FLAG_CUSTOM_CIPHER\s0\fR set, then \fIinl\fR must be a multiple of
|
|
\&\fIEVP_CIPHER_get_block_size()\fR. If it isn't, the result is undefined. If the cipher
|
|
has that flag set, then \fIinl\fR can be any size.
|
|
.Sp
|
|
Due to the constraints of the \s-1API\s0 contract of this function it shouldn't be used
|
|
in applications, please consider using \fIEVP_CipherUpdate()\fR and
|
|
\&\fIEVP_CipherFinal_ex()\fR instead.
|
|
.IP "\fIEVP_get_cipherbyname()\fR, \fIEVP_get_cipherbynid()\fR and \fIEVP_get_cipherbyobj()\fR" 4
|
|
.IX Item "EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()"
|
|
Returns an \fB\s-1EVP_CIPHER\s0\fR structure when passed a cipher name, a cipher \fB\s-1NID\s0\fR or
|
|
an \fB\s-1ASN1_OBJECT\s0\fR structure respectively.
|
|
.Sp
|
|
\&\fIEVP_get_cipherbyname()\fR will return \s-1NULL\s0 for algorithms such as \*(L"\s-1AES\-128\-SIV\*(R",
|
|
\&\*(L"AES\-128\-CBC\-CTS\*(R"\s0 and \*(L"\s-1CAMELLIA\-128\-CBC\-CTS\*(R"\s0 which were previously only
|
|
accessible via low level interfaces.
|
|
.Sp
|
|
The \fIEVP_get_cipherbyname()\fR function is present for backwards compatibility with
|
|
OpenSSL prior to version 3 and is different to the \fIEVP_CIPHER_fetch()\fR function
|
|
since it does not attempt to \*(L"fetch\*(R" an implementation of the cipher.
|
|
Additionally, it only knows about ciphers that are built-in to OpenSSL and have
|
|
an associated \s-1NID.\s0 Similarly \fIEVP_get_cipherbynid()\fR and \fIEVP_get_cipherbyobj()\fR
|
|
also return objects without an associated implementation.
|
|
.Sp
|
|
When the cipher objects returned by these functions are used (such as in a call
|
|
to \fIEVP_EncryptInit_ex()\fR) an implementation of the cipher will be implicitly
|
|
fetched from the loaded providers. This fetch could fail if no suitable
|
|
implementation is available. Use \fIEVP_CIPHER_fetch()\fR instead to explicitly fetch
|
|
the algorithm and an associated implementation from a provider.
|
|
.Sp
|
|
See \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fIcrypto\fR\|(7) for more information about fetching.
|
|
.Sp
|
|
The cipher objects returned from these functions do not need to be freed with
|
|
\&\fIEVP_CIPHER_free()\fR.
|
|
.IP "\fIEVP_CIPHER_get_nid()\fR and \fIEVP_CIPHER_CTX_get_nid()\fR" 4
|
|
.IX Item "EVP_CIPHER_get_nid() and EVP_CIPHER_CTX_get_nid()"
|
|
Return the \s-1NID\s0 of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR
|
|
structure. The actual \s-1NID\s0 value is an internal value which may not have a
|
|
corresponding \s-1OBJECT IDENTIFIER.\s0
|
|
.IP "\fIEVP_CIPHER_CTX_set_flags()\fR, \fIEVP_CIPHER_CTX_clear_flags()\fR and \fIEVP_CIPHER_CTX_test_flags()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_set_flags(), EVP_CIPHER_CTX_clear_flags() and EVP_CIPHER_CTX_test_flags()"
|
|
Sets, clears and tests \fIctx\fR flags. See \*(L"\s-1FLAGS\*(R"\s0 below for more information.
|
|
.Sp
|
|
For provided ciphers \fIEVP_CIPHER_CTX_set_flags()\fR should be called only after the
|
|
fetched cipher has been assigned to the \fIctx\fR. It is recommended to use
|
|
\&\*(L"\s-1PARAMETERS\*(R"\s0 instead.
|
|
.IP "\fIEVP_CIPHER_CTX_set_padding()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_set_padding()"
|
|
Enables or disables padding. This function should be called after the context
|
|
is set up for encryption or decryption with \fIEVP_EncryptInit_ex2()\fR,
|
|
\&\fIEVP_DecryptInit_ex2()\fR or \fIEVP_CipherInit_ex2()\fR. By default encryption operations
|
|
are padded using standard block padding and the padding is checked and removed
|
|
when decrypting. If the \fIpad\fR parameter is zero then no padding is
|
|
performed, the total amount of data encrypted or decrypted must then
|
|
be a multiple of the block size or an error will occur.
|
|
.IP "\fIEVP_CIPHER_get_key_length()\fR and \fIEVP_CIPHER_CTX_get_key_length()\fR" 4
|
|
.IX Item "EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length()"
|
|
Return the key length of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or
|
|
\&\fB\s-1EVP_CIPHER_CTX\s0\fR structure. The constant \fB\s-1EVP_MAX_KEY_LENGTH\s0\fR is the maximum
|
|
key length for all ciphers. Note: although \fIEVP_CIPHER_get_key_length()\fR is fixed for
|
|
a given cipher, the value of \fIEVP_CIPHER_CTX_get_key_length()\fR may be different for
|
|
variable key length ciphers.
|
|
.IP "\fIEVP_CIPHER_CTX_set_key_length()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_set_key_length()"
|
|
Sets the key length of the cipher context.
|
|
If the cipher is a fixed length cipher then attempting to set the key
|
|
length to any value other than the fixed value is an error.
|
|
.IP "\fIEVP_CIPHER_get_iv_length()\fR and \fIEVP_CIPHER_CTX_get_iv_length()\fR" 4
|
|
.IX Item "EVP_CIPHER_get_iv_length() and EVP_CIPHER_CTX_get_iv_length()"
|
|
Return the \s-1IV\s0 length of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or
|
|
\&\fB\s-1EVP_CIPHER_CTX\s0\fR. It will return zero if the cipher does not use an \s-1IV.\s0
|
|
The constant \fB\s-1EVP_MAX_IV_LENGTH\s0\fR is the maximum \s-1IV\s0 length for all ciphers.
|
|
.IP "\fIEVP_CIPHER_CTX_get_tag_length()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_get_tag_length()"
|
|
Returns the tag length of an \s-1AEAD\s0 cipher when passed a \fB\s-1EVP_CIPHER_CTX\s0\fR. It will
|
|
return zero if the cipher does not support a tag. It returns a default value if
|
|
the tag length has not been set.
|
|
.IP "\fIEVP_CIPHER_get_block_size()\fR and \fIEVP_CIPHER_CTX_get_block_size()\fR" 4
|
|
.IX Item "EVP_CIPHER_get_block_size() and EVP_CIPHER_CTX_get_block_size()"
|
|
Return the block size of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or
|
|
\&\fB\s-1EVP_CIPHER_CTX\s0\fR structure. The constant \fB\s-1EVP_MAX_BLOCK_LENGTH\s0\fR is also the
|
|
maximum block length for all ciphers.
|
|
.IP "\fIEVP_CIPHER_get_type()\fR and \fIEVP_CIPHER_CTX_get_type()\fR" 4
|
|
.IX Item "EVP_CIPHER_get_type() and EVP_CIPHER_CTX_get_type()"
|
|
Return the type of the passed cipher or context. This \*(L"type\*(R" is the actual \s-1NID\s0
|
|
of the cipher \s-1OBJECT IDENTIFIER\s0 and as such it ignores the cipher parameters
|
|
(40 bit \s-1RC2\s0 and 128 bit \s-1RC2\s0 have the same \s-1NID\s0). If the cipher does not have an
|
|
object identifier or does not have \s-1ASN1\s0 support this function will return
|
|
\&\fBNID_undef\fR.
|
|
.IP "\fIEVP_CIPHER_is_a()\fR" 4
|
|
.IX Item "EVP_CIPHER_is_a()"
|
|
Returns 1 if \fIcipher\fR is an implementation of an algorithm that's identifiable
|
|
with \fIname\fR, otherwise 0. If \fIcipher\fR is a legacy cipher (it's the return
|
|
value from the likes of \fIEVP_aes128()\fR rather than the result of an
|
|
\&\fIEVP_CIPHER_fetch()\fR), only cipher names registered with the default library
|
|
context (see \s-1\fIOSSL_LIB_CTX\s0\fR\|(3)) will be considered.
|
|
.IP "\fIEVP_CIPHER_get0_name()\fR and \fIEVP_CIPHER_CTX_get0_name()\fR" 4
|
|
.IX Item "EVP_CIPHER_get0_name() and EVP_CIPHER_CTX_get0_name()"
|
|
Return the name of the passed cipher or context. For fetched ciphers with
|
|
multiple names, only one of them is returned. See also \fIEVP_CIPHER_names_do_all()\fR.
|
|
.IP "\fIEVP_CIPHER_names_do_all()\fR" 4
|
|
.IX Item "EVP_CIPHER_names_do_all()"
|
|
Traverses all names for the \fIcipher\fR, and calls \fIfn\fR with each name and
|
|
\&\fIdata\fR. This is only useful with fetched \fB\s-1EVP_CIPHER\s0\fRs.
|
|
.IP "\fIEVP_CIPHER_get0_description()\fR" 4
|
|
.IX Item "EVP_CIPHER_get0_description()"
|
|
Returns a description of the cipher, meant for display and human consumption.
|
|
The description is at the discretion of the cipher implementation.
|
|
.IP "\fIEVP_CIPHER_get0_provider()\fR" 4
|
|
.IX Item "EVP_CIPHER_get0_provider()"
|
|
Returns an \fB\s-1OSSL_PROVIDER\s0\fR pointer to the provider that implements the given
|
|
\&\fB\s-1EVP_CIPHER\s0\fR.
|
|
.IP "\fIEVP_CIPHER_CTX_get0_cipher()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_get0_cipher()"
|
|
Returns the \fB\s-1EVP_CIPHER\s0\fR structure when passed an \fB\s-1EVP_CIPHER_CTX\s0\fR structure.
|
|
\&\fIEVP_CIPHER_CTX_get1_cipher()\fR is the same except the ownership is passed to
|
|
the caller.
|
|
.IP "\fIEVP_CIPHER_get_mode()\fR and \fIEVP_CIPHER_CTX_get_mode()\fR" 4
|
|
.IX Item "EVP_CIPHER_get_mode() and EVP_CIPHER_CTX_get_mode()"
|
|
Return the block cipher mode:
|
|
\&\s-1EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE,
|
|
EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE,
|
|
EVP_CIPH_WRAP_MODE, EVP_CIPH_OCB_MODE\s0 or \s-1EVP_CIPH_SIV_MODE.\s0
|
|
If the cipher is a stream cipher then \s-1EVP_CIPH_STREAM_CIPHER\s0 is returned.
|
|
.IP "\fIEVP_CIPHER_get_flags()\fR" 4
|
|
.IX Item "EVP_CIPHER_get_flags()"
|
|
Returns any flags associated with the cipher. See \*(L"\s-1FLAGS\*(R"\s0
|
|
for a list of currently defined flags.
|
|
.IP "\fIEVP_CIPHER_CTX_get_num()\fR and \fIEVP_CIPHER_CTX_set_num()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_get_num() and EVP_CIPHER_CTX_set_num()"
|
|
Gets or sets the cipher specific \*(L"num\*(R" parameter for the associated \fIctx\fR.
|
|
Built-in ciphers typically use this to track how much of the current underlying block
|
|
has been \*(L"used\*(R" already.
|
|
.IP "\fIEVP_CIPHER_CTX_is_encrypting()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_is_encrypting()"
|
|
Reports whether the \fIctx\fR is being used for encryption or decryption.
|
|
.IP "\fIEVP_CIPHER_CTX_flags()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_flags()"
|
|
A deprecated macro calling \f(CW\*(C`EVP_CIPHER_get_flags(EVP_CIPHER_CTX_get0_cipher(ctx))\*(C'\fR.
|
|
Do not use.
|
|
.IP "\fIEVP_CIPHER_param_to_asn1()\fR" 4
|
|
.IX Item "EVP_CIPHER_param_to_asn1()"
|
|
Sets the AlgorithmIdentifier \*(L"parameter\*(R" based on the passed cipher. This will
|
|
typically include any parameters and an \s-1IV.\s0 The cipher \s-1IV \s0(if any) must be set
|
|
when this call is made. This call should be made before the cipher is actually
|
|
\&\*(L"used\*(R" (before any \fIEVP_EncryptUpdate()\fR, \fIEVP_DecryptUpdate()\fR calls for example).
|
|
This function may fail if the cipher does not have any \s-1ASN1\s0 support.
|
|
.IP "\fIEVP_CIPHER_asn1_to_param()\fR" 4
|
|
.IX Item "EVP_CIPHER_asn1_to_param()"
|
|
Sets the cipher parameters based on an \s-1ASN1\s0 AlgorithmIdentifier \*(L"parameter\*(R".
|
|
The precise effect depends on the cipher. In the case of \fB\s-1RC2\s0\fR, for example,
|
|
it will set the \s-1IV\s0 and effective key length.
|
|
This function should be called after the base cipher type is set but before
|
|
the key is set. For example \fIEVP_CipherInit()\fR will be called with the \s-1IV\s0 and
|
|
key set to \s-1NULL,\s0 \fIEVP_CIPHER_asn1_to_param()\fR will be called and finally
|
|
\&\fIEVP_CipherInit()\fR again with all parameters except the key set to \s-1NULL.\s0 It is
|
|
possible for this function to fail if the cipher does not have any \s-1ASN1\s0 support
|
|
or the parameters cannot be set (for example the \s-1RC2\s0 effective key length
|
|
is not supported.
|
|
.IP "\fIEVP_CIPHER_CTX_rand_key()\fR" 4
|
|
.IX Item "EVP_CIPHER_CTX_rand_key()"
|
|
Generates a random key of the appropriate length based on the cipher context.
|
|
The \fB\s-1EVP_CIPHER\s0\fR can provide its own random key generation routine to support
|
|
keys of a specific form. \fIkey\fR must point to a buffer at least as big as the
|
|
value returned by \fIEVP_CIPHER_CTX_get_key_length()\fR.
|
|
.IP "\fIEVP_CIPHER_do_all_provided()\fR" 4
|
|
.IX Item "EVP_CIPHER_do_all_provided()"
|
|
Traverses all ciphers implemented by all activated providers in the given
|
|
library context \fIlibctx\fR, and for each of the implementations, calls the given
|
|
function \fIfn\fR with the implementation method and the given \fIarg\fR as argument.
|
|
.SH "PARAMETERS"
|
|
.IX Header "PARAMETERS"
|
|
See \s-1\fIOSSL_PARAM\s0\fR\|(3) for information about passing parameters.
|
|
.SS "Gettable \s-1EVP_CIPHER\s0 parameters"
|
|
.IX Subsection "Gettable EVP_CIPHER parameters"
|
|
When \fIEVP_CIPHER_fetch()\fR is called it internally calls \fIEVP_CIPHER_get_params()\fR
|
|
and caches the results.
|
|
.PP
|
|
\&\fIEVP_CIPHER_get_params()\fR can be used with the following \s-1\fIOSSL_PARAM\s0\fR\|(3) keys:
|
|
.ie n .IP """mode"" (\fB\s-1OSSL_CIPHER_PARAM_MODE\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``mode'' (\fB\s-1OSSL_CIPHER_PARAM_MODE\s0\fR) <unsigned integer>" 4
|
|
.IX Item "mode (OSSL_CIPHER_PARAM_MODE) <unsigned integer>"
|
|
Gets the mode for the associated cipher algorithm \fIcipher\fR.
|
|
See \*(L"\fIEVP_CIPHER_get_mode()\fR and \fIEVP_CIPHER_CTX_get_mode()\fR\*(R" for a list of valid modes.
|
|
Use \fIEVP_CIPHER_get_mode()\fR to retrieve the cached value.
|
|
.ie n .IP """keylen"" (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``keylen'' (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR) <unsigned integer>" 4
|
|
.IX Item "keylen (OSSL_CIPHER_PARAM_KEYLEN) <unsigned integer>"
|
|
Gets the key length for the associated cipher algorithm \fIcipher\fR.
|
|
Use \fIEVP_CIPHER_get_key_length()\fR to retrieve the cached value.
|
|
.ie n .IP """ivlen"" (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``ivlen'' (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR) <unsigned integer>" 4
|
|
.IX Item "ivlen (OSSL_CIPHER_PARAM_IVLEN) <unsigned integer>"
|
|
Gets the \s-1IV\s0 length for the associated cipher algorithm \fIcipher\fR.
|
|
Use \fIEVP_CIPHER_get_iv_length()\fR to retrieve the cached value.
|
|
.ie n .IP """blocksize"" (\fB\s-1OSSL_CIPHER_PARAM_BLOCK_SIZE\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``blocksize'' (\fB\s-1OSSL_CIPHER_PARAM_BLOCK_SIZE\s0\fR) <unsigned integer>" 4
|
|
.IX Item "blocksize (OSSL_CIPHER_PARAM_BLOCK_SIZE) <unsigned integer>"
|
|
Gets the block size for the associated cipher algorithm \fIcipher\fR.
|
|
The block size should be 1 for stream ciphers.
|
|
Note that the block size for a cipher may be different to the block size for
|
|
the underlying encryption/decryption primitive.
|
|
For example \s-1AES\s0 in \s-1CTR\s0 mode has a block size of 1 (because it operates like a
|
|
stream cipher), even though \s-1AES\s0 has a block size of 16.
|
|
Use \fIEVP_CIPHER_get_block_size()\fR to retrieve the cached value.
|
|
.ie n .IP """aead"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD\s0\fR) <integer>" 4
|
|
.el .IP "``aead'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD\s0\fR) <integer>" 4
|
|
.IX Item "aead (OSSL_CIPHER_PARAM_AEAD) <integer>"
|
|
Gets 1 if this is an \s-1AEAD\s0 cipher algorithm, otherwise it gets 0.
|
|
Use (EVP_CIPHER_get_flags(cipher) & \s-1EVP_CIPH_FLAG_AEAD_CIPHER\s0) to retrieve the
|
|
cached value.
|
|
.ie n .IP """custom-iv"" (\fB\s-1OSSL_CIPHER_PARAM_CUSTOM_IV\s0\fR) <integer>" 4
|
|
.el .IP "``custom-iv'' (\fB\s-1OSSL_CIPHER_PARAM_CUSTOM_IV\s0\fR) <integer>" 4
|
|
.IX Item "custom-iv (OSSL_CIPHER_PARAM_CUSTOM_IV) <integer>"
|
|
Gets 1 if the cipher algorithm \fIcipher\fR has a custom \s-1IV,\s0 otherwise it gets 0.
|
|
Storing and initializing the \s-1IV\s0 is left entirely to the implementation, if a
|
|
custom \s-1IV\s0 is used.
|
|
Use (EVP_CIPHER_get_flags(cipher) & \s-1EVP_CIPH_CUSTOM_IV\s0) to retrieve the
|
|
cached value.
|
|
.ie n .IP """cts"" (\fB\s-1OSSL_CIPHER_PARAM_CTS\s0\fR) <integer>" 4
|
|
.el .IP "``cts'' (\fB\s-1OSSL_CIPHER_PARAM_CTS\s0\fR) <integer>" 4
|
|
.IX Item "cts (OSSL_CIPHER_PARAM_CTS) <integer>"
|
|
Gets 1 if the cipher algorithm \fIcipher\fR uses ciphertext stealing,
|
|
otherwise it gets 0.
|
|
This is currently used to indicate that the cipher is a one shot that only
|
|
allows a single call to \fIEVP_CipherUpdate()\fR.
|
|
Use (EVP_CIPHER_get_flags(cipher) & \s-1EVP_CIPH_FLAG_CTS\s0) to retrieve the
|
|
cached value.
|
|
.ie n .IP """tls-multi"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK\s0\fR) <integer>" 4
|
|
.el .IP "``tls-multi'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK\s0\fR) <integer>" 4
|
|
.IX Item "tls-multi (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK) <integer>"
|
|
Gets 1 if the cipher algorithm \fIcipher\fR supports interleaving of crypto blocks,
|
|
otherwise it gets 0. The interleaving is an optimization only applicable to certain
|
|
\&\s-1TLS\s0 ciphers.
|
|
Use (EVP_CIPHER_get_flags(cipher) & \s-1EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK\s0) to retrieve the
|
|
cached value.
|
|
.ie n .IP """has-randkey"" (\fB\s-1OSSL_CIPHER_PARAM_HAS_RANDKEY\s0\fR) <integer>" 4
|
|
.el .IP "``has-randkey'' (\fB\s-1OSSL_CIPHER_PARAM_HAS_RANDKEY\s0\fR) <integer>" 4
|
|
.IX Item "has-randkey (OSSL_CIPHER_PARAM_HAS_RANDKEY) <integer>"
|
|
Gets 1 if the cipher algorithm \fIcipher\fR supports the gettable \s-1EVP_CIPHER_CTX\s0
|
|
parameter \fB\s-1OSSL_CIPHER_PARAM_RANDOM_KEY\s0\fR. Only \s-1DES\s0 and 3DES set this to 1,
|
|
all other OpenSSL ciphers return 0.
|
|
.SS "Gettable and Settable \s-1EVP_CIPHER_CTX\s0 parameters"
|
|
.IX Subsection "Gettable and Settable EVP_CIPHER_CTX parameters"
|
|
The following \s-1\fIOSSL_PARAM\s0\fR\|(3) keys can be used with both \fIEVP_CIPHER_CTX_get_params()\fR
|
|
and \fIEVP_CIPHER_CTX_set_params()\fR.
|
|
.ie n .IP """padding"" (\fB\s-1OSSL_CIPHER_PARAM_PADDING\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``padding'' (\fB\s-1OSSL_CIPHER_PARAM_PADDING\s0\fR) <unsigned integer>" 4
|
|
.IX Item "padding (OSSL_CIPHER_PARAM_PADDING) <unsigned integer>"
|
|
Gets or sets the padding mode for the cipher context \fIctx\fR.
|
|
Padding is enabled if the value is 1, and disabled if the value is 0.
|
|
See also \fIEVP_CIPHER_CTX_set_padding()\fR.
|
|
.ie n .IP """num"" (\fB\s-1OSSL_CIPHER_PARAM_NUM\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``num'' (\fB\s-1OSSL_CIPHER_PARAM_NUM\s0\fR) <unsigned integer>" 4
|
|
.IX Item "num (OSSL_CIPHER_PARAM_NUM) <unsigned integer>"
|
|
Gets or sets the cipher specific \*(L"num\*(R" parameter for the cipher context \fIctx\fR.
|
|
Built-in ciphers typically use this to track how much of the current underlying
|
|
block has been \*(L"used\*(R" already.
|
|
See also \fIEVP_CIPHER_CTX_get_num()\fR and \fIEVP_CIPHER_CTX_set_num()\fR.
|
|
.ie n .IP """keylen"" (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``keylen'' (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR) <unsigned integer>" 4
|
|
.IX Item "keylen (OSSL_CIPHER_PARAM_KEYLEN) <unsigned integer>"
|
|
Gets or sets the key length for the cipher context \fIctx\fR.
|
|
The length of the \*(L"keylen\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
See also \fIEVP_CIPHER_CTX_get_key_length()\fR and \fIEVP_CIPHER_CTX_set_key_length()\fR.
|
|
.ie n .IP """tag"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAG\s0\fR) <octet string>" 4
|
|
.el .IP "``tag'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAG\s0\fR) <octet string>" 4
|
|
.IX Item "tag (OSSL_CIPHER_PARAM_AEAD_TAG) <octet string>"
|
|
Gets or sets the \s-1AEAD\s0 tag for the associated cipher context \fIctx\fR.
|
|
See \*(L"\s-1AEAD\s0 Interface\*(R" in \fIEVP_EncryptInit\fR\|(3).
|
|
.ie n .IP """keybits"" (\fB\s-1OSSL_CIPHER_PARAM_RC2_KEYBITS\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``keybits'' (\fB\s-1OSSL_CIPHER_PARAM_RC2_KEYBITS\s0\fR) <unsigned integer>" 4
|
|
.IX Item "keybits (OSSL_CIPHER_PARAM_RC2_KEYBITS) <unsigned integer>"
|
|
Gets or sets the effective keybits used for a \s-1RC2\s0 cipher.
|
|
The length of the \*(L"keybits\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
.ie n .IP """rounds"" (\fB\s-1OSSL_CIPHER_PARAM_ROUNDS\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``rounds'' (\fB\s-1OSSL_CIPHER_PARAM_ROUNDS\s0\fR) <unsigned integer>" 4
|
|
.IX Item "rounds (OSSL_CIPHER_PARAM_ROUNDS) <unsigned integer>"
|
|
Gets or sets the number of rounds to be used for a cipher.
|
|
This is used by the \s-1RC5\s0 cipher.
|
|
.ie n .IP """alg_id_param"" (\fB\s-1OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS\s0\fR) <octet string>" 4
|
|
.el .IP "``alg_id_param'' (\fB\s-1OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS\s0\fR) <octet string>" 4
|
|
.IX Item "alg_id_param (OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS) <octet string>"
|
|
Used to pass the \s-1DER\s0 encoded AlgorithmIdentifier parameter to or from
|
|
the cipher implementation. Functions like \fIEVP_CIPHER_param_to_asn1\fR\|(3)
|
|
and \fIEVP_CIPHER_asn1_to_param\fR\|(3) use this parameter for any implementation
|
|
that has the flag \fB\s-1EVP_CIPH_FLAG_CUSTOM_ASN1\s0\fR set.
|
|
.ie n .IP """cts_mode"" (\fB\s-1OSSL_CIPHER_PARAM_CTS_MODE\s0\fR) <\s-1UTF8\s0 string>" 4
|
|
.el .IP "``cts_mode'' (\fB\s-1OSSL_CIPHER_PARAM_CTS_MODE\s0\fR) <\s-1UTF8\s0 string>" 4
|
|
.IX Item "cts_mode (OSSL_CIPHER_PARAM_CTS_MODE) <UTF8 string>"
|
|
Gets or sets the cipher text stealing mode. For all modes the output size is the
|
|
same as the input size. The input length must be greater than or equal to the
|
|
block size. (The block size for \s-1AES\s0 and \s-1CAMELLIA\s0 is 16 bytes).
|
|
.Sp
|
|
Valid values for the mode are:
|
|
.RS 4
|
|
.ie n .IP """\s-1CS1""\s0" 4
|
|
.el .IP "``\s-1CS1''\s0" 4
|
|
.IX Item "CS1"
|
|
The \s-1NIST\s0 variant of cipher text stealing.
|
|
For input lengths that are multiples of the block size it is equivalent to
|
|
using a \*(L"AES-XXX-CBC\*(R" or \*(L"CAMELLIA-XXX-CBC\*(R" cipher otherwise the second last
|
|
cipher text block is a partial block.
|
|
.ie n .IP """\s-1CS2""\s0" 4
|
|
.el .IP "``\s-1CS2''\s0" 4
|
|
.IX Item "CS2"
|
|
For input lengths that are multiples of the block size it is equivalent to
|
|
using a \*(L"AES-XXX-CBC\*(R" or \*(L"CAMELLIA-XXX-CBC\*(R" cipher, otherwise it is the same as
|
|
\&\*(L"\s-1CS3\*(R"\s0 mode.
|
|
.ie n .IP """\s-1CS3""\s0" 4
|
|
.el .IP "``\s-1CS3''\s0" 4
|
|
.IX Item "CS3"
|
|
The Kerberos5 variant of cipher text stealing which always swaps the last
|
|
cipher text block with the previous block (which may be a partial or full block
|
|
depending on the input length). If the input length is exactly one full block
|
|
then this is equivalent to using a \*(L"AES-XXX-CBC\*(R" or \*(L"CAMELLIA-XXX-CBC\*(R" cipher.
|
|
.RE
|
|
.RS 4
|
|
.Sp
|
|
The default is \*(L"\s-1CS1\*(R".\s0
|
|
This is only supported for \*(L"\s-1AES\-128\-CBC\-CTS\*(R", \*(L"AES\-192\-CBC\-CTS\*(R", \*(L"AES\-256\-CBC\-CTS\*(R",
|
|
\&\*(L"CAMELLIA\-128\-CBC\-CTS\*(R", \*(L"CAMELLIA\-192\-CBC\-CTS\*(R"\s0 and \*(L"\s-1CAMELLIA\-256\-CBC\-CTS\*(R".\s0
|
|
.RE
|
|
.ie n .IP """tls1multi_interleave"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``tls1multi_interleave'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\s0\fR) <unsigned integer>" 4
|
|
.IX Item "tls1multi_interleave (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE) <unsigned integer>"
|
|
Sets or gets the number of records being sent in one go for a tls1 multiblock
|
|
cipher operation (either 4 or 8 records).
|
|
.SS "Gettable \s-1EVP_CIPHER_CTX\s0 parameters"
|
|
.IX Subsection "Gettable EVP_CIPHER_CTX parameters"
|
|
The following \s-1\fIOSSL_PARAM\s0\fR\|(3) keys can be used with \fIEVP_CIPHER_CTX_get_params()\fR:
|
|
.ie n .IP """ivlen"" (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR and <\fB\s-1OSSL_CIPHER_PARAM_AEAD_IVLEN\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``ivlen'' (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR and <\fB\s-1OSSL_CIPHER_PARAM_AEAD_IVLEN\s0\fR) <unsigned integer>" 4
|
|
.IX Item "ivlen (OSSL_CIPHER_PARAM_IVLEN and <OSSL_CIPHER_PARAM_AEAD_IVLEN) <unsigned integer>"
|
|
Gets the \s-1IV\s0 length for the cipher context \fIctx\fR.
|
|
The length of the \*(L"ivlen\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
See also \fIEVP_CIPHER_CTX_get_iv_length()\fR.
|
|
.ie n .IP """iv"" (\fB\s-1OSSL_CIPHER_PARAM_IV\s0\fR) <octet string \s-1OR\s0 octet ptr>" 4
|
|
.el .IP "``iv'' (\fB\s-1OSSL_CIPHER_PARAM_IV\s0\fR) <octet string \s-1OR\s0 octet ptr>" 4
|
|
.IX Item "iv (OSSL_CIPHER_PARAM_IV) <octet string OR octet ptr>"
|
|
Gets the \s-1IV\s0 used to initialize the associated cipher context \fIctx\fR.
|
|
See also \fIEVP_CIPHER_CTX_get_original_iv()\fR.
|
|
.ie n .IP """updated-iv"" (\fB\s-1OSSL_CIPHER_PARAM_UPDATED_IV\s0\fR) <octet string \s-1OR\s0 octet ptr>" 4
|
|
.el .IP "``updated-iv'' (\fB\s-1OSSL_CIPHER_PARAM_UPDATED_IV\s0\fR) <octet string \s-1OR\s0 octet ptr>" 4
|
|
.IX Item "updated-iv (OSSL_CIPHER_PARAM_UPDATED_IV) <octet string OR octet ptr>"
|
|
Gets the updated pseudo-IV state for the associated cipher context, e.g.,
|
|
the previous ciphertext block for \s-1CBC\s0 mode or the iteratively encrypted \s-1IV\s0
|
|
value for \s-1OFB\s0 mode. Note that octet pointer access is deprecated and is
|
|
provided only for backwards compatibility with historical libcrypto APIs.
|
|
See also \fIEVP_CIPHER_CTX_get_updated_iv()\fR.
|
|
.ie n .IP """randkey"" (\fB\s-1OSSL_CIPHER_PARAM_RANDOM_KEY\s0\fR) <octet string>" 4
|
|
.el .IP "``randkey'' (\fB\s-1OSSL_CIPHER_PARAM_RANDOM_KEY\s0\fR) <octet string>" 4
|
|
.IX Item "randkey (OSSL_CIPHER_PARAM_RANDOM_KEY) <octet string>"
|
|
Gets an implementation specific randomly generated key for the associated
|
|
cipher context \fIctx\fR. This is currently only supported by \s-1DES\s0 and 3DES (which set
|
|
the key to odd parity).
|
|
.ie n .IP """taglen"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAGLEN\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``taglen'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAGLEN\s0\fR) <unsigned integer>" 4
|
|
.IX Item "taglen (OSSL_CIPHER_PARAM_AEAD_TAGLEN) <unsigned integer>"
|
|
Gets the tag length to be used for an \s-1AEAD\s0 cipher for the associated cipher
|
|
context \fIctx\fR. It gets a default value if it has not been set.
|
|
The length of the \*(L"taglen\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
See also \fIEVP_CIPHER_CTX_get_tag_length()\fR.
|
|
.ie n .IP """tlsaadpad"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``tlsaadpad'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD\s0\fR) <unsigned integer>" 4
|
|
.IX Item "tlsaadpad (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD) <unsigned integer>"
|
|
Gets the length of the tag that will be added to a \s-1TLS\s0 record for the \s-1AEAD\s0
|
|
tag for the associated cipher context \fIctx\fR.
|
|
The length of the \*(L"tlsaadpad\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
.ie n .IP """tlsivgen"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN\s0\fR) <octet string>" 4
|
|
.el .IP "``tlsivgen'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN\s0\fR) <octet string>" 4
|
|
.IX Item "tlsivgen (OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN) <octet string>"
|
|
Gets the invocation field generated for encryption.
|
|
Can only be called after \*(L"tlsivfixed\*(R" is set.
|
|
This is only used for \s-1GCM\s0 mode.
|
|
.ie n .IP """tls1multi_enclen"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``tls1multi_enclen'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN\s0\fR) <unsigned integer>" 4
|
|
.IX Item "tls1multi_enclen (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN) <unsigned integer>"
|
|
Get the total length of the record returned from the \*(L"tls1multi_enc\*(R" operation.
|
|
.ie n .IP """tls1multi_maxbufsz"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``tls1multi_maxbufsz'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE\s0\fR) <unsigned integer>" 4
|
|
.IX Item "tls1multi_maxbufsz (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE) <unsigned integer>"
|
|
Gets the maximum record length for a \s-1TLS1\s0 multiblock cipher operation.
|
|
The length of the \*(L"tls1multi_maxbufsz\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
.ie n .IP """tls1multi_aadpacklen"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``tls1multi_aadpacklen'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN\s0\fR) <unsigned integer>" 4
|
|
.IX Item "tls1multi_aadpacklen (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN) <unsigned integer>"
|
|
Gets the result of running the \*(L"tls1multi_aad\*(R" operation.
|
|
.ie n .IP """tls-mac"" (\fB\s-1OSSL_CIPHER_PARAM_TLS_MAC\s0\fR) <octet ptr>" 4
|
|
.el .IP "``tls-mac'' (\fB\s-1OSSL_CIPHER_PARAM_TLS_MAC\s0\fR) <octet ptr>" 4
|
|
.IX Item "tls-mac (OSSL_CIPHER_PARAM_TLS_MAC) <octet ptr>"
|
|
Used to pass the \s-1TLS MAC\s0 data.
|
|
.SS "Settable \s-1EVP_CIPHER_CTX\s0 parameters"
|
|
.IX Subsection "Settable EVP_CIPHER_CTX parameters"
|
|
The following \s-1\fIOSSL_PARAM\s0\fR\|(3) keys can be used with \fIEVP_CIPHER_CTX_set_params()\fR:
|
|
.ie n .IP """mackey"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_MAC_KEY\s0\fR) <octet string>" 4
|
|
.el .IP "``mackey'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_MAC_KEY\s0\fR) <octet string>" 4
|
|
.IX Item "mackey (OSSL_CIPHER_PARAM_AEAD_MAC_KEY) <octet string>"
|
|
Sets the \s-1MAC\s0 key used by composite \s-1AEAD\s0 ciphers such as \s-1AES\-CBC\-HMAC\-SHA256.\s0
|
|
.ie n .IP """speed"" (\fB\s-1OSSL_CIPHER_PARAM_SPEED\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``speed'' (\fB\s-1OSSL_CIPHER_PARAM_SPEED\s0\fR) <unsigned integer>" 4
|
|
.IX Item "speed (OSSL_CIPHER_PARAM_SPEED) <unsigned integer>"
|
|
Sets the speed option for the associated cipher context. This is only supported
|
|
by \s-1AES SIV\s0 ciphers which disallow multiple operations by default.
|
|
Setting \*(L"speed\*(R" to 1 allows another encrypt or decrypt operation to be
|
|
performed. This is used for performance testing.
|
|
.ie n .IP """use-bits"" (\fB\s-1OSSL_CIPHER_PARAM_USE_BITS\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``use-bits'' (\fB\s-1OSSL_CIPHER_PARAM_USE_BITS\s0\fR) <unsigned integer>" 4
|
|
.IX Item "use-bits (OSSL_CIPHER_PARAM_USE_BITS) <unsigned integer>"
|
|
Determines if the input length \fIinl\fR passed to \fIEVP_EncryptUpdate()\fR,
|
|
\&\fIEVP_DecryptUpdate()\fR and \fIEVP_CipherUpdate()\fR is the number of bits or number of bytes.
|
|
Setting \*(L"use-bits\*(R" to 1 uses bits. The default is in bytes.
|
|
This is only used for \fB\s-1CFB1\s0\fR ciphers.
|
|
.Sp
|
|
This can be set using EVP_CIPHER_CTX_set_flags(ctx, \s-1EVP_CIPH_FLAG_LENGTH_BITS\s0).
|
|
.ie n .IP """tls-version"" (\fB\s-1OSSL_CIPHER_PARAM_TLS_VERSION\s0\fR) <integer>" 4
|
|
.el .IP "``tls-version'' (\fB\s-1OSSL_CIPHER_PARAM_TLS_VERSION\s0\fR) <integer>" 4
|
|
.IX Item "tls-version (OSSL_CIPHER_PARAM_TLS_VERSION) <integer>"
|
|
Sets the \s-1TLS\s0 version.
|
|
.ie n .IP """tls-mac-size"" (\fB\s-1OSSL_CIPHER_PARAM_TLS_MAC_SIZE\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``tls-mac-size'' (\fB\s-1OSSL_CIPHER_PARAM_TLS_MAC_SIZE\s0\fR) <unsigned integer>" 4
|
|
.IX Item "tls-mac-size (OSSL_CIPHER_PARAM_TLS_MAC_SIZE) <unsigned integer>"
|
|
Set the \s-1TLS MAC\s0 size.
|
|
.ie n .IP """tlsaad"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD\s0\fR) <octet string>" 4
|
|
.el .IP "``tlsaad'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD\s0\fR) <octet string>" 4
|
|
.IX Item "tlsaad (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD) <octet string>"
|
|
Sets TLSv1.2 \s-1AAD\s0 information for the associated cipher context \fIctx\fR.
|
|
TLSv1.2 \s-1AAD\s0 information is always 13 bytes in length and is as defined for the
|
|
\&\*(L"additional_data\*(R" field described in section 6.2.3.3 of \s-1RFC5246.\s0
|
|
.ie n .IP """tlsivfixed"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED\s0\fR) <octet string>" 4
|
|
.el .IP "``tlsivfixed'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED\s0\fR) <octet string>" 4
|
|
.IX Item "tlsivfixed (OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED) <octet string>"
|
|
Sets the fixed portion of an \s-1IV\s0 for an \s-1AEAD\s0 cipher used in a \s-1TLS\s0 record
|
|
encryption/ decryption for the associated cipher context.
|
|
\&\s-1TLS\s0 record encryption/decryption always occurs \*(L"in place\*(R" so that the input and
|
|
output buffers are always the same memory location.
|
|
\&\s-1AEAD\s0 IVs in TLSv1.2 consist of an implicit \*(L"fixed\*(R" part and an explicit part
|
|
that varies with every record.
|
|
Setting a \s-1TLS\s0 fixed \s-1IV\s0 changes a cipher to encrypt/decrypt \s-1TLS\s0 records.
|
|
\&\s-1TLS\s0 records are encrypted/decrypted using a single OSSL_FUNC_cipher_cipher call per
|
|
record.
|
|
For a record decryption the first bytes of the input buffer will be the explicit
|
|
part of the \s-1IV\s0 and the final bytes of the input buffer will be the \s-1AEAD\s0 tag.
|
|
The length of the explicit part of the \s-1IV\s0 and the tag length will depend on the
|
|
cipher in use and will be defined in the \s-1RFC\s0 for the relevant ciphersuite.
|
|
In order to allow for \*(L"in place\*(R" decryption the plaintext output should be
|
|
written to the same location in the output buffer that the ciphertext payload
|
|
was read from, i.e. immediately after the explicit \s-1IV.\s0
|
|
.Sp
|
|
When encrypting a record the first bytes of the input buffer should be empty to
|
|
allow space for the explicit \s-1IV,\s0 as will the final bytes where the tag will
|
|
be written.
|
|
The length of the input buffer will include the length of the explicit \s-1IV,\s0 the
|
|
payload, and the tag bytes.
|
|
The cipher implementation should generate the explicit \s-1IV\s0 and write it to the
|
|
beginning of the output buffer, do \*(L"in place\*(R" encryption of the payload and
|
|
write that to the output buffer, and finally add the tag onto the end of the
|
|
output buffer.
|
|
.Sp
|
|
Whether encrypting or decrypting the value written to \fI*outl\fR in the
|
|
OSSL_FUNC_cipher_cipher call should be the length of the payload excluding the explicit
|
|
\&\s-1IV\s0 length and the tag length.
|
|
.ie n .IP """tlsivinv"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV\s0\fR) <octet string>" 4
|
|
.el .IP "``tlsivinv'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV\s0\fR) <octet string>" 4
|
|
.IX Item "tlsivinv (OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV) <octet string>"
|
|
Sets the invocation field used for decryption.
|
|
Can only be called after \*(L"tlsivfixed\*(R" is set.
|
|
This is only used for \s-1GCM\s0 mode.
|
|
.ie n .IP """tls1multi_enc"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC\s0\fR) <octet string>" 4
|
|
.el .IP "``tls1multi_enc'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC\s0\fR) <octet string>" 4
|
|
.IX Item "tls1multi_enc (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC) <octet string>"
|
|
Triggers a multiblock \s-1TLS1\s0 encrypt operation for a \s-1TLS1\s0 aware cipher that
|
|
supports sending 4 or 8 records in one go.
|
|
The cipher performs both the \s-1MAC\s0 and encrypt stages and constructs the record
|
|
headers itself.
|
|
\&\*(L"tls1multi_enc\*(R" supplies the output buffer for the encrypt operation,
|
|
\&\*(L"tls1multi_encin\*(R" & \*(L"tls1multi_interleave\*(R" must also be set in order to supply
|
|
values to the encrypt operation.
|
|
.ie n .IP """tls1multi_encin"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN\s0\fR) <octet string>" 4
|
|
.el .IP "``tls1multi_encin'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN\s0\fR) <octet string>" 4
|
|
.IX Item "tls1multi_encin (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN) <octet string>"
|
|
Supplies the data to encrypt for a \s-1TLS1\s0 multiblock cipher operation.
|
|
.ie n .IP """tls1multi_maxsndfrag"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``tls1multi_maxsndfrag'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT\s0\fR) <unsigned integer>" 4
|
|
.IX Item "tls1multi_maxsndfrag (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT) <unsigned integer>"
|
|
Sets the maximum send fragment size for a \s-1TLS1\s0 multiblock cipher operation.
|
|
It must be set before using \*(L"tls1multi_maxbufsz\*(R".
|
|
The length of the \*(L"tls1multi_maxsndfrag\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
.ie n .IP """tls1multi_aad"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD\s0\fR) <octet string>" 4
|
|
.el .IP "``tls1multi_aad'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD\s0\fR) <octet string>" 4
|
|
.IX Item "tls1multi_aad (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD) <octet string>"
|
|
Sets the authenticated additional data used by a \s-1TLS1\s0 multiblock cipher operation.
|
|
The supplied data consists of 13 bytes of record data containing:
|
|
Bytes 0\-7: The sequence number of the first record
|
|
Byte 8: The record type
|
|
Byte 9\-10: The protocol version
|
|
Byte 11\-12: Input length (Always 0)
|
|
.Sp
|
|
\&\*(L"tls1multi_interleave\*(R" must also be set for this operation.
|
|
.ie n .IP """xts_standard"" (\fB\s-1OSSL_CIPHER_PARAM_XTS_STANDARD\s0\fR) <\s-1UTF8\s0 string>" 4
|
|
.el .IP "``xts_standard'' (\fB\s-1OSSL_CIPHER_PARAM_XTS_STANDARD\s0\fR) <\s-1UTF8\s0 string>" 4
|
|
.IX Item "xts_standard (OSSL_CIPHER_PARAM_XTS_STANDARD) <UTF8 string>"
|
|
Sets the \s-1XTS\s0 standard to use with \s-1SM4\-XTS\s0 algorithm. \s-1XTS\s0 mode has two
|
|
implementations, one is standardized in \s-1IEEE\s0 Std. 1619\-2007 and has
|
|
been widely used (e.g., \s-1XTS AES\s0), the other is proposed recently
|
|
(\s-1GB/T 17964\-2021\s0 implemented in May 2022) and is currently only used
|
|
in \s-1SM4.\s0
|
|
.Sp
|
|
The main difference between them is the multiplication by the
|
|
primitive element X to calculate the tweak values. The \s-1IEEE\s0
|
|
Std 1619\-2007 noted that the multiplication \*(L"is a left shift of each
|
|
byte by one bit with carry propagating from one byte to the next
|
|
one\*(R", which means that in each byte, the leftmost bit is the most
|
|
significant bit. But in \s-1GB/T 17964\-2021,\s0 the rightmost bit is the
|
|
most significant bit, thus the multiplication becomes a right shift
|
|
of each byte by one bit with carry propagating from one byte to the
|
|
next one.
|
|
.Sp
|
|
Valid values for the mode are:
|
|
.RS 4
|
|
.ie n .IP """\s-1GB""\s0" 4
|
|
.el .IP "``\s-1GB''\s0" 4
|
|
.IX Item "GB"
|
|
The \s-1GB/T 17964\-2021\s0 variant of \s-1SM4\-XTS\s0 algorithm.
|
|
.ie n .IP """\s-1IEEE""\s0" 4
|
|
.el .IP "``\s-1IEEE''\s0" 4
|
|
.IX Item "IEEE"
|
|
The \s-1IEEE\s0 Std. 1619\-2007 variant of \s-1SM4\-XTS\s0 algorithm.
|
|
.RE
|
|
.RS 4
|
|
.Sp
|
|
The default value is \*(L"\s-1GB\*(R".\s0
|
|
.RE
|
|
.SH "CONTROLS"
|
|
.IX Header "CONTROLS"
|
|
The Mappings from \fIEVP_CIPHER_CTX_ctrl()\fR identifiers to \s-1PARAMETERS\s0 are listed
|
|
in the following section. See the \*(L"\s-1PARAMETERS\*(R"\s0 section for more details.
|
|
.PP
|
|
\&\fIEVP_CIPHER_CTX_ctrl()\fR can be used to send the following standard controls:
|
|
.IP "\s-1EVP_CTRL_AEAD_SET_IVLEN\s0 and \s-1EVP_CTRL_GET_IVLEN\s0" 4
|
|
.IX Item "EVP_CTRL_AEAD_SET_IVLEN and EVP_CTRL_GET_IVLEN"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR and
|
|
\&\fIEVP_CIPHER_CTX_get_params()\fR get called with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the
|
|
key \*(L"ivlen\*(R" (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR).
|
|
.IP "\s-1EVP_CTRL_AEAD_SET_IV_FIXED\s0" 4
|
|
.IX Item "EVP_CTRL_AEAD_SET_IV_FIXED"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR gets called
|
|
with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the key \*(L"tlsivfixed\*(R"
|
|
(\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED\s0\fR).
|
|
.IP "\s-1EVP_CTRL_AEAD_SET_MAC_KEY\s0" 4
|
|
.IX Item "EVP_CTRL_AEAD_SET_MAC_KEY"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR gets called
|
|
with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the key \*(L"mackey\*(R"
|
|
(\fB\s-1OSSL_CIPHER_PARAM_AEAD_MAC_KEY\s0\fR).
|
|
.IP "\s-1EVP_CTRL_AEAD_SET_TAG\s0 and \s-1EVP_CTRL_AEAD_GET_TAG\s0" 4
|
|
.IX Item "EVP_CTRL_AEAD_SET_TAG and EVP_CTRL_AEAD_GET_TAG"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR and
|
|
\&\fIEVP_CIPHER_CTX_get_params()\fR get called with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the
|
|
key \*(L"tag\*(R" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAG\s0\fR).
|
|
.IP "\s-1EVP_CTRL_CCM_SET_L\s0" 4
|
|
.IX Item "EVP_CTRL_CCM_SET_L"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR gets called
|
|
with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the key \*(L"ivlen\*(R" (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR)
|
|
with a value of (15 \- L)
|
|
.IP "\s-1EVP_CTRL_COPY\s0" 4
|
|
.IX Item "EVP_CTRL_COPY"
|
|
There is no \s-1OSSL_PARAM\s0 mapping for this. Use \fIEVP_CIPHER_CTX_copy()\fR instead.
|
|
.IP "\s-1EVP_CTRL_GCM_SET_IV_INV\s0" 4
|
|
.IX Item "EVP_CTRL_GCM_SET_IV_INV"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR gets called
|
|
with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the key \*(L"tlsivinv\*(R"
|
|
(\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV\s0\fR).
|
|
.IP "\s-1EVP_CTRL_RAND_KEY\s0" 4
|
|
.IX Item "EVP_CTRL_RAND_KEY"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR gets called
|
|
with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the key \*(L"randkey\*(R"
|
|
(\fB\s-1OSSL_CIPHER_PARAM_RANDOM_KEY\s0\fR).
|
|
.IP "\s-1EVP_CTRL_SET_KEY_LENGTH\s0" 4
|
|
.IX Item "EVP_CTRL_SET_KEY_LENGTH"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR gets called
|
|
with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the key \*(L"keylen\*(R" (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR).
|
|
.IP "\s-1EVP_CTRL_SET_RC2_KEY_BITS\s0 and \s-1EVP_CTRL_GET_RC2_KEY_BITS\s0" 4
|
|
.IX Item "EVP_CTRL_SET_RC2_KEY_BITS and EVP_CTRL_GET_RC2_KEY_BITS"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR and
|
|
\&\fIEVP_CIPHER_CTX_get_params()\fR get called with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the
|
|
key \*(L"keybits\*(R" (\fB\s-1OSSL_CIPHER_PARAM_RC2_KEYBITS\s0\fR).
|
|
.IP "\s-1EVP_CTRL_SET_RC5_ROUNDS\s0 and \s-1EVP_CTRL_GET_RC5_ROUNDS\s0" 4
|
|
.IX Item "EVP_CTRL_SET_RC5_ROUNDS and EVP_CTRL_GET_RC5_ROUNDS"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR and
|
|
\&\fIEVP_CIPHER_CTX_get_params()\fR get called with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the
|
|
key \*(L"rounds\*(R" (\fB\s-1OSSL_CIPHER_PARAM_ROUNDS\s0\fR).
|
|
.IP "\s-1EVP_CTRL_SET_SPEED\s0" 4
|
|
.IX Item "EVP_CTRL_SET_SPEED"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR gets called
|
|
with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the key \*(L"speed\*(R" (\fB\s-1OSSL_CIPHER_PARAM_SPEED\s0\fR).
|
|
.IP "\s-1EVP_CTRL_GCM_IV_GEN\s0" 4
|
|
.IX Item "EVP_CTRL_GCM_IV_GEN"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_get_params()\fR gets called
|
|
with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the key
|
|
\&\*(L"tlsivgen\*(R" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN\s0\fR).
|
|
.IP "\s-1EVP_CTRL_AEAD_TLS1_AAD\s0" 4
|
|
.IX Item "EVP_CTRL_AEAD_TLS1_AAD"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR get called
|
|
with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the key
|
|
\&\*(L"tlsaad\*(R" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD\s0\fR)
|
|
followed by \fIEVP_CIPHER_CTX_get_params()\fR with a key of
|
|
\&\*(L"tlsaadpad\*(R" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD\s0\fR).
|
|
.IP "\s-1EVP_CTRL_TLS1_1_MULTIBLOCK_MAX_BUFSIZE\s0" 4
|
|
.IX Item "EVP_CTRL_TLS1_1_MULTIBLOCK_MAX_BUFSIZE"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR,
|
|
\&\fIEVP_CIPHER_CTX_set_params()\fR gets called with an \s-1\fIOSSL_PARAM\s0\fR\|(3) item with the
|
|
key \s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT\s0
|
|
followed by \fIEVP_CIPHER_CTX_get_params()\fR with a key of
|
|
\&\*(L"tls1multi_maxbufsz\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE\s0\fR).
|
|
.IP "\s-1EVP_CTRL_TLS1_1_MULTIBLOCK_AAD\s0" 4
|
|
.IX Item "EVP_CTRL_TLS1_1_MULTIBLOCK_AAD"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR gets called
|
|
with \s-1\fIOSSL_PARAM\s0\fR\|(3) items with the keys
|
|
\&\*(L"tls1multi_aad\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD\s0\fR) and
|
|
\&\*(L"tls1multi_interleave\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\s0\fR)
|
|
followed by \fIEVP_CIPHER_CTX_get_params()\fR with keys of
|
|
\&\*(L"tls1multi_aadpacklen\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN\s0\fR) and
|
|
\&\*(L"tls1multi_interleave\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\s0\fR).
|
|
.IP "\s-1EVP_CTRL_TLS1_1_MULTIBLOCK_ENCRYPT\s0" 4
|
|
.IX Item "EVP_CTRL_TLS1_1_MULTIBLOCK_ENCRYPT"
|
|
When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fIEVP_CIPHER_CTX_set_params()\fR gets called
|
|
with \s-1\fIOSSL_PARAM\s0\fR\|(3) items with the keys
|
|
\&\*(L"tls1multi_enc\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC\s0\fR),
|
|
\&\*(L"tls1multi_encin\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN\s0\fR) and
|
|
\&\*(L"tls1multi_interleave\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\s0\fR),
|
|
followed by \fIEVP_CIPHER_CTX_get_params()\fR with a key of
|
|
\&\*(L"tls1multi_enclen\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN\s0\fR).
|
|
.SH "FLAGS"
|
|
.IX Header "FLAGS"
|
|
\&\fIEVP_CIPHER_CTX_set_flags()\fR, \fIEVP_CIPHER_CTX_clear_flags()\fR and \fIEVP_CIPHER_CTX_test_flags()\fR.
|
|
can be used to manipulate and test these \fB\s-1EVP_CIPHER_CTX\s0\fR flags:
|
|
.IP "\s-1EVP_CIPH_NO_PADDING\s0" 4
|
|
.IX Item "EVP_CIPH_NO_PADDING"
|
|
Used by \fIEVP_CIPHER_CTX_set_padding()\fR.
|
|
.Sp
|
|
See also \*(L"Gettable and Settable \s-1EVP_CIPHER_CTX\s0 parameters\*(R" \*(L"padding\*(R"
|
|
.IP "\s-1EVP_CIPH_FLAG_LENGTH_BITS\s0" 4
|
|
.IX Item "EVP_CIPH_FLAG_LENGTH_BITS"
|
|
See \*(L"Settable \s-1EVP_CIPHER_CTX\s0 parameters\*(R" \*(L"use-bits\*(R".
|
|
.IP "\s-1EVP_CIPHER_CTX_FLAG_WRAP_ALLOW\s0" 4
|
|
.IX Item "EVP_CIPHER_CTX_FLAG_WRAP_ALLOW"
|
|
Used for Legacy purposes only. This flag needed to be set to indicate the
|
|
cipher handled wrapping.
|
|
.PP
|
|
\&\fIEVP_CIPHER_flags()\fR uses the following flags that
|
|
have mappings to \*(L"Gettable \s-1EVP_CIPHER\s0 parameters\*(R":
|
|
.IP "\s-1EVP_CIPH_FLAG_AEAD_CIPHER\s0" 4
|
|
.IX Item "EVP_CIPH_FLAG_AEAD_CIPHER"
|
|
See \*(L"Gettable \s-1EVP_CIPHER\s0 parameters\*(R" \*(L"aead\*(R".
|
|
.IP "\s-1EVP_CIPH_CUSTOM_IV\s0" 4
|
|
.IX Item "EVP_CIPH_CUSTOM_IV"
|
|
See \*(L"Gettable \s-1EVP_CIPHER\s0 parameters\*(R" \*(L"custom-iv\*(R".
|
|
.IP "\s-1EVP_CIPH_FLAG_CTS\s0" 4
|
|
.IX Item "EVP_CIPH_FLAG_CTS"
|
|
See \*(L"Gettable \s-1EVP_CIPHER\s0 parameters\*(R" \*(L"cts\*(R".
|
|
.IP "\s-1EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK\s0;" 4
|
|
.IX Item "EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK;"
|
|
See \*(L"Gettable \s-1EVP_CIPHER\s0 parameters\*(R" \*(L"tls-multi\*(R".
|
|
.IP "\s-1EVP_CIPH_RAND_KEY\s0" 4
|
|
.IX Item "EVP_CIPH_RAND_KEY"
|
|
See \*(L"Gettable \s-1EVP_CIPHER\s0 parameters\*(R" \*(L"has-randkey\*(R".
|
|
.PP
|
|
\&\fIEVP_CIPHER_flags()\fR uses the following flags for legacy purposes only:
|
|
.IP "\s-1EVP_CIPH_VARIABLE_LENGTH\s0" 4
|
|
.IX Item "EVP_CIPH_VARIABLE_LENGTH"
|
|
.PD 0
|
|
.IP "\s-1EVP_CIPH_FLAG_CUSTOM_CIPHER\s0" 4
|
|
.IX Item "EVP_CIPH_FLAG_CUSTOM_CIPHER"
|
|
.IP "\s-1EVP_CIPH_ALWAYS_CALL_INIT\s0" 4
|
|
.IX Item "EVP_CIPH_ALWAYS_CALL_INIT"
|
|
.IP "\s-1EVP_CIPH_CTRL_INIT\s0" 4
|
|
.IX Item "EVP_CIPH_CTRL_INIT"
|
|
.IP "\s-1EVP_CIPH_CUSTOM_KEY_LENGTH\s0" 4
|
|
.IX Item "EVP_CIPH_CUSTOM_KEY_LENGTH"
|
|
.IP "\s-1EVP_CIPH_CUSTOM_COPY\s0" 4
|
|
.IX Item "EVP_CIPH_CUSTOM_COPY"
|
|
.IP "\s-1EVP_CIPH_FLAG_DEFAULT_ASN1\s0" 4
|
|
.IX Item "EVP_CIPH_FLAG_DEFAULT_ASN1"
|
|
.PD
|
|
See \fIEVP_CIPHER_meth_set_flags\fR\|(3) for further information related to the above
|
|
flags.
|
|
.SH "RETURN VALUES"
|
|
.IX Header "RETURN VALUES"
|
|
\&\fIEVP_CIPHER_fetch()\fR returns a pointer to a \fB\s-1EVP_CIPHER\s0\fR for success
|
|
and \fB\s-1NULL\s0\fR for failure.
|
|
.PP
|
|
\&\fIEVP_CIPHER_up_ref()\fR returns 1 for success or 0 otherwise.
|
|
.PP
|
|
\&\fIEVP_CIPHER_CTX_new()\fR returns a pointer to a newly created
|
|
\&\fB\s-1EVP_CIPHER_CTX\s0\fR for success and \fB\s-1NULL\s0\fR for failure.
|
|
.PP
|
|
\&\fIEVP_CIPHER_CTX_dup()\fR returns a new \s-1EVP_MD_CTX\s0 if successful or \s-1NULL\s0 on failure.
|
|
.PP
|
|
\&\fIEVP_CIPHER_CTX_copy()\fR returns 1 if successful or 0 for failure.
|
|
.PP
|
|
\&\fIEVP_EncryptInit_ex2()\fR, \fIEVP_EncryptUpdate()\fR and \fIEVP_EncryptFinal_ex()\fR
|
|
return 1 for success and 0 for failure.
|
|
.PP
|
|
\&\fIEVP_DecryptInit_ex2()\fR and \fIEVP_DecryptUpdate()\fR return 1 for success and 0 for failure.
|
|
\&\fIEVP_DecryptFinal_ex()\fR returns 0 if the decrypt failed or 1 for success.
|
|
.PP
|
|
\&\fIEVP_CipherInit_ex2()\fR and \fIEVP_CipherUpdate()\fR return 1 for success and 0 for failure.
|
|
\&\fIEVP_CipherFinal_ex()\fR returns 0 for a decryption failure or 1 for success.
|
|
.PP
|
|
\&\fIEVP_Cipher()\fR returns 1 on success or 0 on failure, if the flag
|
|
\&\fB\s-1EVP_CIPH_FLAG_CUSTOM_CIPHER\s0\fR is not set for the cipher.
|
|
\&\fIEVP_Cipher()\fR returns the number of bytes written to \fIout\fR for encryption / decryption, or
|
|
the number of bytes authenticated in a call specifying \s-1AAD\s0 for an \s-1AEAD\s0 cipher, if the flag
|
|
\&\fB\s-1EVP_CIPH_FLAG_CUSTOM_CIPHER\s0\fR is set for the cipher.
|
|
.PP
|
|
\&\fIEVP_CIPHER_CTX_reset()\fR returns 1 for success and 0 for failure.
|
|
.PP
|
|
\&\fIEVP_get_cipherbyname()\fR, \fIEVP_get_cipherbynid()\fR and \fIEVP_get_cipherbyobj()\fR
|
|
return an \fB\s-1EVP_CIPHER\s0\fR structure or \s-1NULL\s0 on error.
|
|
.PP
|
|
\&\fIEVP_CIPHER_get_nid()\fR and \fIEVP_CIPHER_CTX_get_nid()\fR return a \s-1NID.\s0
|
|
.PP
|
|
\&\fIEVP_CIPHER_get_block_size()\fR and \fIEVP_CIPHER_CTX_get_block_size()\fR return the
|
|
block size.
|
|
.PP
|
|
\&\fIEVP_CIPHER_get_key_length()\fR and \fIEVP_CIPHER_CTX_get_key_length()\fR return the key
|
|
length.
|
|
.PP
|
|
\&\fIEVP_CIPHER_CTX_set_padding()\fR always returns 1.
|
|
.PP
|
|
\&\fIEVP_CIPHER_get_iv_length()\fR and \fIEVP_CIPHER_CTX_get_iv_length()\fR return the \s-1IV\s0
|
|
length, zero if the cipher does not use an \s-1IV\s0 and a negative value on error.
|
|
.PP
|
|
\&\fIEVP_CIPHER_CTX_get_tag_length()\fR return the tag length or zero if the cipher
|
|
does not use a tag.
|
|
.PP
|
|
\&\fIEVP_CIPHER_get_type()\fR and \fIEVP_CIPHER_CTX_get_type()\fR return the \s-1NID\s0 of the
|
|
cipher's \s-1OBJECT IDENTIFIER\s0 or NID_undef if it has no defined
|
|
\&\s-1OBJECT IDENTIFIER.\s0
|
|
.PP
|
|
\&\fIEVP_CIPHER_CTX_cipher()\fR returns an \fB\s-1EVP_CIPHER\s0\fR structure.
|
|
.PP
|
|
\&\fIEVP_CIPHER_CTX_get_num()\fR returns a nonnegative num value or
|
|
\&\fB\s-1EVP_CTRL_RET_UNSUPPORTED\s0\fR if the implementation does not support the call
|
|
or on any other error.
|
|
.PP
|
|
\&\fIEVP_CIPHER_CTX_set_num()\fR returns 1 on success and 0 if the implementation
|
|
does not support the call or on any other error.
|
|
.PP
|
|
\&\fIEVP_CIPHER_CTX_is_encrypting()\fR returns 1 if the \fIctx\fR is set up for encryption
|
|
0 otherwise.
|
|
.PP
|
|
\&\fIEVP_CIPHER_param_to_asn1()\fR and \fIEVP_CIPHER_asn1_to_param()\fR return greater
|
|
than zero for success and zero or a negative number on failure.
|
|
.PP
|
|
\&\fIEVP_CIPHER_CTX_rand_key()\fR returns 1 for success and zero or a negative number
|
|
for failure.
|
|
.PP
|
|
\&\fIEVP_CIPHER_names_do_all()\fR returns 1 if the callback was called for all names.
|
|
A return value of 0 means that the callback was not called for any names.
|
|
.SH "CIPHER LISTING"
|
|
.IX Header "CIPHER LISTING"
|
|
All algorithms have a fixed key length unless otherwise stated.
|
|
.PP
|
|
Refer to \*(L"\s-1SEE ALSO\*(R"\s0 for the full list of ciphers available through the \s-1EVP\s0
|
|
interface.
|
|
.IP "\fIEVP_enc_null()\fR" 4
|
|
.IX Item "EVP_enc_null()"
|
|
Null cipher: does nothing.
|
|
.SH "AEAD INTERFACE"
|
|
.IX Header "AEAD INTERFACE"
|
|
The \s-1EVP\s0 interface for Authenticated Encryption with Associated Data (\s-1AEAD\s0)
|
|
modes are subtly altered and several additional \fIctrl\fR operations are supported
|
|
depending on the mode specified.
|
|
.PP
|
|
To specify additional authenticated data (\s-1AAD\s0), a call to \fIEVP_CipherUpdate()\fR,
|
|
\&\fIEVP_EncryptUpdate()\fR or \fIEVP_DecryptUpdate()\fR should be made with the output
|
|
parameter \fIout\fR set to \fB\s-1NULL\s0\fR. In this case, on success, the parameter
|
|
\&\fIoutl\fR is set to the number of bytes authenticated.
|
|
.PP
|
|
When decrypting, the return value of \fIEVP_DecryptFinal()\fR or \fIEVP_CipherFinal()\fR
|
|
indicates whether the operation was successful. If it does not indicate success,
|
|
the authentication operation has failed and any output data \fB\s-1MUST NOT\s0\fR be used
|
|
as it is corrupted.
|
|
.SS "\s-1GCM\s0 and \s-1OCB\s0 Modes"
|
|
.IX Subsection "GCM and OCB Modes"
|
|
The following \fIctrl\fRs are supported in \s-1GCM\s0 and \s-1OCB\s0 modes.
|
|
.IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_SET_IVLEN,\s0 ivlen, \s-1NULL\s0)" 4
|
|
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)"
|
|
Sets the \s-1IV\s0 length. This call can only be made before specifying an \s-1IV.\s0 If
|
|
not called a default \s-1IV\s0 length is used.
|
|
.Sp
|
|
For \s-1GCM AES\s0 and \s-1OCB AES\s0 the default is 12 (i.e. 96 bits). For \s-1OCB\s0 mode the
|
|
maximum is 15.
|
|
.IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_GET_TAG,\s0 taglen, tag)" 4
|
|
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)"
|
|
Writes \f(CW\*(C`taglen\*(C'\fR bytes of the tag value to the buffer indicated by \f(CW\*(C`tag\*(C'\fR.
|
|
This call can only be made when encrypting data and \fBafter\fR all data has been
|
|
processed (e.g. after an \fIEVP_EncryptFinal()\fR call).
|
|
.Sp
|
|
For \s-1OCB, \s0\f(CW\*(C`taglen\*(C'\fR must either be 16 or the value previously set via
|
|
\&\fB\s-1EVP_CTRL_AEAD_SET_TAG\s0\fR.
|
|
.IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_SET_TAG,\s0 taglen, tag)" 4
|
|
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)"
|
|
When decrypting, this call sets the expected tag to \f(CW\*(C`taglen\*(C'\fR bytes from \f(CW\*(C`tag\*(C'\fR.
|
|
\&\f(CW\*(C`taglen\*(C'\fR must be between 1 and 16 inclusive.
|
|
The tag must be set prior to any call to \fIEVP_DecryptFinal()\fR or
|
|
\&\fIEVP_DecryptFinal_ex()\fR.
|
|
.Sp
|
|
For \s-1GCM,\s0 this call is only valid when decrypting data.
|
|
.Sp
|
|
For \s-1OCB,\s0 this call is valid when decrypting data to set the expected tag,
|
|
and when encrypting to set the desired tag length.
|
|
.Sp
|
|
In \s-1OCB\s0 mode, calling this when encrypting with \f(CW\*(C`tag\*(C'\fR set to \f(CW\*(C`NULL\*(C'\fR sets the
|
|
tag length. The tag length can only be set before specifying an \s-1IV.\s0 If this is
|
|
not called prior to setting the \s-1IV\s0 during encryption, then a default tag length
|
|
is used.
|
|
.Sp
|
|
For \s-1OCB AES,\s0 the default tag length is 16 (i.e. 128 bits). It is also the
|
|
maximum tag length for \s-1OCB.\s0
|
|
.SS "\s-1CCM\s0 Mode"
|
|
.IX Subsection "CCM Mode"
|
|
The \s-1EVP\s0 interface for \s-1CCM\s0 mode is similar to that of the \s-1GCM\s0 mode but with a
|
|
few additional requirements and different \fIctrl\fR values.
|
|
.PP
|
|
For \s-1CCM\s0 mode, the total plaintext or ciphertext length \fB\s-1MUST\s0\fR be passed to
|
|
\&\fIEVP_CipherUpdate()\fR, \fIEVP_EncryptUpdate()\fR or \fIEVP_DecryptUpdate()\fR with the output
|
|
and input parameters (\fIin\fR and \fIout\fR) set to \fB\s-1NULL\s0\fR and the length passed in
|
|
the \fIinl\fR parameter.
|
|
.PP
|
|
The following \fIctrl\fRs are supported in \s-1CCM\s0 mode.
|
|
.IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_SET_TAG,\s0 taglen, tag)" 4
|
|
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)"
|
|
This call is made to set the expected \fB\s-1CCM\s0\fR tag value when decrypting or
|
|
the length of the tag (with the \f(CW\*(C`tag\*(C'\fR parameter set to \s-1NULL\s0) when encrypting.
|
|
The tag length is often referred to as \fBM\fR. If not set a default value is
|
|
used (12 for \s-1AES\s0). When decrypting, the tag needs to be set before passing
|
|
in data to be decrypted, but as in \s-1GCM\s0 and \s-1OCB\s0 mode, it can be set after
|
|
passing additional authenticated data (see \*(L"\s-1AEAD INTERFACE\*(R"\s0).
|
|
.IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_CCM_SET_L,\s0 ivlen, \s-1NULL\s0)" 4
|
|
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)"
|
|
Sets the \s-1CCM \s0\fBL\fR value. If not set a default is used (8 for \s-1AES\s0).
|
|
.IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_SET_IVLEN,\s0 ivlen, \s-1NULL\s0)" 4
|
|
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)"
|
|
Sets the \s-1CCM\s0 nonce (\s-1IV\s0) length. This call can only be made before specifying a
|
|
nonce value. The nonce length is given by \fB15 \- L\fR so it is 7 by default for
|
|
\&\s-1AES.\s0
|
|
.SS "\s-1SIV\s0 Mode"
|
|
.IX Subsection "SIV Mode"
|
|
Both the AES-SIV and AES-GCM-SIV ciphers fall under this mode.
|
|
.PP
|
|
For \s-1SIV\s0 mode ciphers the behaviour of the \s-1EVP\s0 interface is subtly
|
|
altered and several additional ctrl operations are supported.
|
|
.PP
|
|
To specify any additional authenticated data (\s-1AAD\s0) and/or a Nonce, a call to
|
|
\&\fIEVP_CipherUpdate()\fR, \fIEVP_EncryptUpdate()\fR or \fIEVP_DecryptUpdate()\fR should be made
|
|
with the output parameter \fIout\fR set to \fB\s-1NULL\s0\fR.
|
|
.PP
|
|
\&\s-1RFC5297\s0 states that the Nonce is the last piece of \s-1AAD\s0 before the actual
|
|
encrypt/decrypt takes place. The \s-1API\s0 does not differentiate the Nonce from
|
|
other \s-1AAD.\s0
|
|
.PP
|
|
When decrypting the return value of \fIEVP_DecryptFinal()\fR or \fIEVP_CipherFinal()\fR
|
|
indicates if the operation was successful. If it does not indicate success
|
|
the authentication operation has failed and any output data \fB\s-1MUST NOT\s0\fR
|
|
be used as it is corrupted.
|
|
.PP
|
|
The \s-1API\s0 does not store the the \s-1SIV \s0(Synthetic Initialization Vector) in
|
|
the cipher text. Instead, it is stored as the tag within the \s-1EVP_CIPHER_CTX.\s0
|
|
The \s-1SIV\s0 must be retrieved from the context after encryption, and set into
|
|
the context before decryption.
|
|
.PP
|
|
This differs from \s-1RFC5297\s0 in that the cipher output from encryption, and
|
|
the cipher input to decryption, does not contain the \s-1SIV.\s0 This also means
|
|
that the plain text and cipher text lengths are identical.
|
|
.PP
|
|
The following ctrls are supported in \s-1SIV\s0 mode, and are used to get and set
|
|
the Synthetic Initialization Vector:
|
|
.IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_GET_TAG,\s0 taglen, tag);" 4
|
|
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);"
|
|
Writes \fItaglen\fR bytes of the tag value (the Synthetic Initialization Vector)
|
|
to the buffer indicated by \fItag\fR. This call can only be made when encrypting
|
|
data and \fBafter\fR all data has been processed (e.g. after an \fIEVP_EncryptFinal()\fR
|
|
call). For \s-1SIV\s0 mode the taglen must be 16.
|
|
.IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_SET_TAG,\s0 taglen, tag);" 4
|
|
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);"
|
|
Sets the expected tag (the Synthetic Initialization Vector) to \fItaglen\fR
|
|
bytes from \fItag\fR. This call is only legal when decrypting data and must be
|
|
made \fBbefore\fR any data is processed (e.g. before any \fIEVP_DecryptUpdate()\fR
|
|
calls). For \s-1SIV\s0 mode the taglen must be 16.
|
|
.PP
|
|
\&\s-1SIV\s0 mode makes two passes over the input data, thus, only one call to
|
|
\&\fIEVP_CipherUpdate()\fR, \fIEVP_EncryptUpdate()\fR or \fIEVP_DecryptUpdate()\fR should be made
|
|
with \fIout\fR set to a non\-\fB\s-1NULL\s0\fR value. A call to \fIEVP_DecryptFinal()\fR or
|
|
\&\fIEVP_CipherFinal()\fR is not required, but will indicate if the update
|
|
operation succeeded.
|
|
.SS "ChaCha20\-Poly1305"
|
|
.IX Subsection "ChaCha20-Poly1305"
|
|
The following \fIctrl\fRs are supported for the ChaCha20\-Poly1305 \s-1AEAD\s0 algorithm.
|
|
.IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_SET_IVLEN,\s0 ivlen, \s-1NULL\s0)" 4
|
|
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)"
|
|
Sets the nonce length. This call is now redundant since the only valid value
|
|
is the default length of 12 (i.e. 96 bits).
|
|
Prior to OpenSSL 3.0 a nonce of less than 12 bytes could be used to automatically
|
|
pad the iv with leading 0 bytes to make it 12 bytes in length.
|
|
.IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_GET_TAG,\s0 taglen, tag)" 4
|
|
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)"
|
|
Writes \f(CW\*(C`taglen\*(C'\fR bytes of the tag value to the buffer indicated by \f(CW\*(C`tag\*(C'\fR.
|
|
This call can only be made when encrypting data and \fBafter\fR all data has been
|
|
processed (e.g. after an \fIEVP_EncryptFinal()\fR call).
|
|
.Sp
|
|
\&\f(CW\*(C`taglen\*(C'\fR specified here must be 16 (\fB\s-1POLY1305_BLOCK_SIZE\s0\fR, i.e. 128\-bits) or
|
|
less.
|
|
.IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_SET_TAG,\s0 taglen, tag)" 4
|
|
.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)"
|
|
Sets the expected tag to \f(CW\*(C`taglen\*(C'\fR bytes from \f(CW\*(C`tag\*(C'\fR.
|
|
The tag length can only be set before specifying an \s-1IV.
|
|
\&\s0\f(CW\*(C`taglen\*(C'\fR must be between 1 and 16 (\fB\s-1POLY1305_BLOCK_SIZE\s0\fR) inclusive.
|
|
This call is only valid when decrypting data.
|
|
.SH "NOTES"
|
|
.IX Header "NOTES"
|
|
Where possible the \fB\s-1EVP\s0\fR interface to symmetric ciphers should be used in
|
|
preference to the low-level interfaces. This is because the code then becomes
|
|
transparent to the cipher used and much more flexible. Additionally, the
|
|
\&\fB\s-1EVP\s0\fR interface will ensure the use of platform specific cryptographic
|
|
acceleration such as AES-NI (the low-level interfaces do not provide the
|
|
guarantee).
|
|
.PP
|
|
\&\s-1PKCS\s0 padding works by adding \fBn\fR padding bytes of value \fBn\fR to make the total
|
|
length of the encrypted data a multiple of the block size. Padding is always
|
|
added so if the data is already a multiple of the block size \fBn\fR will equal
|
|
the block size. For example if the block size is 8 and 11 bytes are to be
|
|
encrypted then 5 padding bytes of value 5 will be added.
|
|
.PP
|
|
When decrypting the final block is checked to see if it has the correct form.
|
|
.PP
|
|
Although the decryption operation can produce an error if padding is enabled,
|
|
it is not a strong test that the input data or key is correct. A random block
|
|
has better than 1 in 256 chance of being of the correct format and problems with
|
|
the input data earlier on will not produce a final decrypt error.
|
|
.PP
|
|
If padding is disabled then the decryption operation will always succeed if
|
|
the total amount of data decrypted is a multiple of the block size.
|
|
.PP
|
|
The functions \fIEVP_EncryptInit()\fR, \fIEVP_EncryptInit_ex()\fR,
|
|
\&\fIEVP_EncryptFinal()\fR, \fIEVP_DecryptInit()\fR, \fIEVP_DecryptInit_ex()\fR,
|
|
\&\fIEVP_CipherInit()\fR, \fIEVP_CipherInit_ex()\fR and \fIEVP_CipherFinal()\fR are obsolete
|
|
but are retained for compatibility with existing code. New code should
|
|
use \fIEVP_EncryptInit_ex2()\fR, \fIEVP_EncryptFinal_ex()\fR, \fIEVP_DecryptInit_ex2()\fR,
|
|
\&\fIEVP_DecryptFinal_ex()\fR, \fIEVP_CipherInit_ex2()\fR and \fIEVP_CipherFinal_ex()\fR
|
|
because they can reuse an existing context without allocating and freeing
|
|
it up on each call.
|
|
.PP
|
|
There are some differences between functions \fIEVP_CipherInit()\fR and
|
|
\&\fIEVP_CipherInit_ex()\fR, significant in some circumstances. \fIEVP_CipherInit()\fR fills
|
|
the passed context object with zeros. As a consequence, \fIEVP_CipherInit()\fR does
|
|
not allow step-by-step initialization of the ctx when the \fIkey\fR and \fIiv\fR are
|
|
passed in separate calls. It also means that the flags set for the \s-1CTX\s0 are
|
|
removed, and it is especially important for the
|
|
\&\fB\s-1EVP_CIPHER_CTX_FLAG_WRAP_ALLOW\s0\fR flag treated specially in
|
|
\&\fIEVP_CipherInit_ex()\fR.
|
|
.PP
|
|
Ignoring failure returns of the \fB\s-1EVP_CIPHER_CTX\s0\fR initialization functions can
|
|
lead to subsequent undefined behavior when calling the functions that update or
|
|
finalize the context. The only valid calls on the \fB\s-1EVP_CIPHER_CTX\s0\fR when
|
|
initialization fails are calls that attempt another initialization of the
|
|
context or release the context.
|
|
.PP
|
|
\&\fIEVP_get_cipherbynid()\fR, and \fIEVP_get_cipherbyobj()\fR are implemented as macros.
|
|
.SH "BUGS"
|
|
.IX Header "BUGS"
|
|
\&\fB\s-1EVP_MAX_KEY_LENGTH\s0\fR and \fB\s-1EVP_MAX_IV_LENGTH\s0\fR only refer to the internal
|
|
ciphers with default key lengths. If custom ciphers exceed these values the
|
|
results are unpredictable. This is because it has become standard practice to
|
|
define a generic key as a fixed unsigned char array containing
|
|
\&\fB\s-1EVP_MAX_KEY_LENGTH\s0\fR bytes.
|
|
.PP
|
|
The \s-1ASN1\s0 code is incomplete (and sometimes inaccurate) it has only been tested
|
|
for certain common S/MIME ciphers (\s-1RC2, DES,\s0 triple \s-1DES\s0) in \s-1CBC\s0 mode.
|
|
.SH "EXAMPLES"
|
|
.IX Header "EXAMPLES"
|
|
Encrypt a string using \s-1IDEA:\s0
|
|
.PP
|
|
.Vb 10
|
|
\& int do_crypt(char *outfile)
|
|
\& {
|
|
\& unsigned char outbuf[1024];
|
|
\& int outlen, tmplen;
|
|
\& /*
|
|
\& * Bogus key and IV: we\*(Aqd normally set these from
|
|
\& * another source.
|
|
\& */
|
|
\& unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
|
|
\& unsigned char iv[] = {1,2,3,4,5,6,7,8};
|
|
\& char intext[] = "Some Crypto Text";
|
|
\& EVP_CIPHER_CTX *ctx;
|
|
\& FILE *out;
|
|
\&
|
|
\& ctx = EVP_CIPHER_CTX_new();
|
|
\& if (!EVP_EncryptInit_ex2(ctx, EVP_idea_cbc(), key, iv, NULL)) {
|
|
\& /* Error */
|
|
\& EVP_CIPHER_CTX_free(ctx);
|
|
\& return 0;
|
|
\& }
|
|
\&
|
|
\& if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) {
|
|
\& /* Error */
|
|
\& EVP_CIPHER_CTX_free(ctx);
|
|
\& return 0;
|
|
\& }
|
|
\& /*
|
|
\& * Buffer passed to EVP_EncryptFinal() must be after data just
|
|
\& * encrypted to avoid overwriting it.
|
|
\& */
|
|
\& if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) {
|
|
\& /* Error */
|
|
\& EVP_CIPHER_CTX_free(ctx);
|
|
\& return 0;
|
|
\& }
|
|
\& outlen += tmplen;
|
|
\& EVP_CIPHER_CTX_free(ctx);
|
|
\& /*
|
|
\& * Need binary mode for fopen because encrypted data is
|
|
\& * binary data. Also cannot use strlen() on it because
|
|
\& * it won\*(Aqt be NUL terminated and may contain embedded
|
|
\& * NULs.
|
|
\& */
|
|
\& out = fopen(outfile, "wb");
|
|
\& if (out == NULL) {
|
|
\& /* Error */
|
|
\& return 0;
|
|
\& }
|
|
\& fwrite(outbuf, 1, outlen, out);
|
|
\& fclose(out);
|
|
\& return 1;
|
|
\& }
|
|
.Ve
|
|
.PP
|
|
The ciphertext from the above example can be decrypted using the \fBopenssl\fR
|
|
utility with the command line (shown on two lines for clarity):
|
|
.PP
|
|
.Vb 2
|
|
\& openssl idea \-d \e
|
|
\& \-K 000102030405060708090A0B0C0D0E0F \-iv 0102030405060708 <filename
|
|
.Ve
|
|
.PP
|
|
General encryption and decryption function example using \s-1FILE I/O\s0 and \s-1AES128\s0
|
|
with a 128\-bit key:
|
|
.PP
|
|
.Vb 12
|
|
\& int do_crypt(FILE *in, FILE *out, int do_encrypt)
|
|
\& {
|
|
\& /* Allow enough space in output buffer for additional block */
|
|
\& unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
|
|
\& int inlen, outlen;
|
|
\& EVP_CIPHER_CTX *ctx;
|
|
\& /*
|
|
\& * Bogus key and IV: we\*(Aqd normally set these from
|
|
\& * another source.
|
|
\& */
|
|
\& unsigned char key[] = "0123456789abcdeF";
|
|
\& unsigned char iv[] = "1234567887654321";
|
|
\&
|
|
\& /* Don\*(Aqt set key or IV right away; we want to check lengths */
|
|
\& ctx = EVP_CIPHER_CTX_new();
|
|
\& if (!EVP_CipherInit_ex2(ctx, EVP_aes_128_cbc(), NULL, NULL,
|
|
\& do_encrypt, NULL)) {
|
|
\& /* Error */
|
|
\& EVP_CIPHER_CTX_free(ctx);
|
|
\& return 0;
|
|
\& }
|
|
\& OPENSSL_assert(EVP_CIPHER_CTX_get_key_length(ctx) == 16);
|
|
\& OPENSSL_assert(EVP_CIPHER_CTX_get_iv_length(ctx) == 16);
|
|
\&
|
|
\& /* Now we can set key and IV */
|
|
\& if (!EVP_CipherInit_ex2(ctx, NULL, key, iv, do_encrypt, NULL)) {
|
|
\& /* Error */
|
|
\& EVP_CIPHER_CTX_free(ctx);
|
|
\& return 0;
|
|
\& }
|
|
\&
|
|
\& for (;;) {
|
|
\& inlen = fread(inbuf, 1, 1024, in);
|
|
\& if (inlen <= 0)
|
|
\& break;
|
|
\& if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen)) {
|
|
\& /* Error */
|
|
\& EVP_CIPHER_CTX_free(ctx);
|
|
\& return 0;
|
|
\& }
|
|
\& fwrite(outbuf, 1, outlen, out);
|
|
\& }
|
|
\& if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) {
|
|
\& /* Error */
|
|
\& EVP_CIPHER_CTX_free(ctx);
|
|
\& return 0;
|
|
\& }
|
|
\& fwrite(outbuf, 1, outlen, out);
|
|
\&
|
|
\& EVP_CIPHER_CTX_free(ctx);
|
|
\& return 1;
|
|
\& }
|
|
.Ve
|
|
.PP
|
|
Encryption using AES-CBC with a 256\-bit key with \*(L"\s-1CS1\*(R"\s0 ciphertext stealing.
|
|
.PP
|
|
.Vb 10
|
|
\& int encrypt(const unsigned char *key, const unsigned char *iv,
|
|
\& const unsigned char *msg, size_t msg_len, unsigned char *out)
|
|
\& {
|
|
\& /*
|
|
\& * This assumes that key size is 32 bytes and the iv is 16 bytes.
|
|
\& * For ciphertext stealing mode the length of the ciphertext "out" will be
|
|
\& * the same size as the plaintext size "msg_len".
|
|
\& * The "msg_len" can be any size >= 16.
|
|
\& */
|
|
\& int ret = 0, encrypt = 1, outlen, len;
|
|
\& EVP_CIPHER_CTX *ctx = NULL;
|
|
\& EVP_CIPHER *cipher = NULL;
|
|
\& OSSL_PARAM params[2];
|
|
\&
|
|
\& ctx = EVP_CIPHER_CTX_new();
|
|
\& cipher = EVP_CIPHER_fetch(NULL, "AES\-256\-CBC\-CTS", NULL);
|
|
\& if (ctx == NULL || cipher == NULL)
|
|
\& goto err;
|
|
\&
|
|
\& /*
|
|
\& * The default is "CS1" so this is not really needed,
|
|
\& * but would be needed to set either "CS2" or "CS3".
|
|
\& */
|
|
\& params[0] = OSSL_PARAM_construct_utf8_string(OSSL_CIPHER_PARAM_CTS_MODE,
|
|
\& "CS1", 0);
|
|
\& params[1] = OSSL_PARAM_construct_end();
|
|
\&
|
|
\& if (!EVP_CipherInit_ex2(ctx, cipher, key, iv, encrypt, params))
|
|
\& goto err;
|
|
\&
|
|
\& /* NOTE: CTS mode does not support multiple calls to EVP_CipherUpdate() */
|
|
\& if (!EVP_CipherUpdate(ctx, out, &outlen, msg, msg_len))
|
|
\& goto err;
|
|
\& if (!EVP_CipherFinal_ex(ctx, out + outlen, &len))
|
|
\& goto err;
|
|
\& ret = 1;
|
|
\& err:
|
|
\& EVP_CIPHER_free(cipher);
|
|
\& EVP_CIPHER_CTX_free(ctx);
|
|
\& return ret;
|
|
\& }
|
|
.Ve
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\fIevp\fR\|(7),
|
|
\&\fIproperty\fR\|(7),
|
|
\&\*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fIcrypto\fR\|(7),
|
|
\&\fIprovider\-cipher\fR\|(7),
|
|
\&\fIlife_cycle\-cipher\fR\|(7)
|
|
.PP
|
|
Supported ciphers are listed in:
|
|
.PP
|
|
\&\fIEVP_aes_128_gcm\fR\|(3),
|
|
\&\fIEVP_aria_128_gcm\fR\|(3),
|
|
\&\fIEVP_bf_cbc\fR\|(3),
|
|
\&\fIEVP_camellia_128_ecb\fR\|(3),
|
|
\&\fIEVP_cast5_cbc\fR\|(3),
|
|
\&\fIEVP_chacha20\fR\|(3),
|
|
\&\fIEVP_des_cbc\fR\|(3),
|
|
\&\fIEVP_desx_cbc\fR\|(3),
|
|
\&\fIEVP_idea_cbc\fR\|(3),
|
|
\&\fIEVP_rc2_cbc\fR\|(3),
|
|
\&\fIEVP_rc4\fR\|(3),
|
|
\&\fIEVP_rc5_32_12_16_cbc\fR\|(3),
|
|
\&\fIEVP_seed_cbc\fR\|(3),
|
|
\&\fIEVP_sm4_cbc\fR\|(3),
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
Support for \s-1OCB\s0 mode was added in OpenSSL 1.1.0.
|
|
.PP
|
|
\&\fB\s-1EVP_CIPHER_CTX\s0\fR was made opaque in OpenSSL 1.1.0. As a result,
|
|
\&\fIEVP_CIPHER_CTX_reset()\fR appeared and \fIEVP_CIPHER_CTX_cleanup()\fR
|
|
disappeared. \fIEVP_CIPHER_CTX_init()\fR remains as an alias for
|
|
\&\fIEVP_CIPHER_CTX_reset()\fR.
|
|
.PP
|
|
The \fIEVP_CIPHER_CTX_cipher()\fR function was deprecated in OpenSSL 3.0; use
|
|
\&\fIEVP_CIPHER_CTX_get0_cipher()\fR instead.
|
|
.PP
|
|
The \fIEVP_EncryptInit_ex2()\fR, \fIEVP_DecryptInit_ex2()\fR, \fIEVP_CipherInit_ex2()\fR,
|
|
\&\fIEVP_CIPHER_fetch()\fR, \fIEVP_CIPHER_free()\fR, \fIEVP_CIPHER_up_ref()\fR,
|
|
\&\fIEVP_CIPHER_CTX_get0_cipher()\fR, \fIEVP_CIPHER_CTX_get1_cipher()\fR,
|
|
\&\fIEVP_CIPHER_get_params()\fR, \fIEVP_CIPHER_CTX_set_params()\fR,
|
|
\&\fIEVP_CIPHER_CTX_get_params()\fR, \fIEVP_CIPHER_gettable_params()\fR,
|
|
\&\fIEVP_CIPHER_settable_ctx_params()\fR, \fIEVP_CIPHER_gettable_ctx_params()\fR,
|
|
\&\fIEVP_CIPHER_CTX_settable_params()\fR and \fIEVP_CIPHER_CTX_gettable_params()\fR
|
|
functions were added in 3.0.
|
|
.PP
|
|
The \fIEVP_CIPHER_nid()\fR, \fIEVP_CIPHER_name()\fR, \fIEVP_CIPHER_block_size()\fR,
|
|
\&\fIEVP_CIPHER_key_length()\fR, \fIEVP_CIPHER_iv_length()\fR, \fIEVP_CIPHER_flags()\fR,
|
|
\&\fIEVP_CIPHER_mode()\fR, \fIEVP_CIPHER_type()\fR, \fIEVP_CIPHER_CTX_nid()\fR,
|
|
\&\fIEVP_CIPHER_CTX_block_size()\fR, \fIEVP_CIPHER_CTX_key_length()\fR,
|
|
\&\fIEVP_CIPHER_CTX_iv_length()\fR, \fIEVP_CIPHER_CTX_tag_length()\fR,
|
|
\&\fIEVP_CIPHER_CTX_num()\fR, \fIEVP_CIPHER_CTX_type()\fR, and \fIEVP_CIPHER_CTX_mode()\fR
|
|
functions were renamed to include \f(CW\*(C`get\*(C'\fR or \f(CW\*(C`get0\*(C'\fR in their names in
|
|
OpenSSL 3.0, respectively. The old names are kept as non-deprecated
|
|
alias macros.
|
|
.PP
|
|
The \fIEVP_CIPHER_CTX_encrypting()\fR function was renamed to
|
|
\&\fIEVP_CIPHER_CTX_is_encrypting()\fR in OpenSSL 3.0. The old name is kept as
|
|
non-deprecated alias macro.
|
|
.PP
|
|
The \fIEVP_CIPHER_CTX_flags()\fR macro was deprecated in OpenSSL 1.1.0.
|
|
.PP
|
|
\&\fIEVP_CIPHER_CTX_dup()\fR was added in OpenSSL 3.2.
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
|
|
.PP
|
|
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
|
<https://www.openssl.org/source/license.html>.
|