[thirdparty/openssl.git] / doc / man7 / provider-encoder.pod

=pod

=head1 NAME

provider-encoder - The ENCODER library E<lt>-E<gt> provider functions

=head1 SYNOPSIS

 #include <openssl/core_dispatch.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 encoder context */
 void *OSSL_FUNC_encoder_newctx(void *provctx);
 void OSSL_FUNC_encoder_freectx(void *ctx);
 int OSSL_FUNC_encoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_encoder_settable_ctx_params(void *provctx)

 /* Functions to encode object data */
 int OSSL_FUNC_encoder_encode_data(void *ctx, const OSSL_PARAM *data,
                                         OSSL_CORE_BIO *out,
                                         OSSL_PASSPHRASE_CALLBACK *cb,
                                         void *cbarg);
 int OSSL_FUNC_encoder_encode_object(void *ctx, void *obj, OSSL_CORE_BIO *out,
                                           OSSL_PASSPHRASE_CALLBACK *cb,
                                           void *cbarg);

=head1 DESCRIPTION

I<We use the wide term "encode" in this manual.  This includes but is
not limited to serialization.>

The ENCODER is a generic method to encode any set of object data
in L<OSSL_PARAM(3)> array form, or any provider side object into
encoded form, and write it to the given OSSL_CORE_BIO.  If the caller wants
to get the encoded stream to memory, it should provide a
L<BIO_s_membuf(3)>.

The encoder doesn't need to know more about the B<OSSL_CORE_BIO> pointer than
being able to pass it to the appropriate BIO upcalls (see
L<provider-base(7)/Core functions>).

The encoding using the L<OSSL_PARAM(3)> array form allows a
encoder to be used for data that's been exported from another
provider, and thereby allow them to exist independently of each
other.

The encoding 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_FUNC_{name}>.
For example, the "function" OSSL_FUNC_encoder_encode_data() has these:

 typedef int
     (OSSL_FUNC_encoder_encode_data_fn)(void *provctx,
                                            const OSSL_PARAM params[],
                                            OSSL_CORE_BIO *out);
 static ossl_inline OSSL_FUNC_encoder_encode_data_fn
     OSSL_FUNC_encoder_encode_data(const OSSL_DISPATCH *opf);

B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
macros in L<openssl-core_dispatch.h(7)>, as follows:

 OSSL_FUNC_encoder_newctx              OSSL_FUNC_ENCODER_NEWCTX
 OSSL_FUNC_encoder_freectx             OSSL_FUNC_ENCODER_FREECTX
 OSSL_FUNC_encoder_set_ctx_params      OSSL_FUNC_ENCODER_SET_CTX_PARAMS
 OSSL_FUNC_encoder_settable_ctx_params OSSL_FUNC_ENCODER_SETTABLE_CTX_PARAMS

 OSSL_FUNC_encoder_encode_data      OSSL_FUNC_ENCODER_ENCODE_DATA
 OSSL_FUNC_encoder_encode_object    OSSL_FUNC_ENCODER_ENCODE_OBJECT

=head2 Names and properties

The name of an implementation should match the type of object it
handles.  For example, an implementation that encodes an RSA key
should be named accordingly.

To be able to specify exactly what encoding format and what type
of data a encoder 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 key 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 parameters

An implementation with that format property value outputs key
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

OSSL_FUNC_encoder_newctx() returns a context to be used with the rest of
the functions.

OSSL_FUNC_encoder_freectx() frees the given I<ctx>, if it was created by
OSSL_FUNC_encoder_newctx().

OSSL_FUNC_encoder_set_ctx_params() sets context data according to
parameters from I<params> that it recognises.  Unrecognised parameters
should be ignored.

OSSL_FUNC_encoder_settable_ctx_params() returns a constant B<OSSL_PARAM>
array describing the parameters that OSSL_FUNC_encoder_set_ctx_params()
can handle.

See L<OSSL_PARAM(3)> for further details on the parameters structure used
by OSSL_FUNC_encoder_set_ctx_params() and OSSL_FUNC_encoder_settable_ctx_params().

=head2 Encoding functions

=for comment There will be a "Decoding functions" title as well

OSSL_FUNC_encoder_encode_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
encoded form to the B<OSSL_CORE_BIO>.

OSSL_FUNC_encoder_encode_object() should take a pointer to an object
that it knows intimately, and output that object in encoded form to
the B<OSSL_CORE_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 encoding 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 Encoder parameters

Parameters currently recognised by built-in encoders are as
follows:

=over 4

=item "cipher" (B<OSSL_ENCODER_PARAM_CIPHER>) <UTF8 string>

