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