blob: 2bb1706fac1314be28d0c203796b6d2e56bab886 [file] [log] [blame]
Yingdi Yub8f8b342015-04-27 11:06:42 -07001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2/**
Yingdi Yu6ee2d362015-07-16 21:48:05 -07003 * Copyright (c) 2013-2017 Regents of the University of California.
Yingdi Yub8f8b342015-04-27 11:06:42 -07004 *
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
Alexander Afanasyev97709c02016-08-25 19:58:30 -070022#ifndef NDN_SECURITY_PIB_IDENTITY_HPP
23#define NDN_SECURITY_PIB_IDENTITY_HPP
Yingdi Yub8f8b342015-04-27 11:06:42 -070024
25#include "key-container.hpp"
26
27namespace ndn {
28namespace security {
Yingdi Yu6ee2d362015-07-16 21:48:05 -070029namespace pib {
Yingdi Yub8f8b342015-04-27 11:06:42 -070030
Yingdi Yucbe72b02015-11-25 17:35:37 -080031namespace detail {
32class IdentityImpl;
33} // namespace detail
34
Yingdi Yub8f8b342015-04-27 11:06:42 -070035/**
Yingdi Yucbe72b02015-11-25 17:35:37 -080036 * @brief A frontend handle of an Identity
Yingdi Yub8f8b342015-04-27 11:06:42 -070037 *
Yingdi Yu6ee2d362015-07-16 21:48:05 -070038 * Identity is at the top level in PIB's Identity-Key-Certificate hierarchy. An identity has a
39 * Name, and contains zero or more keys, at most one of which is set as the default key of this
40 * identity. Properties of a key can be accessed after obtaining a Key object.
Yingdi Yub8f8b342015-04-27 11:06:42 -070041 */
42class Identity
43{
44public:
Yingdi Yub8f8b342015-04-27 11:06:42 -070045 /**
46 * @brief Default Constructor
47 *
48 * Identity created using this default constructor is just a place holder.
Yingdi Yucbe72b02015-11-25 17:35:37 -080049 * It can obtain an actual instance from Pib::getIdentity(...). A typical
Yingdi Yub8f8b342015-04-27 11:06:42 -070050 * usage would be for exception handling:
51 *
52 * Identity id;
53 * try {
54 * id = pib.getIdentity(...);
55 * }
Yingdi Yu6ee2d362015-07-16 21:48:05 -070056 * catch (const Pib::Error&) {
Yingdi Yub8f8b342015-04-27 11:06:42 -070057 * ...
58 * }
59 *
Yingdi Yu6ee2d362015-07-16 21:48:05 -070060 * An Identity instance created using this constructor is invalid. Calling a
Yingdi Yub8f8b342015-04-27 11:06:42 -070061 * member method on an invalid Identity instance may cause an std::domain_error.
62 */
63 Identity();
64
Yingdi Yu6ee2d362015-07-16 21:48:05 -070065 /**
Yingdi Yucbe72b02015-11-25 17:35:37 -080066 * @brief Create an Identity with a backend implementation @p impl.
Yingdi Yu6ee2d362015-07-16 21:48:05 -070067 *
Yingdi Yucbe72b02015-11-25 17:35:37 -080068 * This method should only be used by IdentityContainer.
Yingdi Yu6ee2d362015-07-16 21:48:05 -070069 */
Yingdi Yucbe72b02015-11-25 17:35:37 -080070 explicit
71 Identity(weak_ptr<detail::IdentityImpl> impl);
Yingdi Yu6ee2d362015-07-16 21:48:05 -070072
Yingdi Yucbe72b02015-11-25 17:35:37 -080073 /**
74 * @brief Get the name of the identity.
75 */
Yingdi Yub8f8b342015-04-27 11:06:42 -070076 const Name&
77 getName() const;
78
79 /**
Yingdi Yucbe72b02015-11-25 17:35:37 -080080 * @brief Get a key with id @p keyName.
81 * @throw std::invalid_argument @p keyName does not match identity
82 * @throw Pib::Error the key does not exist.
Yingdi Yuc8209892015-06-19 17:47:56 -070083 */
84 Key
Yingdi Yu6ee2d362015-07-16 21:48:05 -070085 getKey(const Name& keyName) const;
Yingdi Yuc8209892015-06-19 17:47:56 -070086
Yingdi Yucbe72b02015-11-25 17:35:37 -080087 /**
88 * @brief Get all keys for this identity.
89 */
Yingdi Yuc8209892015-06-19 17:47:56 -070090 const KeyContainer&
91 getKeys() const;
92
93 /**
94 * @brief Get the default key for this Identity.
Yingdi Yucbe72b02015-11-25 17:35:37 -080095 * @throw Pib::Error the default key does not exist.
Yingdi Yuc8209892015-06-19 17:47:56 -070096 */
Yingdi Yucbe72b02015-11-25 17:35:37 -080097 const Key&
Yingdi Yuc8209892015-06-19 17:47:56 -070098 getDefaultKey() const;
99
Yingdi Yucbe72b02015-11-25 17:35:37 -0800100 /*
101 * @return True if the identity instance is valid
102 */
Yingdi Yuc8209892015-06-19 17:47:56 -0700103 operator bool() const;
104
Yingdi Yucbe72b02015-11-25 17:35:37 -0800105 /**
106 * @return True if the identity instance is invalid
107 */
Yingdi Yuc8209892015-06-19 17:47:56 -0700108 bool
109 operator!() const;
110
111NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PRIVATE: // write operations should be private
Yingdi Yuc8209892015-06-19 17:47:56 -0700112 /**
Yingdi Yucbe72b02015-11-25 17:35:37 -0800113 * @brief Add a @p key of @p keyLen bytes (in PKCS#8 format) with @p keyName.
114 * @return the handle of added key
115 * @throw std::invalid_argument key name does not match identity
116 * @throw Pib::Error a key with the same name already exists
Yingdi Yub8f8b342015-04-27 11:06:42 -0700117 */
118 Key
Yingdi Yufe4733a2015-10-22 14:24:12 -0700119 addKey(const uint8_t* key, size_t keyLen, const Name& keyName) const;
Yingdi Yub8f8b342015-04-27 11:06:42 -0700120
121 /**
Yingdi Yu6ee2d362015-07-16 21:48:05 -0700122 * @brief Remove a key with @p keyName
Yingdi Yucbe72b02015-11-25 17:35:37 -0800123 * @throw std::invalid_argument @p keyName does not match identity
Yingdi Yub8f8b342015-04-27 11:06:42 -0700124 */
125 void
Yingdi Yufe4733a2015-10-22 14:24:12 -0700126 removeKey(const Name& keyName) const;
Yingdi Yub8f8b342015-04-27 11:06:42 -0700127
128 /**
Yingdi Yucbe72b02015-11-25 17:35:37 -0800129 * @brief Set an existing key with @p keyName as the default key.
130 * @throw std::invalid_argument @p keyName does not match identity
131 * @throw Pib::Error the key does not exist.
Yingdi Yub8f8b342015-04-27 11:06:42 -0700132 * @return The default key
Yingdi Yub8f8b342015-04-27 11:06:42 -0700133 */
Yingdi Yucbe72b02015-11-25 17:35:37 -0800134 const Key&
Yingdi Yufe4733a2015-10-22 14:24:12 -0700135 setDefaultKey(const Name& keyName) const;
Yingdi Yub8f8b342015-04-27 11:06:42 -0700136
137 /**
Yingdi Yucbe72b02015-11-25 17:35:37 -0800138 * @brief Add a @p key of @p keyLen bytes with @p keyName and set it as the default key
139 * @throw std::invalid_argument @p keyName does not match identity
140 * @throw Pib::Error the key with the same name already exists.
Yingdi Yub8f8b342015-04-27 11:06:42 -0700141 * @return the default key
142 */
Yingdi Yucbe72b02015-11-25 17:35:37 -0800143 const Key&
Yingdi Yufe4733a2015-10-22 14:24:12 -0700144 setDefaultKey(const uint8_t* key, size_t keyLen, const Name& keyName) const;
Yingdi Yub8f8b342015-04-27 11:06:42 -0700145
Yingdi Yucbe72b02015-11-25 17:35:37 -0800146private:
Yingdi Yub8f8b342015-04-27 11:06:42 -0700147 /**
Yingdi Yucbe72b02015-11-25 17:35:37 -0800148 * @brief Check the validity of the instance
149 * @return a shared_ptr when the instance is valid
150 * @throw std::domain_error the instance is invalid
Yingdi Yub8f8b342015-04-27 11:06:42 -0700151 */
Yingdi Yucbe72b02015-11-25 17:35:37 -0800152 shared_ptr<detail::IdentityImpl>
153 lock() const;
Yingdi Yub8f8b342015-04-27 11:06:42 -0700154
Yingdi Yub8f8b342015-04-27 11:06:42 -0700155private:
Yingdi Yucbe72b02015-11-25 17:35:37 -0800156 weak_ptr<detail::IdentityImpl> m_impl;
Yingdi Yufe4733a2015-10-22 14:24:12 -0700157
158 friend class v2::KeyChain;
Yingdi Yub8f8b342015-04-27 11:06:42 -0700159};
160
Yingdi Yu6ee2d362015-07-16 21:48:05 -0700161} // namespace pib
162
163using pib::Identity;
164
Yingdi Yub8f8b342015-04-27 11:06:42 -0700165} // namespace security
166} // namespace ndn
167
Alexander Afanasyev97709c02016-08-25 19:58:30 -0700168#endif // NDN_SECURITY_PIB_IDENTITY_HPP