The name of the encryption cipher to be used when generating encrypted
encoding.  This is used when encoding private keys, as well as
other objects that need protection.

If this name is invalid for the encoding implementation, the
implementation should refuse to perform the encoding, i.e.
OSSL_FUNC_encoder_encode_data() and OSSL_FUNC_encoder_encode_object()
should return an error.

=item "properties" (B<OSSL_ENCODER_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 encoding 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_ENCODER_PARAM_PASS>) <octet string>

A pass phrase provided by the application.  When this is given, the
built-in encoders 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

OSSL_FUNC_encoder_newctx() returns a pointer to a context, or NULL on
failure.

OSSL_FUNC_encoder_set_ctx_params() returns 1, unless a recognised
parameters was invalid or caused an error, for which 0 is returned.

OSSL_FUNC_encoder_settable_ctx_params() returns a pointer to an array of
constant B<OSSL_PARAM> elements.

OSSL_FUNC_encoder_encode_data() and OSSL_FUNC_encoder_encode_object()
return 1 on success, or 0 on failure.

=head1 SEE ALSO

L<provider(7)>

=head1 HISTORY

The ENCODER interface was introduced 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
Commit	Line	Data
0d003c52 RL	1	=pod
	2
	3	=head1 NAME
	4
ece9304c	5	provider-encoder - The ENCODER library E<lt>-E<gt> provider functions
0d003c52 RL	6
	7	=head1 SYNOPSIS
	8
23c48d94	9	#include <openssl/core_dispatch.h>
0d003c52 RL	10
	11	/*
	12	* None of these are actual functions, but are displayed like this for
	13	* the function signatures for functions that are offered as function
	14	* pointers in OSSL_DISPATCH arrays.
	15	*/
	16
ece9304c RL	17	/* Functions to construct / destruct / manipulate the encoder context */
	18	void OSSL_FUNC_encoder_newctx(void provctx);
	19	void OSSL_FUNC_encoder_freectx(void *ctx);
	20	int OSSL_FUNC_encoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
	21	const OSSL_PARAM OSSL_FUNC_encoder_settable_ctx_params(void provctx)
0d003c52	22
ece9304c RL	23	/* Functions to encode object data */
ece9304c RL	24	int OSSL_FUNC_encoder_encode_data(void ctx, const OSSL_PARAM data,
363b1e5d DMSP	25	OSSL_CORE_BIO *out,
	26	OSSL_PASSPHRASE_CALLBACK *cb,
	27	void *cbarg);
ece9304c	28	int OSSL_FUNC_encoder_encode_object(void ctx, void obj, OSSL_CORE_BIO *out,
363b1e5d DMSP	29	OSSL_PASSPHRASE_CALLBACK *cb,
363b1e5d DMSP	30	void *cbarg);
0d003c52 RL	31
	32	=head1 DESCRIPTION
	33
ece9304c RL	34	I<We use the wide term "encode" in this manual. This includes but is
	35	not limited to serialization.>
	36
	37	The ENCODER is a generic method to encode any set of object data
0d003c52	38	in L<OSSL_PARAM(3)> array form, or any provider side object into
ece9304c RL	39	encoded form, and write it to the given OSSL_CORE_BIO. If the caller wants
ece9304c RL	40	to get the encoded stream to memory, it should provide a
0d003c52 RL	41	L<BIO_s_membuf(3)>.
0d003c52 RL	42
ece9304c	43	The encoder doesn't need to know more about the B<OSSL_CORE_BIO> pointer than
0d003c52 RL	44	being able to pass it to the appropriate BIO upcalls (see
	45	L<provider-base(7)/Core functions>).
	46
ece9304c RL	47	The encoding using the L<OSSL_PARAM(3)> array form allows a
ece9304c RL	48	encoder to be used for data that's been exported from another
0d003c52 RL	49	provider, and thereby allow them to exist independently of each
	50	other.
	51
ece9304c	52	The encoding using a provider side object can only be safely used
0d003c52 RL	53	with provider data coming from the same provider, for example keys
	54	with the L<KEYMGMT\|provider-keymgmt(7)> provider.
	55
	56	All "functions" mentioned here are passed as function pointers between
	57	F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
	58	B<OSSL_ALGORITHM> arrays that are returned by the provider's
	59	provider_query_operation() function
	60	(see L<provider-base(7)/Provider Functions>).
	61
	62	All these "functions" have a corresponding function type definition
	63	named B<OSSL_{name}_fn>, and a helper function to retrieve the
	64	function pointer from a B<OSSL_DISPATCH> element named
