blob: 19d377caa3009814f13f5a729a754f2b14b46bac [file] [log] [blame]
Zhiyi Zhangf4bb5c72015-08-19 19:02:51 -07001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2/**
3 * Copyright (c) 2013-2016 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 * @author Zhiyi Zhang <dreamerbarrychang@gmail.com>
22 * @author Yingdi Yu <http://irl.cs.ucla.edu/~yingdi/>
23 */
24
25#ifndef NDN_SECURITY_V2_CERTIFICATE_HPP
26#define NDN_SECURITY_V2_CERTIFICATE_HPP
27
28#include "../../data.hpp"
29
30namespace ndn {
31namespace security {
32namespace v2 {
33
34/**
35 * @brief The certificate following the certificate format naming convention
36 *
37 * Overview of NDN certificate format:
38 *
39 * CertificateV2 ::= DATA-TLV TLV-LENGTH
40 * Name (= /<NameSpace>/KEY/[KeyId]/[IssuerId]/[Version])
41 * MetaInfo (.ContentType = KEY)
42 * Content (= X509PublicKeyContent)
43 * SignatureInfo (= CertificateV2SignatureInfo)
44 * SignatureValue
45 *
46 * X509PublicKeyContent ::= CONTENT-TLV TLV-LENGTH
47 * BYTE+ (= public key bits in PKCS#8 format)
48 *
49 * CertificateV2SignatureInfo ::= SIGNATURE-INFO-TYPE TLV-LENGTH
50 * SignatureType
51 * KeyLocator
52 * ValidityPeriod
53 * ... optional critical or non-critical extension blocks ...
54 *
55 * An example of NDN certificate name:
56 *
57 * /edu/ucla/cs/yingdi/KEY/%03%CD...%F1/%9F%D3...%B7/%FD%d2...%8E
58 * \_________________/ \___________/ \___________/\___________/
59 * Certificate Namespace Key Id Issuer Id Version
60 * (Identity)
61 * \__________________________________/
62 * Key Name
63 *
64 * Notes:
65 *
66 * - `Key Id` is opaque name component to identify an instance of the public key for the
67 * certificate namespace. The value of `Key ID` is controlled by the namespace owner. The
68 * library includes helpers for generation of key IDs using 8-byte random number, SHA-256
69 * digest of the public key, timestamp, and the specified numerical identifiers.
70 *
71 * - `Issuer Id` is opaque name component to identify issuer of the certificate. The value is
72 * controlled by the issuer. The library includes helpers to set issuer ID to a 8-byte
73 * random number, SHA-256 digest of the issuer's public key, and the specified numerical
74 * identifiers.
75 *
76 * - `Key Name` is a logical name of the key used for management pursposes. Key Name includes
77 * the certificate namespace, keyword `KEY`, and `KeyId` components.
78 *
79 * @see doc/specs/certificate-format.rst
80 */
81class Certificate : public Data
82{
83public:
84 Certificate();
85
86 /**
87 * @brief Construct certificate from a data object
88 * @throw tlv::Error if data does not follow certificate format
89 */
90 explicit
91 Certificate(Data&& data);
92
93 /**
94 * @brief Construct certificate from a data object
95 * @throw tlv::Error if data does not follow certificate format
96 */
97 explicit
98 Certificate(const Data& data);
99
100 /**
101 * @brief Construct certificate from a wire encoding
102 * @throw tlv::Error if wire encoding is invalid or does not follow certificate format
103 */
104 explicit
105 Certificate(const Block& block);
106
107 /**
108 * @brief Get key name
109 */
110 Name
111 getKeyName() const;
112
113 /**
114 * @brief Get identity name
115 */
116 Name
117 getIdentity() const;
118
119 /**
120 * @brief Get key ID
121 */
122 name::Component
123 getKeyId() const;
124
125 /**
126 * @brief Get issuer ID
127 */
128 name::Component
129 getIssuerId() const;
130
131 /**
132 * @brief Get public key bits (in PKCS#8 format)
133 * @throw Error If content is empty
134 */
135 const Buffer
136 getPublicKey() const;
137
138 /**
139 * @brief Get validity period of the certificate
140 */
141 ValidityPeriod
142 getValidityPeriod() const;
143
144 /**
145 * @brief Check if the certificate is valid at @p ts.
146 */
147 bool
148 isValid(const time::system_clock::TimePoint& ts = time::system_clock::now()) const;
149
150 /**
151 * @brief Get extension with TLV @p type
152 * @throw ndn::SignatureInfo::Error if the specified block type does not exist
153 */
154 const Block&
155 getExtension(uint32_t type) const;
156
157 // @TODO Implement extension enumeration (Issue #3907)
158public:
159 /**
160 * @brief Check if the specified name follows the naming convention for the certificate
161 */
162 static bool
163 isValidName(const Name& certName);
164
165public:
166 static const ssize_t VERSION_OFFSET;
167 static const ssize_t ISSUER_ID_OFFSET;
168 static const ssize_t KEY_COMPONENT_OFFSET;
169 static const ssize_t KEY_ID_OFFSET;
170 static const size_t MIN_CERT_NAME_LENGTH;
171 static const size_t MIN_KEY_NAME_LENGTH;
172 static const name::Component KEY_COMPONENT;
173};
174
175} // namespace v2
176} // namespace security
177} // namespace ndn
178
179#endif // NDN_SECURITY_V2_CERTIFICATE_HPP