Botan 2.13.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

x509cert.h
Go to the documentation of this file.
1 /*
2 * X.509 Certificates
3 * (C) 1999-2007,2015,2017 Jack Lloyd
4 *
5 * Botan is released under the Simplified BSD License (see license.txt)
6 */
7
8 #ifndef BOTAN_X509_CERTS_H_
9 #define BOTAN_X509_CERTS_H_
10
11 #include <botan/x509_obj.h>
12 #include <botan/x509_key.h>
13 #include <botan/asn1_time.h>
14 #include <botan/key_constraint.h>
15 #include <botan/name_constraint.h>
16 #include <memory>
17
18 namespace Botan {
19
20 class Public_Key;
21 class X509_DN;
22 class AlternativeName;
23 class Extensions;
24
25 enum class Usage_Type
26 {
27 UNSPECIFIED, // no restrictions
28 TLS_SERVER_AUTH,
29 TLS_CLIENT_AUTH,
30 CERTIFICATE_AUTHORITY,
31 OCSP_RESPONDER,
32 ENCRYPTION
33 };
34
35 struct X509_Certificate_Data;
36
37 /**
38 * This class represents an X.509 Certificate
39 */
40 class BOTAN_PUBLIC_API(2,0) X509_Certificate : public X509_Object
41 {
42 public:
43 /**
44 * Return a newly allocated copy of the public key associated
45 * with the subject of this certificate. This object is owned
46 * by the caller.
47 *
48 * @return public key
49 */
50 Public_Key* subject_public_key() const
51 {
52 return load_subject_public_key().release();
53 }
54
55 /**
56 * Create a public key object associated with the public key bits in this
57 * certificate. If the public key bits was valid for X.509 encoding
58 * purposes but invalid algorithmically (for example, RSA with an even
59 * modulus) that will be detected at this point, and an exception will be
60 * thrown.
61 *
62 * @return subject public key of this certificate
63 */
64 std::unique_ptr<Public_Key> load_subject_public_key() const;
65
66 /**
67 * Get the public key associated with this certificate. This includes the
68 * outer AlgorithmIdentifier
69 * @return subject public key of this certificate
70 */
71 const std::vector<uint8_t>& subject_public_key_bits() const;
72
73 /**
74 * Get the SubjectPublicKeyInfo associated with this certificate.
75 * @return subject public key info of this certificate
76 */
77 const std::vector<uint8_t>& subject_public_key_info() const;
78
79 /**
80 * Return the algorithm identifier of the public key
81 */
82 const AlgorithmIdentifier& subject_public_key_algo() const;
83
84 /**
85 * Get the bit string of the public key associated with this certificate
86 * @return public key bits
87 */
88 const std::vector<uint8_t>& subject_public_key_bitstring() const;
89
90 /**
91 * Get the SHA-1 bit string of the public key associated with this certificate.
92 * This is used for OCSP among other protocols.
93 * This function will throw if SHA-1 is not available.
94 * @return hash of subject public key of this certificate
95 */
96 const std::vector<uint8_t>& subject_public_key_bitstring_sha1() const;
97
98 /**
99 * Get the certificate's issuer distinguished name (DN).
100 * @return issuer DN of this certificate
101 */
102 const X509_DN& issuer_dn() const;
103
104 /**
105 * Get the certificate's subject distinguished name (DN).
106 * @return subject DN of this certificate
107 */
108 const X509_DN& subject_dn() const;
109
110 /**
111 * Get a value for a specific subject_info parameter name.
112 * @param name the name of the parameter to look up. Possible names include
113 * "X509.Certificate.version", "X509.Certificate.serial",
114 * "X509.Certificate.start", "X509.Certificate.end",
115 * "X509.Certificate.v2.key_id", "X509.Certificate.public_key",
116 * "X509v3.BasicConstraints.path_constraint",
117 * "X509v3.BasicConstraints.is_ca", "X509v3.NameConstraints",
118 * "X509v3.ExtendedKeyUsage", "X509v3.CertificatePolicies",
119 * "X509v3.SubjectKeyIdentifier", "X509.Certificate.serial",
120 * "X520.CommonName", "X520.Organization", "X520.Country",
121 * "RFC822" (Email in SAN) or "PKCS9.EmailAddress" (Email in DN).
122 * @return value(s) of the specified parameter
123 */
124 std::vector<std::string> subject_info(const std::string& name) const;
125
126 /**
127 * Get a value for a specific subject_info parameter name.
128 * @param name the name of the parameter to look up. Possible names are
129 * "X509.Certificate.v2.key_id" or "X509v3.AuthorityKeyIdentifier".
130 * @return value(s) of the specified parameter
131 */
132 std::vector<std::string> issuer_info(const std::string& name) const;
133
134 /**
135 * Raw issuer DN bits
136 */
137 const std::vector<uint8_t>& raw_issuer_dn() const;
138
139 /**
140 * SHA-256 of Raw issuer DN
141 */
142 std::vector<uint8_t> raw_issuer_dn_sha256() const;
143
144 /**
145 * Raw subject DN
146 */
147 const std::vector<uint8_t>& raw_subject_dn() const;
148
149 /**
150 * SHA-256 of Raw subject DN
151 */
152 std::vector<uint8_t> raw_subject_dn_sha256() const;
153
154 /**
155 * Get the notBefore of the certificate as a string
156 * @return notBefore of the certificate
157 */
158 std::string BOTAN_DEPRECATED("Use not_before().to_string()") start_time() const
159 {
160 return not_before().to_string();
161 }
162
163 /**
164 * Get the notAfter of the certificate as a string
165 * @return notAfter of the certificate
166 */
167 std::string BOTAN_DEPRECATED("Use not_after().to_string()") end_time() const
168 {
169 return not_after().to_string();
170 }
171
172 /**
173 * Get the notBefore of the certificate as X509_Time
174 * @return notBefore of the certificate
175 */
176 const X509_Time& not_before() const;
177
178 /**
179 * Get the notAfter of the certificate as X509_Time
180 * @return notAfter of the certificate
181 */
182 const X509_Time& not_after() const;
183
184 /**
185 * Get the X509 version of this certificate object.
186 * @return X509 version
187 */
188 uint32_t x509_version() const;
189
190 /**
191 * Get the serial number of this certificate.
192 * @return certificates serial number
193 */
194 const std::vector<uint8_t>& serial_number() const;
195
196 /**
197 * Get the serial number's sign
198 * @return 1 iff the serial is negative.
199 */
200 bool is_serial_negative() const;
201
202 /**
203 * Get the DER encoded AuthorityKeyIdentifier of this certificate.
204 * @return DER encoded AuthorityKeyIdentifier
205 */
206 const std::vector<uint8_t>& authority_key_id() const;
207
208 /**
209 * Get the DER encoded SubjectKeyIdentifier of this certificate.
210 * @return DER encoded SubjectKeyIdentifier
211 */
212 const std::vector<uint8_t>& subject_key_id() const;
213
214 /**
215 * Check whether this certificate is self signed.
216 * If the DN issuer and subject agree,
217 * @return true if this certificate is self signed
218 */
219 bool is_self_signed() const;
220
221 /**
222 * Check whether this certificate is a CA certificate.
223 * @return true if this certificate is a CA certificate
224 */
225 bool is_CA_cert() const;
226
227 /**
228 * Returns true if the specified @param usage is set in the key usage extension
229 * or if no key usage constraints are set at all.
230 * To check if a certain key constraint is set in the certificate
231 * use @see X509_Certificate#has_constraints.
232 */
233 bool allowed_usage(Key_Constraints usage) const;
234
235 /**
236 * Returns true if the specified @param usage is set in the extended key usage extension
237 * or if no extended key usage constraints are set at all.
238 * To check if a certain extended key constraint is set in the certificate
239 * use @see X509_Certificate#has_ex_constraint.
240 */
241 bool allowed_extended_usage(const std::string& usage) const;
242
243 /**
244 * Returns true if the specified usage is set in the extended key usage extension,
245 * or if no extended key usage constraints are set at all.
246 * To check if a certain extended key constraint is set in the certificate
247 * use @see X509_Certificate#has_ex_constraint.
248 */
249 bool allowed_extended_usage(const OID& usage) const;
250
251 /**
252 * Returns true if the required key and extended key constraints are set in the certificate
253 * for the specified @param usage or if no key constraints are set in both the key usage
254 * and extended key usage extension.
255 */
256 bool allowed_usage(Usage_Type usage) const;
257
258 /**
259 * Returns true if the specified @param constraints are included in the key
260 * usage extension.
261 */
262 bool has_constraints(Key_Constraints constraints) const;
263
264 /**
265 * Returns true if and only if @param ex_constraint (referring to an
266 * extended key constraint, eg "PKIX.ServerAuth") is included in the
267 * extended key extension.
268 */
269 bool BOTAN_DEPRECATED("Use version taking an OID")
270 has_ex_constraint(const std::string& ex_constraint) const;
271
272 /**
273 * Returns true if and only if OID @param ex_constraint is
274 * included in the extended key extension.
275 */
276 bool has_ex_constraint(const OID& ex_constraint) const;
277
278 /**
279 * Get the path limit as defined in the BasicConstraints extension of
280 * this certificate.
281 * @return path limit
282 */
283 uint32_t path_limit() const;
284
285 /**
286 * Check whenever a given X509 Extension is marked critical in this
287 * certificate.
288 */
289 bool is_critical(const std::string& ex_name) const;
290
291 /**
292 * Get the key constraints as defined in the KeyUsage extension of this
293 * certificate.
294 * @return key constraints
295 */
296 Key_Constraints constraints() const;
297
298 /**
299 * Get the key constraints as defined in the ExtendedKeyUsage
300 * extension of this certificate.
301 * @return key constraints
302 */
303 std::vector<std::string>
304 BOTAN_DEPRECATED("Use extended_key_usage") ex_constraints() const;
305
306 /**
307 * Get the key usage as defined in the ExtendedKeyUsage extension
308 * of this certificate, or else an empty vector.
309 * @return key usage
310 */
311 const std::vector<OID>& extended_key_usage() const;
312
313 /**
314 * Get the name constraints as defined in the NameConstraints
315 * extension of this certificate.
316 * @return name constraints
317 */
318 const NameConstraints& name_constraints() const;
319
320 /**
321 * Get the policies as defined in the CertificatePolicies extension
322 * of this certificate.
323 * @return certificate policies
324 */
325 std::vector<std::string> BOTAN_DEPRECATED("Use certificate_policy_oids") policies() const;
326
327 const std::vector<OID>& certificate_policy_oids() const;
328
329 /**
330 * Get all extensions of this certificate.
331 * @return certificate extensions
332 */
333 const Extensions& v3_extensions() const;
334
335 /**
336 * Return the v2 issuer key ID. v2 key IDs are almost never used,
337 * instead see v3_subject_key_id.
338 */
339 const std::vector<uint8_t>& v2_issuer_key_id() const;
340
341 /**
342 * Return the v2 subject key ID. v2 key IDs are almost never used,
343 * instead see v3_subject_key_id.
344 */
345 const std::vector<uint8_t>& v2_subject_key_id() const;
346
347 /**
348 * Return the subject alternative names (DNS, IP, ...)
349 */
350 const AlternativeName& subject_alt_name() const;
351
352 /**
353 * Return the issuer alternative names (DNS, IP, ...)
354 */
355 const AlternativeName& issuer_alt_name() const;
356
357 /**
358 * Return the listed address of an OCSP responder, or empty if not set
359 */
360 std::string ocsp_responder() const;
361
362 /**
363 * Return the listed addresses of ca issuers, or empty if not set
364 */
365 std::vector<std::string> ca_issuers() const;
366
367 /**
368 * Return the CRL distribution point, or empty if not set
369 */
370 std::string crl_distribution_point() const;
371
372 /**
373 * @return a free-form string describing the certificate
374 */
375 std::string to_string() const;
376
377 /**
378 * @return a fingerprint of the certificate
379 * @param hash_name hash function used to calculate the fingerprint
380 */
381 std::string fingerprint(const std::string& hash_name = "SHA-1") const;
382
383 /**
384 * Check if a certain DNS name matches up with the information in
385 * the cert
386 * @param name DNS name to match
387 */
388 bool matches_dns_name(const std::string& name) const;
389
390 /**
391 * Check to certificates for equality.
392 * @return true both certificates are (binary) equal
393 */
394 bool operator==(const X509_Certificate& other) const;
395
396 /**
397 * Impose an arbitrary (but consistent) ordering, eg to allow sorting
398 * a container of certificate objects.
399 * @return true if this is less than other by some unspecified criteria
400 */
401 bool operator<(const X509_Certificate& other) const;
402
403 /**
404 * Create a certificate from a data source providing the DER or
405 * PEM encoded certificate.
406 * @param source the data source
407 */
408 explicit X509_Certificate(DataSource& source);
409
410 #if defined(BOTAN_TARGET_OS_HAS_FILESYSTEM)
411 /**
412 * Create a certificate from a file containing the DER or PEM
413 * encoded certificate.
414 * @param filename the name of the certificate file
415 */
416 explicit X509_Certificate(const std::string& filename);
417 #endif
418
419 /**
420 * Create a certificate from a buffer
421 * @param in the buffer containing the DER-encoded certificate
422 */
423 explicit X509_Certificate(const std::vector<uint8_t>& in);
424
425 /**
426 * Create a certificate from a buffer
427 * @param data the buffer containing the DER-encoded certificate
428 * @param length length of data in bytes
429 */
430 X509_Certificate(const uint8_t data[], size_t length);
431
432 /**
433 * Create an uninitialized certificate object. Any attempts to
434 * access this object will throw an exception.
435 */
436 X509_Certificate() = default;
437
438 X509_Certificate(const X509_Certificate& other) = default;
439
440 X509_Certificate& operator=(const X509_Certificate& other) = default;
441
442 private:
443 std::string PEM_label() const override;
444
445 std::vector<std::string> alternate_PEM_labels() const override;
446
447 void force_decode() override;
448
449 const X509_Certificate_Data& data() const;
450
451 std::shared_ptr<X509_Certificate_Data> m_data;
452 };
453
454 /**
455 * Check two certificates for inequality
456 * @param cert1 The first certificate
457 * @param cert2 The second certificate
458 * @return true if the arguments represent different certificates,
459 * false if they are binary identical
460 */
461 BOTAN_PUBLIC_API(2,0) bool operator!=(const X509_Certificate& cert1, const X509_Certificate& cert2);
462
463 }
464
465 #endif
BOTAN_PUBLIC_API
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
std
Definition: bigint.h:1135
Botan::Extensions
Definition: x509_ext.h:90
Botan::DataSource
Definition: data_src.h:21
Botan::to_string
std::string to_string(ErrorType type)
Convert an ErrorType to string.
Definition: exceptn.cpp:11
Botan::Usage_Type::CERTIFICATE_AUTHORITY
Botan::X509_Certificate::subject_public_key
Public_Key * subject_public_key() const
Definition: x509cert.h:50
name
std::string name
Definition: commoncrypto_hash.cpp:23
Botan::X509_Certificate
Definition: x509cert.h:40
Botan::Usage_Type::TLS_CLIENT_AUTH
Botan::X509_Object
Definition: x509_obj.h:26
Botan::Usage_Type::ENCRYPTION
Botan::X509_DN
Definition: x509_dn.h:24
Botan
Definition: alg_id.cpp:13
Botan::Public_Key
Definition: pk_keys.h:29
Botan::Usage_Type::TLS_SERVER_AUTH
Botan::Usage_Type::OCSP_RESPONDER
Botan::Usage_Type::UNSPECIFIED
Botan::AlgorithmIdentifier
Definition: alg_id.h:21
Botan::OID
Definition: asn1_oid.h:20
Botan::Key_Constraints
Key_Constraints
Definition: key_constraint.h:21
Botan::X509_Time
Definition: asn1_time.h:19
Botan::Usage_Type
Usage_Type
Definition: x509cert.h:25
Botan::AlternativeName
Definition: asn1_alt_name.h:21
Botan::NameConstraints
Name Constraints.
Definition: name_constraint.h:147