OSSL_DECODER(3ossl)

1OSSL_DECODER(3ossl)                 OpenSSL                OSSL_DECODER(3ossl)
2
3
4

NAME

6       OSSL_DECODER, OSSL_DECODER_fetch, OSSL_DECODER_up_ref,
7       OSSL_DECODER_free, OSSL_DECODER_get0_provider,
8       OSSL_DECODER_get0_properties, OSSL_DECODER_is_a,
9       OSSL_DECODER_get0_name, OSSL_DECODER_get0_description,
10       OSSL_DECODER_do_all_provided, OSSL_DECODER_names_do_all,
11       OSSL_DECODER_gettable_params, OSSL_DECODER_get_params - Decoder method
12       routines
13

SYNOPSIS

15        #include <openssl/decoder.h>
16
17        typedef struct ossl_decoder_st OSSL_DECODER;
18
19        OSSL_DECODER *OSSL_DECODER_fetch(OSSL_LIB_CTX *ctx, const char *name,
20                                         const char *properties);
21        int OSSL_DECODER_up_ref(OSSL_DECODER *decoder);
22        void OSSL_DECODER_free(OSSL_DECODER *decoder);
23        const OSSL_PROVIDER *OSSL_DECODER_get0_provider(const OSSL_DECODER *decoder);
24        const char *OSSL_DECODER_get0_properties(const OSSL_DECODER *decoder);
25        int OSSL_DECODER_is_a(const OSSL_DECODER *decoder, const char *name);
26        const char *OSSL_DECODER_get0_name(const OSSL_DECODER *decoder);
27        const char *OSSL_DECODER_get0_description(const OSSL_DECODER *decoder);
28        void OSSL_DECODER_do_all_provided(OSSL_LIB_CTX *libctx,
29                                          void (*fn)(OSSL_DECODER *decoder, void *arg),
30                                          void *arg);
31        int OSSL_DECODER_names_do_all(const OSSL_DECODER *decoder,
32                                      void (*fn)(const char *name, void *data),
33                                      void *data);
34        const OSSL_PARAM *OSSL_DECODER_gettable_params(OSSL_DECODER *decoder);
35        int OSSL_DECODER_get_params(OSSL_DECODER_CTX *ctx, const OSSL_PARAM params[]);
36

DESCRIPTION

38       OSSL_DECODER is a method for decoders, which know how to decode encoded
39       data into an object of some type that the rest of OpenSSL knows how to
40       handle.
41
42       OSSL_DECODER_fetch() looks for an algorithm within the provider that
43       has been loaded into the OSSL_LIB_CTX given by ctx, having the name
44       given by name and the properties given by properties.  The name
45       determines what type of object the fetched decoder method is expected
46       to be able to decode, and the properties are used to determine the
47       expected output type.  For known properties and the values they may
48       have, please have a look in "Names and properties" in
49       provider-encoder(7).
50
51       OSSL_DECODER_up_ref() increments the reference count for the given
52       decoder.
53
54       OSSL_DECODER_free() decrements the reference count for the given
55       decoder, and when the count reaches zero, frees it.
56
57       OSSL_DECODER_get0_provider() returns the provider of the given decoder.
58
59       OSSL_DECODER_get0_properties() returns the property definition
60       associated with the given decoder.
61
62       OSSL_DECODER_is_a() checks if decoder is an implementation of an
63       algorithm that's identifiable with name.
64
65       OSSL_DECODER_get0_name() returns the name used to fetch the given
66       decoder.
67
68       OSSL_DECODER_get0_description() returns a description of the decoder,
69       meant for display and human consumption.  The description is at the
70       discretion of the decoder implementation.
71
72       OSSL_DECODER_names_do_all() traverses all names for the given decoder,
73       and calls fn with each name and data as arguments.
74
75       OSSL_DECODER_do_all_provided() traverses all decoder implementations by
76       all activated providers in the library context libctx, and for each of
77       the implementations, calls fn with the implementation method and arg as
78       arguments.
79
80       OSSL_DECODER_gettable_params() returns an OSSL_PARAM(3) array of
81       parameter descriptors.
82
83       OSSL_DECODER_get_params() attempts to get parameters specified with an
84       OSSL_PARAM(3) array params.  Parameters that the implementation doesn't
85       recognise should be ignored.
86

RETURN VALUES

88       OSSL_DECODER_fetch() returns a pointer to an OSSL_DECODER object, or
89       NULL on error.
90
91       OSSL_DECODER_up_ref() returns 1 on success, or 0 on error.
92
93       OSSL_DECODER_free() doesn't return any value.
94
95       OSSL_DECODER_get0_provider() returns a pointer to a provider object, or
96       NULL on error.
97
98       OSSL_DECODER_get0_properties() returns a pointer to a property
99       definition string, or NULL on error.
100
101       OSSL_DECODER_is_a() returns 1 if decoder was identifiable, otherwise 0.
102
103       OSSL_DECODER_get0_name() returns the algorithm name from the provided
104       implementation for the given decoder. Note that the decoder may have
105       multiple synonyms associated with it. In this case the first name from
106       the algorithm definition is returned. Ownership of the returned string
107       is retained by the decoder object and should not be freed by the
108       caller.
109
110       OSSL_DECODER_get0_description() returns a pointer to a decription, or
111       NULL if there isn't one.
112
113       OSSL_DECODER_names_do_all() returns 1 if the callback was called for
114       all names. A return value of 0 means that the callback was not called
115       for any names.
116

NOTES

118       OSSL_DECODER_fetch() may be called implicitly by other fetching
119       functions, using the same library context and properties.  Any other
120       API that uses keys will typically do this.
121

EXAMPLES

123       To list all decoders in a provider to a bio_out:
124
125        static void collect_decoders(OSSL_DECODER *decoder, void *stack)
126        {
127            STACK_OF(OSSL_DECODER) *decoder_stack = stack;
128
129            sk_OSSL_DECODER_push(decoder_stack, decoder);
130            OSSL_DECODER_up_ref(decoder);
131        }
132
133        void print_name(const char *name, void *vdata)
134        {
135            BIO *bio = vdata;
136
137            BIO_printf(bio, "%s ", name);
138        }
139
140
141        STACK_OF(OSSL_DECODER) *decoders;
142        int i;
143
144        decoders = sk_OSSL_DECODER_new_null();
145
146        BIO_printf(bio_out, "DECODERs provided by %s:\n", provider);
147        OSSL_DECODER_do_all_provided(NULL, collect_decoders,
148                                     decoders);
149
150        for (i = 0; i < sk_OSSL_DECODER_num(decoders); i++) {
151            OSSL_DECODER *decoder = sk_OSSL_DECODER_value(decoders, i);
152
153            if (strcmp(OSSL_PROVIDER_get0_name(OSSL_DECODER_get0_provider(decoder)),
154                       provider) != 0)
155                continue;
156
157            if (OSSL_DECODER_names_do_all(decoder, print_name, bio_out))
158                   BIO_printf(bio_out, "\n");
159        }
160        sk_OSSL_DECODER_pop_free(decoders, OSSL_DECODER_free);
161

HISTORY

167       The functions described here were added in OpenSSL 3.0.
168

COPYRIGHT

170       Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
171
172       Licensed under the Apache License 2.0 (the "License").  You may not use
173       this file except in compliance with the License.  You can obtain a copy
174       in the file LICENSE in the source distribution or at
175       <https://www.openssl.org/source/license.html>.
176
177
178
1793.0.5                             2022-11-01               OSSL_DECODER(3ossl)