QuasarApp/openssl
4
0
Fork 0
mirror of https://github.com/QuasarApp/openssl.git synced 2025-04-28 18:54:36 +00:00
Code Issues Projects Releases Wiki Activity

SERIALIZER: New API for serialization of objects through providers

Browse Source 
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)
This commit is contained in:
Richard Levitte 2019-11-18 01:29:06 +01:00
parent 36fa4d8a0d
commit 0d003c52d3
22 changed files with 1165 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
crypto/build.info
View File

@ -5,7 +5,7 @@ SUBDIRS=objects buffer bio stack lhash rand evp asn1 pem x509 conf \
md2 md4 md5 sha mdc2 hmac ripemd whrlpool poly1305 \
siphash sm3 des aes rc2 rc4 rc5 idea aria bf cast camellia \
seed sm4 chacha modes bn ec rsa dsa dh sm2 dso engine \
err comp ocsp cms ts srp cmac ct async ess crmf cmp
err comp ocsp cms ts srp cmac ct async ess crmf cmp serializer
LIBS=../libcrypto

2
crypto/err/err.c
View File

@ -75,6 +75,7 @@ static ERR_STRING_DATA ERR_str_libraries[] = {
{ERR_PACK(ERR_LIB_SM2, 0, 0), "SM2 routines"},
{ERR_PACK(ERR_LIB_ESS, 0, 0), "ESS routines"},
{ERR_PACK(ERR_LIB_PROV, 0, 0), "Provider routines"},
{ERR_PACK(ERR_LIB_OSSL_SERIALIZER, 0, 0), "SERIALIZER routines"},
{0, NULL},
};
@ -111,6 +112,7 @@ static ERR_STRING_DATA ERR_str_reasons[] = {
{ERR_R_DISABLED, "called a function that was disabled at compile-time"},
{ERR_R_INIT_FAIL, "init fail"},
{ERR_R_OPERATION_FAIL, "operation fail"},
{ERR_R_INVALID_PROVIDER_FUNCTIONS, "invalid provider functions"},
{0, NULL},
};

1
crypto/err/openssl.ec
View File

@ -40,6 +40,7 @@ L OSSL_STORE include/openssl/store.h crypto/store/store_err.c
L ESS include/openssl/ess.h crypto/ess/ess_err.c
L PROP include/internal/property.h crypto/property/property_err.c
L PROV providers/common/include/prov/providercommon.h providers/common/provider_err.c
L OSSL_SERIALIZER include/openssl/serializer.h crypto/serializer/serializer_err.c
# additional header files to be scanned for function names
L NONE include/openssl/x509_vfy.h NONE

2
crypto/property/property_parse.c
View File

@ -568,6 +568,8 @@ int ossl_property_parse_init(OPENSSL_CTX *ctx)
"version", /* Version number of this provider */
"fips", /* FIPS supporting provider */
"engine", /* An old style engine masquerading as a provider */
"format", /* output format for serializers */
"type", /* output type for serializers */
};
size_t i;

1
crypto/serializer/build.info Normal file
View File

@ -0,0 +1 @@
SOURCE[../../libcrypto]=serializer_meth.c

34
crypto/serializer/serializer_local.h Normal file
View File

@ -0,0 +1,34 @@
/*
* 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
* https://www.openssl.org/source/license.html
*/
#include <openssl/core_numbers.h>
#include <openssl/types.h>
#include "internal/cryptlib.h"
#include "internal/refcount.h"
struct ossl_serializer_st {
OSSL_PROVIDER *prov;
int id;
const char *propdef;
CRYPTO_REF_COUNT refcnt;
CRYPTO_RWLOCK *lock;
OSSL_OP_serializer_newctx_fn *newctx;
OSSL_OP_serializer_freectx_fn *freectx;
OSSL_OP_serializer_set_ctx_params_fn *set_ctx_params;
OSSL_OP_serializer_settable_ctx_params_fn *settable_ctx_params;
OSSL_OP_serializer_serialize_data_fn *serialize_data;
OSSL_OP_serializer_serialize_object_fn *serialize_object;
};
struct ossl_serializer_ctx_st {
OSSL_SERIALIZER *ser;
void *serctx;
};

514
crypto/serializer/serializer_meth.c Normal file
View File

