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

=pod

=head1 NAME

EVP_PKEY_param_fromdata_init, EVP_PKEY_key_fromdata_init, EVP_PKEY_fromdata,
EVP_PKEY_param_fromdata_settable, EVP_PKEY_key_fromdata_settable
- functions to create key parameters and keys from user data

=head1 SYNOPSIS

 #include <openssl/evp.h>

 int EVP_PKEY_param_fromdata_init(EVP_PKEY_CTX *ctx);
 int EVP_PKEY_key_fromdata_init(EVP_PKEY_CTX *ctx);
 int EVP_PKEY_fromdata(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey, OSSL_PARAM params[]);
 const OSSL_PARAM *EVP_PKEY_param_fromdata_settable(EVP_PKEY_CTX *ctx);
 const OSSL_PARAM *EVP_PKEY_key_fromdata_settable(EVP_PKEY_CTX *ctx);

=head1 DESCRIPTION

The functions described here are used to create new keys from user
provided key data, such as I<n>, I<e> and I<d> for a minimal RSA
keypair.

These functions use an B<EVP_PKEY_CTX> context, which should primarily
be created with L<EVP_PKEY_CTX_new_from_name(3)> or
L<EVP_PKEY_CTX_new_id(3)>.

The exact key data that the user can pass depends on the key type.
These are passed as an L<OSSL_PARAM(3)> array.

EVP_PKEY_param_fromdata_init() initializes a public key algorithm context
for creating key parameters from user data.

EVP_PKEY_key_fromdata_init() initializes a public key algorithm context for
creating a key from user data.

EVP_PKEY_fromdata() creates the structure to store key parameters or a
key, given data from I<params> and a context that's been initialized with
EVP_PKEY_param_fromdata_init() or EVP_PKEY_key_fromdata_init().  The result is
written to I<*ppkey>. The parameters that can be used for various types of key
are as described by the diverse "Common parameters" sections of the
L<B<EVP_PKEY-RSA>(7)|EVP_PKEY-RSA(7)/Common RSA parameters>,
L<B<EVP_PKEY-DSA>(7)|EVP_PKEY-DSA(7)/Common DSA & DH parameters>,
L<B<EVP_PKEY-DH>(7)|EVP_PKEY-DH(7)/Common DH parameters>,
L<B<EVP_PKEY-EC>(7)|EVP_PKEY-EC(7)/Common EC parameters>,
L<B<EVP_PKEY-ED448>(7)|EVP_PKEY-ED448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
L<B<EVP_PKEY-X25519>(7)|EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
L<B<EVP_PKEY-X448>(7)|EVP_PKEY-X448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
and L<B<EVP_PKEY-ED25519>(7)|EVP_PKEY-ED25519(7)/Common X25519, X448, ED25519 and ED448 parameters> pages.

=for comment the awful list of links above is made this way so we get nice
rendering as a man-page while still getting proper links in HTML

EVP_PKEY_param_fromdata_settable() and EVP_PKEY_key_fromdata_settable()
get a constant B<OSSL_PARAM> array that describes the settable parameters
that can be used with EVP_PKEY_fromdata().
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.

=head1 NOTES

These functions only work with key management methods coming from a
provider.

=for comment We may choose to make this available for legacy methods too... 

=head1 RETURN VALUES

EVP_PKEY_key_fromdata_init(), EVP_PKEY_param_fromdata_init() and
EVP_PKEY_fromdata() return 1 for success and 0 or a negative value for
failure.  In particular a return value of -2 indicates the operation is
not supported by the public key algorithm.

=head1 EXAMPLES

These examples are very terse for the sake of staying on topic, which
is the EVP_PKEY_fromdata() set of functions.  In real applications,
BIGNUMs would be handled and converted to byte arrays with
BN_bn2nativepad(), but that's off topic here.

=begin comment

TODO Write a set of cookbook documents and link to them.

=end comment

