OLD | NEW |
---|---|
(Empty) | |
1 // Copyright 2016 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_PATH_BUILDER_H_ | |
6 #define NET_CERT_INTERNAL_PATH_BUILDER_H_ | |
7 | |
8 #include <memory> | |
9 #include <string> | |
10 #include <vector> | |
11 | |
12 #include "base/callback.h" | |
13 #include "net/base/completion_callback.h" | |
14 #include "net/base/net_errors.h" | |
15 #include "net/base/net_export.h" | |
16 #include "net/cert/internal/completion_status.h" | |
17 #include "net/der/input.h" | |
18 #include "net/der/parse_values.h" | |
19 | |
20 namespace net { | |
21 | |
22 namespace der { | |
23 struct GeneralizedTime; | |
24 } | |
25 | |
26 class CertPathIter; | |
27 class CertIssuerSource; | |
28 class ParsedCertificate; | |
29 class TrustStore; | |
30 class SignaturePolicy; | |
31 | |
32 // Checks whether a certificate is trusted by building candidate paths to trust | |
33 // anchors and verifying those paths according to RFC 5280. Each instance of | |
34 // CertPathBuilder is used for a single verification. | |
35 // | |
36 // WARNING: This implementation is currently experimental. Consult an OWNER | |
37 // before using it. | |
38 class NET_EXPORT CertPathBuilder { | |
39 public: | |
40 // Represents a single candidate path that was built. | |
41 struct NET_EXPORT ResultPath { | |
42 ResultPath(); | |
43 ~ResultPath(); | |
44 | |
45 // Returns true if this path was successfully verified. | |
46 bool is_success() const { return rv == OK; } | |
47 | |
48 // The candidate path, in forward direction. | |
49 // * path[0] is the target certificate. | |
50 // * path[i+1] is a candidate issuer of path[i]. The subject matches | |
51 // path[i]'s issuer, but nothing else is guaranteed unless is_success() is | |
52 // true. | |
53 // * path[N-1] will be a trust anchor if is_success() is true, otherwise | |
54 // it may or may not be a trust anchor. | |
55 std::vector<scoped_refptr<ParsedCertificate>> path; | |
56 // A net error code result of attempting to verify this path. | |
eroman
2016/06/27 19:58:52
I personally find these blocks of text easier when
mattm
2016/06/27 23:45:45
Done.
| |
57 // TODO(mattm): may want to have an independent result enum, which caller | |
58 // can map to a net error if they want. | |
59 int rv = ERR_UNEXPECTED; | |
eroman
2016/06/27 19:58:52
instead of "rv" how about "error" or "status" or "
mattm
2016/06/27 23:45:45
Yeah I should have renamed this. Though I didn't r
| |
60 }; | |
61 | |
62 // Provides the results of the path building attempt. | |
eroman
2016/06/27 19:58:52
How about expanding this:
Provides the overall re
mattm
2016/06/27 23:45:45
Done.
| |
63 struct NET_EXPORT Result { | |
64 Result(); | |
65 ~Result(); | |
66 | |
67 // Returns true if there was a valid path. | |
68 bool is_success() const { return result() == OK; } | |
69 | |
70 // Returns the overall best result. | |
71 int result() const { | |
72 if (paths.empty()) | |
73 return ERR_CERT_AUTHORITY_INVALID; | |
74 return paths[best_result_index]->rv; | |
75 } | |
76 | |
77 // List of paths that were attempted and the result for each. | |
78 std::vector<std::unique_ptr<ResultPath>> paths; | |
79 // Index into |paths|. Before use, |paths.empty()| must be checked. | |
80 // NOTE: currently the definition of "best" is fairly limited. Successful is | |
81 // better than unsuccessful, but otherwise nothing is guaranteed. | |
82 size_t best_result_index = 0; | |
83 | |
84 private: | |
85 DISALLOW_COPY_AND_ASSIGN(Result); | |
86 }; | |
87 | |
88 // TODO(mattm): allow caller specified hook/callback to extend path | |
89 // verification. | |
90 // | |
91 // Creates a CertPathBuilder that attempts to find a path from |cert| to a | |
92 // trust anchor in |trust_store|, which satisfies |signature_policy| and is | |
93 // valid at |time|. Details of attempted path(s) are stored in |*result|. | |
94 // | |
95 // The caller must keep |trust_store|, |signature_policy|, and |*result| valid | |
96 // for the lifetime of the CertPathBuilder. | |
97 CertPathBuilder(scoped_refptr<ParsedCertificate> cert, | |
eroman
2016/06/27 19:58:52
What is the design tradeoff for having the paramet
mattm
2016/06/27 23:45:45
They're all stored in members so putting in the co
| |
98 const TrustStore* trust_store, | |
99 const SignaturePolicy* signature_policy, | |
100 const der::GeneralizedTime& time, | |
101 Result* result); | |
102 ~CertPathBuilder(); | |
103 | |
104 // Adds a CertIssuerSource to provide intermediates for use in path building. | |
105 // Multiple sources may be added. Must not be called after Run is called. | |
106 // The |*cert_issuer_source| must remain valid for the lifetime of the | |
107 // CertPathBuilder. | |
108 // | |
109 // (If no issuer sources are added, the target certificate will only verify if | |
110 // it is a trust anchor or is directly signed by a trust anchor.) | |
111 void AddCertIssuerSource(CertIssuerSource* cert_issuer_source); | |
112 | |
113 // Begins verification of the target certificate. | |
114 // | |
115 // If the return value is SYNC then the verification is complete and the | |
116 // |result| value can be inspected for the status, and |callback| will not be | |
117 // called. | |
118 // If the return value is ASYNC, the |callback| will be called asynchronously | |
119 // once the verification is complete. |result| should not be examined or | |
120 // modified until the |callback| is run. | |
121 // | |
122 // If |callback| is null, verification always completes synchronously, even if | |
123 // it fails to find a valid path and one could have been found asynchronously. | |
124 // | |
125 // The CertPathBuilder may be deleted while an ASYNC verification is pending, | |
126 // in which case the verification is cancelled, |callback| will not be called, | |
127 // and the output Result will be in an undefined state. | |
eroman
2016/06/27 19:58:52
How about deleting CertPathBuilder within the comp
mattm
2016/06/27 23:45:45
Yes, added that to the comment.
| |
128 // Must not be called more than once on each CertPathBuilder instance. | |
129 CompletionStatus Run(const base::Closure& callback); | |
130 | |
131 private: | |
132 enum State { | |
133 STATE_NONE, | |
134 STATE_GET_NEXT_PATH, | |
135 STATE_GET_NEXT_PATH_COMPLETE, | |
136 }; | |
137 | |
138 CompletionStatus DoLoop(bool allow_async); | |
139 | |
140 CompletionStatus DoGetNextPath(bool allow_async); | |
141 void HandleGotNextPath(); | |
142 CompletionStatus DoGetNextPathComplete(); | |
143 | |
144 void AddResultPath(const std::vector<scoped_refptr<ParsedCertificate>>& path, | |
145 bool result); | |
eroman
2016/06/27 19:58:52
can you rename "result" to something more like "su
mattm
2016/06/27 23:45:45
Done.
| |
146 | |
147 base::Closure callback_; | |
148 | |
149 std::unique_ptr<CertPathIter> cert_path_iter_; | |
150 const TrustStore* trust_store_; | |
151 const SignaturePolicy* signature_policy_; | |
152 const der::GeneralizedTime time_; | |
153 | |
154 std::vector<scoped_refptr<ParsedCertificate>> next_path_; | |
eroman
2016/06/27 19:58:52
Please document this.
mattm
2016/06/27 23:45:45
Done.
| |
155 State next_state_; | |
156 | |
157 Result* out_result_; | |
158 | |
159 DISALLOW_COPY_AND_ASSIGN(CertPathBuilder); | |
160 }; | |
161 | |
162 } // namespace net | |
163 | |
164 #endif // NET_CERT_INTERNAL_PATH_BUILDER_H_ | |
OLD | NEW |