net/cert/internal/parse_certificate.h

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef NET_CERT_INTERNAL_PARSE_CERTIFICATE_H_
   6 #define NET_CERT_INTERNAL_PARSE_CERTIFICATE_H_
   7
   8 #include "base/basictypes.h"
   9 #include "base/compiler_specific.h"
  10 #include "net/base/net_export.h"
  11 #include "net/der/input.h"
  12 #include "net/der/parse_values.h"
  13
  14 namespace net {
  15
  16 struct ParsedCertificate;
  17 struct ParsedTbsCertificate;
  18
  19 // Parses a DER-encoded "Certificate" as specified by RFC 5280. Returns true on
  20 // success and sets the results in |out|.
  21 //
  22 // Note that on success |out| aliases data from the input |certificate_tlv|.
  23 // Hence the fields of the ParsedCertificate are only valid as long as
  24 // |certificate_tlv| remains valid.
  25 //
  26 // On failure |out| has an undefined state. Some of its fields may have been
  27 // updated during parsing, whereas others may not have been changed.
  28 //
  29 // Refer to the per-field documention of the ParsedCertificate structure for
  30 // details on what validity checks parsing performs.
  31 //
  32 //       Certificate  ::=  SEQUENCE  {
  33 //            tbsCertificate       TBSCertificate,
  34 //            signatureAlgorithm   AlgorithmIdentifier,
  35 //            signatureValue       BIT STRING  }
  36 NET_EXPORT bool ParseCertificate(const der::Input& certificate_tlv,
  37                                  ParsedCertificate* out) WARN_UNUSED_RESULT;
  38
  39 // Parses a DER-encoded "TBSCertificate" as specified by RFC 5280. Returns true
  40 // on success and sets the results in |out|.
  41 //
  42 // Note that on success |out| aliases data from the input |tbs_tlv|.
  43 // Hence the fields of the ParsedTbsCertificate are only valid as long as
  44 // |tbs_tlv| remains valid.
  45 //
  46 // On failure |out| has an undefined state. Some of its fields may have been
  47 // updated during parsing, whereas others may not have been changed.
  48 //
  49 // Refer to the per-field documentation of ParsedTbsCertificate for details on
  50 // what validity checks parsing performs.
  51 //
  52 //       TBSCertificate  ::=  SEQUENCE  {
  53 //            version         [0]  EXPLICIT Version DEFAULT v1,
  54 //            serialNumber         CertificateSerialNumber,
  55 //            signature            AlgorithmIdentifier,
  56 //            issuer               Name,
  57 //            validity             Validity,
  58 //            subject              Name,
  59 //            subjectPublicKeyInfo SubjectPublicKeyInfo,
  60 //            issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
  61 //                                 -- If present, version MUST be v2 or v3
  62 //            subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
  63 //                                 -- If present, version MUST be v2 or v3
  64 //            extensions      [3]  EXPLICIT Extensions OPTIONAL
  65 //                                 -- If present, version MUST be v3
  66 //            }
  67 NET_EXPORT bool ParseTbsCertificate(const der::Input& tbs_tlv,
  68                                     ParsedTbsCertificate* out)
  69     WARN_UNUSED_RESULT;
  70
  71 // Represents a "Version" from RFC 5280:
  72 //         Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
  73 enum class CertificateVersion {
  74   V1,
  75   V2,
  76   V3,
  77 };
  78
  79 // ParsedCertificate contains pointers to the main fields of a DER-encoded RFC
  80 // 5280 "Certificate".
  81 //
  82 // ParsedCertificate is expected to be filled by ParseCertificate(), so
  83 // subsequent field descriptions are in terms of what ParseCertificate() sets.
  84 struct NET_EXPORT ParsedCertificate {
  85   // Corresponds with "tbsCertificate" from RFC 5280:
  86   //         tbsCertificate       TBSCertificate,
  87   //
  88   // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
  89   // guarantees are made regarding the value of this SEQUENCE.
  90   //
  91   // This can be further parsed using ParseTbsCertificate().
  92   der::Input tbs_certificate_tlv;
  93
  94   // Corresponds with "signatureAlgorithm" from RFC 5280:
  95   //         signatureAlgorithm   AlgorithmIdentifier,
  96   //
  97   // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
  98   // guarantees are made regarding the value of this SEQUENCE.
  99   //
 100   // This can be further parsed using SignatureValue::CreateFromDer().
 101   der::Input signature_algorithm_tlv;
 102
 103   // Corresponds with "signatureValue" from RFC 5280:
 104   //         signatureValue       BIT STRING  }
 105   //
 106   // Parsing guarantees that this is a valid BIT STRING.
 107   der::BitString signature_value;
 108 };
 109
 110 // ParsedTbsCertificate contains pointers to the main fields of a DER-encoded
 111 // RFC 5280 "TBSCertificate".
 112 //
 113 // ParsedTbsCertificate is expected to be filled by ParseTbsCertificate(), so
 114 // subsequent field descriptions are in terms of what ParseTbsCertificate()
 115 // sets.
 116 struct NET_EXPORT ParsedTbsCertificate {
 117   ParsedTbsCertificate();
 118   ~ParsedTbsCertificate();
 119
 120   // Corresponds with "version" from RFC 5280:
 121   //         version         [0]  EXPLICIT Version DEFAULT v1,
 122   //
 123   // Parsing guarantees that the version is one of v1, v2, or v3.
 124   CertificateVersion version = CertificateVersion::V1;
 125
 126   // Corresponds with "serialNumber" from RFC 5280:
 127   //         serialNumber         CertificateSerialNumber,
 128   //
 129   // This field specifically contains the content bytes of the INTEGER. So for
 130   // instance if the serial number was 1000 then this would contain bytes
 131   // {0x03, 0xE8}.
 132   //
 133   // In addition to being a valid DER-encoded INTEGER, parsing guarantees that
 134   // the serial number is at most 20 bytes long. Parsing does NOT guarantee
 135   // that the integer is positive (might be zero or negative).
 136   der::Input serial_number;
 137
 138   // Corresponds with "signatureAlgorithm" from RFC 5280:
 139   //         signatureAlgorithm   AlgorithmIdentifier,
 140   //
 141   // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
 142   // guarantees are made regarding the value of this SEQUENCE.
 143   //
 144   // This can be further parsed using SignatureValue::CreateFromDer().
 145   der::Input signature_algorithm_tlv;
 146
 147   // Corresponds with "issuer" from RFC 5280:
 148   //         issuer               Name,
 149   //
 150   // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
 151   // guarantees are made regarding the value of this SEQUENCE.
 152   der::Input issuer_tlv;
 153
 154   // Corresponds with "validity" from RFC 5280:
 155   //         validity             Validity,
 156   //
 157   // Where Validity is defined as:
 158   //
 159   //   Validity ::= SEQUENCE {
 160   //        notBefore      Time,
 161   //        notAfter       Time }
 162   //
 163   // Parsing guarantees that notBefore (validity_not_before) and notAfter
 164   // (validity_not_after) are valid DER-encoded dates, however it DOES NOT
 165   // gurantee anything about their values. For instance notAfter could be
 166   // before notBefore, or the dates could indicate an expired certificate.
 167   // Consumers are responsible for testing expiration.
 168   der::GeneralizedTime validity_not_before;
 169   der::GeneralizedTime validity_not_after;
 170
 171   // Corresponds with "subject" from RFC 5280:
 172   //         subject              Name,
 173   //
 174   // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
 175   // guarantees are made regarding the value of this SEQUENCE.
 176   der::Input subject_tlv;
 177
 178   // Corresponds with "subjectPublicKeyInfo" from RFC 5280:
 179   //         subjectPublicKeyInfo SubjectPublicKeyInfo,
 180   //
 181   // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
 182   // guarantees are made regarding the value of this SEQUENCE.
 183   der::Input spki_tlv;
 184
 185   // Corresponds with "issuerUniqueID" from RFC 5280:
 186   //         issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
 187   //                              -- If present, version MUST be v2 or v3
 188   //
 189   // Parsing guarantees that if issuer_unique_id is present it is a valid BIT
 190   // STRING, and that the version is either v2 or v3
 191   bool has_issuer_unique_id = false;
 192   der::BitString issuer_unique_id;
 193
 194   // Corresponds with "subjectUniqueID" from RFC 5280:
 195   //         subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
 196   //                              -- If present, version MUST be v2 or v3
 197   //
 198   // Parsing guarantees that if subject_unique_id is present it is a valid BIT
 199   // STRING, and that the version is either v2 or v3
 200   bool has_subject_unique_id = false;
 201   der::BitString subject_unique_id;
 202
 203   // Corresponds with "extensions" from RFC 5280:
 204   //         extensions      [3]  EXPLICIT Extensions OPTIONAL
 205   //                              -- If present, version MUST be v3
 206   //
 207   //
 208   // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
 209   // guarantees are made regarding the value of this SEQUENCE. (Note that the
 210   // EXPLICIT outer tag is stripped.)
 211   //
 212   // Parsing guarantees that if extensions is present the version is v3.
 213   bool has_extensions = false;
 214   der::Input extensions_tlv;
 215 };
 216
 217 }  // namespace net
 218
 219 #endif  // NET_CERT_INTERNAL_PARSE_CERTIFICATE_H_