NAME¶

OSSL_DECODER_CTX, OSSL_DECODER_CTX_new, OSSL_DECODER_settable_ctx_params, OSSL_DECODER_CTX_set_params, OSSL_DECODER_CTX_free, OSSL_DECODER_CTX_set_selection, OSSL_DECODER_CTX_set_input_type, OSSL_DECODER_CTX_set_input_structure, OSSL_DECODER_CTX_add_decoder, OSSL_DECODER_CTX_add_extra, OSSL_DECODER_CTX_get_num_decoders, OSSL_DECODER_INSTANCE, OSSL_DECODER_CONSTRUCT, OSSL_DECODER_CLEANUP, OSSL_DECODER_CTX_set_construct, OSSL_DECODER_CTX_set_construct_data, OSSL_DECODER_CTX_set_cleanup, OSSL_DECODER_CTX_get_construct, OSSL_DECODER_CTX_get_construct_data, OSSL_DECODER_CTX_get_cleanup, OSSL_DECODER_export, OSSL_DECODER_INSTANCE_get_decoder, OSSL_DECODER_INSTANCE_get_decoder_ctx, OSSL_DECODER_INSTANCE_get_input_type, OSSL_DECODER_INSTANCE_get_input_structure - Decoder context routines

SYNOPSIS¶

 #include <openssl/decoder.h>
 typedef struct ossl_decoder_ctx_st OSSL_DECODER_CTX;
 OSSL_DECODER_CTX *OSSL_DECODER_CTX_new(void);
 const OSSL_PARAM *OSSL_DECODER_settable_ctx_params(OSSL_DECODER *decoder);
 int OSSL_DECODER_CTX_set_params(OSSL_DECODER_CTX *ctx,
                                 const OSSL_PARAM params[]);
 void OSSL_DECODER_CTX_free(OSSL_DECODER_CTX *ctx);
 int OSSL_DECODER_CTX_set_selection(OSSL_DECODER_CTX *ctx, int selection);
 int OSSL_DECODER_CTX_set_input_type(OSSL_DECODER_CTX *ctx,
                                     const char *input_type);
 int OSSL_DECODER_CTX_set_input_structure(OSSL_DECODER_CTX *ctx,
                                          const char *input_structure);
 int OSSL_DECODER_CTX_add_decoder(OSSL_DECODER_CTX *ctx, OSSL_DECODER *decoder);
 int OSSL_DECODER_CTX_add_extra(OSSL_DECODER_CTX *ctx,
                                OSSL_LIB_CTX *libctx,
                                const char *propq);
 int OSSL_DECODER_CTX_get_num_decoders(OSSL_DECODER_CTX *ctx);
 typedef struct ossl_decoder_instance_st OSSL_DECODER_INSTANCE;
 OSSL_DECODER *
 OSSL_DECODER_INSTANCE_get_decoder(OSSL_DECODER_INSTANCE *decoder_inst);
 void *
 OSSL_DECODER_INSTANCE_get_decoder_ctx(OSSL_DECODER_INSTANCE *decoder_inst);
 const char *
 OSSL_DECODER_INSTANCE_get_input_type(OSSL_DECODER_INSTANCE *decoder_inst);
 OSSL_DECODER_INSTANCE_get_input_structure(OSSL_DECODER_INSTANCE *decoder_inst,
                                           int *was_set);
 typedef int OSSL_DECODER_CONSTRUCT(OSSL_DECODER_INSTANCE *decoder_inst,
                                    const OSSL_PARAM *object,
                                    void *construct_data);
 typedef void OSSL_DECODER_CLEANUP(void *construct_data);
 int OSSL_DECODER_CTX_set_construct(OSSL_DECODER_CTX *ctx,
                                    OSSL_DECODER_CONSTRUCT *construct);
 int OSSL_DECODER_CTX_set_construct_data(OSSL_DECODER_CTX *ctx,
                                         void *construct_data);
 int OSSL_DECODER_CTX_set_cleanup(OSSL_DECODER_CTX *ctx,
                                  OSSL_DECODER_CLEANUP *cleanup);
 OSSL_DECODER_CONSTRUCT *OSSL_DECODER_CTX_get_construct(OSSL_DECODER_CTX *ctx);
 void *OSSL_DECODER_CTX_get_construct_data(OSSL_DECODER_CTX *ctx);
 OSSL_DECODER_CLEANUP *OSSL_DECODER_CTX_get_cleanup(OSSL_DECODER_CTX *ctx);
 int OSSL_DECODER_export(OSSL_DECODER_INSTANCE *decoder_inst,
                         void *reference, size_t reference_sz,
                         OSSL_CALLBACK *export_cb, void *export_cbarg);

DESCRIPTION¶

The OSSL_DECODER_CTX holds data about multiple decoders, as needed to figure out what the input data is and to attempt to unpack it into one of several possible related results. This also includes chaining decoders, so the output from one can become the input for another. This allows having generic format decoders such as PEM to DER, as well as more specialized decoders like DER to RSA.

The chains may be limited by specifying an input type, which is considered a starting point. This is both considered by OSSL_DECODER_CTX_add_extra(), which will stop adding one more decoder implementations when it has already added those that take the specified input type, and functions like OSSL_DECODER_from_bio(3), which will only start the decoding process with the decoder implementations that take that input type. For example, if the input type is set to "DER", a PEM to DER decoder will be ignored.

The input type can also be NULL, which means that the caller doesn't know what type of input they have. In this case, OSSL_DECODER_from_bio() will simply try with one decoder implementation after the other, and thereby discover what kind of input the caller gave it.

For every decoding done, even an intermediary one, a constructor provided by the caller is called to attempt to construct an appropriate type / structure that the caller knows how to handle from the current decoding result. The constructor is set with OSSL_DECODER_CTX_set_construct().

OSSL_DECODER_INSTANCE is an opaque structure that contains data about the decoder that was just used, and that may be useful for the constructor. There are some functions to extract data from this type, described further down.

RETURN VALUES¶

OSSL_DECODER_CTX_new() returns a pointer to a OSSL_DECODER_CTX, or NULL if the context structure couldn't be allocated.

OSSL_DECODER_settable_ctx_params() returns an OSSL_PARAM(3) array, or NULL if none is available.

OSSL_DECODER_CTX_set_params() returns 1 if all recognised parameters were valid, or 0 if one of them was invalid or caused some other failure in the implementation.

OSSL_DECODER_CTX_add_decoder(), OSSL_DECODER_CTX_add_extra(), OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and OSSL_DECODER_CTX_set_cleanup() return 1 on success, or 0 on failure.

OSSL_DECODER_CTX_get_construct(), OSSL_DECODER_CTX_get_construct_data() and OSSL_DECODER_CTX_get_cleanup() return the current pointers to the constructor, the constructor data and the cleanup functions, respectively.

OSSL_DECODER_CTX_num_decoders() returns the current number of decoders. It returns 0 if ctx is NULL.

OSSL_DECODER_export() returns 1 on success, or 0 on failure.

OSSL_DECODER_INSTANCE_decoder() returns an OSSL_DECODER pointer on success, or NULL on failure.

OSSL_DECODER_INSTANCE_decoder_ctx() returns a provider context pointer on success, or NULL on failure.

SEE ALSO¶

provider(7), OSSL_DECODER(3), OSSL_DECODER_from_bio(3)

HISTORY¶

The functions described here were added in OpenSSL 3.0.

COPYRIGHT¶

Copyright 2020-2024 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 <https://www.openssl.org/source/license.html>.