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