71ba642180d2c56228479bda0c273e8723fbed51
[openssl.git] / doc / man3 / EVP_PKEY_fromdata.pod
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
7 - functions to create key parameters and keys from user data
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
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
25 These functions use an B<EVP_PKEY_CTX> context, which should primarly
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
32 EVP_PKEY_param_fromdata_init() initializes a public key algorithm context
33 for creating key parameters from user data.
34
35 EVP_PKEY_key_fromdata_init() initializes a public key algorithm context for
36 creating a key from user data.
37
38 EVP_PKEY_fromdata() creates the structure to store key parameters or a
39 key, given data from I<params> and a context that's been initialized with
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
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
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   */
97  unsigned long rsa_n = 0xbc747fc5;
98  unsigned long rsa_e = 0x10001;
99  unsigned long rsa_d = 0x7b133399;
100  OSSL_PARAM params[] = {
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  };
106      
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
220 =head1 SEE ALSO
221
222 L<EVP_PKEY_CTX_new(3)>, L<provider(7)>, L<EVP_PKEY_gettable_params(3)>,
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)>
227
228 =head1 HISTORY
229
230 These functions were added in OpenSSL 3.0.
231
232 =head1 COPYRIGHT
233
234 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
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