=head2 Creating an RSA keypair using raw key data

 #include <openssl/evp.h>

 /*
  * These are extremely small to make this example simple.  A real
  * and secure application will not use such small numbers.  A real
  * and secure application is expected to use BIGNUMs, and to build
  * this array dynamically.
  */
 unsigned long rsa_n = 0xbc747fc5;
 unsigned long rsa_e = 0x10001;
 unsigned long rsa_d = 0x7b133399;
 OSSL_PARAM params[] = {
     OSSL_PARAM_ulong("n", &rsa_n),
     OSSL_PARAM_ulong("e", &rsa_e),
     OSSL_PARAM_ulong("d", &rsa_d),
     OSSL_PARAM_END
 };

 int main()
 {
     EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
     EVP_PKEY *pkey = NULL;

     if (ctx == NULL
         || !EVP_PKEY_key_fromdata_init(ctx)
         || !EVP_PKEY_fromdata(ctx, &pkey, params))
         exit(1);

     /* Do what you want with |pkey| */
 }

=head2 Creating an ECC keypair using raw key data

 #include <openssl/evp.h>

 /*
  * These arrays represent large numbers, big endian organization.
  * In a real application, these would probably be bignums that get
  * converted to the native integer organization with BN_bn2nativepad().
  * We're not doing that here, since this is not an example of BIGNUM
  * functionality, but an example of EVP_PKEY_fromdata().
  */
 #ifndef B_ENDIAN
 # error "We haven't prepared little endian arrays"
 #endif
 const unsigned char priv[] = {
     0xb9, 0x2f, 0x3c, 0xe6, 0x2f, 0xfb, 0x45, 0x68,
     0x39, 0x96, 0xf0, 0x2a, 0xaf, 0x6c, 0xda, 0xf2,
     0x89, 0x8a, 0x27, 0xbf, 0x39, 0x9b, 0x7e, 0x54,
     0x21, 0xc2, 0xa1, 0xe5, 0x36, 0x12, 0x48, 0x5d
 };
 const unsigned char pub[] = {
     0x04, 0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c,
     0x5e, 0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f,
     0x58, 0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6,
     0xeb, 0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd,
     0xe5, 0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75,
     0xff, 0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02,
     0x25, 0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16,
     0x2f, 0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a,
     0x47
 };
 const OSSL_PARAM params[] = {
     OSSL_PARAM_utf8_string("curve-name", "prime256v1"),
     OSSL_PARAM_BN("priv", priv, sizeof(priv)),
     OSSL_PARAM_BN("pub", pub, sizeof(pub)),
     OSSL_PARAM_END
 };

 int main()
 {
     EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
     EVP_PKEY *pkey = NULL;

     if (ctx == NULL
         || !EVP_PKEY_key_fromdata_init(ctx)
         || !EVP_PKEY_fromdata(ctx, &pkey, params))
         exit(1);

     /* Do what you want with |pkey| */
 }

=head2 Finding out params for an unknown key type

 #include <openssl/evp.h>

 /* Program expects a key type as first argument */
 int main(int argc, char *argv[])
 {
     EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, argv[1], NULL);
     const *OSSL_PARAM *settable_params = NULL;

     if (ctx == NULL
         || (settable_params = EVP_PKEY_key_fromdata_settable(ctx)) == NULL)
         exit(1);

     for (; settable_params->key != NULL; settable_params++) {
         const char *datatype = NULL;

         switch (settable_params->data_type) {
         case OSSL_PARAM_INTEGER:
             datatype = "integer";
             break;
         case OSSL_PARAM_UNSIGNED_INTEGER:
             datatype = "unsigned integer";
             break;
         case OSSL_PARAM_UTF8_STRING:
             datatype = "printable string (utf-8 encoding expected)";
             break;
         case OSSL_PARAM_UTF8_PTR:
             datatype = "printable string pointer (utf-8 encoding expected)";
             break;
         case OSSL_PARAM_OCTET_STRING:
             datatype = "octet string";
             break;
         case OSSL_PARAM_OCTET_PTR:
             datatype = "octet string pointer";
             break;
         }
         printf("%s : %s ", settable_params->key, datatype);
         if (settable_params->data_size == 0)
             printf("(unlimited size)");
         else
             printf("(maximum size %zu)", settable_params->data_size);
     }
 }

