1 // Copyright 2016 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_TRUST_STORE_H_
16 #define BSSL_PKI_TRUST_STORE_H_
17 
18 #include <optional>
19 
20 #include <openssl/base.h>
21 
22 #include "cert_issuer_source.h"
23 #include "parsed_certificate.h"
24 
25 BSSL_NAMESPACE_BEGIN
26 
27 enum class CertificateTrustType {
28   // This certificate is explicitly blocked (distrusted).
29   DISTRUSTED,
30 
31   // The trustedness of this certificate is unknown (inherits trust from
32   // its issuer).
33   UNSPECIFIED,
34 
35   // This certificate is a trust anchor (as defined by RFC 5280).
36   TRUSTED_ANCHOR,
37 
38   // This certificate can be used as a trust anchor (as defined by RFC 5280) or
39   // a trusted leaf, depending on context.
40   TRUSTED_ANCHOR_OR_LEAF,
41 
42   // This certificate is a directly trusted leaf.
43   TRUSTED_LEAF,
44 
45   LAST = TRUSTED_ANCHOR
46 };
47 
48 // Describes the level of trust in a certificate.
49 struct OPENSSL_EXPORT CertificateTrust {
ForTrustAnchorCertificateTrust50   static constexpr CertificateTrust ForTrustAnchor() {
51     CertificateTrust result;
52     result.type = CertificateTrustType::TRUSTED_ANCHOR;
53     return result;
54   }
55 
ForTrustAnchorOrLeafCertificateTrust56   static constexpr CertificateTrust ForTrustAnchorOrLeaf() {
57     CertificateTrust result;
58     result.type = CertificateTrustType::TRUSTED_ANCHOR_OR_LEAF;
59     return result;
60   }
61 
ForTrustedLeafCertificateTrust62   static constexpr CertificateTrust ForTrustedLeaf() {
63     CertificateTrust result;
64     result.type = CertificateTrustType::TRUSTED_LEAF;
65     return result;
66   }
67 
ForUnspecifiedCertificateTrust68   static constexpr CertificateTrust ForUnspecified() {
69     CertificateTrust result;
70     return result;
71   }
72 
ForDistrustedCertificateTrust73   static constexpr CertificateTrust ForDistrusted() {
74     CertificateTrust result;
75     result.type = CertificateTrustType::DISTRUSTED;
76     return result;
77   }
78 
79   constexpr CertificateTrust WithEnforceAnchorExpiry(bool value = true) const {
80     CertificateTrust result = *this;
81     result.enforce_anchor_expiry = value;
82     return result;
83   }
84 
85   constexpr CertificateTrust WithEnforceAnchorConstraints(
86       bool value = true) const {
87     CertificateTrust result = *this;
88     result.enforce_anchor_constraints = value;
89     return result;
90   }
91 
92   constexpr CertificateTrust WithRequireAnchorBasicConstraints(
93       bool value = true) const {
94     CertificateTrust result = *this;
95     result.require_anchor_basic_constraints = value;
96     return result;
97   }
98 
99   constexpr CertificateTrust WithRequireLeafSelfSigned(
100       bool value = true) const {
101     CertificateTrust result = *this;
102     result.require_leaf_selfsigned = value;
103     return result;
104   }
105 
106   bool IsTrustAnchor() const;
107   bool IsTrustLeaf() const;
108   bool IsDistrusted() const;
109   bool HasUnspecifiedTrust() const;
110 
111   std::string ToDebugString() const;
112 
113   static std::optional<CertificateTrust> FromDebugString(
114       const std::string &trust_string);
115 
116   // The overall type of trust.
117   CertificateTrustType type = CertificateTrustType::UNSPECIFIED;
118 
119   // Optionally, enforce extra bits on trust anchors. If these are false, the
120   // only fields in a trust anchor certificate that are meaningful are its
121   // name and SPKI.
122   bool enforce_anchor_expiry = false;
123   bool enforce_anchor_constraints = false;
124   // Require that X.509v3 trust anchors have a basicConstraints extension.
125   // X.509v1 and X.509v2 trust anchors do not support basicConstraints and are
126   // not affected.
127   // Additionally, this setting only has effect if `enforce_anchor_constraints`
128   // is true, which also requires that the extension assert CA=true.
129   bool require_anchor_basic_constraints = false;
130 
131   // Optionally, require trusted leafs to be self-signed to be trusted.
132   bool require_leaf_selfsigned = false;
133 };
134 
135 // Interface for finding intermediates / trust anchors, and testing the
136 // trustedness of certificates.
137 class OPENSSL_EXPORT TrustStore : public CertIssuerSource {
138  public:
139   TrustStore();
140 
141   TrustStore(const TrustStore &) = delete;
142   TrustStore &operator=(const TrustStore &) = delete;
143 
144   // Returns the trusted of |cert|, which must be non-null.
145   virtual CertificateTrust GetTrust(const ParsedCertificate *cert) = 0;
146 
147   // Disable async issuers for TrustStore, as it isn't needed.
148   void AsyncGetIssuersOf(const ParsedCertificate *cert,
149                          std::unique_ptr<Request> *out_req) final;
150 };
151 
152 BSSL_NAMESPACE_END
153 
154 #endif  // BSSL_PKI_TRUST_STORE_H_
155