From: Tomas Mraz Date: Wed, 31 Mar 2021 11:20:21 +0000 (+0200) Subject: provider-decoder.pod: Documentation of provider side decoder API X-Git-Tag: openssl-3.0.0-alpha15~137 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fdb5315b2d5f4529d020998cf414a1f5b8db7bbd;p=thirdparty%2Fopenssl.git provider-decoder.pod: Documentation of provider side decoder API Fixes #13949 Reviewed-by: Shane Lontis Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/14756) --- diff --git a/doc/build.info b/doc/build.info index 48730cf945a..7ac089005db 100644 --- a/doc/build.info +++ b/doc/build.info @@ -4272,6 +4272,10 @@ DEPEND[html/man7/provider-cipher.html]=man7/provider-cipher.pod GENERATE[html/man7/provider-cipher.html]=man7/provider-cipher.pod DEPEND[man/man7/provider-cipher.7]=man7/provider-cipher.pod GENERATE[man/man7/provider-cipher.7]=man7/provider-cipher.pod +DEPEND[html/man7/provider-decoder.html]=man7/provider-decoder.pod +GENERATE[html/man7/provider-decoder.html]=man7/provider-decoder.pod +DEPEND[man/man7/provider-decoder.7]=man7/provider-decoder.pod +GENERATE[man/man7/provider-decoder.7]=man7/provider-decoder.pod DEPEND[html/man7/provider-digest.html]=man7/provider-digest.pod GENERATE[html/man7/provider-digest.html]=man7/provider-digest.pod DEPEND[man/man7/provider-digest.7]=man7/provider-digest.pod @@ -4419,6 +4423,7 @@ html/man7/property.html \ html/man7/provider-asym_cipher.html \ html/man7/provider-base.html \ html/man7/provider-cipher.html \ +html/man7/provider-decoder.html \ html/man7/provider-digest.html \ html/man7/provider-encoder.html \ html/man7/provider-kdf.html \ @@ -4521,6 +4526,7 @@ man/man7/property.7 \ man/man7/provider-asym_cipher.7 \ man/man7/provider-base.7 \ man/man7/provider-cipher.7 \ +man/man7/provider-decoder.7 \ man/man7/provider-digest.7 \ man/man7/provider-encoder.7 \ man/man7/provider-kdf.7 \ diff --git a/doc/man7/provider-decoder.pod b/doc/man7/provider-decoder.pod new file mode 100644 index 00000000000..73f653e0637 --- /dev/null +++ b/doc/man7/provider-decoder.pod @@ -0,0 +1,337 @@ +=pod + +=head1 NAME + +provider-decoder - The OSSL_DECODER library E-E provider functions + +=head1 SYNOPSIS + + #include + + /* + * None of these are actual functions, but are displayed like this for + * the function signatures for functions that are offered as function + * pointers in OSSL_DISPATCH arrays. + */ + + /* Decoder parameter accessor and descriptor */ + const OSSL_PARAM *OSSL_FUNC_decoder_gettable_params(void *provctx); + int OSSL_FUNC_decoder_get_params(OSSL_PARAM params[]); + + /* Functions to construct / destruct / manipulate the decoder context */ + void *OSSL_FUNC_decoder_newctx(void *provctx); + void OSSL_FUNC_decoder_freectx(void *ctx); + const OSSL_PARAM *OSSL_FUNC_decoder_settable_ctx_params(void *provctx); + int OSSL_FUNC_decoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]); + + /* Functions to check selection support */ + int OSSL_FUNC_decoder_does_selection(void *provctx, int selection); + + /* Functions to decode object data */ + int OSSL_FUNC_decoder_decode(void *ctx, OSSL_CORE_BIO *in, + int selection, + OSSL_CALLBACK *data_cb, void *data_cbarg, + OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); + + /* Functions to export a decoded object */ + void *OSSL_FUNC_decoder_export_object(void *ctx, + const void *objref, size_t objref_sz, + OSSL_CALLBACK *export_cb, + void *export_cbarg); + +=head1 DESCRIPTION + +I + +The DECODER operation is a generic method to create a provider-native +object reference or intermediate decoded data from an encoded form +read from the given B. If the caller wants to decode +data from memory, it should provide a L B. The decoded +data or object reference is passed along with eventual metadata +to the I as B parameters. + +The decoder doesn't need to know more about the B +pointer than being able to pass it to the appropriate BIO upcalls (see +L). + +The DECODER implementation may be part of a chain, where data is +passed from one to the next. For example, there may be an +implementation to decode an object from PEM to DER, and another one +that decodes DER to a provider-native object. + +The last decoding step in the decoding chain is usually supposed to create +a provider-native object referenced by an object reference. To import +that object into a different provider the OSSL_FUNC_decoder_export_object() +can be called as the final step of the decoding process. + +All "functions" mentioned here are passed as function pointers between +F and the provider in B arrays via +B arrays that are returned by the provider's +provider_query_operation() function +(see L). + +All these "functions" have a corresponding function type definition +named B, and a helper function to retrieve the +function pointer from an B element named +B. +For example, the "function" OSSL_FUNC_decoder_decode() has these: + + typedef int + (OSSL_FUNC_decoder_decode_fn)(void *ctx, OSSL_CORE_BIO *in, + int selection, + OSSL_CALLBACK *data_cb, void *data_cbarg, + OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); + static ossl_inline OSSL_FUNC_decoder_decode_fn + OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf); + +B arrays are indexed by numbers that are provided as +macros in L, as follows: + + OSSL_FUNC_decoder_get_params OSSL_FUNC_DECODER_GET_PARAMS + OSSL_FUNC_decoder_gettable_params OSSL_FUNC_DECODER_GETTABLE_PARAMS + + OSSL_FUNC_decoder_newctx OSSL_FUNC_DECODER_NEWCTX + OSSL_FUNC_decoder_freectx OSSL_FUNC_DECODER_FREECTX + OSSL_FUNC_decoder_set_ctx_params OSSL_FUNC_DECODER_SET_CTX_PARAMS + OSSL_FUNC_decoder_settable_ctx_params OSSL_FUNC_DECODER_SETTABLE_CTX_PARAMS + + OSSL_FUNC_decoder_does_selection OSSL_FUNC_DECODER_DOES_SELECTION + + OSSL_FUNC_decoder_decode OSSL_FUNC_DECODER_DECODE + + OSSL_FUNC_decoder_export_object OSSL_FUNC_DECODER_EXPORT_OBJECT + +=head2 Names and properties + +The name of an implementation should match the target type of object +it decodes. For example, an implementation that decodes an RSA key +should be named "RSA". Likewise, an implementation that decodes DER data +from PEM input should be named "DER". + +Properties can be used to further specify details about an implementation: + +=over 4 + +=item input + +This property is used to specify what format of input the implementation +can decode. OpenSSL providers recognize the following input types: + +=over 4 + +=item pem + +An implementation with that input type decodes PEM formatted data. + +=item der + +An implementation with that input type decodes DER formatted data. + +=item msblob + +An implementation with that input type decodes MSBLOB formatted data. + +=item pvk + +An implementation with that input type decodes PVK formatted data. + +=back + +=item structure + +This property is used to specify the structure that the decoded data is +expected to have. An example could be C, to specify explicitly that +the object to be decoded (presumably an asymmetric key pair, in this case) +is wrapped in a PKCS#8 structure. + +=back + +The possible values of both these properties is open ended. A provider may +very well specify input types and structures that libcrypto doesn't know +anything about. + +=head2 Subset selections + +Sometimes, an object has more than one subset of data that is interesting to +treat separately or together. It's possible to specify what subsets are to +be decoded, with a set of bits I that are passed in an B. + +This set of bits depend entirely on what kind of provider-side object is +to be decoded. For example, those bits are assumed to be the same as those +used with L (see L) when +the object is an asymmetric keypair - e.g., B +if the object to be decoded is supposed to contain private key components. + +OSSL_FUNC_decoder_does_selection() should tell if a particular implementation +supports any of the combinations given by I. + +=head2 Context functions + +OSSL_FUNC_decoder_newctx() returns a context to be used with the rest of +the functions. + +OSSL_FUNC_decoder_freectx() frees the given I as created by +OSSL_FUNC_decoder_newctx(). + +OSSL_FUNC_decoder_set_ctx_params() sets context data according to parameters +from I that it recognises. Unrecognised parameters should be +ignored. +Passing NULL for I should return true. + +OSSL_FUNC_decoder_settable_ctx_params() returns a constant B +array describing the parameters that OSSL_FUNC_decoder_set_ctx_params() +can handle. + +See L for further details on the parameters structure used by +OSSL_FUNC_decoder_set_ctx_params() and OSSL_FUNC_decoder_settable_ctx_params(). + +=head2 Export function + +When a provider-native object is created by a decoder it would be unsuitable +for direct use with a foreign provider. The export function allows for +exporting the object into that foreign provider if the foreign provider +supports the type of the object and provides an import function. + +OSSL_FUNC_decoder_export_object() should export the object of size I +referenced by I as an B array and pass that into the +I as well as the given I. + +=head2 Decoding functions + +OSSL_FUNC_decoder_decode() should decode the data as read from +the B I to produce decoded data or an object to be +passed as reference in an B array along with possible other +metadata that was decoded from the input. This B array is +then passed to the I callback. The I bits, +if relevant, should determine what the input data should contain. +The decoding functions also take an B function +pointer along with a pointer to application data I, which should be +used when a pass phrase prompt is needed. + +=head2 Decoder parameters + +The decoder implementation itself has parameters that can be used to +determine how it fits in a chain of decoders: + +=over 4 + +=item "input-type" (B) + +This is used to specify the input type for a decoder implementation. + +This parameter is I. + +Input types currently recognized by built-in decoders: + +=over 4 + +=item "DER" + +ASN.1 DER encoded binary data + +=item "PEM" + +Base64 encoded data with PEM headers + +=item "MSBLOB" + +Private or public key encoding according to Microsoft specification + +=item "PVK" + +Encrypted private key encoding according to Microsoft specification + +=back + +=for comment If we had functionality to get the value of a specific property +in a set of properties, it would be possible to determine the input type +from the C property. + +=item "input-structure" (B) + +This is used to specify the outermost input structure for a decoder +implementation. + +For example, an input of type "DER" for a key pair could be structured +using PKCS#8, or a key type specific structure, such as PKCS#1 for RSA +keys. + +This parameter is I. + +Input structures currently recognized by built-in decoders: + +=over 4 + +=item "type-specific" + +Type specific structure. + +=item "PKCS8" + +Structure according to the PKCS#8 specification. + +=item "SubjectPublicKeyInfo" + +Encoding of public keys according to the Subject Public Key Info of RFC 5280. + +=back + +=for comment If we had functionality to get the value of a specific property +in a set of properties, it would be possible to determine the input +structure from the C property. + +=back + +=head2 Decoder operation parameters + +There are currently no operation parameters currently recognised by the +built-in decoders. + +Parameters currently recognised by the built-in pass phrase callback: + +=over 4 + +=item "info" (B) + +A string of information that will become part of the pass phrase +prompt. This could be used to give the user information on what kind +of object it's being prompted for. + +=back + +=head1 RETURN VALUES + +OSSL_FUNC_decoder_newctx() returns a pointer to a context, or NULL on +failure. + +OSSL_FUNC_decoder_set_ctx_params() returns 1, unless a recognised +parameter was invalid or caused an error, for which 0 is returned. + +OSSL_FUNC_decoder_settable_ctx_params() returns a pointer to an array of +constant B elements. + +OSSL_FUNC_decoder_does_selection() returns 1 if the decoder implementation +supports any of the I bits, otherwise 0. + +OSSL_FUNC_decoder_decode() returns 1 on success, or 0 on failure. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +The DECODER interface was introduced in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut