blob: fae035eaaffe4b1afa390f8c6eeb74f7c2adc160 [file] [log] [blame]
Yingdi Yu151b5572015-04-27 11:07:37 -07001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2/**
3 * Copyright (c) 2013-2015 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_PIB_IMPL_HPP
23#define NDN_SECURITY_PIB_IMPL_HPP
24
25#include <set>
26#include "identity-certificate.hpp"
27
28namespace ndn {
29namespace security {
30
31/**
32 * @brief Abstract class of PIB implementation
33 *
34 * This class defines the interface that an actual PIB (e.g., one based on sqlite3)
35 * implementation should provide.
36 */
37class PibImpl
38{
39public:
40 /**
41 * @brief represents a non-semantic error
42 *
43 * A subclass of PibImpl may throw a subclass of this type when
44 * there's a non-semantic error, such as a storage problem.
45 */
46 class Error : public std::runtime_error
47 {
48 public:
49 explicit
50 Error(const std::string& what)
51 : std::runtime_error(what)
52 {
53 }
54 };
55
56public:
57
58 virtual
59 ~PibImpl()
60 {
61 }
62
63public: // TpmLocator management
64
65 /**
66 * @brief Set the corresponding TPM information to @p tpmLocator.
67 *
68 * If the provided @p tpmLocator is different from the existing one, the
69 * content in PIB will be cleaned up, otherwise nothing will be changed.
70 *
71 * @param tmpLocator The name for the new tmpLocator
72 */
73 virtual void
74 setTpmLocator(const std::string& tpmLocator) = 0;
75
76 /**
77 * @brief Get TPM Locator
78 */
79 virtual std::string
80 getTpmLocator() const = 0;
81
82public: // Identity management
83
84 /**
85 * @brief Check the existence of an identity.
86 *
87 * @param identity The name of the identity.
88 * @return true if the identity exists, otherwise false.
89 */
90 virtual bool
91 hasIdentity(const Name& identity) const = 0;
92
93 /**
94 * @brief Add an identity.
95 *
96 * If the identity already exists, do nothing.
Yingdi Yu3bf91f52015-06-12 19:39:40 -070097 * If no default identity has been set, set the added one as default identity.
Yingdi Yu151b5572015-04-27 11:07:37 -070098 *
99 * @param identity The name of the identity to add.
100 */
101 virtual void
102 addIdentity(const Name& identity) = 0;
103
104 /**
105 * @brief Remove an identity
106 *
107 * If the identity does not exist, do nothing.
Yingdi Yu3bf91f52015-06-12 19:39:40 -0700108 * Remove related keys and certificates as well.
Yingdi Yu151b5572015-04-27 11:07:37 -0700109 *
110 * @param identity The name of the identity to remove.
111 */
112 virtual void
113 removeIdentity(const Name& identity) = 0;
114
115 /// @brief Get the name of all the identities
116 virtual std::set<Name>
117 getIdentities() const = 0;
118
119 /**
120 * @brief Set an identity with name @p identityName as the default identity.
121 *
122 * Since adding an identity only requires the identity name, create the
123 * identity if it does not exist.
124 *
125 * @param identityName The name for the default identity.
126 */
127 virtual void
128 setDefaultIdentity(const Name& identityName) = 0;
129
130 /**
131 * @brief Get the default identity.
132 *
133 * @return The name for the default identity.
134 * @throws Pib::Error if no default identity.
135 */
136 virtual Name
137 getDefaultIdentity() const = 0;
138
139public: // Key management
140
141 /**
142 * @brief Check the existence of a key.
143 *
144 * @param identity The name of the belonged identity.
145 * @param keyId The key id component.
146 * @return true if the key exists, otherwise false. Return false if the identity does not exist
147 */
148 virtual bool
149 hasKey(const Name& identity, const name::Component& keyId) const = 0;
150
151 /**
152 * @brief Add a key.
153 *
154 * If the key already exists, do nothing.
155 * If the identity does not exist, add the identity as well.
Yingdi Yu3bf91f52015-06-12 19:39:40 -0700156 * If no default key of the identity has been set, set the added one as default
157 * key of the identity.
Yingdi Yu151b5572015-04-27 11:07:37 -0700158 *
159 * @param identity The name of the belonged identity.
160 * @param keyId The key id component.
161 * @param publicKey The public key bits.
162 */
163 virtual void
164 addKey(const Name& identity, const name::Component& keyId, const PublicKey& publicKey) = 0;
165
166 /**
167 * @brief Remove a key.
168 *
169 * If the key does not exist, do nothing.
Yingdi Yu3bf91f52015-06-12 19:39:40 -0700170 * Remove related certificates as well.
Yingdi Yu151b5572015-04-27 11:07:37 -0700171 *
172 * @param identity The name of the belonged identity.
173 * @param keyId The key id component.
174 */
175 virtual void
176 removeKey(const Name& identity, const name::Component& keyId) = 0;
177
178 /**
179 * @brief Get the key bits of a key.
180 *
181 * @param identity The name of the belonged identity.
182 * @param keyId The key id component.
183 * @return key bits
184 * @throws Pib::Error if the key does not exist.
185 */
186 virtual PublicKey
187 getKeyBits(const Name& identity, const name::Component& keyId) const = 0;
188
189 /**
190 * @brief Get all the key ids of an identity with name @p identity
191 *
192 * The returned key ids can be used to create a KeyContainer.
193 * With key id, identity name, backend implementation, one can create a Key frontend instance.
194 *
195 * @return the key id name component set. If the identity does not exist, return an empty set.
196 */
197 virtual std::set<name::Component>
198 getKeysOfIdentity(const Name& identity) const = 0;
199
200 /**
201 * @brief Set an key with id @p keyId as the default key of an identity with name @p identity.
202 *
203 * @param identity The name of the belonged identity.
204 * @param keyId The key id component.
205 * @throws Pib::Error if the key does not exist.
206 */
207 virtual void
208 setDefaultKeyOfIdentity(const Name& identity, const name::Component& keyId) = 0;
209
210 /**
211 * @brief Get the id of the default key of an identity with name @p identity.
212 *
213 * @param identity The name of the belonged identity.
214 * @throws Pib::Error if no default key or the identity does not exist.
215 */
216 virtual name::Component
217 getDefaultKeyOfIdentity(const Name& identity) const = 0;
218
219public: // Certificate Management
220
221 /**
222 * @brief Check the existence of a certificate with name @p certName.
223 *
224 * @param certName The name of the certificate.
225 * @return true if the certificate exists, otherwise false.
226 */
227 virtual bool
228 hasCertificate(const Name& certName) const = 0;
229
230 /**
231 * @brief Add a certificate.
232 *
233 * If the certificate already exists, do nothing.
234 * If the key or identity do not exist, add them as well.
Yingdi Yu3bf91f52015-06-12 19:39:40 -0700235 * If no default certificate of the key has been set, set the added one as
236 * default certificate of the key.
Yingdi Yu151b5572015-04-27 11:07:37 -0700237 *
238 * @param certificate The certificate to add.
239 */
240 virtual void
241 addCertificate(const IdentityCertificate& certificate) = 0;
242
243 /**
244 * @brief Remove a certificate with name @p certName.
245 *
246 * If the certificate does not exist, do nothing.
247 *
248 * @param certName The name of the certificate.
249 */
250 virtual void
251 removeCertificate(const Name& certName) = 0;
252
253 /**
254 * @brief Get a certificate with name @p certName.
255 *
256 * @param certName The name of the certificate.
257 * @return the certificate.
258 * @throws Pib::Error if the certificate does not exist.
259 */
260 virtual IdentityCertificate
261 getCertificate(const Name& certName) const = 0;
262
263 /**
264 * @brief Get a list of certificate names of a key with id @p keyId of @p identity.
265 *
266 * The returned certificate names can be used to create a CertificateContainer.
267 * With certificate name and backend implementation, one can obtain the certificate directly.
268 *
269 * @param identity The name of the belonging identity.
270 * @param keyId The key id.
271 * @return The certificate name set. If the key does not exist, return an empty set.
272 */
273 virtual std::set<Name>
274 getCertificatesOfKey(const Name& identity, const name::Component& keyId) const = 0;
275
276 /**
277 * @brief Set a cert with name @p certName as the default of a key with id @keyId of @identity.
278 *
279 * @param identity The name of the belonging identity.
280 * @param keyId The key id.
281 * @param certName The name of the certificate.
282 * @throws Pib::Error if the certificate with name @p certName does not exist.
283 */
284 virtual void
285 setDefaultCertificateOfKey(const Name& identity, const name::Component& keyId,
286 const Name& certName) = 0;
287
288 /**
289 * @brief Get the default certificate of a key with id @keyId of @identity.
290 *
291 * @param identity The name of the belonging identity.
292 * @param keyId The key id.
293 * @return a pointer to the certificate, null if no default certificate for the key.
294 * @throws Pib::Error if the default certificate does not exist.
295 */
296 virtual IdentityCertificate
297 getDefaultCertificateOfKey(const Name& identity, const name::Component& keyId) const = 0;
298
299};
300
301} // namespace security
302} // namespace ndn
303
304#endif // NDN_SECURITY_PIB_IMPL_HPP