blob: 82ea65600037366a0d5770ac29b9cc6032ea2f08 [file] [log] [blame]
Yingdi Yu0b60e7a2015-07-16 21:05:11 -07001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2/**
Yingdi Yufe4733a2015-10-22 14:24:12 -07003 * Copyright (c) 2013-2017 Regents of the University of California.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -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
22#ifndef NDN_SECURITY_TPM_TPM_HPP
23#define NDN_SECURITY_TPM_TPM_HPP
24
25#include "../../common.hpp"
26#include "../security-common.hpp"
27#include "../../name.hpp"
28#include "../key-params.hpp"
29#include "key-handle.hpp"
30#include <unordered_map>
31
32namespace ndn {
33namespace security {
Yingdi Yufe4733a2015-10-22 14:24:12 -070034
35namespace v2 {
36class KeyChain;
37} // namespace v2
38
Yingdi Yu0b60e7a2015-07-16 21:05:11 -070039namespace tpm {
40
41class BackEnd;
42
43/**
44 * @brief represents the front-end of TPM
45 *
46 * The TPM (Trusted Platform Module) stores the private portion of a user's cryptography keys.
47 * The format and location of stored information is indicated by the TpmLocator.
48 * The TPM is designed to work with a PIB (Public Information Base) which stores public keys and
49 * related information such as certificate.
50 *
51 * The TPM also provides functionalities of crypto transformation, such as signing and decryption.
52 *
53 * A TPM consists of a unified front-end interface and a back-end implementation. The front-end
54 * cache the handles of private keys which is provided by the back-end implementation.
55 *
Yingdi Yufe4733a2015-10-22 14:24:12 -070056 * @note Tpm instance is created and managed only by v2::KeyChain. v2::KeyChain::getTpm()
57 * returns a const reference to the managed Tpm instance, through which it is possible to
58 * check existence of private keys, get public keys for the private keys, sign, and decrypt
59 * the supplied buffers using managed private keys.
60 *
61 * @throw BackEnd::Error Failure with the underlying implementation having non-semantic errors
62 * @throw Tpm::Error Failure with semantic error in the underlying implementation
Yingdi Yu0b60e7a2015-07-16 21:05:11 -070063 */
64class Tpm : noncopyable
65{
66public:
Yingdi Yu0b60e7a2015-07-16 21:05:11 -070067 class Error : public std::runtime_error
68 {
69 public:
70 explicit
71 Error(const std::string& what)
72 : std::runtime_error(what)
73 {
74 }
75 };
76
77public:
78 ~Tpm();
79
80 std::string
81 getTpmLocator() const;
82
83 /**
Davide Pesavento92856862017-05-15 21:35:08 -040084 * @brief Check if a private key exists.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -070085 *
86 * @param keyName The key name
87 * @return true if the key exists
88 */
89 bool
90 hasKey(const Name& keyName) const;
91
92 /**
Davide Pesavento92856862017-05-15 21:35:08 -040093 * @return The public portion of an asymmetric key with name @p keyName,
94 * or nullptr if the key does not exist,
Yingdi Yu0b60e7a2015-07-16 21:05:11 -070095 *
Davide Pesavento92856862017-05-15 21:35:08 -040096 * The public key is in PKCS#8 format.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -070097 */
98 ConstBufferPtr
99 getPublicKey(const Name& keyName) const;
100
101 /**
Davide Pesavento92856862017-05-15 21:35:08 -0400102 * @brief Sign blob using the key with name @p keyName and using the digest @p digestAlgorithm.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700103 *
Davide Pesavento92856862017-05-15 21:35:08 -0400104 * @return The signature, or nullptr if the key does not exist.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700105 */
106 ConstBufferPtr
107 sign(const uint8_t* buf, size_t size, const Name& keyName, DigestAlgorithm digestAlgorithm) const;
108
109 /**
Davide Pesavento92856862017-05-15 21:35:08 -0400110 * @brief Decrypt blob using the key with name @p keyName.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700111 *
Davide Pesavento92856862017-05-15 21:35:08 -0400112 * @return The decrypted data, or nullptr if the key does not exist.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700113 */
114 ConstBufferPtr
115 decrypt(const uint8_t* buf, size_t size, const Name& keyName) const;
116
Yingdi Yufe4733a2015-10-22 14:24:12 -0700117public: // Management
118 /**
Davide Pesavento92856862017-05-15 21:35:08 -0400119 * @brief Check if the TPM is in terminal mode.
Yingdi Yufe4733a2015-10-22 14:24:12 -0700120 */
121 bool
122 isTerminalMode() const;
123
124 /**
Davide Pesavento92856862017-05-15 21:35:08 -0400125 * @brief Set the terminal mode of the TPM.
Yingdi Yufe4733a2015-10-22 14:24:12 -0700126 *
Davide Pesavento92856862017-05-15 21:35:08 -0400127 * When in terminal mode, the TPM will not ask user permission from GUI.
Yingdi Yufe4733a2015-10-22 14:24:12 -0700128 */
129 void
130 setTerminalMode(bool isTerminal) const;
131
132 /**
Davide Pesavento92856862017-05-15 21:35:08 -0400133 * @return true if the TPM is locked, otherwise false.
Yingdi Yufe4733a2015-10-22 14:24:12 -0700134 */
135 bool
136 isTpmLocked() const;
137
138 /**
Davide Pesavento92856862017-05-15 21:35:08 -0400139 * @brief Unlock the TPM.
Yingdi Yufe4733a2015-10-22 14:24:12 -0700140 *
Davide Pesavento92856862017-05-15 21:35:08 -0400141 * @param password The password to unlock the TPM.
Yingdi Yufe4733a2015-10-22 14:24:12 -0700142 * @param passwordLength The password size.
143 */
144 bool
145 unlockTpm(const char* password, size_t passwordLength) const;
146
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700147NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PRIVATE:
148 /*
Davide Pesavento92856862017-05-15 21:35:08 -0400149 * @brief Create a new TPM instance with the specified @p location.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700150 *
151 * @param scheme The scheme for the TPM
152 * @param location The location for the TPM
153 * @param impl The back-end implementation
154 */
155 Tpm(const std::string& scheme, const std::string& location, unique_ptr<BackEnd> impl);
156
157 BackEnd*
158 getBackEnd()
159 {
160 return m_backEnd.get();
161 }
162
163 /**
164 * @brief Create key for @p identityName according to @p params.
165 *
166 * The created key is named as: /<identityName>/[keyId]/KEY
167 *
Davide Pesavento92856862017-05-15 21:35:08 -0400168 * @return The key name.
169 * @throw Tpm::Error the key already exists or @p params is invalid.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700170 */
171 Name
172 createKey(const Name& identityName, const KeyParams& params);
173
174 /**
175 * @brief Delete a key pair with name @p keyName.
176 */
177 void
178 deleteKey(const Name& keyName);
179
180 /**
Davide Pesavento92856862017-05-15 21:35:08 -0400181 * @brief Export a private key.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700182 *
Davide Pesavento92856862017-05-15 21:35:08 -0400183 * Export a private key in encrypted PKCS #8 format.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700184 *
Davide Pesavento92856862017-05-15 21:35:08 -0400185 * @param keyName The private key name
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700186 * @param pw The password to encrypt the private key
187 * @param pwLen The length of the password
Davide Pesavento92856862017-05-15 21:35:08 -0400188 * @return The encoded private key wrapper.
189 * @throw BackEnd::Error the key does not exist or it cannot be exported.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700190 */
191 ConstBufferPtr
192 exportPrivateKey(const Name& keyName, const char* pw, size_t pwLen);
193
194 /**
Davide Pesavento92856862017-05-15 21:35:08 -0400195 * @brief Import a private key.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700196 *
197 * @param keyName The private key name
198 * @param pkcs8 The private key wrapper
199 * @param pkcs8Len The length of the private key wrapper
200 * @param pw The password to encrypt the private key
201 * @param pwLen The length of the password
Davide Pesavento92856862017-05-15 21:35:08 -0400202 * @return true if the operation is successful, false otherwise.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700203 */
204 bool
Davide Pesavento92856862017-05-15 21:35:08 -0400205 importPrivateKey(const Name& keyName, const uint8_t* pkcs8, size_t pkcs8Len,
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700206 const char* pw, size_t pwLen);
207
208 /**
Davide Pesavento92856862017-05-15 21:35:08 -0400209 * @brief Clear the key cache.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700210 *
211 * An empty cache can force Tpm to do key lookup in back-end.
212 */
213 void
214 clearKeyCache()
215 {
216 m_keys.clear();
217 }
218
219private:
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700220 /**
Davide Pesavento92856862017-05-15 21:35:08 -0400221 * @brief Internal KeyHandle lookup.
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700222 *
223 * @return A pointer to the handle of key @p keyName if it exists, otherwise nullptr.
224 */
225 const KeyHandle*
226 findKey(const Name& keyName) const;
227
228private:
229 std::string m_scheme;
230 std::string m_location;
231
232 mutable std::unordered_map<Name, unique_ptr<KeyHandle>> m_keys;
233
234 unique_ptr<BackEnd> m_backEnd;
Yingdi Yufe4733a2015-10-22 14:24:12 -0700235
236 friend class v2::KeyChain;
Yingdi Yu0b60e7a2015-07-16 21:05:11 -0700237};
238
239} // namespace tpm
240
241using tpm::Tpm;
242
243} // namespace security
244} // namespace ndn
245
246#endif // NDN_SECURITY_TPM_TPM_HPP