doc/man3/OSSL_SERIALIZER.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_SERIALIZER,
   6 OSSL_SERIALIZER_fetch,
   7 OSSL_SERIALIZER_up_ref,
   8 OSSL_SERIALIZER_free,
   9 OSSL_SERIALIZER_provider,
  10 OSSL_SERIALIZER_properties,
  11 OSSL_SERIALIZER_is_a,
  12 OSSL_SERIALIZER_number,
  13 OSSL_SERIALIZER_do_all_provided,
  14 OSSL_SERIALIZER_names_do_all
  15 - Serializer method routines
  16
  17 =head1 SYNOPSIS
  18
  19  #include <openssl/serializer.h>
  20
  21  typedef struct ossl_serializer_st OSSL_SERIALIZER;
  22
  23  OSSL_SERIALIZER *OSSL_SERIALIZER_fetch(OPENSSL_CTX *ctx, const char *name,
  24                                         const char *properties);
  25  int OSSL_SERIALIZER_up_ref(OSSL_SERIALIZER *serializer);
  26  void OSSL_SERIALIZER_free(OSSL_SERIALIZER *serializer);
  27  const OSSL_PROVIDER *OSSL_SERIALIZER_provider(const OSSL_SERIALIZER
  28                                                *serializer);
  29  const char *OSSL_SERIALIZER_properties(const OSSL_SERIALIZER *ser);
  30  int OSSL_SERIALIZER_is_a(const OSSL_SERIALIZER *serializer,
  31                           const char *name);
  32  int OSSL_SERIALIZER_number(const OSSL_SERIALIZER *serializer);
  33  void OSSL_SERIALIZER_do_all_provided(OPENSSL_CTX *libctx,
  34                                       void (*fn)(OSSL_SERIALIZER *serializer,
  35                                                  void *arg),
  36                                       void *arg);
  37  void OSSL_SERIALIZER_names_do_all(const OSSL_SERIALIZER *serializer,
  38                                    void (*fn)(const char *name, void *data),
  39                                    void *data);
  40
  41 =head1 DESCRIPTION
  42
  43 =for comment Future development should also talk about deserialization
  44
  45 B<OSSL_SERIALIZER> is a method for serializers, which know how to
  46 serialize an object of some kind to a serialized form, such as PEM,
  47 DER, or even human readable text.
  48
  49 OSSL_SERIALIZER_fetch() looks for an algorithm within the provider that
  50 has been loaded into the B<OPENSSL_CTX> given by I<ctx>, having the
  51 name given by I<name> and the properties given by I<properties>.
  52 The I<name> determines what type of object the fetched serializer
  53 method is expected to be able to serialize, and the properties are
  54 used to determine the expected output type.
  55 For known properties and the values they may have, please have a look
  56 in L<provider-serializer(7)/Names and properties>.
  57
  58 OSSL_SERIALIZER_up_ref() increments the reference count for the given
  59 I<serializer>.
  60
  61 OSSL_SERIALIZER_free() decrements the reference count for the given
  62 I<serializer>, and when the count reaches zero, frees it.
  63
  64 OSSL_SERIALIZER_provider() returns the provider of the given
  65 I<serializer>.
  66
  67 OSSL_SERIALIZER_provider() returns the property definition associated
  68 with the given I<serializer>.
  69
  70 OSSL_SERIALIZER_is_a() checks if I<serializer> is an implementation of an
  71 algorithm that's identifiable with I<name>.
  72
  73 OSSL_SERIALIZER_number() returns the internal dynamic number assigned to
  74 the given I<serializer>.
  75
  76 OSSL_SERIALIZER_names_do_all() traverses all names for the given
  77 I<serializer>, and calls I<fn> with each name and I<data>.
  78
  79 OSSL_SERIALIZER_do_all_provided() traverses all serializer
  80 implementations by all activated providers in the library context
  81 I<libctx>, and for each of the implementations, calls I<fn> with the
  82 implementation method and I<data> as arguments.
  83
  84 =head1 NOTES
  85
  86 OSSL_SERIALIZER_fetch() may be called implicitly by other fetching
  87 functions, using the same library context and properties.
  88 Any other API that uses keys will typically do this.
  89
  90 =head1 RETURN VALUES
  91
  92 OSSL_SERIALIZER_fetch() returns a pointer to the key management
  93 implementation represented by an OSSL_SERIALIZER object, or NULL on
  94 error.
  95
  96 OSSL_SERIALIZER_up_ref() returns 1 on success, or 0 on error.
  97
  98 OSSL_SERIALIZER_free() doesn't return any value.
  99
 100 OSSL_SERIALIZER_provider() returns a pointer to a provider object, or
 101 NULL on error.
 102
 103 OSSL_SERIALIZER_properties() returns a pointer to a property
 104 definition string, or NULL on error.
 105
 106 OSSL_SERIALIZER_is_a() returns 1 of I<serializer> was identifiable,
 107 otherwise 0.
 108
 109 OSSL_SERIALIZER_number() returns an integer.
 110
 111 =head1 SEE ALSO
 112
 113 L<provider(7)>, L<OSSL_SERIALIZER_CTX(3)>, L<OSSL_SERIALIZER_to_bio(3)>,
 114 L<OSSL_SERIALIZER_CTX_new_by_EVP_PKEY(3)>, L<OPENSSL_CTX(3)>
 115
 116 =head1 HISTORY
 117
 118 The functions described here were added in OpenSSL 3.0.
 119
 120 =head1 COPYRIGHT
 121
 122 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 123
 124 Licensed under the Apache License 2.0 (the "License").  You may not use
 125 this file except in compliance with the License.  You can obtain a copy
 126 in the file LICENSE in the source distribution or at
 127 L<https://www.openssl.org/source/license.html>.
 128
 129 =cut