The descriptor L<OSSL_PARAM(3)> returned by
EVP_PKEY_key_fromdata_settable() may also be used programmatically, for
example with L<OSSL_PARAM_allocate_from_text(3)>.

=head1 SEE ALSO

L<EVP_PKEY_CTX_new(3)>, L<provider(7)>, L<EVP_PKEY_gettable_params(3)>,
L<OSSL_PARAM(3)>,
L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>,
L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>,
L<EVP_PKEY-ED25519(7)>

=head1 HISTORY

These functions 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
46e2dd05 RL	1	=pod
	2
	3	=head1 NAME
	4
	5	EVP_PKEY_param_fromdata_init, EVP_PKEY_key_fromdata_init, EVP_PKEY_fromdata,
	6	EVP_PKEY_param_fromdata_settable, EVP_PKEY_key_fromdata_settable
b305452f	7	- functions to create key parameters and keys from user data
46e2dd05 RL	8
	9	=head1 SYNOPSIS
	10
	11	#include <openssl/evp.h>
	12
	13	int EVP_PKEY_param_fromdata_init(EVP_PKEY_CTX *ctx);
	14	int EVP_PKEY_key_fromdata_init(EVP_PKEY_CTX *ctx);
	15	int EVP_PKEY_fromdata(EVP_PKEY_CTX ctx, EVP_PKEY *ppkey, OSSL_PARAM params[]);
	16	const OSSL_PARAM EVP_PKEY_param_fromdata_settable(EVP_PKEY_CTX ctx);
	17	const OSSL_PARAM EVP_PKEY_key_fromdata_settable(EVP_PKEY_CTX ctx);
	18
	19	=head1 DESCRIPTION
	20
476de2e5 RL	21	The functions described here are used to create new keys from user
	22	provided key data, such as I<n>, I<e> and I<d> for a minimal RSA
	23	keypair.
	24
8c1cbc72	25	These functions use an B<EVP_PKEY_CTX> context, which should primarily
476de2e5 RL	26	be created with L<EVP_PKEY_CTX_new_from_name(3)> or
	27	L<EVP_PKEY_CTX_new_id(3)>.
	28
	29	The exact key data that the user can pass depends on the key type.
	30	These are passed as an L<OSSL_PARAM(3)> array.
	31
46e2dd05	32	EVP_PKEY_param_fromdata_init() initializes a public key algorithm context
b305452f	33	for creating key parameters from user data.
46e2dd05 RL	34
	35	EVP_PKEY_key_fromdata_init() initializes a public key algorithm context for
	36	creating a key from user data.
	37
476de2e5 RL	38	EVP_PKEY_fromdata() creates the structure to store key parameters or a
476de2e5 RL	39	key, given data from I<params> and a context that's been initialized with
9e537cd2 SL	40	EVP_PKEY_param_fromdata_init() or EVP_PKEY_key_fromdata_init(). The result is
	41	written to I<*ppkey>. The parameters that can be used for various types of key
	42	are as described by the diverse "Common parameters" sections of the
	43	L<B<EVP_PKEY-RSA>(7)\|EVP_PKEY-RSA(7)/Common RSA parameters>,
	44	L<B<EVP_PKEY-DSA>(7)\|EVP_PKEY-DSA(7)/Common DSA & DH parameters>,
	45	L<B<EVP_PKEY-DH>(7)\|EVP_PKEY-DH(7)/Common DH parameters>,
	46	L<B<EVP_PKEY-EC>(7)\|EVP_PKEY-EC(7)/Common EC parameters>,
	47	L<B<EVP_PKEY-ED448>(7)\|EVP_PKEY-ED448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
	48	L<B<EVP_PKEY-X25519>(7)\|EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
	49	L<B<EVP_PKEY-X448>(7)\|EVP_PKEY-X448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
	50	and L<B<EVP_PKEY-ED25519>(7)\|EVP_PKEY-ED25519(7)/Common X25519, X448, ED25519 and ED448 parameters> pages.
	51
	52	=for comment the awful list of links above is made this way so we get nice
	53	rendering as a man-page while still getting proper links in HTML
