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