@ -0,0 +1,514 @@
/*
* 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
* https://www.openssl.org/source/license.html
*/
#include <openssl/core.h>
#include <openssl/core_numbers.h>
#include <openssl/serializer.h>
#include "internal/core.h"
#include "internal/namemap.h"
#include "internal/property.h"
#include "internal/provider.h"
#include "crypto/serializer.h"
#include "serializer_local.h"
/*
* Serializer can have multiple names, separated with colons in a name string
*/
#define NAME_SEPARATOR ':'
/* Simple method structure constructor and destructor */
static OSSL_SERIALIZER *ossl_serializer_new(void)
{
OSSL_SERIALIZER *ser = NULL;
if ((ser = OPENSSL_zalloc(sizeof(*ser))) == NULL
|| (ser->lock = CRYPTO_THREAD_lock_new()) == NULL) {
OSSL_SERIALIZER_free(ser);
ERR_raise(ERR_LIB_OSSL_SERIALIZER, ERR_R_MALLOC_FAILURE);
return NULL;
}
ser->refcnt = 1;
return ser;
}
int OSSL_SERIALIZER_up_ref(OSSL_SERIALIZER *ser)
{
int ref = 0;
CRYPTO_UP_REF(&ser->refcnt, &ref, ser->lock);
return 1;
}
void OSSL_SERIALIZER_free(OSSL_SERIALIZER *ser)
{
int ref = 0;
if (ser == NULL)
return;
CRYPTO_DOWN_REF(&ser->refcnt, &ref, ser->lock);
if (ref > 0)
return;
ossl_provider_free(ser->prov);
CRYPTO_THREAD_lock_free(ser->lock);
OPENSSL_free(ser);
}
/* Permanent serializer method store, constructor and destructor */
static void serializer_store_free(void *vstore)
{
ossl_method_store_free(vstore);
}
static void *serializer_store_new(OPENSSL_CTX *ctx)
{
return ossl_method_store_new(ctx);
}
static const OPENSSL_CTX_METHOD serializer_store_method = {
serializer_store_new,
serializer_store_free,
};
/* Data to be passed through ossl_method_construct() */
struct serializer_data_st {
OPENSSL_CTX *libctx;
OSSL_METHOD_CONSTRUCT_METHOD *mcm;
int id; /* For get_serializer_from_store() */
const char *names; /* For get_serializer_from_store() */
const char *propquery; /* For get_serializer_from_store() */
};
/*
* Generic routines to fetch / create SERIALIZER methods with
* ossl_method_construct()
*/
/* Temporary serializer method store, constructor and destructor */
static void *alloc_tmp_serializer_store(OPENSSL_CTX *ctx)
{
return ossl_method_store_new(ctx);
}
static void dealloc_tmp_serializer_store(void *store)
{
if (store != NULL)
ossl_method_store_free(store);
}
/* Get the permanent serializer store */
static OSSL_METHOD_STORE *get_serializer_store(OPENSSL_CTX *libctx)
{
return openssl_ctx_get_data(libctx, OPENSSL_CTX_SERIALIZER_STORE_INDEX,
&serializer_store_method);
}
/* Get serializer methods from a store, or put one in */
static void *get_serializer_from_store(OPENSSL_CTX *libctx, void *store,
void *data)
{
struct serializer_data_st *methdata = data;
void *method = NULL;
int id;
if ((id = methdata->id) == 0) {
OSSL_NAMEMAP *namemap = ossl_namemap_stored(libctx);
id = ossl_namemap_name2num(namemap, methdata->names);
}
if (store == NULL
&& (store = get_serializer_store(libctx)) == NULL)
return NULL;
if (!ossl_method_store_fetch(store, id, methdata->propquery, &method))
return NULL;
return method;
}
static int put_serializer_in_store(OPENSSL_CTX *libctx, void *store,
void *method, const OSSL_PROVIDER *prov,
int operation_id, const char *names,
const char *propdef, void *unused)
{
OSSL_NAMEMAP *namemap;
int id;
if ((namemap = ossl_namemap_stored(libctx)) == NULL
|| (id = ossl_namemap_name2num(namemap, names)) == 0)
return 0;
if (store == NULL && (store = get_serializer_store(libctx)) == NULL)
return 0;
return ossl_method_store_add(store, prov, id, propdef, method,
(int (*)(void *))OSSL_SERIALIZER_up_ref,
(void (*)(void *))OSSL_SERIALIZER_free);
}
/* Create and populate a serializer method */
static void *serializer_from_dispatch(int id, const OSSL_ALGORITHM *algodef,
OSSL_PROVIDER *prov)
{
OSSL_SERIALIZER *ser = NULL;
const OSSL_DISPATCH *fns = algodef->implementation;
if ((ser = ossl_serializer_new()) == NULL)
return NULL;
ser->id = id;
ser->propdef = algodef->property_definition;
for (; fns->function_id != 0; fns++) {
switch (fns->function_id) {
case OSSL_FUNC_SERIALIZER_NEWCTX:
if (ser->newctx == NULL)
ser->newctx =
OSSL_get_OP_serializer_newctx(fns);
break;
case OSSL_FUNC_SERIALIZER_FREECTX:
if (ser->freectx == NULL)
ser->freectx =
OSSL_get_OP_serializer_freectx(fns);
break;
case OSSL_FUNC_SERIALIZER_SET_CTX_PARAMS:
if (ser->set_ctx_params == NULL)
ser->set_ctx_params =
OSSL_get_OP_serializer_set_ctx_params(fns);
break;
case OSSL_FUNC_SERIALIZER_SETTABLE_CTX_PARAMS:
if (ser->settable_ctx_params == NULL)
ser->settable_ctx_params =
OSSL_get_OP_serializer_settable_ctx_params(fns);
break;
case OSSL_FUNC_SERIALIZER_SERIALIZE_DATA:
if (ser->serialize_data == NULL)
ser->serialize_data =
OSSL_get_OP_serializer_serialize_data(fns);
break;
case OSSL_FUNC_SERIALIZER_SERIALIZE_OBJECT:
if (ser->serialize_object == NULL)
ser->serialize_object =
OSSL_get_OP_serializer_serialize_object(fns);
break;
}
}
/*
* Try to check that the method is sensible.
* If you have a constructor, you must have a destructor and vice versa.
* You must have at least one of the serializing driver functions.
*/
if (!((ser->newctx == NULL && ser->freectx == NULL)
|| (ser->newctx != NULL && ser->freectx != NULL))
|| (ser->serialize_data == NULL && ser->serialize_object == NULL)) {
OSSL_SERIALIZER_free(ser);
ERR_raise(ERR_LIB_OSSL_SERIALIZER, ERR_R_INVALID_PROVIDER_FUNCTIONS);
return NULL;
}
if (prov != NULL && !ossl_provider_up_ref(prov)) {
OSSL_SERIALIZER_free(ser);
return NULL;
}
ser->prov = prov;
return ser;
}
/*
* The core fetching functionality passes the names of the implementation.
* This function is responsible to getting an identity number for them,
* then call serializer_from_dispatch() with that identity number.
*/
static void *construct_serializer(const OSSL_ALGORITHM *algodef,
OSSL_PROVIDER *prov, void *unused)
{
/*
* This function is only called if get_serializer_from_store() returned
* NULL, so it's safe to say that of all the spots to create a new
* namemap entry, this is it. Should the name already exist there, we
* know that ossl_namemap_add() will return its corresponding number.
*/
OPENSSL_CTX *libctx = ossl_provider_library_context(prov);
OSSL_NAMEMAP *namemap = ossl_namemap_stored(libctx);
const char *names = algodef->algorithm_names;
int id = ossl_namemap_add_names(namemap, 0, names, NAME_SEPARATOR);
void *method = NULL;
if (id != 0)
method = serializer_from_dispatch(id, algodef, prov);
return method;
}
/* Intermediary function to avoid ugly casts, used below */
static void destruct_serializer(void *method, void *data)
{
OSSL_SERIALIZER_free(method);
}
static int up_ref_serializer(void *method)
{
return OSSL_SERIALIZER_up_ref(method);
}
static void free_serializer(void *method)
{
OSSL_SERIALIZER_free(method);
}
/* Fetching support. Can fetch by numeric identity or by name */
static OSSL_SERIALIZER *inner_ossl_serializer_fetch(OPENSSL_CTX *libctx,
int id, const char *name,
const char *properties)
{
OSSL_METHOD_STORE *store = get_serializer_store(libctx);
OSSL_NAMEMAP *namemap = ossl_namemap_stored(libctx);
void *method = NULL;
if (store == NULL || namemap == NULL)
return NULL;
/*
* If we have been passed neither a name_id or a name, we have an
* internal programming error.
*/
if (!ossl_assert(id != 0 || name != NULL))
return NULL;
if (id == 0)
id = ossl_namemap_name2num(namemap, name);
if (id == 0
|| !ossl_method_store_cache_get(store, id, properties, &method)) {
OSSL_METHOD_CONSTRUCT_METHOD mcm = {
alloc_tmp_serializer_store,
dealloc_tmp_serializer_store,
get_serializer_from_store,
put_serializer_in_store,
construct_serializer,
destruct_serializer
};
struct serializer_data_st mcmdata;
mcmdata.libctx = libctx;
mcmdata.mcm = &mcm;
mcmdata.id = id;
mcmdata.names = name;
mcmdata.propquery = properties;
if ((method = ossl_method_construct(libctx, OSSL_OP_SERIALIZER,
0 /* !force_cache */,
&mcm, &mcmdata)) != NULL) {
/*
* If construction did create a method for us, we know that
* there is a correct name_id and meth_id, since those have
* already been calculated in get_serializer_from_store() and
* put_serializer_in_store() above.
*/
if (id == 0)
id = ossl_namemap_name2num(namemap, name);
ossl_method_store_cache_set(store, id, properties, method,
up_ref_serializer, free_serializer);
}
}
return method;
}
OSSL_SERIALIZER *OSSL_SERIALIZER_fetch(OPENSSL_CTX *libctx, const char *name,
const char *properties)
{
return inner_ossl_serializer_fetch(libctx, 0, name, properties);
}
OSSL_SERIALIZER *ossl_serializer_fetch_by_number(OPENSSL_CTX *libctx, int id,
const char *properties)
{
return inner_ossl_serializer_fetch(libctx, id, NULL, properties);
}
/*
* Library of basic method functions
*/
const OSSL_PROVIDER *OSSL_SERIALIZER_provider(const OSSL_SERIALIZER *ser)
{
if (!ossl_assert(ser != NULL)) {
ERR_raise(ERR_LIB_OSSL_SERIALIZER, ERR_R_PASSED_NULL_PARAMETER);
return 0;
}
return ser->prov;
}
const char *OSSL_SERIALIZER_properties(const OSSL_SERIALIZER *ser)
{
if (!ossl_assert(ser != NULL)) {
ERR_raise(ERR_LIB_OSSL_SERIALIZER, ERR_R_PASSED_NULL_PARAMETER);
return 0;
}
return ser->propdef;
}
int OSSL_SERIALIZER_number(const OSSL_SERIALIZER *ser)
{
if (!ossl_assert(ser != NULL)) {
ERR_raise(ERR_LIB_OSSL_SERIALIZER, ERR_R_PASSED_NULL_PARAMETER);
return 0;
}
return ser->id;
}
int OSSL_SERIALIZER_is_a(const OSSL_SERIALIZER *ser, const char *name)
{
if (ser->prov != NULL) {
OPENSSL_CTX *libctx = ossl_provider_library_context(ser->prov);
OSSL_NAMEMAP *namemap = ossl_namemap_stored(libctx);
return ossl_namemap_name2num(namemap, name) == ser->id;
}
return 0;
}
struct serializer_do_all_data_st {
void (*user_fn)(void *method, void *arg);
void *user_arg;
};
static void serializer_do_one(OSSL_PROVIDER *provider,
const OSSL_ALGORITHM *algodef,
int no_store, void *vdata)
{
struct serializer_do_all_data_st *data = vdata;
OPENSSL_CTX *libctx = ossl_provider_library_context(provider);
OSSL_NAMEMAP *namemap = ossl_namemap_stored(libctx);
const char *names = algodef->algorithm_names;
int id = ossl_namemap_add_names(namemap, 0, names, NAME_SEPARATOR);
void *method = NULL;
if (id != 0)
method =
serializer_from_dispatch(id, algodef, provider);
if (method != NULL) {
data->user_fn(method, data->user_arg);
OSSL_SERIALIZER_free(method);
}
}
void OSSL_SERIALIZER_do_all_provided(OPENSSL_CTX *libctx,
void (*fn)(OSSL_SERIALIZER *ser,
void *arg),
void *arg)
{
struct serializer_do_all_data_st data;
data.user_fn = (void (*)(void *, void *))fn;
data.user_arg = arg;
ossl_algorithm_do_all(libctx, OSSL_OP_SERIALIZER, NULL,
serializer_do_one, &data);
}
void OSSL_SERIALIZER_names_do_all(const OSSL_SERIALIZER *ser,
void (*fn)(const char *name, void *data),
void *data)
{
if (ser == NULL)
return;
if (ser->prov != NULL) {
OPENSSL_CTX *libctx = ossl_provider_library_context(ser->prov);
OSSL_NAMEMAP *namemap = ossl_namemap_stored(libctx);
ossl_namemap_doall_names(namemap, ser->id, fn, data);
}
}
const OSSL_PARAM *OSSL_SERIALIZER_settable_ctx_params(OSSL_SERIALIZER *ser)
{
if (ser != NULL && ser->settable_ctx_params != NULL)
return ser->settable_ctx_params();
return NULL;
}
/*
* Serializer context support
*/
/*
* |ser| value NULL is valid, and signifies that there is no serializer.
* This is useful to provide fallback mechanisms.
* Funtions that want to verify if there is a serializer can do so with
* OSSL_SERIALIZER_CTX_get_serializer()
*/
OSSL_SERIALIZER_CTX *OSSL_SERIALIZER_CTX_new(OSSL_SERIALIZER *ser)
{
OSSL_SERIALIZER_CTX *ctx;
if ((ctx = OPENSSL_zalloc(sizeof(*ctx))) == NULL) {
ERR_raise(ERR_LIB_OSSL_SERIALIZER, ERR_R_MALLOC_FAILURE);
return NULL;
}
ctx->ser = ser;
if (ser != NULL && ser->newctx != NULL) {
const OSSL_PROVIDER *prov = OSSL_SERIALIZER_provider(ser);
void *provctx = ossl_provider_ctx(prov);
if (OSSL_SERIALIZER_up_ref(ser)) {
ctx->serctx = ser->newctx(provctx);
} else {
OSSL_SERIALIZER_free(ser);
OPENSSL_free(ctx);
ctx = NULL;
}
}
return ctx;
}
const OSSL_SERIALIZER *
OSSL_SERIALIZER_CTX_get_serializer(OSSL_SERIALIZER_CTX *ctx)
{
if (!ossl_assert(ctx != NULL)) {
ERR_raise(ERR_LIB_OSSL_SERIALIZER, ERR_R_PASSED_NULL_PARAMETER);
return 0;
}
return ctx->ser;
}
int OSSL_SERIALIZER_CTX_set_params(OSSL_SERIALIZER_CTX *ctx,
const OSSL_PARAM params[])
{
if (!ossl_assert(ctx != NULL)) {
ERR_raise(ERR_LIB_OSSL_SERIALIZER, ERR_R_PASSED_NULL_PARAMETER);
return 0;
}
if (ctx->ser != NULL && ctx->ser->set_ctx_params != NULL)
return ctx->ser->set_ctx_params(ctx->serctx, params);
return 0;
}
void OSSL_SERIALIZER_CTX_free(OSSL_SERIALIZER_CTX *ctx)
{
if (ctx != NULL) {
if (ctx->ser != NULL && ctx->ser->freectx != NULL)
ctx->ser->freectx(ctx->serctx);
OSSL_SERIALIZER_free(ctx->ser);
OPENSSL_free(ctx);
}
}

