Index: net/cert/ct_policy_enforcer.h |
diff --git a/net/cert/ct_policy_enforcer.h b/net/cert/ct_policy_enforcer.h |
index a2db8f0872e449a8d3b2c772126a5b00c5d6be8e..110c208ee49c1f7b010466be59be0621bcd71e53 100644 |
--- a/net/cert/ct_policy_enforcer.h |
+++ b/net/cert/ct_policy_enforcer.h |
@@ -17,6 +17,7 @@ namespace net { |
namespace ct { |
class EVCertsWhitelist; |
+enum class CertPolicyCompliance; |
enum class EVPolicyCompliance; |
} // namespace ct |
@@ -25,19 +26,73 @@ class X509Certificate; |
using SCTList = std::vector<scoped_refptr<ct::SignedCertificateTimestamp>>; |
-// Class for checking that a given certificate conforms to security-related |
+// Class for checking that a given certificate conforms to |
+// Certificate Transparency-related policies. |
+// |
+// Each method can be called independently, to determine whether |
+// or not it complies with a given policy. |
+// |
+// For example, to determine if a certificate complies with the |
+// EV certificate policy, callers need only to call |
+// DoesConformToEVPolicy() - it is not necessary to first check |
+// whether or not DoesConformToCertPolicy(). |
+// |
+// However, consider the case where a given certificate is desired |
+// to be EV, but, if it does not conform to the EV policy, will |
+// be downgraded to DV. In this case, it's necessary to check if |
+// it complies with either policy. This can be done one of two |
+// ways, reflected in pseudo-code below: |
+// |
+// Recommended: |
+// // Checks EV certificates against the EV policy. If the |
+// // certificate fails, it will be downgraded to DV, in which |
+// // case, the DV policy will apply. |
+// bool is_valid_cert_policy = DoesConformToCertPolicy(...); |
+// bool is_valid_ev_policy = is_ev && DoesConformToEVPolicy(...); |
+// if (!is_valid_ev_policy) |
+// is_ev = false; |
+// is_valid_ct = is_valid_ev_policy || is_valid_cert_policy; |
+// |
+// NOT recommended: |
+// // Checks all certificates against the basic policy, and only |
+// // if they meet the baseline policy, check EV. |
+// bool conforms_to_cert_policy = DoesConformToCertPolicy(...); |
+// if (conforms_to_cert_policy && is_ev) { |
+// conforms_to_cert_policy = DoesConformToEVPolicy(...); |
+// } |
+// |
+// The reason the second form is NOT recommended is that the EV and Cert |
+// policies may be completely independent: a certificate might fail the |
+// cert policy but pass the EV policy (because, for example, the EV |
+// policy supports whitelisting certificates). Or, conversely, the EV |
+// policy might have stricter SCT requirements, so that a certificate |
+// passes the certificate policy but fails the EV policy. For this |
+// reason, callers are encouraged to check the policy specific to the |
+// certificate type being validated, and only call other methods if they |
+// are changing the type of certificate because it failed one or more |
// policies. |
class NET_EXPORT CTPolicyEnforcer { |
public: |
CTPolicyEnforcer() {} |
virtual ~CTPolicyEnforcer() {} |
+ // Returns the CT certificate policy compliance status for a given |
+ // certificate and collection of SCTs. |
+ // |cert| is the certificate for which to check compliance, and |
+ // ||verified_scts| contains any/all SCTs associated with |cert| that |
+ // |have been verified (well-formed, issued by known logs, and |
+ // |applying to |cert|). |
+ virtual ct::CertPolicyCompliance DoesConformToCertPolicy( |
+ X509Certificate* cert, |
+ const SCTList& verified_scts, |
+ const BoundNetLog& net_log); |
+ |
// Returns the CT/EV policy compliance status for a given certificate |
// and collection of SCTs. |
// |cert| is the certificate for which to check compliance, and |
- // |verified_scts| contains any/all SCTs associated with |cert| that |
- // have been verified (well-formed, issued by known logs, and applying to |
- // |cert|). |
+ // ||verified_scts| contains any/all SCTs associated with |cert| that |
+ // |have been verified (well-formed, issued by known logs, and |
+ // |applying to |cert|). |
virtual ct::EVPolicyCompliance DoesConformToCTEVPolicy( |
X509Certificate* cert, |
const ct::EVCertsWhitelist* ev_whitelist, |