Botan 3.5.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
22enum class Usage_Type {
23 UNSPECIFIED, // no restrictions
29};
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 */
76 const AlgorithmIdentifier& subject_public_key_algo() const;
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 */
240 bool has_constraints(Key_Constraints constraints) const;
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 limit as defined in the BasicConstraints extension of
256 * this certificate.
257 * @return path limit
258 */
259 uint32_t path_limit() const;
260
261 /**
262 * Check whenever a given X509 Extension is marked critical in this
263 * certificate.
264 */
265 bool is_critical(std::string_view ex_name) const;
266
267 /**
268 * Get the key constraints as defined in the KeyUsage extension of this
269 * certificate.
270 * @return key constraints
271 */
272 Key_Constraints constraints() const;
273
274 /**
275 * Get the key usage as defined in the ExtendedKeyUsage extension
276 * of this certificate, or else an empty vector.
277 * @return key usage
278 */
279 const std::vector<OID>& extended_key_usage() const;
280
281 /**
282 * Get the name constraints as defined in the NameConstraints
283 * extension of this certificate.
284 * @return name constraints
285 */
286 const NameConstraints& name_constraints() const;
287
288 /**
289 * Get the policies as defined in the CertificatePolicies extension
290 * of this certificate.
291 * @return certificate policies
292 */
293 const std::vector<OID>& certificate_policy_oids() const;
294
295 /**
296 * Get all extensions of this certificate.
297 * @return certificate extensions
298 */
299 const Extensions& v3_extensions() const;
300
301 /**
302 * Return the v2 issuer key ID. v2 key IDs are almost never used,
303 * instead see v3_subject_key_id.
304 */
305 const std::vector<uint8_t>& v2_issuer_key_id() const;
306
307 /**
308 * Return the v2 subject key ID. v2 key IDs are almost never used,
309 * instead see v3_subject_key_id.
310 */
311 const std::vector<uint8_t>& v2_subject_key_id() const;
312
313 /**
314 * Return the subject alternative names (DNS, IP, ...)
315 */
316 const AlternativeName& subject_alt_name() const;
317
318 /**
319 * Return the issuer alternative names (DNS, IP, ...)
320 */
321 const AlternativeName& issuer_alt_name() const;
322
323 /**
324 * Return the listed address of an OCSP responder, or empty if not set
325 */
326 std::string ocsp_responder() const;
327
328 /**
329 * Return the listed addresses of ca issuers, or empty if not set
330 */
331 std::vector<std::string> ca_issuers() const;
332
333 /**
334 * Return the CRL distribution point, or empty if not set
335 */
336 BOTAN_DEPRECATED("Use crl_distribution_points") std::string crl_distribution_point() const;
337
338 /**
339 * Return the CRL distribution points, or empty if not set
340 */
341 std::vector<std::string> crl_distribution_points() const;
342
343 /**
344 * @return a free-form string describing the certificate
345 */
346 std::string to_string() const;
347
348 /**
349 * @return a fingerprint of the certificate
350 * @param hash_name hash function used to calculate the fingerprint
351 */
352 std::string fingerprint(std::string_view hash_name = "SHA-1") const;
353
354 /**
355 * Check if a certain DNS name matches up with the information in
356 * the cert
357 * @param name DNS name to match
358 *
359 * Note: this will also accept a dotted quad input, in which case
360 * the SAN for IPv4 addresses will be checked.
361 */
362 bool matches_dns_name(std::string_view name) const;
363
364 /**
365 * Check to certificates for equality.
366 * @return true both certificates are (binary) equal
367 */
368 bool operator==(const X509_Certificate& other) const;
369
370 /**
371 * Impose an arbitrary (but consistent) ordering, eg to allow sorting
372 * a container of certificate objects.
373 * @return true if this is less than other by some unspecified criteria
374 */
375 bool operator<(const X509_Certificate& other) const;
376
377 /**
378 * Create a certificate from a data source providing the DER or
379 * PEM encoded certificate.
380 * @param source the data source
381 */
382 explicit X509_Certificate(DataSource& source);
383
384#if defined(BOTAN_TARGET_OS_HAS_FILESYSTEM)
385 /**
386 * Create a certificate from a file containing the DER or PEM
387 * encoded certificate.
388 * @param filename the name of the certificate file
389 */
390 explicit X509_Certificate(std::string_view filename);
391#endif
392
393 /**
394 * Create a certificate from a buffer
395 * @param in the buffer containing the DER-encoded certificate
396 */
397 explicit X509_Certificate(const std::vector<uint8_t>& in);
398
399 /**
400 * Create a certificate from a buffer
401 * @param data the buffer containing the DER-encoded certificate
402 * @param length length of data in bytes
403 */
404 X509_Certificate(const uint8_t data[], size_t length);
405
406 /**
407 * Create an uninitialized certificate object. Any attempts to
408 * access this object will throw an exception.
409 */
410 X509_Certificate() = default;
411
412 X509_Certificate(const X509_Certificate& other) = default;
413
415
416 private:
417 std::string PEM_label() const override;
418
419 std::vector<std::string> alternate_PEM_labels() const override;
420
421 void force_decode() override;
422
423 const X509_Certificate_Data& data() const;
424
425 std::shared_ptr<X509_Certificate_Data> m_data;
426};
427
428/**
429* Check two certificates for inequality
430* @param cert1 The first certificate
431* @param cert2 The second certificate
432* @return true if the arguments represent different certificates,
433* false if they are binary identical
434*/
435BOTAN_PUBLIC_API(2, 0) bool operator!=(const X509_Certificate& cert1, const X509_Certificate& cert2);
436
437} // namespace Botan
438
439#endif
Name Constraints.
Definition pkix_types.h:358
X509_Certificate(const X509_Certificate &other)=default
X509_Certificate & operator=(const X509_Certificate &other)=default
std::string name
#define BOTAN_PUBLIC_API(maj, min)
Definition compiler.h:31
#define BOTAN_DEPRECATED(msg)
Definition compiler.h:125
bool operator<(const OID &a, const OID &b)
Definition asn1_oid.cpp:158
bool operator==(const AlgorithmIdentifier &a1, const AlgorithmIdentifier &a2)
Definition alg_id.cpp:54
Usage_Type
Definition x509cert.h:22