]>
Commit | Line | Data |
---|---|---|
4db48ec0 LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_tmp_rsa_callback, SSL_CTX_set_tmp_rsa, SSL_CTX_need_tmp_rsa, SSL_set_tmp_rsa_callback, SSL_set_tmp_rsa, SSL_need_tmp_rsa - handle RSA keys for ephemeral key exchange | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | void SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx, | |
12 | RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)); | |
13 | long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa); | |
14 | long SSL_CTX_need_tmp_rsa(SSL_CTX *ctx); | |
15 | ||
16 | void SSL_set_tmp_rsa_callback(SSL_CTX *ctx, | |
17 | RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)); | |
18 | long SSL_set_tmp_rsa(SSL *ssl, RSA *rsa) | |
19 | long SSL_need_tmp_rsa(SSL *ssl) | |
20 | ||
da736b31 | 21 | RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength); |
4db48ec0 LJ |
22 | |
23 | =head1 DESCRIPTION | |
24 | ||
25 | SSL_CTX_set_tmp_rsa_callback() sets the callback function for B<ctx> to be | |
26 | used when a temporary/ephemeral RSA key is required to B<tmp_rsa_callback>. | |
37f599bc LJ |
27 | The callback is inherited by all SSL objects newly created from B<ctx> |
28 | with <SSL_new(3)|SSL_new(3)>. Already created SSL objects are not affected. | |
4db48ec0 LJ |
29 | |
30 | SSL_CTX_set_tmp_rsa() sets the temporary/ephemeral RSA key to be used to be | |
37f599bc LJ |
31 | B<rsa>. The key is inherited by all SSL objects newly created from B<ctx> |
32 | with <SSL_new(3)|SSL_new(3)>. Already created SSL objects are not affected. | |
4db48ec0 | 33 | |
3b80e3aa | 34 | SSL_CTX_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed |
37f599bc LJ |
35 | for RSA-based strength-limited 'exportable' ciphersuites because a RSA key |
36 | with a keysize larger than 512 bits is installed. | |
4db48ec0 LJ |
37 | |
38 | SSL_set_tmp_rsa_callback() sets the callback only for B<ssl>. | |
39 | ||
40 | SSL_set_tmp_rsa() sets the key only for B<ssl>. | |
41 | ||
3b80e3aa | 42 | SSL_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed, |
37f599bc LJ |
43 | for RSA-based strength-limited 'exportable' ciphersuites because a RSA key |
44 | with a keysize larger than 512 bits is installed. | |
4db48ec0 LJ |
45 | |
46 | These functions apply to SSL/TLS servers only. | |
47 | ||
48 | =head1 NOTES | |
49 | ||
50 | When using a cipher with RSA authentication, an ephemeral RSA key exchange | |
51 | can take place. In this case the session data are negotiated using the | |
52 | ephemeral/temporary RSA key and the RSA key supplied and certified | |
53 | by the certificate chain is only used for signing. | |
54 | ||
37f599bc LJ |
55 | Under previous export restrictions, ciphers with RSA keys shorter (512 bits) |
56 | than the usual key length of 1024 bits were created. To use these ciphers | |
57 | with RSA keys of usual length, an ephemeral key exchange must be performed, | |
58 | as the normal (certified) key cannot be directly used. | |
59 | ||
4db48ec0 LJ |
60 | Using ephemeral RSA key exchange yields forward secrecy, as the connection |
61 | can only be decrypted, when the RSA key is known. By generating a temporary | |
62 | RSA key inside the server application that is lost when the application | |
63 | is left, it becomes impossible for an attacker to decrypt past sessions, | |
64 | even if he gets hold of the normal (certified) RSA key, as this key was | |
37f599bc LJ |
65 | used for signing only. The downside is that creating a RSA key is |
66 | computationally expensive. | |
67 | ||
68 | Additionally, the use of ephemeral RSA key exchange is only allowed in | |
69 | the TLS standard, when the RSA key can be used for signing only, that is | |
70 | for export ciphers. Using ephemeral RSA key exchange for other purposes | |
71 | violates the standard and can break interoperability with clients. | |
72 | It is therefore strongly recommended to not use ephemeral RSA key | |
0b30fc90 | 73 | exchange and use DHE (Ephemeral Diffie-Hellman) key exchange instead |
37f599bc | 74 | in order to achieve forward secrecy (see |
9b86974e | 75 | L<SSL_CTX_set_tmp_dh_callback(3)>). |
37f599bc | 76 | |
ce325c60 DSH |
77 | An application may either directly specify the key or can supply the key via a |
78 | callback function. The callback approach has the advantage, that the callback | |
79 | may generate the key only in case it is actually needed. As the generation of a | |
80 | RSA key is however costly, it will lead to a significant delay in the handshake | |
81 | procedure. Another advantage of the callback function is that it can supply | |
82 | keys of different size while the explicit setting of the key is only useful for | |
83 | key size of 512 bits to satisfy the export restricted ciphers and does give | |
84 | away key length if a longer key would be allowed. | |
4db48ec0 LJ |
85 | |
86 | The B<tmp_rsa_callback> is called with the B<keylength> needed and | |
87 | the B<is_export> information. The B<is_export> flag is set, when the | |
88 | ephemeral RSA key exchange is performed with an export cipher. | |
89 | ||
90 | =head1 EXAMPLES | |
91 | ||
92 | Generate temporary RSA keys to prepare ephemeral RSA key exchange. As the | |
37f599bc | 93 | generation of a RSA key costs a lot of computer time, they saved for later |
4db48ec0 LJ |
94 | reuse. For demonstration purposes, two keys for 512 bits and 1024 bits |
95 | respectively are generated. | |
96 | ||
97 | ... | |
98 | /* Set up ephemeral RSA stuff */ | |
99 | RSA *rsa_512 = NULL; | |
100 | RSA *rsa_1024 = NULL; | |
37f599bc LJ |
101 | |
102 | rsa_512 = RSA_generate_key(512,RSA_F4,NULL,NULL); | |
103 | if (rsa_512 == NULL) | |
4db48ec0 | 104 | evaluate_error_queue(); |
37f599bc LJ |
105 | |
106 | rsa_1024 = RSA_generate_key(1024,RSA_F4,NULL,NULL); | |
107 | if (rsa_1024 == NULL) | |
108 | evaluate_error_queue(); | |
109 | ||
4db48ec0 LJ |
110 | ... |
111 | ||
112 | RSA *tmp_rsa_callback(SSL *s, int is_export, int keylength) | |
113 | { | |
114 | RSA *rsa_tmp=NULL; | |
115 | ||
116 | switch (keylength) { | |
117 | case 512: | |
118 | if (rsa_512) | |
119 | rsa_tmp = rsa_512; | |
37f599bc LJ |
120 | else { /* generate on the fly, should not happen in this example */ |
121 | rsa_tmp = RSA_generate_key(keylength,RSA_F4,NULL,NULL); | |
4db48ec0 LJ |
122 | rsa_512 = rsa_tmp; /* Remember for later reuse */ |
123 | } | |
124 | break; | |
125 | case 1024: | |
126 | if (rsa_1024) | |
127 | rsa_tmp=rsa_1024; | |
128 | else | |
37f599bc | 129 | should_not_happen_in_this_example(); |
4db48ec0 LJ |
130 | break; |
131 | default: | |
132 | /* Generating a key on the fly is very costly, so use what is there */ | |
133 | if (rsa_1024) | |
134 | rsa_tmp=rsa_1024; | |
135 | else | |
136 | rsa_tmp=rsa_512; /* Use at least a shorter key */ | |
137 | } | |
138 | return(rsa_tmp); | |
139 | } | |
140 | ||
141 | =head1 RETURN VALUES | |
142 | ||
143 | SSL_CTX_set_tmp_rsa_callback() and SSL_set_tmp_rsa_callback() do not return | |
144 | diagnostic output. | |
145 | ||
146 | SSL_CTX_set_tmp_rsa() and SSL_set_tmp_rsa() do return 1 on success and 0 | |
147 | on failure. Check the error queue to find out the reason of failure. | |
148 | ||
149 | SSL_CTX_need_tmp_rsa() and SSL_need_tmp_rsa() return 1 if a temporary | |
150 | RSA key is needed and 0 otherwise. | |
151 | ||
152 | =head1 SEE ALSO | |
153 | ||
9b86974e RS |
154 | L<ssl(3)>, L<SSL_CTX_set_cipher_list(3)>, |
155 | L<SSL_CTX_set_options(3)>, | |
156 | L<SSL_CTX_set_tmp_dh_callback(3)>, | |
157 | L<SSL_new(3)>, L<ciphers(1)> | |
4db48ec0 LJ |
158 | |
159 | =cut |