[thirdparty/openssl.git] / doc / man3 / OSSL_ENCODER_CTX.pod

=pod

=head1 NAME

OSSL_ENCODER_CTX,
OSSL_ENCODER_CTX_new,
OSSL_ENCODER_settable_ctx_params,
OSSL_ENCODER_CTX_set_params,
OSSL_ENCODER_CTX_free,
OSSL_ENCODER_CTX_set_output_type,
OSSL_ENCODER_CTX_set_selection,
OSSL_ENCODER_CTX_add_encoder,
OSSL_ENCODER_CTX_add_extra,
OSSL_ENCODER_CTX_get_num_encoders,
OSSL_ENCODER_INSTANCE,
OSSL_ENCODER_INSTANCE_get_encoder,
OSSL_ENCODER_INSTANCE_get_encoder_ctx,
OSSL_ENCODER_INSTANCE_get_input_type,
OSSL_ENCODER_INSTANCE_get_output_type,
OSSL_ENCODER_CONSTRUCT,
OSSL_ENCODER_CLEANUP,
OSSL_ENCODER_CTX_set_construct,
OSSL_ENCODER_CTX_set_construct_data,
OSSL_ENCODER_CTX_set_cleanup
- Encoder context routines

=head1 SYNOPSIS

 #include <openssl/encoder.h>

 typedef struct ossl_encoder_ctx_st OSSL_ENCODER_CTX;

 OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new();
 const OSSL_PARAM *OSSL_ENCODER_settable_ctx_params(OSSL_ENCODER *encoder);
 int OSSL_ENCODER_CTX_set_params(OSSL_ENCODER_CTX *ctx,
                                 const OSSL_PARAM params[]);
 void OSSL_ENCODER_CTX_free(OSSL_ENCODER_CTX *ctx);

 int OSSL_ENCODER_CTX_set_output_type(OSSL_ENCODER_CTX *ctx,
                                      const char *output_type);
 int OSSL_ENCODER_CTX_set_selection(OSSL_ENCODER_CTX *ctx, int selection);

 int OSSL_ENCODER_CTX_add_encoder(OSSL_ENCODER_CTX *ctx, OSSL_ENCODER *encoder);
 int OSSL_ENCODER_CTX_add_extra(OSSL_ENCODER_CTX *ctx,
                                OSSL_LIB_CTX *libctx, const char *propq);
 int OSSL_ENCODER_CTX_get_num_encoders(OSSL_ENCODER_CTX *ctx);

 typedef struct ossl_encoder_instance_st OSSL_ENCODER_INSTANCE;
 OSSL_ENCODER *
 OSSL_ENCODER_INSTANCE_get_encoder(OSSL_ENCODER_INSTANCE *encoder_inst);
 void *
 OSSL_ENCODER_INSTANCE_get_encoder_ctx(OSSL_ENCODER_INSTANCE *encoder_inst);
 const char *
 OSSL_ENCODER_INSTANCE_get_input_type(OSSL_ENCODER_INSTANCE *encoder_inst);
 const char *
 OSSL_ENCODER_INSTANCE_get_output_type(OSSL_ENCODER_INSTANCE *encoder_inst);

 typedef const void *OSSL_ENCODER_CONSTRUCT(OSSL_ENCODER_INSTANCE *encoder_inst,
                                            void *construct_data);
 typedef void OSSL_ENCODER_CLEANUP(void *construct_data);

 int OSSL_ENCODER_CTX_set_construct(OSSL_ENCODER_CTX *ctx,
                                    OSSL_ENCODER_CONSTRUCT *construct);
 int OSSL_ENCODER_CTX_set_construct_data(OSSL_ENCODER_CTX *ctx,
                                         void *construct_data);
 int OSSL_ENCODER_CTX_set_cleanup(OSSL_ENCODER_CTX *ctx,
                                  OSSL_ENCODER_CLEANUP *cleanup);

=head1 DESCRIPTION

Encoding an input object to the desired encoding may be done with a chain of
encoder implementations, which means that the output from one encoder may be
the input for the next in the chain.  The B<OSSL_ENCODER_CTX> holds all the
data about these encoders.  This allows having generic format encoders such
as DER to PEM, as well as more specialized encoders like RSA to DER.

The final output type must be given, and a chain of encoders must end with
an implementation that produces that output type.

At the beginning of the encoding process, a contructor provided by the
caller is called to ensure that there is an appropriate provider-side object
to start with.
The constructor is set with OSSL_ENCODER_CTX_set_construct().

B<OSSL_ENCODER_INSTANCE> is an opaque structure that contains data about the
encoder that is going to be used, and that may be useful for the
constructor.  There are some functions to extract data from this type,
described in L</Constructor> below.

=head2 Functions

