{
    "content": [
        {
            "type": "text",
            "text": "# provider-decoder(7ssl) (man)\n\n**Summary:** provider-decoder - The OSSLDECODER library <-> provider functions\n\n**Synopsis:** #include <openssl/coredispatch.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/* Decoder parameter accessor and descriptor */\nconst OSSLPARAM *OSSLFUNCdecodergettableparams(void *provctx);\nint OSSLFUNCdecodergetparams(OSSLPARAM params[]);\n/* Functions to construct / destruct / manipulate the decoder context */\nvoid *OSSLFUNCdecodernewctx(void *provctx);\nvoid OSSLFUNCdecoderfreectx(void *ctx);\nconst OSSLPARAM *OSSLFUNCdecodersettablectxparams(void *provctx);\nint OSSLFUNCdecodersetctxparams(void *ctx, const OSSLPARAM params[]);\n/* Functions to check selection support */\nint OSSLFUNCdecoderdoesselection(void *provctx, int selection);\n/* Functions to decode object data */\nint OSSLFUNCdecoderdecode(void *ctx, OSSLCOREBIO *in,\nint selection,\nOSSLCALLBACK *datacb, void *datacbarg,\nOSSLPASSPHRASECALLBACK *cb, void *cbarg);\n/* Functions to export a decoded object */\nvoid *OSSLFUNCdecoderexportobject(void *ctx,\nconst void *objref, sizet objrefsz,\nOSSLCALLBACK *exportcb,\nvoid *exportcbarg);\n\n## See Also\n\n- provider(7)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (33 lines)\n- **DESCRIPTION** (55 lines) — 6 subsections\n  - Names and properties (41 lines)\n  - Subset selections (13 lines)\n  - Context functions (14 lines)\n  - Export function (9 lines)\n  - Decoding functions (27 lines)\n  - Decoder operation parameters (8 lines)\n- **RETURN VALUES** (14 lines)\n- **SEE ALSO** (2 lines)\n- **HISTORY** (2 lines)\n- **COPYRIGHT** (9 lines)\n\n## Full Content\n\n### NAME\n\nprovider-decoder - The OSSLDECODER library <-> provider functions\n\n### SYNOPSIS\n\n#include <openssl/coredispatch.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/* Decoder parameter accessor and descriptor */\nconst OSSLPARAM *OSSLFUNCdecodergettableparams(void *provctx);\nint OSSLFUNCdecodergetparams(OSSLPARAM params[]);\n\n/* Functions to construct / destruct / manipulate the decoder context */\nvoid *OSSLFUNCdecodernewctx(void *provctx);\nvoid OSSLFUNCdecoderfreectx(void *ctx);\nconst OSSLPARAM *OSSLFUNCdecodersettablectxparams(void *provctx);\nint OSSLFUNCdecodersetctxparams(void *ctx, const OSSLPARAM params[]);\n\n/* Functions to check selection support */\nint OSSLFUNCdecoderdoesselection(void *provctx, int selection);\n\n/* Functions to decode object data */\nint OSSLFUNCdecoderdecode(void *ctx, OSSLCOREBIO *in,\nint selection,\nOSSLCALLBACK *datacb, void *datacbarg,\nOSSLPASSPHRASECALLBACK *cb, void *cbarg);\n\n/* Functions to export a decoded object */\nvoid *OSSLFUNCdecoderexportobject(void *ctx,\nconst void *objref, sizet objrefsz,\nOSSLCALLBACK *exportcb,\nvoid *exportcbarg);\n\n### DESCRIPTION\n\nThe term \"decode\" is used throughout this manual.  This includes but is not limited to\ndeserialization as individual decoders can also do decoding into intermediate data formats.\n\nThe DECODER operation is a generic method to create a provider-native object reference or\nintermediate decoded data from an encoded form read from the given OSSLCOREBIO. If the\ncaller wants to decode data from memory, it should provide a BIOsmem(3) BIO. The decoded\ndata or object reference is passed along with eventual metadata to the metadatacb as\nOSSLPARAM parameters.\n\nThe decoder doesn't need to know more about the OSSLCOREBIO pointer than being able to pass\nit to the appropriate BIO upcalls (see \"Core functions\" in provider-base(7)).\n\nThe DECODER implementation may be part of a chain, where data is passed from one to the next.\nFor example, there may be an implementation to decode an object from PEM to DER, and another\none that decodes DER to a provider-native object.\n\nThe last decoding step in the decoding chain is usually supposed to create a provider-native\nobject referenced by an object reference. To import that object into a different provider the\nOSSLFUNCdecoderexportobject() can be called as the final step of the decoding process.\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\"\nOSSLFUNCdecoderdecode() has these:\n\ntypedef int\n(OSSLFUNCdecoderdecodefn)(void *ctx, OSSLCOREBIO *in,\nint selection,\nOSSLCALLBACK *datacb, void *datacbarg,\nOSSLPASSPHRASECALLBACK *cb, void *cbarg);\nstatic osslinline OSSLFUNCdecoderdecodefn\nOSSLFUNCdecoderdecode(const OSSLDISPATCH *opf);\n\nOSSLDISPATCH arrays are indexed by numbers that are provided as macros in\nopenssl-coredispatch.h(7), as follows:\n\nOSSLFUNCdecodergetparams          OSSLFUNCDECODERGETPARAMS\nOSSLFUNCdecodergettableparams     OSSLFUNCDECODERGETTABLEPARAMS\n\nOSSLFUNCdecodernewctx              OSSLFUNCDECODERNEWCTX\nOSSLFUNCdecoderfreectx             OSSLFUNCDECODERFREECTX\nOSSLFUNCdecodersetctxparams      OSSLFUNCDECODERSETCTXPARAMS\nOSSLFUNCdecodersettablectxparams OSSLFUNCDECODERSETTABLECTXPARAMS\n\nOSSLFUNCdecoderdoesselection      OSSLFUNCDECODERDOESSELECTION\n\nOSSLFUNCdecoderdecode              OSSLFUNCDECODERDECODE\n\nOSSLFUNCdecoderexportobject       OSSLFUNCDECODEREXPORTOBJECT\n\n#### Names and properties\n\nThe name of an implementation should match the target type of object it decodes. For example,\nan implementation that decodes an RSA key should be named \"RSA\". Likewise, an implementation\nthat decodes DER data from PEM input should be named \"DER\".\n\nProperties can be used to further specify details about an implementation:\n\ninput\nThis property is used to specify what format of input the implementation can decode.\n\nThis property is mandatory.\n\nOpenSSL providers recognize the following input types:\n\npem An implementation with that input type decodes PEM formatted data.\n\nder An implementation with that input type decodes DER formatted data.\n\nmsblob\nAn implementation with that input type decodes MSBLOB formatted data.\n\npvk An implementation with that input type decodes PVK formatted data.\n\nstructure\nThis property is used to specify the structure that the decoded data is expected to have.\n\nThis property is optional.\n\nStructures currently recognised by built-in decoders:\n\n\"type-specific\"\nType specific structure.\n\n\"pkcs8\"\nStructure according to the PKCS#8 specification.\n\n\"SubjectPublicKeyInfo\"\nEncoding of public keys according to the Subject Public Key Info of RFC 5280.\n\nThe possible values of both these properties is open ended.  A provider may very well specify\ninput types and structures that libcrypto doesn't know anything about.\n\n#### Subset selections\n\nSometimes, an object has more than one subset of data that is interesting to treat separately\nor together.  It's possible to specify what subsets are to be decoded, with a set of bits\nselection that are passed in an int.\n\nThis set of bits depend entirely on what kind of provider-side object is to be decoded.  For\nexample, those bits are assumed to be the same as those used with provider-keymgmt(7) (see\n\"Key Objects\" in provider-keymgmt(7)) when the object is an asymmetric keypair - e.g.,\nOSSLKEYMGMTSELECTPRIVATEKEY if the object to be decoded is supposed to contain private\nkey components.\n\nOSSLFUNCdecoderdoesselection() should tell if a particular implementation supports any of\nthe combinations given by selection.\n\n#### Context functions\n\nOSSLFUNCdecodernewctx() returns a context to be used with the rest of the functions.\n\nOSSLFUNCdecoderfreectx() frees the given ctx as created by OSSLFUNCdecodernewctx().\n\nOSSLFUNCdecodersetctxparams() sets context data according to parameters from params that\nit recognises.  Unrecognised parameters should be ignored.  Passing NULL for params should\nreturn true.\n\nOSSLFUNCdecodersettablectxparams() returns a constant OSSLPARAM array describing the\nparameters that OSSLFUNCdecodersetctxparams() can handle.\n\nSee OSSLPARAM(3) for further details on the parameters structure used by\nOSSLFUNCdecodersetctxparams() and OSSLFUNCdecodersettablectxparams().\n\n#### Export function\n\nWhen a provider-native object is created by a decoder it would be unsuitable for direct use\nwith a foreign provider. The export function allows for exporting the object into that\nforeign provider if the foreign provider supports the type of the object and provides an\nimport function.\n\nOSSLFUNCdecoderexportobject() should export the object of size objrefsz referenced by\nobjref as an OSSLPARAM array and pass that into the exportcb as well as the given\nexportcbarg.\n\n#### Decoding functions\n\nOSSLFUNCdecoderdecode() should decode the data as read from the OSSLCOREBIO in to\nproduce decoded data or an object to be passed as reference in an OSSLPARAM array along with\npossible other metadata that was decoded from the input. This OSSLPARAM array is then passed\nto the datacb callback.  The selection bits, if relevant, should determine what the input\ndata should contain.  The decoding functions also take an OSSLPASSPHRASECALLBACK function\npointer along with a pointer to application data cbarg, which should be used when a pass\nphrase prompt is needed.\n\nIt's important to understand that the return value from this function is interpreted as\nfollows:\n\nTrue (1)\nThis means \"carry on the decoding process\", and is meaningful even though this function\ncouldn't decode the input into anything, because there may be another decoder\nimplementation that can decode it into something.\n\nThe datacb callback should never be called when this function can't decode the input\ninto anything.\n\nFalse (0)\nThis means \"stop the decoding process\", and is meaningful when the input could be decoded\ninto some sort of object that this function understands, but further treatment of that\nobject results into errors that won't be possible for some other decoder implementation\nto get a different result.\n\nThe conditions to stop the decoding process are at the discretion of the implementation.\n\n#### Decoder operation parameters\n\nThere are currently no operation parameters currently recognised by the built-in decoders.\n\nParameters currently recognised by the built-in pass phrase callback:\n\n\"info\" (OSSLPASSPHRASEPARAMINFO) <UTF8 string>\nA string of information that will become part of the pass phrase prompt.  This could be\nused to give the user information on what kind of object it's being prompted for.\n\n### RETURN VALUES\n\nOSSLFUNCdecodernewctx() returns a pointer to a context, or NULL on failure.\n\nOSSLFUNCdecodersetctxparams() returns 1, unless a recognised parameter was invalid or\ncaused an error, for which 0 is returned.\n\nOSSLFUNCdecodersettablectxparams() returns a pointer to an array of constant OSSLPARAM\nelements.\n\nOSSLFUNCdecoderdoesselection() returns 1 if the decoder implementation supports any of\nthe selection bits, otherwise 0.\n\nOSSLFUNCdecoderdecode() returns 1 to signal that the decoding process should continue, or\n0 to signal that it should stop.\n\n### SEE ALSO\n\nprovider(7)\n\n### HISTORY\n\nThe DECODER interface was introduced in OpenSSL 3.0.\n\n### COPYRIGHT\n\nCopyright 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 <https://www.openssl.org/source/license.html>.\n\n\n\n3.0.2                                        2026-04-07                       PROVIDER-DECODER(7SSL)\n\n"
        }
    ],
    "structuredContent": {
        "command": "provider-decoder",
        "section": "7ssl",
        "mode": "man",
        "summary": "provider-decoder - The OSSLDECODER library <-> provider functions",
        "synopsis": "#include <openssl/coredispatch.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/* Decoder parameter accessor and descriptor */\nconst OSSLPARAM *OSSLFUNCdecodergettableparams(void *provctx);\nint OSSLFUNCdecodergetparams(OSSLPARAM params[]);\n/* Functions to construct / destruct / manipulate the decoder context */\nvoid *OSSLFUNCdecodernewctx(void *provctx);\nvoid OSSLFUNCdecoderfreectx(void *ctx);\nconst OSSLPARAM *OSSLFUNCdecodersettablectxparams(void *provctx);\nint OSSLFUNCdecodersetctxparams(void *ctx, const OSSLPARAM params[]);\n/* Functions to check selection support */\nint OSSLFUNCdecoderdoesselection(void *provctx, int selection);\n/* Functions to decode object data */\nint OSSLFUNCdecoderdecode(void *ctx, OSSLCOREBIO *in,\nint selection,\nOSSLCALLBACK *datacb, void *datacbarg,\nOSSLPASSPHRASECALLBACK *cb, void *cbarg);\n/* Functions to export a decoded object */\nvoid *OSSLFUNCdecoderexportobject(void *ctx,\nconst void *objref, sizet objrefsz,\nOSSLCALLBACK *exportcb,\nvoid *exportcbarg);",
        "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": 33,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 55,
                "subsections": [
                    {
                        "name": "Names and properties",
                        "lines": 41
                    },
                    {
                        "name": "Subset selections",
                        "lines": 13
                    },
                    {
                        "name": "Context functions",
                        "lines": 14
                    },
                    {
                        "name": "Export function",
                        "lines": 9
                    },
                    {
                        "name": "Decoding functions",
                        "lines": 27
                    },
                    {
                        "name": "Decoder operation parameters",
                        "lines": 8
                    }
                ]
            },
            {
                "name": "RETURN VALUES",
                "lines": 14,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "HISTORY",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 9,
                "subsections": []
            }
        ]
    }
}