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