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. 64 65OSSL_DECODER_get0_provider() returns the provider of the given 66I<decoder>. 67 68OSSL_DECODER_get0_properties() returns the property definition associated 69with the given I<decoder>. 70 71OSSL_DECODER_is_a() checks if I<decoder> is an implementation 72of an algorithm that's identifiable with I<name>. 73 74OSSL_DECODER_get0_name() returns the name used to fetch the given I<decoder>. 75 76OSSL_DECODER_get0_description() returns a description of the I<decoder>, meant 77for display and human consumption. The description is at the discretion 78of the I<decoder> implementation. 79 80OSSL_DECODER_names_do_all() traverses all names for the given 81I<decoder>, and calls I<fn> with each name and I<data> as arguments. 82 83OSSL_DECODER_do_all_provided() traverses all decoder 84implementations by all activated providers in the library context 85I<libctx>, and for each of the implementations, calls I<fn> with the 86implementation method and I<arg> as arguments. 87 88OSSL_DECODER_gettable_params() returns an L<OSSL_PARAM(3)> 89array of parameter descriptors. 90 91OSSL_DECODER_get_params() attempts to get parameters specified 92with an L<OSSL_PARAM(3)> array I<params>. Parameters that the 93implementation doesn't recognise should be ignored. 94 95=head1 RETURN VALUES 96 97OSSL_DECODER_fetch() returns a pointer to an OSSL_DECODER object, 98or NULL on error. 99 100OSSL_DECODER_up_ref() returns 1 on success, or 0 on error. 101 102OSSL_DECODER_free() doesn't return any value. 103 104OSSL_DECODER_get0_provider() returns a pointer to a provider object, or 105NULL on error. 106 107OSSL_DECODER_get0_properties() returns a pointer to a property 108definition string, or NULL on error. 109 110OSSL_DECODER_is_a() returns 1 if I<decoder> was identifiable, 111otherwise 0. 112 113OSSL_DECODER_get0_name() returns the algorithm name from the provided 114implementation for the given I<decoder>. Note that the I<decoder> may have 115multiple synonyms associated with it. In this case the first name from the 116algorithm definition is returned. Ownership of the returned string is retained 117by the I<decoder> object and should not be freed by the caller. 118 119OSSL_DECODER_get0_description() returns a pointer to a description, or NULL if 120there isn't one. 121 122OSSL_DECODER_names_do_all() returns 1 if the callback was called for all 123names. A return value of 0 means that the callback was not called for any names. 124 125=head1 NOTES 126 127OSSL_DECODER_fetch() may be called implicitly by other fetching 128functions, using the same library context and properties. 129Any other API that uses keys will typically do this. 130 131=head1 EXAMPLES 132 133To list all decoders in a provider to a bio_out: 134 135 static void collect_decoders(OSSL_DECODER *decoder, void *stack) 136 { 137 STACK_OF(OSSL_DECODER) *decoder_stack = stack; 138 139 sk_OSSL_DECODER_push(decoder_stack, decoder); 140 OSSL_DECODER_up_ref(decoder); 141 } 142 143 void print_name(const char *name, void *vdata) 144 { 145 BIO *bio = vdata; 146 147 BIO_printf(bio, "%s ", name); 148 } 149 150 151 STACK_OF(OSSL_DECODER) *decoders; 152 int i; 153 154 decoders = sk_OSSL_DECODER_new_null(); 155 156 BIO_printf(bio_out, "DECODERs provided by %s:\n", provider); 157 OSSL_DECODER_do_all_provided(NULL, collect_decoders, 158 decoders); 159 160 for (i = 0; i < sk_OSSL_DECODER_num(decoders); i++) { 161 OSSL_DECODER *decoder = sk_OSSL_DECODER_value(decoders, i); 162 163 if (strcmp(OSSL_PROVIDER_get0_name(OSSL_DECODER_get0_provider(decoder)), 164 provider) != 0) 165 continue; 166 167 if (OSSL_DECODER_names_do_all(decoder, print_name, bio_out)) 168 BIO_printf(bio_out, "\n"); 169 } 170 sk_OSSL_DECODER_pop_free(decoders, OSSL_DECODER_free); 171 172=head1 SEE ALSO 173 174L<provider(7)>, L<OSSL_DECODER_CTX(3)>, L<OSSL_DECODER_from_bio(3)>, 175L<OSSL_DECODER_CTX_new_for_pkey(3)>, L<OSSL_LIB_CTX(3)> 176 177=head1 HISTORY 178 179The functions described here were added in OpenSSL 3.0. 180 181=head1 COPYRIGHT 182 183Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. 184 185Licensed under the Apache License 2.0 (the "License"). You may not use 186this file except in compliance with the License. You can obtain a copy 187in the file LICENSE in the source distribution or at 188L<https://www.openssl.org/source/license.html>. 189 190=cut 191