1=pod 2 3=head1 NAME 4 5provider-cipher - The cipher library E<lt>-E<gt> provider functions 6 7=head1 SYNOPSIS 8 9=for openssl multiple includes 10 11 #include <openssl/core_dispatch.h> 12 #include <openssl/core_names.h> 13 14 /* 15 * None of these are actual functions, but are displayed like this for 16 * the function signatures for functions that are offered as function 17 * pointers in OSSL_DISPATCH arrays. 18 */ 19 20 /* Context management */ 21 void *OSSL_FUNC_cipher_newctx(void *provctx); 22 void OSSL_FUNC_cipher_freectx(void *cctx); 23 void *OSSL_FUNC_cipher_dupctx(void *cctx); 24 25 /* Encryption/decryption */ 26 int OSSL_FUNC_cipher_encrypt_init(void *cctx, const unsigned char *key, 27 size_t keylen, const unsigned char *iv, 28 size_t ivlen, const OSSL_PARAM params[]); 29 int OSSL_FUNC_cipher_decrypt_init(void *cctx, const unsigned char *key, 30 size_t keylen, const unsigned char *iv, 31 size_t ivlen, const OSSL_PARAM params[]); 32 int OSSL_FUNC_cipher_update(void *cctx, unsigned char *out, size_t *outl, 33 size_t outsize, const unsigned char *in, size_t inl); 34 int OSSL_FUNC_cipher_final(void *cctx, unsigned char *out, size_t *outl, 35 size_t outsize); 36 int OSSL_FUNC_cipher_cipher(void *cctx, unsigned char *out, size_t *outl, 37 size_t outsize, const unsigned char *in, size_t inl); 38 39 /* Encryption/decryption using cipher pipeline */ 40 int OSSL_FUNC_cipher_pipeline_encrypt_init(void *cctx, const unsigned char *key, 41 size_t keylen, size_t numpipes, 42 const unsigned char **iv, size_t ivlen, 43 const OSSL_PARAM params[])) 44 int OSSL_FUNC_cipher_pipeline_decrypt_init(void *cctx, const unsigned char *key, 45 size_t keylen, size_t numpipes, 46 const unsigned char **iv, size_t ivlen, 47 const OSSL_PARAM params[])) 48 int OSSL_FUNC_cipher_pipeline_update(void *cctx, size_t numpipes, 49 unsigned char **out, size_t *outl, 50 const size_t *outsize, 51 const unsigned char **in, const size_t *inl)) 52 int OSSL_FUNC_cipher_pipeline_final(void *cctx, size_t numpipes, 53 unsigned char **out, size_t *outl, 54 const size_t *outsize)) 55 56 /* Cipher parameter descriptors */ 57 const OSSL_PARAM *OSSL_FUNC_cipher_gettable_params(void *provctx); 58 59 /* Cipher operation parameter descriptors */ 60 const OSSL_PARAM *OSSL_FUNC_cipher_gettable_ctx_params(void *cctx, 61 void *provctx); 62 const OSSL_PARAM *OSSL_FUNC_cipher_settable_ctx_params(void *cctx, 63 void *provctx); 64 65 /* Cipher parameters */ 66 int OSSL_FUNC_cipher_get_params(OSSL_PARAM params[]); 67 68 /* Cipher operation parameters */ 69 int OSSL_FUNC_cipher_get_ctx_params(void *cctx, OSSL_PARAM params[]); 70 int OSSL_FUNC_cipher_set_ctx_params(void *cctx, const OSSL_PARAM params[]); 71 72=head1 DESCRIPTION 73 74This documentation is primarily aimed at provider authors. See L<provider(7)> 75for further information. 76 77The CIPHER operation enables providers to implement cipher algorithms and make 78them available to applications via the API functions L<EVP_EncryptInit_ex(3)>, 79L<EVP_EncryptUpdate(3)> and L<EVP_EncryptFinal(3)> (as well as the decrypt 80equivalents and other related functions). 81 82All "functions" mentioned here are passed as function pointers between 83F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via 84L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's 85provider_query_operation() function 86(see L<provider-base(7)/Provider Functions>). 87 88All these "functions" have a corresponding function type definition 89named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the 90function pointer from an L<OSSL_DISPATCH(3)> element named 91B<OSSL_FUNC_{name}>. 92For example, the "function" OSSL_FUNC_cipher_newctx() has these: 93 94 typedef void *(OSSL_FUNC_cipher_newctx_fn)(void *provctx); 95 static ossl_inline OSSL_FUNC_cipher_newctx_fn 96 OSSL_FUNC_cipher_newctx(const OSSL_DISPATCH *opf); 97 98L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as 99macros in L<openssl-core_dispatch.h(7)>, as follows: 100 101 OSSL_FUNC_cipher_newctx OSSL_FUNC_CIPHER_NEWCTX 102 OSSL_FUNC_cipher_freectx OSSL_FUNC_CIPHER_FREECTX 103 OSSL_FUNC_cipher_dupctx OSSL_FUNC_CIPHER_DUPCTX 104 105 OSSL_FUNC_cipher_encrypt_init OSSL_FUNC_CIPHER_ENCRYPT_INIT 106 OSSL_FUNC_cipher_decrypt_init OSSL_FUNC_CIPHER_DECRYPT_INIT 107 OSSL_FUNC_cipher_update OSSL_FUNC_CIPHER_UPDATE 108 OSSL_FUNC_cipher_final OSSL_FUNC_CIPHER_FINAL 109 OSSL_FUNC_cipher_cipher OSSL_FUNC_CIPHER_CIPHER 110 111 OSSL_FUNC_cipher_pipeline_encrypt_init OSSL_FUNC_CIPHER_PIPELINE_ENCRYPT_INIT 112 OSSL_FUNC_cipher_pipeline_decrypt_init OSSL_FUNC_CIPHER_PIPELINE_DECRYPT_INIT 113 OSSL_FUNC_cipher_pipeline_update OSSL_FUNC_CIPHER_PIPELINE_UPDATE 114 OSSL_FUNC_cipher_pipeline_final OSSL_FUNC_CIPHER_PIPELINE_FINAL 115 116 OSSL_FUNC_cipher_get_params OSSL_FUNC_CIPHER_GET_PARAMS 117 OSSL_FUNC_cipher_get_ctx_params OSSL_FUNC_CIPHER_GET_CTX_PARAMS 118 OSSL_FUNC_cipher_set_ctx_params OSSL_FUNC_CIPHER_SET_CTX_PARAMS 119 120 OSSL_FUNC_cipher_gettable_params OSSL_FUNC_CIPHER_GETTABLE_PARAMS 121 OSSL_FUNC_cipher_gettable_ctx_params OSSL_FUNC_CIPHER_GETTABLE_CTX_PARAMS 122 OSSL_FUNC_cipher_settable_ctx_params OSSL_FUNC_CIPHER_SETTABLE_CTX_PARAMS 123 124A cipher algorithm implementation may not implement all of these functions. 125In order to be a consistent set of functions there must at least be a complete 126set of "encrypt" functions, or a complete set of "decrypt" functions, or a 127single "cipher" function. Similarly, there can be a complete set of pipeline 128"encrypt" functions, and/or a complete set of pipeline "decrypt" functions. 129In all cases both the OSSL_FUNC_cipher_newctx and OSSL_FUNC_cipher_freectx functions must be 130present. 131All other functions are optional. 132 133=head2 Context Management Functions 134 135OSSL_FUNC_cipher_newctx() should create and return a pointer to a provider side 136structure for holding context information during a cipher operation. 137A pointer to this context will be passed back in a number of the other cipher 138operation function calls. 139The parameter I<provctx> is the provider context generated during provider 140initialisation (see L<provider(7)>). 141 142OSSL_FUNC_cipher_freectx() is passed a pointer to the provider side cipher context in 143the I<cctx> parameter. 144This function should free any resources associated with that context. 145 146OSSL_FUNC_cipher_dupctx() should duplicate the provider side cipher context in the 147I<cctx> parameter and return the duplicate copy. 148 149=head2 Encryption/Decryption Functions 150 151OSSL_FUNC_cipher_encrypt_init() initialises a cipher operation for encryption given a 152newly created provider side cipher context in the I<cctx> parameter. 153The key to be used is given in I<key> which is I<keylen> bytes long. 154The IV to be used is given in I<iv> which is I<ivlen> bytes long. 155The I<params>, if not NULL, should be set on the context in a manner similar to 156using OSSL_FUNC_cipher_set_ctx_params(). 157 158OSSL_FUNC_cipher_decrypt_init() is the same as OSSL_FUNC_cipher_encrypt_init() except that it 159initialises the context for a decryption operation. 160 161OSSL_FUNC_cipher_update() is called to supply data to be encrypted/decrypted as part of 162a previously initialised cipher operation. 163The I<cctx> parameter contains a pointer to a previously initialised provider 164side context. 165OSSL_FUNC_cipher_update() should encrypt/decrypt I<inl> bytes of data at the location 166pointed to by I<in>. 167The encrypted data should be stored in I<out> and the amount of data written to 168I<*outl> which should not exceed I<outsize> bytes. 169OSSL_FUNC_cipher_update() may be called multiple times for a single cipher operation. 170It is the responsibility of the cipher implementation to handle input lengths 171that are not multiples of the block length. 172In such cases a cipher implementation will typically cache partial blocks of 173input data until a complete block is obtained. 174The pointers I<out> and I<in> may point to the same location, in which 175case the encryption must be done in-place. If I<out> and I<in> point to different 176locations, the requirements of L<EVP_EncryptUpdate(3)> and L<EVP_DecryptUpdate(3)> 177guarantee that the two buffers are disjoint. 178Similarly, the requirements of L<EVP_EncryptUpdate(3)> and L<EVP_DecryptUpdate(3)> 179ensure that the buffer pointed to by I<out> contains sufficient room for the 180operation being performed. 181 182OSSL_FUNC_cipher_final() completes an encryption or decryption started through previous 183OSSL_FUNC_cipher_encrypt_init() or OSSL_FUNC_cipher_decrypt_init(), and OSSL_FUNC_cipher_update() 184calls. 185The I<cctx> parameter contains a pointer to the provider side context. 186Any final encryption/decryption output should be written to I<out> and the 187amount of data written to I<*outl> which should not exceed I<outsize> bytes. 188The same expectations apply to I<outsize> as documented for 189L<EVP_EncryptFinal(3)> and L<EVP_DecryptFinal(3)>. 190 191OSSL_FUNC_cipher_cipher() performs encryption/decryption using the provider side cipher 192context in the I<cctx> parameter that should have been previously initialised via 193a call to OSSL_FUNC_cipher_encrypt_init() or OSSL_FUNC_cipher_decrypt_init(). 194This should call the raw underlying cipher function without any padding. 195This will be invoked in the provider as a result of the application calling 196L<EVP_Cipher(3)>. 197The application is responsible for ensuring that the input is a multiple of the 198block length. 199The data to be encrypted/decrypted will be in I<in>, and it will be I<inl> bytes 200in length. 201The output from the encryption/decryption should be stored in I<out> and the 202amount of data stored should be put in I<*outl> which should be no more than 203I<outsize> bytes. 204 205OSSL_FUNC_cipher_pipeline_encrypt_init(), OSSL_FUNC_cipher_pipeline_decrypt_init() 206OSSL_FUNC_cipher_pipeline_update(), and OSSL_FUNC_cipher_pipeline_final() are similar to 207the non-pipeline variants, but are used when the application is using cipher pipelining. 208The I<numpipes> parameter is the number of pipes in the pipeline. The I<iv> parameter 209is an array of buffers with IVs, each I<ivlen> bytes long. The I<in> and I<out> are 210arrays of buffer pointers. The I<inl> and I<outl>, I<outsize> are arrays of size_t 211representing corresponding buffer length as similar to the non-pipeline variants. 212All arrays are of length I<numpipes>. See L<EVP_CipherPipelineEncryptInit(3)> for more 213information. 214 215=head2 Cipher Parameters 216 217See L<OSSL_PARAM(3)> for further details on the parameters structure used by 218these functions. 219 220OSSL_FUNC_cipher_get_params() gets details of the algorithm implementation 221and stores them in I<params>. 222 223OSSL_FUNC_cipher_set_ctx_params() sets cipher operation parameters for the 224provider side cipher context I<cctx> to I<params>. 225Any parameter settings are additional to any that were previously set. 226Passing NULL for I<params> should return true. 227 228OSSL_FUNC_cipher_get_ctx_params() gets cipher operation details details from 229the given provider side cipher context I<cctx> and stores them in I<params>. 230Passing NULL for I<params> should return true. 231 232OSSL_FUNC_cipher_gettable_params(), OSSL_FUNC_cipher_gettable_ctx_params(), 233and OSSL_FUNC_cipher_settable_ctx_params() all return constant L<OSSL_PARAM(3)> 234arrays as descriptors of the parameters that OSSL_FUNC_cipher_get_params(), 235OSSL_FUNC_cipher_get_ctx_params(), and OSSL_FUNC_cipher_set_ctx_params() 236can handle, respectively. OSSL_FUNC_cipher_gettable_ctx_params() and 237OSSL_FUNC_cipher_settable_ctx_params() will return the parameters associated 238with the provider side context I<cctx> in its current state if it is 239not NULL. Otherwise, they return the parameters associated with the 240provider side algorithm I<provctx>. 241 242Parameters currently recognised by built-in ciphers are listed in 243L<EVP_EncryptInit(3)/PARAMETERS>. 244Not all parameters are relevant to, or are understood by all ciphers. 245 246=head1 RETURN VALUES 247 248OSSL_FUNC_cipher_newctx() and OSSL_FUNC_cipher_dupctx() should return the newly created 249provider side cipher context, or NULL on failure. 250 251OSSL_FUNC_cipher_encrypt_init(), OSSL_FUNC_cipher_decrypt_init(), OSSL_FUNC_cipher_update(), 252OSSL_FUNC_cipher_final(), OSSL_FUNC_cipher_cipher(), 253OSSL_FUNC_cipher_pipeline_encrypt_init(), OSSL_FUNC_cipher_pipeline_decrypt_init(), 254OSSL_FUNC_cipher_pipeline_update(), OSSL_FUNC_cipher_pipeline_final(), 255OSSL_FUNC_cipher_get_params(), OSSL_FUNC_cipher_get_ctx_params() and 256OSSL_FUNC_cipher_set_ctx_params() should return 1 for 257success or 0 on error. 258 259OSSL_FUNC_cipher_gettable_params(), OSSL_FUNC_cipher_gettable_ctx_params() and 260OSSL_FUNC_cipher_settable_ctx_params() should return a constant L<OSSL_PARAM(3)> 261array, or NULL if none is offered. 262 263=head1 SEE ALSO 264 265L<provider(7)>, L<OSSL_PROVIDER-FIPS(7)>, L<OSSL_PROVIDER-default(7)>, 266L<OSSL_PROVIDER-legacy(7)>, 267L<EVP_CIPHER-AES(7)>, L<EVP_CIPHER-ARIA(7)>, L<EVP_CIPHER-BLOWFISH(7)>, 268L<EVP_CIPHER-CAMELLIA(7)>, L<EVP_CIPHER-CAST(7)>, L<EVP_CIPHER-CHACHA(7)>, 269L<EVP_CIPHER-DES(7)>, L<EVP_CIPHER-IDEA(7)>, L<EVP_CIPHER-RC2(7)>, 270L<EVP_CIPHER-RC4(7)>, L<EVP_CIPHER-RC5(7)>, L<EVP_CIPHER-SEED(7)>, 271L<EVP_CIPHER-SM4(7)>, L<EVP_CIPHER-NULL(7)>, 272L<life_cycle-cipher(7)>, L<EVP_EncryptInit(3)> 273 274=head1 HISTORY 275 276The provider CIPHER interface was introduced in OpenSSL 3.0. 277 278=head1 COPYRIGHT 279 280Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. 281 282Licensed under the Apache License 2.0 (the "License"). You may not use 283this file except in compliance with the License. You can obtain a copy 284in the file LICENSE in the source distribution or at 285L<https://www.openssl.org/source/license.html>. 286 287=cut 288
