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

=pod

=begin comment

Any deprecated keypair/params d2i or i2d functions are collected on this page.

=end comment

=head1 NAME

d2i_DSAPrivateKey,
d2i_DSAPrivateKey_bio,
d2i_DSAPrivateKey_fp,
d2i_DSAPublicKey,
d2i_DSA_PUBKEY,
d2i_DSA_PUBKEY_bio,
d2i_DSA_PUBKEY_fp,
d2i_DSAparams,
d2i_RSAPrivateKey,
d2i_RSAPrivateKey_bio,
d2i_RSAPrivateKey_fp,
d2i_RSAPublicKey,
d2i_RSAPublicKey_bio,
d2i_RSAPublicKey_fp,
d2i_RSA_PUBKEY,
d2i_RSA_PUBKEY_bio,
d2i_RSA_PUBKEY_fp,
d2i_DHparams,
d2i_DHparams_bio,
d2i_DHparams_fp,
d2i_ECPKParameters,
d2i_ECParameters,
d2i_ECPrivateKey,
d2i_ECPrivateKey_bio,
d2i_ECPrivateKey_fp,
d2i_EC_PUBKEY,
d2i_EC_PUBKEY_bio,
d2i_EC_PUBKEY_fp,
i2d_RSAPrivateKey,
i2d_RSAPrivateKey_bio,
i2d_RSAPrivateKey_fp,
i2d_RSAPublicKey,
i2d_RSAPublicKey_bio,
i2d_RSAPublicKey_fp,
i2d_RSA_PUBKEY,
i2d_RSA_PUBKEY_bio,
i2d_RSA_PUBKEY_fp,
i2d_DHparams,
i2d_DHparams_bio,
i2d_DHparams_fp,
i2d_DSAPrivateKey,
i2d_DSAPrivateKey_bio,
i2d_DSAPrivateKey_fp,
i2d_DSAPublicKey,
i2d_DSA_PUBKEY,
i2d_DSA_PUBKEY_bio,
i2d_DSA_PUBKEY_fp,
i2d_DSAparams,
i2d_ECPKParameters,
i2d_ECParameters,
i2d_ECPrivateKey,
i2d_ECPrivateKey_bio,
i2d_ECPrivateKey_fp,
i2d_EC_PUBKEY,
i2d_EC_PUBKEY_bio,
i2d_EC_PUBKEY_fp
- DEPRECATED

=head1 SYNOPSIS

=for openssl generic

Deprecated since OpenSSL 3.0, can be hidden entirely by defining
B<OPENSSL_API_COMPAT> with a suitable version value, see
L<openssl_user_macros(7)>:

 TYPE *d2i_TYPEPrivateKey(TYPE **a, const unsigned char **ppin, long length);
 TYPE *d2i_TYPEPrivateKey_bio(BIO *bp, TYPE **a);
 TYPE *d2i_TYPEPrivateKey_fp(FILE *fp, TYPE **a);
 TYPE *d2i_TYPEPublicKey(TYPE **a, const unsigned char **ppin, long length);
 TYPE *d2i_TYPEPublicKey_bio(BIO *bp, TYPE **a);
 TYPE *d2i_TYPEPublicKey_fp(FILE *fp, TYPE **a);
 TYPE *d2i_TYPEparams(TYPE **a, const unsigned char **ppin, long length);
 TYPE *d2i_TYPEparams_bio(BIO *bp, TYPE **a);
 TYPE *d2i_TYPEparams_fp(FILE *fp, TYPE **a);
 TYPE *d2i_TYPE_PUBKEY(TYPE **a, const unsigned char **ppin, long length);
 TYPE *d2i_TYPE_PUBKEY_bio(BIO *bp, TYPE **a);
 TYPE *d2i_TYPE_PUBKEY_fp(FILE *fp, TYPE **a);

 int i2d_TYPEPrivateKey(const TYPE *a, unsigned char **ppout);
 int i2d_TYPEPrivateKey(TYPE *a, unsigned char **ppout);
 int i2d_TYPEPrivateKey_fp(FILE *fp, const TYPE *a);
 int i2d_TYPEPrivateKey_fp(FILE *fp, TYPE *a);
 int i2d_TYPEPrivateKey_bio(BIO *bp, const TYPE *a);
 int i2d_TYPEPrivateKey_bio(BIO *bp, TYPE *a);
 int i2d_TYPEPublicKey(const TYPE *a, unsigned char **ppout);
 int i2d_TYPEPublicKey(TYPE *a, unsigned char **ppout);
 int i2d_TYPEPublicKey_fp(FILE *fp, const TYPE *a);
 int i2d_TYPEPublicKey_fp(FILE *fp, TYPE *a);
 int i2d_TYPEPublicKey_bio(BIO *bp, const TYPE *a);
 int i2d_TYPEPublicKey_bio(BIO *bp, TYPE *a);
 int i2d_TYPEparams(const TYPE *a, unsigned char **ppout);
 int i2d_TYPEparams(TYPE *a, unsigned char **ppout);
 int i2d_TYPEparams_fp(FILE *fp, const TYPE *a);
 int i2d_TYPEparams_fp(FILE *fp, TYPE *a);
 int i2d_TYPEparams_bio(BIO *bp, const TYPE *a);
 int i2d_TYPEparams_bio(BIO *bp, TYPE *a);
 int i2d_TYPE_PUBKEY(const TYPE *a, unsigned char **ppout);
 int i2d_TYPE_PUBKEY(TYPE *a, unsigned char **ppout);
 int i2d_TYPE_PUBKEY_fp(FILE *fp, const TYPE *a);
 int i2d_TYPE_PUBKEY_fp(FILE *fp, TYPE *a);
 int i2d_TYPE_PUBKEY_bio(BIO *bp, const TYPE *a);
 int i2d_TYPE_PUBKEY_bio(BIO *bp, TYPE *a);

