blob: f24499c8c3ec6fe9177aab0e9d8e04daa11479d6 [file] [log] [blame]
Alexander Afanasyev7e721412017-01-11 13:36:08 -08001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2/**
3 * Copyright (c) 2013-2017 Regents of the University of California.
4 *
5 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
6 *
7 * ndn-cxx library is free software: you can redistribute it and/or modify it under the
8 * terms of the GNU Lesser General Public License as published by the Free Software
9 * Foundation, either version 3 of the License, or (at your option) any later version.
10 *
11 * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
12 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
13 * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
14 *
15 * You should have received copies of the GNU General Public License and GNU Lesser
16 * General Public License along with ndn-cxx, e.g., in COPYING.md file. If not, see
17 * <http://www.gnu.org/licenses/>.
18 *
19 * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
20 */
21
22#ifndef NDN_SECURITY_V2_VALIDATOR_HPP
23#define NDN_SECURITY_V2_VALIDATOR_HPP
24
Alexander Afanasyev7bc10fa2017-01-13 16:56:26 -080025#include "certificate-fetcher.hpp"
Alexander Afanasyev7e721412017-01-11 13:36:08 -080026#include "certificate-request.hpp"
Alexander Afanasyev7bc10fa2017-01-13 16:56:26 -080027#include "certificate-storage.hpp"
Alexander Afanasyev7e721412017-01-11 13:36:08 -080028#include "validation-callback.hpp"
29#include "validation-policy.hpp"
30#include "validation-state.hpp"
31
32namespace ndn {
33
34class Face;
35
Alexander Afanasyev7e721412017-01-11 13:36:08 -080036namespace security {
37namespace v2 {
38
39/**
40 * @brief Interface for validating data and interest packets.
41 *
42 * Every time a validation process initiated, it creates a ValidationState that exist until
43 * validation finishes with either success or failure. This state serves several purposes:
44 * - record Interest or Data packet being validated
45 * - record failure callback
46 * - record certificates in the certification chain for the Interest or Data packet being validated
47 * - record names of the requested certificates to detect loops in the certificate chain
48 * - keep track of the validation chain size (aka validation "depth")
49 *
Alexander Afanasyev7bc10fa2017-01-13 16:56:26 -080050 * During validation, policy and/or key fetcher can augment validation state with policy- and
51 * fetcher-specific information using ndn::Tag's.
Alexander Afanasyev7e721412017-01-11 13:36:08 -080052 *
53 * A validator has a trust anchor cache to save static and dynamic trust anchors, a verified
54 * certificate cache for saving certificates that are already verified and an unverified
55 * certificate cache for saving prefetched but not yet verified certificates.
56 *
57 * @todo Limit the maximum time the validation process is allowed to run before declaring failure
58 * @todo Ability to customize maximum lifetime for trusted and untrusted certificate caches.
59 * Current implementation hard-codes them to be 1 hour and 5 minutes.
60 */
Alexander Afanasyev7bc10fa2017-01-13 16:56:26 -080061class Validator : public CertificateStorage
Alexander Afanasyev7e721412017-01-11 13:36:08 -080062{
63public:
64 /**
65 * @brief Validator constructor.
66 *
Alexander Afanasyev7bc10fa2017-01-13 16:56:26 -080067 * @param policy Validation policy to be associated with the validator
68 * @param certFetcher Certificate fetcher implementation.
Alexander Afanasyev7e721412017-01-11 13:36:08 -080069 */
Alexander Afanasyev7bc10fa2017-01-13 16:56:26 -080070 Validator(unique_ptr<ValidationPolicy> policy, unique_ptr<CertificateFetcher> certFetcher);
Alexander Afanasyev7e721412017-01-11 13:36:08 -080071
72 ~Validator();
73
74 /**
75 * @brief Set the maximum depth of the certificate chain
76 */
77 void
78 setMaxDepth(size_t depth);
79
80 /**
81 * @return The maximum depth of the certificate chain
82 */
83 size_t
84 getMaxDepth() const;
85
86 /**
87 * @brief Asynchronously validate @p data
88 *
89 * @note @p successCb and @p failureCb must not be nullptr
90 */
91 void
92 validate(const Data& data,
93 const DataValidationSuccessCallback& successCb,
94 const DataValidationFailureCallback& failureCb);
95
96 /**
97 * @brief Asynchronously validate @p interest
98 *
99 * @note @p successCb and @p failureCb must not be nullptr
100 */
101 void
102 validate(const Interest& interest,
103 const InterestValidationSuccessCallback& successCb,
104 const InterestValidationFailureCallback& failureCb);
105
106public: // anchor management
107 /**
108 * @brief load static trust anchor.
109 *
110 * Static trust anchors are permanently associated with the validator and never expire.
111 *
112 * @param groupId Certificate group id.
113 * @param cert Certificate to load as a trust anchor.
114 */
115 void
116 loadAnchor(const std::string& groupId, Certificate&& cert);
117
118 /**
119 * @brief load dynamic trust anchors.
120 *
121 * Dynamic trust anchors are associated with the validator for as long as the underlying
122 * trust anchor file (set of files) exist(s).
123 *
124 * @param groupId Certificate group id, must not be empty.
125 * @param certfilePath Specifies the path to load the trust anchors.
126 * @param refreshPeriod Refresh period for the trust anchors, must be positive.
127 * @param isDir Tells whether the path is a directory or a single file.
128 */
129 void
130 loadAnchor(const std::string& groupId, const std::string& certfilePath,
131 time::nanoseconds refreshPeriod, bool isDir = false);
132
133 /**
134 * @brief Cache verified @p cert a period of time (1 hour)
135 *
136 * @todo Add ability to customize time period
137 */
138 void
139 cacheVerifiedCertificate(Certificate&& cert);
140
Alexander Afanasyev7e721412017-01-11 13:36:08 -0800141private: // Common validator operations
142 /**
143 * @brief Recursive validation of the certificate in the certification chain
144 *
145 * @param cert The certificate to check.
146 * @param state The current validation state.
147 */
148 void
149 validate(const Certificate& cert, const shared_ptr<ValidationState>& state);
150
151 /**
152 * @brief Request certificate for further validation.
153 *
154 * @param certRequest Certificate request.
155 * @param state The current validation state.
156 */
157 void
158 requestCertificate(const shared_ptr<CertificateRequest>& certRequest,
159 const shared_ptr<ValidationState>& state);
160
Alexander Afanasyev7e721412017-01-11 13:36:08 -0800161private:
162 unique_ptr<ValidationPolicy> m_policy;
Alexander Afanasyev7bc10fa2017-01-13 16:56:26 -0800163 unique_ptr<CertificateFetcher> m_certFetcher;
Alexander Afanasyev7e721412017-01-11 13:36:08 -0800164 size_t m_maxDepth;
165};
166
167} // namespace v2
168} // namespace security
169} // namespace ndn
170
171#endif // NDN_SECURITY_V2_VALIDATOR_HPP