1 // Copyright 2015 The Chromium Authors
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 //     https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef BSSL_PKI_PARSE_CERTIFICATE_H_
16 #define BSSL_PKI_PARSE_CERTIFICATE_H_
17 
18 #include <stdint.h>
19 
20 #include <map>
21 #include <memory>
22 #include <optional>
23 #include <vector>
24 
25 #include <openssl/base.h>
26 
27 #include "general_names.h"
28 #include "input.h"
29 #include "parse_values.h"
30 
31 BSSL_NAMESPACE_BEGIN
32 
33 namespace der {
34 class Parser;
35 }
36 
37 class CertErrors;
38 struct ParsedTbsCertificate;
39 
40 // Returns true if the given serial number (CertificateSerialNumber in RFC 5280)
41 // is valid:
42 //
43 //    CertificateSerialNumber  ::=  INTEGER
44 //
45 // The input to this function is the (unverified) value octets of the INTEGER.
46 // This function will verify that:
47 //
48 //   * The octets are a valid DER-encoding of an INTEGER (for instance, minimal
49 //     encoding length).
50 //
51 //   * No more than 20 octets are used.
52 //
53 // Note that it DOES NOT reject non-positive values (zero or negative).
54 //
55 // For reference, here is what RFC 5280 section 4.1.2.2 says:
56 //
57 //     Given the uniqueness requirements above, serial numbers can be
58 //     expected to contain long integers.  Certificate users MUST be able to
59 //     handle serialNumber values up to 20 octets.  Conforming CAs MUST NOT
60 //     use serialNumber values longer than 20 octets.
61 //
62 //     Note: Non-conforming CAs may issue certificates with serial numbers
63 //     that are negative or zero.  Certificate users SHOULD be prepared to
64 //     gracefully handle such certificates.
65 //
66 // |errors| must be a non-null destination for any errors/warnings. If
67 // |warnings_only| is set to true, then what would ordinarily be errors are
68 // instead added as warnings.
69 [[nodiscard]] OPENSSL_EXPORT bool VerifySerialNumber(der::Input value,
70                                                      bool warnings_only,
71                                                      CertErrors *errors);
72 
73 // Consumes a "Time" value (as defined by RFC 5280) from |parser|. On success
74 // writes the result to |*out| and returns true. On failure no guarantees are
75 // made about the state of |parser|.
76 //
77 // From RFC 5280:
78 //
79 //     Time ::= CHOICE {
80 //          utcTime        UTCTime,
81 //          generalTime    GeneralizedTime }
82 [[nodiscard]] OPENSSL_EXPORT bool ReadUTCOrGeneralizedTime(
83     der::Parser *parser, der::GeneralizedTime *out);
84 
85 // Parses a DER-encoded "Validity" as specified by RFC 5280. Returns true on
86 // success and sets the results in |not_before| and |not_after|:
87 //
88 //       Validity ::= SEQUENCE {
89 //            notBefore      Time,
90 //            notAfter       Time }
91 //
92 // Note that upon success it is NOT guaranteed that |*not_before <= *not_after|.
93 [[nodiscard]] OPENSSL_EXPORT bool ParseValidity(
94     der::Input validity_tlv, der::GeneralizedTime *not_before,
95     der::GeneralizedTime *not_after);
96 
97 struct OPENSSL_EXPORT ParseCertificateOptions {
98   // If set to true, then parsing will skip checks on the certificate's serial
99   // number. The only requirement will be that the serial number is an INTEGER,
100   // however it is not required to be a valid DER-encoding (i.e. minimal
101   // encoding), nor is it required to be constrained to any particular length.
102   bool allow_invalid_serial_numbers = false;
103 };
104 
105 // Parses a DER-encoded "Certificate" as specified by RFC 5280. Returns true on
106 // success and sets the results in the |out_*| parameters. On both the failure
107 // and success case, if |out_errors| was non-null it may contain extra error
108 // information.
109 //
110 // Note that on success the out parameters alias data from the input
111 // |certificate_tlv|.  Hence the output values are only valid as long as
112 // |certificate_tlv| remains valid.
113 //
114 // On failure the out parameters have an undefined state, except for
115 // out_errors. Some of them may have been updated during parsing, whereas
116 // others may not have been changed.
117 //
118 // The out parameters represent each field of the Certificate SEQUENCE:
119 //       Certificate  ::=  SEQUENCE  {
120 //
121 // The |out_tbs_certificate_tlv| parameter corresponds with "tbsCertificate"
122 // from RFC 5280:
123 //         tbsCertificate       TBSCertificate,
124 //
125 // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
126 // guarantees are made regarding the value of this SEQUENCE.
127 // This can be further parsed using ParseTbsCertificate().
128 //
129 // The |out_signature_algorithm_tlv| parameter corresponds with
130 // "signatureAlgorithm" from RFC 5280:
131 //         signatureAlgorithm   AlgorithmIdentifier,
132 //
133 // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
134 // guarantees are made regarding the value of this SEQUENCE.
135 // This can be further parsed using SignatureValue::Create().
136 //
137 // The |out_signature_value| parameter corresponds with "signatureValue" from
138 // RFC 5280:
139 //         signatureValue       BIT STRING  }
140 //
141 // Parsing guarantees that this is a valid BIT STRING.
142 [[nodiscard]] OPENSSL_EXPORT bool ParseCertificate(
143     der::Input certificate_tlv, der::Input *out_tbs_certificate_tlv,
144     der::Input *out_signature_algorithm_tlv,
145     der::BitString *out_signature_value, CertErrors *out_errors);
146 
147 // Parses a DER-encoded "TBSCertificate" as specified by RFC 5280. Returns true
148 // on success and sets the results in |out|. Certain invalid inputs may
149 // be accepted based on the provided |options|.
150 //
151 // If |errors| was non-null then any warnings/errors that occur during parsing
152 // are added to it.
153 //
154 // Note that on success |out| aliases data from the input |tbs_tlv|.
155 // Hence the fields of the ParsedTbsCertificate are only valid as long as
156 // |tbs_tlv| remains valid.
157 //
158 // On failure |out| has an undefined state. Some of its fields may have been
159 // updated during parsing, whereas others may not have been changed.
160 //
161 // Refer to the per-field documentation of ParsedTbsCertificate for details on
162 // what validity checks parsing performs.
163 //
164 //       TBSCertificate  ::=  SEQUENCE  {
165 //            version         [0]  EXPLICIT Version DEFAULT v1,
166 //            serialNumber         CertificateSerialNumber,
167 //            signature            AlgorithmIdentifier,
168 //            issuer               Name,
169 //            validity             Validity,
170 //            subject              Name,
171 //            subjectPublicKeyInfo SubjectPublicKeyInfo,
172 //            issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
173 //                                 -- If present, version MUST be v2 or v3
174 //            subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
175 //                                 -- If present, version MUST be v2 or v3
176 //            extensions      [3]  EXPLICIT Extensions OPTIONAL
177 //                                 -- If present, version MUST be v3
178 //            }
179 [[nodiscard]] OPENSSL_EXPORT bool ParseTbsCertificate(
180     der::Input tbs_tlv, const ParseCertificateOptions &options,
181     ParsedTbsCertificate *out, CertErrors *errors);
182 
183 // Represents a "Version" from RFC 5280:
184 //         Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
185 enum class CertificateVersion {
186   V1,
187   V2,
188   V3,
189 };
190 
191 // ParsedTbsCertificate contains pointers to the main fields of a DER-encoded
192 // RFC 5280 "TBSCertificate".
193 //
194 // ParsedTbsCertificate is expected to be filled by ParseTbsCertificate(), so
195 // subsequent field descriptions are in terms of what ParseTbsCertificate()
196 // sets.
197 struct OPENSSL_EXPORT ParsedTbsCertificate {
198   ParsedTbsCertificate();
199   ParsedTbsCertificate(ParsedTbsCertificate &&other);
200   ParsedTbsCertificate &operator=(ParsedTbsCertificate &&other) = default;
201   ~ParsedTbsCertificate();
202 
203   // Corresponds with "version" from RFC 5280:
204   //         version         [0]  EXPLICIT Version DEFAULT v1,
205   //
206   // Parsing guarantees that the version is one of v1, v2, or v3.
207   CertificateVersion version = CertificateVersion::V1;
208 
209   // Corresponds with "serialNumber" from RFC 5280:
210   //         serialNumber         CertificateSerialNumber,
211   //
212   // This field specifically contains the content bytes of the INTEGER. So for
213   // instance if the serial number was 1000 then this would contain bytes
214   // {0x03, 0xE8}.
215   //
216   // The serial number may or may not be a valid DER-encoded INTEGER:
217   //
218   // If the option |allow_invalid_serial_numbers=true| was used during
219   // parsing, then nothing further can be assumed about these bytes.
220   //
221   // Otherwise if |allow_invalid_serial_numbers=false| then in addition
222   // to being a valid DER-encoded INTEGER, parsing guarantees that
223   // the serial number is at most 20 bytes long. Parsing does NOT guarantee
224   // that the integer is positive (might be zero or negative).
225   der::Input serial_number;
226 
227   // Corresponds with "signatureAlgorithm" from RFC 5280:
228   //         signatureAlgorithm   AlgorithmIdentifier,
229   //
230   // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
231   // guarantees are made regarding the value of this SEQUENCE.
232   //
233   // This can be further parsed using SignatureValue::Create().
234   der::Input signature_algorithm_tlv;
235 
236   // Corresponds with "issuer" from RFC 5280:
237   //         issuer               Name,
238   //
239   // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
240   // guarantees are made regarding the value of this SEQUENCE.
241   der::Input issuer_tlv;
242 
243   // Corresponds with "validity" from RFC 5280:
244   //         validity             Validity,
245   //
246   // Where Validity is defined as:
247   //
248   //   Validity ::= SEQUENCE {
249   //        notBefore      Time,
250   //        notAfter       Time }
251   //
252   // Parsing guarantees that notBefore (validity_not_before) and notAfter
253   // (validity_not_after) are valid DER-encoded dates, however it DOES NOT
254   // gurantee anything about their values. For instance notAfter could be
255   // before notBefore, or the dates could indicate an expired certificate.
256   // Consumers are responsible for testing expiration.
257   der::GeneralizedTime validity_not_before;
258   der::GeneralizedTime validity_not_after;
259 
260   // Corresponds with "subject" from RFC 5280:
261   //         subject              Name,
262   //
263   // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
264   // guarantees are made regarding the value of this SEQUENCE.
265   der::Input subject_tlv;
266 
267   // Corresponds with "subjectPublicKeyInfo" from RFC 5280:
268   //         subjectPublicKeyInfo SubjectPublicKeyInfo,
269   //
270   // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
271   // guarantees are made regarding the value of this SEQUENCE.
272   der::Input spki_tlv;
273 
274   // Corresponds with "issuerUniqueID" from RFC 5280:
275   //         issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
276   //                              -- If present, version MUST be v2 or v3
277   //
278   // Parsing guarantees that if issuer_unique_id is present it is a valid BIT
279   // STRING, and that the version is either v2 or v3
280   std::optional<der::BitString> issuer_unique_id;
281 
282   // Corresponds with "subjectUniqueID" from RFC 5280:
283   //         subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
284   //                              -- If present, version MUST be v2 or v3
285   //
286   // Parsing guarantees that if subject_unique_id is present it is a valid BIT
287   // STRING, and that the version is either v2 or v3
288   std::optional<der::BitString> subject_unique_id;
289 
290   // Corresponds with "extensions" from RFC 5280:
291   //         extensions      [3]  EXPLICIT Extensions OPTIONAL
292   //                              -- If present, version MUST be v3
293   //
294   //
295   // This contains the full (unverified) Tag-Length-Value for a SEQUENCE. No
296   // guarantees are made regarding the value of this SEQUENCE. (Note that the
297   // EXPLICIT outer tag is stripped.)
298   //
299   // Parsing guarantees that if extensions is present the version is v3.
300   std::optional<der::Input> extensions_tlv;
301 };
302 
303 // ParsedExtension represents a parsed "Extension" from RFC 5280. It contains
304 // der:Inputs which are not owned so the associated data must be kept alive.
305 //
306 //    Extension  ::=  SEQUENCE  {
307 //            extnID      OBJECT IDENTIFIER,
308 //            critical    BOOLEAN DEFAULT FALSE,
309 //            extnValue   OCTET STRING
310 //                        -- contains the DER encoding of an ASN.1 value
311 //                        -- corresponding to the extension type identified
312 //                        -- by extnID
313 //            }
314 struct OPENSSL_EXPORT ParsedExtension {
315   der::Input oid;
316   // |value| will contain the contents of the OCTET STRING. For instance for
317   // basicConstraints it will be the TLV for a SEQUENCE.
318   der::Input value;
319   bool critical = false;
320 };
321 
322 // Parses a DER-encoded "Extension" as specified by RFC 5280. Returns true on
323 // success and sets the results in |out|.
324 //
325 // Note that on success |out| aliases data from the input |extension_tlv|.
326 // Hence the fields of the ParsedExtension are only valid as long as
327 // |extension_tlv| remains valid.
328 //
329 // On failure |out| has an undefined state. Some of its fields may have been
330 // updated during parsing, whereas others may not have been changed.
331 [[nodiscard]] OPENSSL_EXPORT bool ParseExtension(der::Input extension_tlv,
332                                                  ParsedExtension *out);
333 
334 // From RFC 5280:
335 //
336 //     id-ce-subjectKeyIdentifier OBJECT IDENTIFIER ::=  { id-ce 14 }
337 //
338 // In dotted notation: 2.5.29.14
339 inline constexpr uint8_t kSubjectKeyIdentifierOid[] = {0x55, 0x1d, 0x0e};
340 
341 // From RFC 5280:
342 //
343 //     id-ce-keyUsage OBJECT IDENTIFIER ::=  { id-ce 15 }
344 //
345 // In dotted notation: 2.5.29.15
346 inline constexpr uint8_t kKeyUsageOid[] = {0x55, 0x1d, 0x0f};
347 
348 // From RFC 5280:
349 //
350 //     id-ce-subjectAltName OBJECT IDENTIFIER ::=  { id-ce 17 }
351 //
352 // In dotted notation: 2.5.29.17
353 inline constexpr uint8_t kSubjectAltNameOid[] = {0x55, 0x1d, 0x11};
354 
355 // From RFC 5280:
356 //
357 //     id-ce-basicConstraints OBJECT IDENTIFIER ::=  { id-ce 19 }
358 //
359 // In dotted notation: 2.5.29.19
360 inline constexpr uint8_t kBasicConstraintsOid[] = {0x55, 0x1d, 0x13};
361 
362 // From RFC 5280:
363 //
364 //     id-ce-nameConstraints OBJECT IDENTIFIER ::=  { id-ce 30 }
365 //
366 // In dotted notation: 2.5.29.30
367 inline constexpr uint8_t kNameConstraintsOid[] = {0x55, 0x1d, 0x1e};
368 
369 // From RFC 5280:
370 //
371 //     id-ce-certificatePolicies OBJECT IDENTIFIER ::=  { id-ce 32 }
372 //
373 // In dotted notation: 2.5.29.32
374 inline constexpr uint8_t kCertificatePoliciesOid[] = {0x55, 0x1d, 0x20};
375 
376 // From RFC 5280:
377 //
378 //     id-ce-authorityKeyIdentifier OBJECT IDENTIFIER ::=  { id-ce 35 }
379 //
380 // In dotted notation: 2.5.29.35
381 inline constexpr uint8_t kAuthorityKeyIdentifierOid[] = {0x55, 0x1d, 0x23};
382 
383 // From RFC 5280:
384 //
385 //     id-ce-policyConstraints OBJECT IDENTIFIER ::=  { id-ce 36 }
386 //
387 // In dotted notation: 2.5.29.36
388 inline constexpr uint8_t kPolicyConstraintsOid[] = {0x55, 0x1d, 0x24};
389 
390 // From RFC 5280:
391 //
392 //     id-ce-extKeyUsage OBJECT IDENTIFIER ::= { id-ce 37 }
393 //
394 // In dotted notation: 2.5.29.37
395 inline constexpr uint8_t kExtKeyUsageOid[] = {0x55, 0x1d, 0x25};
396 
397 // From RFC 5280:
398 //
399 //     id-pe-authorityInfoAccess OBJECT IDENTIFIER ::= { id-pe 1 }
400 //
401 // In dotted notation: 1.3.6.1.5.5.7.1.1
402 inline constexpr uint8_t kAuthorityInfoAccessOid[] = {0x2B, 0x06, 0x01, 0x05,
403                                                       0x05, 0x07, 0x01, 0x01};
404 
405 // From RFC 5280:
406 //
407 //     id-ad-caIssuers OBJECT IDENTIFIER ::= { id-ad 2 }
408 //
409 // In dotted notation: 1.3.6.1.5.5.7.48.2
410 inline constexpr uint8_t kAdCaIssuersOid[] = {0x2B, 0x06, 0x01, 0x05,
411                                               0x05, 0x07, 0x30, 0x02};
412 
413 // From RFC 5280:
414 //
415 //     id-ad-ocsp OBJECT IDENTIFIER ::= { id-ad 1 }
416 //
417 // In dotted notation: 1.3.6.1.5.5.7.48.1
418 inline constexpr uint8_t kAdOcspOid[] = {0x2B, 0x06, 0x01, 0x05,
419                                          0x05, 0x07, 0x30, 0x01};
420 
421 // From RFC 5280:
422 //
423 //     id-ce-cRLDistributionPoints OBJECT IDENTIFIER ::=  { id-ce 31 }
424 //
425 // In dotted notation: 2.5.29.31
426 inline constexpr uint8_t kCrlDistributionPointsOid[] = {0x55, 0x1d, 0x1f};
427 
428 // From RFC 6962:
429 //
430 // critical poison extension.
431 //
432 // In dotted notation 1.3.6.1.4.1.11129.2.4.3
433 inline constexpr uint8_t kCtPoisonOid[] = {0x2B, 0x06, 0x01, 0x04, 0x01,
434                                            0xD6, 0x79, 0x02, 0x04, 0x03};
435 
436 // From
437 // https://learn.microsoft.com/en-us/windows/win32/seccertenroll/supported-extensions#msapplicationpolicies
438 //
439 // OID: XCN_OID_APPLICATION_CERT_POLICIES (1.3.6.1.4.1.311.21.10)
440 inline constexpr uint8_t kMSApplicationPoliciesOid[] = {
441     0x2b, 0x06, 0x01, 0x04, 0x01, 0x82, 0x37, 0x15, 0x0a};
442 
443 // From GSMA RCC.16 v1.0 End-to-End Encryption Specification.
444 // id-gsmaRCSE2EE OBJECT IDENTIFIER ::=  { joint-iso-itu-t(2)
445 // international-organizations(23) gsma(146) rcs(2) rcsE2EE (1)}
446 // (Note this spec incorrectly says id-appleDraftRCSE2EE in place of
447 // id-gmsaRCSE2EE in several places)
448 //
449 // From GSMA RCC.16 v1.0 End-to-End Encryption Specification section A.2.8.8,
450 // and A.3.8.9.
451 // id-participantInformation OBJECT IDENTIFIER ::= { id-gmsaRCS2EE 4 }
452 // In dotted notation: 2.23.146.2.1.4
453 inline constexpr uint8_t kRcsMlsParticipantInformation[] = {0x67, 0x81, 0x12,
454                                                             0x02, 0x01, 0x04};
455 
456 // From GSMA RCC.16 v1.0 End-to-End Encryption Specification.
457 // id-gsmaRCSE2EE OBJECT IDENTIFIER ::=  { joint-iso-itu-t(2)
458 // international-organizations(23) gsma(146) rcs(2) rcsE2EE (1)}
459 // (Note this spec incorrectly says id-appleDraftRCSE2EE in place of
460 // id-gmsaRCSE2EE in several places)
461 //
462 // From GSMA RCC.16 v1.0 End-to-End Encryption Specification section A.2.8.8,
463 // and A.3.8.10.
464 // id-acsParticipantInformation OBJECT IDENTIFIER ::= { id-gmsaRCS2EE 5 }
465 // In dotted notation: 2.23.146.2.1.5
466 inline constexpr uint8_t kRcsMlsAcsParticipantInformation[] = {
467     0x67, 0x81, 0x12, 0x02, 0x01, 0x05};
468 
469 // Parses the Extensions sequence as defined by RFC 5280. Extensions are added
470 // to the map |extensions| keyed by the OID. Parsing guarantees that each OID
471 // is unique. Note that certificate verification must consume each extension
472 // marked as critical.
473 //
474 // Returns true on success and fills |extensions|. The output will reference
475 // bytes in |extensions_tlv|, so that data must be kept alive.
476 // On failure |extensions| may be partially written to and should not be used.
477 [[nodiscard]] OPENSSL_EXPORT bool ParseExtensions(
478     der::Input extensions_tlv,
479     std::map<der::Input, ParsedExtension> *extensions);
480 
481 // Removes the extension with OID |oid| from |unconsumed_extensions| and fills
482 // |extension| with the matching extension value. If there was no extension
483 // matching |oid| then returns |false|.
484 [[nodiscard]] OPENSSL_EXPORT bool ConsumeExtension(
485     der::Input oid,
486     std::map<der::Input, ParsedExtension> *unconsumed_extensions,
487     ParsedExtension *extension);
488 
489 struct ParsedBasicConstraints {
490   bool is_ca = false;
491   bool has_path_len = false;
492   uint8_t path_len = 0;
493 };
494 
495 // Parses the BasicConstraints extension as defined by RFC 5280:
496 //
497 //    BasicConstraints ::= SEQUENCE {
498 //         cA                      BOOLEAN DEFAULT FALSE,
499 //         pathLenConstraint       INTEGER (0..MAX) OPTIONAL }
500 //
501 // The maximum allowed value of pathLenConstraints will be whatever can fit
502 // into a uint8_t.
503 [[nodiscard]] OPENSSL_EXPORT bool ParseBasicConstraints(
504     der::Input basic_constraints_tlv, ParsedBasicConstraints *out);
505 
506 // KeyUsageBit contains the index for a particular key usage. The index is
507 // measured from the most significant bit of a bit string.
508 //
509 // From RFC 5280 section 4.2.1.3:
510 //
511 //     KeyUsage ::= BIT STRING {
512 //          digitalSignature        (0),
513 //          nonRepudiation          (1), -- recent editions of X.509 have
514 //                               -- renamed this bit to contentCommitment
515 //          keyEncipherment         (2),
516 //          dataEncipherment        (3),
517 //          keyAgreement            (4),
518 //          keyCertSign             (5),
519 //          cRLSign                 (6),
520 //          encipherOnly            (7),
521 //          decipherOnly            (8) }
522 enum KeyUsageBit {
523   KEY_USAGE_BIT_DIGITAL_SIGNATURE = 0,
524   KEY_USAGE_BIT_NON_REPUDIATION = 1,
525   KEY_USAGE_BIT_KEY_ENCIPHERMENT = 2,
526   KEY_USAGE_BIT_DATA_ENCIPHERMENT = 3,
527   KEY_USAGE_BIT_KEY_AGREEMENT = 4,
528   KEY_USAGE_BIT_KEY_CERT_SIGN = 5,
529   KEY_USAGE_BIT_CRL_SIGN = 6,
530   KEY_USAGE_BIT_ENCIPHER_ONLY = 7,
531   KEY_USAGE_BIT_DECIPHER_ONLY = 8,
532 };
533 
534 // Parses the KeyUsage extension as defined by RFC 5280. Returns true on
535 // success, and |key_usage| will alias data in |key_usage_tlv|. On failure
536 // returns false, and |key_usage| may have been modified.
537 //
538 // In addition to validating that key_usage_tlv is a BIT STRING, this does
539 // additional KeyUsage specific validations such as requiring at least 1 bit to
540 // be set.
541 //
542 // To test if a particular key usage is set, call, e.g.:
543 //     key_usage->AssertsBit(KEY_USAGE_BIT_DIGITAL_SIGNATURE);
544 [[nodiscard]] OPENSSL_EXPORT bool ParseKeyUsage(der::Input key_usage_tlv,
545                                                 der::BitString *key_usage);
546 
547 struct AuthorityInfoAccessDescription {
548   // The accessMethod DER OID value.
549   der::Input access_method_oid;
550   // The accessLocation DER TLV.
551   der::Input access_location;
552 };
553 // Parses the Authority Information Access extension defined by RFC 5280.
554 // Returns true on success, and |out_access_descriptions| will alias data
555 // in |authority_info_access_tlv|.On failure returns false, and
556 // out_access_descriptions may have been partially filled.
557 //
558 // No validation is performed on the contents of the
559 // AuthorityInfoAccessDescription fields.
560 [[nodiscard]] OPENSSL_EXPORT bool ParseAuthorityInfoAccess(
561     der::Input authority_info_access_tlv,
562     std::vector<AuthorityInfoAccessDescription> *out_access_descriptions);
563 
564 // Parses the Authority Information Access extension defined by RFC 5280,
565 // extracting the caIssuers URIs and OCSP URIs.
566 //
567 // Returns true on success, and |out_ca_issuers_uris| and |out_ocsp_uris| will
568 // alias data in |authority_info_access_tlv|. On failure returns false, and
569 // |out_ca_issuers_uris| and |out_ocsp_uris| may have been partially filled.
570 //
571 // |out_ca_issuers_uris| is filled with the accessLocations of type
572 // uniformResourceIdentifier for the accessMethod id-ad-caIssuers.
573 // |out_ocsp_uris| is filled with the accessLocations of type
574 // uniformResourceIdentifier for the accessMethod id-ad-ocsp.
575 //
576 // The values in |out_ca_issuers_uris| and |out_ocsp_uris| are checked to be
577 // IA5String (ASCII strings), but no other validation is performed on them.
578 //
579 // accessMethods other than id-ad-caIssuers and id-ad-ocsp are silently ignored.
580 // accessLocation types other than uniformResourceIdentifier are silently
581 // ignored.
582 [[nodiscard]] OPENSSL_EXPORT bool ParseAuthorityInfoAccessURIs(
583     der::Input authority_info_access_tlv,
584     std::vector<std::string_view> *out_ca_issuers_uris,
585     std::vector<std::string_view> *out_ocsp_uris);
586 
587 // ParsedDistributionPoint represents a parsed DistributionPoint from RFC 5280.
588 //
589 //   DistributionPoint ::= SEQUENCE {
590 //    distributionPoint       [0]     DistributionPointName OPTIONAL,
591 //    reasons                 [1]     ReasonFlags OPTIONAL,
592 //    cRLIssuer               [2]     GeneralNames OPTIONAL }
593 struct OPENSSL_EXPORT ParsedDistributionPoint {
594   ParsedDistributionPoint();
595   ParsedDistributionPoint(ParsedDistributionPoint &&other);
596   ~ParsedDistributionPoint();
597 
598   // The parsed fullName, if distributionPoint was present and was a fullName.
599   std::unique_ptr<GeneralNames> distribution_point_fullname;
600 
601   // If present, the DER encoded value of the nameRelativeToCRLIssuer field.
602   // This should be a RelativeDistinguishedName, but the parser does not
603   // validate it.
604   std::optional<der::Input> distribution_point_name_relative_to_crl_issuer;
605 
606   // If present, the DER encoded value of the reasons field. This should be a
607   // ReasonFlags bitString, but the parser does not validate it.
608   std::optional<der::Input> reasons;
609 
610   // If present, the DER encoded value of the cRLIssuer field. This should be a
611   // GeneralNames, but the parser does not validate it.
612   std::optional<der::Input> crl_issuer;
613 };
614 
615 // Parses the value of a CRL Distribution Points extension (sequence of
616 // DistributionPoint). Return true on success, and fills |distribution_points|
617 // with values that reference data in |distribution_points_tlv|.
618 [[nodiscard]] OPENSSL_EXPORT bool ParseCrlDistributionPoints(
619     der::Input distribution_points_tlv,
620     std::vector<ParsedDistributionPoint> *distribution_points);
621 
622 // Represents the AuthorityKeyIdentifier extension defined by RFC 5280 section
623 // 4.2.1.1.
624 //
625 //    AuthorityKeyIdentifier ::= SEQUENCE {
626 //       keyIdentifier             [0] KeyIdentifier           OPTIONAL,
627 //       authorityCertIssuer       [1] GeneralNames            OPTIONAL,
628 //       authorityCertSerialNumber [2] CertificateSerialNumber OPTIONAL  }
629 //
630 //    KeyIdentifier ::= OCTET STRING
631 struct OPENSSL_EXPORT ParsedAuthorityKeyIdentifier {
632   ParsedAuthorityKeyIdentifier();
633   ~ParsedAuthorityKeyIdentifier();
634   ParsedAuthorityKeyIdentifier(ParsedAuthorityKeyIdentifier &&other);
635   ParsedAuthorityKeyIdentifier &operator=(ParsedAuthorityKeyIdentifier &&other);
636 
637   // The keyIdentifier, which is an OCTET STRING.
638   std::optional<der::Input> key_identifier;
639 
640   // The authorityCertIssuer, which should be a GeneralNames, but this is not
641   // enforced by ParseAuthorityKeyIdentifier.
642   std::optional<der::Input> authority_cert_issuer;
643 
644   // The DER authorityCertSerialNumber, which should be a
645   // CertificateSerialNumber (an INTEGER) but this is not enforced by
646   // ParseAuthorityKeyIdentifier.
647   std::optional<der::Input> authority_cert_serial_number;
648 };
649 
650 // Parses the value of an authorityKeyIdentifier extension. Returns true on
651 // success and fills |authority_key_identifier| with values that reference data
652 // in |extension_value|. On failure the state of |authority_key_identifier| is
653 // not guaranteed.
654 [[nodiscard]] OPENSSL_EXPORT bool ParseAuthorityKeyIdentifier(
655     der::Input extension_value,
656     ParsedAuthorityKeyIdentifier *authority_key_identifier);
657 
658 // Parses the value of a subjectKeyIdentifier extension. Returns true on
659 // success and |subject_key_identifier| references data in |extension_value|.
660 // On failure the state of |subject_key_identifier| is not guaranteed.
661 [[nodiscard]] OPENSSL_EXPORT bool ParseSubjectKeyIdentifier(
662     der::Input extension_value, der::Input *subject_key_identifier);
663 
664 BSSL_NAMESPACE_END
665 
666 #endif  // BSSL_PKI_PARSE_CERTIFICATE_H_
667