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