5 OSSL_SERIALIZER_CTX_new_by_EVP_PKEY,
6 OSSL_SERIALIZER_CTX_set_cipher,
7 OSSL_SERIALIZER_CTX_set_passphrase,
8 OSSL_SERIALIZER_CTX_set_passphrase_cb,
9 OSSL_SERIALIZER_CTX_set_passphrase_ui,
10 OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ,
11 OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ,
12 OSSL_SERIALIZER_Parameters_TO_PEM_PQ,
13 OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ,
14 OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ,
15 OSSL_SERIALIZER_Parameters_TO_TEXT_PQ
16 - Serializer routines to serialize EVP_PKEYs
20 #include <openssl/serializer.h>
22 OSSL_SERIALIZER_CTX *OSSL_SERIALIZER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey,
23 const char *propquery);
25 int OSSL_SERIALIZER_CTX_set_cipher(OSSL_SERIALIZER_CTX *ctx,
26 const char *cipher_name,
27 const char *propquery);
28 int OSSL_SERIALIZER_CTX_set_passphrase(OSSL_SERIALIZER_CTX *ctx,
29 const unsigned char *kstr,
31 int OSSL_SERIALIZER_CTX_set_passphrase_cb(OSSL_SERIALIZER_CTX *ctx, int enc,
32 pem_password_cb *cb, void *cbarg);
33 int OSSL_SERIALIZER_CTX_set_passphrase_ui(OSSL_SERIALIZER_CTX *ctx,
34 const UI_METHOD *ui_method,
37 #define OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ "format=pem,type=public"
38 #define OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ "format=pem,type=private"
39 #define OSSL_SERIALIZER_Parameters_TO_PEM_PQ "format=pem,type=domainparams"
41 #define OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ "format=text,type=public"
42 #define OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ "format=text,type=private"
43 #define OSSL_SERIALIZER_Parameters_TO_TEXT_PQ "format=text,type=domainparams"
47 OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() creates a B<OSSL_SERIALIZER_CTX>
48 with a suitable attached output routine for B<EVP_PKEY>s. It will
49 search for a serializer implementation that matches the algorithm of
50 the B<EVP_PKEY> and the property query given with I<propquery>. It
51 will prefer to find a serializer from the same provider as the key
52 data of the B<EVP_PKEY> itself, but failing that, it will choose the
53 first serializer that supplies a generic serializing function.
55 If no suitable serializer was found, OSSL_SERIALIZER_CTX_new_by_EVP_PKEY()
56 still creates a B<OSSL_SERIALIZER_CTX>, but with no associated
57 serializer (L<OSSL_SERIALIZER_CTX_get_serializer(3)> returns NULL).
58 This helps the caller distinguish between an error when creating
59 the B<OSSL_SERIALIZER_CTX>, and the lack the serializer support and
62 OSSL_SERIALIZER_CTX_set_cipher() tells the implementation what cipher
63 should be used to encrypt serialized keys. The cipher is given by
64 name I<cipher_name>. The interpretation of that I<cipher_name> is
65 implementation dependent. The implementation may implement the digest
66 directly itself or by other implementations, or it may choose to fetch
67 it. If the implementation supports fetching the cipher, then it may
68 use I<propquery> as properties to be queried for when fetching.
69 I<cipher_name> may also be NULL, which will result in unencrypted
72 OSSL_SERIALIZER_CTX_set_passphrase() gives the implementation a
73 pass phrase to use when encrypting the serialized private key.
74 Alternatively, a pass phrase callback may be specified with the
77 OSSL_SERIALIZER_CTX_set_passphrase_cb() and
78 OSSL_SERIALIZER_CTX_set_passphrase_ui() sets up a callback method that
79 the implementation can use to prompt for a pass phrase.
81 =for comment Note that the callback method is called indirectly,
82 through an internal B<OSSL_PASSPHRASE_CALLBACK> function.
84 The macros B<OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ>,
85 B<OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ>,
86 B<OSSL_SERIALIZER_Parameters_TO_PEM_PQ>,
87 B<OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ>,
88 B<OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ>,
89 B<OSSL_SERIALIZER_Parameters_TO_TEXT_PQ> are convenience macros with
90 property queries to serialize the B<EVP_PKEY> as a public key, private
91 key or parameters to B<PEM>, or to text.
95 OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() returns a pointer to a
96 B<OSSL_SERIALIZER_CTX>, or NULL if it couldn't be created.
98 OSSL_SERIALIZER_CTX_set_cipher(),
99 OSSL_SERIALIZER_CTX_set_passphrase(),
100 OSSL_SERIALIZER_CTX_set_passphrase_cb(), and
101 OSSL_SERIALIZER_CTX_set_passphrase_ui() all return 1 on success, or 0
106 Parts of the function and macro names are made to match already
107 existing OpenSSL names.
109 B<EVP_PKEY> in OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() matches the type
110 name, thus making for the naming pattern
111 B<OSSL_SERIALIZER_CTX_new_by_I<TYPE>>() when new types are handled.
113 B<PUBKEY>, B<PrivateKey> and B<Parameters> in the macro names match
114 the B<I<TYPE>> part of of B<PEM_write_bio_I<TYPE>> functions as well
115 as B<i2d_I<TYPE>_bio> functions.
119 L<provider(7)>, L<OSSL_SERIALIZER(3)>, L<OSSL_SERIALIZER_CTX(3)>
123 The functions described here were added in OpenSSL 3.0.
127 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
129 Licensed under the Apache License 2.0 (the "License"). You may not use
130 this file except in compliance with the License. You can obtain a copy
131 in the file LICENSE in the source distribution or at
132 L<https://www.openssl.org/source/license.html>.