{ "content": [ { "type": "text", "text": "# PROVIDER-KEM (info)\n\n## NAME\n\nprovider-kem - The kem library <-> provider functions\n\n## SYNOPSIS\n\n#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 *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);\n\n## DESCRIPTION\n\nThis documentation is primarily aimed at provider authors. See\nprovider(7) for further information.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **RETURN VALUES**\n- **SEE ALSO**\n- **HISTORY**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "PROVIDER-KEM", "section": "", "mode": "info", "summary": "provider-kem - The kem library <-> provider functions", "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 *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);", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "provider", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/provider/7/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 31, "subsections": [] }, { "name": "DESCRIPTION", "lines": 136, "subsections": [] }, { "name": "RETURN VALUES", "lines": 5, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "HISTORY", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "provider-kem - The kem 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 *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\nprovider(7) for further information.\n\nThe asymmetric kem (OSSLOPKEM) operation enables providers to\nimplement asymmetric kem algorithms and make them available to\napplications via the API functions EVPPKEYencapsulate(3),\nEVPPKEYdecapsulate(3) and other related functions.\n\nAll \"functions\" mentioned here are passed as function pointers between\nlibcrypto and the provider in OSSLDISPATCH arrays via OSSLALGORITHM\narrays that are returned by the provider's providerqueryoperation()\nfunction (see \"Provider Functions\" in provider-base(7)).\n\nAll these \"functions\" have a corresponding function type definition\nnamed OSSLFUNC{name}fn, and a helper function to retrieve the\nfunction pointer from an OSSLDISPATCH element named OSSLFUNC{name}.\nFor example, the \"function\" OSSLFUNCkemnewctx() 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\nin openssl-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\nthese functions. In order to be a consistent set of functions a\nprovider must implement OSSLFUNCkemnewctx and OSSLFUNCkemfreectx.\nIt must also implement both of OSSLFUNCkemencapsulateinit and\nOSSLFUNCkemencapsulate, or both of OSSLFUNCkemdecapsulateinit\nand OSSLFUNCkemdecapsulate. OSSLFUNCkemgetctxparams is\noptional but if it is present then so must\nOSSLFUNCkemgettablectxparams. Similarly,\nOSSLFUNCkemsetctxparams is optional but if it is present then so\nmust OSSLFUNCkemsettablectxparams.\n\nAn asymmetric kem algorithm must also implement some mechanism for\ngenerating, loading or importing keys via the key management\n(OSSLOPKEYMGMT) operation. See provider-keymgmt(7) for further\ndetails.\n\nContext Management Functions\nOSSLFUNCkemnewctx() should create and return a pointer to a provider\nside structure for holding context information during an asymmetric kem\noperation. A pointer to this context will be passed back in a number\nof the other asymmetric kem operation function calls. The parameter\nprovctx is the provider context generated during provider\ninitialisation (see provider(7)).\n\nOSSLFUNCkemfreectx() is passed a pointer to the provider side\nasymmetric kem context in the ctx parameter. This function should free\nany resources associated with that context.\n\nOSSLFUNCkemdupctx() should duplicate the provider side asymmetric\nkem context in the ctx parameter and return the duplicate copy.\n\nAsymmetric Key Encapsulation Functions\nOSSLFUNCkemencapsulateinit() initialises a context for an\nasymmetric encapsulation given a provider side asymmetric kem context\nin the ctx parameter, a pointer to a provider key object in the provkey\nparameter and the name of the algorithm. The params, if not NULL,\nshould be set on the context in a manner similar to using\nOSSLFUNCkemsetctxparams(). The key object should have been\npreviously generated, loaded or imported into the provider using the\nkey management (OSSLOPKEYMGMT) operation (see provider-keymgmt(7)>.\n\nOSSLFUNCkemencapsulate() performs the actual encapsulation itself.\nA previously initialised asymmetric kem context is passed in the ctx\nparameter. Unless out is NULL, the data to be encapsulated is\ninternally generated, and returned into the buffer pointed to by the\nsecret parameter and the encapsulated data should also be written to\nthe location pointed to by the out parameter. The length of the\nencapsulated data should be written to *outlen and the length of the\ngenerated secret should be written to *secretlen.\n\nIf out is NULL then the maximum length of the encapsulated data should\nbe written to *outlen, and the maximum length of the generated secret\nshould be written to *secretlen.\n\nDecapsulation Functions\nOSSLFUNCkemdecapsulateinit() initialises a context for an\nasymmetric decapsulation given a provider side asymmetric kem context\nin the ctx parameter, a pointer to a provider key object in the provkey\nparameter, and a name of the algorithm. The key object should have\nbeen previously generated, loaded or imported into the provider using\nthe key management (OSSLOPKEYMGMT) operation (see\nprovider-keymgmt(7)>.\n\nOSSLFUNCkemdecapsulate() performs the actual decapsulation itself.\nA previously initialised asymmetric kem context is passed in the ctx\nparameter. The data to be decapsulated is pointed to by the in\nparameter which is inlen bytes long. Unless out is NULL, the\ndecapsulated data should be written to the location pointed to by the\nout parameter. The length of the decapsulated data should be written\nto *outlen. If out is NULL then the maximum length of the decapsulated\ndata should be written to *outlen.\n\nAsymmetric Key Encapsulation Parameters\nSee OSSLPARAM(3) for further details on the parameters structure used\nby the OSSLFUNCkemgetctxparams() and\nOSSLFUNCkemsetctxparams() functions.\n\nOSSLFUNCkemgetctxparams() gets asymmetric kem parameters\nassociated with the given provider side asymmetric kem context ctx and\nstores them in params. Passing NULL for params should return true.\n\nOSSLFUNCkemsetctxparams() sets the asymmetric kem parameters\nassociated with the given provider side asymmetric kem context ctx to\nparams. Any parameter settings are additional to any that were\npreviously set. Passing NULL for params should return true.\n\nNo parameters are currently recognised by built-in asymmetric kem\nalgorithms.\n\nOSSLFUNCkemgettablectxparams() and\nOSSLFUNCkemsettablectxparams() get a constant OSSLPARAM array\nthat describes the gettable and settable parameters, i.e. parameters\nthat can be used with OSSLFUNCkemgetctxparams() and\nOSSLFUNCkemsetctxparams() respectively. See OSSLPARAM(3) for the\nuse of OSSLPARAM as parameter descriptor.\n", "subsections": [] }, "RETURN VALUES": { "content": "OSSLFUNCkemnewctx() and OSSLFUNCkemdupctx() should return the\nnewly created provider side 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\nthis file except in compliance with the License. You can obtain a copy\nin the file LICENSE in the source distribution or at\n.\n\n3.0.2 2026-06-02 PROVIDER-KEM(7SSL)", "subsections": [] } } } }