Certificates

class Certificate

Implemented by SSL adapter to handle certificate operations.

Public Types

enum DN

Distinguished Name type.

Values:

ISSUER

SUBJECT

enum RDN

Relative Distinguished Name type identifying a name component.

Values:

XX

MAX

Public Functions

virtual ~Certificate()

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

Return Value

• 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

Return Value

• String: The requested Distinguished Name component

size_t printTo(Print &p) const

Debugging print support.

class 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 Types

template<>
typedef int (*Comparer)(const Validator &lhs, const Validator &rhs)

Public Functions

bool add(Validator *validator)

Add a validator to the list.

Parameters

• validator: Must be allocated on the heap

template <class T>
bool pin(const T &fingerprint)

Pin a fingerprint.

Creates and adds a fingerprint validator to the list

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

Return Value

• bool: true on success, false on failure

unsigned int capacity() const

bool contains(const Validator &elem) const

const Validator &firstElement() const

int indexOf(const Validator &elem) const

bool isEmpty() const

const Validator &lastElement() const

int lastIndexOf(const Validator &elem) const

unsigned int count() const

unsigned int size() const

void copyInto(Validator *array) const

bool add(const Validator &obj)

bool addElement(const Validator &obj)

bool addElement(Validator *objp)

void clear()

bool ensureCapacity(unsigned int minCapacity)

void removeAllElements()

bool removeElement(const Validator &obj)

bool setSize(unsigned int newSize)

void trimToSize()

const Validator &elementAt(unsigned int index) const

bool insertElementAt(const Validator &obj, unsigned int index)

const void remove(unsigned int index)

void removeElementAt(unsigned int index)

bool setElementAt(const Validator &obj, unsigned int index)

const Validator &get(unsigned int index) const

const Validator &operator[](unsigned int index) const

Validator &operator[](unsigned int index)

void sort(Comparer compareFunction)

const Validator &at(unsigned int i) const

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.

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 >

Public Functions

virtual ~Validator()

virtual bool validate(const Certificate &certificate) = 0

union 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:

CertSha1

SHA1 Fingerprint of entire certificate.

CertSha256

SHA256 Fingerprint of entire certificate.

PkiSha256

SHA256 Fingerprint of Public Key Information.

Public Members

Cert cert

Pki pki

union Cert

#include <Fingerprints.h>

Fingerprints for the entire Certificate.

Public Members

Sha1 sha1

Sha256 sha256

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

Public Members

Crypto::Sha1::Hash hash

Public Static Attributes

constexpr Type type = Type::CertSha1

struct Sha256

#include <Fingerprints.h>

Fingerprint based on the SHA256 value of the certificate.

Typically displayed in browser certificate information

Public Members

Crypto::Sha256::Hash hash

Public Static Attributes

constexpr Type type = Type::CertSha256

union Pki

#include <Fingerprints.h>

for the Public Key only

Public Members

Sha256 sha256

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.

Public Members

Crypto::Sha256::Hash hash

Public Static Attributes

constexpr Type type = Type::PkiSha256

class Types

#include <Fingerprints.h>

Maintains a set of fingerprint types.

Public Functions

void add(Type type)

void remove(Type type)

bool contains(Type type) const

Private Members

uint32_t mask = 0