mirror of https://github.com/openssl/openssl.git
145 lines
5.8 KiB
Plaintext
145 lines
5.8 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
OSSL_SERIALIZER_CTX_new_by_EVP_PKEY,
|
|
OSSL_SERIALIZER_CTX_set_cipher,
|
|
OSSL_SERIALIZER_CTX_set_passphrase,
|
|
OSSL_SERIALIZER_CTX_set_passphrase_cb,
|
|
OSSL_SERIALIZER_CTX_set_passphrase_ui,
|
|
OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ,
|
|
OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ,
|
|
OSSL_SERIALIZER_Parameters_TO_PEM_PQ,
|
|
OSSL_SERIALIZER_PUBKEY_TO_DER_PQ,
|
|
OSSL_SERIALIZER_PrivateKey_TO_DER_PQ,
|
|
OSSL_SERIALIZER_Parameters_TO_DER_PQ,
|
|
OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ,
|
|
OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ,
|
|
OSSL_SERIALIZER_Parameters_TO_TEXT_PQ
|
|
- Serializer routines to serialize EVP_PKEYs
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/serializer.h>
|
|
|
|
OSSL_SERIALIZER_CTX *OSSL_SERIALIZER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey,
|
|
const char *propquery);
|
|
|
|
int OSSL_SERIALIZER_CTX_set_cipher(OSSL_SERIALIZER_CTX *ctx,
|
|
const char *cipher_name,
|
|
const char *propquery);
|
|
int OSSL_SERIALIZER_CTX_set_passphrase(OSSL_SERIALIZER_CTX *ctx,
|
|
const unsigned char *kstr,
|
|
size_t klen);
|
|
int OSSL_SERIALIZER_CTX_set_passphrase_cb(OSSL_SERIALIZER_CTX *ctx, int enc,
|
|
pem_password_cb *cb, void *cbarg);
|
|
int OSSL_SERIALIZER_CTX_set_passphrase_ui(OSSL_SERIALIZER_CTX *ctx,
|
|
const UI_METHOD *ui_method,
|
|
void *ui_data);
|
|
|
|
#define OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ "format=pem,type=public"
|
|
#define OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ "format=pem,type=private"
|
|
#define OSSL_SERIALIZER_Parameters_TO_PEM_PQ "format=pem,type=parameters"
|
|
|
|
#define OSSL_SERIALIZER_PUBKEY_TO_DER_PQ "format=der,type=public"
|
|
#define OSSL_SERIALIZER_PrivateKey_TO_DER_PQ "format=der,type=private"
|
|
#define OSSL_SERIALIZER_Parameters_TO_DER_PQ "format=der,type=parameters"
|
|
|
|
#define OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ "format=text,type=public"
|
|
#define OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ "format=text,type=private"
|
|
#define OSSL_SERIALIZER_Parameters_TO_TEXT_PQ "format=text,type=parameters"
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() creates a B<OSSL_SERIALIZER_CTX>
|
|
with a suitable attached output routine for B<EVP_PKEY>s. It will
|
|
search for a serializer implementation that matches the algorithm of
|
|
the B<EVP_PKEY> and the property query given with I<propquery>. It
|
|
will prefer to find a serializer from the same provider as the key
|
|
data of the B<EVP_PKEY> itself, but failing that, it will choose the
|
|
first serializer that supplies a generic serializing function.
|
|
|
|
If no suitable serializer was found, OSSL_SERIALIZER_CTX_new_by_EVP_PKEY()
|
|
still creates a B<OSSL_SERIALIZER_CTX>, but with no associated
|
|
serializer (L<OSSL_SERIALIZER_CTX_get_serializer(3)> returns NULL).
|
|
This helps the caller distinguish between an error when creating
|
|
the B<OSSL_SERIALIZER_CTX>, and the lack the serializer support and
|
|
act accordingly.
|
|
|
|
OSSL_SERIALIZER_CTX_set_cipher() tells the implementation what cipher
|
|
should be used to encrypt serialized keys. The cipher is given by
|
|
name I<cipher_name>. The interpretation of that I<cipher_name> is
|
|
implementation dependent. The implementation may implement the digest
|
|
directly itself or by other implementations, or it may choose to fetch
|
|
it. If the implementation supports fetching the cipher, then it may
|
|
use I<propquery> as properties to be queried for when fetching.
|
|
I<cipher_name> may also be NULL, which will result in unencrypted
|
|
serialization.
|
|
|
|
OSSL_SERIALIZER_CTX_set_passphrase() gives the implementation a
|
|
pass phrase to use when encrypting the serialized private key.
|
|
Alternatively, a pass phrase callback may be specified with the
|
|
following functions.
|
|
|
|
OSSL_SERIALIZER_CTX_set_passphrase_cb() and
|
|
OSSL_SERIALIZER_CTX_set_passphrase_ui() sets up a callback method that
|
|
the implementation can use to prompt for a pass phrase.
|
|
|
|
=for comment Note that the callback method is called indirectly,
|
|
through an internal B<OSSL_PASSPHRASE_CALLBACK> function.
|
|
|
|
The macros B<OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ>,
|
|
B<OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ>,
|
|
B<OSSL_SERIALIZER_Parameters_TO_PEM_PQ>,
|
|
B<OSSL_SERIALIZER_PUBKEY_TO_DER_PQ>,
|
|
B<OSSL_SERIALIZER_PrivateKey_TO_DER_PQ>,
|
|
B<OSSL_SERIALIZER_Parameters_TO_DER_PQ>,
|
|
B<OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ>,
|
|
B<OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ>,
|
|
B<OSSL_SERIALIZER_Parameters_TO_TEXT_PQ> are convenience macros with
|
|
property queries to serialize the B<EVP_PKEY> as a public key, private
|
|
key or parameters to B<PEM>, to B<DER>, or to text.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() returns a pointer to a
|
|
B<OSSL_SERIALIZER_CTX>, or NULL if it couldn't be created.
|
|
|
|
OSSL_SERIALIZER_CTX_set_cipher(),
|
|
OSSL_SERIALIZER_CTX_set_passphrase(),
|
|
OSSL_SERIALIZER_CTX_set_passphrase_cb(), and
|
|
OSSL_SERIALIZER_CTX_set_passphrase_ui() all return 1 on success, or 0
|
|
on failure.
|
|
|
|
=head1 NOTES
|
|
|
|
Parts of the function and macro names are made to match already
|
|
existing OpenSSL names.
|
|
|
|
B<EVP_PKEY> in OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() matches the type
|
|
name, thus making for the naming pattern
|
|
B<OSSL_SERIALIZER_CTX_new_by_I<TYPE>>() when new types are handled.
|
|
|
|
B<PUBKEY>, B<PrivateKey> and B<Parameters> in the macro names match
|
|
the B<I<TYPE>> part of of B<PEM_write_bio_I<TYPE>> functions as well
|
|
as B<i2d_I<TYPE>_bio> functions.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<provider(7)>, L<OSSL_SERIALIZER(3)>, L<OSSL_SERIALIZER_CTX(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
The functions described here were added in OpenSSL 3.0.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2019-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
|