363b1e5d	65	B<OSSL_FUNC_{name}>.
ece9304c	66	For example, the "function" OSSL_FUNC_encoder_encode_data() has these:
0d003c52 RL	67
0d003c52 RL	68	typedef int
ece9304c	69	(OSSL_FUNC_encoder_encode_data_fn)(void *provctx,
0d003c52	70	const OSSL_PARAM params[],
06a2027b	71	OSSL_CORE_BIO *out);
ece9304c RL	72	static ossl_inline OSSL_FUNC_encoder_encode_data_fn
ece9304c RL	73	OSSL_FUNC_encoder_encode_data(const OSSL_DISPATCH *opf);
0d003c52 RL	74
0d003c52 RL	75	B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
23c48d94	76	macros in L<openssl-core_dispatch.h(7)>, as follows:
0d003c52	77
ece9304c RL	78	OSSL_FUNC_encoder_newctx OSSL_FUNC_ENCODER_NEWCTX
	79	OSSL_FUNC_encoder_freectx OSSL_FUNC_ENCODER_FREECTX
	80	OSSL_FUNC_encoder_set_ctx_params OSSL_FUNC_ENCODER_SET_CTX_PARAMS
	81	OSSL_FUNC_encoder_settable_ctx_params OSSL_FUNC_ENCODER_SETTABLE_CTX_PARAMS
0d003c52	82
ece9304c RL	83	OSSL_FUNC_encoder_encode_data OSSL_FUNC_ENCODER_ENCODE_DATA
ece9304c RL	84	OSSL_FUNC_encoder_encode_object OSSL_FUNC_ENCODER_ENCODE_OBJECT
0d003c52 RL	85
	86	=head2 Names and properties
	87
	88	The name of an implementation should match the type of object it
ece9304c	89	handles. For example, an implementation that encodes an RSA key
0d003c52 RL	90	should be named accordingly.
0d003c52 RL	91
ece9304c RL	92	To be able to specify exactly what encoding format and what type
ece9304c RL	93	of data a encoder implementation is expected to handle, two
0d003c52 RL	94	additional properties may be given:
	95
	96	=over 4
	97
	98	=item format
	99
	100	This property is used to specify what kind of output format the
	101	implementation produces. Currently known formats are:
	102
	103	=over 4
	104
	105	=item text
	106
	107	An implementation with that format property value outputs human
	108	readable text, making that implementation suitable for C<-text> output
	109	in diverse L<openssl(1)> commands.
	110
	111	=item pem
	112
	113	An implementation with that format property value outputs PEM
	114	formatted data.
	115
	116	=item der
	117
	118	An implementation with that format property value outputs DER
	119	formatted data.
	120
	121	=back
	122
	123	=item type
	124
	125	With objects that have multiple purposes, this can be used to specify
	126	the purpose type. The currently known use cases are asymmetric keys
b305452f	127	and key parameters, where the type can be one of:
0d003c52 RL	128
	129	=over 4
	130
	131	=item private
	132
	133	An implementation with that format property value outputs a private
	134	key.
	135
	136	=item public
	137
	138	An implementation with that format property value outputs a public
	139	key.
	140
b305452f	141	=item parameters
0d003c52	142
b305452f	143	An implementation with that format property value outputs key
0d003c52 RL	144	parameters.
	145
	146	=back
	147
	148	=back
	149
	150	The possible values of both these properties is open ended. A
	151	provider may very well specify other formats that libcrypto doesn't
	152	know anything about.
	153
	154	=head2 Context functions
	155
ece9304c	156	OSSL_FUNC_encoder_newctx() returns a context to be used with the rest of
0d003c52 RL	157	the functions.
0d003c52 RL	158
ece9304c RL	159	OSSL_FUNC_encoder_freectx() frees the given I<ctx>, if it was created by
ece9304c RL	160	OSSL_FUNC_encoder_newctx().
0d003c52	161
ece9304c	162	OSSL_FUNC_encoder_set_ctx_params() sets context data according to
0d003c52 RL	163	parameters from I<params> that it recognises. Unrecognised parameters
	164	should be ignored.
	165
ece9304c RL	166	OSSL_FUNC_encoder_settable_ctx_params() returns a constant B<OSSL_PARAM>
ece9304c RL	167	array describing the parameters that OSSL_FUNC_encoder_set_ctx_params()
0d003c52 RL	168	can handle.
	169
	170	See L<OSSL_PARAM(3)> for further details on the parameters structure used
