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