2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
28 * A "profile" is an initialisation function for a SSL context, that
29 * configures a list of cipher suites and algorithm implementations.
30 * While BearSSL comes with a few predefined profiles, you might one
31 * to define you own, using the example below as guidance.
33 * Each individual initialisation call sets a parameter or an algorithm
34 * support. Setting a specific algorithm pulls in the implementation of
35 * that algorithm in the compiled binary, as per static linking
36 * behaviour. Removing some of this calls will then reduce total code
37 * footprint, but also mechanically prevents some features to be
38 * supported (protocol versions and cipher suites).
40 * The two below define profiles for the client and the server contexts,
41 * respectively. Of course, in a typical size-constrained application,
42 * you would use one or the other, not both, to avoid pulling in code
47 example_client_profile(br_ssl_client_context
*cc
48 /* and possibly some other arguments */)
51 * A list of cipher suites, by preference (first is most
52 * preferred). The list below contains all cipher suites supported
53 * by BearSSL; trim it done to your needs.
55 static const uint16_t suites
[] = {
56 BR_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
,
57 BR_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
,
58 BR_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
,
59 BR_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
,
60 BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
,
61 BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
,
62 BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
,
63 BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
,
64 BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
,
65 BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
,
66 BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
,
67 BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
,
68 BR_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
,
69 BR_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
,
70 BR_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384
,
71 BR_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384
,
72 BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
,
73 BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
,
74 BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384
,
75 BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384
,
76 BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
,
77 BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
,
78 BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA
,
79 BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA
,
80 BR_TLS_RSA_WITH_AES_128_GCM_SHA256
,
81 BR_TLS_RSA_WITH_AES_256_GCM_SHA384
,
82 BR_TLS_RSA_WITH_AES_128_CBC_SHA256
,
83 BR_TLS_RSA_WITH_AES_256_CBC_SHA256
,
84 BR_TLS_RSA_WITH_AES_128_CBC_SHA
,
85 BR_TLS_RSA_WITH_AES_256_CBC_SHA
,
86 BR_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
,
87 BR_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
,
88 BR_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
,
89 BR_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
,
90 BR_TLS_RSA_WITH_3DES_EDE_CBC_SHA
94 * Client context must be cleared at some point. This sets
95 * every value and pointer to 0 or NULL.
97 br_ssl_client_zero(cc
);
100 * Define minimum and maximum protocol versions. Supported
106 br_ssl_engine_set_versions(&cc
->eng
, BR_TLS10
, BR_TLS12
);
109 * Set the PRF implementation(s).
110 * For TLS 1.0 and 1.1, the "prf10" is needed.
111 * For TLS 1.2, this depends on the cipher suite:
112 * -- cipher suites with a name ending in "SHA384" need "prf_sha384";
113 * -- all others need "prf_sha256".
115 * Note that a cipher suite like TLS_RSA_WITH_AES_128_CBC_SHA will
116 * use SHA-1 for the per-record MAC (that's what the final "SHA"
117 * means), but still SHA-256 for the PRF when selected along with
118 * the TLS-1.2 protocol version.
120 br_ssl_engine_set_prf10(&cc
->eng
, &br_tls10_prf
);
121 br_ssl_engine_set_prf_sha256(&cc
->eng
, &br_tls12_sha256_prf
);
122 br_ssl_engine_set_prf_sha384(&cc
->eng
, &br_tls12_sha384_prf
);
125 * Set hash functions for the engine. Required hash functions
126 * depend on the protocol and cipher suite:
128 * -- TLS 1.0 and 1.1 require both MD5 and SHA-1.
129 * -- With TLS 1.2, cipher suites with a name ending in "SHA384"
131 * -- With TLS 1.2, cipher suites with a name ending in "SHA256"
133 * -- With TLS 1.2, cipher suites with a name ending in "SHA"
134 * require both SHA-256 and SHA-1.
136 * Note that with current implementations, SHA-224 and SHA-256
137 * share the same file, so if you use one, you may have the other
138 * one with no additional overhead. Similarly, SHA-384 and SHA-512
139 * share the same implementation code.
141 br_ssl_engine_set_hash(&cc
->eng
, br_md5_ID
, &br_md5_vtable
);
142 br_ssl_engine_set_hash(&cc
->eng
, br_sha1_ID
, &br_sha1_vtable
);
143 br_ssl_engine_set_hash(&cc
->eng
, br_sha224_ID
, &br_sha224_vtable
);
144 br_ssl_engine_set_hash(&cc
->eng
, br_sha256_ID
, &br_sha256_vtable
);
145 br_ssl_engine_set_hash(&cc
->eng
, br_sha384_ID
, &br_sha384_vtable
);
146 br_ssl_engine_set_hash(&cc
->eng
, br_sha512_ID
, &br_sha512_vtable
);
149 * Set the cipher suites. All specified cipher suite MUST be
150 * supported, and the relevant algorithms MUST have been
151 * configured (failure to provide needed implementations may
152 * trigger unwanted behaviours like segfaults or overflows).
154 br_ssl_engine_set_suites(&cc
->eng
, suites
,
155 (sizeof suites
) / (sizeof suites
[0]));
158 * Public-key algorithm imeplementations.
160 * -- RSA public core ("rsapub") is needed for "RSA" key exchange
161 * (cipher suites whose name starts with TLS_RSA).
163 * -- RSA signature verification ("rsavrfy") is needed for
164 * "ECDHE_RSA" cipher suites (not ECDH_RSA).
166 * -- Elliptic curve implementation ("ec") is needed for cipher
167 * suites that use elliptic curves (both "ECDH" and "ECDHE"
170 * -- ECDSA signature verification is needed for "ECDHE_ECDSA"
171 * cipher suites (but not for ECDH_ECDSA or ECDH_RSA).
173 * The RSA code comes in two variants, called "i31" and "i32".
174 * Right now, the "i31" is somewhat faster.
176 br_ssl_client_set_rsapub(cc
, &br_rsa_i31_public
);
177 br_ssl_client_set_rsavrfy(cc
, &br_rsa_i31_pkcs1_vrfy
);
178 br_ssl_engine_set_ec(&cc
->eng
, &br_ec_prime_i31
);
179 br_ssl_client_set_ecdsa(cc
, &br_ecdsa_i31_vrfy_asn1
);
183 * -- Cipher suites in AES_128_CBC, AES_256_CBC and 3DES_EDE_CBC
184 * need the CBC record handler ("set_cbc").
185 * -- Cipher suites in AES_128_GCM and AES_256_GCM need the GCM
186 * record handler ("set_gcm").
188 br_ssl_engine_set_cbc(&cc
->eng
,
189 &br_sslrec_in_cbc_vtable
,
190 &br_sslrec_out_cbc_vtable
);
191 br_ssl_engine_set_gcm(&cc
->eng
,
192 &br_sslrec_in_gcm_vtable
,
193 &br_sslrec_out_gcm_vtable
);
196 * Symmetric encryption:
197 * -- AES_128_CBC and AES_256_CBC require an "aes_cbc" implementation
198 * (actually two implementations, for encryption and decryption).
199 * -- 3DES_EDE_CBC requires a "des_cbc" implementation
200 * (actually two implementations, for encryption and decryption).
201 * -- AES_128_GCM and AES_256_GCM require an "aes_ctr" imeplementation
202 * and also a GHASH implementation.
204 * Two 3DES implementations are provided:
206 * des_tab Classical table-based implementation; it is
209 * dest_ct Constant-time DES/3DES implementation. It is
210 * slower than des_tab.
212 * Four AES implementations are provided:
214 * aes_ct Constant-time AES implementation, for 32-bit
217 * aes_ct64 Constant-time AES implementation, for 64-bit
218 * systems. It actually also runs on 32-bit systems,
219 * but, on such systems, it yields larger code and
220 * slightly worse performance. On 64-bit systems,
221 * aes_ct64 is about twice faster than aes_ct for
222 * CTR processing (GCM encryption and decryption),
223 * and for CBC (decryption only).
225 * aes_small Smallest implementation provided, but also the
226 * slowest, and it is not constant-time. Use it
227 * only if desperate for code size.
229 * aes_big Classical table-based AES implementation. This
230 * is decently fast and still resonably compact,
231 * but it is not constant-time.
233 * Whether having constant-time implementations is absolutely
234 * required for security depends on the context (in particular
235 * whether the target architecture actually has cache memory),
236 * and while side-channel analysis for non-constant-time AES
237 * code has been demonstrated in lab conditions, it certainly
238 * does not apply to all actual usages, and it has never been
239 * spotted in the wild. It is still considered cautious to use
240 * constant-time code by default, and to consider the other
241 * implementations only if duly measured performance issues make
244 br_ssl_engine_set_aes_cbc(&cc
->eng
,
245 &br_aes_ct_cbcenc_vtable
,
246 &br_aes_ct_cbcdec_vtable
);
247 br_ssl_engine_set_aes_ctr(&cc
->eng
,
248 &br_aes_ct_ctr_vtable
);
249 /* Alternate: aes_ct64
250 br_ssl_engine_set_aes_cbc(&cc->eng,
251 &br_aes_ct64_cbcenc_vtable,
252 &br_aes_ct64_cbcdec_vtable);
253 br_ssl_engine_set_aes_ctr(&cc->eng,
254 &br_aes_ct64_ctr_vtable);
256 /* Alternate: aes_small
257 br_ssl_engine_set_aes_cbc(&cc->eng,
258 &br_aes_small_cbcenc_vtable,
259 &br_aes_small_cbcdec_vtable);
260 br_ssl_engine_set_aes_ctr(&cc->eng,
261 &br_aes_small_ctr_vtable);
263 /* Alternate: aes_big
264 br_ssl_engine_set_aes_cbc(&cc->eng,
265 &br_aes_big_cbcenc_vtable,
266 &br_aes_big_cbcdec_vtable);
267 br_ssl_engine_set_aes_ctr(&cc->eng,
268 &br_aes_big_ctr_vtable);
270 br_ssl_engine_set_des_cbc(&cc
->eng
,
271 &br_des_ct_cbcenc_vtable
,
272 &br_des_ct_cbcdec_vtable
);
273 /* Alternate: des_tab
274 br_ssl_engine_set_des_cbc(&cc->eng,
275 &br_des_tab_cbcenc_vtable,
276 &br_des_tab_cbcdec_vtable);
280 * GHASH is needed for AES_128_GCM and AES_256_GCM. Three
281 * implementations are provided:
283 * ctmul Uses 32-bit multiplications with a 64-bit result.
285 * ctmul32 Uses 32-bit multiplications with a 32-bit result.
287 * ctmul64 Uses 64-bit multiplications with a 64-bit result.
289 * On 64-bit platforms, ctmul64 is the smallest and fastest of
290 * the three. On 32-bit systems, ctmul should be prefered. The
291 * ctmul32 implementation is meant to be used for the specific
292 * 32-bit systems that do not have a 32x32->64 multiplier (i.e.
293 * the ARM Cortex-M0 and Cortex-M0+).
295 * These implementations are all constant-time as long as the
296 * underlying multiplication opcode is constant-time (which is
297 * true for all modern systems, but not for older architectures
298 * such that ARM9 or 80486).
300 br_ssl_engine_set_ghash(&cc
->eng
,
302 /* Alternate: ghash_ctmul32
303 br_ssl_engine_set_ghash(&cc->eng,
306 /* Alternate: ghash_ctmul64
307 br_ssl_engine_set_ghash(&cc->eng,
313 * For a client, the normal case is to validate the server
314 * certificate with regards to a set of trust anchors. This
315 * entails using a br_x509_minimal_context structure, configured
316 * with the relevant algorithms, as shown below.
318 * Alternatively, the client could "know" the intended server
319 * public key through an out-of-band mechanism, in which case
320 * a br_x509_knownkey_context is appropriate, for a much reduced
323 * We assume here that the following extra parameters have been
326 * xc engine context (br_x509_minimal_context *)
327 * trust_anchors trust anchors (br_x509_trust_anchor *)
328 * trust_anchors_num number of trust anchors (size_t)
332 * The X.509 engine needs a hash function for processing the
333 * subject and issuer DN of certificates and trust anchors. Any
334 * supported hash function is appropriate; here we use SHA-256.
337 br_x509_minimal_init(xc
, &br_sha256_vtable
,
338 trust_anchors
, trust_anchors_num
);
341 * Set suites and asymmetric crypto implementations. We use the
342 * "i31" code for RSA (it is somewhat faster than the "i32"
343 * implementation). These implementations are used for
344 * signature verification on certificates, but not for the
345 * SSL-specific usage of the server's public key. For instance,
346 * if the server has an EC public key but the rest of the chain
347 * (intermediate CA, root...) use RSA, then you would need only
348 * the RSA verification function below.
350 br_x509_minimal_set_rsa(xc
, &br_rsa_i31_pkcs1_vrfy
);
351 br_x509_minimal_set_ecdsa(xc
,
352 &br_ec_prime_i31
, &br_ecdsa_i31_vrfy_asn1
);
355 * Set supported hash functions. These are for signatures on
356 * certificates. There again, you only need the hash functions
357 * that are actually used in certificates, but if a given
358 * function was included for the SSL engine, you may as well
361 * Note: the engine explicitly rejects signatures that use MD5.
362 * Thus, there is no need for MD5 here.
364 br_ssl_engine_set_hash(xc
, br_sha1_ID
, &br_sha1_vtable
);
365 br_ssl_engine_set_hash(xc
, br_sha224_ID
, &br_sha224_vtable
);
366 br_ssl_engine_set_hash(xc
, br_sha256_ID
, &br_sha256_vtable
);
367 br_ssl_engine_set_hash(xc
, br_sha384_ID
, &br_sha384_vtable
);
368 br_ssl_engine_set_hash(xc
, br_sha512_ID
, &br_sha512_vtable
);
371 * Link the X.509 engine in the SSL engine.
373 br_ssl_engine_set_x509(&cc
->eng
, &xc
->vtable
);
378 * Example server profile. Most of it is shared with the client
379 * profile, so see the comments in the client function for details.
381 * This example function assumes a server with a (unique) RSA private
382 * key, so the list of cipher suites is trimmed down for RSA.
385 example_server_profile(br_ssl_server_context
*cc
,
386 const br_x509_certificate
*chain
, size_t chain_len
,
387 const br_rsa_private_key
*sk
)
389 static const uint16_t suites
[] = {
390 BR_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
,
391 BR_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
,
392 BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
,
393 BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
,
394 BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
,
395 BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
,
396 BR_TLS_RSA_WITH_AES_128_GCM_SHA256
,
397 BR_TLS_RSA_WITH_AES_256_GCM_SHA384
,
398 BR_TLS_RSA_WITH_AES_128_CBC_SHA256
,
399 BR_TLS_RSA_WITH_AES_256_CBC_SHA256
,
400 BR_TLS_RSA_WITH_AES_128_CBC_SHA
,
401 BR_TLS_RSA_WITH_AES_256_CBC_SHA
,
402 BR_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
,
403 BR_TLS_RSA_WITH_3DES_EDE_CBC_SHA
406 br_ssl_server_zero(cc
);
407 br_ssl_engine_set_versions(&cc
->eng
, BR_TLS10
, BR_TLS12
);
409 br_ssl_engine_set_prf10(&cc
->eng
, &br_tls10_prf
);
410 br_ssl_engine_set_prf_sha256(&cc
->eng
, &br_tls12_sha256_prf
);
411 br_ssl_engine_set_prf_sha384(&cc
->eng
, &br_tls12_sha384_prf
);
414 * Apart from the requirements listed in the client side, these
415 * hash functions are also used by the server to compute its
416 * signature on ECDHE parameters. Which functions are needed
417 * depends on what the client may support; furthermore, the
418 * client may fail to send the relevant extension, in which
419 * case the server will default to whatever it can (as per the
420 * standard, it should be SHA-1 in that case).
422 br_ssl_engine_set_hash(&cc
->eng
, br_md5_ID
, &br_md5_vtable
);
423 br_ssl_engine_set_hash(&cc
->eng
, br_sha1_ID
, &br_sha1_vtable
);
424 br_ssl_engine_set_hash(&cc
->eng
, br_sha224_ID
, &br_sha224_vtable
);
425 br_ssl_engine_set_hash(&cc
->eng
, br_sha256_ID
, &br_sha256_vtable
);
426 br_ssl_engine_set_hash(&cc
->eng
, br_sha384_ID
, &br_sha384_vtable
);
427 br_ssl_engine_set_hash(&cc
->eng
, br_sha512_ID
, &br_sha512_vtable
);
429 br_ssl_engine_set_suites(&cc
->eng
, suites
,
430 (sizeof suites
) / (sizeof suites
[0]));
433 * Elliptic curve implementation is used for ECDHE suites (but
436 br_ssl_engine_set_ec(&cc
->eng
, &br_ec_prime_i31
);
439 * Set the "server policy": handler for the certificate chain
440 * and private key operations. Here, we indicate that the RSA
441 * private key is fit for both signing and decrypting, and we
442 * provide the two relevant implementations.
444 * BR_KEYTYPE_KEYX allows TLS_RSA_*, BR_KEYTYPE_SIGN allows
447 br_ssl_server_set_single_rsa(cc
, chain
, chain_len
, sk
,
448 BR_KEYTYPE_KEYX
| BR_KEYTYPE_SIGN
,
449 br_rsa_i31_private
, br_rsa_i31_pkcs1_sign
);
451 * If the server used an EC private key, this call would look
454 br_ssl_server_set_single_ec(cc, chain, chain_len, sk,
455 BR_KEYTYPE_KEYX | BR_KEYTYPE_SIGN,
456 cert_issuer_key_type,
457 &br_ec_prime_i31, br_ecdsa_i31_sign_asn1);
459 * Note the tricky points:
461 * -- "ECDH" cipher suites use only the EC code (&br_ec_prime_i31);
462 * the ECDHE_ECDSA cipher suites need both the EC code and
463 * the ECDSA signature implementation.
465 * -- For "ECDH" (not "ECDHE") cipher suites, the engine must
466 * know the key type (RSA or EC) for the intermediate CA that
467 * issued the server's certificate; this is an artefact of
468 * how the protocol is defined. BearSSL won't try to decode
469 * the server's certificate to obtain that information (it
470 * could do that, the code is there, but it would increase the
471 * footprint). So this must be provided by the caller.
473 * -- BR_KEYTYPE_KEYX allows ECDH, BR_KEYTYPE_SIGN allows
477 br_ssl_engine_set_cbc(&cc
->eng
,
478 &br_sslrec_in_cbc_vtable
,
479 &br_sslrec_out_cbc_vtable
);
480 br_ssl_engine_set_gcm(&cc
->eng
,
481 &br_sslrec_in_gcm_vtable
,
482 &br_sslrec_out_gcm_vtable
);
484 br_ssl_engine_set_aes_cbc(&cc
->eng
,
485 &br_aes_ct_cbcenc_vtable
,
486 &br_aes_ct_cbcdec_vtable
);
487 br_ssl_engine_set_aes_ctr(&cc
->eng
,
488 &br_aes_ct_ctr_vtable
);
489 /* Alternate: aes_ct64
490 br_ssl_engine_set_aes_cbc(&cc->eng,
491 &br_aes_ct64_cbcenc_vtable,
492 &br_aes_ct64_cbcdec_vtable);
493 br_ssl_engine_set_aes_ctr(&cc->eng,
494 &br_aes_ct64_ctr_vtable);
496 /* Alternate: aes_small
497 br_ssl_engine_set_aes_cbc(&cc->eng,
498 &br_aes_small_cbcenc_vtable,
499 &br_aes_small_cbcdec_vtable);
500 br_ssl_engine_set_aes_ctr(&cc->eng,
501 &br_aes_small_ctr_vtable);
503 /* Alternate: aes_big
504 br_ssl_engine_set_aes_cbc(&cc->eng,
505 &br_aes_big_cbcenc_vtable,
506 &br_aes_big_cbcdec_vtable);
507 br_ssl_engine_set_aes_ctr(&cc->eng,
508 &br_aes_big_ctr_vtable);
510 br_ssl_engine_set_des_cbc(&cc
->eng
,
511 &br_des_ct_cbcenc_vtable
,
512 &br_des_ct_cbcdec_vtable
);
513 /* Alternate: des_tab
514 br_ssl_engine_set_des_cbc(&cc->eng,
515 &br_des_tab_cbcenc_vtable,
516 &br_des_tab_cbcdec_vtable);
519 br_ssl_engine_set_ghash(&cc
->eng
,
521 /* Alternate: ghash_ctmul32
522 br_ssl_engine_set_ghash(&cc->eng,
525 /* Alternate: ghash_ctmul64
526 br_ssl_engine_set_ghash(&cc->eng,