diff options
author | Tomas Mraz <tomas@openssl.org> | 2021-03-31 13:20:21 +0200 |
---|---|---|
committer | Tomas Mraz <tomas@openssl.org> | 2021-04-09 10:32:00 +0200 |
commit | fdb5315b2d5f4529d020998cf414a1f5b8db7bbd (patch) | |
tree | 503d2254caf6a615f867d47863d48223623b0dff | |
parent | 3201abeb46eb8c8bfa3d7a9242d0e8a9d7b2539a (diff) |
provider-decoder.pod: Documentation of provider side decoder API
Fixes #13949
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14756)
-rw-r--r-- | doc/build.info | 6 | ||||
-rw-r--r-- | doc/man7/provider-decoder.pod | 337 |
2 files changed, 343 insertions, 0 deletions
diff --git a/doc/build.info b/doc/build.info index 48730cf945..7ac089005d 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 0000000000..73f653e063 --- /dev/null +++ b/doc/man7/provider-decoder.pod @@ -0,0 +1,337 @@ +=pod + +=head1 NAME + +provider-decoder - The OSSL_DECODER library E<lt>-E<gt> provider functions + +=head1 SYNOPSIS + + #include <openssl/core_dispatch.h> + + /* + * 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 term "decode" is used throughout this manual. This includes but is +not limited to deserialization as individual decoders can also do +decoding into intermediate data formats.> + +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<OSSL_CORE_BIO>. If the caller wants to decode +data from memory, it should provide a L<BIO_s_mem(3)> B<BIO>. The decoded +data or object reference is passed along with eventual metadata +to the I<metadata_cb> as B<OSSL_PARAM> parameters. + +The decoder doesn't need to know more about the B<OSSL_CORE_BIO> +pointer than being able to pass it to the appropriate BIO upcalls (see +L<provider-base(7)/Core functions>). + +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<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via +B<OSSL_ALGORITHM> arrays that are returned by the provider's +provider_query_operation() function +(see L<provider-base(7)/Provider Functions>). + +All these "functions" have a corresponding function type definition +named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the +function pointer from an B<OSSL_DISPATCH> element named +B<OSSL_FUNC_{name}>. +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<OSSL_DISPATCH> arrays are indexed by numbers that are provided as +macros in L<openssl-core_dispatch.h(7)>, 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<pkcs8>, 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<selection> that are passed in an B<int>. + +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<provider-keymgmt(7)> (see L<provider-keymgmt(7)/Key Objects>) when +the object is an asymmetric keypair - e.g., B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> +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<selection>. + +=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<ctx> as created by +OSSL_FUNC_decoder_newctx(). + +OSSL_FUNC_decoder_set_ctx_params() sets context data according to parameters +from I<params> that it recognises. Unrecognised parameters should be +ignored. +Passing NULL for I<params> should return true. + +OSSL_FUNC_decoder_settable_ctx_params() returns a constant B<OSSL_PARAM> +array describing the parameters that OSSL_FUNC_decoder_set_ctx_params() +can handle. + +See L<OSSL_PARAM(3)> 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<objref_sz> +referenced by I<objref> as an B<OSSL_PARAM> array and pass that into the +I<export_cb> as well as the given I<export_cbarg>. + +=head2 Decoding functions + +OSSL_FUNC_decoder_decode() should decode the data as read from +the B<OSSL_CORE_BIO> I<in> to produce decoded data or an object to be +passed as reference in an B<OSSL_PARAM> array along with possible other +metadata that was decoded from the input. This B<OSSL_PARAM> array is +then passed to the I<data_cb> callback. The I<selection> bits, +if relevant, should determine what the input data should contain. +The decoding functions also take an B<OSSL_PASSPHRASE_CALLBACK> function +pointer along with a pointer to application data I<cbarg>, 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<OSSL_DECODER_PARAM_INPUT_TYPE>) <UTF8 string> + +This is used to specify the input type for a decoder implementation. + +This parameter is I<mandatory>. + +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<input> property. + +=item "input-structure" (B<OSSL_ENCODER_PARAM_INPUT_STRUCTURE>) <UTF8 string> + +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<optional>. + +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<structure> 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<OSSL_PASSPHRASE_PARAM_INFO>) <UTF8 string> + +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<OSSL_PARAM> elements. + +OSSL_FUNC_decoder_does_selection() returns 1 if the decoder implementation +supports any of the I<selection> bits, otherwise 0. + +OSSL_FUNC_decoder_decode() returns 1 on success, or 0 on failure. + +=head1 SEE ALSO + +L<provider(7)> + +=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<https://www.openssl.org/source/license.html>. + +=cut |