1=pod 2 3=head1 NAME 4 5EVP_CIPHER_meth_new, EVP_CIPHER_meth_dup, EVP_CIPHER_meth_free, 6EVP_CIPHER_meth_set_iv_length, EVP_CIPHER_meth_set_flags, 7EVP_CIPHER_meth_set_impl_ctx_size, EVP_CIPHER_meth_set_init, 8EVP_CIPHER_meth_set_do_cipher, EVP_CIPHER_meth_set_cleanup, 9EVP_CIPHER_meth_set_set_asn1_params, EVP_CIPHER_meth_set_get_asn1_params, 10EVP_CIPHER_meth_set_ctrl, EVP_CIPHER_meth_get_init, 11EVP_CIPHER_meth_get_do_cipher, EVP_CIPHER_meth_get_cleanup, 12EVP_CIPHER_meth_get_set_asn1_params, EVP_CIPHER_meth_get_get_asn1_params, 13EVP_CIPHER_meth_get_ctrl 14- Routines to build up EVP_CIPHER methods 15 16=head1 SYNOPSIS 17 18 #include <openssl/evp.h> 19 20The following functions have been deprecated since OpenSSL 3.0, and can be 21hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 22see L<openssl_user_macros(7)>: 23 24 EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len); 25 EVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher); 26 void EVP_CIPHER_meth_free(EVP_CIPHER *cipher); 27 28 int EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len); 29 int EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags); 30 int EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size); 31 int EVP_CIPHER_meth_set_init(EVP_CIPHER *cipher, 32 int (*init)(EVP_CIPHER_CTX *ctx, 33 const unsigned char *key, 34 const unsigned char *iv, 35 int enc)); 36 int EVP_CIPHER_meth_set_do_cipher(EVP_CIPHER *cipher, 37 int (*do_cipher)(EVP_CIPHER_CTX *ctx, 38 unsigned char *out, 39 const unsigned char *in, 40 size_t inl)); 41 int EVP_CIPHER_meth_set_cleanup(EVP_CIPHER *cipher, 42 int (*cleanup)(EVP_CIPHER_CTX *)); 43 int EVP_CIPHER_meth_set_set_asn1_params(EVP_CIPHER *cipher, 44 int (*set_asn1_parameters)(EVP_CIPHER_CTX *, 45 ASN1_TYPE *)); 46 int EVP_CIPHER_meth_set_get_asn1_params(EVP_CIPHER *cipher, 47 int (*get_asn1_parameters)(EVP_CIPHER_CTX *, 48 ASN1_TYPE *)); 49 int EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher, 50 int (*ctrl)(EVP_CIPHER_CTX *, int type, 51 int arg, void *ptr)); 52 53 int (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx, 54 const unsigned char *key, 55 const unsigned char *iv, 56 int enc); 57 int (*EVP_CIPHER_meth_get_do_cipher(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx, 58 unsigned char *out, 59 const unsigned char *in, 60 size_t inl); 61 int (*EVP_CIPHER_meth_get_cleanup(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *); 62 int (*EVP_CIPHER_meth_get_set_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, 63 ASN1_TYPE *); 64 int (*EVP_CIPHER_meth_get_get_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, 65 ASN1_TYPE *); 66 int (*EVP_CIPHER_meth_get_ctrl(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, 67 int type, int arg, 68 void *ptr); 69 70=head1 DESCRIPTION 71 72All of the functions described on this page are deprecated. 73Applications should instead use the OSSL_PROVIDER APIs. 74 75The B<EVP_CIPHER> type is a structure for symmetric cipher method 76implementation. 77 78EVP_CIPHER_meth_new() creates a new B<EVP_CIPHER> structure. 79 80EVP_CIPHER_meth_dup() creates a copy of B<cipher>. 81 82EVP_CIPHER_meth_free() destroys a B<EVP_CIPHER> structure. 83 84EVP_CIPHER_meth_set_iv_length() sets the length of the IV. 85This is only needed when the implemented cipher mode requires it. 86 87EVP_CIPHER_meth_set_flags() sets the flags to describe optional 88behaviours in the particular B<cipher>. 89With the exception of cipher modes, of which only one may be present, 90several flags can be or'd together. 91The available flags are: 92 93=over 4 94 95=item EVP_CIPH_STREAM_CIPHER, EVP_CIPH_ECB_MODE EVP_CIPH_CBC_MODE, 96EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, 97EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, EVP_CIPH_WRAP_MODE, 98EVP_CIPH_OCB_MODE, EVP_CIPH_SIV_MODE 99 100The cipher mode. 101 102=item EVP_CIPH_VARIABLE_LENGTH 103 104This cipher is of variable length. 105 106=item EVP_CIPH_CUSTOM_IV 107 108Storing and initialising the IV is left entirely to the 109implementation. 110 111=item EVP_CIPH_ALWAYS_CALL_INIT 112 113Set this if the implementation's init() function should be called even 114if B<key> is B<NULL>. 115 116=item EVP_CIPH_CTRL_INIT 117 118Set this to have the implementation's ctrl() function called with 119command code B<EVP_CTRL_INIT> early in its setup. 120 121=item EVP_CIPH_CUSTOM_KEY_LENGTH 122 123Checking and setting the key length after creating the B<EVP_CIPHER> 124is left to the implementation. 125Whenever someone uses EVP_CIPHER_CTX_set_key_length() on a 126B<EVP_CIPHER> with this flag set, the implementation's ctrl() function 127will be called with the control code B<EVP_CTRL_SET_KEY_LENGTH> and 128the key length in B<arg>. 129 130=item EVP_CIPH_NO_PADDING 131 132Don't use standard block padding. 133 134=item EVP_CIPH_RAND_KEY 135 136Making a key with random content is left to the implementation. 137This is done by calling the implementation's ctrl() function with the 138control code B<EVP_CTRL_RAND_KEY> and the pointer to the key memory 139storage in B<ptr>. 140 141=item EVP_CIPH_CUSTOM_COPY 142 143Set this to have the implementation's ctrl() function called with 144command code B<EVP_CTRL_COPY> at the end of EVP_CIPHER_CTX_copy(). 145The intended use is for further things to deal with after the 146implementation specific data block has been copied. 147The destination B<EVP_CIPHER_CTX> is passed to the control with the 148B<ptr> parameter. 149The implementation specific data block is reached with 150EVP_CIPHER_CTX_get_cipher_data(). 151 152=item EVP_CIPH_FLAG_DEFAULT_ASN1 153 154Use the default EVP routines to pass IV to and from ASN.1. 155 156=item EVP_CIPH_FLAG_LENGTH_BITS 157 158Signals that the length of the input buffer for encryption / 159decryption is to be understood as the number of bits instead of 160bytes for this implementation. 161This is only useful for CFB1 ciphers. 162 163=item EVP_CIPH_FLAG_CTS 164 165Indicates that the cipher uses ciphertext stealing. This is currently 166used to indicate that the cipher is a one shot that only allows a single call to 167EVP_CipherUpdate(). 168 169=item EVP_CIPH_FLAG_CUSTOM_CIPHER 170 171This indicates that the implementation takes care of everything, 172including padding, buffering and finalization. 173The EVP routines will simply give them control and do nothing more. 174 175=item EVP_CIPH_FLAG_AEAD_CIPHER 176 177This indicates that this is an AEAD cipher implementation. 178 179=item EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK 180 181Allow interleaving of crypto blocks, a particular optimization only applicable 182to certain TLS ciphers. 183 184=back 185 186EVP_CIPHER_meth_set_impl_ctx_size() sets the size of the EVP_CIPHER's 187implementation context so that it can be automatically allocated. 188 189EVP_CIPHER_meth_set_init() sets the cipher init function for 190B<cipher>. 191The cipher init function is called by EVP_CipherInit(), 192EVP_CipherInit_ex(), EVP_EncryptInit(), EVP_EncryptInit_ex(), 193EVP_DecryptInit(), EVP_DecryptInit_ex(). 194 195EVP_CIPHER_meth_set_do_cipher() sets the cipher function for 196B<cipher>. 197The cipher function is called by EVP_CipherUpdate(), 198EVP_EncryptUpdate(), EVP_DecryptUpdate(), EVP_CipherFinal(), 199EVP_EncryptFinal(), EVP_EncryptFinal_ex(), EVP_DecryptFinal() and 200EVP_DecryptFinal_ex(). 201 202EVP_CIPHER_meth_set_cleanup() sets the function for B<cipher> to do 203extra cleanup before the method's private data structure is cleaned 204out and freed. 205Note that the cleanup function is passed a B<EVP_CIPHER_CTX *>, the 206private data structure is then available with 207EVP_CIPHER_CTX_get_cipher_data(). 208This cleanup function is called by EVP_CIPHER_CTX_reset() and 209EVP_CIPHER_CTX_free(). 210 211EVP_CIPHER_meth_set_set_asn1_params() sets the function for B<cipher> 212to set the AlgorithmIdentifier "parameter" based on the passed cipher. 213This function is called by EVP_CIPHER_param_to_asn1(). 214EVP_CIPHER_meth_set_get_asn1_params() sets the function for B<cipher> 215that sets the cipher parameters based on an ASN.1 AlgorithmIdentifier 216"parameter". 217Both these functions are needed when there is a need for custom data 218(more or other than the cipher IV). 219They are called by EVP_CIPHER_param_to_asn1() and 220EVP_CIPHER_asn1_to_param() respectively if defined. 221 222EVP_CIPHER_meth_set_ctrl() sets the control function for B<cipher>. 223 224EVP_CIPHER_meth_get_init(), EVP_CIPHER_meth_get_do_cipher(), 225EVP_CIPHER_meth_get_cleanup(), EVP_CIPHER_meth_get_set_asn1_params(), 226EVP_CIPHER_meth_get_get_asn1_params() and EVP_CIPHER_meth_get_ctrl() 227are all used to retrieve the method data given with the 228EVP_CIPHER_meth_set_*() functions above. 229 230=head1 RETURN VALUES 231 232EVP_CIPHER_meth_new() and EVP_CIPHER_meth_dup() return a pointer to a 233newly created B<EVP_CIPHER>, or NULL on failure. 234All EVP_CIPHER_meth_set_*() functions return 1. 235All EVP_CIPHER_meth_get_*() functions return pointers to their 236respective B<cipher> function. 237 238=head1 SEE ALSO 239 240L<EVP_EncryptInit(3)> 241 242=head1 HISTORY 243 244All of these functions were deprecated in OpenSSL 3.0. 245 246The functions described here were added in OpenSSL 1.1.0. 247The B<EVP_CIPHER> structure created with these functions became reference 248counted in OpenSSL 3.0. 249 250=head1 COPYRIGHT 251 252Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. 253 254Licensed under the Apache License 2.0 (the "License"). You may not use 255this file except in compliance with the License. You can obtain a copy 256in the file LICENSE in the source distribution or at 257L<https://www.openssl.org/source/license.html>. 258 259=cut 260
