Added macro that indicates presence of the time callback feature. Also added C++...
[BearSSL] / inc / bearssl_x509.h
1 /*
2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
3 *
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:
11 *
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
14 *
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
22 * SOFTWARE.
23 */
24
25 #ifndef BR_BEARSSL_X509_H__
26 #define BR_BEARSSL_X509_H__
27
28 #include <stddef.h>
29 #include <stdint.h>
30
31 #include "bearssl_ec.h"
32 #include "bearssl_hash.h"
33 #include "bearssl_rsa.h"
34
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38
39 /** \file bearssl_x509.h
40 *
41 * # X.509 Certificate Chain Processing
42 *
43 * An X.509 processing engine receives an X.509 chain, chunk by chunk,
44 * as received from a SSL/TLS client or server (the client receives the
45 * server's certificate chain, and the server receives the client's
46 * certificate chain if it requested a client certificate). The chain
47 * is thus injected in the engine in SSL order (end-entity first).
48 *
49 * The engine's job is to return the public key to use for SSL/TLS.
50 * How exactly that key is obtained and verified is entirely up to the
51 * engine.
52 *
53 * **The "known key" engine** returns a public key which is already known
54 * from out-of-band information (e.g. the client _remembers_ the key from
55 * a previous connection, as in the usual SSH model). This is the simplest
56 * engine since it simply ignores the chain, thereby avoiding the need
57 * for any decoding logic.
58 *
59 * **The "minimal" engine** implements minimal X.509 decoding and chain
60 * validation:
61 *
62 * - The provided chain should validate "as is". There is no attempt
63 * at reordering, skipping or downloading extra certificates.
64 *
65 * - X.509 v1, v2 and v3 certificates are supported.
66 *
67 * - Trust anchors are a DN and a public key. Each anchor is either a
68 * "CA" anchor, or a non-CA.
69 *
70 * - If the end-entity certificate matches a non-CA anchor (subject DN
71 * is equal to the non-CA name, and public key is also identical to
72 * the anchor key), then this is a _direct trust_ case and the
73 * remaining certificates are ignored.
74 *
75 * - Unless direct trust is applied, the chain must be verifiable up to
76 * a certificate whose issuer DN matches the DN from a "CA" trust anchor,
77 * and whose signature is verifiable against that anchor's public key.
78 * Subsequent certificates in the chain are ignored.
79 *
80 * - The engine verifies subject/issuer DN matching, and enforces
81 * processing of Basic Constraints and Key Usage extensions. The
82 * Authority Key Identifier, Subject Key Identifier, Issuer Alt Name,
83 * Subject Directory Attribute, CRL Distribution Points, Freshest CRL,
84 * Authority Info Access and Subject Info Access extensions are
85 * ignored. The Subject Alt Name is decoded for the end-entity
86 * certificate under some conditions (see below). Other extensions
87 * are ignored if non-critical, or imply chain rejection if critical.
88 *
89 * - The Subject Alt Name extension is parsed for names of type `dNSName`
90 * when decoding the end-entity certificate, and only if there is a
91 * server name to match. If there is no SAN extension, then the
92 * Common Name from the subjectDN is used. That name matching is
93 * case-insensitive and honours a single starting wildcard (i.e. if
94 * the name in the certificate starts with "`*.`" then this matches
95 * any word as first element). Note: this name matching is performed
96 * also in the "direct trust" model.
97 *
98 * - DN matching is byte-to-byte equality (a future version might
99 * include some limited processing for case-insensitive matching and
100 * whitespace normalisation).
101 *
102 * - Successful validation produces a public key type but also a set
103 * of allowed usages (`BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`).
104 * The caller is responsible for checking that the key type and
105 * usages are compatible with the expected values (e.g. with the
106 * selected cipher suite, when the client validates the server's
107 * certificate).
108 *
109 * **Important caveats:**
110 *
111 * - The "minimal" engine does not check revocation status. The relevant
112 * extensions are ignored, and CRL or OCSP responses are not gathered
113 * or checked.
114 *
115 * - The "minimal" engine does not currently support Name Constraints
116 * (some basic functionality to handle sub-domains may be added in a
117 * later version).
118 *
119 * - The decoder is not "validating" in the sense that it won't reject
120 * some certificates with invalid field values when these fields are
121 * not actually processed.
122 */
123
124 /*
125 * X.509 error codes are in the 32..63 range.
126 */
127
128 /** \brief X.509 status: validation was successful; this is not actually
129 an error. */
130 #define BR_ERR_X509_OK 32
131
132 /** \brief X.509 status: invalid value in an ASN.1 structure. */
133 #define BR_ERR_X509_INVALID_VALUE 33
134
135 /** \brief X.509 status: truncated certificate. */
136 #define BR_ERR_X509_TRUNCATED 34
137
138 /** \brief X.509 status: empty certificate chain (no certificate at all). */
139 #define BR_ERR_X509_EMPTY_CHAIN 35
140
141 /** \brief X.509 status: decoding error: inner element extends beyond
142 outer element size. */
143 #define BR_ERR_X509_INNER_TRUNC 36
144
145 /** \brief X.509 status: decoding error: unsupported tag class (application
146 or private). */
147 #define BR_ERR_X509_BAD_TAG_CLASS 37
148
149 /** \brief X.509 status: decoding error: unsupported tag value. */
150 #define BR_ERR_X509_BAD_TAG_VALUE 38
151
152 /** \brief X.509 status: decoding error: indefinite length. */
153 #define BR_ERR_X509_INDEFINITE_LENGTH 39
154
155 /** \brief X.509 status: decoding error: extraneous element. */
156 #define BR_ERR_X509_EXTRA_ELEMENT 40
157
158 /** \brief X.509 status: decoding error: unexpected element. */
159 #define BR_ERR_X509_UNEXPECTED 41
160
161 /** \brief X.509 status: decoding error: expected constructed element, but
162 is primitive. */
163 #define BR_ERR_X509_NOT_CONSTRUCTED 42
164
165 /** \brief X.509 status: decoding error: expected primitive element, but
166 is constructed. */
167 #define BR_ERR_X509_NOT_PRIMITIVE 43
168
169 /** \brief X.509 status: decoding error: BIT STRING length is not multiple
170 of 8. */
171 #define BR_ERR_X509_PARTIAL_BYTE 44
172
173 /** \brief X.509 status: decoding error: BOOLEAN value has invalid length. */
174 #define BR_ERR_X509_BAD_BOOLEAN 45
175
176 /** \brief X.509 status: decoding error: value is off-limits. */
177 #define BR_ERR_X509_OVERFLOW 46
178
179 /** \brief X.509 status: invalid distinguished name. */
180 #define BR_ERR_X509_BAD_DN 47
181
182 /** \brief X.509 status: invalid date/time representation. */
183 #define BR_ERR_X509_BAD_TIME 48
184
185 /** \brief X.509 status: certificate contains unsupported features that
186 cannot be ignored. */
187 #define BR_ERR_X509_UNSUPPORTED 49
188
189 /** \brief X.509 status: key or signature size exceeds internal limits. */
190 #define BR_ERR_X509_LIMIT_EXCEEDED 50
191
192 /** \brief X.509 status: key type does not match that which was expected. */
193 #define BR_ERR_X509_WRONG_KEY_TYPE 51
194
195 /** \brief X.509 status: signature is invalid. */
196 #define BR_ERR_X509_BAD_SIGNATURE 52
197
198 /** \brief X.509 status: validation time is unknown. */
199 #define BR_ERR_X509_TIME_UNKNOWN 53
200
201 /** \brief X.509 status: certificate is expired or not yet valid. */
202 #define BR_ERR_X509_EXPIRED 54
203
204 /** \brief X.509 status: issuer/subject DN mismatch in the chain. */
205 #define BR_ERR_X509_DN_MISMATCH 55
206
207 /** \brief X.509 status: expected server name was not found in the chain. */
208 #define BR_ERR_X509_BAD_SERVER_NAME 56
209
210 /** \brief X.509 status: unknown critical extension in certificate. */
211 #define BR_ERR_X509_CRITICAL_EXTENSION 57
212
213 /** \brief X.509 status: not a CA, or path length constraint violation */
214 #define BR_ERR_X509_NOT_CA 58
215
216 /** \brief X.509 status: Key Usage extension prohibits intended usage. */
217 #define BR_ERR_X509_FORBIDDEN_KEY_USAGE 59
218
219 /** \brief X.509 status: public key found in certificate is too small. */
220 #define BR_ERR_X509_WEAK_PUBLIC_KEY 60
221
222 /** \brief X.509 status: chain could not be linked to a trust anchor. */
223 #define BR_ERR_X509_NOT_TRUSTED 62
224
225 /**
226 * \brief Aggregate structure for public keys.
227 */
228 typedef struct {
229 /** \brief Key type: `BR_KEYTYPE_RSA` or `BR_KEYTYPE_EC` */
230 unsigned char key_type;
231 /** \brief Actual public key. */
232 union {
233 /** \brief RSA public key. */
234 br_rsa_public_key rsa;
235 /** \brief EC public key. */
236 br_ec_public_key ec;
237 } key;
238 } br_x509_pkey;
239
240 /**
241 * \brief Distinguished Name (X.500) structure.
242 *
243 * The DN is DER-encoded.
244 */
245 typedef struct {
246 /** \brief Encoded DN data. */
247 unsigned char *data;
248 /** \brief Encoded DN length (in bytes). */
249 size_t len;
250 } br_x500_name;
251
252 /**
253 * \brief Trust anchor structure.
254 */
255 typedef struct {
256 /** \brief Encoded DN (X.500 name). */
257 br_x500_name dn;
258 /** \brief Anchor flags (e.g. `BR_X509_TA_CA`). */
259 unsigned flags;
260 /** \brief Anchor public key. */
261 br_x509_pkey pkey;
262 } br_x509_trust_anchor;
263
264 /**
265 * \brief Trust anchor flag: CA.
266 *
267 * A "CA" anchor is deemed fit to verify signatures on certificates.
268 * A "non-CA" anchor is accepted only for direct trust (server's
269 * certificate name and key match the anchor).
270 */
271 #define BR_X509_TA_CA 0x0001
272
273 /*
274 * Key type: combination of a basic key type (low 4 bits) and some
275 * optional flags.
276 *
277 * For a public key, the basic key type only is set.
278 *
279 * For an expected key type, the flags indicate the intended purpose(s)
280 * for the key; the basic key type may be set to 0 to indicate that any
281 * key type compatible with the indicated purpose is acceptable.
282 */
283 /** \brief Key type: algorithm is RSA. */
284 #define BR_KEYTYPE_RSA 1
285 /** \brief Key type: algorithm is EC. */
286 #define BR_KEYTYPE_EC 2
287
288 /**
289 * \brief Key type: usage is "key exchange".
290 *
291 * This value is combined (with bitwise OR) with the algorithm
292 * (`BR_KEYTYPE_RSA` or `BR_KEYTYPE_EC`) when informing the X.509
293 * validation engine that it should find a public key of that type,
294 * fit for key exchanges (e.g. `TLS_RSA_*` and `TLS_ECDH_*` cipher
295 * suites).
296 */
297 #define BR_KEYTYPE_KEYX 0x10
298
299 /**
300 * \brief Key type: usage is "signature".
301 *
302 * This value is combined (with bitwise OR) with the algorithm
303 * (`BR_KEYTYPE_RSA` or `BR_KEYTYPE_EC`) when informing the X.509
304 * validation engine that it should find a public key of that type,
305 * fit for signatures (e.g. `TLS_ECDHE_*` cipher suites).
306 */
307 #define BR_KEYTYPE_SIGN 0x20
308
309 /*
310 * start_chain Called when a new chain is started. If 'server_name'
311 * is not NULL and non-empty, then it is a name that
312 * should be looked for in the EE certificate (in the
313 * SAN extension as dNSName, or in the subjectDN's CN
314 * if there is no SAN extension).
315 * The caller ensures that the provided 'server_name'
316 * pointer remains valid throughout validation.
317 *
318 * start_cert Begins a new certificate in the chain. The provided
319 * length is in bytes; this is the total certificate length.
320 *
321 * append Get some additional bytes for the current certificate.
322 *
323 * end_cert Ends the current certificate.
324 *
325 * end_chain Called at the end of the chain. Returned value is
326 * 0 on success, or a non-zero error code.
327 *
328 * get_pkey Returns the EE certificate public key.
329 *
330 * For a complete chain, start_chain() and end_chain() are always
331 * called. For each certificate, start_cert(), some append() calls, then
332 * end_cert() are called, in that order. There may be no append() call
333 * at all if the certificate is empty (which is not valid but may happen
334 * if the peer sends exactly that).
335 *
336 * get_pkey() shall return a pointer to a structure that is valid as
337 * long as a new chain is not started. This may be a sub-structure
338 * within the context for the engine. This function MAY return a valid
339 * pointer to a public key even in some cases of validation failure,
340 * depending on the validation engine.
341 */
342
343 /**
344 * \brief Class type for an X.509 engine.
345 *
346 * A certificate chain validation uses a caller-allocated context, which
347 * contains the running state for that validation. Methods are called
348 * in due order:
349 *
350 * - `start_chain()` is called at the start of the validation.
351 * - Certificates are processed one by one, in SSL order (end-entity
352 * comes first). For each certificate, the following methods are
353 * called:
354 *
355 * - `start_cert()` at the beginning of the certificate.
356 * - `append()` is called zero, one or more times, to provide
357 * the certificate (possibly in chunks).
358 * - `end_cert()` at the end of the certificate.
359 *
360 * - `end_chain()` is called when the last certificate in the chain
361 * was processed.
362 * - `get_pkey()` is called after chain processing, if the chain
363 * validation was successful.
364 *
365 * A context structure may be reused; the `start_chain()` method shall
366 * ensure (re)initialisation.
367 */
368 typedef struct br_x509_class_ br_x509_class;
369 struct br_x509_class_ {
370 /**
371 * \brief X.509 context size, in bytes.
372 */
373 size_t context_size;
374
375 /**
376 * \brief Start a new chain.
377 *
378 * This method shall set the vtable (first field) of the context
379 * structure.
380 *
381 * The `server_name`, if not `NULL`, will be considered as a
382 * fully qualified domain name, to be matched against the `dNSName`
383 * elements of the end-entity certificate's SAN extension (if there
384 * is no SAN, then the Common Name from the subjectDN will be used).
385 * If `server_name` is `NULL` then no such matching is performed.
386 *
387 * \param ctx validation context.
388 * \param server_name server name to match (or `NULL`).
389 */
390 void (*start_chain)(const br_x509_class **ctx,
391 const char *server_name);
392
393 /**
394 * \brief Start a new certificate.
395 *
396 * \param ctx validation context.
397 * \param length new certificate length (in bytes).
398 */
399 void (*start_cert)(const br_x509_class **ctx, uint32_t length);
400
401 /**
402 * \brief Receive some bytes for the current certificate.
403 *
404 * This function may be called several times in succession for
405 * a given certificate. The caller guarantees that for each
406 * call, `len` is not zero, and the sum of all chunk lengths
407 * for a certificate matches the total certificate length which
408 * was provided in the previous `start_cert()` call.
409 *
410 * If the new certificate is empty (no byte at all) then this
411 * function won't be called at all.
412 *
413 * \param ctx validation context.
414 * \param buf certificate data chunk.
415 * \param len certificate data chunk length (in bytes).
416 */
417 void (*append)(const br_x509_class **ctx,
418 const unsigned char *buf, size_t len);
419
420 /**
421 * \brief Finish the current certificate.
422 *
423 * This function is called when the end of the current certificate
424 * is reached.
425 *
426 * \param ctx validation context.
427 */
428 void (*end_cert)(const br_x509_class **ctx);
429
430 /**
431 * \brief Finish the chain.
432 *
433 * This function is called at the end of the chain. It shall
434 * return either 0 if the validation was successful, or a
435 * non-zero error code. The `BR_ERR_X509_*` constants are
436 * error codes, though other values may be possible.
437 *
438 * \param ctx validation context.
439 * \return 0 on success, or a non-zero error code.
440 */
441 unsigned (*end_chain)(const br_x509_class **ctx);
442
443 /**
444 * \brief Get the resulting end-entity public key.
445 *
446 * The decoded public key is returned. The returned pointer
447 * may be valid only as long as the context structure is
448 * unmodified, i.e. it may cease to be valid if the context
449 * is released or reused.
450 *
451 * This function _may_ return `NULL` if the validation failed.
452 * However, returning a public key does not mean that the
453 * validation was wholly successful; some engines may return
454 * a decoded public key even if the chain did not end on a
455 * trusted anchor.
456 *
457 * If validation succeeded and `usage` is not `NULL`, then
458 * `*usage` is filled with a combination of `BR_KEYTYPE_SIGN`
459 * and/or `BR_KEYTYPE_KEYX` that specifies the validated key
460 * usage types. It is the caller's responsibility to check
461 * that value against the intended use of the public key.
462 *
463 * \param ctx validation context.
464 * \return the end-entity public key, or `NULL`.
465 */
466 const br_x509_pkey *(*get_pkey)(
467 const br_x509_class *const *ctx, unsigned *usages);
468 };
469
470 /**
471 * \brief The "known key" X.509 engine structure.
472 *
473 * The structure contents are opaque (they shall not be accessed directly),
474 * except for the first field (the vtable).
475 *
476 * The "known key" engine returns an externally configured public key,
477 * and totally ignores the certificate contents.
478 */
479 typedef struct {
480 /** \brief Reference to the context vtable. */
481 const br_x509_class *vtable;
482 #ifndef BR_DOXYGEN_IGNORE
483 br_x509_pkey pkey;
484 unsigned usages;
485 #endif
486 } br_x509_knownkey_context;
487
488 /**
489 * \brief Class instance for the "known key" X.509 engine.
490 */
491 extern const br_x509_class br_x509_knownkey_vtable;
492
493 /**
494 * \brief Initialize a "known key" X.509 engine with a known RSA public key.
495 *
496 * The `usages` parameter indicates the allowed key usages for that key
497 * (`BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`).
498 *
499 * The provided pointers are linked in, not copied, so they must remain
500 * valid while the public key may be in usage.
501 *
502 * \param ctx context to initialise.
503 * \param pk known public key.
504 * \param usages allowed key usages.
505 */
506 void br_x509_knownkey_init_rsa(br_x509_knownkey_context *ctx,
507 const br_rsa_public_key *pk, unsigned usages);
508
509 /**
510 * \brief Initialize a "known key" X.509 engine with a known EC public key.
511 *
512 * The `usages` parameter indicates the allowed key usages for that key
513 * (`BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`).
514 *
515 * The provided pointers are linked in, not copied, so they must remain
516 * valid while the public key may be in usage.
517 *
518 * \param ctx context to initialise.
519 * \param pk known public key.
520 * \param usages allowed key usages.
521 */
522 void br_x509_knownkey_init_ec(br_x509_knownkey_context *ctx,
523 const br_ec_public_key *pk, unsigned usages);
524
525 #ifndef BR_DOXYGEN_IGNORE
526 /*
527 * The minimal X.509 engine has some state buffers which must be large
528 * enough to simultaneously accommodate:
529 * -- the public key extracted from the current certificate;
530 * -- the signature on the current certificate or on the previous
531 * certificate;
532 * -- the public key extracted from the EE certificate.
533 *
534 * We store public key elements in their raw unsigned big-endian
535 * encoding. We want to support up to RSA-4096 with a short (up to 64
536 * bits) public exponent, thus a buffer for a public key must have
537 * length at least 520 bytes. Similarly, a RSA-4096 signature has length
538 * 512 bytes.
539 *
540 * Though RSA public exponents can formally be as large as the modulus
541 * (mathematically, even larger exponents would work, but PKCS#1 forbids
542 * them), exponents that do not fit on 32 bits are extremely rare,
543 * notably because some widespread implementations (e.g. Microsoft's
544 * CryptoAPI) don't support them. Moreover, large public exponent do not
545 * seem to imply any tangible security benefit, and they increase the
546 * cost of public key operations. The X.509 "minimal" engine will tolerate
547 * public exponents of arbitrary size as long as the modulus and the
548 * exponent can fit together in the dedicated buffer.
549 *
550 * EC public keys are shorter than RSA public keys; even with curve
551 * NIST P-521 (the largest curve we care to support), a public key is
552 * encoded over 133 bytes only.
553 */
554 #define BR_X509_BUFSIZE_KEY 520
555 #define BR_X509_BUFSIZE_SIG 512
556 #endif
557
558 /**
559 * \brief Type for receiving a name element.
560 *
561 * An array of such structures can be provided to the X.509 decoding
562 * engines. If the specified elements are found in the certificate
563 * subject DN or the SAN extension, then the name contents are copied
564 * as zero-terminated strings into the buffer.
565 *
566 * The decoder converts TeletexString and BMPString to UTF8String, and
567 * ensures that the resulting string is zero-terminated. If the string
568 * does not fit in the provided buffer, then the copy is aborted and an
569 * error is reported.
570 */
571 typedef struct {
572 /**
573 * \brief Element OID.
574 *
575 * For X.500 name elements (to be extracted from the subject DN),
576 * this is the encoded OID for the requested name element; the
577 * first byte shall contain the length of the DER-encoded OID
578 * value, followed by the OID value (for instance, OID 2.5.4.3,
579 * for id-at-commonName, will be `03 55 04 03`). This is
580 * equivalent to full DER encoding with the length but without
581 * the tag.
582 *
583 * For SAN name elements, the first byte (`oid[0]`) has value 0,
584 * followed by another byte that matches the expected GeneralName
585 * tag. Allowed second byte values are then:
586 *
587 * - 1: `rfc822Name`
588 *
589 * - 2: `dNSName`
590 *
591 * - 6: `uniformResourceIdentifier`
592 *
593 * - 0: `otherName`
594 *
595 * If first and second byte are 0, then this is a SAN element of
596 * type `otherName`; the `oid[]` array should then contain, right
597 * after the two bytes of value 0, an encoded OID (with the same
598 * conventions as for X.500 name elements). If a match is found
599 * for that OID, then the corresponding name element will be
600 * extracted, as long as it is a supported string type.
601 */
602 const unsigned char *oid;
603
604 /**
605 * \brief Destination buffer.
606 */
607 char *buf;
608
609 /**
610 * \brief Length (in bytes) of the destination buffer.
611 *
612 * The buffer MUST NOT be smaller than 1 byte.
613 */
614 size_t len;
615
616 /**
617 * \brief Decoding status.
618 *
619 * Status is 0 if the name element was not found, 1 if it was
620 * found and decoded, or -1 on error. Error conditions include
621 * an unrecognised encoding, an invalid encoding, or a string
622 * too large for the destination buffer.
623 */
624 int status;
625
626 } br_name_element;
627
628 /**
629 * \brief The "minimal" X.509 engine structure.
630 *
631 * The structure contents are opaque (they shall not be accessed directly),
632 * except for the first field (the vtable).
633 *
634 * The "minimal" engine performs a rudimentary but serviceable X.509 path
635 * validation.
636 */
637 typedef struct {
638 const br_x509_class *vtable;
639
640 #ifndef BR_DOXYGEN_IGNORE
641 /* Structure for returning the EE public key. */
642 br_x509_pkey pkey;
643
644 /* CPU for the T0 virtual machine. */
645 struct {
646 uint32_t *dp;
647 uint32_t *rp;
648 const unsigned char *ip;
649 } cpu;
650 uint32_t dp_stack[32];
651 uint32_t rp_stack[32];
652 int err;
653
654 /* Server name to match with the SAN / CN of the EE certificate. */
655 const char *server_name;
656
657 /* Validated key usages. */
658 unsigned char key_usages;
659
660 /* Explicitly set date and time. */
661 uint32_t days, seconds;
662
663 /* Current certificate length (in bytes). Set to 0 when the
664 certificate has been fully processed. */
665 uint32_t cert_length;
666
667 /* Number of certificates processed so far in the current chain.
668 It is incremented at the end of the processing of a certificate,
669 so it is 0 for the EE. */
670 uint32_t num_certs;
671
672 /* Certificate data chunk. */
673 const unsigned char *hbuf;
674 size_t hlen;
675
676 /* The pad serves as destination for various operations. */
677 unsigned char pad[256];
678
679 /* Buffer for EE public key data. */
680 unsigned char ee_pkey_data[BR_X509_BUFSIZE_KEY];
681
682 /* Buffer for currently decoded public key. */
683 unsigned char pkey_data[BR_X509_BUFSIZE_KEY];
684
685 /* Signature type: signer key type, offset to the hash
686 function OID (in the T0 data block) and hash function
687 output length (TBS hash length). */
688 unsigned char cert_signer_key_type;
689 uint16_t cert_sig_hash_oid;
690 unsigned char cert_sig_hash_len;
691
692 /* Current/last certificate signature. */
693 unsigned char cert_sig[BR_X509_BUFSIZE_SIG];
694 uint16_t cert_sig_len;
695
696 /* Minimum RSA key length (difference in bytes from 128). */
697 int16_t min_rsa_size;
698
699 /* Configured trust anchors. */
700 const br_x509_trust_anchor *trust_anchors;
701 size_t trust_anchors_num;
702
703 /*
704 * Multi-hasher for the TBS.
705 */
706 unsigned char do_mhash;
707 br_multihash_context mhash;
708 unsigned char tbs_hash[64];
709
710 /*
711 * Simple hasher for the subject/issuer DN.
712 */
713 unsigned char do_dn_hash;
714 const br_hash_class *dn_hash_impl;
715 br_hash_compat_context dn_hash;
716 unsigned char current_dn_hash[64];
717 unsigned char next_dn_hash[64];
718 unsigned char saved_dn_hash[64];
719
720 /*
721 * Name elements to gather.
722 */
723 br_name_element *name_elts;
724 size_t num_name_elts;
725
726 /*
727 * Public key cryptography implementations (signature verification).
728 */
729 br_rsa_pkcs1_vrfy irsa;
730 br_ecdsa_vrfy iecdsa;
731 const br_ec_impl *iec;
732 #endif
733
734 } br_x509_minimal_context;
735
736 /**
737 * \brief Class instance for the "minimal" X.509 engine.
738 */
739 extern const br_x509_class br_x509_minimal_vtable;
740
741 /**
742 * \brief Initialise a "minimal" X.509 engine.
743 *
744 * The `dn_hash_impl` parameter shall be a hash function internally used
745 * to match X.500 names (subject/issuer DN, and anchor names). Any standard
746 * hash function may be used, but a collision-resistant hash function is
747 * advised.
748 *
749 * After initialization, some implementations for signature verification
750 * (hash functions and signature algorithms) MUST be added.
751 *
752 * \param ctx context to initialise.
753 * \param dn_hash_impl hash function for DN comparisons.
754 * \param trust_anchors trust anchors.
755 * \param trust_anchors_num number of trust anchors.
756 */
757 void br_x509_minimal_init(br_x509_minimal_context *ctx,
758 const br_hash_class *dn_hash_impl,
759 const br_x509_trust_anchor *trust_anchors, size_t trust_anchors_num);
760
761 /**
762 * \brief Set a supported hash function in an X.509 "minimal" engine.
763 *
764 * Hash functions are used with signature verification algorithms.
765 * Once initialised (with `br_x509_minimal_init()`), the context must
766 * be configured with the hash functions it shall support for that
767 * purpose. The hash function identifier MUST be one of the standard
768 * hash function identifiers (1 to 6, for MD5, SHA-1, SHA-224, SHA-256,
769 * SHA-384 and SHA-512).
770 *
771 * If `impl` is `NULL`, this _removes_ support for the designated
772 * hash function.
773 *
774 * \param ctx validation context.
775 * \param id hash function identifier (from 1 to 6).
776 * \param impl hash function implementation (or `NULL`).
777 */
778 static inline void
779 br_x509_minimal_set_hash(br_x509_minimal_context *ctx,
780 int id, const br_hash_class *impl)
781 {
782 br_multihash_setimpl(&ctx->mhash, id, impl);
783 }
784
785 /**
786 * \brief Set a RSA signature verification implementation in the X.509
787 * "minimal" engine.
788 *
789 * Once initialised (with `br_x509_minimal_init()`), the context must
790 * be configured with the signature verification implementations that
791 * it is supposed to support. If `irsa` is `0`, then the RSA support
792 * is disabled.
793 *
794 * \param ctx validation context.
795 * \param irsa RSA signature verification implementation (or `0`).
796 */
797 static inline void
798 br_x509_minimal_set_rsa(br_x509_minimal_context *ctx,
799 br_rsa_pkcs1_vrfy irsa)
800 {
801 ctx->irsa = irsa;
802 }
803
804 /**
805 * \brief Set a ECDSA signature verification implementation in the X.509
806 * "minimal" engine.
807 *
808 * Once initialised (with `br_x509_minimal_init()`), the context must
809 * be configured with the signature verification implementations that
810 * it is supposed to support.
811 *
812 * If `iecdsa` is `0`, then this call disables ECDSA support; in that
813 * case, `iec` may be `NULL`. Otherwise, `iecdsa` MUST point to a function
814 * that verifies ECDSA signatures with format "asn1", and it will use
815 * `iec` as underlying elliptic curve support.
816 *
817 * \param ctx validation context.
818 * \param iec elliptic curve implementation (or `NULL`).
819 * \param iecdsa ECDSA implementation (or `0`).
820 */
821 static inline void
822 br_x509_minimal_set_ecdsa(br_x509_minimal_context *ctx,
823 const br_ec_impl *iec, br_ecdsa_vrfy iecdsa)
824 {
825 ctx->iecdsa = iecdsa;
826 ctx->iec = iec;
827 }
828
829 /**
830 * \brief Initialise a "minimal" X.509 engine with default algorithms.
831 *
832 * This function performs the same job as `br_x509_minimal_init()`, but
833 * also sets implementations for RSA, ECDSA, and the standard hash
834 * functions.
835 *
836 * \param ctx context to initialise.
837 * \param trust_anchors trust anchors.
838 * \param trust_anchors_num number of trust anchors.
839 */
840 void br_x509_minimal_init_full(br_x509_minimal_context *ctx,
841 const br_x509_trust_anchor *trust_anchors, size_t trust_anchors_num);
842
843 /**
844 * \brief Set the validation time for the X.509 "minimal" engine.
845 *
846 * The validation time is set as two 32-bit integers, for days and
847 * seconds since a fixed epoch:
848 *
849 * - Days are counted in a proleptic Gregorian calendar since
850 * January 1st, 0 AD. Year "0 AD" is the one that preceded "1 AD";
851 * it is also traditionally known as "1 BC".
852 *
853 * - Seconds are counted since midnight, from 0 to 86400 (a count of
854 * 86400 is possible only if a leap second happened).
855 *
856 * The validation date and time is understood in the UTC time zone.
857 *
858 * If the validation date and time are not explicitly set, but BearSSL
859 * was compiled with support for the system clock on the underlying
860 * platform, then the current time will automatically be used. Otherwise,
861 * not setting the validation date and time implies a validation
862 * failure (except in case of direct trust of the EE key).
863 *
864 * \param ctx validation context.
865 * \param days days since January 1st, 0 AD (Gregorian calendar).
866 * \param seconds seconds since midnight (0 to 86400).
867 */
868 static inline void
869 br_x509_minimal_set_time(br_x509_minimal_context *ctx,
870 uint32_t days, uint32_t seconds)
871 {
872 ctx->days = days;
873 ctx->seconds = seconds;
874 }
875
876 /**
877 * \brief Set the minimal acceptable length for RSA keys (X.509 "minimal"
878 * engine).
879 *
880 * The RSA key length is expressed in bytes. The default minimum key
881 * length is 128 bytes, corresponding to 1017 bits. RSA keys shorter
882 * than the configured length will be rejected, implying validation
883 * failure. This setting applies to keys extracted from certificates
884 * (both end-entity, and intermediate CA) but not to "CA" trust anchors.
885 *
886 * \param ctx validation context.
887 * \param byte_length minimum RSA key length, **in bytes** (not bits).
888 */
889 static inline void
890 br_x509_minimal_set_minrsa(br_x509_minimal_context *ctx, int byte_length)
891 {
892 ctx->min_rsa_size = (int16_t)(byte_length - 128);
893 }
894
895 /**
896 * \brief Set the name elements to gather.
897 *
898 * The provided array is linked in the context. The elements are
899 * gathered from the EE certificate. If the same element type is
900 * requested several times, then the relevant structures will be filled
901 * in the order the matching values are encountered in the certificate.
902 *
903 * \param ctx validation context.
904 * \param elts array of name element structures to fill.
905 * \param num_elts number of name element structures to fill.
906 */
907 static inline void
908 br_x509_minimal_set_name_elements(br_x509_minimal_context *ctx,
909 br_name_element *elts, size_t num_elts)
910 {
911 ctx->name_elts = elts;
912 ctx->num_name_elts = num_elts;
913 }
914
915 /**
916 * \brief X.509 decoder context.
917 *
918 * This structure is _not_ for X.509 validation, but for extracting
919 * names and public keys from encoded certificates. Intended usage is
920 * to use (self-signed) certificates as trust anchors.
921 *
922 * Contents are opaque and shall not be accessed directly.
923 */
924 typedef struct {
925
926 #ifndef BR_DOXYGEN_IGNORE
927 /* Structure for returning the public key. */
928 br_x509_pkey pkey;
929
930 /* CPU for the T0 virtual machine. */
931 struct {
932 uint32_t *dp;
933 uint32_t *rp;
934 const unsigned char *ip;
935 } cpu;
936 uint32_t dp_stack[32];
937 uint32_t rp_stack[32];
938 int err;
939
940 /* The pad serves as destination for various operations. */
941 unsigned char pad[256];
942
943 /* Flag set when decoding succeeds. */
944 unsigned char decoded;
945
946 /* Validity dates. */
947 uint32_t notbefore_days, notbefore_seconds;
948 uint32_t notafter_days, notafter_seconds;
949
950 /* The "CA" flag. This is set to true if the certificate contains
951 a Basic Constraints extension that asserts CA status. */
952 unsigned char isCA;
953
954 /* DN processing: the subject DN is extracted and pushed to the
955 provided callback. */
956 unsigned char copy_dn;
957 void *append_dn_ctx;
958 void (*append_dn)(void *ctx, const void *buf, size_t len);
959
960 /* Certificate data chunk. */
961 const unsigned char *hbuf;
962 size_t hlen;
963
964 /* Buffer for decoded public key. */
965 unsigned char pkey_data[BR_X509_BUFSIZE_KEY];
966
967 /* Type of key and hash function used in the certificate signature. */
968 unsigned char signer_key_type;
969 unsigned char signer_hash_id;
970 #endif
971
972 } br_x509_decoder_context;
973
974 /**
975 * \brief Initialise an X.509 decoder context for processing a new
976 * certificate.
977 *
978 * The `append_dn()` callback (with opaque context `append_dn_ctx`)
979 * will be invoked to receive, chunk by chunk, the certificate's
980 * subject DN. If `append_dn` is `0` then the subject DN will be
981 * ignored.
982 *
983 * \param ctx X.509 decoder context to initialise.
984 * \param append_dn DN receiver callback (or `0`).
985 * \param append_dn_ctx context for the DN receiver callback.
986 */
987 void br_x509_decoder_init(br_x509_decoder_context *ctx,
988 void (*append_dn)(void *ctx, const void *buf, size_t len),
989 void *append_dn_ctx);
990
991 /**
992 * \brief Push some certificate bytes into a decoder context.
993 *
994 * If `len` is non-zero, then that many bytes are pushed, from address
995 * `data`, into the provided decoder context.
996 *
997 * \param ctx X.509 decoder context.
998 * \param data certificate data chunk.
999 * \param len certificate data chunk length (in bytes).
1000 */
1001 void br_x509_decoder_push(br_x509_decoder_context *ctx,
1002 const void *data, size_t len);
1003
1004 /**
1005 * \brief Obtain the decoded public key.
1006 *
1007 * Returned value is a pointer to a structure internal to the decoder
1008 * context; releasing or reusing the decoder context invalidates that
1009 * structure.
1010 *
1011 * If decoding was not finished, or failed, then `NULL` is returned.
1012 *
1013 * \param ctx X.509 decoder context.
1014 * \return the public key, or `NULL` on unfinished/error.
1015 */
1016 static inline br_x509_pkey *
1017 br_x509_decoder_get_pkey(br_x509_decoder_context *ctx)
1018 {
1019 if (ctx->decoded && ctx->err == 0) {
1020 return &ctx->pkey;
1021 } else {
1022 return NULL;
1023 }
1024 }
1025
1026 /**
1027 * \brief Get decoder error status.
1028 *
1029 * If no error was reported yet but the certificate decoding is not
1030 * finished, then the error code is `BR_ERR_X509_TRUNCATED`. If decoding
1031 * was successful, then 0 is returned.
1032 *
1033 * \param ctx X.509 decoder context.
1034 * \return 0 on successful decoding, or a non-zero error code.
1035 */
1036 static inline int
1037 br_x509_decoder_last_error(br_x509_decoder_context *ctx)
1038 {
1039 if (ctx->err != 0) {
1040 return ctx->err;
1041 }
1042 if (!ctx->decoded) {
1043 return BR_ERR_X509_TRUNCATED;
1044 }
1045 return 0;
1046 }
1047
1048 /**
1049 * \brief Get the "isCA" flag from an X.509 decoder context.
1050 *
1051 * This flag is set if the decoded certificate claims to be a CA through
1052 * a Basic Constraints extension. This flag should not be read before
1053 * decoding completed successfully.
1054 *
1055 * \param ctx X.509 decoder context.
1056 * \return the "isCA" flag.
1057 */
1058 static inline int
1059 br_x509_decoder_isCA(br_x509_decoder_context *ctx)
1060 {
1061 return ctx->isCA;
1062 }
1063
1064 /**
1065 * \brief Get the issuing CA key type (type of algorithm used to sign the
1066 * decoded certificate).
1067 *
1068 * This is `BR_KEYTYPE_RSA` or `BR_KEYTYPE_EC`. The value 0 is returned
1069 * if the signature type was not recognised.
1070 *
1071 * \param ctx X.509 decoder context.
1072 * \return the issuing CA key type.
1073 */
1074 static inline int
1075 br_x509_decoder_get_signer_key_type(br_x509_decoder_context *ctx)
1076 {
1077 return ctx->signer_key_type;
1078 }
1079
1080 /**
1081 * \brief Get the identifier for the hash function used to sign the decoded
1082 * certificate.
1083 *
1084 * This is 0 if the hash function was not recognised.
1085 *
1086 * \param ctx X.509 decoder context.
1087 * \return the signature hash function identifier.
1088 */
1089 static inline int
1090 br_x509_decoder_get_signer_hash_id(br_x509_decoder_context *ctx)
1091 {
1092 return ctx->signer_hash_id;
1093 }
1094
1095 /**
1096 * \brief Type for an X.509 certificate (DER-encoded).
1097 */
1098 typedef struct {
1099 /** \brief The DER-encoded certificate data. */
1100 unsigned char *data;
1101 /** \brief The DER-encoded certificate length (in bytes). */
1102 size_t data_len;
1103 } br_x509_certificate;
1104
1105 /**
1106 * \brief Private key decoder context.
1107 *
1108 * The private key decoder recognises RSA and EC private keys, either in
1109 * their raw, DER-encoded format, or wrapped in an unencrypted PKCS#8
1110 * archive (again DER-encoded).
1111 *
1112 * Structure contents are opaque and shall not be accessed directly.
1113 */
1114 typedef struct {
1115 #ifndef BR_DOXYGEN_IGNORE
1116 /* Structure for returning the private key. */
1117 union {
1118 br_rsa_private_key rsa;
1119 br_ec_private_key ec;
1120 } key;
1121
1122 /* CPU for the T0 virtual machine. */
1123 struct {
1124 uint32_t *dp;
1125 uint32_t *rp;
1126 const unsigned char *ip;
1127 } cpu;
1128 uint32_t dp_stack[32];
1129 uint32_t rp_stack[32];
1130 int err;
1131
1132 /* Private key data chunk. */
1133 const unsigned char *hbuf;
1134 size_t hlen;
1135
1136 /* The pad serves as destination for various operations. */
1137 unsigned char pad[256];
1138
1139 /* Decoded key type; 0 until decoding is complete. */
1140 unsigned char key_type;
1141
1142 /* Buffer for the private key elements. It shall be large enough
1143 to accommodate all elements for a RSA-4096 private key (roughly
1144 five 2048-bit integers, possibly a bit more). */
1145 unsigned char key_data[3 * BR_X509_BUFSIZE_SIG];
1146 #endif
1147 } br_skey_decoder_context;
1148
1149 /**
1150 * \brief Initialise a private key decoder context.
1151 *
1152 * \param ctx key decoder context to initialise.
1153 */
1154 void br_skey_decoder_init(br_skey_decoder_context *ctx);
1155
1156 /**
1157 * \brief Push some data bytes into a private key decoder context.
1158 *
1159 * If `len` is non-zero, then that many data bytes, starting at address
1160 * `data`, are pushed into the decoder.
1161 *
1162 * \param ctx key decoder context.
1163 * \param data private key data chunk.
1164 * \param len private key data chunk length (in bytes).
1165 */
1166 void br_skey_decoder_push(br_skey_decoder_context *ctx,
1167 const void *data, size_t len);
1168
1169 /**
1170 * \brief Get the decoding status for a private key.
1171 *
1172 * Decoding status is 0 on success, or a non-zero error code. If the
1173 * decoding is unfinished when this function is called, then the
1174 * status code `BR_ERR_X509_TRUNCATED` is returned.
1175 *
1176 * \param ctx key decoder context.
1177 * \return 0 on successful decoding, or a non-zero error code.
1178 */
1179 static inline int
1180 br_skey_decoder_last_error(const br_skey_decoder_context *ctx)
1181 {
1182 if (ctx->err != 0) {
1183 return ctx->err;
1184 }
1185 if (ctx->key_type == 0) {
1186 return BR_ERR_X509_TRUNCATED;
1187 }
1188 return 0;
1189 }
1190
1191 /**
1192 * \brief Get the decoded private key type.
1193 *
1194 * Private key type is `BR_KEYTYPE_RSA` or `BR_KEYTYPE_EC`. If decoding is
1195 * not finished or failed, then 0 is returned.
1196 *
1197 * \param ctx key decoder context.
1198 * \return decoded private key type, or 0.
1199 */
1200 static inline int
1201 br_skey_decoder_key_type(const br_skey_decoder_context *ctx)
1202 {
1203 if (ctx->err == 0) {
1204 return ctx->key_type;
1205 } else {
1206 return 0;
1207 }
1208 }
1209
1210 /**
1211 * \brief Get the decoded RSA private key.
1212 *
1213 * This function returns `NULL` if the decoding failed, or is not
1214 * finished, or the key is not RSA. The returned pointer references
1215 * structures within the context that can become invalid if the context
1216 * is reused or released.
1217 *
1218 * \param ctx key decoder context.
1219 * \return decoded RSA private key, or `NULL`.
1220 */
1221 static inline const br_rsa_private_key *
1222 br_skey_decoder_get_rsa(const br_skey_decoder_context *ctx)
1223 {
1224 if (ctx->err == 0 && ctx->key_type == BR_KEYTYPE_RSA) {
1225 return &ctx->key.rsa;
1226 } else {
1227 return NULL;
1228 }
1229 }
1230
1231 /**
1232 * \brief Get the decoded EC private key.
1233 *
1234 * This function returns `NULL` if the decoding failed, or is not
1235 * finished, or the key is not EC. The returned pointer references
1236 * structures within the context that can become invalid if the context
1237 * is reused or released.
1238 *
1239 * \param ctx key decoder context.
1240 * \return decoded EC private key, or `NULL`.
1241 */
1242 static inline const br_ec_private_key *
1243 br_skey_decoder_get_ec(const br_skey_decoder_context *ctx)
1244 {
1245 if (ctx->err == 0 && ctx->key_type == BR_KEYTYPE_EC) {
1246 return &ctx->key.ec;
1247 } else {
1248 return NULL;
1249 }
1250 }
1251
1252 /**
1253 * \brief Encode an RSA private key (raw DER format).
1254 *
1255 * This function encodes the provided key into the "raw" format specified
1256 * in PKCS#1 (RFC 8017, Appendix C, type `RSAPrivateKey`), with DER
1257 * encoding rules.
1258 *
1259 * The key elements are:
1260 *
1261 * - `sk`: the private key (`p`, `q`, `dp`, `dq` and `iq`)
1262 *
1263 * - `pk`: the public key (`n` and `e`)
1264 *
1265 * - `d` (size: `dlen` bytes): the private exponent
1266 *
1267 * The public key elements, and the private exponent `d`, can be
1268 * recomputed from the private key (see `br_rsa_compute_modulus()`,
1269 * `br_rsa_compute_pubexp()` and `br_rsa_compute_privexp()`).
1270 *
1271 * If `dest` is not `NULL`, then the encoded key is written at that
1272 * address, and the encoded length (in bytes) is returned. If `dest` is
1273 * `NULL`, then nothing is written, but the encoded length is still
1274 * computed and returned.
1275 *
1276 * \param dest the destination buffer (or `NULL`).
1277 * \param sk the RSA private key.
1278 * \param pk the RSA public key.
1279 * \param d the RSA private exponent.
1280 * \param dlen the RSA private exponent length (in bytes).
1281 * \return the encoded key length (in bytes).
1282 */
1283 size_t br_encode_rsa_raw_der(void *dest, const br_rsa_private_key *sk,
1284 const br_rsa_public_key *pk, const void *d, size_t dlen);
1285
1286 /**
1287 * \brief Encode an RSA private key (PKCS#8 DER format).
1288 *
1289 * This function encodes the provided key into the PKCS#8 format
1290 * (RFC 5958, type `OneAsymmetricKey`). It wraps around the "raw DER"
1291 * format for the RSA key, as implemented by `br_encode_rsa_raw_der()`.
1292 *
1293 * The key elements are:
1294 *
1295 * - `sk`: the private key (`p`, `q`, `dp`, `dq` and `iq`)
1296 *
1297 * - `pk`: the public key (`n` and `e`)
1298 *
1299 * - `d` (size: `dlen` bytes): the private exponent
1300 *
1301 * The public key elements, and the private exponent `d`, can be
1302 * recomputed from the private key (see `br_rsa_compute_modulus()`,
1303 * `br_rsa_compute_pubexp()` and `br_rsa_compute_privexp()`).
1304 *
1305 * If `dest` is not `NULL`, then the encoded key is written at that
1306 * address, and the encoded length (in bytes) is returned. If `dest` is
1307 * `NULL`, then nothing is written, but the encoded length is still
1308 * computed and returned.
1309 *
1310 * \param dest the destination buffer (or `NULL`).
1311 * \param sk the RSA private key.
1312 * \param pk the RSA public key.
1313 * \param d the RSA private exponent.
1314 * \param dlen the RSA private exponent length (in bytes).
1315 * \return the encoded key length (in bytes).
1316 */
1317 size_t br_encode_rsa_pkcs8_der(void *dest, const br_rsa_private_key *sk,
1318 const br_rsa_public_key *pk, const void *d, size_t dlen);
1319
1320 /**
1321 * \brief Encode an EC private key (raw DER format).
1322 *
1323 * This function encodes the provided key into the "raw" format specified
1324 * in RFC 5915 (type `ECPrivateKey`), with DER encoding rules.
1325 *
1326 * The private key is provided in `sk`, the public key being `pk`. If
1327 * `pk` is `NULL`, then the encoded key will not include the public key
1328 * in its `publicKey` field (which is nominally optional).
1329 *
1330 * If `dest` is not `NULL`, then the encoded key is written at that
1331 * address, and the encoded length (in bytes) is returned. If `dest` is
1332 * `NULL`, then nothing is written, but the encoded length is still
1333 * computed and returned.
1334 *
1335 * If the key cannot be encoded (e.g. because there is no known OBJECT
1336 * IDENTIFIER for the used curve), then 0 is returned.
1337 *
1338 * \param dest the destination buffer (or `NULL`).
1339 * \param sk the EC private key.
1340 * \param pk the EC public key (or `NULL`).
1341 * \return the encoded key length (in bytes), or 0.
1342 */
1343 size_t br_encode_ec_raw_der(void *dest,
1344 const br_ec_private_key *sk, const br_ec_public_key *pk);
1345
1346 /**
1347 * \brief Encode an EC private key (PKCS#8 DER format).
1348 *
1349 * This function encodes the provided key into the PKCS#8 format
1350 * (RFC 5958, type `OneAsymmetricKey`). The curve is identified
1351 * by an OID provided as parameters to the `privateKeyAlgorithm`
1352 * field. The private key value (contents of the `privateKey` field)
1353 * contains the DER encoding of the `ECPrivateKey` type defined in
1354 * RFC 5915, without the `parameters` field (since they would be
1355 * redundant with the information in `privateKeyAlgorithm`).
1356 *
1357 * The private key is provided in `sk`, the public key being `pk`. If
1358 * `pk` is not `NULL`, then the encoded public key is included in the
1359 * `publicKey` field of the private key value (but not in the `publicKey`
1360 * field of the PKCS#8 `OneAsymmetricKey` wrapper).
1361 *
1362 * If `dest` is not `NULL`, then the encoded key is written at that
1363 * address, and the encoded length (in bytes) is returned. If `dest` is
1364 * `NULL`, then nothing is written, but the encoded length is still
1365 * computed and returned.
1366 *
1367 * If the key cannot be encoded (e.g. because there is no known OBJECT
1368 * IDENTIFIER for the used curve), then 0 is returned.
1369 *
1370 * \param dest the destination buffer (or `NULL`).
1371 * \param sk the EC private key.
1372 * \param pk the EC public key (or `NULL`).
1373 * \return the encoded key length (in bytes), or 0.
1374 */
1375 size_t br_encode_ec_pkcs8_der(void *dest,
1376 const br_ec_private_key *sk, const br_ec_public_key *pk);
1377
1378 /**
1379 * \brief PEM banner for RSA private key (raw).
1380 */
1381 #define BR_ENCODE_PEM_RSA_RAW "RSA PRIVATE KEY"
1382
1383 /**
1384 * \brief PEM banner for EC private key (raw).
1385 */
1386 #define BR_ENCODE_PEM_EC_RAW "EC PRIVATE KEY"
1387
1388 /**
1389 * \brief PEM banner for an RSA or EC private key in PKCS#8 format.
1390 */
1391 #define BR_ENCODE_PEM_PKCS8 "PRIVATE KEY"
1392
1393 #ifdef __cplusplus
1394 }
1395 #endif
1396
1397 #endif