secure/lib/libcrypto/man/man3/EVP_CIPHER_meth_new.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "EVP_CIPHER_METH_NEW 3"
 136 .TH EVP_CIPHER_METH_NEW 3 "2022-05-03" "1.1.1o" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 EVP_CIPHER_meth_new, EVP_CIPHER_meth_dup, EVP_CIPHER_meth_free, EVP_CIPHER_meth_set_iv_length, EVP_CIPHER_meth_set_flags, EVP_CIPHER_meth_set_impl_ctx_size, EVP_CIPHER_meth_set_init, EVP_CIPHER_meth_set_do_cipher, EVP_CIPHER_meth_set_cleanup, EVP_CIPHER_meth_set_set_asn1_params, EVP_CIPHER_meth_set_get_asn1_params, EVP_CIPHER_meth_set_ctrl, EVP_CIPHER_meth_get_init, EVP_CIPHER_meth_get_do_cipher, EVP_CIPHER_meth_get_cleanup, EVP_CIPHER_meth_get_set_asn1_params, EVP_CIPHER_meth_get_get_asn1_params, EVP_CIPHER_meth_get_ctrl \- Routines to build up EVP_CIPHER methods
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/evp.h>
 147 \&
 148 \& EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len);
 149 \& EVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher);
 150 \& void EVP_CIPHER_meth_free(EVP_CIPHER *cipher);
 151 \&
 152 \& int EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len);
 153 \& int EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags);
 154 \& int EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size);
 155 \& int EVP_CIPHER_meth_set_init(EVP_CIPHER *cipher,
 156 \&                              int (*init)(EVP_CIPHER_CTX *ctx,
 157 \&                                          const unsigned char *key,
 158 \&                                          const unsigned char *iv,
 159 \&                                          int enc));
 160 \& int EVP_CIPHER_meth_set_do_cipher(EVP_CIPHER *cipher,
 161 \&                                   int (*do_cipher)(EVP_CIPHER_CTX *ctx,
 162 \&                                                    unsigned char *out,
 163 \&                                                    const unsigned char *in,
 164 \&                                                    size_t inl));
 165 \& int EVP_CIPHER_meth_set_cleanup(EVP_CIPHER *cipher,
 166 \&                                 int (*cleanup)(EVP_CIPHER_CTX *));
 167 \& int EVP_CIPHER_meth_set_set_asn1_params(EVP_CIPHER *cipher,
 168 \&                                         int (*set_asn1_parameters)(EVP_CIPHER_CTX *,
 169 \&                                                                    ASN1_TYPE *));
 170 \& int EVP_CIPHER_meth_set_get_asn1_params(EVP_CIPHER *cipher,
 171 \&                                         int (*get_asn1_parameters)(EVP_CIPHER_CTX *,
 172 \&                                                                    ASN1_TYPE *));
 173 \& int EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher,
 174 \&                              int (*ctrl)(EVP_CIPHER_CTX *, int type,
 175 \&                                          int arg, void *ptr));
 176 \&
 177 \& int (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,
 178 \&                                                           const unsigned char *key,
 179 \&                                                           const unsigned char *iv,
 180 \&                                                           int enc);
 181 \& int (*EVP_CIPHER_meth_get_do_cipher(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,
 182 \&                                                                unsigned char *out,
 183 \&                                                                const unsigned char *in,
 184 \&                                                                size_t inl);
 185 \& int (*EVP_CIPHER_meth_get_cleanup(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *);
 186 \& int (*EVP_CIPHER_meth_get_set_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
 187 \&                                                                      ASN1_TYPE *);
 188 \& int (*EVP_CIPHER_meth_get_get_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
 189 \&                                                                      ASN1_TYPE *);
 190 \& int (*EVP_CIPHER_meth_get_ctrl(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
 191 \&                                                           int type, int arg,
 192 \&                                                           void *ptr);
 193 .Ve
 194 .SH "DESCRIPTION"
 195 .IX Header "DESCRIPTION"
 196 The \fB\s-1EVP_CIPHER\s0\fR type is a structure for symmetric cipher method
 197 implementation.
 198 .PP
 199 \&\fBEVP_CIPHER_meth_new()\fR creates a new \fB\s-1EVP_CIPHER\s0\fR structure.
 200 .PP
 201 \&\fBEVP_CIPHER_meth_dup()\fR creates a copy of \fBcipher\fR.
 202 .PP
 203 \&\fBEVP_CIPHER_meth_free()\fR destroys a \fB\s-1EVP_CIPHER\s0\fR structure.
 204 .PP
 205 \&\fBEVP_CIPHER_meth_set_iv_length()\fR sets the length of the \s-1IV.\s0
 206 This is only needed when the implemented cipher mode requires it.
 207 .PP
 208 \&\fBEVP_CIPHER_meth_set_flags()\fR sets the flags to describe optional
 209 behaviours in the particular \fBcipher\fR.
 210 With the exception of cipher modes, of which only one may be present,
 211 several flags can be or'd together.
 212 The available flags are:
 213 .IP "\s-1EVP_CIPH_STREAM_CIPHER, EVP_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" 4
 214 .IX Item "EVP_CIPH_STREAM_CIPHER, EVP_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"
 215 The cipher mode.
 216 .IP "\s-1EVP_CIPH_VARIABLE_LENGTH\s0" 4
 217 .IX Item "EVP_CIPH_VARIABLE_LENGTH"
 218 This cipher is of variable length.
 219 .IP "\s-1EVP_CIPH_CUSTOM_IV\s0" 4
 220 .IX Item "EVP_CIPH_CUSTOM_IV"
 221 Storing and initialising the \s-1IV\s0 is left entirely to the
 222 implementation.
 223 .IP "\s-1EVP_CIPH_ALWAYS_CALL_INIT\s0" 4
 224 .IX Item "EVP_CIPH_ALWAYS_CALL_INIT"
 225 Set this if the implementation's \fBinit()\fR function should be called even
 226 if \fBkey\fR is \fB\s-1NULL\s0\fR.
 227 .IP "\s-1EVP_CIPH_CTRL_INIT\s0" 4
 228 .IX Item "EVP_CIPH_CTRL_INIT"
 229 Set this to have the implementation's \fBctrl()\fR function called with
 230 command code \fB\s-1EVP_CTRL_INIT\s0\fR early in its setup.
 231 .IP "\s-1EVP_CIPH_CUSTOM_KEY_LENGTH\s0" 4
 232 .IX Item "EVP_CIPH_CUSTOM_KEY_LENGTH"
 233 Checking and setting the key length after creating the \fB\s-1EVP_CIPHER\s0\fR
 234 is left to the implementation.
 235 Whenever someone uses \fBEVP_CIPHER_CTX_set_key_length()\fR on a
 236 \&\fB\s-1EVP_CIPHER\s0\fR with this flag set, the implementation's \fBctrl()\fR function
 237 will be called with the control code \fB\s-1EVP_CTRL_SET_KEY_LENGTH\s0\fR and
 238 the key length in \fBarg\fR.
 239 .IP "\s-1EVP_CIPH_NO_PADDING\s0" 4
 240 .IX Item "EVP_CIPH_NO_PADDING"
 241 Don't use standard block padding.
 242 .IP "\s-1EVP_CIPH_RAND_KEY\s0" 4
 243 .IX Item "EVP_CIPH_RAND_KEY"
 244 Making a key with random content is left to the implementation.
 245 This is done by calling the implementation's \fBctrl()\fR function with the
 246 control code \fB\s-1EVP_CTRL_RAND_KEY\s0\fR and the pointer to the key memory
 247 storage in \fBptr\fR.
 248 .IP "\s-1EVP_CIPH_CUSTOM_COPY\s0" 4
 249 .IX Item "EVP_CIPH_CUSTOM_COPY"
 250 Set this to have the implementation's \fBctrl()\fR function called with
 251 command code \fB\s-1EVP_CTRL_COPY\s0\fR at the end of \fBEVP_CIPHER_CTX_copy()\fR.
 252 The intended use is for further things to deal with after the
 253 implementation specific data block has been copied.
 254 The destination \fB\s-1EVP_CIPHER_CTX\s0\fR is passed to the control with the
 255 \&\fBptr\fR parameter.
 256 The implementation specific data block is reached with
 257 \&\fBEVP_CIPHER_CTX_get_cipher_data()\fR.
 258 .IP "\s-1EVP_CIPH_FLAG_DEFAULT_ASN1\s0" 4
 259 .IX Item "EVP_CIPH_FLAG_DEFAULT_ASN1"
 260 Use the default \s-1EVP\s0 routines to pass \s-1IV\s0 to and from \s-1ASN.1.\s0
 261 .IP "\s-1EVP_CIPH_FLAG_LENGTH_BITS\s0" 4
 262 .IX Item "EVP_CIPH_FLAG_LENGTH_BITS"
 263 Signals that the length of the input buffer for encryption /
 264 decryption is to be understood as the number of bits instead of
 265 bytes for this implementation.
 266 This is only useful for \s-1CFB1\s0 ciphers.
 267 .IP "\s-1EVP_CIPH_FLAG_CUSTOM_CIPHER\s0" 4
 268 .IX Item "EVP_CIPH_FLAG_CUSTOM_CIPHER"
 269 This indicates that the implementation takes care of everything,
 270 including padding, buffering and finalization.
 271 The \s-1EVP\s0 routines will simply give them control and do nothing more.
 272 .IP "\s-1EVP_CIPH_FLAG_AEAD_CIPHER\s0" 4
 273 .IX Item "EVP_CIPH_FLAG_AEAD_CIPHER"
 274 This indicates that this is an \s-1AEAD\s0 cipher implementation.
 275 .IP "\s-1EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK\s0" 4
 276 .IX Item "EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK"
 277 Allow interleaving of crypto blocks, a particular optimization only applicable
 278 to certain \s-1TLS\s0 ciphers.
 279 .PP
 280 \&\fBEVP_CIPHER_meth_set_impl_ctx_size()\fR sets the size of the \s-1EVP_CIPHER\s0's
 281 implementation context so that it can be automatically allocated.
 282 .PP
 283 \&\fBEVP_CIPHER_meth_set_init()\fR sets the cipher init function for
 284 \&\fBcipher\fR.
 285 The cipher init function is called by \fBEVP_CipherInit()\fR,
 286 \&\fBEVP_CipherInit_ex()\fR, \fBEVP_EncryptInit()\fR, \fBEVP_EncryptInit_ex()\fR,
 287 \&\fBEVP_DecryptInit()\fR, \fBEVP_DecryptInit_ex()\fR.
 288 .PP
 289 \&\fBEVP_CIPHER_meth_set_do_cipher()\fR sets the cipher function for
 290 \&\fBcipher\fR.
 291 The cipher function is called by \fBEVP_CipherUpdate()\fR,
 292 \&\fBEVP_EncryptUpdate()\fR, \fBEVP_DecryptUpdate()\fR, \fBEVP_CipherFinal()\fR,
 293 \&\fBEVP_EncryptFinal()\fR, \fBEVP_EncryptFinal_ex()\fR, \fBEVP_DecryptFinal()\fR and
 294 \&\fBEVP_DecryptFinal_ex()\fR.
 295 .PP
 296 \&\fBEVP_CIPHER_meth_set_cleanup()\fR sets the function for \fBcipher\fR to do
 297 extra cleanup before the method's private data structure is cleaned
 298 out and freed.
 299 Note that the cleanup function is passed a \fB\s-1EVP_CIPHER_CTX\s0 *\fR, the
 300 private data structure is then available with
 301 \&\fBEVP_CIPHER_CTX_get_cipher_data()\fR.
 302 This cleanup function is called by \fBEVP_CIPHER_CTX_reset()\fR and
 303 \&\fBEVP_CIPHER_CTX_free()\fR.
 304 .PP
 305 \&\fBEVP_CIPHER_meth_set_set_asn1_params()\fR sets the function for \fBcipher\fR
 306 to set the AlgorithmIdentifier \*(L"parameter\*(R" based on the passed cipher.
 307 This function is called by \fBEVP_CIPHER_param_to_asn1()\fR.
 308 \&\fBEVP_CIPHER_meth_set_get_asn1_params()\fR sets the function for \fBcipher\fR
 309 that sets the cipher parameters based on an \s-1ASN.1\s0 AlgorithmIdentifier
 310 \&\*(L"parameter\*(R".
 311 Both these functions are needed when there is a need for custom data
 312 (more or other than the cipher \s-1IV\s0).
 313 They are called by \fBEVP_CIPHER_param_to_asn1()\fR and
 314 \&\fBEVP_CIPHER_asn1_to_param()\fR respectively if defined.
 315 .PP
 316 \&\fBEVP_CIPHER_meth_set_ctrl()\fR sets the control function for \fBcipher\fR.
 317 .PP
 318 \&\fBEVP_CIPHER_meth_get_init()\fR, \fBEVP_CIPHER_meth_get_do_cipher()\fR,
 319 \&\fBEVP_CIPHER_meth_get_cleanup()\fR, \fBEVP_CIPHER_meth_get_set_asn1_params()\fR,
 320 \&\fBEVP_CIPHER_meth_get_get_asn1_params()\fR and \fBEVP_CIPHER_meth_get_ctrl()\fR
 321 are all used to retrieve the method data given with the
 322 EVP_CIPHER_meth_set_*() functions above.
 323 .SH "RETURN VALUES"
 324 .IX Header "RETURN VALUES"
 325 \&\fBEVP_CIPHER_meth_new()\fR and \fBEVP_CIPHER_meth_dup()\fR return a pointer to a
 326 newly created \fB\s-1EVP_CIPHER\s0\fR, or \s-1NULL\s0 on failure.
 327 All EVP_CIPHER_meth_set_*() functions return 1.
 328 All EVP_CIPHER_meth_get_*() functions return pointers to their
 329 respective \fBcipher\fR function.
 330 .SH "SEE ALSO"
 331 .IX Header "SEE ALSO"
 332 EVP_EncryptInit
 333 .SH "HISTORY"
 334 .IX Header "HISTORY"
 335 The functions described here were added in OpenSSL 1.1.0.
 336 .SH "COPYRIGHT"
 337 .IX Header "COPYRIGHT"
 338 Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
 339 .PP
 340 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 341 this file except in compliance with the License.  You can obtain a copy
 342 in the file \s-1LICENSE\s0 in the source distribution or at
 343 <https://www.openssl.org/source/license.html>.