mirror of
https://github.com/openssl/openssl.git
synced 2024-12-09 05:51:54 +08:00
866234ac35
The following public functions is added: - 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_CTX_new_by_EVP_PKEY() selects a suitable serializer for the given EVP_PKEY, and sets up the OSSL_SERIALIZER_CTX to function together with OSSL_SERIALIZER_to_bio() and OSSL_SERIALIZER_to_fp(). OSSL_SERIALIZER_CTX_set_cipher() indicates what cipher should be used to produce an encrypted serialization of the EVP_PKEY. This is passed directly to the provider using OSSL_SERIALIZER_CTX_set_params(). OSSL_SERIALIZER_CTX_set_passphrase() can be used to set a pass phrase to be used for the encryption. This is passed directly to the provider using OSSL_SERIALIZER_CTX_set_params(). OSSL_SERIALIZER_CTX_set_passphrase_cb() and OSSL_SERIALIZER_CTX_set_passphrase_ui() sets up a callback to be used to prompt for a passphrase. This is stored in the context, and is called via an internal intermediary at the time of serialization. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10394)
277 lines
8.8 KiB
Plaintext
277 lines
8.8 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
provider-serializer - The SERIALIZER library E<lt>-E<gt> provider functions
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
=begin comment
|
|
|
|
Future development will also include deserializing functions.
|
|
|
|
=end comment
|
|
|
|
#include <openssl/core_numbers.h>
|
|
|
|
/*
|
|
* None of these are actual functions, but are displayed like this for
|
|
* the function signatures for functions that are offered as function
|
|
* pointers in OSSL_DISPATCH arrays.
|
|
*/
|
|
|
|
/* Functions to construct / destruct / manipulate the serializer context */
|
|
void *OP_serializer_newctx(void *provctx);
|
|
void OP_serializer_freectx(void *ctx);
|
|
int OP_serializer_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
|
|
const OSSL_PARAM *OP_serializer_settable_ctx_params(void)
|
|
|
|
/* Functions to serialize object data */
|
|
int OP_serializer_serialize_data(void *ctx, const OSSL_PARAM *data,
|
|
BIO *out,
|
|
OSSL_PASSPHRASE_CALLBACK *cb,
|
|
void *cbarg);
|
|
int OP_serializer_serialize_object(void *ctx, void *obj, BIO *out,
|
|
OSSL_PASSPHRASE_CALLBACK *cb,
|
|
void *cbarg);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The SERIALIZER is a generic method to serialize any set of object data
|
|
in L<OSSL_PARAM(3)> array form, or any provider side object into
|
|
serialized form, and write it to the given BIO. If the caller wants
|
|
to get the serialized stream to memory, it should provide a
|
|
L<BIO_s_membuf(3)>.
|
|
|
|
The serializer doesn't need to know more about the B<BIO> pointer than
|
|
being able to pass it to the appropriate BIO upcalls (see
|
|
L<provider-base(7)/Core functions>).
|
|
|
|
The serialization using the L<OSSL_PARAM(3)> array form allows a
|
|
serializer to be used for data that's been exported from another
|
|
provider, and thereby allow them to exist independently of each
|
|
other.
|
|
|
|
The serialization using a provider side object can only be safely used
|
|
with provider data coming from the same provider, for example keys
|
|
with the L<KEYMGMT|provider-keymgmt(7)> provider.
|
|
|
|
All "functions" mentioned here are passed as function pointers between
|
|
F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
|
|
B<OSSL_ALGORITHM> arrays that are returned by the provider's
|
|
provider_query_operation() function
|
|
(see L<provider-base(7)/Provider Functions>).
|
|
|
|
All these "functions" have a corresponding function type definition
|
|
named B<OSSL_{name}_fn>, and a helper function to retrieve the
|
|
function pointer from a B<OSSL_DISPATCH> element named
|
|
B<OSSL_get_{name}>.
|
|
For example, the "function" OP_serializer_serialize_data() has these:
|
|
|
|
typedef int
|
|
(OSSL_OP_serializer_serialize_data_fn)(void *provctx,
|
|
const OSSL_PARAM params[],
|
|
BIO *out);
|
|
static ossl_inline OSSL_OP_serializer_serialize_data_fn
|
|
OSSL_get_OP_serializer_serialize_data(const OSSL_DISPATCH *opf);
|
|
|
|
B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
|
|
macros in L<openssl-core_numbers.h(7)>, as follows:
|
|
|
|
OP_serializer_newctx OSSL_FUNC_SERIALIZER_NEWCTX
|
|
OP_serializer_freectx OSSL_FUNC_SERIALIZER_FREECTX
|
|
OP_serializer_set_ctx_params OSSL_FUNC_SERIALIZER_SET_CTX_PARAMS
|
|
OP_serializer_settable_ctx_params OSSL_FUNC_SERIALIZER_SETTABLE_CTX_PARAMS
|
|
|
|
OP_serializer_serialize_data OSSL_FUNC_SERIALIZER_SERIALIZE_DATA
|
|
OP_serializer_serialize_object OSSL_FUNC_SERIALIZER_SERIALIZE_OBJECT
|
|
|
|
=head2 Names and properties
|
|
|
|
The name of an implementation should match the type of object it
|
|
handles. For example, an implementation that serializes an RSA key
|
|
should be named accordingly.
|
|
|
|
To be able to specify exactly what serialization format and what type
|
|
of data a serializer implementation is expected to handle, two
|
|
additional properties may be given:
|
|
|
|
=over 4
|
|
|
|
=item format
|
|
|
|
This property is used to specify what kind of output format the
|
|
implementation produces. Currently known formats are:
|
|
|
|
=over 4
|
|
|
|
=item text
|
|
|
|
An implementation with that format property value outputs human
|
|
readable text, making that implementation suitable for C<-text> output
|
|
in diverse L<openssl(1)> commands.
|
|
|
|
=item pem
|
|
|
|
An implementation with that format property value outputs PEM
|
|
formatted data.
|
|
|
|
=item der
|
|
|
|
An implementation with that format property value outputs DER
|
|
formatted data.
|
|
|
|
=back
|
|
|
|
=item type
|
|
|
|
With objects that have multiple purposes, this can be used to specify
|
|
the purpose type. The currently known use cases are asymmetric keys
|
|
and domain parameters, where the type can be one of:
|
|
|
|
=over 4
|
|
|
|
=item private
|
|
|
|
An implementation with that format property value outputs a private
|
|
key.
|
|
|
|
=item public
|
|
|
|
An implementation with that format property value outputs a public
|
|
key.
|
|
|
|
=item domainparams
|
|
|
|
An implementation with that format property value outputs domain
|
|
parameters.
|
|
|
|
=back
|
|
|
|
=back
|
|
|
|
The possible values of both these properties is open ended. A
|
|
provider may very well specify other formats that libcrypto doesn't
|
|
know anything about.
|
|
|
|
=head2 Context functions
|
|
|
|
OP_serializer_newctx() returns a context to be used with the rest of
|
|
the functions.
|
|
|
|
OP_serializer_freectx() frees the given I<ctx>, if it was created by
|
|
OP_serializer_newctx().
|
|
|
|
OP_serializer_set_ctx_params() sets context data according to
|
|
parameters from I<params> that it recognises. Unrecognised parameters
|
|
should be ignored.
|
|
|
|
OP_serializer_settable_ctx_params() returns a constant B<OSSL_PARAM>
|
|
array describing the parameters that OP_serializer_set_ctx_params()
|
|
can handle.
|
|
|
|
See L<OSSL_PARAM(3)> for further details on the parameters structure used
|
|
by OP_serializer_set_ctx_params() and OP_serializer_settable_ctx_params().
|
|
|
|
=head2 Serializing functions
|
|
|
|
=for comment There will be a "Deserializing functions" title as well
|
|
|
|
OP_serializer_serialize_data() should take an array of B<OSSL_PARAM>,
|
|
I<data>, and if it contains the data necessary for the object type
|
|
that the implementation handles, it should output the object in
|
|
serialized form to the B<BIO>.
|
|
|
|
OP_serializer_serialize_object() should take a pointer to an object
|
|
that it knows intimately, and output that object in serialized form to
|
|
the B<BIO>. The caller I<must> ensure that this function is called
|
|
with a pointer that the provider of this function is familiar with.
|
|
It is not suitable to use with object pointers coming from other
|
|
providers.
|
|
|
|
Both serialization functions also take an B<OSSL_PASSPHRASE_CALLBACK>
|
|
function pointer along with a pointer to application data I<cbarg>,
|
|
which should be used when a pass phrase prompt is needed.
|
|
|
|
=head2 Serializer parameters
|
|
|
|
Parameters currently recognised by built-in serializers are as
|
|
follows:
|
|
|
|
=over 4
|
|
|
|
=item "cipher" (B<OSSL_SERIALIZER_PARAM_CIPHER>) <UTF8 string>
|
|
|
|
The name of the encryption cipher to be used when generating encrypted
|
|
serialization. This is used when serializing private keys, as well as
|
|
other objects that need protection.
|
|
|
|
If this name is invalid for the serialization implementation, the
|
|
implementation should refuse to perform the serialization, i.e.
|
|
OP_serializer_serialize_data() and OP_serializer_serialize_object()
|
|
should return an error.
|
|
|
|
=item "properties" (B<OSSL_SERIALIZER_PARAM_PROPERTIES>) <UTF8 string>
|
|
|
|
The properties to be queried when trying to fetch the algorithm given
|
|
with the "cipher" parameter.
|
|
This must be given together with the "cipher" parameter to be
|
|
considered valid.
|
|
|
|
The serialization implementation isn't obligated to use this value.
|
|
However, it is recommended that implementations that do not handle
|
|
property strings return an error on receiving this parameter unless
|
|
its value NULL or the empty string.
|
|
|
|
=item "passphrase" (B<OSSL_SERIALIZER_PARAM_PASS>) <octet string>
|
|
|
|
A pass phrase provided by the application. When this is given, the
|
|
built-in serializers will not attempt to use the passphrase callback.
|
|
|
|
=back
|
|
|
|
Parameters currently recognised by the built-in pass phrase callback:
|
|
|
|
=over 4
|
|
|
|
=item "info" (B<OSSL_PASSPHRASE_PARAM_INFO>) <UTF8 string>
|
|
|
|
A string of information that will become part of the pass phrase
|
|
prompt. This could be used to give the user information on what kind
|
|
of object it's being prompted for.
|
|
|
|
=back
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
OP_serializer_newctx() returns a pointer to a context, or NULL on
|
|
failure.
|
|
|
|
OP_serializer_set_ctx_params() returns 1, unless a recognised
|
|
parameters was invalid or caused an error, for which 0 is returned.
|
|
|
|
OP_serializer_settable_ctx_params() returns a pointer to an array of
|
|
constant B<OSSL_PARAM> elements.
|
|
|
|
OP_serializer_serialize_data() and OP_serializer_serialize_object()
|
|
return 1 on success, or 0 on failure.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<provider(7)>
|
|
|
|
=head1 HISTORY
|
|
|
|
The SERIALIZER interface was introduced in OpenSSL 3.0.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2019 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
|