blob: 53a0ba12031148bef5e4b6c48996e67963bf3700 [file] [log] [blame]
Yingdi Yub8f8b342015-04-27 11:06:42 -07001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2/**
Alexander Afanasyev2fa59392016-07-29 17:24:23 -07003 * Copyright (c) 2013-2016 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_KEY_HPP
23#define NDN_SECURITY_PIB_KEY_HPP
Yingdi Yub8f8b342015-04-27 11:06:42 -070024
Alexander Afanasyev97709c02016-08-25 19:58:30 -070025#include "../v1/identity-certificate.hpp"
Yingdi Yub8f8b342015-04-27 11:06:42 -070026#include "certificate-container.hpp"
27
28namespace ndn {
29namespace security {
30
31class PibImpl;
32class Identity;
33class KeyContainer;
34
35/**
36 * @brief represents a key
37 *
38 * Key is at the second level in PIB's Identity-Key-Certificate hierarchy.
39 * An Key has a Name (identity + keyId), and contains one or more certificates,
40 * one of which is set as the default certificate of this key. A certificate
41 * can be directly accessed from a Key object.
42 *
43 * @throw PibImpl::Error when underlying implementation has non-semantic error.
44 */
45class Key
46{
47public:
48 friend class Identity;
49 friend class KeyContainer;
Yingdi Yuc8209892015-06-19 17:47:56 -070050 friend class KeyChain;
Yingdi Yub8f8b342015-04-27 11:06:42 -070051
52public:
53 /**
54 * @brief Default Constructor
55 *
56 * Key created using this default constructor is just a place holder.
57 * It must obtain an actual instance from Identity::getKey(...). A typical
58 * usage would be for exception handling:
59 *
60 * Key key;
61 * try {
62 * key = Identity.getKey(...);
63 * }
64 * catch (Pib::Error&) {
65 * ...
66 * }
67 *
68 * A Key instance created using the constructor is invalid. Calling a
69 * member method on an invalid Key instance may cause an std::domain_error.
70 */
71 Key();
72
73 /// @brief Get the name of the key.
74 const Name&
75 getName() const;
76
77 /// @brief Get the name of the belonging identity.
78 const Name&
79 getIdentity() const;
80
81 /// @brief Get the key id of the key.
82 const name::Component&
83 getKeyId() const;
84
85 /// @brief Get public key
Alexander Afanasyev2fa59392016-07-29 17:24:23 -070086 const v1::PublicKey&
Yingdi Yub8f8b342015-04-27 11:06:42 -070087 getPublicKey() const;
88
89 /**
Yingdi Yuc8209892015-06-19 17:47:56 -070090 * @brief Get a certificate.
91 *
92 * @return the certificate
93 * @throws Pib::Error if the certificate does not exist.
94 */
Alexander Afanasyev2fa59392016-07-29 17:24:23 -070095 v1::IdentityCertificate
Yingdi Yuc8209892015-06-19 17:47:56 -070096 getCertificate(const Name& certName) const;
97
98 /// @brief Get all the certificates for this key.
99 const CertificateContainer&
100 getCertificates() const;
101
102 /**
103 * @brief Get the default certificate for this Key.
104 *
105 * @throws Pib::Error if the default certificate does not exist.
106 */
Alexander Afanasyev2fa59392016-07-29 17:24:23 -0700107 const v1::IdentityCertificate&
Yingdi Yuc8209892015-06-19 17:47:56 -0700108 getDefaultCertificate() const;
109
110 /// @brief Check if the Key instance is valid
111 operator bool() const;
112
113 /// @brief Check if the Key instance is invalid
114 bool
115 operator!() const;
116
117NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PRIVATE: // write operations should be private
118
119 /**
Yingdi Yub8f8b342015-04-27 11:06:42 -0700120 * @brief Add a certificate.
121 *
122 * @param certificate The certificate to add.
123 */
124 void
Alexander Afanasyev2fa59392016-07-29 17:24:23 -0700125 addCertificate(const v1::IdentityCertificate& certificate);
Yingdi Yub8f8b342015-04-27 11:06:42 -0700126
127 /**
128 * @brief Remove a certificate.
129 *
130 * @param certName The name of the certificate to delete.
131 */
132 void
133 removeCertificate(const Name& certName);
134
135 /**
Yingdi Yub8f8b342015-04-27 11:06:42 -0700136 * @brief Set the default certificate.
137 *
138 * @param certName The name of the default certificate of the key.
139 * @return the default certificate
140 * @throws Pib::Error if the certificate does not exist.
141 */
Alexander Afanasyev2fa59392016-07-29 17:24:23 -0700142 const v1::IdentityCertificate&
Yingdi Yub8f8b342015-04-27 11:06:42 -0700143 setDefaultCertificate(const Name& certName);
144
145 /**
146 * @brief Set the default certificate.
147 *
148 * If the certificate does not exist, add it and set it as the default certificate of the key.
149 * If the certificate exists, simply set it as the default certificate of the key.
150 *
151 * @param certificate The certificate to add.
152 * @return the default certificate
153 */
Alexander Afanasyev2fa59392016-07-29 17:24:23 -0700154 const v1::IdentityCertificate&
155 setDefaultCertificate(const v1::IdentityCertificate& certificate);
Yingdi Yub8f8b342015-04-27 11:06:42 -0700156
Yingdi Yub8f8b342015-04-27 11:06:42 -0700157NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PRIVATE:
158 /**
159 * @brief Create a Key with @p identityName and @p keyId.
160 *
161 * If the key/identity does not exist in the backend, create it in backend.
162 *
163 * @param identityName The name of the Identity.
164 * @param keyId The key id of the key.
165 * @param publicKey The public key to add.
166 * @param impl The actual backend implementation.
167 */
168 Key(const Name& identityName, const name::Component& keyId,
Alexander Afanasyev2fa59392016-07-29 17:24:23 -0700169 const v1::PublicKey& publicKey, shared_ptr<PibImpl> impl);
Yingdi Yub8f8b342015-04-27 11:06:42 -0700170
171 /**
172 * @brief Create an KeyEntry with @p identityName and @p keyId.
173 *
174 * @param identityName The name of the Identity.
175 * @param keyId The key id of the key.
176 * @param impl The actual backend implementation.
177 * @throws Pib::Error if the key does not exist.
178 */
179 Key(const Name& identityName, const name::Component& keyId, shared_ptr<PibImpl> impl);
180
181 /**
182 * @brief Check the validity of this instance
183 *
184 * @throws std::domain_error if the instance is invalid
185 */
186 void
187 validityCheck() const;
188
189private:
190 Name m_id;
191 name::Component m_keyId;
192 Name m_keyName;
Alexander Afanasyev2fa59392016-07-29 17:24:23 -0700193 v1::PublicKey m_key;
Yingdi Yub8f8b342015-04-27 11:06:42 -0700194
Yingdi Yuc8209892015-06-19 17:47:56 -0700195 mutable bool m_hasDefaultCertificate;
Alexander Afanasyev2fa59392016-07-29 17:24:23 -0700196 mutable v1::IdentityCertificate m_defaultCertificate;
Yingdi Yub8f8b342015-04-27 11:06:42 -0700197
Yingdi Yuc8209892015-06-19 17:47:56 -0700198 mutable bool m_needRefreshCerts;
199 mutable CertificateContainer m_certificates;
Yingdi Yub8f8b342015-04-27 11:06:42 -0700200
201 shared_ptr<PibImpl> m_impl;
202};
203
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700204namespace v2 {
205
206/**
207 * @brief Construct key name based on the appropriate naming conventions
208 */
209Name
210constructKeyName(const Name& identity, const name::Component& keyId);
211
212} // namespace v2
213
Yingdi Yub8f8b342015-04-27 11:06:42 -0700214} // namespace security
215} // namespace ndn
216
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700217#endif // NDN_SECURITY_PIB_KEY_HPP