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