1=pod 2 3=head1 NAME 4 5OSSL_ENCODER, 6OSSL_ENCODER_fetch, 7OSSL_ENCODER_up_ref, 8OSSL_ENCODER_free, 9OSSL_ENCODER_get0_provider, 10OSSL_ENCODER_get0_properties, 11OSSL_ENCODER_is_a, 12OSSL_ENCODER_get0_name, 13OSSL_ENCODER_get0_description, 14OSSL_ENCODER_do_all_provided, 15OSSL_ENCODER_names_do_all, 16OSSL_ENCODER_gettable_params, 17OSSL_ENCODER_get_params 18- Encoder method routines 19 20=head1 SYNOPSIS 21 22 #include <openssl/encoder.h> 23 24 typedef struct ossl_encoder_st OSSL_ENCODER; 25 26 OSSL_ENCODER *OSSL_ENCODER_fetch(OSSL_LIB_CTX *ctx, const char *name, 27 const char *properties); 28 int OSSL_ENCODER_up_ref(OSSL_ENCODER *encoder); 29 void OSSL_ENCODER_free(OSSL_ENCODER *encoder); 30 const OSSL_PROVIDER *OSSL_ENCODER_get0_provider(const OSSL_ENCODER *encoder); 31 const char *OSSL_ENCODER_get0_properties(const OSSL_ENCODER *encoder); 32 int OSSL_ENCODER_is_a(const OSSL_ENCODER *encoder, const char *name); 33 const char *OSSL_ENCODER_get0_name(const OSSL_ENCODER *encoder); 34 const char *OSSL_ENCODER_get0_description(const OSSL_ENCODER *encoder); 35 void OSSL_ENCODER_do_all_provided(OSSL_LIB_CTX *libctx, 36 void (*fn)(OSSL_ENCODER *encoder, void *arg), 37 void *arg); 38 int OSSL_ENCODER_names_do_all(const OSSL_ENCODER *encoder, 39 void (*fn)(const char *name, void *data), 40 void *data); 41 const OSSL_PARAM *OSSL_ENCODER_gettable_params(OSSL_ENCODER *encoder); 42 int OSSL_ENCODER_get_params(OSSL_ENCODER_CTX *ctx, const OSSL_PARAM params[]); 43 44=head1 DESCRIPTION 45 46B<OSSL_ENCODER> is a method for encoders, which know how to 47encode an object of some kind to a encoded form, such as PEM, 48DER, or even human readable text. 49 50OSSL_ENCODER_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 encoder 54method is expected to be able to encode, 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_ENCODER_up_ref() increments the reference count for the given 60I<encoder>. 61 62OSSL_ENCODER_free() decrements the reference count for the given 63I<encoder>, and when the count reaches zero, frees it. 64If the argument is NULL, nothing is done. 65 66OSSL_ENCODER_get0_provider() returns the provider of the given 67I<encoder>. 68 69OSSL_ENCODER_get0_properties() returns the property definition associated 70with the given I<encoder>. 71 72OSSL_ENCODER_is_a() checks if I<encoder> is an implementation of an 73algorithm that's identifiable with I<name>. 74 75OSSL_ENCODER_get0_name() returns the name used to fetch the given I<encoder>. 76 77OSSL_ENCODER_get0_description() returns a description of the I<loader>, meant 78for display and human consumption. The description is at the discretion of the 79I<loader> implementation. 80 81OSSL_ENCODER_names_do_all() traverses all names for the given 82I<encoder>, and calls I<fn> with each name and I<data> as arguments. 83 84OSSL_ENCODER_do_all_provided() traverses all encoder 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_ENCODER_gettable_params() returns an L<OSSL_PARAM(3)> 90array of parameter descriptors. 91 92OSSL_ENCODER_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_ENCODER_fetch() returns a pointer to the key management 99implementation represented by an OSSL_ENCODER object, or NULL on 100error. 101 102OSSL_ENCODER_up_ref() returns 1 on success, or 0 on error. 103 104OSSL_ENCODER_free() doesn't return any value. 105 106OSSL_ENCODER_get0_provider() returns a pointer to a provider object, or 107NULL on error. 108 109OSSL_ENCODER_get0_properties() returns a pointer to a property 110definition string, or NULL on error. 111 112OSSL_ENCODER_is_a() returns 1 of I<encoder> was identifiable, 113otherwise 0. 114 115OSSL_ENCODER_get0_name() returns the algorithm name from the provided 116implementation for the given I<encoder>. Note that the I<encoder> may have 117multiple synonyms associated with it. In this case the first name from the 118algorithm definition is returned. Ownership of the returned string is retained 119by the I<encoder> object and should not be freed by the caller. 120 121OSSL_ENCODER_get0_description() returns a pointer to a description, or NULL if 122there isn't one. 123 124OSSL_ENCODER_names_do_all() returns 1 if the callback was called for all 125names. A return value of 0 means that the callback was not called for any names. 126 127=head1 SEE ALSO 128 129L<provider(7)>, L<OSSL_ENCODER_CTX(3)>, L<OSSL_ENCODER_to_bio(3)>, 130L<OSSL_ENCODER_CTX_new_for_pkey(3)>, L<OSSL_LIB_CTX(3)> 131 132=head1 HISTORY 133 134The functions described here were added in OpenSSL 3.0. 135 136=head1 COPYRIGHT 137 138Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. 139 140Licensed under the Apache License 2.0 (the "License"). You may not use 141this file except in compliance with the License. You can obtain a copy 142in the file LICENSE in the source distribution or at 143L<https://www.openssl.org/source/license.html>. 144 145=cut 146