=head1 DESCRIPTION

All functions described here are deprecated.  Please use L<OSSL_DECODER(3)>
instead of the B<d2i> functions and L<OSSL_ENCODER(3)> instead of the B<i2d>
functions.  See L</Migration> below.

In the description here, B<I<TYPE>> is used a placeholder for any of the
OpenSSL datatypes, such as B<RSA>.
The function parameters I<ppin> and I<ppout> are generally either both named
I<pp> in the headers, or I<in> and I<out>.

All the functions here behave the way that's described in L<d2i_X509(3)>.

Please note that not all functions in the synopsis are available for all key
types.  For example, there are no d2i_RSAparams() or i2d_RSAparams(),
because the PKCS#1 B<RSA> structure doesn't include any key parameters.

B<d2i_I<TYPE>PrivateKey>() and derivates thereof decode DER encoded
B<I<TYPE>> private key data organized in a type specific structure.

B<d2i_I<TYPE>PublicKey>() and derivates thereof decode DER encoded
B<I<TYPE>> public key data organized in a type specific structure.

B<d2i_I<TYPE>params>() and derivates thereof decode DER encoded B<I<TYPE>>
key parameters organized in a type specific structure.

B<d2i_I<TYPE>_PUBKEY>() and derivates thereof decode DER encoded B<I<TYPE>>
public key data organized in a B<SubjectPublicKeyInfo> structure.

B<i2d_I<TYPE>PrivateKey>() and derivates thereof encode the private key
B<I<TYPE>> data into a type specific DER encoded structure.

B<i2d_I<TYPE>PublicKey>() and derivates thereof encode the public key
B<I<TYPE>> data into a type specific DER encoded structure.

B<i2d_I<TYPE>params>() and derivates thereof encode the B<I<TYPE>> key
parameters data into a type specific DER encoded structure.

B<i2d_I<TYPE>_PUBKEY>() and derivates thereof encode the public key
B<I<TYPE>> data into a DER encoded B<SubjectPublicKeyInfo> structure.

For example, d2i_RSAPrivateKey() and d2i_RSAPublicKey() expects the
structure defined by PKCS#1.
Similarly, i2d_RSAPrivateKey() and  i2d_RSAPublicKey() produce DER encoded
string organized according to PKCS#1.

=head2 Migration

Migration from the diverse B<I<TYPE>>s requires using corresponding new
OpenSSL types.  For all B<I<TYPE>>s described here, the corresponding new
type is B<EVP_PKEY>.  The rest of this section assumes that this has been
done, exactly how to do that is described elsewhere.

There are two migration paths:

