diff options
author | Richard Levitte <levitte@openssl.org> | 2020-08-16 21:25:08 +0200 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2020-08-21 09:23:58 +0200 |
commit | ece9304c96f71277ca95696d9bc49fdec51e9f17 (patch) | |
tree | 7038f8760e1538754bc67371cb5a466a83935dad /doc/man3/OSSL_DECODER.pod | |
parent | f650993f1de3dbb5eda9009ad0c4895a7b1b7fe2 (diff) | |
download | openssl-ece9304c96f71277ca95696d9bc49fdec51e9f17.tar.gz |
Rename OSSL_SERIALIZER / OSSL_DESERIALIZER to OSSL_ENCODE / OSSL_DECODE
Fixes #12455
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/12660)
Diffstat (limited to 'doc/man3/OSSL_DECODER.pod')
-rw-r--r-- | doc/man3/OSSL_DECODER.pod | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/doc/man3/OSSL_DECODER.pod b/doc/man3/OSSL_DECODER.pod new file mode 100644 index 0000000000..96d0a51ca5 --- /dev/null +++ b/doc/man3/OSSL_DECODER.pod @@ -0,0 +1,142 @@ +=pod + +=head1 NAME + +OSSL_DECODER, +OSSL_DECODER_fetch, +OSSL_DECODER_up_ref, +OSSL_DECODER_free, +OSSL_DECODER_provider, +OSSL_DECODER_properties, +OSSL_DECODER_is_a, +OSSL_DECODER_number, +OSSL_DECODER_do_all_provided, +OSSL_DECODER_names_do_all, +OSSL_DECODER_gettable_params, +OSSL_DECODER_get_params +- Decoder method routines + +=head1 SYNOPSIS + + #include <openssl/decoder.h> + + typedef struct ossl_decoder_st OSSL_DECODER; + + OSSL_DECODER *OSSL_DECODER_fetch(OPENSSL_CTX *ctx, const char *name, + const char *properties); + int OSSL_DECODER_up_ref(OSSL_DECODER *decoder); + void OSSL_DECODER_free(OSSL_DECODER *decoder); + const OSSL_PROVIDER *OSSL_DECODER_provider(const OSSL_DECODER *decoder); + const char *OSSL_DECODER_properties(const OSSL_DECODER *decoder); + int OSSL_DECODER_is_a(const OSSL_DECODER *decoder, const char *name); + int OSSL_DECODER_number(const OSSL_DECODER *decoder); + void OSSL_DECODER_do_all_provided(OPENSSL_CTX *libctx, + void (*fn)(OSSL_DECODER *decoder, void *arg), + void *arg); + void OSSL_DECODER_names_do_all(const OSSL_DECODER *decoder, + void (*fn)(const char *name, void *data), + void *data); + const OSSL_PARAM *OSSL_DECODER_gettable_params(OSSL_DECODER *decoder); + int OSSL_DECODER_get_params(OSSL_DECODER_CTX *ctx, const OSSL_PARAM params[]); + +=head1 DESCRIPTION + +B<OSSL_DECODER> is a method for decoders, which know how to +decode encoded data into an object of some type that the rest +of OpenSSL knows how to handle. + +OSSL_DECODER_fetch() looks for an algorithm within the provider that +has been loaded into the B<OPENSSL_CTX> given by I<ctx>, having the +name given by I<name> and the properties given by I<properties>. +The I<name> determines what type of object the fetched decoder +method is expected to be able to decode, and the properties are +used to determine the expected output type. +For known properties and the values they may have, please have a look +in L<provider-encoder(7)/Names and properties>. + +OSSL_DECODER_up_ref() increments the reference count for the given +I<decoder>. + +OSSL_DECODER_free() decrements the reference count for the given +I<decoder>, and when the count reaches zero, frees it. + +OSSL_DECODER_provider() returns the provider of the given +I<decoder>. + +OSSL_DECODER_properties() returns the property definition associated +with the given I<decoder>. + +OSSL_DECODER_is_a() checks if I<decoder> is an implementation +of an algorithm that's identifiable with I<name>. + +OSSL_DECODER_number() returns the internal dynamic number assigned +to the given I<decoder>. + +OSSL_DECODER_names_do_all() traverses all names for the given +I<decoder>, and calls I<fn> with each name and I<data>. + +OSSL_DECODER_do_all_provided() traverses all encoder +implementations by all activated providers in the library context +I<libctx>, and for each of the implementations, calls I<fn> with the +implementation method and I<data> as arguments. + +OSSL_DECODER_gettable_params() returns an L<OSSL_PARAM(3)> +array of parameter descriptors. + +OSSL_DECODER_get_params() attempts to get parameters specified +with an L<OSSL_PARAM(3)> array I<params>. Parameters that the +implementation doesn't recognise should be ignored. + +=head1 RETURN VALUES + +OSSL_DECODER_fetch() returns a pointer to an OSSL_DECODER object, +or NULL on error. + +OSSL_DECODER_up_ref() returns 1 on success, or 0 on error. + +OSSL_DECODER_free() doesn't return any value. + +OSSL_DECODER_provider() returns a pointer to a provider object, or +NULL on error. + +OSSL_DECODER_properties() returns a pointer to a property +definition string, or NULL on error. + +OSSL_DECODER_is_a() returns 1 if I<decoder> was identifiable, +otherwise 0. + +OSSL_DECODER_number() returns an integer. + +=head1 NOTES + +OSSL_DECODER_fetch() may be called implicitly by other fetching +functions, using the same library context and properties. +Any other API that uses keys will typically do this. + +=begin comment TODO(3.0) Add examples! + +=head1 EXAMPLES + +Text, because pod2xxx doesn't like empty sections + +=end comment + +=head1 SEE ALSO + +L<provider(7)>, L<OSSL_DECODER_CTX(3)>, L<OSSL_DECODER_from_bio(3)>, +L<OSSL_DECODER_CTX_new_by_EVP_PKEY(3)>, L<OPENSSL_CTX(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |