7 OSSL_ENCODER_settable_ctx_params,
8 OSSL_ENCODER_CTX_set_params,
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,
23 OSSL_ENCODER_CTX_set_construct,
24 OSSL_ENCODER_CTX_set_construct_data,
25 OSSL_ENCODER_CTX_set_cleanup
26 - Encoder context routines
30 #include <openssl/encoder.h>
32 typedef struct ossl_encoder_ctx_st OSSL_ENCODER_CTX;
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);
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);
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);
51 typedef struct ossl_encoder_instance_st OSSL_ENCODER_INSTANCE;
53 OSSL_ENCODER_INSTANCE_get_encoder(OSSL_ENCODER_INSTANCE *encoder_inst);
55 OSSL_ENCODER_INSTANCE_get_encoder_ctx(OSSL_ENCODER_INSTANCE *encoder_inst);
57 OSSL_ENCODER_INSTANCE_get_output_type(OSSL_ENCODER_INSTANCE *encoder_inst);
59 OSSL_ENCODER_INSTANCE_get_output_structure(OSSL_ENCODER_INSTANCE *encoder_inst);
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);
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);
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.
80 The final output type must be given, and a chain of encoders must end with
81 an implementation that produces that output type.
83 At the beginning of the encoding process, a constructor provided by the
84 caller is called to ensure that there is an appropriate provider-side object
86 The constructor is set with OSSL_ENCODER_CTX_set_construct().
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.
95 OSSL_ENCODER_CTX_new() creates a B<OSSL_ENCODER_CTX>.
97 OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)>
98 array of parameter descriptors.
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.
104 OSSL_ENCODER_CTX_free() frees the given context I<ctx>.
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.
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
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.
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
121 OSSL_ENCODER_CTX_get_num_encoders() gets the number of encoders currently
122 added to the context I<ctx>.
124 OSSL_ENCODER_CTX_set_construct() sets the constructor I<construct>.
126 OSSL_ENCODER_CTX_set_construct_data() sets the constructor data that is
127 passed to the constructor every time it's called.
129 OSSL_ENCODER_CTX_set_cleanup() sets the constructor data I<cleanup>
130 function. This is called by L<OSSL_ENCODER_CTX_free(3)>.
134 A B<OSSL_ENCODER_CONSTRUCT> gets the following arguments:
138 =item I<encoder_inst>
140 The B<OSSL_ENCODER_INSTANCE> for the encoder from which the constructor gets
143 =item I<construct_data>
145 The pointer that was set with OSSL_ENCODE_CTX_set_construct_data().
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 occurred.
153 These utility functions may be used by a constructor:
155 OSSL_ENCODER_INSTANCE_get_encoder() can be used to get the encoder
156 implementation of the encoder instance I<encoder_inst>.
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>.
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.
165 OSSL_ENCODER_INSTANCE_get_output_structure() can be used to get the output
166 structure for the encoder implementation of the encoder instance
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.
175 OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array, or
176 NULL if none is available.
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
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.
186 OSSL_ENCODER_CTX_get_num_encoders() returns the current number of encoders.
187 It returns 0 if I<ctx> is NULL.
189 OSSL_ENCODER_INSTANCE_get_encoder() returns an B<OSSL_ENCODER> pointer on
190 success, or NULL on failure.
192 OSSL_ENCODER_INSTANCE_get_encoder_ctx() returns a provider context pointer on
193 success, or NULL on failure.
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.
198 OSSL_ENCODER_INSTANCE_get_output_type() returns a string with the name of the
201 OSSL_ENCODER_INSTANCE_get_output_structure() returns a string with the name
202 of the output structure.
206 L<provider(7)>, L<OSSL_ENCODER(3)>
210 The functions described here were added in OpenSSL 3.0.
214 Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
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>.