=over 4

=item *

Replace
b<d2i_I<TYPE>PrivateKey()> with L<d2i_PrivateKey(3)>,
b<d2i_I<TYPE>PublicKey()> with L<d2i_PublicKey(3)>,
b<d2i_I<TYPE>params()> with L<d2i_KeyParams(3)>,
b<d2i_I<TYPE>_PUBKEY()> with L<d2i_PUBKEY(3)>,
b<i2d_I<TYPE>PrivateKey()> with L<i2d_PrivateKey(3)>,
b<i2d_I<TYPE>PublicKey()> with L<i2d_PublicKey(3)>,
b<i2d_I<TYPE>params()> with L<i2d_KeyParams(3)>,
b<i2d_I<TYPE>_PUBKEY()> with L<i2d_PUBKEY(3)>.
A caveat is that L<i2d_PrivateKey(3)> may output a DER encoded PKCS#8
outermost structure instead of the type specific structure, and that
L<d2i_PrivateKey(3)> recognises and unpacks a PKCS#8 structures.

=item *

Use L<OSSL_DECODER(3)> and L<OSSL_ENCODER(3)>.  How to migrate is described
below.  All those descriptions assume that the key to be encoded is in the
variable I<pkey>.

=back

=head3 Migrating B<i2d> functions to B<OSSL_ENCODER>

The exact L<OSSL_ENCODER(3)> output is driven by arguments rather than by
function names.  The sample code to get DER encoded output in a type
specific structure is uniform, the only things that vary are the selection
of what part of the B<EVP_PKEY> should be output, and the structure.  The
B<i2d> functions names can therefore be translated into two variables,
I<selection> and I<structure> as follows:

=over 4

=item B<i2d_I<TYPE>PrivateKey>() translates into:

 int selection = EVP_PKEY_PRIVATE_KEY;
 const char *structure = "type-specific";

=item B<i2d_I<TYPE>PublicKey>() translates into:

 int selection = EVP_PKEY_PUBLIC_KEY;
 const char *structure = "type-specific";

=item B<i2d_I<TYPE>params>() translates into:

 int selection = EVP_PKEY_PARAMETERS;
 const char *structure = "type-specific";

=item B<i2d_I<TYPE>_PUBKEY>() translates into:

 int selection = EVP_PKEY_PUBLIC_KEY;
 const char *structure = "SubjectPublicKeyInfo";

=back

The following sample code does the rest of the work:

 unsigned char *p = buffer;     /* |buffer| is supplied by the caller */
 size_t len = buffer_size;      /* assumed be the size of |buffer| */
 OSSL_ENCODER_CTX *ctx =
     OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "DER", structure,
                                   NULL, NULL);
 if (ctx == NULL) {
     /* fatal error handling */
 }
 if (OSSL_ENCODER_CTX_get_num_encoders(ctx) == 0) {
     OSSL_ENCODER_CTX_free(ctx);
     /* non-fatal error handling */
 }
 if (!OSSL_ENCODER_to_data(ctx, &p, &len)) {
     OSSL_ENCODER_CTX_free(ctx);
     /* error handling */
 }
 OSSL_ENCODER_CTX_free(ctx);

=for comment TODO: a similar section on OSSL_DECODER is to be added

=head1 NOTES

The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for
"internal" (that is, an internal C structure) and "DER" respectively.
So B<i2d_I<TYPE>>() converts from internal to DER.

The functions can also understand B<BER> forms.

The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an
empty structure such as that returned by TYPE_new().

The encoded data is in binary form and may contain embedded zeros.
Therefore, any FILE pointers or BIOs should be opened in binary mode.
Functions such as strlen() will B<not> return the correct length
of the encoded structure.

The ways that I<*ppin> and I<*ppout> are incremented after the operation
can trap the unwary. See the B<WARNINGS> section in L<d2i_X509(3)> for some
common errors.
The reason for this-auto increment behaviour is to reflect a typical
usage of ASN1 functions: after one structure is encoded or decoded
another will be processed after it.

The following points about the data types might be useful:

=over 4

=item B<DSA_PUBKEY>

Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.

=item B<DSAPublicKey>, B<DSAPrivateKey>

Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
L<PEM_write_PrivateKey(3)>, or similar instead.

