secure/lib/libcrypto/man/EVP_CIPHER_meth_new.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "EVP_CIPHER_METH_NEW 3"
 132 .TH EVP_CIPHER_METH_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/evp.h>
 143 \&
 144 \& EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len);
 145 \& EVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher);
 146 \& void EVP_CIPHER_meth_free(EVP_CIPHER *cipher);
 147 \&
 148 \& int EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len);
 149 \& int EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags);
 150 \& int EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size);
 151 \& int EVP_CIPHER_meth_set_init(EVP_CIPHER *cipher,
 152 \&                              int (*init)(EVP_CIPHER_CTX *ctx,
 153 \&                                          const unsigned char *key,
 154 \&                                          const unsigned char *iv,
 155 \&                                          int enc));
 156 \& int EVP_CIPHER_meth_set_do_cipher(EVP_CIPHER *cipher,
 157 \&                                   int (*do_cipher)(EVP_CIPHER_CTX *ctx,
 158 \&                                                    unsigned char *out,
 159 \&                                                    const unsigned char *in,
 160 \&                                                    size_t inl));
 161 \& int EVP_CIPHER_meth_set_cleanup(EVP_CIPHER *cipher,
 162 \&                                 int (*cleanup)(EVP_CIPHER_CTX *));
 163 \& int EVP_CIPHER_meth_set_set_asn1_params(EVP_CIPHER *cipher,
 164 \&                                         int (*set_asn1_parameters)(EVP_CIPHER_CTX *,
 165 \&                                                                    ASN1_TYPE *));
 166 \& int EVP_CIPHER_meth_set_get_asn1_params(EVP_CIPHER *cipher,
 167 \&                                         int (*get_asn1_parameters)(EVP_CIPHER_CTX *,
 168 \&                                                                    ASN1_TYPE *));
 169 \& int EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher,
 170 \&                              int (*ctrl)(EVP_CIPHER_CTX *, int type,
 171 \&                                          int arg, void *ptr));
 172 \&
 173 \& int (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,
 174 \&                                                           const unsigned char *key,
 175 \&                                                           const unsigned char *iv,
 176 \&                                                           int enc);
 177 \& int (*EVP_CIPHER_meth_get_do_cipher(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,
 178 \&                                                                unsigned char *out,
 179 \&                                                                const unsigned char *in,
 180 \&                                                                size_t inl);
 181 \& int (*EVP_CIPHER_meth_get_cleanup(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *);
 182 \& int (*EVP_CIPHER_meth_get_set_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
 183 \&                                                                      ASN1_TYPE *);
 184 \& int (*EVP_CIPHER_meth_get_get_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
 185 \&                                                                      ASN1_TYPE *);
 186 \& int (*EVP_CIPHER_meth_get_ctrl(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
 187 \&                                                           int type, int arg,
 188 \&                                                           void *ptr);
 189 .Ve
 190 .SH "DESCRIPTION"
 191 .IX Header "DESCRIPTION"
 192 The \fB\s-1EVP_CIPHER\s0\fR type is a structure for symmetric cipher method
 193 implementation.
 194 .PP
 195 \&\fIEVP_CIPHER_meth_new()\fR creates a new \fB\s-1EVP_CIPHER\s0\fR structure.
 196 .PP
 197 \&\fIEVP_CIPHER_meth_dup()\fR creates a copy of \fBcipher\fR.
 198 .PP
 199 \&\fIEVP_CIPHER_meth_free()\fR destroys a \fB\s-1EVP_CIPHER\s0\fR structure.
 200 .PP
 201 \&\fIEVP_CIPHER_meth_set_iv_length()\fR sets the length of the \s-1IV.\s0
 202 This is only needed when the implemented cipher mode requires it.
 203 .PP
 204 \&\fIEVP_CIPHER_meth_set_flags()\fR sets the flags to describe optional
 205 behaviours in the particular \fBcipher\fR.
 206 With the exception of cipher modes, of which only one may be present,
 207 several flags can be or'd together.
 208 The available flags are:
 209 .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
 210 .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"
 211 The cipher mode.
 212 .IP "\s-1EVP_CIPH_VARIABLE_LENGTH\s0" 4
 213 .IX Item "EVP_CIPH_VARIABLE_LENGTH"
 214 This cipher is of variable length.
 215 .IP "\s-1EVP_CIPH_CUSTOM_IV\s0" 4
 216 .IX Item "EVP_CIPH_CUSTOM_IV"
 217 Storing and initialising the \s-1IV\s0 is left entirely to the
 218 implementation.
 219 .IP "\s-1EVP_CIPH_ALWAYS_CALL_INIT\s0" 4
 220 .IX Item "EVP_CIPH_ALWAYS_CALL_INIT"
 221 Set this if the implementation's \fIinit()\fR function should be called even
 222 if \fBkey\fR is \fB\s-1NULL\s0\fR.
 223 .IP "\s-1EVP_CIPH_CTRL_INIT\s0" 4
 224 .IX Item "EVP_CIPH_CTRL_INIT"
 225 Set this to have the implementation's \fIctrl()\fR function called with
 226 command code \fB\s-1EVP_CTRL_INIT\s0\fR early in its setup.
 227 .IP "\s-1EVP_CIPH_CUSTOM_KEY_LENGTH\s0" 4
 228 .IX Item "EVP_CIPH_CUSTOM_KEY_LENGTH"
 229 Checking and setting the key length after creating the \fB\s-1EVP_CIPHER\s0\fR
 230 is left to the implementation.
 231 Whenever someone uses \fIEVP_CIPHER_CTX_set_key_length()\fR on a
 232 \&\fB\s-1EVP_CIPHER\s0\fR with this flag set, the implementation's \fIctrl()\fR function
 233 will be called with the control code \fB\s-1EVP_CTRL_SET_KEY_LENGTH\s0\fR and
 234 the key length in \fBarg\fR.
 235 .IP "\s-1EVP_CIPH_NO_PADDING\s0" 4
 236 .IX Item "EVP_CIPH_NO_PADDING"
 237 Don't use standard block padding.
 238 .IP "\s-1EVP_CIPH_RAND_KEY\s0" 4
 239 .IX Item "EVP_CIPH_RAND_KEY"
 240 Making a key with random content is left to the implementation.
 241 This is done by calling the implementation's \fIctrl()\fR function with the
 242 control code \fB\s-1EVP_CTRL_RAND_KEY\s0\fR and the pointer to the key memory
 243 storage in \fBptr\fR.
 244 .IP "\s-1EVP_CIPH_CUSTOM_COPY\s0" 4
 245 .IX Item "EVP_CIPH_CUSTOM_COPY"
 246 Set this to have the implementation's \fIctrl()\fR function called with
 247 command code \fB\s-1EVP_CTRL_COPY\s0\fR at the end of \fIEVP_CIPHER_CTX_copy()\fR.
 248 The intended use is for further things to deal with after the
 249 implementation specific data block has been copied.
 250 The destination \fB\s-1EVP_CIPHER_CTX\s0\fR is passed to the control with the
 251 \&\fBptr\fR parameter.
 252 The implementation specific data block is reached with
 253 \&\fIEVP_CIPHER_CTX_get_cipher_data()\fR.
 254 .IP "\s-1EVP_CIPH_FLAG_DEFAULT_ASN1\s0" 4
 255 .IX Item "EVP_CIPH_FLAG_DEFAULT_ASN1"
 256 Use the default \s-1EVP\s0 routines to pass \s-1IV\s0 to and from \s-1ASN.1.\s0
 257 .IP "\s-1EVP_CIPH_FLAG_LENGTH_BITS\s0" 4
 258 .IX Item "EVP_CIPH_FLAG_LENGTH_BITS"
 259 Signals that the length of the input buffer for encryption /
 260 decryption is to be understood as the number of bits instead of
 261 bytes for this implementation.
 262 This is only useful for \s-1CFB1\s0 ciphers.
 263 .IP "\s-1EVP_CIPH_FLAG_CUSTOM_CIPHER\s0" 4
 264 .IX Item "EVP_CIPH_FLAG_CUSTOM_CIPHER"
 265 This indicates that the implementation takes care of everything,
 266 including padding, buffering and finalization.
 267 The \s-1EVP\s0 routines will simply give them control and do nothing more.
 268 .IP "\s-1EVP_CIPH_FLAG_AEAD_CIPHER\s0" 4
 269 .IX Item "EVP_CIPH_FLAG_AEAD_CIPHER"
 270 This indicates that this is an \s-1AEAD\s0 cipher implementation.
 271 .IP "\s-1EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK\s0" 4
 272 .IX Item "EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK"
 273 Allow interleaving of crypto blocks, a particular optimization only applicable
 274 to certain \s-1TLS\s0 ciphers.
 275 .PP
 276 \&\fIEVP_CIPHER_meth_set_impl_ctx_size()\fR sets the size of the \s-1EVP_CIPHER\s0's
 277 implementation context so that it can be automatically allocated.
 278 .PP
 279 \&\fIEVP_CIPHER_meth_set_init()\fR sets the cipher init function for
 280 \&\fBcipher\fR.
 281 The cipher init function is called by \fIEVP_CipherInit()\fR,
 282 \&\fIEVP_CipherInit_ex()\fR, \fIEVP_EncryptInit()\fR, \fIEVP_EncryptInit_ex()\fR,
 283 \&\fIEVP_DecryptInit()\fR, \fIEVP_DecryptInit_ex()\fR.
 284 .PP
 285 \&\fIEVP_CIPHER_meth_set_do_cipher()\fR sets the cipher function for
 286 \&\fBcipher\fR.
 287 The cipher function is called by \fIEVP_CipherUpdate()\fR,
 288 \&\fIEVP_EncryptUpdate()\fR, \fIEVP_DecryptUpdate()\fR, \fIEVP_CipherFinal()\fR,
 289 \&\fIEVP_EncryptFinal()\fR, \fIEVP_EncryptFinal_ex()\fR, \fIEVP_DecryptFinal()\fR and
 290 \&\fIEVP_DecryptFinal_ex()\fR.
 291 .PP
 292 \&\fIEVP_CIPHER_meth_set_cleanup()\fR sets the function for \fBcipher\fR to do
 293 extra cleanup before the method's private data structure is cleaned
 294 out and freed.
 295 Note that the cleanup function is passed a \fB\s-1EVP_CIPHER_CTX\s0 *\fR, the
 296 private data structure is then available with
 297 \&\fIEVP_CIPHER_CTX_get_cipher_data()\fR.
 298 This cleanup function is called by \fIEVP_CIPHER_CTX_reset()\fR and
 299 \&\fIEVP_CIPHER_CTX_free()\fR.
 300 .PP
 301 \&\fIEVP_CIPHER_meth_set_set_asn1_params()\fR sets the function for \fBcipher\fR
 302 to set the AlgorithmIdentifier \*(L"parameter\*(R" based on the passed cipher.
 303 This function is called by \fIEVP_CIPHER_param_to_asn1()\fR.
 304 \&\fIEVP_CIPHER_meth_set_get_asn1_params()\fR sets the function for \fBcipher\fR
 305 that sets the cipher parameters based on an \s-1ASN.1\s0 AlgorithmIdentifier
 306 \&\*(L"parameter\*(R".
 307 Both these functions are needed when there is a need for custom data
 308 (more or other than the cipher \s-1IV\s0).
 309 They are called by \fIEVP_CIPHER_param_to_asn1()\fR and
 310 \&\fIEVP_CIPHER_asn1_to_param()\fR respectively if defined.
 311 .PP
 312 \&\fIEVP_CIPHER_meth_set_ctrl()\fR sets the control function for \fBcipher\fR.
 313 .PP
 314 \&\fIEVP_CIPHER_meth_get_init()\fR, \fIEVP_CIPHER_meth_get_do_cipher()\fR,
 315 \&\fIEVP_CIPHER_meth_get_cleanup()\fR, \fIEVP_CIPHER_meth_get_set_asn1_params()\fR,
 316 \&\fIEVP_CIPHER_meth_get_get_asn1_params()\fR and \fIEVP_CIPHER_meth_get_ctrl()\fR
 317 are all used to retrieve the method data given with the
 318 EVP_CIPHER_meth_set_*() functions above.
 319 .SH "RETURN VALUES"
 320 .IX Header "RETURN VALUES"
 321 \&\fIEVP_CIPHER_meth_new()\fR and \fIEVP_CIPHER_meth_dup()\fR return a pointer to a
 322 newly created \fB\s-1EVP_CIPHER\s0\fR, or \s-1NULL\s0 on failure.
 323 All EVP_CIPHER_meth_set_*() functions return 1.
 324 All EVP_CIPHER_meth_get_*() functions return pointers to their
 325 respective \fBcipher\fR function.
 326 .SH "SEE ALSO"
 327 .IX Header "SEE ALSO"
 328 EVP_EncryptInit
 329 .SH "HISTORY"
 330 .IX Header "HISTORY"
 331 The functions described here were added in OpenSSL 1.1.0.
 332 .SH "COPYRIGHT"
 333 .IX Header "COPYRIGHT"
 334 Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
 335 .PP
 336 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 337 this file except in compliance with the License.  You can obtain a copy
 338 in the file \s-1LICENSE\s0 in the source distribution or at
 339 <https://www.openssl.org/source/license.html>.