335 lines
9.7 KiB
Groff
335 lines
9.7 KiB
Groff
.\" $OpenBSD: EVP_CIPHER_meth_new.3,v 1.1 2023/03/16 15:05:23 tb Exp $
|
|
.\" selective merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000
|
|
.\"
|
|
.\" The original file was written by Richard Levitte <levitte@openssl.org>
|
|
.\" Copyright (c) 2015 The OpenSSL Project.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\"
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\"
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in
|
|
.\" the documentation and/or other materials provided with the
|
|
.\" distribution.
|
|
.\"
|
|
.\" 3. All advertising materials mentioning features or use of this
|
|
.\" software must display the following acknowledgment:
|
|
.\" "This product includes software developed by the OpenSSL Project
|
|
.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
|
|
.\"
|
|
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
|
|
.\" endorse or promote products derived from this software without
|
|
.\" prior written permission. For written permission, please contact
|
|
.\" openssl-core@openssl.org.
|
|
.\"
|
|
.\" 5. Products derived from this software may not be called "OpenSSL"
|
|
.\" nor may "OpenSSL" appear in their names without prior written
|
|
.\" permission of the OpenSSL Project.
|
|
.\"
|
|
.\" 6. Redistributions of any form whatsoever must retain the following
|
|
.\" acknowledgment:
|
|
.\" "This product includes software developed by the OpenSSL Project
|
|
.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
|
|
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
|
|
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
|
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
|
|
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd $Mdocdate: March 16 2023 $
|
|
.Dt EVP_CIPHER_METH_NEW 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm EVP_CIPHER_meth_new ,
|
|
.Nm EVP_CIPHER_meth_dup ,
|
|
.Nm EVP_CIPHER_meth_free ,
|
|
.Nm EVP_CIPHER_meth_set_iv_length ,
|
|
.Nm EVP_CIPHER_meth_set_flags ,
|
|
.Nm EVP_CIPHER_meth_set_impl_ctx_size ,
|
|
.Nm EVP_CIPHER_meth_set_init ,
|
|
.Nm EVP_CIPHER_meth_set_do_cipher ,
|
|
.Nm EVP_CIPHER_meth_set_cleanup ,
|
|
.Nm EVP_CIPHER_meth_set_set_asn1_params ,
|
|
.Nm EVP_CIPHER_meth_set_get_asn1_params ,
|
|
.Nm EVP_CIPHER_meth_set_ctrl
|
|
.Nd Routines to build up EVP_CIPHER methods
|
|
.Sh SYNOPSIS
|
|
.In openssl/evp.h
|
|
.Ft EVP_CIPHER *
|
|
.Fo EVP_CIPHER_meth_new
|
|
.Fa "int cipher_type"
|
|
.Fa "int block_size"
|
|
.Fa "int key_len"
|
|
.Fc
|
|
.Ft EVP_CIPHER *
|
|
.Fo EVP_CIPHER_meth_dup
|
|
.Fa "const EVP_CIPHER *cipher"
|
|
.Fc
|
|
.Ft void
|
|
.Fo EVP_CIPHER_meth_free
|
|
.Fa "EVP_CIPHER *cipher"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_CIPHER_meth_set_iv_length
|
|
.Fa "EVP_CIPHER *cipher"
|
|
.Fa "int iv_len"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_CIPHER_meth_set_flags
|
|
.Fa "EVP_CIPHER *cipher"
|
|
.Fa "unsigned long flags"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_CIPHER_meth_set_impl_ctx_size
|
|
.Fa "EVP_CIPHER *cipher"
|
|
.Fa "int ctx_size"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_CIPHER_meth_set_init
|
|
.Fa "EVP_CIPHER *cipher"
|
|
.Fa "int (*init)(EVP_CIPHER_CTX *ctx, const unsigned char *key,\
|
|
const unsigned char *iv, int enc)"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_CIPHER_meth_set_do_cipher
|
|
.Fa "EVP_CIPHER *cipher"
|
|
.Fa "int (*do_cipher)(EVP_CIPHER_CTX *ctx, unsigned char *out,\
|
|
const unsigned char *in, size_t inl)"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_CIPHER_meth_set_cleanup
|
|
.Fa "EVP_CIPHER *cipher"
|
|
.Fa "int (*cleanup)(EVP_CIPHER_CTX *)"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_CIPHER_meth_set_set_asn1_params
|
|
.Fa "EVP_CIPHER *cipher"
|
|
.Fa "int (*set_asn1_parameters)(EVP_CIPHER_CTX *, ASN1_TYPE *)"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_CIPHER_meth_set_get_asn1_params
|
|
.Fa "EVP_CIPHER *cipher"
|
|
.Fa "int (*get_asn1_parameters)(EVP_CIPHER_CTX *, ASN1_TYPE *)"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_CIPHER_meth_set_ctrl
|
|
.Fa "EVP_CIPHER *cipher"
|
|
.Fa "int (*ctrl)(EVP_CIPHER_CTX *, int type, int arg, void *ptr)"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Vt EVP_CIPHER
|
|
type is a structure holding function pointers for
|
|
a symmetric cipher implementation.
|
|
.Pp
|
|
.Fn EVP_CIPHER_meth_new
|
|
allocates a new
|
|
.Vt EVP_CIPHER
|
|
structure.
|
|
The cipher's NID (see
|
|
.Xr EVP_CIPHER_nid 3 )
|
|
is set to
|
|
.Fa cipher_type ,
|
|
the block size and key length are set to
|
|
.Fa block_size
|
|
and
|
|
.Fa key_len ,
|
|
respectively.
|
|
.Pp
|
|
.Fn EVP_CIPHER_meth_dup
|
|
creates a copy of
|
|
.Fa cipher .
|
|
.Pp
|
|
.Fn EVP_CIPHER_meth_free
|
|
frees an
|
|
.Vt EVP_CIPHER
|
|
structure.
|
|
.Pp
|
|
.Fn EVP_CIPHER_meth_set_iv_length
|
|
sets the length of the initialization vector.
|
|
This is only needed when the implemented cipher mode requires it.
|
|
.Pp
|
|
.Fn EVP_CIPHER_meth_set_flags
|
|
overwrites the flags to describe optional behaviours in
|
|
.Fa cipher
|
|
with
|
|
.Fa flags .
|
|
At most one of the following cipher modes can be set:
|
|
.Dv EVP_CIPH_STREAM_CIPHER ,
|
|
.Dv EVP_CIPH_ECB_MODE ,
|
|
.Dv EVP_CIPH_CBC_MODE ,
|
|
.Dv EVP_CIPH_CFB_MODE ,
|
|
.Dv EVP_CIPH_OFB_MODE ,
|
|
.Dv EVP_CIPH_CTR_MODE ,
|
|
.Dv EVP_CIPH_GCM_MODE ,
|
|
.Dv EVP_CIPH_CCM_MODE ,
|
|
.Dv EVP_CIPH_XTS_MODE ,
|
|
and
|
|
.Dv EVP_CIPH_WRAP_MODE .
|
|
The available flags are:
|
|
.Bl -tag -width Ds
|
|
.It EVP_CIPH_VARIABLE_LENGTH
|
|
This cipher is of variable length.
|
|
.It EVP_CIPH_CUSTOM_IV
|
|
Storing and initialising the IV is left entirely to the implementation.
|
|
.It EVP_CIPH_ALWAYS_CALL_INIT
|
|
Set this if the implementation's
|
|
.Fn init
|
|
function should be called even if
|
|
.Fa key
|
|
is
|
|
.Dv NULL .
|
|
.It EVP_CIPH_CTRL_INIT
|
|
Set this to have the implementation's
|
|
.Fn ctrl
|
|
function called with command code
|
|
.Dv EVP_CTRL_INIT
|
|
early in its setup.
|
|
.It EVP_CIPH_CUSTOM_KEY_LENGTH
|
|
Checking and setting the key length after creating the
|
|
.Vt EVP_CIPHER
|
|
is left to the implementation.
|
|
Whenever someone uses
|
|
.Xr EVP_CIPHER_CTX_set_key_length 3
|
|
on a
|
|
.Vt EVP_CIPHER
|
|
with this flag set, the implementation's
|
|
.Fn ctrl
|
|
function will be called with the control code
|
|
.Dv EVP_CTRL_SET_KEY_LENGTH
|
|
and the key length in
|
|
.Fa arg .
|
|
.It EVP_CIPH_NO_PADDING
|
|
Don't use standard block padding.
|
|
.It EVP_CIPH_RAND_KEY
|
|
Making a key with random content is left to the implementation.
|
|
This is done by calling the implementation's
|
|
.Fn ctrl
|
|
function with the control code
|
|
.Dv EVP_CTRL_RAND_KEY
|
|
and the pointer to the key memory storage in
|
|
.Fa ptr .
|
|
.It EVP_CIPH_CUSTOM_COPY
|
|
Set this to have the implementation's
|
|
.Fn ctrl
|
|
function called with command code
|
|
.Dv EVP_CTRL_COPY
|
|
at the end of
|
|
.Xr EVP_CIPHER_CTX_copy 3 .
|
|
The intended use is for further things to deal with after the
|
|
implementation specific data block has been copied.
|
|
The destination
|
|
.Vt EVP_CIPHER_CTX
|
|
object is passed to the control with the
|
|
.Fa ptr
|
|
parameter.
|
|
The implementation-specific data block is reached with
|
|
.Xr EVP_CIPHER_CTX_get_cipher_data 3 .
|
|
.It EVP_CIPH_FLAG_DEFAULT_ASN1
|
|
Use the default EVP routines to pass IV to and from ASN.1.
|
|
.It 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 instead of bytes for this
|
|
implementation.
|
|
This is only useful for CFB1 ciphers.
|
|
.It 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.
|
|
.It EVP_CIPH_FLAG_AEAD_CIPHER
|
|
This indicates that this is an AEAD cipher implementation.
|
|
.El
|
|
.Pp
|
|
.Fn EVP_CIPHER_meth_set_impl_ctx_size
|
|
sets the size of the EVP_CIPHER's implementation context so that it can
|
|
be automatically allocated.
|
|
.Pp
|
|
.Fn EVP_CIPHER_meth_set_init
|
|
sets the cipher init function for
|
|
.Fa cipher .
|
|
The cipher init function is called by
|
|
.Xr EVP_CipherInit 3 ,
|
|
.Xr EVP_CipherInit_ex 3 ,
|
|
.Xr EVP_EncryptInit 3 ,
|
|
.Xr EVP_EncryptInit_ex 3 ,
|
|
.Xr EVP_DecryptInit 3 ,
|
|
.Xr EVP_DecryptInit_ex 3 .
|
|
.Pp
|
|
.Fn EVP_CIPHER_meth_set_do_cipher
|
|
sets the cipher function for
|
|
.Fa cipher .
|
|
The cipher function is called by
|
|
.Xr EVP_CipherUpdate 3 ,
|
|
.Xr EVP_EncryptUpdate 3 ,
|
|
.Xr EVP_DecryptUpdate 3 ,
|
|
.Xr EVP_CipherFinal 3 ,
|
|
.Xr EVP_EncryptFinal 3 ,
|
|
.Xr EVP_EncryptFinal_ex 3 ,
|
|
.Xr EVP_DecryptFinal 3
|
|
and
|
|
.Xr EVP_DecryptFinal_ex 3 .
|
|
.Pp
|
|
.Fn EVP_CIPHER_meth_set_cleanup
|
|
sets the function for
|
|
.Fa cipher
|
|
to do extra cleanup before the method's private data structure is
|
|
cleaned out and freed.
|
|
Note that the cleanup function is passed a
|
|
.Sy EVP_CIPHER_CTX * ,
|
|
the private data structure is then available with
|
|
.Xr EVP_CIPHER_CTX_get_cipher_data 3 .
|
|
This cleanup function is called by
|
|
.Xr EVP_CIPHER_CTX_reset 3
|
|
and
|
|
.Xr EVP_CIPHER_CTX_free 3 .
|
|
.Pp
|
|
.Fn EVP_CIPHER_meth_set_set_asn1_params
|
|
sets the function for
|
|
.Fa cipher
|
|
to set the AlgorithmIdentifier "parameter" based on the passed cipher.
|
|
This function is called by
|
|
.Xr EVP_CIPHER_param_to_asn1 3 .
|
|
.Fn EVP_CIPHER_meth_set_get_asn1_params
|
|
sets the function for
|
|
.Fa cipher
|
|
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
|
|
.Xr EVP_CIPHER_param_to_asn1 3
|
|
and
|
|
.Xr EVP_CIPHER_asn1_to_param 3
|
|
respectively if defined.
|
|
.Pp
|
|
.Fn EVP_CIPHER_meth_set_ctrl
|
|
sets the control function for
|
|
.Fa cipher .
|
|
.Sh RETURN VALUES
|
|
.Fn EVP_CIPHER_meth_new
|
|
and
|
|
.Fn EVP_CIPHER_meth_dup
|
|
return a pointer to a newly created
|
|
.Vt EVP_CIPHER ,
|
|
or NULL on failure.
|
|
.Pp
|
|
All
|
|
.Fn EVP_CIPHER_meth_set_*
|
|
functions return 1.
|
|
.Sh SEE ALSO
|
|
.Xr EVP_EncryptInit 3
|
|
.Sh HISTORY
|
|
These functions first appeared in OpenSSL 1.1.0 and have been available since
|
|
.Ox 7.3 .
|