128
doc/man3/OSSL_SERIALIZER.pod Normal file
View File

@ -0,0 +1,128 @@
=pod
=head1 NAME
OSSL_SERIALIZER,
OSSL_SERIALIZER_fetch,
OSSL_SERIALIZER_up_ref,
OSSL_SERIALIZER_free,
OSSL_SERIALIZER_provider,
OSSL_SERIALIZER_properties,
OSSL_SERIALIZER_is_a,
OSSL_SERIALIZER_number,
OSSL_SERIALIZER_do_all_provided,
OSSL_SERIALIZER_names_do_all
- Serializer method routines
=head1 SYNOPSIS
#include <openssl/serializer.h>
typedef struct ossl_serializer_st OSSL_SERIALIZER;
OSSL_SERIALIZER *OSSL_SERIALIZER_fetch(OPENSSL_CTX *ctx, const char *name,
const char *properties);
int OSSL_SERIALIZER_up_ref(OSSL_SERIALIZER *serializer);
void OSSL_SERIALIZER_free(OSSL_SERIALIZER *serializer);
const OSSL_PROVIDER *OSSL_SERIALIZER_provider(const OSSL_SERIALIZER
*serializer);
const char *OSSL_SERIALIZER_properties(const OSSL_SERIALIZER *ser);
int OSSL_SERIALIZER_is_a(const OSSL_SERIALIZER *serializer,
const char *name);
int OSSL_SERIALIZER_number(const OSSL_SERIALIZER *serializer);
void OSSL_SERIALIZER_do_all_provided(OPENSSL_CTX *libctx,
void (*fn)(OSSL_SERIALIZER *serializer,
void *arg),
void *arg);
void OSSL_SERIALIZER_names_do_all(const OSSL_SERIALIZER *serializer,
void (*fn)(const char *name, void *data),
void *data);
=head1 DESCRIPTION
=for comment Future development should also talk about deserialization
B<OSSL_SERIALIZER> is a method for serializers, which know how to
serialize an object of some kind to a serialized form, such as PEM,
DER, or even human readable text.
OSSL_SERIALIZER_fetch() looks for an algorithm within the provider that
has been loaded into the B<OPENSSL_CTX> given by I<ctx>, having the
name given by I<name> and the properties given by I<properties>.
The I<name> determines what type of object the fetched serializer
method is expected to be able to serialize, and the properties are
used to determine the expected output type.
For known properties and the values they may have, please have a look
in L<provider-serializer(7)/Names and properties>.
OSSL_SERIALIZER_up_ref() increments the reference count for the given
I<serializer>.
OSSL_SERIALIZER_free() decrements the reference count for the given
I<serializer>, and when the count reaches zero, frees it.
OSSL_SERIALIZER_provider() returns the provider of the given
I<serializer>.
OSSL_SERIALIZER_provider() returns the property definition associated
with the given I<serializer>.
OSSL_SERIALIZER_is_a() checks if I<serializer> is an implementation of an
algorithm that's identifiable with I<name>.
OSSL_SERIALIZER_number() returns the internal dynamic number assigned to
the given I<serializer>.
OSSL_SERIALIZER_names_do_all() traverses all names for the given
I<serializer>, and calls I<fn> with each name and I<data>.
OSSL_SERIALIZER_do_all_provided() traverses all serializer
implementations by all activated providers in the library context
I<libctx>, and for each of the implementations, calls I<fn> with the
implementation method and I<data> as arguments.
=head1 NOTES
OSSL_SERIALIZER_fetch() may be called implicitly by other fetching
functions, using the same library context and properties.
Any other API that uses keys will typically do this.
=head1 RETURN VALUES
OSSL_SERIALIZER_fetch() returns a pointer to the key management
implementation represented by an OSSL_SERIALIZER object, or NULL on
error.
OSSL_SERIALIZER_up_ref() returns 1 on success, or 0 on error.
OSSL_SERIALIZER_free() doesn't return any value.
OSSL_SERIALIZER_provider() returns a pointer to a provider object, or
NULL on error.
OSSL_SERIALIZER_properties() returns a pointer to a property
definition string, or NULL on error.
OSSL_SERIALIZER_is_a() returns 1 of I<serializer> was identifiable,
otherwise 0.
OSSL_SERIALIZER_number() returns an integer.
=head1 SEE ALSO
L<provider(7)>, L<OSSL_SERIALIZER_CTX(3)>, L<OPENSSL_CTX(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

94
doc/man3/OSSL_SERIALIZER_CTX.pod Normal file
View File

@ -0,0 +1,94 @@
=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

23
doc/man7/openssl-core.h.pod
View File

@ -76,7 +76,7 @@ B<OSSL_PARAM> is further described in L<OSSL_PARAM(3)>
=item B<OSSL_CALLBACK>
This is a function type for a generic callback function:
This is a function type for a generic feedback callback function:
typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);
@ -86,6 +86,27 @@ expected to build an B<OSSL_PARAM> array of data it wants or is
expected to pass back, and pass that as I<params>, as well as
the caller data pointer it received, as I<arg>.
=item B<OSSL_PASSPHRASE_CALLBACK>
This is a function type for a generic pass phrase callback function:
typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size,
size_t *pass_len,
const OSSL_PARAM params[],
void *arg);
This callback can be used to prompt the user for a passphrase. When
calling it, a buffer to store the pass phrase needs to be given with
I<pass>, and its size with I<pass_size>. The length of the prompted
pass phrase will be given back in I<*pass_len>.
Additional parameters can be passed with the B<OSSL_PARAM> array
I<params>.
A function that takes a pointer of this type should also take a
pointer to caller data, which should be passed as I<arg> to this
callback.
=back
=head1 SEE ALSO