OSSL_ENCODER_CTX_new() creates a B<OSSL_ENCODER_CTX>.

OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)>
array of parameter descriptors.

OSSL_ENCODER_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_ENCODER_CTX_free() frees the given context I<ctx>.

OSSL_ENCODER_CTX_add_encoder() populates the B<OSSL_ENCODER_CTX>
I<ctx> with a encoder, to be used to encode an input object.

OSSL_ENCODER_CTX_add_extra() finds encoders that further encodes output
from already added encoders, and adds them as well.  This is used to build
encoder chains.

OSSL_ENCODER_CTX_set_output_type() sets the ending output type.  This must
be specified, and determines if a complete encoder chain is available.

OSSL_ENCODER_CTX_num_encoders() gets the number of encoders currently added
to the context I<ctx>.

OSSL_ENCODER_CTX_set_construct() sets the constructor I<construct>.

OSSL_ENCODER_CTX_set_construct_data() sets the constructor data that is
passed to the constructor every time it's called.

OSSL_ENCODER_CTX_set_cleanup() sets the constructor data I<cleanup>
function.  This is called by L<OSSL_ENCODER_CTX_free(3)>.

=head2 Constructor

A B<OSSL_ENCODER_CONSTRUCT> gets the following arguments:

=over 4

=item I<encoder_inst>

The B<OSSL_ENCODER_INSTANCE> for the encoder from which the constructor gets
its data.

=item I<construct_data>

The pointer that was set with OSSL_ENCODE_CTX_set_construct_data().

=back

The constructor is expected to return a valid (non-NULL) pointer to a
provider-native object that can be used as first input of an encoding chain,
or NULL to indicate that an error has occured.

These utility functions may be used by a constructor:

OSSL_ENCODER_INSTANCE_encoder() can be used to get the encoder method from a
encoder instance I<encoder_inst>.

OSSL_ENCODER_INSTANCE_encoder_ctx() can be used to get the encoder method's
provider context from a encoder instance I<encoder_inst>.

OSSL_ENCODER_INSTANCE_input_type() can be used to get the input type for
encoder method from a encoder instance I<encoder_inst>.  This may be NULL.

OSSL_ENCODER_INSTANCE_output_type() can be used to get the output type for
encoder method from a encoder instance I<encoder_inst>.  This will never be
NULL.

=head1 RETURN VALUES

OSSL_ENCODER_CTX_new() returns a pointer to a B<OSSL_ENCODER_CTX>, or NULL
if the context structure couldn't be allocated.

OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array, or
NULL if none is available.

OSSL_ENCODER_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.

OSSL_DECODER_CTX_add_decoder(), OSSL_DECODER_CTX_add_extra(),
OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and
OSSL_DECODER_CTX_set_cleanup() return 1 on success, or 0 on failure.

OSSL_DECODER_CTX_num_decoders() returns the current number of decoders.  It
returns 0 if I<ctx> is NULL.

OSSL_DECODER_INSTANCE_decoder() returns an B<OSSL_DECODER> pointer on
success, or NULL on failure.

OSSL_DECODER_INSTANCE_decoder_ctx() returns a provider context pointer on
success, or NULL on failure.

OSSL_ENCODER_INSTANCE_input_type() returns a string with the name of the
input type, if relevant.  NULL is a valid returned value.

OSSL_ENCODER_INSTANCE_output_type() returns a string with the name of the
output type.

=head1 SEE ALSO

