1 | =pod
|
---|
2 |
|
---|
3 | =head1 NAME
|
---|
4 |
|
---|
5 | OSSL_ENCODER_CTX,
|
---|
6 | OSSL_ENCODER_CTX_new,
|
---|
7 | OSSL_ENCODER_settable_ctx_params,
|
---|
8 | OSSL_ENCODER_CTX_set_params,
|
---|
9 | OSSL_ENCODER_CTX_free,
|
---|
10 | OSSL_ENCODER_CTX_set_selection,
|
---|
11 | OSSL_ENCODER_CTX_set_output_type,
|
---|
12 | OSSL_ENCODER_CTX_set_output_structure,
|
---|
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,
|
---|
19 | OSSL_ENCODER_INSTANCE_get_output_type,
|
---|
20 | OSSL_ENCODER_INSTANCE_get_output_structure,
|
---|
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
|
---|
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 |
|
---|
34 | OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new();
|
---|
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 |
|
---|
40 | int OSSL_ENCODER_CTX_set_selection(OSSL_ENCODER_CTX *ctx, int selection);
|
---|
41 | int OSSL_ENCODER_CTX_set_output_type(OSSL_ENCODER_CTX *ctx,
|
---|
42 | const char *output_type);
|
---|
43 | int OSSL_ENCODER_CTX_set_output_structure(OSSL_ENCODER_CTX *ctx,
|
---|
44 | const char *output_structure);
|
---|
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,
|
---|
48 | OSSL_LIB_CTX *libctx, const char *propq);
|
---|
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 *
|
---|
57 | OSSL_ENCODER_INSTANCE_get_output_type(OSSL_ENCODER_INSTANCE *encoder_inst);
|
---|
58 | const char *
|
---|
59 | OSSL_ENCODER_INSTANCE_get_output_structure(OSSL_ENCODER_INSTANCE *encoder_inst);
|
---|
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 |
|
---|
72 | =head1 DESCRIPTION
|
---|
73 |
|
---|
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.
|
---|
79 |
|
---|
80 | The final output type must be given, and a chain of encoders must end with
|
---|
81 | an implementation that produces that output type.
|
---|
82 |
|
---|
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().
|
---|
87 |
|
---|
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.
|
---|
92 |
|
---|
93 | =head2 Functions
|
---|
94 |
|
---|
95 | OSSL_ENCODER_CTX_new() creates a B<OSSL_ENCODER_CTX>.
|
---|
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 |
|
---|
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 |
|
---|
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>.
|
---|
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 |
|
---|
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>.
|
---|
160 |
|
---|
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.
|
---|
169 |
|
---|
170 | =head1 RETURN VALUES
|
---|
171 |
|
---|
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.
|
---|
174 |
|
---|
175 | OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array, or
|
---|
176 | NULL if none is available.
|
---|
177 |
|
---|
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 |
|
---|
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.
|
---|
185 |
|
---|
186 | OSSL_ENCODER_CTX_get_num_encoders() returns the current number of encoders.
|
---|
187 | It returns 0 if I<ctx> is NULL.
|
---|
188 |
|
---|
189 | OSSL_ENCODER_INSTANCE_get_encoder() returns an B<OSSL_ENCODER> pointer on
|
---|
190 | success, or NULL on failure.
|
---|
191 |
|
---|
192 | OSSL_ENCODER_INSTANCE_get_encoder_ctx() returns a provider context pointer on
|
---|
193 | success, or NULL on failure.
|
---|
194 |
|
---|
195 | OSSL_ENCODER_INSTANCE_get_output_type() returns a string with the name of the
|
---|
196 | input type, if relevant. NULL is a valid returned value.
|
---|
197 |
|
---|
198 | OSSL_ENCODER_INSTANCE_get_output_type() returns a string with the name of the
|
---|
199 | output type.
|
---|
200 |
|
---|
201 | OSSL_ENCODER_INSTANCE_get_output_structure() returns a string with the name
|
---|
202 | of the output structure.
|
---|
203 |
|
---|
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 |
|
---|
214 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
|
---|
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
|
---|