SERIALIZER: add support for serializing EVP_PKEYs
[openssl.git] / 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