iPXE
x509.h
Go to the documentation of this file.
1 #ifndef _IPXE_X509_H
2 #define _IPXE_X509_H
3 
4 /** @file
5  *
6  * X.509 certificates
7  *
8  */
9 
10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
11 
12 #include <stdint.h>
13 #include <stddef.h>
14 #include <time.h>
15 #include <ipxe/asn1.h>
16 #include <ipxe/refcnt.h>
17 #include <ipxe/list.h>
18 
19 struct image;
20 
21 /** An X.509 serial number */
22 struct x509_serial {
23  /** Raw serial number */
24  struct asn1_cursor raw;
25 };
26 
27 /** An X.509 issuer */
28 struct x509_issuer {
29  /** Raw issuer */
30  struct asn1_cursor raw;
31 };
32 
33 /** An X.509 time */
34 struct x509_time {
35  /** Seconds since the Epoch */
37 };
38 
39 /** An X.509 certificate validity period */
40 struct x509_validity {
41  /** Not valid before */
43  /** Not valid after */
45 };
46 
47 /** An X.509 certificate public key */
49  /** Raw public key information */
50  struct asn1_cursor raw;
51  /** Public key algorithm */
53  /** Raw public key bit string */
55 };
56 
57 /** An X.509 certificate subject */
58 struct x509_subject {
59  /** Raw subject */
60  struct asn1_cursor raw;
61  /** Common name */
63  /** Public key information */
65 };
66 
67 /** An X.509 certificate signature */
69  /** Signature algorithm */
71  /** Signature value */
73 };
74 
75 /** An X.509 certificate basic constraints set */
77  /** Subject is a CA */
78  int ca;
79  /** Path length */
80  unsigned int path_len;
81 };
82 
83 /** Unlimited path length
84  *
85  * We use -2U, since this quantity represents one *fewer* than the
86  * maximum number of remaining certificates in a chain.
87  */
88 #define X509_PATH_LEN_UNLIMITED -2U
89 
90 /** An X.509 certificate key usage */
92  /** Key usage extension is present */
93  int present;
94  /** Usage bits */
95  unsigned int bits;
96 };
97 
98 /** X.509 certificate key usage bits */
106  X509_CRL_SIGN = 0x0002,
109 };
110 
111 /** An X.509 certificate extended key usage */
113  /** Usage bits */
114  unsigned int bits;
115 };
116 
117 /** X.509 certificate extended key usage bits
118  *
119  * Extended key usages are identified by OID; these bits are purely an
120  * internal definition.
121  */
125 };
126 
127 /** X.509 certificate OCSP responder */
129  /** URI */
130  struct asn1_cursor uri;
131  /** OCSP status is good */
132  int good;
133 };
134 
135 /** X.509 certificate authority information access */
137  /** OCSP responder */
139 };
140 
141 /** X.509 certificate subject alternative name */
143  /** Names */
145 };
146 
147 /** X.509 certificate general name types */
152 };
153 
154 /** An X.509 certificate extensions set */
156  /** Basic constraints */
158  /** Key usage */
160  /** Extended key usage */
162  /** Authority information access */
164  /** Subject alternative name */
166 };
167 
168 /** A link in an X.509 certificate chain */
169 struct x509_link {
170  /** List of links */
171  struct list_head list;
172  /** Certificate */
174 };
175 
176 /** An X.509 certificate chain */
177 struct x509_chain {
178  /** Reference count */
179  struct refcnt refcnt;
180  /** List of links */
181  struct list_head links;
182 };
183 
184 /** An X.509 certificate */
186  /** Reference count */
187  struct refcnt refcnt;
188 
189  /** Link in certificate store */
190  struct x509_link store;
191 
192  /** Flags */
193  unsigned int flags;
194  /** Root against which certificate has been validated (if any) */
195  struct x509_root *root;
196  /** Maximum number of subsequent certificates in chain */
197  unsigned int path_remaining;
198 
199  /** Raw certificate */
200  struct asn1_cursor raw;
201  /** Version */
202  unsigned int version;
203  /** Serial number */
205  /** Raw tbsCertificate */
206  struct asn1_cursor tbs;
207  /** Signature algorithm */
209  /** Issuer */
211  /** Validity */
213  /** Subject */
215  /** Signature */
217  /** Extensions */
219 };
220 
221 /** X.509 certificate flags */
223  /** Certificate was added at build time */
225  /** Certificate was added explicitly at run time */
227 };
228 
229 /**
230  * Get reference to X.509 certificate
231  *
232  * @v cert X.509 certificate
233  * @ret cert X.509 certificate
234  */
235 static inline __attribute__ (( always_inline )) struct x509_certificate *
236 x509_get ( struct x509_certificate *cert ) {
237  ref_get ( &cert->refcnt );
238  return cert;
239 }
240 
241 /**
242  * Drop reference to X.509 certificate
243  *
244  * @v cert X.509 certificate
245  */
246 static inline __attribute__ (( always_inline )) void
247 x509_put ( struct x509_certificate *cert ) {
248  ref_put ( &cert->refcnt );
249 }
250 
251 /**
252  * Get reference to X.509 certificate chain
253  *
254  * @v chain X.509 certificate chain
255  * @ret chain X.509 certificate chain
256  */
257 static inline __attribute__ (( always_inline )) struct x509_chain *
258 x509_chain_get ( struct x509_chain *chain ) {
259  ref_get ( &chain->refcnt );
260  return chain;
261 }
262 
263 /**
264  * Drop reference to X.509 certificate chain
265  *
266  * @v chain X.509 certificate chain
267  */
268 static inline __attribute__ (( always_inline )) void
269 x509_chain_put ( struct x509_chain *chain ) {
270  ref_put ( &chain->refcnt );
271 }
272 
273 /**
274  * Get first certificate in X.509 certificate chain
275  *
276  * @v chain X.509 certificate chain
277  * @ret cert X.509 certificate, or NULL
278  */
279 static inline __attribute__ (( always_inline )) struct x509_certificate *
280 x509_first ( struct x509_chain *chain ) {
281  struct x509_link *link;
282 
283  link = list_first_entry ( &chain->links, struct x509_link, list );
284  return ( link ? link->cert : NULL );
285 }
286 
287 /**
288  * Get last certificate in X.509 certificate chain
289  *
290  * @v chain X.509 certificate chain
291  * @ret cert X.509 certificate, or NULL
292  */
293 static inline __attribute__ (( always_inline )) struct x509_certificate *
294 x509_last ( struct x509_chain *chain ) {
295  struct x509_link *link;
296 
297  link = list_last_entry ( &chain->links, struct x509_link, list );
298  return ( link ? link->cert : NULL );
299 }
300 
301 /** An X.509 extension */
303  /** Name */
304  const char *name;
305  /** Object identifier */
306  struct asn1_cursor oid;
307  /** Parse extension
308  *
309  * @v cert X.509 certificate
310  * @v raw ASN.1 cursor
311  * @ret rc Return status code
312  */
313  int ( * parse ) ( struct x509_certificate *cert,
314  const struct asn1_cursor *raw );
315 };
316 
317 /** An X.509 key purpose */
319  /** Name */
320  const char *name;
321  /** Object identifier */
322  struct asn1_cursor oid;
323  /** Extended key usage bits */
324  unsigned int bits;
325 };
326 
327 /** An X.509 access method */
329  /** Name */
330  const char *name;
331  /** Object identifier */
332  struct asn1_cursor oid;
333  /** Parse access method
334  *
335  * @v cert X.509 certificate
336  * @v raw ASN.1 cursor
337  * @ret rc Return status code
338  */
339  int ( * parse ) ( struct x509_certificate *cert,
340  const struct asn1_cursor *raw );
341 };
342 
343 /** An X.509 root certificate list */
344 struct x509_root {
345  /** Reference count */
346  struct refcnt refcnt;
347  /** Fingerprint digest algorithm */
349  /** Number of certificates */
350  unsigned int count;
351  /** Certificate fingerprints */
352  const void *fingerprints;
353 };
354 
355 /**
356  * Get reference to X.509 root certificate list
357  *
358  * @v root X.509 root certificate list
359  * @ret root X.509 root certificate list
360  */
361 static inline __attribute__ (( always_inline )) struct x509_root *
363  ref_get ( &root->refcnt );
364  return root;
365 }
366 
367 /**
368  * Drop reference to X.509 root certificate list
369  *
370  * @v root X.509 root certificate list
371  */
372 static inline __attribute__ (( always_inline )) void
374  ref_put ( &root->refcnt );
375 }
376 
377 extern const char * x509_name ( struct x509_certificate *cert );
378 extern int x509_parse ( struct x509_certificate *cert,
379  const struct asn1_cursor *raw );
380 extern int x509_certificate ( const void *data, size_t len,
381  struct x509_certificate **cert );
382 extern int x509_is_valid ( struct x509_certificate *cert,
383  struct x509_root *root );
384 extern int x509_validate ( struct x509_certificate *cert,
385  struct x509_certificate *issuer,
386  time_t time, struct x509_root *root );
387 extern int x509_check_name ( struct x509_certificate *cert, const char *name );
388 
389 extern struct x509_chain * x509_alloc_chain ( void );
390 extern int x509_append ( struct x509_chain *chain,
391  struct x509_certificate *cert );
392 extern int x509_append_raw ( struct x509_chain *chain, const void *data,
393  size_t len );
394 extern int x509_auto_append ( struct x509_chain *chain,
395  struct x509_chain *certs );
396 extern int x509_validate_chain ( struct x509_chain *chain, time_t time,
397  struct x509_chain *store,
398  struct x509_root *root );
399 extern int image_x509 ( struct image *image, size_t offset,
400  struct x509_certificate **cert );
401 
402 /* Functions exposed only for unit testing */
403 extern int x509_check_issuer ( struct x509_certificate *cert,
404  struct x509_certificate *issuer );
405 extern void x509_fingerprint ( struct x509_certificate *cert,
406  struct digest_algorithm *digest,
407  void *fingerprint );
408 extern int x509_check_root ( struct x509_certificate *cert,
409  struct x509_root *root );
410 extern int x509_check_time ( struct x509_certificate *cert, time_t time );
411 
412 /**
413  * Invalidate X.509 certificate
414  *
415  * @v cert X.509 certificate
416  */
417 static inline void x509_invalidate ( struct x509_certificate *cert ) {
418  x509_root_put ( cert->root );
419  cert->root = NULL;
420  cert->path_remaining = 0;
421 }
422 
423 /**
424  * Invalidate X.509 certificate chain
425  *
426  * @v chain X.509 certificate chain
427  */
428 static inline void x509_invalidate_chain ( struct x509_chain *chain ) {
429  struct x509_link *link;
430 
431  list_for_each_entry ( link, &chain->links, list )
432  x509_invalidate ( link->cert );
433 }
434 
435 #endif /* _IPXE_X509_H */
x509_key_usage_bits
X.509 certificate key usage bits.
Definition: x509.h:99
static void x509_chain_put(struct x509_chain *chain)
Drop reference to X.509 certificate chain.
Definition: x509.h:269
const char * name
Name.
Definition: x509.h:330
#define __attribute__(x)
Definition: compiler.h:10
struct asn1_bit_string raw_bits
Raw public key bit string.
Definition: x509.h:54
int x509_validate(struct x509_certificate *cert, struct x509_certificate *issuer, time_t time, struct x509_root *root)
Validate X.509 certificate.
Definition: x509.c:1371
An ASN.1 OID-identified algorithm.
Definition: asn1.h:306
struct asn1_cursor raw
Raw public key information.
Definition: x509.h:50
const char * name
Definition: ath9k_hw.c:1984
struct x509_extended_key_usage ext_usage
Extended key usage.
Definition: x509.h:161
struct asn1_cursor raw
Raw issuer.
Definition: x509.h:30
unsigned int path_remaining
Maximum number of subsequent certificates in chain.
Definition: x509.h:197
static struct x509_chain * x509_chain_get(struct x509_chain *chain)
Get reference to X.509 certificate chain.
Definition: x509.h:258
x509_general_name_types
X.509 certificate general name types.
Definition: x509.h:148
struct asn1_cursor names
Names.
Definition: x509.h:144
#define ASN1_IMPLICIT_TAG(number)
ASN.1 implicit tag.
Definition: asn1.h:95
static struct x509_certificate * x509_get(struct x509_certificate *cert)
Get reference to X.509 certificate.
Definition: x509.h:236
unsigned int path_len
Path length.
Definition: x509.h:80
An X.509 certificate basic constraints set.
Definition: x509.h:76
struct refcnt refcnt
Reference count.
Definition: x509.h:187
x509_extended_key_usage_bits
X.509 certificate extended key usage bits.
Definition: x509.h:122
int good
OCSP status is good.
Definition: x509.h:132
struct stp_switch root
Root switch.
Definition: stp.h:26
unsigned int bits
Usage bits.
Definition: x509.h:114
int x509_check_root(struct x509_certificate *cert, struct x509_root *root)
Check X.509 root certificate.
Definition: x509.c:1260
struct list_head links
List of links.
Definition: x509.h:181
const char * x509_name(struct x509_certificate *cert)
Get X.509 certificate display name.
Definition: x509.c:145
struct x509_issuer issuer
Issuer.
Definition: x509.h:210
const char * name
Name.
Definition: x509.h:320
int x509_check_time(struct x509_certificate *cert, time_t time)
Check X.509 certificate validity period.
Definition: x509.c:1292
struct asn1_algorithm * signature_algorithm
Signature algorithm.
Definition: x509.h:208
struct asn1_cursor oid
Object identifier.
Definition: x509.h:306
static void x509_root_put(struct x509_root *root)
Drop reference to X.509 root certificate list.
Definition: x509.h:373
struct asn1_algorithm * algorithm
Signature algorithm.
Definition: x509.h:70
struct asn1_cursor raw
Raw serial number.
Definition: x509.h:24
struct asn1_cursor oid
Object identifier.
Definition: x509.h:322
An executable image.
Definition: image.h:24
void x509_fingerprint(struct x509_certificate *cert, struct digest_algorithm *digest, void *fingerprint)
Calculate X.509 certificate fingerprint.
Definition: x509.c:1242
time_t time
Seconds since the Epoch.
Definition: x509.h:36
int image_x509(struct image *image, size_t offset, struct x509_certificate **cert)
Extract X.509 certificate object from image.
Definition: x509.c:1831
#define list_last_entry(list, type, member)
Get the container of the last entry in a list.
Definition: list.h:346
struct md4_digest digest
Digest of data already processed.
Definition: md4.h:12
unsigned int flags
Flags.
Definition: x509.h:193
An X.509 key purpose.
Definition: x509.h:318
A doubly-linked list entry (or list head)
Definition: list.h:18
int present
Key usage extension is present.
Definition: x509.h:93
A reference counter.
Definition: refcnt.h:26
X.509 certificate OCSP responder.
Definition: x509.h:128
#define list_first_entry(list, type, member)
Get the container of the first entry in a list.
Definition: list.h:333
An X.509 certificate chain.
Definition: x509.h:177
int x509_check_name(struct x509_certificate *cert, const char *name)
Check X.509 certificate name.
Definition: x509.c:1569
int x509_check_issuer(struct x509_certificate *cert, struct x509_certificate *issuer)
Check X.509 certificate against issuer certificate.
Definition: x509.c:1182
struct x509_time not_before
Not valid before.
Definition: x509.h:42
struct x509_root * root
Root against which certificate has been validated (if any)
Definition: x509.h:195
ASN.1 encoding.
struct x509_signature signature
Signature.
Definition: x509.h:216
#define list_for_each_entry(pos, head, member)
Iterate over entries in a list.
Definition: list.h:420
struct x509_chain * x509_alloc_chain(void)
Allocate X.509 certificate chain.
Definition: x509.c:1627
struct digest_algorithm * digest
Fingerprint digest algorithm.
Definition: x509.h:348
static userptr_t size_t offset
Offset of the first segment within the content.
Definition: deflate.h:259
u32 link
Link to next descriptor.
Definition: ar9003_mac.h:68
int x509_is_valid(struct x509_certificate *cert, struct x509_root *root)
Check if X.509 certificate is valid.
Definition: x509.c:1318
static struct x509_root * x509_root_get(struct x509_root *root)
Get reference to X.509 root certificate list.
Definition: x509.h:362
An X.509 certificate public key.
Definition: x509.h:48
X.509 certificate authority information access.
Definition: x509.h:136
struct x509_authority_info_access auth_info
Authority information access.
Definition: x509.h:163
struct x509_public_key public_key
Public key information.
Definition: x509.h:64
Linked lists.
static struct x509_certificate * x509_last(struct x509_chain *chain)
Get last certificate in X.509 certificate chain.
Definition: x509.h:294
An X.509 certificate.
Definition: x509.h:185
struct x509_serial serial
Serial number.
Definition: x509.h:204
struct x509_subject subject
Subject.
Definition: x509.h:214
int ca
Subject is a CA.
Definition: x509.h:78
#define ref_get(refcnt)
Get additional reference to object.
Definition: refcnt.h:92
struct asn1_algorithm * algorithm
Public key algorithm.
Definition: x509.h:52
An X.509 issuer.
Definition: x509.h:28
struct asn1_bit_string value
Signature value.
Definition: x509.h:72
An X.509 certificate key usage.
Definition: x509.h:91
An X.509 certificate validity period.
Definition: x509.h:40
struct asn1_cursor raw
Raw subject.
Definition: x509.h:60
const char * name
Name.
Definition: x509.h:304
unsigned int bits
Extended key usage bits.
Definition: x509.h:324
int(* parse)(struct x509_certificate *cert, const struct asn1_cursor *raw)
Parse access method.
Definition: x509.h:339
Certificate was added at build time.
Definition: x509.h:224
An X.509 root certificate list.
Definition: x509.h:344
struct x509_validity validity
Validity.
Definition: x509.h:212
struct asn1_cursor common_name
Common name.
Definition: x509.h:62
int x509_parse(struct x509_certificate *cert, const struct asn1_cursor *raw)
Parse X.509 certificate from ASN.1 data.
Definition: x509.c:1003
struct x509_subject_alt_name alt_name
Subject alternative name.
Definition: x509.h:165
An X.509 serial number.
Definition: x509.h:22
uint32_t len
Length.
Definition: ena.h:14
An X.509 time.
Definition: x509.h:34
int x509_validate_chain(struct x509_chain *chain, time_t time, struct x509_chain *store, struct x509_root *root)
Validate X.509 certificate chain.
Definition: x509.c:1774
An X.509 certificate extended key usage.
Definition: x509.h:112
int x509_certificate(const void *data, size_t len, struct x509_certificate **cert)
Create X.509 certificate.
Definition: x509.c:1069
An X.509 certificate subject.
Definition: x509.h:58
unsigned int bits
Usage bits.
Definition: x509.h:95
unsigned int version
Version.
Definition: x509.h:202
static void x509_put(struct x509_certificate *cert)
Drop reference to X.509 certificate.
Definition: x509.h:247
static struct x509_certificate * x509_first(struct x509_chain *chain)
Get first certificate in X.509 certificate chain.
Definition: x509.h:280
unsigned int count
Number of certificates.
Definition: x509.h:350
struct asn1_cursor tbs
Raw tbsCertificate.
Definition: x509.h:206
A message digest algorithm.
Definition: crypto.h:17
Reference counting.
X.509 certificate subject alternative name.
Definition: x509.h:142
struct x509_link store
Link in certificate store.
Definition: x509.h:190
uint8_t data[48]
Additional event data.
Definition: ena.h:22
struct x509_time not_after
Not valid after.
Definition: x509.h:44
static void x509_invalidate_chain(struct x509_chain *chain)
Invalidate X.509 certificate chain.
Definition: x509.h:428
__be32 raw[7]
Definition: CIB_PRM.h:28
A Uniform Resource Identifier.
Definition: uri.h:64
struct asn1_cursor oid
Object identifier.
Definition: x509.h:332
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
const void * fingerprints
Certificate fingerprints.
Definition: x509.h:352
An X.509 certificate extensions set.
Definition: x509.h:155
struct asn1_cursor raw
Raw certificate.
Definition: x509.h:200
struct x509_key_usage usage
Key usage.
Definition: x509.h:159
int64_t time_t
Seconds since the Epoch.
Definition: time.h:18
Time source.
int(* parse)(struct x509_certificate *cert, const struct asn1_cursor *raw)
Parse extension.
Definition: x509.h:313
uint64_t time
Current time.
Definition: ntlm.h:20
int x509_append_raw(struct x509_chain *chain, const void *data, size_t len)
Append X.509 certificate to X.509 certificate chain.
Definition: x509.c:1675
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
struct x509_ocsp_responder ocsp
OCSP responder.
Definition: x509.h:138
Certificate was added explicitly at run time.
Definition: x509.h:226
An ASN.1 object cursor.
Definition: asn1.h:20
struct x509_basic_constraints basic
Basic constraints.
Definition: x509.h:157
struct refcnt refcnt
Reference count.
Definition: x509.h:179
int x509_append(struct x509_chain *chain, struct x509_certificate *cert)
Append X.509 certificate to X.509 certificate chain.
Definition: x509.c:1650
struct x509_extensions extensions
Extensions.
Definition: x509.h:218
int x509_auto_append(struct x509_chain *chain, struct x509_chain *certs)
Append X.509 certificates to X.509 certificate chain.
Definition: x509.c:1734
#define ref_put(refcnt)
Drop reference to object.
Definition: refcnt.h:106
x509_flags
X.509 certificate flags.
Definition: x509.h:222
static void x509_invalidate(struct x509_certificate *cert)
Invalidate X.509 certificate.
Definition: x509.h:417
An ASN.1 bit string.
Definition: asn1.h:347
An X.509 certificate signature.
Definition: x509.h:68
An X.509 extension.
Definition: x509.h:302
An X.509 access method.
Definition: x509.h:328