Coverage Report

Created: 2021-02-21 07:20

/src/botan/build/include/botan/x509cert.h
Line
Count
Source (jump to first uncovered line)
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
25
   TLS_SERVER_AUTH,
26
   TLS_CLIENT_AUTH,
27
   CERTIFICATE_AUTHORITY,
28
   OCSP_RESPONDER,
29
   ENCRYPTION
30
   };
31
32
struct X509_Certificate_Data;
33
34
/**
35
* This class represents an X.509 Certificate
36
*/
37
class BOTAN_PUBLIC_API(2,0) X509_Certificate : public X509_Object
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
94.1k
      X509_Certificate(const X509_Certificate& other) = default;
399
400
0
      X509_Certificate& operator=(const X509_Certificate& other) = default;
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
*/
421
BOTAN_PUBLIC_API(2,0) bool operator!=(const X509_Certificate& cert1, const X509_Certificate& cert2);
422
423
}
424
425
#endif