Certificates
-
class Ssl::Certificate
Implemented by SSL adapter to handle certificate operations.
Public Types
Public Functions
-
virtual bool getFingerprint(Fingerprint::Type type, Fingerprint &fingerprint) const = 0
Obtain certificate fingerprint.
- Parameters
type – Which type of fingerprint to return
fingerprint – On success, returned fingerprint
- Returns
bool – true on success, false if fingerprint not available
-
virtual String getName(DN dn, RDN rdn) const = 0
Retrieve an X.509 distinguished name component.
- Parameters
dn – The desired Distinguished Name
rdn – The component to return
- Returns
String – The requested Distinguished Name component
-
size_t printTo(Print &p) const
Debugging print support.
-
virtual bool getFingerprint(Fingerprint::Type type, Fingerprint &fingerprint) const = 0
-
class Ssl::ValidatorList : public Vector<Validator>
Performs certificate validation.
Validators are created in the application’s session initialisation callback. When the certificate has been received, it is checked against each registered validator in turn until successful. All validators are destroyed during this process.
If there are no validators in the list then the certificate will not be checked and the connection accepted.
Public Functions
-
inline bool add(Validator *validator)
Add a validator to the list.
- Parameters
validator – Must be allocated on the heap
-
template<class T>
inline bool pin(const T &fingerprint) Pin a fingerprint.
Creates and adds a fingerprint validator to the list
-
inline bool add(ValidatorCallback callback, void *data = nullptr)
Register a custom validator callback.
- Parameters
callback –
data – User-provided data (optional)
-
bool validate(const Certificate *certificate)
Validate certificate via registered validators.
We only need one match for a successful result, but we free all the validators. This method must be called no more than ONCE.
Note
Called by SSL framework.
- Parameters
certificate – When called with nullptr will free all validators, then fail
- Returns
bool – true on success, false on failure
Public Members
-
Fingerprint::Types fingerprintTypes
Contains a list of registered fingerprint types.
Allows implementations to avoid calculating fingerprint values which are not required, as this is computationally expensive.
-
inline bool add(Validator *validator)
-
class Validator
Base validator class.
Validation is performed by invoking each validator in turn until a successful result is obtained.
Custom validators may either override this class, or use a callback.
Subclassed by Ssl::CallbackValidator, Ssl::FingerprintValidator< FP >
-
union Ssl::Fingerprint
- #include <Fingerprints.h>
Various types of fingerprint.
Applications should use the appropriate type to define a fingerprint, for example:
static const Fingerprint::Cert::Sha1 fingerprint PROGMEM = { ... };
Public Types
-
enum Type
SSL Certificate fingerprint type.
Values:
-
enumerator CertSha1
SHA1 Fingerprint of entire certificate.
-
enumerator CertSha256
SHA256 Fingerprint of entire certificate.
-
enumerator PkiSha256
SHA256 Fingerprint of Public Key Information.
-
enumerator CertSha1
-
union Cert
- #include <Fingerprints.h>
Fingerprints for the entire Certificate.
-
struct Sha1
- #include <Fingerprints.h>
Fingerprint based on the SHA1 value of the certificate.
The SHA1 hash of the entire certificate. This changes on each certificate renewal so needs to be updated every time the remote server updates its certificate.
Advantages: Takes less time to verify than SHA256
Disadvantages: Likely to change periodically
-
struct Sha256
- #include <Fingerprints.h>
Fingerprint based on the SHA256 value of the certificate.
Typically displayed in browser certificate information
Public Static Attributes
-
static constexpr Type type = Type::CertSha256
-
static constexpr Type type = Type::CertSha256
-
struct Sha1
-
union Pki
- #include <Fingerprints.h>
@Fingerprints for the Public Key only
-
struct Sha256
- #include <Fingerprints.h>
Fingerprint based on the SHA256 value of the Public Key Subject in the certificate.
For HTTP public key pinning (RFC7469), the SHA-256 hash of the Subject Public Key Info (which usually only changes when the public key changes) is used.
Advantages: Doesn’t change frequently
Disadvantages: Takes more time (in ms) to verify.
-
struct Sha256
-
enum Type
-
class Ssl::KeyCertPair
Class to manage an SSL key certificate with optional password.
Unnamed Group
-
bool assign(const uint8_t *newKey, unsigned newKeyLength, const uint8_t *newCertificate, unsigned newCertificateLength, const char *newKeyPassword = nullptr)
Create certificate using provided values.
Note
We take a new copy of the certificate
- Parameters
newKey –
newKeyLength –
newCertificate –
newCertificateLength –
newKeyPassword –
- Returns
bool – false on memory allocation failure
Public Functions
-
inline bool assign(const KeyCertPair &keyCert)
Assign another certificate to this structure.
Note
We take a new copy of the certificate
- Parameters
keyCert –
- Returns
bool – false on memory allocation failure
-
bool assign(const uint8_t *newKey, unsigned newKeyLength, const uint8_t *newCertificate, unsigned newCertificateLength, const char *newKeyPassword = nullptr)
-
using Ssl::ValidatorCallback = Delegate<bool(const Certificate *certificate, void *data)>
Validator callback function.
Note
Callback must ALWAYS release any allocated memory before returning. If called with certificate = NULL then just release memory and return false.
- Parameters
ssl – Contains certificate to validate (may be NULL)
data – Data for the callback to use
- Returns
bool – true if validation succeeded