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