{ "mode": "man", "parameter": "provider-base", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/provider-base/7/json", "generated": "2026-06-14T13:04:05Z", "synopsis": "#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/* Functions offered by libcrypto to the providers */\nconst OSSLITEM *coregettableparams(const OSSLCOREHANDLE *handle);\nint coregetparams(const OSSLCOREHANDLE *handle, OSSLPARAM params[]);\ntypedef void (*OSSLthreadstophandlerfn)(void *arg);\nint corethreadstart(const OSSLCOREHANDLE *handle,\nOSSLthreadstophandlerfn handfn,\nvoid *arg);\nOPENSSLCORECTX *coregetlibctx(const OSSLCOREHANDLE *handle);\nvoid corenewerror(const OSSLCOREHANDLE *handle);\nvoid coreseterrordebug(const OSSLCOREHANDLE *handle,\nconst char *file, int line, const char *func);\nvoid corevseterror(const OSSLCOREHANDLE *handle,\nuint32t reason, const char *fmt, valist args);\nint coreobjaddsigid(const OSSLCOREHANDLE *prov, const char *signname,\nconst char *digestname, const char *pkeyname);\nint coreobjcreate(const OSSLCOREHANDLE *handle, const char *oid,\nconst char *sn, const char *ln);\n/*\n* Some OpenSSL functionality is directly offered to providers via\n* dispatch\n*/\nvoid *CRYPTOmalloc(sizet num, const char *file, int line);\nvoid *CRYPTOzalloc(sizet num, const char *file, int line);\nvoid CRYPTOfree(void *ptr, const char *file, int line);\nvoid CRYPTOclearfree(void *ptr, sizet num,\nconst char *file, int line);\nvoid *CRYPTOrealloc(void *addr, sizet num,\nconst char *file, int line);\nvoid *CRYPTOclearrealloc(void *addr, sizet oldnum, sizet num,\nconst char *file, int line);\nvoid *CRYPTOsecuremalloc(sizet num, const char *file, int line);\nvoid *CRYPTOsecurezalloc(sizet num, const char *file, int line);\nvoid CRYPTOsecurefree(void *ptr, const char *file, int line);\nvoid CRYPTOsecureclearfree(void *ptr, sizet num,\nconst char *file, int line);\nint CRYPTOsecureallocated(const void *ptr);\nvoid OPENSSLcleanse(void *ptr, sizet len);\nunsigned char *OPENSSLhexstr2buf(const char *str, long *buflen);\nOSSLCOREBIO *BIOnewfile(const char *filename, const char *mode);\nOSSLCOREBIO *BIOnewmembuf(const void *buf, int len);\nint BIOreadex(OSSLCOREBIO *bio, void *data, sizet datalen,\nsizet *bytesread);\nint BIOwriteex(OSSLCOREBIO *bio, const void *data, sizet datalen,\nsizet *written);\nint BIOupref(OSSLCOREBIO *bio);\nint BIOfree(OSSLCOREBIO *bio);\nint BIOvprintf(OSSLCOREBIO *bio, const char *format, valist args);\nint BIOvsnprintf(char *buf, sizet n, const char *fmt, valist args);\nvoid OSSLSELFTESTsetcallback(OSSLLIBCTX *libctx, OSSLCALLBACK *cb,\nvoid *cbarg);\nsizet getentropy(const OSSLCOREHANDLE *handle,\nunsigned char pout, int entropy,\nsizet minlen, sizet maxlen);\nvoid cleanupentropy(const OSSLCOREHANDLE *handle,\nunsigned char *buf, sizet len);\nsizet getnonce(const OSSLCOREHANDLE *handle,\nunsigned char pout, sizet minlen, sizet maxlen,\nconst void *salt, sizet saltlen);\nvoid cleanupnonce(const OSSLCOREHANDLE *handle,\nunsigned char *buf, sizet len);\n/* Functions for querying the providers in the application library context */\nint providerregisterchildcb(const OSSLCOREHANDLE *handle,\nint (*createcb)(const OSSLCOREHANDLE *provider,\nvoid *cbdata),\nint (*removecb)(const OSSLCOREHANDLE *provider,\nvoid *cbdata),\nint (*globalpropscb)(const char *props, void *cbdata),\nvoid *cbdata);\nvoid providerderegisterchildcb(const OSSLCOREHANDLE *handle);\nconst char *providername(const OSSLCOREHANDLE *prov);\nvoid *providerget0providerctx(const OSSLCOREHANDLE *prov);\nconst OSSLDISPATCH *providerget0dispatch(const OSSLCOREHANDLE *prov);\nint providerupref(const OSSLCOREHANDLE *prov, int activate);\nint providerfree(const OSSLCOREHANDLE *prov, int deactivate);\n/* Functions offered by the provider to libcrypto */\nvoid providerteardown(void *provctx);\nconst OSSLITEM *providergettableparams(void *provctx);\nint providergetparams(void *provctx, OSSLPARAM params[]);\nconst OSSLALGORITHM *providerqueryoperation(void *provctx,\nint operationid,\nconst int *nostore);\nvoid providerunqueryoperation(void *provctx, int operationid,\nconst OSSLALGORITHM *algs);\nconst OSSLITEM *providergetreasonstrings(void *provctx);\nint providergetcapabilities(void *provctx, const char *capability,\nOSSLCALLBACK *cb, void *arg);\nint providerselftest(void *provctx);", "sections": { "NAME": { "content": "provider-base - The basic OpenSSL library <-> provider functions\n", "subsections": [] }, "SYNOPSIS": { "content": "#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/* Functions offered by libcrypto to the providers */\nconst OSSLITEM *coregettableparams(const OSSLCOREHANDLE *handle);\nint coregetparams(const OSSLCOREHANDLE *handle, OSSLPARAM params[]);\n\ntypedef void (*OSSLthreadstophandlerfn)(void *arg);\nint corethreadstart(const OSSLCOREHANDLE *handle,\nOSSLthreadstophandlerfn handfn,\nvoid *arg);\n\nOPENSSLCORECTX *coregetlibctx(const OSSLCOREHANDLE *handle);\nvoid corenewerror(const OSSLCOREHANDLE *handle);\nvoid coreseterrordebug(const OSSLCOREHANDLE *handle,\nconst char *file, int line, const char *func);\nvoid corevseterror(const OSSLCOREHANDLE *handle,\nuint32t reason, const char *fmt, valist args);\n\nint coreobjaddsigid(const OSSLCOREHANDLE *prov, const char *signname,\nconst char *digestname, const char *pkeyname);\nint coreobjcreate(const OSSLCOREHANDLE *handle, const char *oid,\nconst char *sn, const char *ln);\n\n/*\n* Some OpenSSL functionality is directly offered to providers via\n* dispatch\n*/\nvoid *CRYPTOmalloc(sizet num, const char *file, int line);\nvoid *CRYPTOzalloc(sizet num, const char *file, int line);\nvoid CRYPTOfree(void *ptr, const char *file, int line);\nvoid CRYPTOclearfree(void *ptr, sizet num,\nconst char *file, int line);\nvoid *CRYPTOrealloc(void *addr, sizet num,\nconst char *file, int line);\nvoid *CRYPTOclearrealloc(void *addr, sizet oldnum, sizet num,\nconst char *file, int line);\nvoid *CRYPTOsecuremalloc(sizet num, const char *file, int line);\nvoid *CRYPTOsecurezalloc(sizet num, const char *file, int line);\nvoid CRYPTOsecurefree(void *ptr, const char *file, int line);\nvoid CRYPTOsecureclearfree(void *ptr, sizet num,\nconst char *file, int line);\nint CRYPTOsecureallocated(const void *ptr);\nvoid OPENSSLcleanse(void *ptr, sizet len);\n\nunsigned char *OPENSSLhexstr2buf(const char *str, long *buflen);\n\nOSSLCOREBIO *BIOnewfile(const char *filename, const char *mode);\nOSSLCOREBIO *BIOnewmembuf(const void *buf, int len);\nint BIOreadex(OSSLCOREBIO *bio, void *data, sizet datalen,\nsizet *bytesread);\nint BIOwriteex(OSSLCOREBIO *bio, const void *data, sizet datalen,\nsizet *written);\nint BIOupref(OSSLCOREBIO *bio);\nint BIOfree(OSSLCOREBIO *bio);\nint BIOvprintf(OSSLCOREBIO *bio, const char *format, valist args);\nint BIOvsnprintf(char *buf, sizet n, const char *fmt, valist args);\n\nvoid OSSLSELFTESTsetcallback(OSSLLIBCTX *libctx, OSSLCALLBACK *cb,\nvoid *cbarg);\n\nsizet getentropy(const OSSLCOREHANDLE *handle,\nunsigned char pout, int entropy,\nsizet minlen, sizet maxlen);\nvoid cleanupentropy(const OSSLCOREHANDLE *handle,\nunsigned char *buf, sizet len);\nsizet getnonce(const OSSLCOREHANDLE *handle,\nunsigned char pout, sizet minlen, sizet maxlen,\nconst void *salt, sizet saltlen);\nvoid cleanupnonce(const OSSLCOREHANDLE *handle,\nunsigned char *buf, sizet len);\n\n/* Functions for querying the providers in the application library context */\nint providerregisterchildcb(const OSSLCOREHANDLE *handle,\nint (*createcb)(const OSSLCOREHANDLE *provider,\nvoid *cbdata),\nint (*removecb)(const OSSLCOREHANDLE *provider,\nvoid *cbdata),\nint (*globalpropscb)(const char *props, void *cbdata),\nvoid *cbdata);\nvoid providerderegisterchildcb(const OSSLCOREHANDLE *handle);\nconst char *providername(const OSSLCOREHANDLE *prov);\nvoid *providerget0providerctx(const OSSLCOREHANDLE *prov);\nconst OSSLDISPATCH *providerget0dispatch(const OSSLCOREHANDLE *prov);\nint providerupref(const OSSLCOREHANDLE *prov, int activate);\nint providerfree(const OSSLCOREHANDLE *prov, int deactivate);\n\n/* Functions offered by the provider to libcrypto */\nvoid providerteardown(void *provctx);\nconst OSSLITEM *providergettableparams(void *provctx);\nint providergetparams(void *provctx, OSSLPARAM params[]);\nconst OSSLALGORITHM *providerqueryoperation(void *provctx,\nint operationid,\nconst int *nostore);\nvoid providerunqueryoperation(void *provctx, int operationid,\nconst OSSLALGORITHM *algs);\nconst OSSLITEM *providergetreasonstrings(void *provctx);\nint providergetcapabilities(void *provctx, const char *capability,\nOSSLCALLBACK *cb, void *arg);\nint providerselftest(void *provctx);\n", "subsections": [] }, "DESCRIPTION": { "content": "All \"functions\" mentioned here are passed as function pointers between libcrypto and the\nprovider in OSSLDISPATCH arrays, in the call of the provider initialization function. See\n\"Provider\" in provider(7) for a description of the initialization function. They are known as\n\"upcalls\".\n\nAll these \"functions\" have a corresponding function type definition named\nOSSLFUNC{name}fn, and a helper function to retrieve the function pointer from a\nOSSLDISPATCH element named OSSLFUNC{name}. For example, the \"function\"\ncoregettableparams() has these:\n\ntypedef OSSLPARAM *\n(OSSLFUNCcoregettableparamsfn)(const OSSLCOREHANDLE *handle);\nstatic osslinline OSSLNAMEcoregettableparamsfn\nOSSLFUNCcoregettableparams(const OSSLDISPATCH *opf);\n\nOSSLDISPATCH arrays are indexed by numbers that are provided as macros in\nopenssl-coredispatch.h(7), as follows:\n\nFor in (the OSSLDISPATCH array passed from libcrypto to the provider):\n\ncoregettableparams OSSLFUNCCOREGETTABLEPARAMS\ncoregetparams OSSLFUNCCOREGETPARAMS\ncorethreadstart OSSLFUNCCORETHREADSTART\ncoregetlibctx OSSLFUNCCOREGETLIBCTX\ncorenewerror OSSLFUNCCORENEWERROR\ncoreseterrordebug OSSLFUNCCORESETERRORDEBUG\ncorevseterror OSSLFUNCCOREVSETERROR\ncoreobjaddsigid OSSLFUNCCOREOBJADDSIGID\ncoreobjcreate OSSLFUNCCOREOBJCREATE\nCRYPTOmalloc OSSLFUNCCRYPTOMALLOC\nCRYPTOzalloc OSSLFUNCCRYPTOZALLOC\nCRYPTOfree OSSLFUNCCRYPTOFREE\nCRYPTOclearfree OSSLFUNCCRYPTOCLEARFREE\nCRYPTOrealloc OSSLFUNCCRYPTOREALLOC\nCRYPTOclearrealloc OSSLFUNCCRYPTOCLEARREALLOC\nCRYPTOsecuremalloc OSSLFUNCCRYPTOSECUREMALLOC\nCRYPTOsecurezalloc OSSLFUNCCRYPTOSECUREZALLOC\nCRYPTOsecurefree OSSLFUNCCRYPTOSECUREFREE\nCRYPTOsecureclearfree OSSLFUNCCRYPTOSECURECLEARFREE\nCRYPTOsecureallocated OSSLFUNCCRYPTOSECUREALLOCATED\nBIOnewfile OSSLFUNCBIONEWFILE\nBIOnewmembuf OSSLFUNCBIONEWMEMBUF\nBIOreadex OSSLFUNCBIOREADEX\nBIOwriteex OSSLFUNCBIOWRITEEX\nBIOupref OSSLFUNCBIOUPREF\nBIOfree OSSLFUNCBIOFREE\nBIOvprintf OSSLFUNCBIOVPRINTF\nBIOvsnprintf OSSLFUNCBIOVSNPRINTF\nBIOputs OSSLFUNCBIOPUTS\nBIOgets OSSLFUNCBIOGETS\nBIOctrl OSSLFUNCBIOCTRL\nOPENSSLcleanse OSSLFUNCOPENSSLCLEANSE\nOSSLSELFTESTsetcallback OSSLFUNCSELFTESTCB\nosslrandgetentropy OSSLFUNCGETENTROPY\nosslrandcleanupentropy OSSLFUNCCLEANUPENTROPY\nosslrandgetnonce OSSLFUNCGETNONCE\nosslrandcleanupnonce OSSLFUNCCLEANUPNONCE\nproviderregisterchildcb OSSLFUNCPROVIDERREGISTERCHILDCB\nproviderderegisterchildcb OSSLFUNCPROVIDERDEREGISTERCHILDCB\nprovidername OSSLFUNCPROVIDERNAME\nproviderget0providerctx OSSLFUNCPROVIDERGET0PROVIDERCTX\nproviderget0dispatch OSSLFUNCPROVIDERGET0DISPATCH\nproviderupref OSSLFUNCPROVIDERUPREF\nproviderfree OSSLFUNCPROVIDERFREE\n\nFor *out (the OSSLDISPATCH array passed from the provider to libcrypto):\n\nproviderteardown OSSLFUNCPROVIDERTEARDOWN\nprovidergettableparams OSSLFUNCPROVIDERGETTABLEPARAMS\nprovidergetparams OSSLFUNCPROVIDERGETPARAMS\nproviderqueryoperation OSSLFUNCPROVIDERQUERYOPERATION\nproviderunqueryoperation OSSLFUNCPROVIDERUNQUERYOPERATION\nprovidergetreasonstrings OSSLFUNCPROVIDERGETREASONSTRINGS\nprovidergetcapabilities OSSLFUNCPROVIDERGETCAPABILITIES\nproviderselftest OSSLFUNCPROVIDERSELFTEST\n", "subsections": [ { "name": "Core functions", "content": "coregettableparams() returns a constant array of descriptor OSSLPARAM, for parameters that\ncoregetparams() can handle.\n\ncoregetparams() retrieves parameters from the core for the given handle. See \"Core\nparameters\" below for a description of currently known parameters.\n\nThe corethreadstart() function informs the core that the provider has stated an interest in\nthe current thread. The core will inform the provider when the thread eventually stops. It\nmust be passed the handle for this provider, as well as a callback handfn which will be\ncalled when the thread stops. The callback will subsequently be called, with the supplied\nargument arg, from the thread that is stopping and gets passed the provider context as an\nargument. This may be useful to perform thread specific clean up such as freeing thread local\nvariables.\n\ncoregetlibctx() retrieves the core context in which the library object for the current\nprovider is stored, accessible through the handle. This function is useful only for built-in\nproviders such as the default provider. Never cast this to OSSLLIBCTX in a provider that is\nnot built-in as the OSSLLIBCTX of the library loading the provider might be a completely\ndifferent structure than the OSSLLIBCTX of the library the provider is linked to. Use\nOSSLLIBCTXnewchild(3) instead to obtain a proper library context that is linked to the\napplication library context.\n\ncorenewerror(), coreseterrordebug() and corevseterror() are building blocks for\nreporting an error back to the core, with reference to the handle.\n\ncorenewerror()\nallocates a new thread specific error record.\n\nThis corresponds to the OpenSSL function ERRnew(3).\n\ncoreseterrordebug()\nsets debugging information in the current thread specific error record. The debugging\ninformation includes the name of the file file, the line line and the function name func\nwhere the error occurred.\n\nThis corresponds to the OpenSSL function ERRsetdebug(3).\n\ncorevseterror()\nsets the reason for the error, along with any addition data. The reason is a number\ndefined by the provider and used to index the reason strings table that's returned by\nprovidergetreasonstrings(). The additional data is given as a format string fmt and a\nset of arguments args, which are treated in the same manner as with BIOvsnprintf().\nfile and line may also be passed to indicate exactly where the error occurred or was\nreported.\n\nThis corresponds to the OpenSSL function ERRvseterror(3).\n\nThe coreobjcreate() function registers a new OID and associated short name sn and long name\nln for the given handle. It is similar to the OpenSSL function OBJcreate(3) except that it\nreturns 1 on success or 0 on failure. It will treat as success the case where the OID\nalready exists (even if the short name sn or long name ln provided as arguments differ from\nthose associated with the existing OID, in which case the new names are not associated).\nThis function is not thread safe.\n\nThe coreobjaddsigid() function registers a new composite signature algorithm (signname)\nconsisting of an underlying signature algorithm (pkeyname) and digest algorithm\n(digestname) for the given handle. It assumes that the OIDs for the composite signature\nalgorithm as well as for the underlying signature and digest algorithms are either already\nknown to OpenSSL or have been registered via a call to coreobjcreate(). It corresponds to\nthe OpenSSL function OBJaddsigid(3), except that the objects are identified by name rather\nthan a numeric NID. Any name (OID, short name or long name) can be used to identify the\nobject. It will treat as success the case where the composite signature algorithm already\nexists (even if registered against a different underlying signature or digest algorithm). For\ndigestname, NULL or an empty string is permissible for signature algorithms that do not need\na digest to operate correctly. The function returns 1 on success or 0 on failure. This\nfunction is not thread safe.\n\nCRYPTOmalloc(), CRYPTOzalloc(), CRYPTOfree(), CRYPTOclearfree(), CRYPTOrealloc(),\nCRYPTOclearrealloc(), CRYPTOsecuremalloc(), CRYPTOsecurezalloc(), CRYPTOsecurefree(),\nCRYPTOsecureclearfree(), CRYPTOsecureallocated(), BIOnewfile(), BIOnewmembuf(),\nBIOreadex(), BIOwriteex(), BIOupref(), BIOfree(), BIOvprintf(), BIOvsnprintf(),\nBIOgets(), BIOputs(), BIOctrl(), OPENSSLcleanse() and OPENSSLhexstr2buf() correspond\nexactly to the public functions with the same name. As a matter of fact, the pointers in the\nOSSLDISPATCH array are typically direct pointers to those public functions. Note that the\nBIO functions take an OSSLCOREBIO type rather than the standard BIO type. This is to ensure\nthat a provider does not mix BIOs from the core with BIOs used on the provider side (the two\nare not compatible). OSSLSELFTESTsetcallback() is used to set an optional callback that\ncan be passed into a provider. This may be ignored by a provider.\n\ngetentropy() retrieves seeding material from the operating system. The seeding material\nwill have at least entropy bytes of randomness and the output will have at least minlen and\nat most maxlen bytes. The buffer address is stored in *pout and the buffer length is\nreturned to the caller. On error, zero is returned.\n\ncleanupentropy() is used to clean up and free the buffer returned by getentropy(). The\nentropy pointer returned by getentropy() is passed in buf and its length in len.\n\ngetnonce() retrieves a nonce using the passed salt parameter of length saltlen and\noperating system specific information. The salt should contain uniquely identifying\ninformation and this is included, in an unspecified manner, as part of the output. The\noutput is stored in a buffer which contrains at least minlen and at most maxlen bytes. The\nbuffer address is stored in *pout and the buffer length returned to the caller. On error,\nzero is returned.\n\ncleanupnonce() is used to clean up and free the buffer returned by getnonce(). The nonce\npointer returned by getnonce() is passed in buf and its length in len.\n\nproviderregisterchildcb() registers callbacks for being informed about the loading and\nunloading of providers in the application's library context. handle is this provider's\nhandle and cbdata is this provider's data that will be passed back to the callbacks. It\nreturns 1 on success or 0 otherwise. These callbacks may be called while holding locks in\nlibcrypto. In order to avoid deadlocks the callback implementation must not be long running\nand must not call other OpenSSL API functions or upcalls.\n\ncreatecb is a callback that will be called when a new provider is loaded into the\napplication's library context. It is also called for any providers that are already loaded at\nthe point that this callback is registered. The callback is passed the handle being used for\nthe new provider being loadded and this provider's data in cbdata. It should return 1 on\nsuccess or 0 on failure.\n\nremovecb is a callback that will be called when a new provider is unloaded from the\napplication's library context. It is passed the handle being used for the provider being\nunloaded and this provider's data in cbdata. It should return 1 on success or 0 on failure.\n\nglobalpropscb is a callback that will be called when the global properties from the parent\nlibrary context are changed. It should return 1 on success or 0 on failure.\n\nproviderderegisterchildcb() unregisters callbacks previously registered via\nproviderregisterchildcb(). If providerregisterchildcb() has been called then\nproviderderegisterchildcb() should be called at or before the point that this provider's\nteardown function is called.\n\nprovidername() returns a string giving the name of the provider identified by handle.\n\nproviderget0providerctx() returns the provider context that is associated with the\nprovider identified by prov.\n\nproviderget0dispatch() gets the dispatch table registered by the provider identified by\nprov when it initialised.\n\nproviderupref() increments the reference count on the provider prov. If activate is nonzero\nthen the provider is also loaded if it is not already loaded. It returns 1 on success or 0 on\nfailure.\n\nproviderfree() decrements the reference count on the provider prov. If deactivate is nonzero\nthen the provider is also unloaded if it is not already loaded. It returns 1 on success or 0\non failure.\n" }, { "name": "Provider functions", "content": "providerteardown() is called when a provider is shut down and removed from the core's\nprovider store. It must free the passed provctx.\n\nprovidergettableparams() should return a constant array of descriptor OSSLPARAM, for\nparameters that providergetparams() can handle.\n\nprovidergetparams() should process the OSSLPARAM array params, setting the values of the\nparameters it understands.\n\nproviderqueryoperation() should return a constant OSSLALGORITHM that corresponds to the\ngiven operationid. It should indicate if the core may store a reference to this array by\nsetting *nostore to 0 (core may store a reference) or 1 (core may not store a reference).\n\nproviderunqueryoperation() informs the provider that the result of a\nproviderqueryoperation() is no longer directly required and that the function pointers have\nbeen copied. The operationid should match that passed to providerqueryoperation() and\nalgs should be its return value.\n\nprovidergetreasonstrings() should return a constant OSSLITEM array that provides reason\nstrings for reason codes the provider may use when reporting errors using coreputerror().\n\nThe providergetcapabilities() function should call the callback cb passing it a set of\nOSSLPARAMs and the caller supplied argument arg. The OSSLPARAMs should provide details\nabout the capability with the name given in the capability argument relevant for the provider\ncontext provctx. If a provider supports multiple capabilities with the given name then it may\ncall the callback multiple times (one for each capability). Capabilities can be useful for\ndescribing the services that a provider can offer. For further details see the \"CAPABILITIES\"\nsection below. It should return 1 on success or 0 on error.\n\nThe providerselftest() function should perform known answer tests on a subset of the\nalgorithms that it uses, and may also verify the integrity of the provider module. It should\nreturn 1 on success or 0 on error. It will return 1 if this function is not used.\n\nNone of these functions are mandatory, but a provider is fairly useless without at least\nproviderqueryoperation(), and providergettableparams() is fairly useless if not\naccompanied by providergetparams().\n" }, { "name": "Provider parameters", "content": "providergetparams() can return the following provider parameters to the core:\n\n\"name\" (OSSLPROVPARAMNAME) \nThis points to a string that should give a unique name for the provider.\n\n\"version\" (OSSLPROVPARAMVERSION) \nThis points to a string that is a version number associated with this provider. OpenSSL\nin-built providers use OPENSSLVERSIONSTR, but this may be different for any third party\nprovider. This string is for informational purposes only.\n\n\"buildinfo\" (OSSLPROVPARAMBUILDINFO) \nThis points to a string that is a build information associated with this provider.\nOpenSSL in-built providers use OPENSSLFULLVERSIONSTR, but this may be different for\nany third party provider.\n\n\"status\" (OSSLPROVPARAMSTATUS) \nThis returns 0 if the provider has entered an error state, otherwise it returns 1.\n\nprovidergettableparams() should return the above parameters.\n" }, { "name": "Core parameters", "content": "coregetparams() can retrieve the following core parameters for each provider:\n\n\"openssl-version\" (OSSLPROVPARAMCOREVERSION) \nThis points to the OpenSSL libraries' full version string, i.e. the string expanded from\nthe macro OPENSSLVERSIONSTR.\n\n\"provider-name\" (OSSLPROVPARAMCOREPROVNAME) \nThis points to the OpenSSL libraries' idea of what the calling provider is named.\n\n\"module-filename\" (OSSLPROVPARAMCOREMODULEFILENAME) \nThis points to a string containing the full filename of the providers module file.\n\nAdditionally, provider specific configuration parameters from the config file are available,\nin dotted name form. The dotted name form is a concatenation of section names and final\nconfig command name separated by periods.\n\nFor example, let's say we have the following config example:\n\nconfigdiagnostics = 1\nopensslconf = opensslinit\n\n[opensslinit]\nproviders = providerssect\n\n[providerssect]\nfoo = foosect\n\n[foosect]\nactivate = 1\ndata1 = 2\ndata2 = str\nmore = foomore\n\n[foomore]\ndata3 = foo,bar\n\nThe provider will have these additional parameters available:\n\n\"activate\"\npointing at the string \"1\"\n\n\"data1\"\npointing at the string \"2\"\n\n\"data2\"\npointing at the string \"str\"\n\n\"more.data3\"\npointing at the string \"foo,bar\"\n\nFor more information on handling parameters, see OSSLPARAM(3) as OSSLPARAMint(3).\n" } ] }, "CAPABILITIES": { "content": "Capabilities describe some of the services that a provider can offer. Applications can query\nthe capabilities to discover those services.\n\n\"TLS-GROUP\" Capability\n\nThe \"TLS-GROUP\" capability can be queried by libssl to discover the list of TLS groups that a\nprovider can support. Each group supported can be used for key exchange (KEX) or key\nencapsulation method (KEM) during a TLS handshake. TLS clients can advertise the list of TLS\ngroups they support in the supportedgroups extension, and TLS servers can select a group\nfrom the offered list that they also support. In this way a provider can add to the list of\ngroups that libssl already supports with additional ones.\n\nEach TLS group that a provider supports should be described via the callback passed in\nthrough the providergetcapabilities function. Each group should have the following details\nsupplied (all are mandatory, except OSSLCAPABILITYTLSGROUPISKEM):\n\n\"tls-group-name\" (OSSLCAPABILITYTLSGROUPNAME) \nThe name of the group as given in the IANA TLS Supported Groups registry\n.\n\n\"tls-group-name-internal\" (OSSLCAPABILITYTLSGROUPNAMEINTERNAL) \nThe name of the group as known by the provider. This could be the same as the \"tls-group-\nname\", but does not have to be.\n\n\"tls-group-id\" (OSSLCAPABILITYTLSGROUPID) \nThe TLS group id value as given in the IANA TLS Supported Groups registry.\n\n\"tls-group-alg\" (OSSLCAPABILITYTLSGROUPALG) \nThe name of a Key Management algorithm that the provider offers and that should be used\nwith this group. Keys created should be able to support key exchange or key encapsulation\nmethod (KEM), as implied by the optional OSSLCAPABILITYTLSGROUPISKEM flag. The\nalgorithm must support key and parameter generation as well as the key/parameter\ngeneration parameter, OSSLPKEYPARAMGROUPNAME. The group name given via \"tls-group-\nname-internal\" above will be passed via OSSLPKEYPARAMGROUPNAME when libssl wishes to\ngenerate keys/parameters.\n\n\"tls-group-sec-bits\" (OSSLCAPABILITYTLSGROUPSECURITYBITS) \nThe number of bits of security offered by keys in this group. The number of bits should\nbe comparable with the ones given in table 2 and 3 of the NIST SP800-57 document.\n\n\"tls-group-is-kem\" (OSSLCAPABILITYTLSGROUPISKEM) \nBoolean flag to describe if the group should be used in key exchange (KEX) mode (0,\ndefault) or in key encapsulation method (KEM) mode (1).\n\nThis parameter is optional: if not specified, KEX mode is assumed as the default mode for\nthe group.\n\nIn KEX mode, in a typical Diffie-Hellman fashion, both sides execute keygen then derive\nagainst the peer public key. To operate in KEX mode, the group implementation must\nsupport the provider functions as described in provider-keyexch(7).\n\nIn KEM mode, the client executes keygen and sends its public key, the server executes\nencapsulate using the client's public key and sends back the resulting ciphertext,\nfinally the client executes decapsulate to retrieve the same shared secret generated by\nthe server's encapsulate. To operate in KEM mode, the group implementation must support\nthe provider functions as described in provider-kem(7).\n\nBoth in KEX and KEM mode, the resulting shared secret is then used according to the\nprotocol specification.\n\n\"tls-min-tls\" (OSSLCAPABILITYTLSGROUPMINTLS) \n\"tls-max-tls\" (OSSLCAPABILITYTLSGROUPMAXTLS) \n\"tls-min-dtls\" (OSSLCAPABILITYTLSGROUPMINDTLS) \n\"tls-max-dtls\" (OSSLCAPABILITYTLSGROUPMAXDTLS) \nThese parameters can be used to describe the minimum and maximum TLS and DTLS versions\nsupported by the group. The values equate to the on-the-wire encoding of the various TLS\nversions. For example TLSv1.3 is 0x0304 (772 decimal), and TLSv1.2 is 0x0303 (771\ndecimal). A 0 indicates that there is no defined minimum or maximum. A -1 indicates that\nthe group should not be used in that protocol.\n", "subsections": [] }, "EXAMPLES": { "content": "This is an example of a simple provider made available as a dynamically loadable module. It\nimplements the fictitious algorithm \"FOO\" for the fictitious operation \"BAR\".\n\n#include \n#include \n#include \n\n/* Errors used in this provider */\n#define EMALLOC 1\n\nstatic const OSSLITEM reasons[] = {\n{ EMALLOC, \"memory allocation failure\" }.\n{ 0, NULL } /* Termination */\n};\n\n/*\n* To ensure we get the function signature right, forward declare\n* them using function types provided by openssl/coredispatch.h\n*/\nOSSLFUNCbarnewctxfn foonewctx;\nOSSLFUNCbarfreectxfn foofreectx;\nOSSLFUNCbarinitfn fooinit;\nOSSLFUNCbarupdatefn fooupdate;\nOSSLFUNCbarfinalfn foofinal;\n\nOSSLFUNCproviderqueryoperationfn pquery;\nOSSLFUNCprovidergetreasonstringsfn preasons;\nOSSLFUNCproviderteardownfn pteardown;\n\nOSSLproviderinitfn OSSLproviderinit;\n\nOSSLFUNCcoreputerror *cputerror = NULL;\n\n/* Provider context */\nstruct provctxst {\nOSSLCOREHANDLE *handle;\n}\n\n/* operation context for the algorithm FOO */\nstruct fooctxst {\nstruct provctxst *provctx;\nint b;\n};\n\nstatic void *foonewctx(void *provctx)\n{\nstruct fooctxst *fooctx = malloc(sizeof(*fooctx));\n\nif (fooctx != NULL)\nfooctx->provctx = provctx;\nelse\ncputerror(provctx->handle, EMALLOC, FILE, LINE);\nreturn fooctx;\n}\n\nstatic void foofreectx(void *fooctx)\n{\nfree(fooctx);\n}\n\nstatic int fooinit(void *vfooctx)\n{\nstruct fooctxst *fooctx = vfooctx;\n\nfooctx->b = 0x33;\n}\n\nstatic int fooupdate(void *vfooctx, unsigned char *in, sizet inl)\n{\nstruct fooctxst *fooctx = vfooctx;\n\n/* did you expect something serious? */\nif (inl == 0)\nreturn 1;\nfor (; inl-- > 0; in++)\n*in ^= fooctx->b;\nreturn 1;\n}\n\nstatic int foofinal(void *vfooctx)\n{\nstruct fooctxst *fooctx = vfooctx;\n\nfooctx->b = 0x66;\n}\n\nstatic const OSSLDISPATCH foofns[] = {\n{ OSSLFUNCBARNEWCTX, (void (*)(void))foonewctx },\n{ OSSLFUNCBARFREECTX, (void (*)(void))foofreectx },\n{ OSSLFUNCBARINIT, (void (*)(void))fooinit },\n{ OSSLFUNCBARUPDATE, (void (*)(void))fooupdate },\n{ OSSLFUNCBARFINAL, (void (*)(void))foofinal },\n{ 0, NULL }\n};\n\nstatic const OSSLALGORITHM bars[] = {\n{ \"FOO\", \"provider=chumbawamba\", foofns },\n{ NULL, NULL, NULL }\n};\n\nstatic const OSSLALGORITHM *pquery(void *provctx, int operationid,\nint *nostore)\n{\nswitch (operationid) {\ncase OSSLOPBAR:\nreturn bars;\n}\nreturn NULL;\n}\n\nstatic const OSSLITEM *preasons(void *provctx)\n{\nreturn reasons;\n}\n\nstatic void pteardown(void *provctx)\n{\nfree(provctx);\n}\n\nstatic const OSSLDISPATCH provfns[] = {\n{ OSSLFUNCPROVIDERTEARDOWN, (void (*)(void))pteardown },\n{ OSSLFUNCPROVIDERQUERYOPERATION, (void (*)(void))pquery },\n{ OSSLFUNCPROVIDERGETREASONSTRINGS, (void (*)(void))preasons },\n{ 0, NULL }\n};\n\nint OSSLproviderinit(const OSSLCOREHANDLE *handle,\nconst OSSLDISPATCH *in,\nconst OSSLDISPATCH out,\nvoid provctx)\n{\nstruct provctxst *pctx = NULL;\n\nfor (; in->functionid != 0; in++)\nswitch (in->functionid) {\ncase OSSLFUNCCOREPUTERROR:\ncputerror = OSSLFUNCcoreputerror(in);\nbreak;\n}\n\n*out = provfns;\n\nif ((pctx = malloc(sizeof(*pctx))) == NULL) {\n/*\n* ALEA IACTA EST, if the core retrieves the reason table\n* regardless, that string will be displayed, otherwise not.\n*/\ncputerror(handle, EMALLOC, FILE, LINE);\nreturn 0;\n}\npctx->handle = handle;\nreturn 1;\n}\n\nThis relies on a few things existing in openssl/coredispatch.h:\n\n#define OSSLOPBAR 4711\n\n#define OSSLFUNCBARNEWCTX 1\ntypedef void *(OSSLFUNCbarnewctxfn)(void *provctx);\nstatic osslinline OSSLFUNCbarnewctx(const OSSLDISPATCH *opf)\n{ return (OSSLFUNCbarnewctxfn *)opf->function; }\n\n#define OSSLFUNCBARFREECTX 2\ntypedef void (OSSLFUNCbarfreectxfn)(void *ctx);\nstatic osslinline OSSLFUNCbarnewctx(const OSSLDISPATCH *opf)\n{ return (OSSLFUNCbarfreectxfn *)opf->function; }\n\n#define OSSLFUNCBARINIT 3\ntypedef void *(OSSLFUNCbarinitfn)(void *ctx);\nstatic osslinline OSSLFUNCbarinit(const OSSLDISPATCH *opf)\n{ return (OSSLFUNCbarinitfn *)opf->function; }\n\n#define OSSLFUNCBARUPDATE 4\ntypedef void *(OSSLFUNCbarupdatefn)(void *ctx,\nunsigned char *in, sizet inl);\nstatic osslinline OSSLFUNCbarupdate(const OSSLDISPATCH *opf)\n{ return (OSSLFUNCbarupdatefn *)opf->function; }\n\n#define OSSLFUNCBARFINAL 5\ntypedef void *(OSSLFUNCbarfinalfn)(void *ctx);\nstatic osslinline OSSLFUNCbarfinal(const OSSLDISPATCH *opf)\n{ return (OSSLFUNCbarfinalfn *)opf->function; }\n", "subsections": [] }, "SEE ALSO": { "content": "provider(7)\n", "subsections": [] }, "HISTORY": { "content": "The concept of providers and everything surrounding them 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-06-02 PROVIDER-BASE(7SSL)", "subsections": [] } }, "summary": "provider-base - The basic OpenSSL library <-> provider functions", "flags": [], "examples": [ "This is an example of a simple provider made available as a dynamically loadable module. It", "implements the fictitious algorithm \"FOO\" for the fictitious operation \"BAR\".", "#include ", "#include ", "#include ", "/* Errors used in this provider */", "#define EMALLOC 1", "static const OSSLITEM reasons[] = {", "{ EMALLOC, \"memory allocation failure\" }.", "{ 0, NULL } /* Termination */", "};", "/*", "* To ensure we get the function signature right, forward declare", "* them using function types provided by openssl/coredispatch.h", "*/", "OSSLFUNCbarnewctxfn foonewctx;", "OSSLFUNCbarfreectxfn foofreectx;", "OSSLFUNCbarinitfn fooinit;", "OSSLFUNCbarupdatefn fooupdate;", "OSSLFUNCbarfinalfn foofinal;", "OSSLFUNCproviderqueryoperationfn pquery;", "OSSLFUNCprovidergetreasonstringsfn preasons;", "OSSLFUNCproviderteardownfn pteardown;", "OSSLproviderinitfn OSSLproviderinit;", "OSSLFUNCcoreputerror *cputerror = NULL;", "/* Provider context */", "struct provctxst {", "OSSLCOREHANDLE *handle;", "/* operation context for the algorithm FOO */", "struct fooctxst {", "struct provctxst *provctx;", "int b;", "};", "static void *foonewctx(void *provctx)", "struct fooctxst *fooctx = malloc(sizeof(*fooctx));", "if (fooctx != NULL)", "fooctx->provctx = provctx;", "else", "cputerror(provctx->handle, EMALLOC, FILE, LINE);", "return fooctx;", "static void foofreectx(void *fooctx)", "free(fooctx);", "static int fooinit(void *vfooctx)", "struct fooctxst *fooctx = vfooctx;", "fooctx->b = 0x33;", "static int fooupdate(void *vfooctx, unsigned char *in, sizet inl)", "struct fooctxst *fooctx = vfooctx;", "/* did you expect something serious? */", "if (inl == 0)", "return 1;", "for (; inl-- > 0; in++)", "*in ^= fooctx->b;", "return 1;", "static int foofinal(void *vfooctx)", "struct fooctxst *fooctx = vfooctx;", "fooctx->b = 0x66;", "static const OSSLDISPATCH foofns[] = {", "{ OSSLFUNCBARNEWCTX, (void (*)(void))foonewctx },", "{ OSSLFUNCBARFREECTX, (void (*)(void))foofreectx },", "{ OSSLFUNCBARINIT, (void (*)(void))fooinit },", "{ OSSLFUNCBARUPDATE, (void (*)(void))fooupdate },", "{ OSSLFUNCBARFINAL, (void (*)(void))foofinal },", "{ 0, NULL }", "};", "static const OSSLALGORITHM bars[] = {", "{ \"FOO\", \"provider=chumbawamba\", foofns },", "{ NULL, NULL, NULL }", "};", "static const OSSLALGORITHM *pquery(void *provctx, int operationid,", "int *nostore)", "switch (operationid) {", "case OSSLOPBAR:", "return bars;", "return NULL;", "static const OSSLITEM *preasons(void *provctx)", "return reasons;", "static void pteardown(void *provctx)", "free(provctx);", "static const OSSLDISPATCH provfns[] = {", "{ OSSLFUNCPROVIDERTEARDOWN, (void (*)(void))pteardown },", "{ OSSLFUNCPROVIDERQUERYOPERATION, (void (*)(void))pquery },", "{ OSSLFUNCPROVIDERGETREASONSTRINGS, (void (*)(void))preasons },", "{ 0, NULL }", "};", "int OSSLproviderinit(const OSSLCOREHANDLE *handle,", "const OSSLDISPATCH *in,", "const OSSLDISPATCH out,", "void provctx)", "struct provctxst *pctx = NULL;", "for (; in->functionid != 0; in++)", "switch (in->functionid) {", "case OSSLFUNCCOREPUTERROR:", "cputerror = OSSLFUNCcoreputerror(in);", "break;", "*out = provfns;", "if ((pctx = malloc(sizeof(*pctx))) == NULL) {", "/*", "* ALEA IACTA EST, if the core retrieves the reason table", "* regardless, that string will be displayed, otherwise not.", "*/", "cputerror(handle, EMALLOC, FILE, LINE);", "return 0;", "pctx->handle = handle;", "return 1;", "This relies on a few things existing in openssl/coredispatch.h:", "#define OSSLOPBAR 4711", "#define OSSLFUNCBARNEWCTX 1", "typedef void *(OSSLFUNCbarnewctxfn)(void *provctx);", "static osslinline OSSLFUNCbarnewctx(const OSSLDISPATCH *opf)", "{ return (OSSLFUNCbarnewctxfn *)opf->function; }", "#define OSSLFUNCBARFREECTX 2", "typedef void (OSSLFUNCbarfreectxfn)(void *ctx);", "static osslinline OSSLFUNCbarnewctx(const OSSLDISPATCH *opf)", "{ return (OSSLFUNCbarfreectxfn *)opf->function; }", "#define OSSLFUNCBARINIT 3", "typedef void *(OSSLFUNCbarinitfn)(void *ctx);", "static osslinline OSSLFUNCbarinit(const OSSLDISPATCH *opf)", "{ return (OSSLFUNCbarinitfn *)opf->function; }", "#define OSSLFUNCBARUPDATE 4", "typedef void *(OSSLFUNCbarupdatefn)(void *ctx,", "unsigned char *in, sizet inl);", "static osslinline OSSLFUNCbarupdate(const OSSLDISPATCH *opf)", "{ return (OSSLFUNCbarupdatefn *)opf->function; }", "#define OSSLFUNCBARFINAL 5", "typedef void *(OSSLFUNCbarfinalfn)(void *ctx);", "static osslinline OSSLFUNCbarfinal(const OSSLDISPATCH *opf)", "{ return (OSSLFUNCbarfinalfn *)opf->function; }" ], "see_also": [ { "name": "provider", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/provider/7/json" } ] }