=back

=head1 RETURN VALUES

B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
B<I<TYPE>> structure or NULL if an error occurs.  If the "reuse" capability has
been used with a valid structure being passed in via I<a>, then the object is
freed in the event of error and I<*a> is set to NULL.

B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
value if an error occurs.

B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
error occurs.

=head1 SEE ALSO

L<OSSL_ENCODER(3)>, L<OSSL_DECODER(3)>,
L<d2i_PrivateKey(3)>, L<d2i_PublicKey(3)>, L<d2i_KeyParams(3)>,
L<d2i_PUBKEY(3)>,
L<i2d_PrivateKey(3)>, L<i2d_PublicKey(3)>, L<i2d_KeyParams(3)>,
L<i2d_PUBKEY(3)>

=head1 COPYRIGHT

Copyright 2020-2021 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
d7e498ac RL	1	=pod
	2
	3	=begin comment
	4
90c046be	5	Any deprecated keypair/params d2i or i2d functions are collected on this page.
d7e498ac RL	6
	7	=end comment
	8
	9	=head1 NAME
	10
d6fff343 P	11	d2i_DSAPrivateKey,
	12	d2i_DSAPrivateKey_bio,
	13	d2i_DSAPrivateKey_fp,
	14	d2i_DSAPublicKey,
	15	d2i_DSA_PUBKEY,
	16	d2i_DSA_PUBKEY_bio,
	17	d2i_DSA_PUBKEY_fp,
	18	d2i_DSAparams,
d7e498ac RL	19	d2i_RSAPrivateKey,
	20	d2i_RSAPrivateKey_bio,
	21	d2i_RSAPrivateKey_fp,
	22	d2i_RSAPublicKey,
	23	d2i_RSAPublicKey_bio,
	24	d2i_RSAPublicKey_fp,
	25	d2i_RSA_PUBKEY,
	26	d2i_RSA_PUBKEY_bio,
	27	d2i_RSA_PUBKEY_fp,
90c046be MC	28	d2i_DHparams,
	29	d2i_DHparams_bio,
	30	d2i_DHparams_fp,
5b5eea4b SL	31	d2i_ECPKParameters,
	32	d2i_ECParameters,
	33	d2i_ECPrivateKey,
	34	d2i_ECPrivateKey_bio,
	35	d2i_ECPrivateKey_fp,
	36	d2i_EC_PUBKEY,
	37	d2i_EC_PUBKEY_bio,
	38	d2i_EC_PUBKEY_fp,
d7e498ac RL	39	i2d_RSAPrivateKey,
	40	i2d_RSAPrivateKey_bio,
	41	i2d_RSAPrivateKey_fp,
	42	i2d_RSAPublicKey,
	43	i2d_RSAPublicKey_bio,
	44	i2d_RSAPublicKey_fp,
	45	i2d_RSA_PUBKEY,
	46	i2d_RSA_PUBKEY_bio,
90c046be MC	47	i2d_RSA_PUBKEY_fp,
	48	i2d_DHparams,
	49	i2d_DHparams_bio,
5b5eea4b	50	i2d_DHparams_fp,
e52b4215 SL	51	i2d_DSAPrivateKey,
	52	i2d_DSAPrivateKey_bio,
	53	i2d_DSAPrivateKey_fp,
	54	i2d_DSAPublicKey,
	55	i2d_DSA_PUBKEY,
	56	i2d_DSA_PUBKEY_bio,
	57	i2d_DSA_PUBKEY_fp,
	58	i2d_DSAparams,
5b5eea4b SL	59	i2d_ECPKParameters,
	60	i2d_ECParameters,
	61	i2d_ECPrivateKey,
	62	i2d_ECPrivateKey_bio,
	63	i2d_ECPrivateKey_fp,
	64	i2d_EC_PUBKEY,
	65	i2d_EC_PUBKEY_bio,
	66	i2d_EC_PUBKEY_fp
