Botan 3.0.0-alpha0
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 * 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 X509_Time
152 * @return notBefore of the certificate
153 */
154 const X509_Time& not_before() const;
155
156 /**
157 * Get the notAfter of the certificate as X509_Time
158 * @return notAfter of the certificate
159 */
160 const X509_Time& not_after() const;
161
162 /**
163 * Get the X509 version of this certificate object.
164 * @return X509 version
165 */
166 uint32_t x509_version() const;
167
168 /**
169 * Get the serial number of this certificate.
170 * @return certificates serial number
171 */
172 const std::vector<uint8_t>& serial_number() const;
173
174 /**
175 * Get the serial number's sign
176 * @return 1 iff the serial is negative.
177 */
178 bool is_serial_negative() const;
179
180 /**
181 * Get the DER encoded AuthorityKeyIdentifier of this certificate.
182 * @return DER encoded AuthorityKeyIdentifier
183 */
184 const std::vector<uint8_t>& authority_key_id() const;
185
186 /**
187 * Get the DER encoded SubjectKeyIdentifier of this certificate.
188 * @return DER encoded SubjectKeyIdentifier
189 */
190 const std::vector<uint8_t>& subject_key_id() const;
191
192 /**
193 * Check whether this certificate is self signed.
194 * If the DN issuer and subject agree,
195 * @return true if this certificate is self signed
196 */
197 bool is_self_signed() const;
198
199 /**
200 * Check whether this certificate is a CA certificate.
201 * @return true if this certificate is a CA certificate
202 */
203 bool is_CA_cert() const;
204
205 /**
206 * Returns true if the specified @param usage is set in the key usage extension
207 * or if no key usage constraints are set at all.
208 * To check if a certain key constraint is set in the certificate
209 * use @see X509_Certificate#has_constraints.
210 */
211 bool allowed_usage(Key_Constraints usage) const;
212
213 /**
214 * Returns true if the specified @param usage is set in the extended key usage extension
215 * or if no extended key usage constraints are set at all.
216 * To check if a certain extended key constraint is set in the certificate
217 * use @see X509_Certificate#has_ex_constraint.
218 */
219 bool allowed_extended_usage(const std::string& usage) const;
220
221 /**
222 * Returns true if the specified usage is set in the extended key usage extension,
223 * or if no extended key usage constraints are set at all.
224 * To check if a certain extended key constraint is set in the certificate
225 * use @see X509_Certificate#has_ex_constraint.
226 */
227 bool allowed_extended_usage(const OID& usage) const;
228
229 /**
230 * Returns true if the required key and extended key constraints are set in the certificate
231 * for the specified @param usage or if no key constraints are set in both the key usage
232 * and extended key usage extension.
233 */
234 bool allowed_usage(Usage_Type usage) const;
235
236 /**
237 * Returns true if the specified @param constraints are included in the key
238 * usage extension.
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(const OID& ex_constraint) const;
247
248 /**
249 * Get the path limit as defined in the BasicConstraints extension of
250 * this certificate.
251 * @return path limit
252 */
253 uint32_t path_limit() const;
254
255 /**
256 * Check whenever a given X509 Extension is marked critical in this
257 * certificate.
258 */
259 bool is_critical(const std::string& ex_name) const;
260
261 /**
262 * Get the key constraints as defined in the KeyUsage extension of this
263 * certificate.
264 * @return key constraints
265 */
266 Key_Constraints constraints() const;
267
268 /**
269 * Get the key usage as defined in the ExtendedKeyUsage extension
270 * of this certificate, or else an empty vector.
271 * @return key usage
272 */
273 const std::vector<OID>& extended_key_usage() const;
274
275 /**
276 * Get the name constraints as defined in the NameConstraints
277 * extension of this certificate.
278 * @return name constraints
279 */
280 const NameConstraints& name_constraints() const;
281
282 /**
283 * Get the policies as defined in the CertificatePolicies extension
284 * of this certificate.
285 * @return certificate policies
286 */
287 const std::vector<OID>& certificate_policy_oids() const;
288
289 /**
290 * Get all extensions of this certificate.
291 * @return certificate extensions
292 */
293 const Extensions& v3_extensions() const;
294
295 /**
296 * Return the v2 issuer key ID. v2 key IDs are almost never used,
297 * instead see v3_subject_key_id.
298 */
299 const std::vector<uint8_t>& v2_issuer_key_id() const;
300
301 /**
302 * Return the v2 subject key ID. v2 key IDs are almost never used,
303 * instead see v3_subject_key_id.
304 */
305 const std::vector<uint8_t>& v2_subject_key_id() const;
306
307 /**
308 * Return the subject alternative names (DNS, IP, ...)
309 */
310 const AlternativeName& subject_alt_name() const;
311
312 /**
313 * Return the issuer alternative names (DNS, IP, ...)
314 */
315 const AlternativeName& issuer_alt_name() const;
316
317 /**
318 * Return the listed address of an OCSP responder, or empty if not set
319 */
320 std::string ocsp_responder() const;
321
322 /**
323 * Return the listed addresses of ca issuers, or empty if not set
324 */
325 std::vector<std::string> ca_issuers() const;
326
327 /**
328 * Return the CRL distribution point, or empty if not set
329 */
330 std::string crl_distribution_point() const;
331
332 /**
333 * @return a free-form string describing the certificate
334 */
335 std::string to_string() const;
336
337 /**
338 * @return a fingerprint of the certificate
339 * @param hash_name hash function used to calculate the fingerprint
340 */
341 std::string fingerprint(const std::string& hash_name = "SHA-1") const;
342
343 /**
344 * Check if a certain DNS name matches up with the information in
345 * the cert
346 * @param name DNS name to match
347 */
348 bool matches_dns_name(const std::string& name) const;
349
350 /**
351 * Check to certificates for equality.
352 * @return true both certificates are (binary) equal
353 */
354 bool operator==(const X509_Certificate& other) const;
355
356 /**
357 * Impose an arbitrary (but consistent) ordering, eg to allow sorting
358 * a container of certificate objects.
359 * @return true if this is less than other by some unspecified criteria
360 */
361 bool operator<(const X509_Certificate& other) const;
362
363 /**
364 * Create a certificate from a data source providing the DER or
365 * PEM encoded certificate.
366 * @param source the data source
367 */
368 explicit X509_Certificate(DataSource& source);
369
370#if defined(BOTAN_TARGET_OS_HAS_FILESYSTEM)
371 /**
372 * Create a certificate from a file containing the DER or PEM
373 * encoded certificate.
374 * @param filename the name of the certificate file
375 */
376 explicit X509_Certificate(const std::string& filename);
377#endif
378
379 /**
380 * Create a certificate from a buffer
381 * @param in the buffer containing the DER-encoded certificate
382 */
383 explicit X509_Certificate(const std::vector<uint8_t>& in);
384
385 /**
386 * Create a certificate from a buffer
387 * @param data the buffer containing the DER-encoded certificate
388 * @param length length of data in bytes
389 */
390 X509_Certificate(const uint8_t data[], size_t length);
391
392 /**
393 * Create an uninitialized certificate object. Any attempts to
394 * access this object will throw an exception.
395 */
396 X509_Certificate() = default;
397
398 X509_Certificate(const X509_Certificate& other) = default;
399
401
402 private:
403 std::string PEM_label() const override;
404
405 std::vector<std::string> alternate_PEM_labels() const override;
406
407 void force_decode() override;
408
409 const X509_Certificate_Data& data() const;
410
411 std::shared_ptr<X509_Certificate_Data> m_data;
412 };
413
414/**
415* Check two certificates for inequality
416* @param cert1 The first certificate
417* @param cert2 The second certificate
418* @return true if the arguments represent different certificates,
419* false if they are binary identical
420*/
421BOTAN_PUBLIC_API(2,0) bool operator!=(const X509_Certificate& cert1, const X509_Certificate& cert2);
422
423}
424
425#endif
Name Constraints.
Definition: pkix_types.h:314
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:13
bool operator<(const OID &a, const OID &b)
Definition: asn1_oid.cpp:130
@ ENCRYPTION
Definition: cipher_mode.h:23
bool operator==(const AlgorithmIdentifier &a1, const AlgorithmIdentifier &a2)
Definition: alg_id.cpp:65
Usage_Type
Definition: x509cert.h:23
std::string to_string(ErrorType type)
Convert an ErrorType to string.
Definition: exceptn.cpp:11
Key_Constraints
Definition: pkix_enums.h:102