| =pod | |
| =head1 NAME | |
| OSSL_ENCODER_CTX, | |
| OSSL_ENCODER_CTX_new, | |
| OSSL_ENCODER_settable_ctx_params, | |
| OSSL_ENCODER_CTX_set_params, | |
| OSSL_ENCODER_CTX_free, | |
| OSSL_ENCODER_CTX_set_selection, | |
| OSSL_ENCODER_CTX_set_output_type, | |
| OSSL_ENCODER_CTX_set_output_structure, | |
| OSSL_ENCODER_CTX_add_encoder, | |
| OSSL_ENCODER_CTX_add_extra, | |
| OSSL_ENCODER_CTX_get_num_encoders, | |
| OSSL_ENCODER_INSTANCE, | |
| OSSL_ENCODER_INSTANCE_get_encoder, | |
| OSSL_ENCODER_INSTANCE_get_encoder_ctx, | |
| OSSL_ENCODER_INSTANCE_get_output_type, | |
| OSSL_ENCODER_INSTANCE_get_output_structure, | |
| OSSL_ENCODER_CONSTRUCT, | |
| OSSL_ENCODER_CLEANUP, | |
| OSSL_ENCODER_CTX_set_construct, | |
| OSSL_ENCODER_CTX_set_construct_data, | |
| OSSL_ENCODER_CTX_set_cleanup | |
| - Encoder context routines | |
| =head1 SYNOPSIS | |
| #include <openssl/encoder.h> | |
| typedef struct ossl_encoder_ctx_st OSSL_ENCODER_CTX; | |
| OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new(); | |
| const OSSL_PARAM *OSSL_ENCODER_settable_ctx_params(OSSL_ENCODER *encoder); | |
| int OSSL_ENCODER_CTX_set_params(OSSL_ENCODER_CTX *ctx, | |
| const OSSL_PARAM params[]); | |
| void OSSL_ENCODER_CTX_free(OSSL_ENCODER_CTX *ctx); | |
| int OSSL_ENCODER_CTX_set_selection(OSSL_ENCODER_CTX *ctx, int selection); | |
| int OSSL_ENCODER_CTX_set_output_type(OSSL_ENCODER_CTX *ctx, | |
| const char *output_type); | |
| int OSSL_ENCODER_CTX_set_output_structure(OSSL_ENCODER_CTX *ctx, | |
| const char *output_structure); | |
| int OSSL_ENCODER_CTX_add_encoder(OSSL_ENCODER_CTX *ctx, OSSL_ENCODER *encoder); | |
| int OSSL_ENCODER_CTX_add_extra(OSSL_ENCODER_CTX *ctx, | |
| OSSL_LIB_CTX *libctx, const char *propq); | |
| int OSSL_ENCODER_CTX_get_num_encoders(OSSL_ENCODER_CTX *ctx); | |
| typedef struct ossl_encoder_instance_st OSSL_ENCODER_INSTANCE; | |
| OSSL_ENCODER * | |
| OSSL_ENCODER_INSTANCE_get_encoder(OSSL_ENCODER_INSTANCE *encoder_inst); | |
| void * | |
| OSSL_ENCODER_INSTANCE_get_encoder_ctx(OSSL_ENCODER_INSTANCE *encoder_inst); | |
| const char * | |
| OSSL_ENCODER_INSTANCE_get_output_type(OSSL_ENCODER_INSTANCE *encoder_inst); | |
| const char * | |
| OSSL_ENCODER_INSTANCE_get_output_structure(OSSL_ENCODER_INSTANCE *encoder_inst); | |
| typedef const void *OSSL_ENCODER_CONSTRUCT(OSSL_ENCODER_INSTANCE *encoder_inst, | |
| void *construct_data); | |
| typedef void OSSL_ENCODER_CLEANUP(void *construct_data); | |
| int OSSL_ENCODER_CTX_set_construct(OSSL_ENCODER_CTX *ctx, | |
| OSSL_ENCODER_CONSTRUCT *construct); | |
| int OSSL_ENCODER_CTX_set_construct_data(OSSL_ENCODER_CTX *ctx, | |
| void *construct_data); | |
| int OSSL_ENCODER_CTX_set_cleanup(OSSL_ENCODER_CTX *ctx, | |
| OSSL_ENCODER_CLEANUP *cleanup); | |
| =head1 DESCRIPTION | |
| Encoding an input object to the desired encoding may be done with a chain of | |
| encoder implementations, which means that the output from one encoder may be | |
| the input for the next in the chain. The B<OSSL_ENCODER_CTX> holds all the | |
| data about these encoders. This allows having generic format encoders such | |
| as DER to PEM, as well as more specialized encoders like RSA to DER. | |
| The final output type must be given, and a chain of encoders must end with | |
| an implementation that produces that output type. | |
| At the beginning of the encoding process, a constructor provided by the | |
| caller is called to ensure that there is an appropriate provider-side object | |
| to start with. | |
| The constructor is set with OSSL_ENCODER_CTX_set_construct(). | |
| B<OSSL_ENCODER_INSTANCE> is an opaque structure that contains data about the | |
| encoder that is going to be used, and that may be useful for the | |
| constructor. There are some functions to extract data from this type, | |
| described in L</Constructor> below. | |
| =head2 Functions | |
| OSSL_ENCODER_CTX_new() creates a B<OSSL_ENCODER_CTX>. | |
| OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> | |
| array of parameter descriptors. | |
| OSSL_ENCODER_CTX_set_params() attempts to set parameters specified | |
| with an L<OSSL_PARAM(3)> array I<params>. Parameters that the | |
| implementation doesn't recognise should be ignored. | |
| OSSL_ENCODER_CTX_free() frees the given context I<ctx>. | |
| OSSL_ENCODER_CTX_add_encoder() populates the B<OSSL_ENCODER_CTX> | |
| I<ctx> with a encoder, to be used to encode an input object. | |
| OSSL_ENCODER_CTX_add_extra() finds encoders that further encodes output | |
| from already added encoders, and adds them as well. This is used to build | |
| encoder chains. | |
| OSSL_ENCODER_CTX_set_output_type() sets the ending output type. This must | |
| be specified, and determines if a complete encoder chain is available. | |
| OSSL_ENCODER_CTX_set_output_structure() sets the desired output structure. | |
| This may be used to determines what encoder implementations may be used. | |
| Depending on the type of object being encoded, the output structure may | |
| not be relevant. | |
| OSSL_ENCODER_CTX_get_num_encoders() gets the number of encoders currently | |
| added to the context I<ctx>. | |
| OSSL_ENCODER_CTX_set_construct() sets the constructor I<construct>. | |
| OSSL_ENCODER_CTX_set_construct_data() sets the constructor data that is | |
| passed to the constructor every time it's called. | |
| OSSL_ENCODER_CTX_set_cleanup() sets the constructor data I<cleanup> | |
| function. This is called by L<OSSL_ENCODER_CTX_free(3)>. | |
| =head2 Constructor | |
| A B<OSSL_ENCODER_CONSTRUCT> gets the following arguments: | |
| =over 4 | |
| =item I<encoder_inst> | |
| The B<OSSL_ENCODER_INSTANCE> for the encoder from which the constructor gets | |
| its data. | |
| =item I<construct_data> | |
| The pointer that was set with OSSL_ENCODE_CTX_set_construct_data(). | |
| =back | |
| The constructor is expected to return a valid (non-NULL) pointer to a | |
| provider-native object that can be used as first input of an encoding chain, | |
| or NULL to indicate that an error has occurred. | |
| These utility functions may be used by a constructor: | |
| OSSL_ENCODER_INSTANCE_get_encoder() can be used to get the encoder | |
| implementation of the encoder instance I<encoder_inst>. | |
| OSSL_ENCODER_INSTANCE_get_encoder_ctx() can be used to get the encoder | |
| implementation's provider context of the encoder instance I<encoder_inst>. | |
| OSSL_ENCODER_INSTANCE_get_output_type() can be used to get the output type | |
| for the encoder implementation of the encoder instance I<encoder_inst>. | |
| This will never be NULL. | |
| OSSL_ENCODER_INSTANCE_get_output_structure() can be used to get the output | |
| structure for the encoder implementation of the encoder instance | |
| I<encoder_inst>. | |
| This may be NULL. | |
| =head1 RETURN VALUES | |
| OSSL_ENCODER_CTX_new() returns a pointer to a B<OSSL_ENCODER_CTX>, or NULL | |
| if the context structure couldn't be allocated. | |
| OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array, or | |
| NULL if none is available. | |
| OSSL_ENCODER_CTX_set_params() returns 1 if all recognised parameters were | |
| valid, or 0 if one of them was invalid or caused some other failure in the | |
| implementation. | |
| OSSL_ENCODER_CTX_add_encoder(), OSSL_ENCODER_CTX_add_extra(), | |
| OSSL_ENCODER_CTX_set_construct(), OSSL_ENCODER_CTX_set_construct_data() and | |
| OSSL_ENCODER_CTX_set_cleanup() return 1 on success, or 0 on failure. | |
| OSSL_ENCODER_CTX_get_num_encoders() returns the current number of encoders. | |
| It returns 0 if I<ctx> is NULL. | |
| OSSL_ENCODER_INSTANCE_get_encoder() returns an B<OSSL_ENCODER> pointer on | |
| success, or NULL on failure. | |
| OSSL_ENCODER_INSTANCE_get_encoder_ctx() returns a provider context pointer on | |
| success, or NULL on failure. | |
| OSSL_ENCODER_INSTANCE_get_output_type() returns a string with the name of the | |
| input type, if relevant. NULL is a valid returned value. | |
| OSSL_ENCODER_INSTANCE_get_output_type() returns a string with the name of the | |
| output type. | |
| OSSL_ENCODER_INSTANCE_get_output_structure() returns a string with the name | |
| of the output structure. | |
| =head1 SEE ALSO | |
| L<provider(7)>, L<OSSL_ENCODER(3)> | |
| =head1 HISTORY | |
| The functions described here were added in OpenSSL 3.0. | |
| =head1 COPYRIGHT | |
| Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved. | |
| Licensed under the Apache License 2.0 (the "License"). You may not use | |
| this file except in compliance with the License. You can obtain a copy | |
| in the file LICENSE in the source distribution or at | |
| L<https://www.openssl.org/source/license.html>. | |
| =cut |