558 lines
29 KiB
Groff
Executable File
558 lines
29 KiB
Groff
Executable File
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
|
.\" nothing in troff, for use with C<>.
|
|
.tr \(*W-
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
'br\}
|
|
.\"
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\"
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
.\" output yourself in some meaningful fashion.
|
|
.ie \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. nr % 0
|
|
. rr F
|
|
.\}
|
|
.el \{\
|
|
. de IX
|
|
..
|
|
.\}
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "PROVIDER-CIPHER 7"
|
|
.TH PROVIDER-CIPHER 7 "2020-03-02" "3.0.0-dev" "OpenSSL"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
.\" way too many mistakes in technical documents.
|
|
.if n .ad l
|
|
.nh
|
|
.SH "NAME"
|
|
provider\-cipher \- The cipher library <\-> provider functions
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 2
|
|
\& #include <openssl/core_numbers.h>
|
|
\& #include <openssl/core_names.h>
|
|
\&
|
|
\& /*
|
|
\& * None of these are actual functions, but are displayed like this for
|
|
\& * the function signatures for functions that are offered as function
|
|
\& * pointers in OSSL_DISPATCH arrays.
|
|
\& */
|
|
\&
|
|
\& /* Context management */
|
|
\& void *OP_cipher_newctx(void *provctx);
|
|
\& void OP_cipher_freectx(void *cctx);
|
|
\& void *OP_cipher_dupctx(void *cctx);
|
|
\&
|
|
\& /* Encryption/decryption */
|
|
\& int OP_cipher_encrypt_init(void *cctx, const unsigned char *key,
|
|
\& size_t keylen, const unsigned char *iv,
|
|
\& size_t ivlen);
|
|
\& int OP_cipher_decrypt_init(void *cctx, const unsigned char *key,
|
|
\& size_t keylen, const unsigned char *iv,
|
|
\& size_t ivlen);
|
|
\& int OP_cipher_update(void *cctx, unsigned char *out, size_t *outl,
|
|
\& size_t outsize, const unsigned char *in, size_t inl);
|
|
\& int OP_cipher_final(void *cctx, unsigned char *out, size_t *outl,
|
|
\& size_t outsize);
|
|
\& int OP_cipher_cipher(void *cctx, unsigned char *out, size_t *outl,
|
|
\& size_t outsize, const unsigned char *in, size_t inl);
|
|
\&
|
|
\& /* Cipher parameter descriptors */
|
|
\& const OSSL_PARAM *OP_cipher_gettable_params(void);
|
|
\&
|
|
\& /* Cipher operation parameter descriptors */
|
|
\& const OSSL_PARAM *OP_cipher_gettable_ctx_params(void);
|
|
\& const OSSL_PARAM *OP_cipher_settable_ctx_params(void);
|
|
\&
|
|
\& /* Cipher parameters */
|
|
\& int OP_cipher_get_params(OSSL_PARAM params[]);
|
|
\&
|
|
\& /* Cipher operation parameters */
|
|
\& int OP_cipher_get_ctx_params(void *cctx, OSSL_PARAM params[]);
|
|
\& int OP_cipher_set_ctx_params(void *cctx, const OSSL_PARAM params[]);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
This documentation is primarily aimed at provider authors. See \fIprovider\fR\|(7)
|
|
for further information.
|
|
.PP
|
|
The \s-1CIPHER\s0 operation enables providers to implement cipher algorithms and make
|
|
them available to applications via the \s-1API\s0 functions \fIEVP_EncryptInit_ex\fR\|(3),
|
|
\&\fIEVP_EncryptUpdate\fR\|(3) and \fIEVP_EncryptFinal\fR\|(3) (as well as the decrypt
|
|
equivalents and other related functions).
|
|
.PP
|
|
All \*(L"functions\*(R" mentioned here are passed as function pointers between
|
|
\&\fIlibcrypto\fR and the provider in \fB\s-1OSSL_DISPATCH\s0\fR arrays via
|
|
\&\fB\s-1OSSL_ALGORITHM\s0\fR arrays that are returned by the provider's
|
|
\&\fIprovider_query_operation()\fR function
|
|
(see \*(L"Provider Functions\*(R" in \fIprovider\-base\fR\|(7)).
|
|
.PP
|
|
All these \*(L"functions\*(R" have a corresponding function type definition
|
|
named \fBOSSL_{name}_fn\fR, and a helper function to retrieve the
|
|
function pointer from an \fB\s-1OSSL_DISPATCH\s0\fR element named
|
|
\&\fBOSSL_get_{name}\fR.
|
|
For example, the \*(L"function\*(R" \fIOP_cipher_newctx()\fR has these:
|
|
.PP
|
|
.Vb 3
|
|
\& typedef void *(OSSL_OP_cipher_newctx_fn)(void *provctx);
|
|
\& static ossl_inline OSSL_OP_cipher_newctx_fn
|
|
\& OSSL_get_OP_cipher_newctx(const OSSL_DISPATCH *opf);
|
|
.Ve
|
|
.PP
|
|
\&\fB\s-1OSSL_DISPATCH\s0\fR arrays are indexed by numbers that are provided as
|
|
macros in \fIopenssl\-core_numbers.h\fR\|(7), as follows:
|
|
.PP
|
|
.Vb 3
|
|
\& OP_cipher_newctx OSSL_FUNC_CIPHER_NEWCTX
|
|
\& OP_cipher_freectx OSSL_FUNC_CIPHER_FREECTX
|
|
\& OP_cipher_dupctx OSSL_FUNC_CIPHER_DUPCTX
|
|
\&
|
|
\& OP_cipher_encrypt_init OSSL_FUNC_CIPHER_ENCRYPT_INIT
|
|
\& OP_cipher_decrypt_init OSSL_FUNC_CIPHER_DECRYPT_INIT
|
|
\& OP_cipher_update OSSL_FUNC_CIPHER_UPDATE
|
|
\& OP_cipher_final OSSL_FUNC_CIPHER_FINAL
|
|
\& OP_cipher_cipher OSSL_FUNC_CIPHER_CIPHER
|
|
\&
|
|
\& OP_cipher_get_params OSSL_FUNC_CIPHER_GET_PARAMS
|
|
\& OP_cipher_get_ctx_params OSSL_FUNC_CIPHER_GET_CTX_PARAMS
|
|
\& OP_cipher_set_ctx_params OSSL_FUNC_CIPHER_SET_CTX_PARAMS
|
|
\&
|
|
\& OP_cipher_gettable_params OSSL_FUNC_CIPHER_GETTABLE_PARAMS
|
|
\& OP_cipher_gettable_ctx_params OSSL_FUNC_CIPHER_GETTABLE_CTX_PARAMS
|
|
\& OP_cipher_settable_ctx_params OSSL_FUNC_CIPHER_SETTABLE_CTX_PARAMS
|
|
.Ve
|
|
.PP
|
|
A cipher algorithm implementation may not implement all of these functions.
|
|
In order to be a consistent set of functions there must at least be a complete
|
|
set of \*(L"encrypt\*(R" functions, or a complete set of \*(L"decrypt\*(R" functions, or a
|
|
single \*(L"cipher\*(R" function.
|
|
In all cases both the OP_cipher_newctx and OP_cipher_freectx functions must be
|
|
present.
|
|
All other functions are optional.
|
|
.SS "Context Management Functions"
|
|
.IX Subsection "Context Management Functions"
|
|
\&\fIOP_cipher_newctx()\fR should create and return a pointer to a provider side
|
|
structure for holding context information during a cipher operation.
|
|
A pointer to this context will be passed back in a number of the other cipher
|
|
operation function calls.
|
|
The parameter \fIprovctx\fR is the provider context generated during provider
|
|
initialisation (see \fIprovider\fR\|(7)).
|
|
.PP
|
|
\&\fIOP_cipher_freectx()\fR is passed a pointer to the provider side cipher context in
|
|
the \fIcctx\fR parameter.
|
|
This function should free any resources associated with that context.
|
|
.PP
|
|
\&\fIOP_cipher_dupctx()\fR should duplicate the provider side cipher context in the
|
|
\&\fIcctx\fR parameter and return the duplicate copy.
|
|
.SS "Encryption/Decryption Functions"
|
|
.IX Subsection "Encryption/Decryption Functions"
|
|
\&\fIOP_cipher_encrypt_init()\fR initialises a cipher operation for encryption given a
|
|
newly created provider side cipher context in the \fIcctx\fR parameter.
|
|
The key to be used is given in \fIkey\fR which is \fIkeylen\fR bytes long.
|
|
The \s-1IV\s0 to be used is given in \fIiv\fR which is \fIivlen\fR bytes long.
|
|
.PP
|
|
\&\fIOP_cipher_decrypt_init()\fR is the same as \fIOP_cipher_encrypt_init()\fR except that it
|
|
initialises the context for a decryption operation.
|
|
.PP
|
|
\&\fIOP_cipher_update()\fR is called to supply data to be encrypted/decrypted as part of
|
|
a previously initialised cipher operation.
|
|
The \fIcctx\fR parameter contains a pointer to a previously initialised provider
|
|
side context.
|
|
\&\fIOP_cipher_update()\fR should encrypt/decrypt \fIinl\fR bytes of data at the location
|
|
pointed to by \fIin\fR.
|
|
The encrypted data should be stored in \fIout\fR and the amount of data written to
|
|
\&\fI*outl\fR which should not exceed \fIoutsize\fR bytes.
|
|
\&\fIOP_cipher_update()\fR may be called multiple times for a single cipher operation.
|
|
It is the responsibility of the cipher implementation to handle input lengths
|
|
that are not multiples of the block length.
|
|
In such cases a cipher implementation will typically cache partial blocks of
|
|
input data until a complete block is obtained.
|
|
\&\fIout\fR may be the same location as \fIin\fR but it should not partially overlap.
|
|
The same expectations apply to \fIoutsize\fR as documented for
|
|
\&\fIEVP_EncryptUpdate\fR\|(3) and \fIEVP_DecryptUpdate\fR\|(3).
|
|
.PP
|
|
\&\fIOP_cipher_final()\fR completes an encryption or decryption started through previous
|
|
\&\fIOP_cipher_encrypt_init()\fR or \fIOP_cipher_decrypt_init()\fR, and \fIOP_cipher_update()\fR
|
|
calls.
|
|
The \fIcctx\fR parameter contains a pointer to the provider side context.
|
|
Any final encryption/decryption output should be written to \fIout\fR and the
|
|
amount of data written to \fI*outl\fR which should not exceed \fIoutsize\fR bytes.
|
|
The same expectations apply to \fIoutsize\fR as documented for
|
|
\&\fIEVP_EncryptFinal\fR\|(3) and \fIEVP_DecryptFinal\fR\|(3).
|
|
.PP
|
|
\&\fIOP_cipher_cipher()\fR performs encryption/decryption using the provider side cipher
|
|
context in the \fIcctx\fR parameter that should have been previously initialised via
|
|
a call to \fIOP_cipher_encrypt_init()\fR or \fIOP_cipher_decrypt_init()\fR.
|
|
This should call the raw underlying cipher function without any padding.
|
|
This will be invoked in the provider as a result of the application calling
|
|
\&\fIEVP_Cipher\fR\|(3).
|
|
The application is responsible for ensuring that the input is a multiple of the
|
|
block length.
|
|
The data to be encrypted/decrypted will be in \fIin\fR, and it will be \fIinl\fR bytes
|
|
in length.
|
|
The output from the encryption/decryption should be stored in \fIout\fR and the
|
|
amount of data stored should be put in \fI*outl\fR which should be no more than
|
|
\&\fIoutsize\fR bytes.
|
|
.SS "Cipher Parameters"
|
|
.IX Subsection "Cipher Parameters"
|
|
See \s-1\fIOSSL_PARAM\s0\fR\|(3) for further details on the parameters structure used by
|
|
these functions.
|
|
.PP
|
|
\&\fIOP_cipher_get_params()\fR gets details of the algorithm implementation
|
|
and stores them in \fIparams\fR.
|
|
.PP
|
|
\&\fIOP_cipher_set_ctx_params()\fR sets cipher operation parameters for the
|
|
provider side cipher context \fIcctx\fR to \fIparams\fR.
|
|
Any parameter settings are additional to any that were previously set.
|
|
.PP
|
|
\&\fIOP_cipher_get_ctx_params()\fR gets cipher operation details details from
|
|
the given provider side cipher context \fIcctx\fR and stores them in \fIparams\fR.
|
|
.PP
|
|
\&\fIOP_cipher_gettable_params()\fR, \fIOP_cipher_gettable_ctx_params()\fR, and
|
|
\&\fIOP_cipher_settable_ctx_params()\fR all return constant \fB\s-1OSSL_PARAM\s0\fR arrays
|
|
as descriptors of the parameters that \fIOP_cipher_get_params()\fR,
|
|
\&\fIOP_cipher_get_ctx_params()\fR, and \fIOP_cipher_set_ctx_params()\fR can handle,
|
|
respectively.
|
|
.PP
|
|
Parameters currently recognised by built-in ciphers are as follows. Not all
|
|
parameters are relevant to, or are understood by all ciphers:
|
|
.ie n .IP """padding"" (\fB\s-1OSSL_CIPHER_PARAM_PADDING\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``padding'' (\fB\s-1OSSL_CIPHER_PARAM_PADDING\s0\fR) <unsigned integer>" 4
|
|
.IX Item "padding (OSSL_CIPHER_PARAM_PADDING) <unsigned integer>"
|
|
Sets the padding mode for the associated cipher ctx.
|
|
Setting a value of 1 will turn padding on.
|
|
Setting a value of 0 will turn padding off.
|
|
.ie n .IP """mode"" (\fB\s-1OSSL_CIPHER_PARAM_MODE\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``mode'' (\fB\s-1OSSL_CIPHER_PARAM_MODE\s0\fR) <unsigned integer>" 4
|
|
.IX Item "mode (OSSL_CIPHER_PARAM_MODE) <unsigned integer>"
|
|
Gets the mode for the associated cipher algorithm.
|
|
See \fIEVP_CIPHER_mode\fR\|(3) for a list of valid modes.
|
|
.ie n .IP """blocksize"" (\fB\s-1OSSL_CIPHER_PARAM_BLOCK_SIZE\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``blocksize'' (\fB\s-1OSSL_CIPHER_PARAM_BLOCK_SIZE\s0\fR) <unsigned integer>" 4
|
|
.IX Item "blocksize (OSSL_CIPHER_PARAM_BLOCK_SIZE) <unsigned integer>"
|
|
Gets the block size for the associated cipher algorithm.
|
|
The block size should be 1 for stream ciphers.
|
|
Note that the block size for a cipher may be different to the block size for
|
|
the underlying encryption/decryption primitive.
|
|
For example \s-1AES\s0 in \s-1CTR\s0 mode has a block size of 1 (because it operates like a
|
|
stream cipher), even though \s-1AES\s0 has a block size of 16.
|
|
The length of the \*(L"blocksize\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
.ie n .IP """flags"" (\fB\s-1OSSL_CIPHER_PARAM_FLAGS\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``flags'' (\fB\s-1OSSL_CIPHER_PARAM_FLAGS\s0\fR) <unsigned integer>" 4
|
|
.IX Item "flags (OSSL_CIPHER_PARAM_FLAGS) <unsigned integer>"
|
|
Gets any flags for the associated cipher algorithm.
|
|
See \fIEVP_CIPHER_meth_set_flags\fR\|(3) for a list of currently defined cipher
|
|
flags.
|
|
The length of the \*(L"flags\*(R" parameter should equal that of an
|
|
\&\fBunsigned long int\fR.
|
|
.ie n .IP """keylen"" (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``keylen'' (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR) <unsigned integer>" 4
|
|
.IX Item "keylen (OSSL_CIPHER_PARAM_KEYLEN) <unsigned integer>"
|
|
Gets the key length for the associated cipher algorithm.
|
|
This can also be used to get or set the key length for the associated cipher
|
|
ctx.
|
|
The length of the \*(L"keylen\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
.ie n .IP """ivlen"" (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``ivlen'' (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR) <unsigned integer>" 4
|
|
.IX Item "ivlen (OSSL_CIPHER_PARAM_IVLEN) <unsigned integer>"
|
|
Gets the \s-1IV\s0 length for the associated cipher algorithm.
|
|
The length of the \*(L"ivlen\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
.ie n .IP """iv"" (\fB\s-1OSSL_CIPHER_PARAM_IV\s0\fR) <octet string \s-1OR\s0 octet ptr>" 4
|
|
.el .IP "``iv'' (\fB\s-1OSSL_CIPHER_PARAM_IV\s0\fR) <octet string \s-1OR\s0 octet ptr>" 4
|
|
.IX Item "iv (OSSL_CIPHER_PARAM_IV) <octet string OR octet ptr>"
|
|
Gets the \s-1IV\s0 for the associated cipher ctx.
|
|
.ie n .IP """num"" (\fB\s-1OSSL_CIPHER_PARAM_NUM\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``num'' (\fB\s-1OSSL_CIPHER_PARAM_NUM\s0\fR) <unsigned integer>" 4
|
|
.IX Item "num (OSSL_CIPHER_PARAM_NUM) <unsigned integer>"
|
|
Gets or sets the cipher specific \*(L"num\*(R" parameter for the associated cipher ctx.
|
|
Built-in ciphers typically use this to track how much of the current underlying
|
|
block has been \*(L"used\*(R" already.
|
|
.ie n .IP """tag"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAG\s0\fR) <octet string>" 4
|
|
.el .IP "``tag'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAG\s0\fR) <octet string>" 4
|
|
.IX Item "tag (OSSL_CIPHER_PARAM_AEAD_TAG) <octet string>"
|
|
Gets or sets the \s-1AEAD\s0 tag for the associated cipher ctx.
|
|
See \*(L"\s-1AEAD\s0 Interface\*(R" in \fIEVP_EncryptInit\fR\|(3).
|
|
.ie n .IP """taglen"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAGLEN\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``taglen'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAGLEN\s0\fR) <unsigned integer>" 4
|
|
.IX Item "taglen (OSSL_CIPHER_PARAM_AEAD_TAGLEN) <unsigned integer>"
|
|
Gets the tag length to be used for an \s-1AEAD\s0 cipher for the associated cipher ctx.
|
|
It returns a default value if it has not been set.
|
|
The length of the \*(L"taglen\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
.ie n .IP """tlsaad"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD\s0\fR) <octet string>" 4
|
|
.el .IP "``tlsaad'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD\s0\fR) <octet string>" 4
|
|
.IX Item "tlsaad (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD) <octet string>"
|
|
Sets TLSv1.2 \s-1AAD\s0 information for the associated cipher ctx.
|
|
TLSv1.2 \s-1AAD\s0 information is always 13 bytes in length and is as defined for the
|
|
\&\*(L"additional_data\*(R" field described in section 6.2.3.3 of \s-1RFC5246\s0.
|
|
.ie n .IP """tlsaadpad"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``tlsaadpad'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD\s0\fR) <unsigned integer>" 4
|
|
.IX Item "tlsaadpad (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD) <unsigned integer>"
|
|
Gets the length of the tag that will be added to a \s-1TLS\s0 record for the \s-1AEAD\s0
|
|
tag for the associated cipher ctx.
|
|
The length of the \*(L"tlsaadpad\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
.ie n .IP """tlsivfixed"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED\s0\fR) <octet string>" 4
|
|
.el .IP "``tlsivfixed'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED\s0\fR) <octet string>" 4
|
|
.IX Item "tlsivfixed (OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED) <octet string>"
|
|
Sets the fixed portion of an \s-1IV\s0 for an \s-1AEAD\s0 cipher used in a \s-1TLS\s0 record
|
|
encryption/ decryption for the associated cipher ctx.
|
|
\&\s-1TLS\s0 record encryption/decryption always occurs \*(L"in place\*(R" so that the input and
|
|
output buffers are always the same memory location.
|
|
\&\s-1AEAD\s0 IVs in TLSv1.2 consist of an implicit \*(L"fixed\*(R" part and an explicit part
|
|
that varies with every record.
|
|
Setting a \s-1TLS\s0 fixed \s-1IV\s0 changes a cipher to encrypt/decrypt \s-1TLS\s0 records.
|
|
\&\s-1TLS\s0 records are encrypted/decrypted using a single OP_cipher_cipher call per
|
|
record.
|
|
For a record decryption the first bytes of the input buffer will be the explicit
|
|
part of the \s-1IV\s0 and the final bytes of the input buffer will be the \s-1AEAD\s0 tag.
|
|
The length of the explicit part of the \s-1IV\s0 and the tag length will depend on the
|
|
cipher in use and will be defined in the \s-1RFC\s0 for the relevant ciphersuite.
|
|
In order to allow for \*(L"in place\*(R" decryption the plaintext output should be
|
|
written to the same location in the output buffer that the ciphertext payload
|
|
was read from, i.e. immediately after the explicit \s-1IV\s0.
|
|
.Sp
|
|
When encrypting a record the first bytes of the input buffer will be empty to
|
|
allow space for the explicit \s-1IV\s0, as will the final bytes where the tag will
|
|
be written.
|
|
The length of the input buffer will include the length of the explicit \s-1IV\s0, the
|
|
payload, and the tag bytes.
|
|
The cipher implementation should generate the explicit \s-1IV\s0 and write it to the
|
|
beginning of the output buffer, do \*(L"in place\*(R" encryption of the payload and
|
|
write that to the output buffer, and finally add the tag onto the end of the
|
|
output buffer.
|
|
.Sp
|
|
Whether encrypting or decrypting the value written to \fI*outl\fR in the
|
|
OP_cipher_cipher call should be the length of the payload excluding the explicit
|
|
\&\s-1IV\s0 length and the tag length.
|
|
.ie n .IP """ivlen"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_IVLEN\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``ivlen'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_IVLEN\s0\fR) <unsigned integer>" 4
|
|
.IX Item "ivlen (OSSL_CIPHER_PARAM_AEAD_IVLEN) <unsigned integer>"
|
|
Sets the \s-1IV\s0 length to be used for an \s-1AEAD\s0 cipher for the associated cipher ctx.
|
|
The length of the \*(L"ivlen\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
.ie n .IP """mackey"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_MAC_KEY\s0\fR) <octet string>" 4
|
|
.el .IP "``mackey'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_MAC_KEY\s0\fR) <octet string>" 4
|
|
.IX Item "mackey (OSSL_CIPHER_PARAM_AEAD_MAC_KEY) <octet string>"
|
|
Sets the \s-1MAC\s0 key used by composite \s-1AEAD\s0 ciphers such as \s-1AES\-CBC\-HMAC\-SHA256\s0.
|
|
.ie n .IP """randkey"" (\fB\s-1OSSL_CIPHER_PARAM_RANDOM_KEY\s0\fR) <octet string>" 4
|
|
.el .IP "``randkey'' (\fB\s-1OSSL_CIPHER_PARAM_RANDOM_KEY\s0\fR) <octet string>" 4
|
|
.IX Item "randkey (OSSL_CIPHER_PARAM_RANDOM_KEY) <octet string>"
|
|
Gets a implementation specific randomly generated key for the associated
|
|
cipher ctx. This is currently only supported by 3DES (which sets the key to
|
|
odd parity).
|
|
.ie n .IP """alg_id_param"" (\fB\s-1OSSL_CIPHER_PARAM_ALG_ID\s0\fR) <octet string>" 4
|
|
.el .IP "``alg_id_param'' (\fB\s-1OSSL_CIPHER_PARAM_ALG_ID\s0\fR) <octet string>" 4
|
|
.IX Item "alg_id_param (OSSL_CIPHER_PARAM_ALG_ID) <octet string>"
|
|
Used to pass the \s-1DER\s0 encoded AlgorithmIdentifier parameter to or from
|
|
the cipher implementation. Functions like \fIEVP_CIPHER_param_to_asn1\fR\|(3)
|
|
and \fIEVP_CIPHER_asn1_to_param\fR\|(3) use this parameter for any implementation
|
|
that has the flag \fB\s-1EVP_CIPH_FLAG_CUSTOM_ASN1\s0\fR set.
|
|
.ie n .IP """rounds"" (\fB\s-1OSSL_CIPHER_PARAM_ROUNDS\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``rounds'' (\fB\s-1OSSL_CIPHER_PARAM_ROUNDS\s0\fR) <unsigned integer>" 4
|
|
.IX Item "rounds (OSSL_CIPHER_PARAM_ROUNDS) <unsigned integer>"
|
|
Sets or gets the number of rounds to be used for a cipher.
|
|
This is used by the \s-1RC5\s0 cipher.
|
|
.ie n .IP """keybits"" (\fB\s-1OSSL_CIPHER_PARAM_RC2_KEYBITS\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``keybits'' (\fB\s-1OSSL_CIPHER_PARAM_RC2_KEYBITS\s0\fR) <unsigned integer>" 4
|
|
.IX Item "keybits (OSSL_CIPHER_PARAM_RC2_KEYBITS) <unsigned integer>"
|
|
Gets or sets the effective keybits used for a \s-1RC2\s0 cipher.
|
|
The length of the \*(L"keybits\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
.ie n .IP """speed"" (\fB\s-1OSSL_CIPHER_PARAM_SPEED\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``speed'' (\fB\s-1OSSL_CIPHER_PARAM_SPEED\s0\fR) <unsigned integer>" 4
|
|
.IX Item "speed (OSSL_CIPHER_PARAM_SPEED) <unsigned integer>"
|
|
Sets the speed option for the associated cipher ctx. This is only supported
|
|
by \s-1AES\s0 \s-1SIV\s0 ciphers which disallow multiple operations by default.
|
|
Setting \*(L"speed\*(R" to 1 allows another encrypt or decrypt operation to be
|
|
performed. This is used for performance testing.
|
|
.ie n .IP """tlsivgen"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN\s0\fR) <octet string>" 4
|
|
.el .IP "``tlsivgen'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN\s0\fR) <octet string>" 4
|
|
.IX Item "tlsivgen (OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN) <octet string>"
|
|
Gets the invocation field generated for encryption.
|
|
Can only be called after \*(L"tlsivfixed\*(R" is set.
|
|
This is only used for \s-1GCM\s0 mode.
|
|
.ie n .IP """tlsivinv"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV\s0\fR) <octet string>" 4
|
|
.el .IP "``tlsivinv'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV\s0\fR) <octet string>" 4
|
|
.IX Item "tlsivinv (OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV) <octet string>"
|
|
Sets the invocation field used for decryption.
|
|
Can only be called after \*(L"tlsivfixed\*(R" is set.
|
|
This is only used for \s-1GCM\s0 mode.
|
|
.ie n .IP """tls1multi_enc"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC\s0\fR) <octet string>" 4
|
|
.el .IP "``tls1multi_enc'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC\s0\fR) <octet string>" 4
|
|
.IX Item "tls1multi_enc (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC) <octet string>"
|
|
Triggers a multiblock tls1 encrypt operation for a tls1 aware cipher that supports
|
|
sending 4 or 8 records in one go.
|
|
The cipher performs both the \s-1MAC\s0 and encrypt stages and constructs the record
|
|
headers itself.
|
|
\&\*(L"tls1multi_enc\*(R" supplies the output buffer for the encrypt operation,
|
|
\&\*(L"tls1multi_encin\*(R" & \*(L"tls1multi_interleave\*(R" must also be set in order to supply
|
|
values to the encrypt operation.
|
|
.ie n .IP """tls1multi_enclen"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``tls1multi_enclen'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN\s0\fR) <unsigned integer>" 4
|
|
.IX Item "tls1multi_enclen (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN) <unsigned integer>"
|
|
Get the total length of the record returned from the \*(L"tls1multi_enc\*(R" operation.
|
|
.ie n .IP """tls1multi_interleave"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``tls1multi_interleave'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\s0\fR) <unsigned integer>" 4
|
|
.IX Item "tls1multi_interleave (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE) <unsigned integer>"
|
|
Sets or gets the number of records being sent in one go for a tls1 multiblock
|
|
cipher operation (either 4 or 8 records).
|
|
.ie n .IP """tls1multi_encin"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN\s0\fR) <octet string>" 4
|
|
.el .IP "``tls1multi_encin'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN\s0\fR) <octet string>" 4
|
|
.IX Item "tls1multi_encin (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN) <octet string>"
|
|
Supplies the data to encrypt for a tls1 multiblock cipher operation.
|
|
.ie n .IP """tls1multi_maxsndfrag"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``tls1multi_maxsndfrag'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT\s0\fR) <unsigned integer>" 4
|
|
.IX Item "tls1multi_maxsndfrag (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT) <unsigned integer>"
|
|
Sets the maximum send fragment size for a tls1 multiblock cipher operation.
|
|
It must be set before using \*(L"tls1multi_maxbufsz\*(R".
|
|
The length of the \*(L"tls1multi_maxsndfrag\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
.ie n .IP """tls1multi_maxbufsz"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``tls1multi_maxbufsz'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE\s0\fR) <unsigned integer>" 4
|
|
.IX Item "tls1multi_maxbufsz (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE) <unsigned integer>"
|
|
Gets the maximum record length for a tls1 multiblock cipher operation.
|
|
The length of the \*(L"tls1multi_maxbufsz\*(R" parameter should not exceed that of a \fBsize_t\fR.
|
|
.ie n .IP """tls1multi_aad"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD\s0\fR) <octet string>" 4
|
|
.el .IP "``tls1multi_aad'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD\s0\fR) <octet string>" 4
|
|
.IX Item "tls1multi_aad (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD) <octet string>"
|
|
Sets the authenticated additional data used by a tls1 multiblock cipher operation.
|
|
The supplied data consists of 13 bytes of record data containing:
|
|
Bytes 0\-7: The sequence number of the first record
|
|
Byte 8: The record type
|
|
Byte 9\-10: The protocol version
|
|
Byte 11\-12: Input length (Always 0)
|
|
.Sp
|
|
\&\*(L"tls1multi_interleave\*(R" must also be set for this operation.
|
|
.ie n .IP """tls1multi_aadpacklen"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN\s0\fR) <unsigned integer>" 4
|
|
.el .IP "``tls1multi_aadpacklen'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN\s0\fR) <unsigned integer>" 4
|
|
.IX Item "tls1multi_aadpacklen (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN) <unsigned integer>"
|
|
Gets the result of running the \*(L"tls1multi_aad\*(R" operation.
|
|
.SH "RETURN VALUES"
|
|
.IX Header "RETURN VALUES"
|
|
\&\fIOP_cipher_newctx()\fR and \fIOP_cipher_dupctx()\fR should return the newly created
|
|
provider side cipher context, or \s-1NULL\s0 on failure.
|
|
.PP
|
|
\&\fIOP_cipher_encrypt_init()\fR, \fIOP_cipher_decrypt_init()\fR, \fIOP_cipher_update()\fR,
|
|
\&\fIOP_cipher_final()\fR, \fIOP_cipher_cipher()\fR, \fIOP_cipher_get_params()\fR,
|
|
\&\fIOP_cipher_get_ctx_params()\fR and \fIOP_cipher_set_ctx_params()\fR should return 1 for
|
|
success or 0 on error.
|
|
.PP
|
|
\&\fIOP_cipher_gettable_params()\fR, \fIOP_cipher_gettable_ctx_params()\fR and
|
|
\&\fIOP_cipher_settable_ctx_params()\fR should return a constant \fB\s-1OSSL_PARAM\s0\fR
|
|
array, or \s-1NULL\s0 if none is offered.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\fIprovider\fR\|(7)
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
The provider \s-1CIPHER\s0 interface was introduced in OpenSSL 3.0.
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
|
|
.PP
|
|
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
|
<https://www.openssl.org/source/license.html>.
|