L<provider(7)>, L<OSSL_ENCODER(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
Commit	Line	Data
ece9304c RL	1	=pod
	2
	3	=head1 NAME
	4
	5	OSSL_ENCODER_CTX,
	6	OSSL_ENCODER_CTX_new,
ece9304c RL	7	OSSL_ENCODER_settable_ctx_params,
ece9304c RL	8	OSSL_ENCODER_CTX_set_params,
b8975c68 RL	9	OSSL_ENCODER_CTX_free,
	10	OSSL_ENCODER_CTX_set_output_type,
	11	OSSL_ENCODER_CTX_set_selection,
	12	OSSL_ENCODER_CTX_add_encoder,
	13	OSSL_ENCODER_CTX_add_extra,
	14	OSSL_ENCODER_CTX_get_num_encoders,
	15	OSSL_ENCODER_INSTANCE,
	16	OSSL_ENCODER_INSTANCE_get_encoder,
	17	OSSL_ENCODER_INSTANCE_get_encoder_ctx,
	18	OSSL_ENCODER_INSTANCE_get_input_type,
	19	OSSL_ENCODER_INSTANCE_get_output_type,
	20	OSSL_ENCODER_CONSTRUCT,
	21	OSSL_ENCODER_CLEANUP,
	22	OSSL_ENCODER_CTX_set_construct,
	23	OSSL_ENCODER_CTX_set_construct_data,
	24	OSSL_ENCODER_CTX_set_cleanup
ece9304c RL	25	- Encoder context routines
	26
	27	=head1 SYNOPSIS
	28
	29	#include <openssl/encoder.h>
	30
	31	typedef struct ossl_encoder_ctx_st OSSL_ENCODER_CTX;
	32
b8975c68	33	OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new();
ece9304c RL	34	const OSSL_PARAM OSSL_ENCODER_settable_ctx_params(OSSL_ENCODER encoder);
	35	int OSSL_ENCODER_CTX_set_params(OSSL_ENCODER_CTX *ctx,
	36	const OSSL_PARAM params[]);
	37	void OSSL_ENCODER_CTX_free(OSSL_ENCODER_CTX *ctx);
	38
b8975c68 RL	39	int OSSL_ENCODER_CTX_set_output_type(OSSL_ENCODER_CTX *ctx,
	40	const char *output_type);
	41	int OSSL_ENCODER_CTX_set_selection(OSSL_ENCODER_CTX *ctx, int selection);
	42
	43	int OSSL_ENCODER_CTX_add_encoder(OSSL_ENCODER_CTX ctx, OSSL_ENCODER encoder);
	44	int OSSL_ENCODER_CTX_add_extra(OSSL_ENCODER_CTX *ctx,
b4250010	45	OSSL_LIB_CTX libctx, const char propq);
b8975c68 RL	46	int OSSL_ENCODER_CTX_get_num_encoders(OSSL_ENCODER_CTX *ctx);
	47
	48	typedef struct ossl_encoder_instance_st OSSL_ENCODER_INSTANCE;
	49	OSSL_ENCODER *
	50	OSSL_ENCODER_INSTANCE_get_encoder(OSSL_ENCODER_INSTANCE *encoder_inst);
	51	void *
	52	OSSL_ENCODER_INSTANCE_get_encoder_ctx(OSSL_ENCODER_INSTANCE *encoder_inst);
	53	const char *
	54	OSSL_ENCODER_INSTANCE_get_input_type(OSSL_ENCODER_INSTANCE *encoder_inst);
	55	const char *
	56	OSSL_ENCODER_INSTANCE_get_output_type(OSSL_ENCODER_INSTANCE *encoder_inst);
	57
	58	typedef const void OSSL_ENCODER_CONSTRUCT(OSSL_ENCODER_INSTANCE encoder_inst,
	59	void *construct_data);
	60	typedef void OSSL_ENCODER_CLEANUP(void *construct_data);
	61
	62	int OSSL_ENCODER_CTX_set_construct(OSSL_ENCODER_CTX *ctx,
	63	OSSL_ENCODER_CONSTRUCT *construct);
	64	int OSSL_ENCODER_CTX_set_construct_data(OSSL_ENCODER_CTX *ctx,
	65	void *construct_data);
	66	int OSSL_ENCODER_CTX_set_cleanup(OSSL_ENCODER_CTX *ctx,
	67	OSSL_ENCODER_CLEANUP *cleanup);
	68
ece9304c RL	69	=head1 DESCRIPTION
ece9304c RL	70
b8975c68 RL	71	Encoding an input object to the desired encoding may be done with a chain of
	72	encoder implementations, which means that the output from one encoder may be
	73	the input for the next in the chain. The B<OSSL_ENCODER_CTX> holds all the
	74	data about these encoders. This allows having generic format encoders such
	75	as DER to PEM, as well as more specialized encoders like RSA to DER.
ece9304c	76
b8975c68 RL	77	The final output type must be given, and a chain of encoders must end with
b8975c68 RL	78	an implementation that produces that output type.
ece9304c	79
b8975c68 RL	80	At the beginning of the encoding process, a contructor provided by the
	81	caller is called to ensure that there is an appropriate provider-side object
	82	to start with.
	83	The constructor is set with OSSL_ENCODER_CTX_set_construct().
ece9304c	84
b8975c68 RL	85	B<OSSL_ENCODER_INSTANCE> is an opaque structure that contains data about the
	86	encoder that is going to be used, and that may be useful for the
	87	constructor. There are some functions to extract data from this type,
	88	described in L</Constructor> below.
ece9304c	89
b8975c68	90	=head2 Functions
ece9304c	91
b8975c68	92	OSSL_ENCODER_CTX_new() creates a B<OSSL_ENCODER_CTX>.
ece9304c RL	93
	94	OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)>
	95	array of parameter descriptors.
	96
	97	OSSL_ENCODER_CTX_set_params() attempts to set parameters specified
	98	with an L<OSSL_PARAM(3)> array I<params>. Parameters that the
	99	implementation doesn't recognise should be ignored.
	100
	101	OSSL_ENCODER_CTX_free() frees the given context I<ctx>.
	102