227
doc/man7/provider-serializer.pod Normal file
View File

@ -0,0 +1,227 @@
=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.
=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

8
doc/man7/provider.pod
View File

@ -147,6 +147,14 @@ The number for this operation is B<OSSL_OP_KEYEXCH>.
The functions the provider can offer are described in
L<provider-keyexch(7)>
=item Serialization
In the OpenSSL libraries, the corresponding method object is
B<OSSL_SERIALIZER>.
The number for this operation is B<OSSL_OP_SERIALIZER>.
The functions the provider can offer are described in
L<provider-serializer(7)>
=back
=head2 Fetching algorithms

13
include/crypto/serializer.h Normal file
View File

@ -0,0 +1,13 @@
/*
* 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
* https://www.openssl.org/source/license.html
*/
#include <openssl/types.h>
OSSL_SERIALIZER *ossl_serializer_fetch_by_number(OPENSSL_CTX *libctx, int id,
const char *properties);

3
include/internal/cryptlib.h
View File

@ -154,7 +154,8 @@ typedef struct ossl_ex_data_global_st {
# define OPENSSL_CTX_RAND_CRNGT_INDEX 7
# define OPENSSL_CTX_THREAD_EVENT_HANDLER_INDEX 8
# define OPENSSL_CTX_FIPS_PROV_INDEX 9
# define OPENSSL_CTX_MAX_INDEXES 10
# define OPENSSL_CTX_SERIALIZER_STORE_INDEX 10
# define OPENSSL_CTX_MAX_INDEXES 11
typedef struct openssl_ctx_method {
void *(*new_func)(OPENSSL_CTX *ctx);

10
include/openssl/core.h
View File

@ -202,6 +202,16 @@ extern OSSL_provider_init_fn OSSL_provider_init;
*/
typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);
/*
* Passphrase callback function signature
*
* This is similar to the generic callback function above, but adds a
* result parameter.
*/
typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size,
size_t *pass_len,
const OSSL_PARAM params[], void *arg);
# ifdef __cplusplus
}
# endif

