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