b8975c68 RL	103	OSSL_ENCODER_CTX_add_encoder() populates the B<OSSL_ENCODER_CTX>
	104	I<ctx> with a encoder, to be used to encode an input object.
	105
	106	OSSL_ENCODER_CTX_add_extra() finds encoders that further encodes output
	107	from already added encoders, and adds them as well. This is used to build
	108	encoder chains.
	109
	110	OSSL_ENCODER_CTX_set_output_type() sets the ending output type. This must
	111	be specified, and determines if a complete encoder chain is available.
	112
	113	OSSL_ENCODER_CTX_num_encoders() gets the number of encoders currently added
	114	to the context I<ctx>.
	115
	116	OSSL_ENCODER_CTX_set_construct() sets the constructor I<construct>.
	117
	118	OSSL_ENCODER_CTX_set_construct_data() sets the constructor data that is
	119	passed to the constructor every time it's called.
	120
	121	OSSL_ENCODER_CTX_set_cleanup() sets the constructor data I<cleanup>
	122	function. This is called by L<OSSL_ENCODER_CTX_free(3)>.
	123
	124	=head2 Constructor
	125
	126	A B<OSSL_ENCODER_CONSTRUCT> gets the following arguments:
	127
	128	=over 4
	129
	130	=item I<encoder_inst>
	131
	132	The B<OSSL_ENCODER_INSTANCE> for the encoder from which the constructor gets
	133	its data.
	134
	135	=item I<construct_data>
	136
	137	The pointer that was set with OSSL_ENCODE_CTX_set_construct_data().
	138
	139	=back
	140
	141	The constructor is expected to return a valid (non-NULL) pointer to a
	142	provider-native object that can be used as first input of an encoding chain,
	143	or NULL to indicate that an error has occured.
	144
	145	These utility functions may be used by a constructor:
	146
	147	OSSL_ENCODER_INSTANCE_encoder() can be used to get the encoder method from a
	148	encoder instance I<encoder_inst>.
	149
	150	OSSL_ENCODER_INSTANCE_encoder_ctx() can be used to get the encoder method's
	151	provider context from a encoder instance I<encoder_inst>.
	152
	153	OSSL_ENCODER_INSTANCE_input_type() can be used to get the input type for
	154	encoder method from a encoder instance I<encoder_inst>. This may be NULL.
	155
	156	OSSL_ENCODER_INSTANCE_output_type() can be used to get the output type for
	157	encoder method from a encoder instance I<encoder_inst>. This will never be
	158	NULL.
	159
ece9304c RL	160	=head1 RETURN VALUES
ece9304c RL	161
b8975c68 RL	162	OSSL_ENCODER_CTX_new() returns a pointer to a B<OSSL_ENCODER_CTX>, or NULL
b8975c68 RL	163	if the context structure couldn't be allocated.
ece9304c	164
b8975c68 RL	165	OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array, or
b8975c68 RL	166	NULL if none is available.
ece9304c	167
b8975c68 RL	168	OSSL_ENCODER_CTX_set_params() returns 1 if all recognised parameters were
	169	valid, or 0 if one of them was invalid or caused some other failure in the
	170	implementation.
	171
	172	OSSL_DECODER_CTX_add_decoder(), OSSL_DECODER_CTX_add_extra(),
	173	OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and
	174	OSSL_DECODER_CTX_set_cleanup() return 1 on success, or 0 on failure.
	175
	176	OSSL_DECODER_CTX_num_decoders() returns the current number of decoders. It
	177	returns 0 if I<ctx> is NULL.
	178
	179	OSSL_DECODER_INSTANCE_decoder() returns an B<OSSL_DECODER> pointer on
	180	success, or NULL on failure.
	181
	182	OSSL_DECODER_INSTANCE_decoder_ctx() returns a provider context pointer on
	183	success, or NULL on failure.
	184
	185	OSSL_ENCODER_INSTANCE_input_type() returns a string with the name of the
	186	input type, if relevant. NULL is a valid returned value.
ece9304c	187
b8975c68 RL	188	OSSL_ENCODER_INSTANCE_output_type() returns a string with the name of the
b8975c68 RL	189	output type.
ece9304c RL	190
	191	=head1 SEE ALSO
	192
	193	L<provider(7)>, L<OSSL_ENCODER(3)>
	194
	195	=head1 HISTORY
	196
	197	The functions described here were added in OpenSSL 3.0.
	198
	199	=head1 COPYRIGHT
	200
eec0ad10	201	Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
ece9304c RL	202
	203	Licensed under the Apache License 2.0 (the "License"). You may not use
	204	this file except in compliance with the License. You can obtain a copy
	205	in the file LICENSE in the source distribution or at
	206	L<https://www.openssl.org/source/license.html>.
	207
	208	=cut