d7e498ac RL	67	- DEPRECATED
	68
	69	=head1 SYNOPSIS
	70
	71	=for openssl generic
	72
	73	Deprecated since OpenSSL 3.0, can be hidden entirely by defining
	74	B<OPENSSL_API_COMPAT> with a suitable version value, see
	75	L<openssl_user_macros(7)>:
	76
	77	TYPE d2i_TYPEPrivateKey(TYPE a, const unsigned char *ppin, long length);
	78	TYPE d2i_TYPEPrivateKey_bio(BIO bp, TYPE **a);
	79	TYPE d2i_TYPEPrivateKey_fp(FILE fp, TYPE **a);
	80	TYPE d2i_TYPEPublicKey(TYPE a, const unsigned char *ppin, long length);
	81	TYPE d2i_TYPEPublicKey_bio(BIO bp, TYPE **a);
	82	TYPE d2i_TYPEPublicKey_fp(FILE fp, TYPE **a);
	83	TYPE d2i_TYPEparams(TYPE a, const unsigned char *ppin, long length);
	84	TYPE d2i_TYPEparams_bio(BIO bp, TYPE **a);
	85	TYPE d2i_TYPEparams_fp(FILE fp, TYPE **a);
	86	TYPE d2i_TYPE_PUBKEY(TYPE a, const unsigned char *ppin, long length);
	87	TYPE d2i_TYPE_PUBKEY_bio(BIO bp, TYPE **a);
	88	TYPE d2i_TYPE_PUBKEY_fp(FILE fp, TYPE **a);
	89
	90	int i2d_TYPEPrivateKey(const TYPE a, unsigned char *ppout);
	91	int i2d_TYPEPrivateKey(TYPE a, unsigned char *ppout);
	92	int i2d_TYPEPrivateKey_fp(FILE fp, const TYPE a);
	93	int i2d_TYPEPrivateKey_fp(FILE fp, TYPE a);
	94	int i2d_TYPEPrivateKey_bio(BIO bp, const TYPE a);
	95	int i2d_TYPEPrivateKey_bio(BIO bp, TYPE a);
	96	int i2d_TYPEPublicKey(const TYPE a, unsigned char *ppout);
	97	int i2d_TYPEPublicKey(TYPE a, unsigned char *ppout);
	98	int i2d_TYPEPublicKey_fp(FILE fp, const TYPE a);
	99	int i2d_TYPEPublicKey_fp(FILE fp, TYPE a);
	100	int i2d_TYPEPublicKey_bio(BIO bp, const TYPE a);
	101	int i2d_TYPEPublicKey_bio(BIO bp, TYPE a);
	102	int i2d_TYPEparams(const TYPE a, unsigned char *ppout);
	103	int i2d_TYPEparams(TYPE a, unsigned char *ppout);
	104	int i2d_TYPEparams_fp(FILE fp, const TYPE a);
	105	int i2d_TYPEparams_fp(FILE fp, TYPE a);
	106	int i2d_TYPEparams_bio(BIO bp, const TYPE a);
	107	int i2d_TYPEparams_bio(BIO bp, TYPE a);
	108	int i2d_TYPE_PUBKEY(const TYPE a, unsigned char *ppout);
	109	int i2d_TYPE_PUBKEY(TYPE a, unsigned char *ppout);
	110	int i2d_TYPE_PUBKEY_fp(FILE fp, const TYPE a);
	111	int i2d_TYPE_PUBKEY_fp(FILE fp, TYPE a);
	112	int i2d_TYPE_PUBKEY_bio(BIO bp, const TYPE a);
	113	int i2d_TYPE_PUBKEY_bio(BIO bp, TYPE a);
	114
	115	=head1 DESCRIPTION
	116
	117	All functions described here are deprecated. Please use L<OSSL_DECODER(3)>
	118	instead of the B<d2i> functions and L<OSSL_ENCODER(3)> instead of the B<i2d>
	119	functions. See L</Migration> below.
	120
	121	In the description here, B<I<TYPE>> is used a placeholder for any of the
	122	OpenSSL datatypes, such as B<RSA>.
	123	The function parameters I<ppin> and I<ppout> are generally either both named
	124	I<pp> in the headers, or I<in> and I<out>.
	125
	126	All the functions here behave the way that's described in L<d2i_X509(3)>.
	127
	128	Please note that not all functions in the synopsis are available for all key
	129	types. For example, there are no d2i_RSAparams() or i2d_RSAparams(),
	130	because the PKCS#1 B<RSA> structure doesn't include any key parameters.