25
include/openssl/core_numbers.h
View File

@ -160,8 +160,10 @@ OSSL_CORE_MAKE_FUNC(const OSSL_ITEM *,provider_get_reason_strings,
# define OSSL_OP_KEYEXCH 11
# define OSSL_OP_SIGNATURE 12
# define OSSL_OP_ASYM_CIPHER 13
/* New section for non-EVP operations */
# define OSSL_OP_SERIALIZER 20
/* Highest known operation number */
# define OSSL_OP__HIGHEST 13
# define OSSL_OP__HIGHEST 20
/* Digests */
@ -534,6 +536,27 @@ OSSL_CORE_MAKE_FUNC(int, OP_asym_cipher_set_ctx_params,
OSSL_CORE_MAKE_FUNC(const OSSL_PARAM *, OP_asym_cipher_settable_ctx_params,
(void))
/* Serializers */
# define OSSL_FUNC_SERIALIZER_NEWCTX 1
# define OSSL_FUNC_SERIALIZER_FREECTX 2
# define OSSL_FUNC_SERIALIZER_SET_CTX_PARAMS 3
# define OSSL_FUNC_SERIALIZER_SETTABLE_CTX_PARAMS 4
# define OSSL_FUNC_SERIALIZER_SERIALIZE_DATA 10
# define OSSL_FUNC_SERIALIZER_SERIALIZE_OBJECT 11
OSSL_CORE_MAKE_FUNC(void *, OP_serializer_newctx, (void *provctx))
OSSL_CORE_MAKE_FUNC(void, OP_serializer_freectx, (void *ctx))
OSSL_CORE_MAKE_FUNC(int, OP_serializer_set_ctx_params,
(void *ctx, const OSSL_PARAM params[]))
OSSL_CORE_MAKE_FUNC(const OSSL_PARAM *, OP_serializer_settable_ctx_params,
(void))
OSSL_CORE_MAKE_FUNC(int, OP_serializer_serialize_data,
(void *ctx, const OSSL_PARAM[], BIO *out,
OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg))
OSSL_CORE_MAKE_FUNC(int, OP_serializer_serialize_object,
(void *ctx, void *obj, BIO *out,
OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg))
# ifdef __cplusplus
}
# endif

2
include/openssl/err.h
View File

@ -112,6 +112,7 @@ struct err_state_st {
# define ERR_LIB_CRMF 56
# define ERR_LIB_PROV 57
# define ERR_LIB_CMP 58
# define ERR_LIB_OSSL_SERIALIZER 59
# define ERR_LIB_USER 128
@ -231,6 +232,7 @@ struct err_state_st {
# define ERR_R_INIT_FAIL (6|ERR_R_FATAL)
# define ERR_R_PASSED_INVALID_ARGUMENT (7)
# define ERR_R_OPERATION_FAIL (8|ERR_R_FATAL)
# define ERR_R_INVALID_PROVIDER_FUNCTIONS (9|ERR_R_FATAL)
/*
* 99 is the maximum possible ERR_R_... code, higher values are reserved for

1
include/openssl/pem.h
View File

@ -261,7 +261,6 @@ extern "C" {
# define DECLARE_PEM_rw_cb(name, type) \
DECLARE_PEM_read(name, type) \
DECLARE_PEM_write_cb(name, type)
typedef int pem_password_cb (char *buf, int size, int rwflag, void *userdata);
int PEM_get_EVP_CIPHER_INFO(char *header, EVP_CIPHER_INFO *cipher);
int PEM_do_header(EVP_CIPHER_INFO *cipher, unsigned char *data, long *len,

59
include/openssl/serializer.h Normal file
View File

@ -0,0 +1,59 @@
/*
* 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
* https://www.openssl.org/source/license.html
*/
#ifndef OPENSSL_SERIALIZER_H
# define OPENSSL_SERIALIZER_H
# pragma once
# include <openssl/opensslconf.h>
# ifndef OPENSSL_NO_STDIO
# include <stdio.h>
# endif
# include <stdarg.h>
# include <stddef.h>
# include <openssl/types.h>
# include <openssl/core.h>
# ifdef __cplusplus
extern "C" {
# endif
OSSL_SERIALIZER *OSSL_SERIALIZER_fetch(OPENSSL_CTX *libctx,
const char *name,
const char *properties);
int OSSL_SERIALIZER_up_ref(OSSL_SERIALIZER *ser);
void OSSL_SERIALIZER_free(OSSL_SERIALIZER *ser);
const OSSL_PROVIDER *OSSL_SERIALIZER_provider(const OSSL_SERIALIZER *ser);
const char *OSSL_SERIALIZER_properties(const OSSL_SERIALIZER *ser);
int OSSL_SERIALIZER_number(const OSSL_SERIALIZER *ser);
int OSSL_SERIALIZER_is_a(const OSSL_SERIALIZER *ser,
const char *name);
void OSSL_SERIALIZER_do_all_provided(OPENSSL_CTX *libctx,
void (*fn)(OSSL_SERIALIZER *ser,
void *arg),
void *arg);
void OSSL_SERIALIZER_names_do_all(const OSSL_SERIALIZER *ser,
void (*fn)(const char *name, void *data),
void *data);
const OSSL_PARAM *OSSL_SERIALIZER_settable_ctx_params(OSSL_SERIALIZER *ser);
OSSL_SERIALIZER_CTX *OSSL_SERIALIZER_CTX_new(OSSL_SERIALIZER *ser);
const OSSL_SERIALIZER *
OSSL_SERIALIZER_CTX_get_serializer(OSSL_SERIALIZER_CTX *ctx);
int OSSL_SERIALIZER_CTX_set_params(OSSL_SERIALIZER_CTX *ctx,
const OSSL_PARAM params[]);
void OSSL_SERIALIZER_CTX_free(OSSL_SERIALIZER_CTX *ctx);
# ifdef __cplusplus
}
# endif
#endif

5
include/openssl/types.h
View File

@ -203,6 +203,11 @@ typedef struct ossl_item_st OSSL_ITEM;
typedef struct ossl_algorithm_st OSSL_ALGORITHM;
typedef struct ossl_param_st OSSL_PARAM;
typedef int pem_password_cb (char *buf, int size, int rwflag, void *userdata);
typedef struct ossl_serializer_st OSSL_SERIALIZER;
typedef struct ossl_serializer_ctx_st OSSL_SERIALIZER_CTX;
#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L && \
defined(INTMAX_MAX) && defined(UINTMAX_MAX)
typedef intmax_t ossl_intmax_t;

14
util/libcrypto.num
View File

@ -4878,3 +4878,17 @@ EVP_PKEY_meth_set_digestsign ? 3_0_0 EXIST::FUNCTION:
EVP_PKEY_meth_set_digestverify ? 3_0_0 EXIST::FUNCTION:
EVP_PKEY_meth_get_digestsign ? 3_0_0 EXIST::FUNCTION:
EVP_PKEY_meth_get_digestverify ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_up_ref ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_free ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_fetch ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_number ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_is_a ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_provider ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_do_all_provided ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_names_do_all ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_settable_ctx_params ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_CTX_new ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_CTX_get_serializer ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_CTX_set_params ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_CTX_free ? 3_0_0 EXIST::FUNCTION:
OSSL_SERIALIZER_properties ? 3_0_0 EXIST::FUNCTION:

2
util/other.syms
View File

@ -36,6 +36,8 @@ OPENSSL_CTX datatype
NAMING_AUTHORITY datatype
OSSL_PARAM datatype
OSSL_PROVIDER datatype
OSSL_SERIALIZER datatype
OSSL_SERIALIZER_CTX datatype
OSSL_STORE_CTX datatype
OSSL_STORE_INFO datatype
OSSL_STORE_LOADER datatype