46e2dd05 RL	54
	55	EVP_PKEY_param_fromdata_settable() and EVP_PKEY_key_fromdata_settable()
	56	get a constant B<OSSL_PARAM> array that describes the settable parameters
	57	that can be used with EVP_PKEY_fromdata().
	58	See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
	59
	60	=head1 NOTES
	61
	62	These functions only work with key management methods coming from a
	63	provider.
	64
	65	=for comment We may choose to make this available for legacy methods too...
	66
	67	=head1 RETURN VALUES
	68
	69	EVP_PKEY_key_fromdata_init(), EVP_PKEY_param_fromdata_init() and
	70	EVP_PKEY_fromdata() return 1 for success and 0 or a negative value for
	71	failure. In particular a return value of -2 indicates the operation is
	72	not supported by the public key algorithm.
	73
476de2e5 RL	74	=head1 EXAMPLES
	75
	76	These examples are very terse for the sake of staying on topic, which
	77	is the EVP_PKEY_fromdata() set of functions. In real applications,
	78	BIGNUMs would be handled and converted to byte arrays with
	79	BN_bn2nativepad(), but that's off topic here.
	80
	81	=begin comment
	82
	83	TODO Write a set of cookbook documents and link to them.
	84
	85	=end comment
	86
	87	=head2 Creating an RSA keypair using raw key data
	88
	89	#include <openssl/evp.h>
	90
	91	/*
	92	* These are extremely small to make this example simple. A real
	93	* and secure application will not use such small numbers. A real
	94	* and secure application is expected to use BIGNUMs, and to build
	95	* this array dynamically.
	96	*/
5e427a43	97	unsigned long rsa_n = 0xbc747fc5;
	98	unsigned long rsa_e = 0x10001;
	99	unsigned long rsa_d = 0x7b133399;
	100	OSSL_PARAM params[] = {
476de2e5 RL	101	OSSL_PARAM_ulong("n", &rsa_n),
	102	OSSL_PARAM_ulong("e", &rsa_e),
	103	OSSL_PARAM_ulong("d", &rsa_d),
	104	OSSL_PARAM_END
	105	};
60d53313	106
476de2e5 RL	107	int main()
	108	{
	109	EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
	110	EVP_PKEY *pkey = NULL;
	111
	112	if (ctx == NULL
	113	\|\| !EVP_PKEY_key_fromdata_init(ctx)
	114	\|\| !EVP_PKEY_fromdata(ctx, &pkey, params))
	115	exit(1);
	116
	117	/* Do what you want with \|pkey\| */
	118	}
	119
	120	=head2 Creating an ECC keypair using raw key data
	121
	122	#include <openssl/evp.h>
	123
	124	/*
	125	* These arrays represent large numbers, big endian organization.
	126	* In a real application, these would probably be bignums that get
	127	* converted to the native integer organization with BN_bn2nativepad().
	128	* We're not doing that here, since this is not an example of BIGNUM
	129	* functionality, but an example of EVP_PKEY_fromdata().
	130	*/
	131	#ifndef B_ENDIAN
	132	# error "We haven't prepared little endian arrays"
	133	#endif
	134	const unsigned char priv[] = {
	135	0xb9, 0x2f, 0x3c, 0xe6, 0x2f, 0xfb, 0x45, 0x68,
	136	0x39, 0x96, 0xf0, 0x2a, 0xaf, 0x6c, 0xda, 0xf2,
	137	0x89, 0x8a, 0x27, 0xbf, 0x39, 0x9b, 0x7e, 0x54,
	138	0x21, 0xc2, 0xa1, 0xe5, 0x36, 0x12, 0x48, 0x5d
	139	};
	140	const unsigned char pub[] = {
	141	0x04, 0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c,
	142	0x5e, 0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f,
	143	0x58, 0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6,
	144	0xeb, 0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd,
	145	0xe5, 0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75,
	146	0xff, 0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02,
	147	0x25, 0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16,
	148	0x2f, 0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a,
	149	0x47
	150	};
	151	const OSSL_PARAM params[] = {
	152	OSSL_PARAM_utf8_string("curve-name", "prime256v1"),
	153	OSSL_PARAM_BN("priv", priv, sizeof(priv)),
	154	OSSL_PARAM_BN("pub", pub, sizeof(pub)),
	155	OSSL_PARAM_END
	156	};
	157
	158	int main()
	159	{
	160	EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
	161	EVP_PKEY *pkey = NULL;
	162
	163	if (ctx == NULL
	164	\|\| !EVP_PKEY_key_fromdata_init(ctx)
	165	\|\| !EVP_PKEY_fromdata(ctx, &pkey, params))
	166	exit(1);
	167
	168	/* Do what you want with \|pkey\| */
	169	}
	170