131
132	B<d2i_I<TYPE>PrivateKey>() and derivates thereof decode DER encoded
133	B<I<TYPE>> private key data organized in a type specific structure.
134
135	B<d2i_I<TYPE>PublicKey>() and derivates thereof decode DER encoded
136	B<I<TYPE>> public key data organized in a type specific structure.
137
138	B<d2i_I<TYPE>params>() and derivates thereof decode DER encoded B<I<TYPE>>
139	key parameters organized in a type specific structure.
140
141	B<d2i_I<TYPE>_PUBKEY>() and derivates thereof decode DER encoded B<I<TYPE>>
142	public key data organized in a B<SubjectPublicKeyInfo> structure.
143
144	B<i2d_I<TYPE>PrivateKey>() and derivates thereof encode the private key
145	B<I<TYPE>> data into a type specific DER encoded structure.
146
147	B<i2d_I<TYPE>PublicKey>() and derivates thereof encode the public key
148	B<I<TYPE>> data into a type specific DER encoded structure.
149
150	B<i2d_I<TYPE>params>() and derivates thereof encode the B<I<TYPE>> key
151	parameters data into a type specific DER encoded structure.
152
153	B<i2d_I<TYPE>_PUBKEY>() and derivates thereof encode the public key
154	B<I<TYPE>> data into a DER encoded B<SubjectPublicKeyInfo> structure.
155
156	For example, d2i_RSAPrivateKey() and d2i_RSAPublicKey() expects the
157	structure defined by PKCS#1.
158	Similarly, i2d_RSAPrivateKey() and i2d_RSAPublicKey() produce DER encoded
159	string organized according to PKCS#1.
160
161	=head2 Migration
162
163	Migration from the diverse B<I<TYPE>>s requires using corresponding new
164	OpenSSL types. For all B<I<TYPE>>s described here, the corresponding new
165	type is B<EVP_PKEY>. The rest of this section assumes that this has been
166	done, exactly how to do that is described elsewhere.
167
168	There are two migration paths:
169
170	=over 4
171
172	=item *
173
174	Replace
57cd10dd P	175	b<d2i_I<TYPE>PrivateKey()> with L<d2i_PrivateKey(3)>,
	176	b<d2i_I<TYPE>PublicKey()> with L<d2i_PublicKey(3)>,
	177	b<d2i_I<TYPE>params()> with L<d2i_KeyParams(3)>,
	178	b<d2i_I<TYPE>_PUBKEY()> with L<d2i_PUBKEY(3)>,
	179	b<i2d_I<TYPE>PrivateKey()> with L<i2d_PrivateKey(3)>,
	180	b<i2d_I<TYPE>PublicKey()> with L<i2d_PublicKey(3)>,
	181	b<i2d_I<TYPE>params()> with L<i2d_KeyParams(3)>,
d7e498ac RL	182	b<i2d_I<TYPE>_PUBKEY()> with L<i2d_PUBKEY(3)>.
	183	A caveat is that L<i2d_PrivateKey(3)> may output a DER encoded PKCS#8
	184	outermost structure instead of the type specific structure, and that
	185	L<d2i_PrivateKey(3)> recognises and unpacks a PKCS#8 structures.
	186
	187	=item *
	188
	189	Use L<OSSL_DECODER(3)> and L<OSSL_ENCODER(3)>. How to migrate is described
	190	below. All those descriptions assume that the key to be encoded is in the
	191	variable I<pkey>.
	192
	193	=back
	194
	195	=head3 Migrating B<i2d> functions to B<OSSL_ENCODER>
	196
	197	The exact L<OSSL_ENCODER(3)> output is driven by arguments rather than by
	198	function names. The sample code to get DER encoded output in a type
	199	specific structure is uniform, the only things that vary are the selection
	200	of what part of the B<EVP_PKEY> should be output, and the structure. The
	201	B<i2d> functions names can therefore be translated into two variables,
	202	I<selection> and I<structure> as follows:
	203
	204	=over 4
	205
	206	=item B<i2d_I<TYPE>PrivateKey>() translates into:
	207
	208	int selection = EVP_PKEY_PRIVATE_KEY;
	209	const char *structure = "type-specific";
	210
	211	=item B<i2d_I<TYPE>PublicKey>() translates into:
	212
	213	int selection = EVP_PKEY_PUBLIC_KEY;
	214	const char *structure = "type-specific";
	215
	216	=item B<i2d_I<TYPE>params>() translates into:
	217
	218	int selection = EVP_PKEY_PARAMETERS;
	219	const char *structure = "type-specific";
	220
	221	=item B<i2d_I<TYPE>_PUBKEY>() translates into:
	222
	223	int selection = EVP_PKEY_PUBLIC_KEY;
	224	const char *structure = "SubjectPublicKeyInfo";
	225
	226	=back
	227
	228	The following sample code does the rest of the work:
	229
	230	unsigned char p = buffer; / \|buffer\| is supplied by the caller */
	231	size_t len = buffer_size; /* assumed be the size of \|buffer\| */
	232	OSSL_ENCODER_CTX *ctx =
