{ "mode": "man", "parameter": "PROVIDER-CIPHER", "section": "7SSL", "url": "https://www.chedong.com/phpMan.php/man/PROVIDER-CIPHER/7SSL/json", "generated": "2026-05-30T07:09:31Z", "synopsis": "#include \n#include \n/*\n* None of these are actual functions, but are displayed like this for\n* the function signatures for functions that are offered as function\n* pointers in OSSLDISPATCH arrays.\n*/\n/* Context management */\nvoid *OSSLFUNCciphernewctx(void *provctx);\nvoid OSSLFUNCcipherfreectx(void *cctx);\nvoid *OSSLFUNCcipherdupctx(void *cctx);\n/* Encryption/decryption */\nint OSSLFUNCcipherencryptinit(void *cctx, const unsigned char *key,\nsizet keylen, const unsigned char *iv,\nsizet ivlen, const OSSLPARAM params[]);\nint OSSLFUNCcipherdecryptinit(void *cctx, const unsigned char *key,\nsizet keylen, const unsigned char *iv,\nsizet ivlen, const OSSLPARAM params[]);\nint OSSLFUNCcipherupdate(void *cctx, unsigned char *out, sizet *outl,\nsizet outsize, const unsigned char *in, sizet inl);\nint OSSLFUNCcipherfinal(void *cctx, unsigned char *out, sizet *outl,\nsizet outsize);\nint OSSLFUNCciphercipher(void *cctx, unsigned char *out, sizet *outl,\nsizet outsize, const unsigned char *in, sizet inl);\n/* Cipher parameter descriptors */\nconst OSSLPARAM *OSSLFUNCciphergettableparams(void *provctx);\n/* Cipher operation parameter descriptors */\nconst OSSLPARAM *OSSLFUNCciphergettablectxparams(void *cctx,\nvoid *provctx);\nconst OSSLPARAM *OSSLFUNCciphersettablectxparams(void *cctx,\nvoid *provctx);\n/* Cipher parameters */\nint OSSLFUNCciphergetparams(OSSLPARAM params[]);\n/* Cipher operation parameters */\nint OSSLFUNCciphergetctxparams(void *cctx, OSSLPARAM params[]);\nint OSSLFUNCciphersetctxparams(void *cctx, const OSSLPARAM params[]);", "sections": { "NAME": { "content": "provider-cipher - The cipher library <-> provider functions\n", "subsections": [] }, "SYNOPSIS": { "content": "#include \n#include \n\n/*\n* None of these are actual functions, but are displayed like this for\n* the function signatures for functions that are offered as function\n* pointers in OSSLDISPATCH arrays.\n*/\n\n/* Context management */\nvoid *OSSLFUNCciphernewctx(void *provctx);\nvoid OSSLFUNCcipherfreectx(void *cctx);\nvoid *OSSLFUNCcipherdupctx(void *cctx);\n\n/* Encryption/decryption */\nint OSSLFUNCcipherencryptinit(void *cctx, const unsigned char *key,\nsizet keylen, const unsigned char *iv,\nsizet ivlen, const OSSLPARAM params[]);\nint OSSLFUNCcipherdecryptinit(void *cctx, const unsigned char *key,\nsizet keylen, const unsigned char *iv,\nsizet ivlen, const OSSLPARAM params[]);\nint OSSLFUNCcipherupdate(void *cctx, unsigned char *out, sizet *outl,\nsizet outsize, const unsigned char *in, sizet inl);\nint OSSLFUNCcipherfinal(void *cctx, unsigned char *out, sizet *outl,\nsizet outsize);\nint OSSLFUNCciphercipher(void *cctx, unsigned char *out, sizet *outl,\nsizet outsize, const unsigned char *in, sizet inl);\n\n/* Cipher parameter descriptors */\nconst OSSLPARAM *OSSLFUNCciphergettableparams(void *provctx);\n\n/* Cipher operation parameter descriptors */\nconst OSSLPARAM *OSSLFUNCciphergettablectxparams(void *cctx,\nvoid *provctx);\nconst OSSLPARAM *OSSLFUNCciphersettablectxparams(void *cctx,\nvoid *provctx);\n\n/* Cipher parameters */\nint OSSLFUNCciphergetparams(OSSLPARAM params[]);\n\n/* Cipher operation parameters */\nint OSSLFUNCciphergetctxparams(void *cctx, OSSLPARAM params[]);\nint OSSLFUNCciphersetctxparams(void *cctx, const OSSLPARAM params[]);\n", "subsections": [] }, "DESCRIPTION": { "content": "This documentation is primarily aimed at provider authors. See provider(7) for further\ninformation.\n\nThe CIPHER operation enables providers to implement cipher algorithms and make them available\nto applications via the API functions EVPEncryptInitex(3), EVPEncryptUpdate(3) and\nEVPEncryptFinal(3) (as well as the decrypt equivalents and other related functions).\n\nAll \"functions\" mentioned here are passed as function pointers between libcrypto and the\nprovider in OSSLDISPATCH arrays via OSSLALGORITHM arrays that are returned by the\nprovider's providerqueryoperation() function (see \"Provider Functions\" in\nprovider-base(7)).\n\nAll these \"functions\" have a corresponding function type definition named\nOSSLFUNC{name}fn, and a helper function to retrieve the function pointer from an\nOSSLDISPATCH element named OSSLFUNC{name}. For example, the \"function\"\nOSSLFUNCciphernewctx() has these:\n\ntypedef void *(OSSLOSSLFUNCciphernewctxfn)(void *provctx);\nstatic osslinline OSSLOSSLFUNCciphernewctxfn\nOSSLFUNCciphernewctx(const OSSLDISPATCH *opf);\n\nOSSLDISPATCH arrays are indexed by numbers that are provided as macros in\nopenssl-coredispatch.h(7), as follows:\n\nOSSLFUNCciphernewctx OSSLFUNCCIPHERNEWCTX\nOSSLFUNCcipherfreectx OSSLFUNCCIPHERFREECTX\nOSSLFUNCcipherdupctx OSSLFUNCCIPHERDUPCTX\n\nOSSLFUNCcipherencryptinit OSSLFUNCCIPHERENCRYPTINIT\nOSSLFUNCcipherdecryptinit OSSLFUNCCIPHERDECRYPTINIT\nOSSLFUNCcipherupdate OSSLFUNCCIPHERUPDATE\nOSSLFUNCcipherfinal OSSLFUNCCIPHERFINAL\nOSSLFUNCciphercipher OSSLFUNCCIPHERCIPHER\n\nOSSLFUNCciphergetparams OSSLFUNCCIPHERGETPARAMS\nOSSLFUNCciphergetctxparams OSSLFUNCCIPHERGETCTXPARAMS\nOSSLFUNCciphersetctxparams OSSLFUNCCIPHERSETCTXPARAMS\n\nOSSLFUNCciphergettableparams OSSLFUNCCIPHERGETTABLEPARAMS\nOSSLFUNCciphergettablectxparams OSSLFUNCCIPHERGETTABLECTXPARAMS\nOSSLFUNCciphersettablectxparams OSSLFUNCCIPHERSETTABLECTXPARAMS\n\nA cipher algorithm implementation may not implement all of these functions. In order to be a\nconsistent set of functions there must at least be a complete set of \"encrypt\" functions, or\na complete set of \"decrypt\" functions, or a single \"cipher\" function. In all cases both the\nOSSLFUNCciphernewctx and OSSLFUNCcipherfreectx functions must be present. All other\nfunctions are optional.\n", "subsections": [ { "name": "Context Management Functions", "content": "OSSLFUNCciphernewctx() should create and return a pointer to a provider side structure for\nholding context information during a cipher operation. A pointer to this context will be\npassed back in a number of the other cipher operation function calls. The parameter provctx\nis the provider context generated during provider initialisation (see provider(7)).\n\nOSSLFUNCcipherfreectx() is passed a pointer to the provider side cipher context in the\ncctx parameter. This function should free any resources associated with that context.\n\nOSSLFUNCcipherdupctx() should duplicate the provider side cipher context in the cctx\nparameter and return the duplicate copy.\n" }, { "name": "Encryption/Decryption Functions", "content": "OSSLFUNCcipherencryptinit() initialises a cipher operation for encryption given a newly\ncreated provider side cipher context in the cctx parameter. The key to be used is given in\nkey which is keylen bytes long. The IV to be used is given in iv which is ivlen bytes long.\nThe params, if not NULL, should be set on the context in a manner similar to using\nOSSLFUNCciphersetctxparams().\n\nOSSLFUNCcipherdecryptinit() is the same as OSSLFUNCcipherencryptinit() except that it\ninitialises the context for a decryption operation.\n\nOSSLFUNCcipherupdate() is called to supply data to be encrypted/decrypted as part of a\npreviously initialised cipher operation. The cctx parameter contains a pointer to a\npreviously initialised provider side context. OSSLFUNCcipherupdate() should\nencrypt/decrypt inl bytes of data at the location pointed to by in. The encrypted data\nshould be stored in out and the amount of data written to *outl which should not exceed\noutsize bytes. OSSLFUNCcipherupdate() may be called multiple times for a single cipher\noperation. It is the responsibility of the cipher implementation to handle input lengths\nthat are not multiples of the block length. In such cases a cipher implementation will\ntypically cache partial blocks of input data until a complete block is obtained. out may be\nthe same location as in but it should not partially overlap. The same expectations apply to\noutsize as documented for EVPEncryptUpdate(3) and EVPDecryptUpdate(3).\n\nOSSLFUNCcipherfinal() completes an encryption or decryption started through previous\nOSSLFUNCcipherencryptinit() or OSSLFUNCcipherdecryptinit(), and\nOSSLFUNCcipherupdate() calls. The cctx parameter contains a pointer to the provider side\ncontext. Any final encryption/decryption output should be written to out and the amount of\ndata written to *outl which should not exceed outsize bytes. The same expectations apply to\noutsize as documented for EVPEncryptFinal(3) and EVPDecryptFinal(3).\n\nOSSLFUNCciphercipher() performs encryption/decryption using the provider side cipher\ncontext in the cctx parameter that should have been previously initialised via a call to\nOSSLFUNCcipherencryptinit() or OSSLFUNCcipherdecryptinit(). This should call the raw\nunderlying cipher function without any padding. This will be invoked in the provider as a\nresult of the application calling EVPCipher(3). The application is responsible for ensuring\nthat the input is a multiple of the block length. The data to be encrypted/decrypted will be\nin in, and it will be inl bytes in length. The output from the encryption/decryption should\nbe stored in out and the amount of data stored should be put in *outl which should be no more\nthan outsize bytes.\n" }, { "name": "Cipher Parameters", "content": "See OSSLPARAM(3) for further details on the parameters structure used by these functions.\n\nOSSLFUNCciphergetparams() gets details of the algorithm implementation and stores them in\nparams.\n\nOSSLFUNCciphersetctxparams() sets cipher operation parameters for the provider side\ncipher context cctx to params. Any parameter settings are additional to any that were\npreviously set. Passing NULL for params should return true.\n\nOSSLFUNCciphergetctxparams() gets cipher operation details details from the given\nprovider side cipher context cctx and stores them in params. Passing NULL for params should\nreturn true.\n\nOSSLFUNCciphergettableparams(), OSSLFUNCciphergettablectxparams(), and\nOSSLFUNCciphersettablectxparams() all return constant OSSLPARAM arrays as descriptors\nof the parameters that OSSLFUNCciphergetparams(), OSSLFUNCciphergetctxparams(), and\nOSSLFUNCciphersetctxparams() can handle, respectively.\nOSSLFUNCciphergettablectxparams() and OSSLFUNCciphersettablectxparams() will return\nthe parameters associated with the provider side context cctx in its current state if it is\nnot NULL. Otherwise, they return the parameters associated with the provider side algorithm\nprovctx.\n\nParameters currently recognised by built-in ciphers are listed in \"PARAMETERS\" in\nEVPEncryptInit(3). Not all parameters are relevant to, or are understood by all ciphers.\n" } ] }, "RETURN VALUES": { "content": "OSSLFUNCciphernewctx() and OSSLFUNCcipherdupctx() should return the newly created\nprovider side cipher context, or NULL on failure.\n\nOSSLFUNCcipherencryptinit(), OSSLFUNCcipherdecryptinit(), OSSLFUNCcipherupdate(),\nOSSLFUNCcipherfinal(), OSSLFUNCciphercipher(), OSSLFUNCciphergetparams(),\nOSSLFUNCciphergetctxparams() and OSSLFUNCciphersetctxparams() should return 1 for\nsuccess or 0 on error.\n\nOSSLFUNCciphergettableparams(), OSSLFUNCciphergettablectxparams() and\nOSSLFUNCciphersettablectxparams() should return a constant OSSLPARAM array, or NULL if\nnone is offered.\n", "subsections": [] }, "SEE ALSO": { "content": "provider(7), OSSLPROVIDER-FIPS(7), OSSLPROVIDER-default(7), OSSLPROVIDER-legacy(7),\nEVPCIPHER-AES(7), EVPCIPHER-ARIA(7), EVPCIPHER-BLOWFISH(7), EVPCIPHER-CAMELLIA(7),\nEVPCIPHER-CAST(7), EVPCIPHER-CHACHA(7), EVPCIPHER-DES(7), EVPCIPHER-IDEA(7),\nEVPCIPHER-RC2(7), EVPCIPHER-RC4(7), EVPCIPHER-RC5(7), EVPCIPHER-SEED(7),\nEVPCIPHER-SM4(7), lifecycle-cipher(7), EVPEncryptInit(3)\n", "subsections": [] }, "HISTORY": { "content": "The provider CIPHER interface was introduced in OpenSSL 3.0.\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.\n\nLicensed under the Apache License 2.0 (the \"License\"). You may not use this file except in\ncompliance with the License. You can obtain a copy in the file LICENSE in the source\ndistribution or at .\n\n\n\n3.0.2 2026-04-07 PROVIDER-CIPHER(7SSL)", "subsections": [] } }, "summary": "provider-cipher - The cipher library <-> provider functions", "flags": [], "examples": [], "see_also": [ { "name": "provider", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/provider/7/json" }, { "name": "OSSLPROVIDER-FIPS", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/OSSLPROVIDER-FIPS/7/json" }, { "name": "OSSLPROVIDER-default", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/OSSLPROVIDER-default/7/json" }, { "name": "OSSLPROVIDER-legacy", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/OSSLPROVIDER-legacy/7/json" }, { "name": "EVPCIPHER-AES", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPCIPHER-AES/7/json" }, { "name": "EVPCIPHER-ARIA", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPCIPHER-ARIA/7/json" }, { "name": "EVPCIPHER-BLOWFISH", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPCIPHER-BLOWFISH/7/json" }, { "name": "EVPCIPHER-CAMELLIA", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPCIPHER-CAMELLIA/7/json" }, { "name": "EVPCIPHER-CAST", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPCIPHER-CAST/7/json" }, { "name": "EVPCIPHER-CHACHA", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPCIPHER-CHACHA/7/json" }, { "name": "EVPCIPHER-DES", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPCIPHER-DES/7/json" }, { "name": "EVPCIPHER-IDEA", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPCIPHER-IDEA/7/json" }, { "name": "EVPCIPHER-RC2", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPCIPHER-RC2/7/json" }, { "name": "EVPCIPHER-RC4", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPCIPHER-RC4/7/json" }, { "name": "EVPCIPHER-RC5", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPCIPHER-RC5/7/json" }, { "name": "EVPCIPHER-SEED", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPCIPHER-SEED/7/json" }, { "name": "EVPCIPHER-SM4", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPCIPHER-SM4/7/json" }, { "name": "lifecycle-cipher", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/lifecycle-cipher/7/json" }, { "name": "EVPEncryptInit", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/EVPEncryptInit/3/json" } ] }