1 // Copyright 2019 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 CAST_COMMON_CERTIFICATE_CAST_CERT_VALIDATOR_H_
6 #define CAST_COMMON_CERTIFICATE_CAST_CERT_VALIDATOR_H_
7 
8 #include <memory>
9 #include <string>
10 #include <vector>
11 
12 #include "cast/common/certificate/types.h"
13 #include "platform/base/error.h"
14 #include "platform/base/macros.h"
15 
16 namespace openscreen {
17 namespace cast {
18 
19 class CastCRL;
20 
21 // Describes the policy for a Device certificate.
22 enum class CastDeviceCertPolicy {
23   // The device certificate is unrestricted.
24   kUnrestricted,
25 
26   // The device certificate is for an audio-only device.
27   kAudioOnly,
28 };
29 
30 enum class CRLPolicy {
31   // Revocation is only checked if a CRL is provided.
32   kCrlOptional,
33 
34   // Revocation is always checked. A missing CRL results in failure.
35   kCrlRequired,
36 };
37 
38 enum class DigestAlgorithm {
39   kSha1,
40   kSha256,
41   kSha384,
42   kSha512,
43 };
44 
45 struct TrustStore;
46 
47 // An object of this type is returned by the VerifyDeviceCert function, and can
48 // be used for additional certificate-related operations, using the verified
49 // certificate.
50 class CertVerificationContext {
51  public:
52   CertVerificationContext() = default;
53   virtual ~CertVerificationContext() = default;
54 
55   // Use the public key from the verified certificate to verify a
56   // |digest_algorithm|WithRSAEncryption |signature| over arbitrary |data|.
57   // Both |signature| and |data| hold raw binary data. Returns true if the
58   // signature was correct.
59   virtual bool VerifySignatureOverData(
60       const ConstDataSpan& signature,
61       const ConstDataSpan& data,
62       DigestAlgorithm digest_algorithm) const = 0;
63 
64   // Retrieve the Common Name attribute of the subject's distinguished name from
65   // the verified certificate, if present.  Returns an empty string if no Common
66   // Name is found.
67   virtual const std::string& GetCommonName() const = 0;
68 
69  private:
70   OSP_DISALLOW_COPY_AND_ASSIGN(CertVerificationContext);
71 };
72 
73 // Verifies a cast device certificate given a chain of DER-encoded certificates.
74 //
75 // Inputs:
76 //
77 // * |der_certs| is a chain of DER-encoded certificates:
78 //   * |der_certs[0]| is the target certificate (i.e. the device certificate).
79 //   * |der_certs[1..n-1]| are intermediates certificates to use in path
80 //     building.  Their ordering does not matter.
81 //
82 // * |time| is the timestamp to use for determining if the certificate is
83 //   expired.
84 //
85 // * |crl| is the CRL to check for certificate revocation status.
86 //   If this is a nullptr, then revocation checking is currently disabled.
87 //
88 // * |crl_policy| is for choosing how to handle the absence of a CRL.
89 //   If CRL_REQUIRED is passed, then an empty |crl| input would result
90 //   in a failed verification. Otherwise, |crl| is ignored if it is absent.
91 //
92 // * |trust_store| is an optional set of trusted certificates that may act as
93 //   root CAs during chain verification.  If this is nullptr, the built-in Cast
94 //   root certificates will be used.
95 //
96 // Outputs:
97 //
98 // Returns Error::Code::kNone on success.  Otherwise, the corresponding
99 // Error::Code.  On success, the output parameters are filled with more details:
100 //
101 //   * |context| is filled with an object that can be used to verify signatures
102 //     using the device certificate's public key, as well as to extract other
103 //     properties from the device certificate (Common Name).
104 //   * |policy| is filled with an indication of the device certificate's policy
105 //     (i.e. is it for audio-only devices or is it unrestricted?)
106 [[nodiscard]] Error VerifyDeviceCert(
107     const std::vector<std::string>& der_certs,
108     const DateTime& time,
109     std::unique_ptr<CertVerificationContext>* context,
110     CastDeviceCertPolicy* policy,
111     const CastCRL* crl,
112     CRLPolicy crl_policy,
113     TrustStore* trust_store = nullptr);
114 
115 }  // namespace cast
116 }  // namespace openscreen
117 
118 #endif  // CAST_COMMON_CERTIFICATE_CAST_CERT_VALIDATOR_H_
119