ece9304c	171	by OSSL_FUNC_encoder_set_ctx_params() and OSSL_FUNC_encoder_settable_ctx_params().
0d003c52	172
ece9304c	173	=head2 Encoding functions
0d003c52	174
ece9304c	175	=for comment There will be a "Decoding functions" title as well
0d003c52	176
ece9304c	177	OSSL_FUNC_encoder_encode_data() should take an array of B<OSSL_PARAM>,
0d003c52 RL	178	I<data>, and if it contains the data necessary for the object type
0d003c52 RL	179	that the implementation handles, it should output the object in
ece9304c	180	encoded form to the B<OSSL_CORE_BIO>.
0d003c52	181
ece9304c RL	182	OSSL_FUNC_encoder_encode_object() should take a pointer to an object
ece9304c RL	183	that it knows intimately, and output that object in encoded form to
06a2027b	184	the B<OSSL_CORE_BIO>. The caller I<must> ensure that this function is called
0d003c52 RL	185	with a pointer that the provider of this function is familiar with.
	186	It is not suitable to use with object pointers coming from other
	187	providers.
	188
ece9304c	189	Both encoding functions also take an B<OSSL_PASSPHRASE_CALLBACK>
0d003c52 RL	190	function pointer along with a pointer to application data I<cbarg>,
	191	which should be used when a pass phrase prompt is needed.
	192
ece9304c	193	=head2 Encoder parameters
866234ac	194
ece9304c	195	Parameters currently recognised by built-in encoders are as
866234ac RL	196	follows:
	197
	198	=over 4
	199
ece9304c	200	=item "cipher" (B<OSSL_ENCODER_PARAM_CIPHER>) <UTF8 string>
866234ac RL	201
866234ac RL	202	The name of the encryption cipher to be used when generating encrypted
ece9304c	203	encoding. This is used when encoding private keys, as well as
866234ac RL	204	other objects that need protection.
866234ac RL	205
ece9304c RL	206	If this name is invalid for the encoding implementation, the
	207	implementation should refuse to perform the encoding, i.e.
	208	OSSL_FUNC_encoder_encode_data() and OSSL_FUNC_encoder_encode_object()
866234ac RL	209	should return an error.
866234ac RL	210
ece9304c	211	=item "properties" (B<OSSL_ENCODER_PARAM_PROPERTIES>) <UTF8 string>
866234ac RL	212
	213	The properties to be queried when trying to fetch the algorithm given
	214	with the "cipher" parameter.
	215	This must be given together with the "cipher" parameter to be
	216	considered valid.
	217
ece9304c	218	The encoding implementation isn't obligated to use this value.
866234ac RL	219	However, it is recommended that implementations that do not handle
	220	property strings return an error on receiving this parameter unless
	221	its value NULL or the empty string.
	222
ece9304c	223	=item "passphrase" (B<OSSL_ENCODER_PARAM_PASS>) <octet string>
866234ac RL	224
866234ac RL	225	A pass phrase provided by the application. When this is given, the
ece9304c	226	built-in encoders will not attempt to use the passphrase callback.
866234ac RL	227
	228	=back
	229
	230	Parameters currently recognised by the built-in pass phrase callback:
	231
	232	=over 4
	233
	234	=item "info" (B<OSSL_PASSPHRASE_PARAM_INFO>) <UTF8 string>
	235
	236	A string of information that will become part of the pass phrase
	237	prompt. This could be used to give the user information on what kind
	238	of object it's being prompted for.
	239
	240	=back
	241
0d003c52 RL	242	=head1 RETURN VALUES
0d003c52 RL	243
ece9304c	244	OSSL_FUNC_encoder_newctx() returns a pointer to a context, or NULL on
0d003c52 RL	245	failure.
0d003c52 RL	246
ece9304c	247	OSSL_FUNC_encoder_set_ctx_params() returns 1, unless a recognised
0d003c52 RL	248	parameters was invalid or caused an error, for which 0 is returned.
0d003c52 RL	249
ece9304c	250	OSSL_FUNC_encoder_settable_ctx_params() returns a pointer to an array of
0d003c52 RL	251	constant B<OSSL_PARAM> elements.
0d003c52 RL	252
ece9304c	253	OSSL_FUNC_encoder_encode_data() and OSSL_FUNC_encoder_encode_object()
0d003c52 RL	254	return 1 on success, or 0 on failure.
	255
	256	=head1 SEE ALSO
	257
	258	L<provider(7)>
	259
	260	=head1 HISTORY
	261
ece9304c	262	The ENCODER interface was introduced in OpenSSL 3.0.
0d003c52 RL	263
	264	=head1 COPYRIGHT
	265
33388b44	266	Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
0d003c52 RL	267
	268	Licensed under the Apache License 2.0 (the "License"). You may not use
	269	this file except in compliance with the License. You can obtain a copy
	270	in the file LICENSE in the source distribution or at
	271	L<https://www.openssl.org/source/license.html>.
	272
	273	=cut