{
    "mode": "man",
    "parameter": "provider-kem",
    "section": "7ssl",
    "url": "https://www.chedong.com/phpMan.php/man/provider-kem/7ssl/json",
    "generated": "2026-06-15T16:45:09Z",
    "synopsis": "#include <openssl/coredispatch.h>\n#include <openssl/corenames.h>\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 *OSSLFUNCkemnewctx(void *provctx);\nvoid OSSLFUNCkemfreectx(void *ctx);\nvoid *OSSLFUNCkemdupctx(void *ctx);\n/* Encapsulation */\nint OSSLFUNCkemencapsulateinit(void *ctx, void *provkey, const char *name,\nconst OSSLPARAM params[]);\nint OSSLFUNCkemencapsulate(void *ctx, unsigned char *out, sizet *outlen,\nunsigned char *secret, sizet *secretlen);\n/* Decapsulation */\nint OSSLFUNCkemdecapsulateinit(void *ctx, void *provkey, const char *name);\nint OSSLFUNCkemdecapsulate(void *ctx, unsigned char *out, sizet *outlen,\nconst unsigned char *in, sizet inlen);\n/* KEM parameters */\nint OSSLFUNCkemgetctxparams(void *ctx, OSSLPARAM params[]);\nconst OSSLPARAM *OSSLFUNCkemgettablectxparams(void *ctx, void *provctx);\nint OSSLFUNCkemsetctxparams(void *ctx, const OSSLPARAM params[]);\nconst OSSLPARAM *OSSLFUNCkemsettablectxparams(void *ctx, void *provctx);",
    "sections": {
        "NAME": {
            "content": "provider-kem - The kem library <-> provider functions\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "#include <openssl/coredispatch.h>\n#include <openssl/corenames.h>\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 *OSSLFUNCkemnewctx(void *provctx);\nvoid OSSLFUNCkemfreectx(void *ctx);\nvoid *OSSLFUNCkemdupctx(void *ctx);\n\n/* Encapsulation */\nint OSSLFUNCkemencapsulateinit(void *ctx, void *provkey, const char *name,\nconst OSSLPARAM params[]);\nint OSSLFUNCkemencapsulate(void *ctx, unsigned char *out, sizet *outlen,\nunsigned char *secret, sizet *secretlen);\n\n/* Decapsulation */\nint OSSLFUNCkemdecapsulateinit(void *ctx, void *provkey, const char *name);\nint OSSLFUNCkemdecapsulate(void *ctx, unsigned char *out, sizet *outlen,\nconst unsigned char *in, sizet inlen);\n\n/* KEM parameters */\nint OSSLFUNCkemgetctxparams(void *ctx, OSSLPARAM params[]);\nconst OSSLPARAM *OSSLFUNCkemgettablectxparams(void *ctx, void *provctx);\nint OSSLFUNCkemsetctxparams(void *ctx, const OSSLPARAM params[]);\nconst OSSLPARAM *OSSLFUNCkemsettablectxparams(void *ctx, void *provctx);\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This documentation is primarily aimed at provider authors. See provider(7) for further\ninformation.\n\nThe asymmetric kem (OSSLOPKEM) operation enables providers to implement asymmetric kem\nalgorithms and make them available to applications via the API functions\nEVPPKEYencapsulate(3), EVPPKEYdecapsulate(3) 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\"\nOSSLFUNCkemnewctx() has these:\n\ntypedef void *(OSSLFUNCkemnewctxfn)(void *provctx);\nstatic osslinline OSSLFUNCkemnewctxfn\nOSSLFUNCkemnewctx(const OSSLDISPATCH *opf);\n\nOSSLDISPATCH arrays are indexed by numbers that are provided as macros in\nopenssl-coredispatch.h(7), as follows:\n\nOSSLFUNCkemnewctx               OSSLFUNCKEMNEWCTX\nOSSLFUNCkemfreectx              OSSLFUNCKEMFREECTX\nOSSLFUNCkemdupctx               OSSLFUNCKEMDUPCTX\n\nOSSLFUNCkemencapsulateinit     OSSLFUNCKEMENCAPSULATEINIT\nOSSLFUNCkemencapsulate          OSSLFUNCKEMENCAPSULATE\n\nOSSLFUNCkemdecapsulateinit     OSSLFUNCKEMDECAPSULATEINIT\nOSSLFUNCkemdecapsulate          OSSLFUNCKEMDECAPSULATE\n\nOSSLFUNCkemgetctxparams       OSSLFUNCKEMGETCTXPARAMS\nOSSLFUNCkemgettablectxparams  OSSLFUNCKEMGETTABLECTXPARAMS\nOSSLFUNCkemsetctxparams       OSSLFUNCKEMSETCTXPARAMS\nOSSLFUNCkemsettablectxparams  OSSLFUNCKEMSETTABLECTXPARAMS\n\nAn asymmetric kem algorithm implementation may not implement all of these functions.  In\norder to be a consistent set of functions a provider must implement OSSLFUNCkemnewctx and\nOSSLFUNCkemfreectx.  It must also implement both of OSSLFUNCkemencapsulateinit and\nOSSLFUNCkemencapsulate, or both of OSSLFUNCkemdecapsulateinit and\nOSSLFUNCkemdecapsulate.  OSSLFUNCkemgetctxparams is optional but if it is present\nthen so must OSSLFUNCkemgettablectxparams.  Similarly, OSSLFUNCkemsetctxparams is\noptional but if it is present then so must OSSLFUNCkemsettablectxparams.\n\nAn asymmetric kem algorithm must also implement some mechanism for generating, loading or\nimporting keys via the key management (OSSLOPKEYMGMT) operation.  See provider-keymgmt(7)\nfor further details.\n",
            "subsections": [
                {
                    "name": "Context Management Functions",
                    "content": "OSSLFUNCkemnewctx() should create and return a pointer to a provider side structure for\nholding context information during an asymmetric kem operation.  A pointer to this context\nwill be passed back in a number of the other asymmetric kem operation function calls.  The\nparameter provctx is the provider context generated during provider initialisation (see\nprovider(7)).\n\nOSSLFUNCkemfreectx() is passed a pointer to the provider side asymmetric kem context in\nthe ctx parameter.  This function should free any resources associated with that context.\n\nOSSLFUNCkemdupctx() should duplicate the provider side asymmetric kem context in the ctx\nparameter and return the duplicate copy.\n"
                },
                {
                    "name": "Asymmetric Key Encapsulation Functions",
                    "content": "OSSLFUNCkemencapsulateinit() initialises a context for an asymmetric encapsulation given\na provider side asymmetric kem context in the ctx parameter, a pointer to a provider key\nobject in the provkey parameter and the name of the algorithm.  The params, if not NULL,\nshould be set on the context in a manner similar to using OSSLFUNCkemsetctxparams().\nThe key object should have been previously generated, loaded or imported into the provider\nusing the key management (OSSLOPKEYMGMT) operation (see provider-keymgmt(7)>.\n\nOSSLFUNCkemencapsulate() performs the actual encapsulation itself.  A previously\ninitialised asymmetric kem context is passed in the ctx parameter.  Unless out is NULL, the\ndata to be encapsulated is internally generated, and returned into the buffer pointed to by\nthe secret parameter and the encapsulated data should also be written to the location pointed\nto by the out parameter. The length of the encapsulated data should be written to *outlen and\nthe length of the generated secret should be written to *secretlen.\n\nIf out is NULL then the maximum length of the encapsulated data should be written to *outlen,\nand the maximum length of the generated secret should be written to *secretlen.\n"
                },
                {
                    "name": "Decapsulation Functions",
                    "content": "OSSLFUNCkemdecapsulateinit() initialises a context for an asymmetric decapsulation given\na provider side asymmetric kem context in the ctx parameter, a pointer to a provider key\nobject in the provkey parameter, and a name of the algorithm.  The key object should have\nbeen previously generated, loaded or imported into the provider using the key management\n(OSSLOPKEYMGMT) operation (see provider-keymgmt(7)>.\n\nOSSLFUNCkemdecapsulate() performs the actual decapsulation itself.  A previously\ninitialised asymmetric kem context is passed in the ctx parameter.  The data to be\ndecapsulated is pointed to by the in parameter which is inlen bytes long.  Unless out is\nNULL, the decapsulated data should be written to the location pointed to by the out\nparameter.  The length of the decapsulated data should be written to *outlen.  If out is NULL\nthen the maximum length of the decapsulated data should be written to *outlen.\n"
                },
                {
                    "name": "Asymmetric Key Encapsulation Parameters",
                    "content": "See OSSLPARAM(3) for further details on the parameters structure used by the\nOSSLFUNCkemgetctxparams() and OSSLFUNCkemsetctxparams() functions.\n\nOSSLFUNCkemgetctxparams() gets asymmetric kem parameters associated with the given\nprovider side asymmetric kem context ctx and stores them in params.  Passing NULL for params\nshould return true.\n\nOSSLFUNCkemsetctxparams() sets the asymmetric kem parameters associated with the given\nprovider side asymmetric kem context ctx to params.  Any parameter settings are additional to\nany that were previously set.  Passing NULL for params should return true.\n\nNo parameters are currently recognised by built-in asymmetric kem algorithms.\n\nOSSLFUNCkemgettablectxparams() and OSSLFUNCkemsettablectxparams() get a constant\nOSSLPARAM array that describes the gettable and settable parameters, i.e. parameters that\ncan be used with OSSLFUNCkemgetctxparams() and OSSLFUNCkemsetctxparams()\nrespectively.  See OSSLPARAM(3) for the use of OSSLPARAM as parameter descriptor.\n"
                }
            ]
        },
        "RETURN VALUES": {
            "content": "OSSLFUNCkemnewctx() and OSSLFUNCkemdupctx() should return the newly created provider\nside asymmetric kem context, or NULL on failure.\n\nAll other functions should return 1 for success or 0 on error.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "provider(7)\n",
            "subsections": []
        },
        "HISTORY": {
            "content": "The provider KEM interface was introduced in OpenSSL 3.0.\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright 2020-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 <https://www.openssl.org/source/license.html>.\n\n\n\n3.0.2                                        2026-06-02                           PROVIDER-KEM(7SSL)",
            "subsections": []
        }
    },
    "summary": "provider-kem - The kem library <-> provider functions",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "provider",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/provider/7/json"
        }
    ]
}