From aa4d426b4d3527d7e166df1a05058c9a4a0f6683 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 30 Apr 2021 00:33:56 +0200 Subject: initial/final commit --- openssl-1.1.0h/doc/crypto/EVP_CIPHER_meth_new.pod | 253 ++++++++++++++++++++++ 1 file changed, 253 insertions(+) create mode 100644 openssl-1.1.0h/doc/crypto/EVP_CIPHER_meth_new.pod (limited to 'openssl-1.1.0h/doc/crypto/EVP_CIPHER_meth_new.pod') diff --git a/openssl-1.1.0h/doc/crypto/EVP_CIPHER_meth_new.pod b/openssl-1.1.0h/doc/crypto/EVP_CIPHER_meth_new.pod new file mode 100644 index 0000000..08e8290 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_CIPHER_meth_new.pod @@ -0,0 +1,253 @@ +=pod + +=head1 NAME + +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 + +=head1 SYNOPSIS + + #include + + EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len); + EVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher); + void EVP_CIPHER_meth_free(EVP_CIPHER *cipher); + + int EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len); + int EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags); + int EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size); + int EVP_CIPHER_meth_set_init(EVP_CIPHER *cipher, + int (*init) (EVP_CIPHER_CTX *ctx, + const unsigned char *key, + const unsigned char *iv, + int enc)); + int EVP_CIPHER_meth_set_do_cipher(EVP_CIPHER *cipher, + int (*do_cipher) (EVP_CIPHER_CTX *ctx, + unsigned char *out, + const unsigned char *in, + size_t inl)); + int EVP_CIPHER_meth_set_cleanup(EVP_CIPHER *cipher, + int (*cleanup) (EVP_CIPHER_CTX *)); + int EVP_CIPHER_meth_set_set_asn1_params(EVP_CIPHER *cipher, + int (*set_asn1_parameters) (EVP_CIPHER_CTX *, + ASN1_TYPE *)); + int EVP_CIPHER_meth_set_get_asn1_params(EVP_CIPHER *cipher, + int (*get_asn1_parameters) (EVP_CIPHER_CTX *, + ASN1_TYPE *)); + int EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher, + int (*ctrl) (EVP_CIPHER_CTX *, int type, + int arg, void *ptr)); + + int (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx, + const unsigned char *key, + const unsigned char *iv, + int enc); + int (*EVP_CIPHER_meth_get_do_cipher(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx, + unsigned char *out, + const unsigned char *in, + size_t inl); + int (*EVP_CIPHER_meth_get_cleanup(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *); + int (*EVP_CIPHER_meth_get_set_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, + ASN1_TYPE *); + int (*EVP_CIPHER_meth_get_get_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, + ASN1_TYPE *); + int (*EVP_CIPHER_meth_get_ctrl(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, + int type, int arg, + void *ptr); + +=head1 DESCRIPTION + +The B type is a structure for symmetric cipher method +implementation. + +EVP_CIPHER_meth_new() creates a new B structure. + +EVP_CIPHER_meth_dup() creates a copy of B. + +EVP_CIPHER_meth_free() destroys a B structure. + +EVP_CIPHER_meth_iv_length() sets the length of the IV. +This is only needed when the implemented cipher mode requires it. + +EVP_CIPHER_meth_set_flags() sets the flags to describe optional +behaviours in the particular B. +With the exception of cipher modes, of which only one may be present, +several flags can be or'd together. +The available flags are: + +=over 4 + +=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 + +The cipher mode. + +=item EVP_CIPH_VARIABLE_LENGTH + +This cipher is of variable length. + +=item EVP_CIPH_CUSTOM_IV + +Storing and initialising the IV is left entirely to the +implementation. + +=item EVP_CIPH_ALWAYS_CALL_INIT + +Set this if the implementation's init() function should be called even +if B is B. + +=item EVP_CIPH_CTRL_INIT + +Set this to have the implementation's ctrl() function called with +command code B early in its setup. + +=item EVP_CIPH_CUSTOM_KEY_LENGTH + +Checking and setting the key length after creating the B +is left to the implementation. +Whenever someone uses EVP_CIPHER_CTX_set_key_length() on a +B with this flag set, the implementation's ctrl() function +will be called with the control code B and +the key length in B. + +=item EVP_CIPH_NO_PADDING + +Don't use standard block padding. + +=item EVP_CIPH_RAND_KEY + +Making a key with random content is left to the implementation. +This is done by calling the implementation's ctrl() function with the +control code B and the pointer to the key memory +storage in B. + +=item EVP_CIPH_CUSTOM_COPY + +Set this to have the implementation's ctrl() function called with +command code B at the end of EVP_CIPHER_CTX_copy(). +The intended use is for further things to deal with after the +implementation specific data block has been copied. +The destination B is passed to the control with the +B parameter. +The implementation specific data block is reached with +EVP_CIPHER_CTX_get_cipher_data(). + +=item EVP_CIPH_FLAG_DEFAULT_ASN1 + +Use the default EVP routines to pass IV to and from ASN.1. + +=item EVP_CIPH_FLAG_LENGTH_BITS + +Signals that the length of the input buffer for encryption / +decryption is to be understood as the number of bits bits instead of +bytes for this implementation. +This is only useful for CFB1 ciphers. + +=begin comment +The FIPS flags seem to be unused, so I'm hiding them until I get an +explanation or they get removed. /RL + +=item EVP_CIPH_FLAG_FIPS + +=item EVP_CIPH_FLAG_NON_FIPS_ALLOW + +=end comment + +=item EVP_CIPH_FLAG_CUSTOM_CIPHER + +This indicates that the implementation takes care of everything, +including padding, buffering and finalization. +The EVP routines will simply give them control and do nothing more. + +=item EVP_CIPH_FLAG_AEAD_CIPHER + +This indicates that this is an AEAD cipher implementation. + +=item EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK + +Allow interleaving of crypto blocks, a particular optimization only applicable +to certain TLS ciphers. + +=back + +EVP_CIPHER_meth_set_impl_ctx_size() sets the size of the EVP_CIPHER's +implementation context so that it can be automatically allocated. + +EVP_CIPHER_meth_set_init() sets the cipher init function for +B. +The cipher init function is called by EVP_CipherInit(), +EVP_CipherInit_ex(), EVP_EncryptInit(), EVP_EncryptInit_ex(), +EVP_DecryptInit(), EVP_DecryptInit_ex(). + +EVP_CIPHER_meth_set_do_cipher() sets the cipher function for +B. +The cipher function is called by EVP_CipherUpdate(), +EVP_EncryptUpdate(), EVP_DecryptUpdate(), EVP_CipherFinal(), +EVP_EncryptFinal(), EVP_EncryptFinal_ex(), EVP_DecryptFinal() and +EVP_DecryptFinal_ex(). + +EVP_CIPHER_meth_set_cleanup() sets the function for B to do +extra cleanup before the method's private data structure is cleaned +out and freed. +Note that the cleanup function is passed a B, the +private data structure is then available with +EVP_CIPHER_CTX_get_cipher_data(). +This cleanup function is called by EVP_CIPHER_CTX_reset() and +EVP_CIPHER_CTX_free(). + +EVP_CIPHER_meth_set_set_asn1_params() sets the function for B +to set the AlgorithmIdentifier "parameter" based on the passed cipher. +This function is called by EVP_CIPHER_param_to_asn1(). +EVP_CIPHER_meth_set_get_asn1_params() sets the function for B +that sets the cipher parameters based on an ASN.1 AlgorithmIdentifier +"parameter". +Both these functions are needed when there is a need for custom data +(more or other than the cipher IV). +They are called by EVP_CIPHER_param_to_asn1() and +EVP_CIPHER_asn1_to_param() respectively if defined. + +EVP_CIPHER_meth_set_ctrl() sets the control function for B. + +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() and EVP_CIPHER_meth_get_ctrl() +are all used to retrieve the method data given with the +EVP_CIPHER_meth_set_*() functions above. + +=head1 RETURN VALUES + +EVP_CIPHER_meth_new() and EVP_CIPHER_meth_dup() return a pointer to a +newly created B, or NULL on failure. +All EVP_CIPHER_meth_set_*() functions return 1. +All EVP_CIPHER_meth_get_*() functions return pointers to their +respective B function. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +The B structure was openly available in OpenSSL before version +1.1.0. +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut -- cgit v1.2.3