]>
Commit | Line | Data |
---|---|---|
aa93b18c DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init, EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, EVP_PKEY_CTX_get_keygen_info, EVP_PKEVP_PKEY_CTX_set_app_data, EVP_PKEY_CTX_get_app_data - key and parameter generation functions | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/evp.h> | |
10 | ||
11 | int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx); | |
12 | int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); | |
13 | int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx); | |
14 | int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); | |
15 | ||
16 | typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx); | |
17 | ||
18 | void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb); | |
19 | EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx); | |
20 | ||
21 | int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx); | |
22 | ||
23 | void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data); | |
24 | void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx); | |
25 | ||
26 | =head1 DESCRIPTION | |
27 | ||
28 | The EVP_PKEY_keygen_init() function initializes a public key algorithm | |
186bb907 | 29 | context using key B<pkey> for a key generation operation. |
aa93b18c DSH |
30 | |
31 | The EVP_PKEY_keygen() function performs a key generation operation, the | |
32 | generated key is written to B<ppkey>. | |
33 | ||
34 | The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar | |
35 | except parameters are generated. | |
36 | ||
37 | The function EVP_PKEY_set_cb() sets the key or parameter generation callback | |
38 | to B<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter | |
39 | generation callback. | |
40 | ||
41 | The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated | |
42 | with the generation operation. If B<idx> is -1 the total number of | |
43 | parameters available is returned. Any non negative value returns the value of | |
44 | that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for | |
45 | B<idx> should only be called within the generation callback. | |
46 | ||
186bb907 | 47 | If the callback returns 0 then the key generation operation is aborted and an |
aa93b18c DSH |
48 | error occurs. This might occur during a time consuming operation where |
49 | a user clicks on a "cancel" button. | |
50 | ||
51 | The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set | |
52 | and retrieve an opaque pointer. This can be used to set some application | |
53 | defined value which can be retrieved in the callback: for example a handle | |
54 | which is used to update a "progress dialog". | |
55 | ||
56 | =head1 NOTES | |
57 | ||
58 | After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm | |
59 | specific control operations can be performed to set any appropriate parameters | |
60 | for the operation. | |
61 | ||
62 | The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than | |
63 | once on the same context if several operations are performed using the same | |
64 | parameters. | |
65 | ||
66 | The meaning of the parameters passed to the callback will depend on the | |
186bb907 | 67 | algorithm and the specific implementation of the algorithm. Some might not |
aa93b18c DSH |
68 | give any useful information at all during key or parameter generation. Others |
69 | might not even call the callback. | |
70 | ||
71 | The operation performed by key or parameter generation depends on the algorithm | |
72 | used. In some cases (e.g. EC with a supplied named curve) the "generation" | |
73 | option merely sets the appropriate fields in an EVP_PKEY structure. | |
74 | ||
75 | In OpenSSL an EVP_PKEY structure containing a private key also contains the | |
76 | public key components and parameters (if any). An OpenSSL private key is | |
77 | equivalent to what some libraries call a "key pair". A private key can be used | |
78 | in functions which require the use of a public key or parameters. | |
79 | ||
80 | =head1 RETURN VALUES | |
81 | ||
82 | EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and | |
83 | EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure. | |
84 | In particular a return value of -2 indicates the operation is not supported by | |
85 | the public key algorithm. | |
86 | ||
87 | =head1 EXAMPLES | |
88 | ||
89 | Generate a 2048 bit RSA key: | |
90 | ||
91 | #include <openssl/evp.h> | |
92 | #include <openssl/rsa.h> | |
93 | ||
94 | EVP_PKEY_CTX *ctx; | |
95 | EVP_PKEY *pkey = NULL; | |
96 | ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL); | |
97 | if (!ctx) | |
98 | /* Error occurred */ | |
99 | if (EVP_PKEY_keygen_init(ctx) <= 0) | |
100 | /* Error */ | |
101 | if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0) | |
102 | /* Error */ | |
103 | ||
104 | /* Generate key */ | |
105 | if (EVP_PKEY_keygen(ctx, &pkey) <= 0) | |
106 | /* Error */ | |
107 | ||
108 | Generate a key from a set of parameters: | |
109 | ||
110 | #include <openssl/evp.h> | |
111 | #include <openssl/rsa.h> | |
112 | ||
113 | EVP_PKEY_CTX *ctx; | |
114 | EVP_PKEY *pkey = NULL, *param; | |
115 | /* Assumed param is set up already */ | |
116 | ctx = EVP_PKEY_CTX_new(param); | |
117 | if (!ctx) | |
118 | /* Error occurred */ | |
119 | if (EVP_PKEY_keygen_init(ctx) <= 0) | |
120 | /* Error */ | |
121 | ||
122 | /* Generate key */ | |
123 | if (EVP_PKEY_keygen(ctx, &pkey) <= 0) | |
124 | /* Error */ | |
125 | ||
126 | Example of generation callback for OpenSSL public key implementations: | |
127 | ||
128 | /* Application data is a BIO to output status to */ | |
129 | ||
130 | EVP_PKEY_CTX_set_app_data(ctx, status_bio); | |
131 | ||
132 | static int genpkey_cb(EVP_PKEY_CTX *ctx) | |
133 | { | |
134 | char c='*'; | |
135 | BIO *b = EVP_PKEY_CTX_get_app_data(ctx); | |
136 | int p; | |
137 | p = EVP_PKEY_CTX_get_keygen_info(ctx, 0); | |
138 | if (p == 0) c='.'; | |
139 | if (p == 1) c='+'; | |
140 | if (p == 2) c='*'; | |
141 | if (p == 3) c='\n'; | |
142 | BIO_write(b,&c,1); | |
143 | (void)BIO_flush(b); | |
144 | return 1; | |
145 | } | |
146 | ||
147 | =head1 SEE ALSO | |
148 | ||
9b86974e RS |
149 | L<EVP_PKEY_CTX_new(3)>, |
150 | L<EVP_PKEY_encrypt(3)>, | |
151 | L<EVP_PKEY_decrypt(3)>, | |
152 | L<EVP_PKEY_sign(3)>, | |
153 | L<EVP_PKEY_verify(3)>, | |
154 | L<EVP_PKEY_verify_recover(3)>, | |
155 | L<EVP_PKEY_derive(3)> | |
aa93b18c DSH |
156 | |
157 | =head1 HISTORY | |
158 | ||
fb552ac6 | 159 | These functions were first added to OpenSSL 1.0.0. |
aa93b18c DSH |
160 | |
161 | =cut |