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. 64 65OSSL_ENCODER_get0_provider() returns the provider of the given 66I<encoder>. 67 68OSSL_ENCODER_get0_properties() returns the property definition associated 69with the given I<encoder>. 70 71OSSL_ENCODER_is_a() checks if I<encoder> is an implementation of an 72algorithm that's identifiable with I<name>. 73 74OSSL_ENCODER_get0_name() returns the name used to fetch the given I<encoder>. 75 76OSSL_ENCODER_get0_description() returns a description of the I<loader>, meant 77for display and human consumption. The description is at the discretion of the 78I<loader> implementation. 79 80OSSL_ENCODER_names_do_all() traverses all names for the given 81I<encoder>, and calls I<fn> with each name and I<data> as arguments. 82 83OSSL_ENCODER_do_all_provided() traverses all encoder 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_ENCODER_gettable_params() returns an L<OSSL_PARAM(3)> 89array of parameter descriptors. 90 91OSSL_ENCODER_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_ENCODER_fetch() returns a pointer to the key management 98implementation represented by an OSSL_ENCODER object, or NULL on 99error. 100 101OSSL_ENCODER_up_ref() returns 1 on success, or 0 on error. 102 103OSSL_ENCODER_free() doesn't return any value. 104 105OSSL_ENCODER_get0_provider() returns a pointer to a provider object, or 106NULL on error. 107 108OSSL_ENCODER_get0_properties() returns a pointer to a property 109definition string, or NULL on error. 110 111OSSL_ENCODER_is_a() returns 1 of I<encoder> was identifiable, 112otherwise 0. 113 114OSSL_ENCODER_get0_name() returns the algorithm name from the provided 115implementation for the given I<encoder>. Note that the I<encoder> 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<encoder> object and should not be freed by the caller. 119 120OSSL_ENCODER_get0_description() returns a pointer to a description, or NULL if 121there isn't one. 122 123OSSL_ENCODER_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 SEE ALSO 127 128L<provider(7)>, L<OSSL_ENCODER_CTX(3)>, L<OSSL_ENCODER_to_bio(3)>, 129L<OSSL_ENCODER_CTX_new_for_pkey(3)>, L<OSSL_LIB_CTX(3)> 130 131=head1 HISTORY 132 133The functions described here were added in OpenSSL 3.0. 134 135=head1 COPYRIGHT 136 137Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. 138 139Licensed under the Apache License 2.0 (the "License"). You may not use 140this file except in compliance with the License. You can obtain a copy 141in the file LICENSE in the source distribution or at 142L<https://www.openssl.org/source/license.html>. 143 144=cut 145