fe75766c TM	233	OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "DER", structure,
fe75766c TM	234	NULL, NULL);
d7e498ac RL	235	if (ctx == NULL) {
	236	/* fatal error handling */
	237	}
	238	if (OSSL_ENCODER_CTX_get_num_encoders(ctx) == 0) {
	239	OSSL_ENCODER_CTX_free(ctx);
	240	/* non-fatal error handling */
	241	}
	242	if (!OSSL_ENCODER_to_data(ctx, &p, &len)) {
	243	OSSL_ENCODER_CTX_free(ctx);
	244	/* error handling */
	245	}
	246	OSSL_ENCODER_CTX_free(ctx);
	247
	248	=for comment TODO: a similar section on OSSL_DECODER is to be added
	249
d6fff343 P	250	=head1 NOTES
	251
	252	The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for
	253	"internal" (that is, an internal C structure) and "DER" respectively.
	254	So B<i2d_I<TYPE>>() converts from internal to DER.
	255
	256	The functions can also understand B<BER> forms.
	257
	258	The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
	259	populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an
	260	empty structure such as that returned by TYPE_new().
	261
	262	The encoded data is in binary form and may contain embedded zeros.
	263	Therefore, any FILE pointers or BIOs should be opened in binary mode.
	264	Functions such as strlen() will B<not> return the correct length
	265	of the encoded structure.
	266
	267	The ways that I<ppin> and I<ppout> are incremented after the operation
d60e719c TM	268	can trap the unwary. See the B<WARNINGS> section in L<d2i_X509(3)> for some
d60e719c TM	269	common errors.
d6fff343 P	270	The reason for this-auto increment behaviour is to reflect a typical
	271	usage of ASN1 functions: after one structure is encoded or decoded
	272	another will be processed after it.
	273
	274	The following points about the data types might be useful:
	275
	276	=over 4
	277
	278	=item B<DSA_PUBKEY>
	279
	280	Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
	281
	282	=item B<DSAPublicKey>, B<DSAPrivateKey>
	283
	284	Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
	285	L<PEM_write_PrivateKey(3)>, or similar instead.
	286
	287	=back
	288
d7e498ac RL	289	=head1 RETURN VALUES
	290
	291	B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
	292	B<I<TYPE>> structure or NULL if an error occurs. If the "reuse" capability has
	293	been used with a valid structure being passed in via I<a>, then the object is
	294	freed in the event of error and I<*a> is set to NULL.
	295
	296	B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
	297	value if an error occurs.
	298
	299	B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
	300	error occurs.
	301
	302	=head1 SEE ALSO
	303
	304	L<OSSL_ENCODER(3)>, L<OSSL_DECODER(3)>,
	305	L<d2i_PrivateKey(3)>, L<d2i_PublicKey(3)>, L<d2i_KeyParams(3)>,
	306	L<d2i_PUBKEY(3)>,
	307	L<i2d_PrivateKey(3)>, L<i2d_PublicKey(3)>, L<i2d_KeyParams(3)>,
	308	L<i2d_PUBKEY(3)>
	309
	310	=head1 COPYRIGHT
	311
4333b89f	312	Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
d7e498ac RL	313
	314	Licensed under the Apache License 2.0 (the "License"). You may not use
	315	this file except in compliance with the License. You can obtain a copy
	316	in the file LICENSE in the source distribution or at
	317	L<https://www.openssl.org/source/license.html>.
	318
	319	=cut