security: CommandInterestValidator

refs #2376

Change-Id: Ia1d2231a4fb7ad130e11dd0d0dd52d8007149470
diff --git a/src/security/command-interest-validator.hpp b/src/security/command-interest-validator.hpp
new file mode 100644
index 0000000..e789f09
--- /dev/null
+++ b/src/security/command-interest-validator.hpp
@@ -0,0 +1,194 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/**
+ * Copyright (c) 2013-2016 Regents of the University of California.
+ *
+ * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
+ *
+ * ndn-cxx library is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
+ *
+ * You should have received copies of the GNU General Public License and GNU Lesser
+ * General Public License along with ndn-cxx, e.g., in COPYING.md file.  If not, see
+ * <http://www.gnu.org/licenses/>.
+ *
+ * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
+ */
+
+#ifndef NDN_SECURITY_COMMAND_INTEREST_VALIDATOR_HPP
+#define NDN_SECURITY_COMMAND_INTEREST_VALIDATOR_HPP
+
+#include "validator.hpp"
+#include <boost/multi_index_container.hpp>
+#include <boost/multi_index/ordered_index.hpp>
+#include <boost/multi_index/sequenced_index.hpp>
+#include <boost/multi_index/key_extractors.hpp>
+
+namespace ndn {
+namespace security {
+
+/** \brief a validator for stop-and-wait command Interests
+ *  \sa https://redmine.named-data.net/projects/ndn-cxx/wiki/CommandInterest
+ *
+ *  This validator checks timestamp field of a stop-and-wait command Interest.
+ *  Signed Interest validation and Data validation requests are delegated to an inner validator.
+ */
+class CommandInterestValidator : public Validator
+{
+public:
+  class Options
+  {
+  public:
+    Options()
+    {
+    }
+
+  public:
+    /** \brief tolerance of initial timestamp
+     *
+     *  A stop-and-wait command Interest is considered "initial" if the validator
+     *  has not recorded the last timestamp from the same public key, or when
+     *  such knowledge has been erased.
+     *  For an initial command Interest, its timestamp is compared to the current
+     *  system clock, and the command Interest is rejected if the absolute difference
+     *  is greater than the grace interval.
+     *
+     *  This should be positive.
+     *  Setting this option to 0 or negative causes the validator to require exactly same
+     *  timestamp as the system clock, which most likely rejects all command Interests.
+     */
+    time::nanoseconds gracePeriod = time::seconds(120);
+
+    /** \brief max number of distinct public keys to record last timestamp
+     *
+     *  The validator records last timestamps for every public key.
+     *  For a subsequent command Interest using the same public key,
+     *  its timestamp is compared to the last timestamp from that public key,
+     *  and the command Interest is rejected if its timestamp is
+     *  less than or equal to the recorded timestamp.
+     *
+     *  This option limits the number of distinct public keys being tracked.
+     *  If the limit is exceeded, the oldest record is deleted.
+     *
+     *  Setting this option to -1 allows tracking unlimited public keys.
+     *  Setting this option to 0 disables last timestamp records and causes
+     *  every command Interest to be processed as initial.
+     */
+    ssize_t maxTimestamps = 1000;
+
+    /** \brief max lifetime of a last timestamp record
+     *
+     *  A last timestamp record expires and can be deleted if it has not been refreshed
+     *  within this duration.
+     *  Setting this option to 0 or negative makes last timestamp records expire immediately
+     *  and causes every command Interest to be processed as initial.
+     */
+    time::nanoseconds timestampTtl = time::hours(1);
+
+  };
+
+  /** \brief error codes
+   *  \todo #1872 assign numeric codes to these errors
+   */
+  enum class ErrorCode {
+    NONE = 0,
+    NAME_TOO_SHORT,
+    BAD_TIMESTAMP,
+    BAD_SIG_INFO,
+    MISSING_KEY_LOCATOR,
+    BAD_KEY_LOCATOR_TYPE,
+    BAD_CERT_NAME,
+    TIMESTAMP_OUT_OF_GRACE,
+    TIMESTAMP_REORDER
+  };
+
+  /** \brief constructor
+   *  \param inner a Validator for signed Interest signature validation and Data validation;
+   *               this must not be nullptr
+   *  \param options stop-and-wait command Interest validation options
+   *  \throw std::invalid inner is nullptr
+   */
+  explicit
+  CommandInterestValidator(unique_ptr<Validator> inner,
+                           const Options& options = Options());
+
+protected:
+  /** \brief validate command Interest
+   *
+   *  This function executes the following validation procedure:
+   *
+   *  1. parse the Interest as a command Interest, and extract the public key name
+   *  2. invoke inner validation to verify the signed Interest
+   *  3. classify the command Interest as either initial or subsequent,
+   *     and check the timestamp accordingly
+   *  4. record the timestamp as last timestamp of the public key name
+   *
+   *  The validation request is rejected if any step in this procedure fails.
+   */
+  virtual void
+  checkPolicy(const Interest& interest, int nSteps,
+              const OnInterestValidated& accept,
+              const OnInterestValidationFailed& reject,
+              std::vector<shared_ptr<ValidationRequest>>& nextSteps) override;
+
+  /** \brief validate Data
+   *
+   *  The validation request is redirected to the inner validator.
+   */
+  virtual void
+  checkPolicy(const Data& data, int nSteps,
+              const OnDataValidated& accept,
+              const OnDataValidationFailed& reject,
+              std::vector<shared_ptr<ValidationRequest>>& nextSteps) override;
+
+private:
+  void
+  cleanup();
+
+  ErrorCode
+  parseCommandInterest(const Interest& interest, Name& keyName, uint64_t& timestamp) const;
+
+  ErrorCode
+  checkTimestamp(const Name& keyName, uint64_t timestamp,
+                 time::system_clock::TimePoint receiveTime);
+
+private:
+  unique_ptr<Validator> m_inner;
+  Options m_options;
+
+  struct LastTimestampRecord
+  {
+    Name keyName;
+    uint64_t timestamp;
+    time::steady_clock::TimePoint lastRefreshed;
+  };
+
+  typedef boost::multi_index_container<
+    LastTimestampRecord,
+    boost::multi_index::indexed_by<
+      boost::multi_index::ordered_unique<
+        boost::multi_index::member<LastTimestampRecord, Name, &LastTimestampRecord::keyName>
+      >,
+      boost::multi_index::sequenced<>
+    >
+  > Container;
+  typedef Container::nth_index<0>::type Index;
+  typedef Container::nth_index<1>::type Queue;
+
+  Container m_container;
+  Index& m_index;
+  Queue& m_queue;
+};
+
+std::ostream&
+operator<<(std::ostream& os, CommandInterestValidator::ErrorCode error);
+
+} // namespace security
+} // namespace ndn
+
+
+#endif // NDN_SECURITY_COMMAND_INTEREST_VALIDATOR_HPP