qemu/roms/ipxe/src/include/ipxe/x509.h

   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 );
  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 /** An X.509 serial number */
  20 struct x509_serial {
  21         /** Raw serial number */
  22         struct asn1_cursor raw;
  23 };
  24
  25 /** An X.509 issuer */
  26 struct x509_issuer {
  27         /** Raw issuer */
  28         struct asn1_cursor raw;
  29 };
  30
  31 /** An X.509 time */
  32 struct x509_time {
  33         /** Seconds since the Epoch */
  34         time_t time;
  35 };
  36
  37 /** An X.509 certificate validity period */
  38 struct x509_validity {
  39         /** Not valid before */
  40         struct x509_time not_before;
  41         /** Not valid after */
  42         struct x509_time not_after;
  43 };
  44
  45 /** An X.509 certificate public key */
  46 struct x509_public_key {
  47         /** Raw public key information */
  48         struct asn1_cursor raw;
  49         /** Public key algorithm */
  50         struct asn1_algorithm *algorithm;
  51         /** Raw public key bit string */
  52         struct asn1_bit_string raw_bits;
  53 };
  54
  55 /** An X.509 certificate subject */
  56 struct x509_subject {
  57         /** Raw subject */
  58         struct asn1_cursor raw;
  59         /** Common name */
  60         struct asn1_cursor common_name;
  61         /** Public key information */
  62         struct x509_public_key public_key;
  63 };
  64
  65 /** An X.509 certificate signature */
  66 struct x509_signature {
  67         /** Signature algorithm */
  68         struct asn1_algorithm *algorithm;
  69         /** Signature value */
  70         struct asn1_bit_string value;
  71 };
  72
  73 /** An X.509 certificate basic constraints set */
  74 struct x509_basic_constraints {
  75         /** Subject is a CA */
  76         int ca;
  77         /** Path length */
  78         unsigned int path_len;
  79 };
  80
  81 /** Unlimited path length
  82  *
  83  * We use -2U, since this quantity represents one *fewer* than the
  84  * maximum number of remaining certificates in a chain.
  85  */
  86 #define X509_PATH_LEN_UNLIMITED -2U
  87
  88 /** An X.509 certificate key usage */
  89 struct x509_key_usage {
  90         /** Key usage extension is present */
  91         int present;
  92         /** Usage bits */
  93         unsigned int bits;
  94 };
  95
  96 /** X.509 certificate key usage bits */
  97 enum x509_key_usage_bits {
  98         X509_DIGITAL_SIGNATURE = 0x0080,
  99         X509_NON_REPUDIATION = 0x0040,
 100         X509_KEY_ENCIPHERMENT = 0x0020,
 101         X509_DATA_ENCIPHERMENT = 0x0010,
 102         X509_KEY_AGREEMENT = 0x0008,
 103         X509_KEY_CERT_SIGN = 0x0004,
 104         X509_CRL_SIGN = 0x0002,
 105         X509_ENCIPHER_ONLY = 0x0001,
 106         X509_DECIPHER_ONLY = 0x8000,
 107 };
 108
 109 /** An X.509 certificate extended key usage */
 110 struct x509_extended_key_usage {
 111         /** Usage bits */
 112         unsigned int bits;
 113 };
 114
 115 /** X.509 certificate extended key usage bits
 116  *
 117  * Extended key usages are identified by OID; these bits are purely an
 118  * internal definition.
 119  */
 120 enum x509_extended_key_usage_bits {
 121         X509_CODE_SIGNING = 0x0001,
 122         X509_OCSP_SIGNING = 0x0002,
 123 };
 124
 125 /** X.509 certificate OCSP responder */
 126 struct x509_ocsp_responder {
 127         /** URI */
 128         struct asn1_cursor uri;
 129         /** OCSP status is good */
 130         int good;
 131 };
 132
 133 /** X.509 certificate authority information access */
 134 struct x509_authority_info_access {
 135         /** OCSP responder */
 136         struct x509_ocsp_responder ocsp;
 137 };
 138
 139 /** X.509 certificate subject alternative name */
 140 struct x509_subject_alt_name {
 141         /** Names */
 142         struct asn1_cursor names;
 143 };
 144
 145 /** X.509 certificate general name types */
 146 enum x509_general_name_types {
 147         X509_GENERAL_NAME_DNS = ASN1_IMPLICIT_TAG ( 2 ),
 148         X509_GENERAL_NAME_URI = ASN1_IMPLICIT_TAG ( 6 ),
 149         X509_GENERAL_NAME_IP = ASN1_IMPLICIT_TAG ( 7 ),
 150 };
 151
 152 /** An X.509 certificate extensions set */
 153 struct x509_extensions {
 154         /** Basic constraints */
 155         struct x509_basic_constraints basic;
 156         /** Key usage */
 157         struct x509_key_usage usage;
 158         /** Extended key usage */
 159         struct x509_extended_key_usage ext_usage;
 160         /** Authority information access */
 161         struct x509_authority_info_access auth_info;
 162         /** Subject alternative name */
 163         struct x509_subject_alt_name alt_name;
 164 };
 165
 166 /** A link in an X.509 certificate chain */
 167 struct x509_link {
 168         /** List of links */
 169         struct list_head list;
 170         /** Certificate */
 171         struct x509_certificate *cert;
 172 };
 173
 174 /** An X.509 certificate chain */
 175 struct x509_chain {
 176         /** Reference count */
 177         struct refcnt refcnt;
 178         /** List of links */
 179         struct list_head links;
 180 };
 181
 182 /** An X.509 certificate */
 183 struct x509_certificate {
 184         /** Reference count */
 185         struct refcnt refcnt;
 186
 187         /** Link in certificate store */
 188         struct x509_link store;
 189
 190         /** Certificate has been validated */
 191         int valid;
 192         /** Maximum number of subsequent certificates in chain */
 193         unsigned int path_remaining;
 194
 195         /** Raw certificate */
 196         struct asn1_cursor raw;
 197         /** Version */
 198         unsigned int version;
 199         /** Serial number */
 200         struct x509_serial serial;
 201         /** Raw tbsCertificate */
 202         struct asn1_cursor tbs;
 203         /** Signature algorithm */
 204         struct asn1_algorithm *signature_algorithm;
 205         /** Issuer */
 206         struct x509_issuer issuer;
 207         /** Validity */
 208         struct x509_validity validity;
 209         /** Subject */
 210         struct x509_subject subject;
 211         /** Signature */
 212         struct x509_signature signature;
 213         /** Extensions */
 214         struct x509_extensions extensions;
 215 };
 216
 217 /**
 218  * Get reference to X.509 certificate
 219  *
 220  * @v cert              X.509 certificate
 221  * @ret cert            X.509 certificate
 222  */
 223 static inline __attribute__ (( always_inline )) struct x509_certificate *
 224 x509_get ( struct x509_certificate *cert ) {
 225         ref_get ( &cert->refcnt );
 226         return cert;
 227 }
 228
 229 /**
 230  * Drop reference to X.509 certificate
 231  *
 232  * @v cert              X.509 certificate
 233  */
 234 static inline __attribute__ (( always_inline )) void
 235 x509_put ( struct x509_certificate *cert ) {
 236         ref_put ( &cert->refcnt );
 237 }
 238
 239 /**
 240  * Get reference to X.509 certificate chain
 241  *
 242  * @v chain             X.509 certificate chain
 243  * @ret chain           X.509 certificate chain
 244  */
 245 static inline __attribute__ (( always_inline )) struct x509_chain *
 246 x509_chain_get ( struct x509_chain *chain ) {
 247         ref_get ( &chain->refcnt );
 248         return chain;
 249 }
 250
 251 /**
 252  * Drop reference to X.509 certificate chain
 253  *
 254  * @v chain             X.509 certificate chain
 255  */
 256 static inline __attribute__ (( always_inline )) void
 257 x509_chain_put ( struct x509_chain *chain ) {
 258         ref_put ( &chain->refcnt );
 259 }
 260
 261 /**
 262  * Get first certificate in X.509 certificate chain
 263  *
 264  * @v chain             X.509 certificate chain
 265  * @ret cert            X.509 certificate, or NULL
 266  */
 267 static inline __attribute__ (( always_inline )) struct x509_certificate *
 268 x509_first ( struct x509_chain *chain ) {
 269         struct x509_link *link;
 270
 271         link = list_first_entry ( &chain->links, struct x509_link, list );
 272         return ( link ? link->cert : NULL );
 273 }
 274
 275 /**
 276  * Get last certificate in X.509 certificate chain
 277  *
 278  * @v chain             X.509 certificate chain
 279  * @ret cert            X.509 certificate, or NULL
 280  */
 281 static inline __attribute__ (( always_inline )) struct x509_certificate *
 282 x509_last ( struct x509_chain *chain ) {
 283         struct x509_link *link;
 284
 285         link = list_last_entry ( &chain->links, struct x509_link, list );
 286         return ( link ? link->cert : NULL );
 287 }
 288
 289 /** An X.509 extension */
 290 struct x509_extension {
 291         /** Name */
 292         const char *name;
 293         /** Object identifier */
 294         struct asn1_cursor oid;
 295         /** Parse extension
 296          *
 297          * @v cert              X.509 certificate
 298          * @v raw               ASN.1 cursor
 299          * @ret rc              Return status code
 300          */
 301         int ( * parse ) ( struct x509_certificate *cert,
 302                           const struct asn1_cursor *raw );
 303 };
 304
 305 /** An X.509 key purpose */
 306 struct x509_key_purpose {
 307         /** Name */
 308         const char *name;
 309         /** Object identifier */
 310         struct asn1_cursor oid;
 311         /** Extended key usage bits */
 312         unsigned int bits;
 313 };
 314
 315 /** An X.509 access method */
 316 struct x509_access_method {
 317         /** Name */
 318         const char *name;
 319         /** Object identifier */
 320         struct asn1_cursor oid;
 321         /** Parse access method
 322          *
 323          * @v cert              X.509 certificate
 324          * @v raw               ASN.1 cursor
 325          * @ret rc              Return status code
 326          */
 327         int ( * parse ) ( struct x509_certificate *cert,
 328                           const struct asn1_cursor *raw );
 329 };
 330
 331 /** An X.509 root certificate store */
 332 struct x509_root {
 333         /** Fingerprint digest algorithm */
 334         struct digest_algorithm *digest;
 335         /** Number of certificates */
 336         unsigned int count;
 337         /** Certificate fingerprints */
 338         const void *fingerprints;
 339 };
 340
 341 extern const char * x509_name ( struct x509_certificate *cert );
 342 extern int x509_parse ( struct x509_certificate *cert,
 343                         const struct asn1_cursor *raw );
 344 extern int x509_certificate ( const void *data, size_t len,
 345                               struct x509_certificate **cert );
 346 extern int x509_validate ( struct x509_certificate *cert,
 347                            struct x509_certificate *issuer,
 348                            time_t time, struct x509_root *root );
 349 extern int x509_check_name ( struct x509_certificate *cert, const char *name );
 350
 351 extern struct x509_chain * x509_alloc_chain ( void );
 352 extern int x509_append ( struct x509_chain *chain,
 353                          struct x509_certificate *cert );
 354 extern int x509_append_raw ( struct x509_chain *chain, const void *data,
 355                              size_t len );
 356 extern int x509_auto_append ( struct x509_chain *chain,
 357                               struct x509_chain *certs );
 358 extern int x509_validate_chain ( struct x509_chain *chain, time_t time,
 359                                  struct x509_chain *store,
 360                                  struct x509_root *root );
 361
 362 /* Functions exposed only for unit testing */
 363 extern int x509_check_issuer ( struct x509_certificate *cert,
 364                                struct x509_certificate *issuer );
 365 extern void x509_fingerprint ( struct x509_certificate *cert,
 366                                struct digest_algorithm *digest,
 367                                void *fingerprint );
 368 extern int x509_check_root ( struct x509_certificate *cert,
 369                              struct x509_root *root );
 370 extern int x509_check_time ( struct x509_certificate *cert, time_t time );
 371
 372 /**
 373  * Invalidate X.509 certificate
 374  *
 375  * @v cert              X.509 certificate
 376  */
 377 static inline void x509_invalidate ( struct x509_certificate *cert ) {
 378         cert->valid = 0;
 379         cert->path_remaining = 0;
 380 }
 381
 382 /**
 383  * Invalidate X.509 certificate chain
 384  *
 385  * @v chain             X.509 certificate chain
 386  */
 387 static inline void x509_invalidate_chain ( struct x509_chain *chain ) {
 388         struct x509_link *link;
 389
 390         list_for_each_entry ( link, &chain->links, list )
 391                 x509_invalidate ( link->cert );
 392 }
 393
 394 #endif /* _IPXE_X509_H */