171	=head2 Finding out params for an unknown key type
172
173	#include <openssl/evp.h>
174
175	/* Program expects a key type as first argument */
176	int main(int argc, char *argv[])
177	{
178	EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, argv[1], NULL);
179	const OSSL_PARAM settable_params = NULL;
180
181	if (ctx == NULL
182	\|\| (settable_params = EVP_PKEY_key_fromdata_settable(ctx)) == NULL)
183	exit(1);
184
185	for (; settable_params->key != NULL; settable_params++) {
186	const char *datatype = NULL;
187
188	switch (settable_params->data_type) {
189	case OSSL_PARAM_INTEGER:
190	datatype = "integer";
191	break;
192	case OSSL_PARAM_UNSIGNED_INTEGER:
193	datatype = "unsigned integer";
194	break;
195	case OSSL_PARAM_UTF8_STRING:
196	datatype = "printable string (utf-8 encoding expected)";
197	break;
198	case OSSL_PARAM_UTF8_PTR:
199	datatype = "printable string pointer (utf-8 encoding expected)";
200	break;
201	case OSSL_PARAM_OCTET_STRING:
202	datatype = "octet string";
203	break;
204	case OSSL_PARAM_OCTET_PTR:
205	datatype = "octet string pointer";
206	break;
207	}
208	printf("%s : %s ", settable_params->key, datatype);
209	if (settable_params->data_size == 0)
210	printf("(unlimited size)");
211	else
212	printf("(maximum size %zu)", settable_params->data_size);
213	}
214	}
215
216	The descriptor L<OSSL_PARAM(3)> returned by
217	EVP_PKEY_key_fromdata_settable() may also be used programmatically, for
218	example with L<OSSL_PARAM_allocate_from_text(3)>.
219
46e2dd05 RL	220	=head1 SEE ALSO
46e2dd05 RL	221
476de2e5	222	L<EVP_PKEY_CTX_new(3)>, L<provider(7)>, L<EVP_PKEY_gettable_params(3)>,
9e537cd2 SL	223	L<OSSL_PARAM(3)>,
	224	L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>,
	225	L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>,
	226	L<EVP_PKEY-ED25519(7)>
46e2dd05 RL	227
	228	=head1 HISTORY
	229
	230	These functions were added in OpenSSL 3.0.
	231
	232	=head1 COPYRIGHT
	233
9e537cd2	234	Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
46e2dd05 RL	235
	236	Licensed under the Apache License 2.0 (the "License"). You may not use
	237	this file except in compliance with the License. You can obtain a copy
	238	in the file LICENSE in the source distribution or at
	239	L<https://www.openssl.org/source/license.html>.
	240
	241	=cut
	242