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