1=pod 2 3=head1 NAME 4 5OSSL_DECODER, 6OSSL_DECODER_fetch, 7OSSL_DECODER_up_ref, 8OSSL_DECODER_free, 9OSSL_DECODER_get0_provider, 10OSSL_DECODER_get0_properties, 11OSSL_DECODER_is_a, 12OSSL_DECODER_get0_name, 13OSSL_DECODER_get0_description, 14OSSL_DECODER_do_all_provided, 15OSSL_DECODER_names_do_all, 16OSSL_DECODER_gettable_params, 17OSSL_DECODER_get_params 18- Decoder method routines 19 20=head1 SYNOPSIS 21 22 #include <openssl/decoder.h> 23 24 typedef struct ossl_decoder_st OSSL_DECODER; 25 26 OSSL_DECODER *OSSL_DECODER_fetch(OSSL_LIB_CTX *ctx, const char *name, 27 const char *properties); 28 int OSSL_DECODER_up_ref(OSSL_DECODER *decoder); 29 void OSSL_DECODER_free(OSSL_DECODER *decoder); 30 const OSSL_PROVIDER *OSSL_DECODER_get0_provider(const OSSL_DECODER *decoder); 31 const char *OSSL_DECODER_get0_properties(const OSSL_DECODER *decoder); 32 int OSSL_DECODER_is_a(const OSSL_DECODER *decoder, const char *name); 33 const char *OSSL_DECODER_get0_name(const OSSL_DECODER *decoder); 34 const char *OSSL_DECODER_get0_description(const OSSL_DECODER *decoder); 35 void OSSL_DECODER_do_all_provided(OSSL_LIB_CTX *libctx, 36 void (*fn)(OSSL_DECODER *decoder, void *arg), 37 void *arg); 38 int OSSL_DECODER_names_do_all(const OSSL_DECODER *decoder, 39 void (*fn)(const char *name, void *data), 40 void *data); 41 const OSSL_PARAM *OSSL_DECODER_gettable_params(OSSL_DECODER *decoder); 42 int OSSL_DECODER_get_params(OSSL_DECODER_CTX *ctx, const OSSL_PARAM params[]); 43 44=head1 DESCRIPTION 45 46B<OSSL_DECODER> is a method for decoders, which know how to 47decode encoded data into an object of some type that the rest 48of OpenSSL knows how to handle. 49 50OSSL_DECODER_fetch() looks for an algorithm within the provider that 51has been loaded into the B<OSSL_LIB_CTX> given by I<ctx>, having the 52name given by I<name> and the properties given by I<properties>. 53The I<name> determines what type of object the fetched decoder 54method is expected to be able to decode, and the properties are 55used to determine the expected output type. 56For known properties and the values they may have, please have a look 57in L<provider-encoder(7)/Names and properties>. 58 59OSSL_DECODER_up_ref() increments the reference count for the given 60I<decoder>. 61 62OSSL_DECODER_free() decrements the reference count for the given 63I<decoder>, and when the count reaches zero, frees it. 64If the argument is NULL, nothing is done. 65 66OSSL_DECODER_get0_provider() returns the provider of the given 67I<decoder>. 68 69OSSL_DECODER_get0_properties() returns the property definition associated 70with the given I<decoder>. 71 72OSSL_DECODER_is_a() checks if I<decoder> is an implementation 73of an algorithm that's identifiable with I<name>. 74 75OSSL_DECODER_get0_name() returns the name used to fetch the given I<decoder>. 76 77OSSL_DECODER_get0_description() returns a description of the I<decoder>, meant 78for display and human consumption. The description is at the discretion 79of the I<decoder> implementation. 80 81OSSL_DECODER_names_do_all() traverses all names for the given 82I<decoder>, and calls I<fn> with each name and I<data> as arguments. 83 84OSSL_DECODER_do_all_provided() traverses all decoder 85implementations by all activated providers in the library context 86I<libctx>, and for each of the implementations, calls I<fn> with the 87implementation method and I<arg> as arguments. 88 89OSSL_DECODER_gettable_params() returns an L<OSSL_PARAM(3)> 90array of parameter descriptors. 91 92OSSL_DECODER_get_params() attempts to get parameters specified 93with an L<OSSL_PARAM(3)> array I<params>. Parameters that the 94implementation doesn't recognise should be ignored. 95 96=head1 RETURN VALUES 97 98OSSL_DECODER_fetch() returns a pointer to an OSSL_DECODER object, 99or NULL on error. 100 101OSSL_DECODER_up_ref() returns 1 on success, or 0 on error. 102 103OSSL_DECODER_free() doesn't return any value. 104 105OSSL_DECODER_get0_provider() returns a pointer to a provider object, or 106NULL on error. 107 108OSSL_DECODER_get0_properties() returns a pointer to a property 109definition string, or NULL on error. 110 111OSSL_DECODER_is_a() returns 1 if I<decoder> was identifiable, 112otherwise 0. 113 114OSSL_DECODER_get0_name() returns the algorithm name from the provided 115implementation for the given I<decoder>. Note that the I<decoder> may have 116multiple synonyms associated with it. In this case the first name from the 117algorithm definition is returned. Ownership of the returned string is retained 118by the I<decoder> object and should not be freed by the caller. 119 120OSSL_DECODER_get0_description() returns a pointer to a description, or NULL if 121there isn't one. 122 123OSSL_DECODER_names_do_all() returns 1 if the callback was called for all 124names. A return value of 0 means that the callback was not called for any names. 125 126=head1 NOTES 127 128OSSL_DECODER_fetch() may be called implicitly by other fetching 129functions, using the same library context and properties. 130Any other API that uses keys will typically do this. 131 132=head1 EXAMPLES 133 134To list all decoders in a provider to a bio_out: 135 136 static void collect_decoders(OSSL_DECODER *decoder, void *stack) 137 { 138 STACK_OF(OSSL_DECODER) *decoder_stack = stack; 139 140 sk_OSSL_DECODER_push(decoder_stack, decoder); 141 OSSL_DECODER_up_ref(decoder); 142 } 143 144 void print_name(const char *name, void *vdata) 145 { 146 BIO *bio = vdata; 147 148 BIO_printf(bio, "%s ", name); 149 } 150 151 152 STACK_OF(OSSL_DECODER) *decoders; 153 int i; 154 155 decoders = sk_OSSL_DECODER_new_null(); 156 157 BIO_printf(bio_out, "DECODERs provided by %s:\n", provider); 158 OSSL_DECODER_do_all_provided(NULL, collect_decoders, 159 decoders); 160 161 for (i = 0; i < sk_OSSL_DECODER_num(decoders); i++) { 162 OSSL_DECODER *decoder = sk_OSSL_DECODER_value(decoders, i); 163 164 if (strcmp(OSSL_PROVIDER_get0_name(OSSL_DECODER_get0_provider(decoder)), 165 provider) != 0) 166 continue; 167 168 if (OSSL_DECODER_names_do_all(decoder, print_name, bio_out)) 169 BIO_printf(bio_out, "\n"); 170 } 171 sk_OSSL_DECODER_pop_free(decoders, OSSL_DECODER_free); 172 173=head1 SEE ALSO 174 175L<provider(7)>, L<OSSL_DECODER_CTX(3)>, L<OSSL_DECODER_from_bio(3)>, 176L<OSSL_DECODER_CTX_new_for_pkey(3)>, L<OSSL_LIB_CTX(3)> 177 178=head1 HISTORY 179 180The functions described here were added in OpenSSL 3.0. 181 182=head1 COPYRIGHT 183 184Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved. 185 186Licensed under the Apache License 2.0 (the "License"). You may not use 187this file except in compliance with the License. You can obtain a copy 188in the file LICENSE in the source distribution or at 189L<https://www.openssl.org/source/license.html>. 190 191=cut 192