mirror of
https://github.com/openssl/openssl.git
synced 2024-12-15 06:01:37 +08:00
0d003c52d3
Serialization is needed to be able to take a provider object (such as
the provider side key data) and output it in PEM form, DER form, text
form (for display), and possibly other future forms (XML? JSON? JWK?)
The idea is that a serializer should be able to handle objects it has
intimate knowledge of, as well as object data in OSSL_PARAM form. The
latter will allow libcrypto to serialize some object with a different
provider than the one holding the data, if exporting of that data is
allowed and there is a serializer that can handle it.
We will provide serializers for the types of objects we know about,
which should be useful together with any other provider that provides
implementations of the same type of object.
Serializers are selected by method name and a couple of additional
properties:
- format used to tell what format the output should be in.
Possibilities could include "format=text",
"format=pem", "format=der", "format=pem-pkcs1"
(traditional), "format=der-pkcs1" (traditional)
- type used to tell exactly what type of data should be
output, for example "type=public" (the public part of
a key), "type=private" (the private part of a key),
"type=domainparams" (domain parameters).
This also adds a passphrase callback function type,
OSSL_PASSPHRASE_CALLBACK, which is a bit like OSSL_CALLBACK, but it
takes a few extra arguments to place the result in.
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10394)
95 lines
3.0 KiB
Plaintext
95 lines
3.0 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
OSSL_SERIALIZER_CTX,
|
|
OSSL_SERIALIZER_CTX_new,
|
|
OSSL_SERIALIZER_CTX_get_serializer,
|
|
OSSL_SERIALIZER_settable_ctx_params,
|
|
OSSL_SERIALIZER_CTX_set_params,
|
|
OSSL_SERIALIZER_CTX_free
|
|
- Serializer context routines
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/serializer.h>
|
|
|
|
typedef struct ossl_serializer_ctx_st OSSL_SERIALIZER_CTX;
|
|
|
|
OSSL_SERIALIZER_CTX *OSSL_SERIALIZER_CTX_new(OSSL_SERIALIZER *ser);
|
|
const OSSL_SERIALIZER *
|
|
OSSL_SERIALIZER_CTX_get_serializer(OSSL_SERIALIZER_CTX *ctx);
|
|
const OSSL_PARAM *OSSL_SERIALIZER_settable_ctx_params(OSSL_SERIALIZER *ser);
|
|
int OSSL_SERIALIZER_CTX_set_params(OSSL_SERIALIZER_CTX *ctx,
|
|
const OSSL_PARAM params[]);
|
|
void OSSL_SERIALIZER_CTX_free(OSSL_SERIALIZER_CTX *ctx);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
B<OSSL_SERIALIZER_CTX> is a context with which B<OSSL_SERIALIZER>
|
|
operations are performed. The context typically holds values, both
|
|
internal and supplied by the application, which are useful for the
|
|
implementations supplied by providers.
|
|
|
|
OSSL_SERIALIZER_CTX_new() creates a B<OSSL_SERIALIZER_CTX> associated
|
|
with the serializer I<ser>. NULL is a valid I<ser>, the context will
|
|
be created anyway, it's just not very useful. This is intentional, to
|
|
distinguish between errors in allocating the context or assigning it
|
|
values on one hand, and the lack of serializer support on the other.
|
|
|
|
=begin comment
|
|
|
|
The above distinction makes it possible for other routines to sense if
|
|
they need to report an error or fall back on other methods to
|
|
serialize.
|
|
|
|
=end comment
|
|
|
|
OSSL_SERIALIZER_CTX_get_serializer() gets the serializer method
|
|
currently associated with the context I<ctx>.
|
|
|
|
OSSL_SERIALIZER_settable_ctx_params() returns an L<OSSL_PARAM(3)>
|
|
array of parameter descriptors.
|
|
|
|
OSSL_SERIALIZER_CTX_set_params() attempts to set parameters specified
|
|
with an L<OSSL_PARAM(3)> array I<params>. Parameters that the
|
|
implementation doesn't recognise should be ignored.
|
|
|
|
OSSL_SERIALIZER_CTX_free() frees the given context I<ctx>.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
OSSL_SERIALIZER_CTX_new() returns a pointer to a
|
|
B<OSSL_SERIALIZER_CTX>, or NULL if the context structure couldn't be
|
|
allocated.
|
|
|
|
OSSL_SERIALIZER_CTX_get_serializer() returns a pointer to the
|
|
serializer method associated with I<ctx>. NULL is a valid return
|
|
value and signifies that there is no associated serializer method.
|
|
|
|
OSSL_SERIALIZER_settable_ctx_params() returns an L<OSSL_PARAM(3)>
|
|
array, or NULL if none is available.
|
|
|
|
OSSL_SERIALIZER_CTX_set_params() returns 1 if all recognised
|
|
parameters were valid, or 0 if one of them was invalid or caused some
|
|
other failure in the implementation.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<provider(7)>, L<OSSL_SERIALIZER(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
The functions described here were added 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
|