xref: /openssl/doc/man3/OSSL_DECODER.pod (revision 7ed6de99) 
1=pod
2
3=head1 NAME
4
5OSSL_DECODER,
6OSSL_DECODER_fetch,
7OSSL_DECODER_up_ref,
8OSSL_DECODER_free,
9OSSL_DECODER_get0_provider,
10OSSL_DECODER_get0_properties,
11OSSL_DECODER_is_a,
12OSSL_DECODER_get0_name,
13OSSL_DECODER_get0_description,
14OSSL_DECODER_do_all_provided,
15OSSL_DECODER_names_do_all,
16OSSL_DECODER_gettable_params,
17OSSL_DECODER_get_params
18- Decoder method routines
19
20=head1 SYNOPSIS
21
22 #include <openssl/decoder.h>
23
24 typedef struct ossl_decoder_st OSSL_DECODER;
25
26 OSSL_DECODER *OSSL_DECODER_fetch(OSSL_LIB_CTX *ctx, const char *name,
27                                  const char *properties);
28 int OSSL_DECODER_up_ref(OSSL_DECODER *decoder);
29 void OSSL_DECODER_free(OSSL_DECODER *decoder);
30 const OSSL_PROVIDER *OSSL_DECODER_get0_provider(const OSSL_DECODER *decoder);
31 const char *OSSL_DECODER_get0_properties(const OSSL_DECODER *decoder);
32 int OSSL_DECODER_is_a(const OSSL_DECODER *decoder, const char *name);
33 const char *OSSL_DECODER_get0_name(const OSSL_DECODER *decoder);
34 const char *OSSL_DECODER_get0_description(const OSSL_DECODER *decoder);
35 void OSSL_DECODER_do_all_provided(OSSL_LIB_CTX *libctx,
36                                   void (*fn)(OSSL_DECODER *decoder, void *arg),
37                                   void *arg);
38 int OSSL_DECODER_names_do_all(const OSSL_DECODER *decoder,
39                               void (*fn)(const char *name, void *data),
40                               void *data);
41 const OSSL_PARAM *OSSL_DECODER_gettable_params(OSSL_DECODER *decoder);
42 int OSSL_DECODER_get_params(OSSL_DECODER_CTX *ctx, const OSSL_PARAM params[]);
43
44=head1 DESCRIPTION
45
46B<OSSL_DECODER> is a method for decoders, which know how to
47decode encoded data into an object of some type that the rest
48of OpenSSL knows how to handle.
49
50OSSL_DECODER_fetch() looks for an algorithm within the provider that
51has been loaded into the B<OSSL_LIB_CTX> given by I<ctx>, having the
52name given by I<name> and the properties given by I<properties>.
53The I<name> determines what type of object the fetched decoder
54method is expected to be able to decode, and the properties are
55used to determine the expected output type.
56For known properties and the values they may have, please have a look
57in L<provider-encoder(7)/Names and properties>.
58
59OSSL_DECODER_up_ref() increments the reference count for the given
60I<decoder>.
61
62OSSL_DECODER_free() decrements the reference count for the given
63I<decoder>, and when the count reaches zero, frees it.
64If the argument is NULL, nothing is done.
65
66OSSL_DECODER_get0_provider() returns the provider of the given
67I<decoder>.
68
69OSSL_DECODER_get0_properties() returns the property definition associated
70with the given I<decoder>.
71
72OSSL_DECODER_is_a() checks if I<decoder> is an implementation
73of an algorithm that's identifiable with I<name>.
74
75OSSL_DECODER_get0_name() returns the name used to fetch the given I<decoder>.
76
77OSSL_DECODER_get0_description() returns a description of the I<decoder>, meant
78for display and human consumption.  The description is at the discretion
79of the I<decoder> implementation.
80
81OSSL_DECODER_names_do_all() traverses all names for the given
82I<decoder>, and calls I<fn> with each name and I<data> as arguments.
83
84OSSL_DECODER_do_all_provided() traverses all decoder
85implementations by all activated providers in the library context
86I<libctx>, and for each of the implementations, calls I<fn> with the
87implementation method and I<arg> as arguments.
88
89OSSL_DECODER_gettable_params() returns an L<OSSL_PARAM(3)>
90array of parameter descriptors.
91
92OSSL_DECODER_get_params() attempts to get parameters specified
93with an L<OSSL_PARAM(3)> array I<params>.  Parameters that the
94implementation doesn't recognise should be ignored.
95
96=head1 RETURN VALUES
97
98OSSL_DECODER_fetch() returns a pointer to an OSSL_DECODER object,
99or NULL on error.
100
101OSSL_DECODER_up_ref() returns 1 on success, or 0 on error.
102
103OSSL_DECODER_free() doesn't return any value.
104
105OSSL_DECODER_get0_provider() returns a pointer to a provider object, or
106NULL on error.
107
108OSSL_DECODER_get0_properties() returns a pointer to a property
109definition string, or NULL on error.
110
111OSSL_DECODER_is_a() returns 1 if I<decoder> was identifiable,
112otherwise 0.
113
114OSSL_DECODER_get0_name() returns the algorithm name from the provided
115implementation for the given I<decoder>. Note that the I<decoder> may have
116multiple synonyms associated with it. In this case the first name from the
117algorithm definition is returned. Ownership of the returned string is retained
118by the I<decoder> object and should not be freed by the caller.
119
120OSSL_DECODER_get0_description() returns a pointer to a description, or NULL if
121there isn't one.
122
123OSSL_DECODER_names_do_all() returns 1 if the callback was called for all
124names. A return value of 0 means that the callback was not called for any names.
125
126=head1 NOTES
127
128OSSL_DECODER_fetch() may be called implicitly by other fetching
129functions, using the same library context and properties.
130Any other API that uses keys will typically do this.
131
132=head1 EXAMPLES
133
134To list all decoders in a provider to a bio_out:
135
136 static void collect_decoders(OSSL_DECODER *decoder, void *stack)
137 {
138     STACK_OF(OSSL_DECODER) *decoder_stack = stack;
139
140     sk_OSSL_DECODER_push(decoder_stack, decoder);
141     OSSL_DECODER_up_ref(decoder);
142 }
143
144 void print_name(const char *name, void *vdata)
145 {
146     BIO *bio = vdata;
147
148     BIO_printf(bio, "%s ", name);
149 }
150
151
152 STACK_OF(OSSL_DECODER) *decoders;
153 int i;
154
155 decoders = sk_OSSL_DECODER_new_null();
156
157 BIO_printf(bio_out, "DECODERs provided by %s:\n", provider);
158 OSSL_DECODER_do_all_provided(NULL, collect_decoders,
159                              decoders);
160
161 for (i = 0; i < sk_OSSL_DECODER_num(decoders); i++) {
162     OSSL_DECODER *decoder = sk_OSSL_DECODER_value(decoders, i);
163
164     if (strcmp(OSSL_PROVIDER_get0_name(OSSL_DECODER_get0_provider(decoder)),
165                provider) != 0)
166         continue;
167
168     if (OSSL_DECODER_names_do_all(decoder, print_name, bio_out))
169            BIO_printf(bio_out, "\n");
170 }
171 sk_OSSL_DECODER_pop_free(decoders, OSSL_DECODER_free);
172
173=head1 SEE ALSO
174
175L<provider(7)>, L<OSSL_DECODER_CTX(3)>, L<OSSL_DECODER_from_bio(3)>,
176L<OSSL_DECODER_CTX_new_for_pkey(3)>, L<OSSL_LIB_CTX(3)>
177
178=head1 HISTORY
179
180The functions described here were added in OpenSSL 3.0.
181
182=head1 COPYRIGHT
183
184Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.
185
186Licensed under the Apache License 2.0 (the "License").  You may not use
187this file except in compliance with the License.  You can obtain a copy
188in the file LICENSE in the source distribution or at
189L<https://www.openssl.org/source/license.html>.
190
191=cut
192