]>
Commit | Line | Data |
---|---|---|
ece9304c RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | OSSL_ENCODER_CTX, | |
6 | OSSL_ENCODER_CTX_new, | |
ece9304c RL |
7 | OSSL_ENCODER_settable_ctx_params, |
8 | OSSL_ENCODER_CTX_set_params, | |
b8975c68 | 9 | OSSL_ENCODER_CTX_free, |
b8975c68 | 10 | OSSL_ENCODER_CTX_set_selection, |
8a98a507 RL |
11 | OSSL_ENCODER_CTX_set_output_type, |
12 | OSSL_ENCODER_CTX_set_output_structure, | |
b8975c68 RL |
13 | OSSL_ENCODER_CTX_add_encoder, |
14 | OSSL_ENCODER_CTX_add_extra, | |
15 | OSSL_ENCODER_CTX_get_num_encoders, | |
16 | OSSL_ENCODER_INSTANCE, | |
17 | OSSL_ENCODER_INSTANCE_get_encoder, | |
18 | OSSL_ENCODER_INSTANCE_get_encoder_ctx, | |
b8975c68 | 19 | OSSL_ENCODER_INSTANCE_get_output_type, |
8a98a507 | 20 | OSSL_ENCODER_INSTANCE_get_output_structure, |
b8975c68 RL |
21 | OSSL_ENCODER_CONSTRUCT, |
22 | OSSL_ENCODER_CLEANUP, | |
23 | OSSL_ENCODER_CTX_set_construct, | |
24 | OSSL_ENCODER_CTX_set_construct_data, | |
25 | OSSL_ENCODER_CTX_set_cleanup | |
ece9304c RL |
26 | - Encoder context routines |
27 | ||
28 | =head1 SYNOPSIS | |
29 | ||
30 | #include <openssl/encoder.h> | |
31 | ||
32 | typedef struct ossl_encoder_ctx_st OSSL_ENCODER_CTX; | |
33 | ||
b8975c68 | 34 | OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new(); |
ece9304c RL |
35 | const OSSL_PARAM *OSSL_ENCODER_settable_ctx_params(OSSL_ENCODER *encoder); |
36 | int OSSL_ENCODER_CTX_set_params(OSSL_ENCODER_CTX *ctx, | |
37 | const OSSL_PARAM params[]); | |
38 | void OSSL_ENCODER_CTX_free(OSSL_ENCODER_CTX *ctx); | |
39 | ||
8a98a507 | 40 | int OSSL_ENCODER_CTX_set_selection(OSSL_ENCODER_CTX *ctx, int selection); |
b8975c68 RL |
41 | int OSSL_ENCODER_CTX_set_output_type(OSSL_ENCODER_CTX *ctx, |
42 | const char *output_type); | |
8a98a507 RL |
43 | int OSSL_ENCODER_CTX_set_output_structure(OSSL_ENCODER_CTX *ctx, |
44 | const char *output_structure); | |
b8975c68 RL |
45 | |
46 | int OSSL_ENCODER_CTX_add_encoder(OSSL_ENCODER_CTX *ctx, OSSL_ENCODER *encoder); | |
47 | int OSSL_ENCODER_CTX_add_extra(OSSL_ENCODER_CTX *ctx, | |
b4250010 | 48 | OSSL_LIB_CTX *libctx, const char *propq); |
b8975c68 RL |
49 | int OSSL_ENCODER_CTX_get_num_encoders(OSSL_ENCODER_CTX *ctx); |
50 | ||
51 | typedef struct ossl_encoder_instance_st OSSL_ENCODER_INSTANCE; | |
52 | OSSL_ENCODER * | |
53 | OSSL_ENCODER_INSTANCE_get_encoder(OSSL_ENCODER_INSTANCE *encoder_inst); | |
54 | void * | |
55 | OSSL_ENCODER_INSTANCE_get_encoder_ctx(OSSL_ENCODER_INSTANCE *encoder_inst); | |
56 | const char * | |
b8975c68 | 57 | OSSL_ENCODER_INSTANCE_get_output_type(OSSL_ENCODER_INSTANCE *encoder_inst); |
8a98a507 RL |
58 | const char * |
59 | OSSL_ENCODER_INSTANCE_get_output_structure(OSSL_ENCODER_INSTANCE *encoder_inst); | |
b8975c68 RL |
60 | |
61 | typedef const void *OSSL_ENCODER_CONSTRUCT(OSSL_ENCODER_INSTANCE *encoder_inst, | |
62 | void *construct_data); | |
63 | typedef void OSSL_ENCODER_CLEANUP(void *construct_data); | |
64 | ||
65 | int OSSL_ENCODER_CTX_set_construct(OSSL_ENCODER_CTX *ctx, | |
66 | OSSL_ENCODER_CONSTRUCT *construct); | |
67 | int OSSL_ENCODER_CTX_set_construct_data(OSSL_ENCODER_CTX *ctx, | |
68 | void *construct_data); | |
69 | int OSSL_ENCODER_CTX_set_cleanup(OSSL_ENCODER_CTX *ctx, | |
70 | OSSL_ENCODER_CLEANUP *cleanup); | |
71 | ||
ece9304c RL |
72 | =head1 DESCRIPTION |
73 | ||
b8975c68 RL |
74 | Encoding an input object to the desired encoding may be done with a chain of |
75 | encoder implementations, which means that the output from one encoder may be | |
76 | the input for the next in the chain. The B<OSSL_ENCODER_CTX> holds all the | |
77 | data about these encoders. This allows having generic format encoders such | |
78 | as DER to PEM, as well as more specialized encoders like RSA to DER. | |
ece9304c | 79 | |
b8975c68 RL |
80 | The final output type must be given, and a chain of encoders must end with |
81 | an implementation that produces that output type. | |
ece9304c | 82 | |
b8975c68 RL |
83 | At the beginning of the encoding process, a contructor provided by the |
84 | caller is called to ensure that there is an appropriate provider-side object | |
85 | to start with. | |
86 | The constructor is set with OSSL_ENCODER_CTX_set_construct(). | |
ece9304c | 87 | |
b8975c68 RL |
88 | B<OSSL_ENCODER_INSTANCE> is an opaque structure that contains data about the |
89 | encoder that is going to be used, and that may be useful for the | |
90 | constructor. There are some functions to extract data from this type, | |
91 | described in L</Constructor> below. | |
ece9304c | 92 | |
b8975c68 | 93 | =head2 Functions |
ece9304c | 94 | |
b8975c68 | 95 | OSSL_ENCODER_CTX_new() creates a B<OSSL_ENCODER_CTX>. |
ece9304c RL |
96 | |
97 | OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> | |
98 | array of parameter descriptors. | |
99 | ||
100 | OSSL_ENCODER_CTX_set_params() attempts to set parameters specified | |
101 | with an L<OSSL_PARAM(3)> array I<params>. Parameters that the | |
102 | implementation doesn't recognise should be ignored. | |
103 | ||
104 | OSSL_ENCODER_CTX_free() frees the given context I<ctx>. | |
105 | ||
b8975c68 RL |
106 | OSSL_ENCODER_CTX_add_encoder() populates the B<OSSL_ENCODER_CTX> |
107 | I<ctx> with a encoder, to be used to encode an input object. | |
108 | ||
109 | OSSL_ENCODER_CTX_add_extra() finds encoders that further encodes output | |
110 | from already added encoders, and adds them as well. This is used to build | |
111 | encoder chains. | |
112 | ||
113 | OSSL_ENCODER_CTX_set_output_type() sets the ending output type. This must | |
114 | be specified, and determines if a complete encoder chain is available. | |
115 | ||
8a98a507 RL |
116 | OSSL_ENCODER_CTX_set_output_structure() sets the desired output structure. |
117 | This may be used to determines what encoder implementations may be used. | |
118 | Depending on the type of object being encoded, the output structure may | |
119 | not be relevant. | |
120 | ||
121 | OSSL_ENCODER_CTX_get_num_encoders() gets the number of encoders currently | |
122 | added to the context I<ctx>. | |
b8975c68 RL |
123 | |
124 | OSSL_ENCODER_CTX_set_construct() sets the constructor I<construct>. | |
125 | ||
126 | OSSL_ENCODER_CTX_set_construct_data() sets the constructor data that is | |
127 | passed to the constructor every time it's called. | |
128 | ||
129 | OSSL_ENCODER_CTX_set_cleanup() sets the constructor data I<cleanup> | |
130 | function. This is called by L<OSSL_ENCODER_CTX_free(3)>. | |
131 | ||
132 | =head2 Constructor | |
133 | ||
134 | A B<OSSL_ENCODER_CONSTRUCT> gets the following arguments: | |
135 | ||
136 | =over 4 | |
137 | ||
138 | =item I<encoder_inst> | |
139 | ||
140 | The B<OSSL_ENCODER_INSTANCE> for the encoder from which the constructor gets | |
141 | its data. | |
142 | ||
143 | =item I<construct_data> | |
144 | ||
145 | The pointer that was set with OSSL_ENCODE_CTX_set_construct_data(). | |
146 | ||
147 | =back | |
148 | ||
149 | The constructor is expected to return a valid (non-NULL) pointer to a | |
150 | provider-native object that can be used as first input of an encoding chain, | |
151 | or NULL to indicate that an error has occured. | |
152 | ||
153 | These utility functions may be used by a constructor: | |
154 | ||
8a98a507 RL |
155 | OSSL_ENCODER_INSTANCE_get_encoder() can be used to get the encoder |
156 | implementation of the encoder instance I<encoder_inst>. | |
157 | ||
158 | OSSL_ENCODER_INSTANCE_get_encoder_ctx() can be used to get the encoder | |
159 | implementation's provider context of the encoder instance I<encoder_inst>. | |
b8975c68 | 160 | |
8a98a507 RL |
161 | OSSL_ENCODER_INSTANCE_get_output_type() can be used to get the output type |
162 | for the encoder implementation of the encoder instance I<encoder_inst>. | |
163 | This will never be NULL. | |
164 | ||
165 | OSSL_ENCODER_INSTANCE_get_output_structure() can be used to get the output | |
166 | structure for the encoder implementation of the encoder instance | |
167 | I<encoder_inst>. | |
168 | This may be NULL. | |
b8975c68 | 169 | |
ece9304c RL |
170 | =head1 RETURN VALUES |
171 | ||
b8975c68 RL |
172 | OSSL_ENCODER_CTX_new() returns a pointer to a B<OSSL_ENCODER_CTX>, or NULL |
173 | if the context structure couldn't be allocated. | |
ece9304c | 174 | |
b8975c68 RL |
175 | OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array, or |
176 | NULL if none is available. | |
ece9304c | 177 | |
b8975c68 RL |
178 | OSSL_ENCODER_CTX_set_params() returns 1 if all recognised parameters were |
179 | valid, or 0 if one of them was invalid or caused some other failure in the | |
180 | implementation. | |
181 | ||
8a98a507 RL |
182 | OSSL_ENCODER_CTX_add_encoder(), OSSL_ENCODER_CTX_add_extra(), |
183 | OSSL_ENCODER_CTX_set_construct(), OSSL_ENCODER_CTX_set_construct_data() and | |
184 | OSSL_ENCODER_CTX_set_cleanup() return 1 on success, or 0 on failure. | |
b8975c68 | 185 | |
8a98a507 RL |
186 | OSSL_ENCODER_CTX_get_num_encoders() returns the current number of encoders. |
187 | It returns 0 if I<ctx> is NULL. | |
b8975c68 | 188 | |
8a98a507 | 189 | OSSL_ENCODER_INSTANCE_get_encoder() returns an B<OSSL_ENCODER> pointer on |
b8975c68 RL |
190 | success, or NULL on failure. |
191 | ||
8a98a507 | 192 | OSSL_ENCODER_INSTANCE_get_encoder_ctx() returns a provider context pointer on |
b8975c68 RL |
193 | success, or NULL on failure. |
194 | ||
8a98a507 | 195 | OSSL_ENCODER_INSTANCE_get_output_type() returns a string with the name of the |
b8975c68 | 196 | input type, if relevant. NULL is a valid returned value. |
ece9304c | 197 | |
8a98a507 | 198 | OSSL_ENCODER_INSTANCE_get_output_type() returns a string with the name of the |
b8975c68 | 199 | output type. |
ece9304c | 200 | |
8a98a507 RL |
201 | OSSL_ENCODER_INSTANCE_get_output_structure() returns a string with the name |
202 | of the output structure. | |
203 | ||
ece9304c RL |
204 | =head1 SEE ALSO |
205 | ||
206 | L<provider(7)>, L<OSSL_ENCODER(3)> | |
207 | ||
208 | =head1 HISTORY | |
209 | ||
210 | The functions described here were added in OpenSSL 3.0. | |
211 | ||
212 | =head1 COPYRIGHT | |
213 | ||
eec0ad10 | 214 | Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. |
ece9304c RL |
215 | |
216 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
217 | this file except in compliance with the License. You can obtain a copy | |
218 | in the file LICENSE in the source distribution or at | |
219 | L<https://www.openssl.org/source/license.html>. | |
220 | ||
221 | =cut |