File SolidSyslogTlsFingerprint.h¶

FileList > Core > Interface > SolidSyslogTlsFingerprint.h

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "SolidSyslogExternC.h"

Classes¶

Type	Name
struct	SolidSyslogTlsFingerprint A parsed fingerprint: which hash, and its bytes.

Detailed Description¶

Certificate fingerprints in the RFC 5425 §4.2.2 form, and the peer authorisation a TLS stream performs with them.

No TLS library type appears here: a stream supplies the digest of the peer's certificate through a callback, and Core owns the parse and the comparison, so every TLS pack authorises a pinned peer by the same rule.

Public Types Documentation¶

enum @4¶

The longest digest a supported algorithm produces, in bytes.

enum @4 {
    SOLIDSYSLOG_TLS_FINGERPRINT_DIGEST_MAX = 32
};

SolidSyslogTlsAuthorisation¶

The verdict on a peer certificate against a list of pins.

enum SolidSyslogTlsAuthorisation {
    SOLIDSYSLOG_TLS_AUTHORISATION_MATCHED,
    SOLIDSYSLOG_TLS_AUTHORISATION_NO_MATCH,
    SOLIDSYSLOG_TLS_AUTHORISATION_MALFORMED,
    SOLIDSYSLOG_TLS_AUTHORISATION_DIGEST_UNAVAILABLE
};

Only MATCHED authorises.

SolidSyslogTlsDigestFunction¶

How a TLS stream obtains the digest of the peer's certificate: writes the hash of its DER encoding under algorithm intodigest , which holds SOLIDSYSLOG_TLS_FINGERPRINT_DIGEST_MAX bytes, and its length intolength .

typedef bool(* SolidSyslogTlsDigestFunction) (void *context, enum SolidSyslogTlsHashAlgorithm algorithm, uint8_t *digest, size_t *length);

Returns false where the algorithm cannot be computed, for instance a hash compiled out of the TLS library; the peer is then refused.

SolidSyslogTlsFingerprintListState¶

The worst state found in a pin list: a pin that will not parse outweighs one that names SHA-1.

enum SolidSyslogTlsFingerprintListState {
    SOLIDSYSLOG_TLS_FINGERPRINT_LIST_WELL_FORMED,
    SOLIDSYSLOG_TLS_FINGERPRINT_LIST_USES_SHA1,
    SOLIDSYSLOG_TLS_FINGERPRINT_LIST_MALFORMED
};

SolidSyslogTlsHashAlgorithm¶

The hash algorithms a fingerprint label may name.

enum SolidSyslogTlsHashAlgorithm {
    SOLIDSYSLOG_TLS_HASH_SHA1,
    SOLIDSYSLOG_TLS_HASH_SHA256
};

RFC 5425 §4.2.2 makes SHA-1 mandatory; SHA-256 is the one to configure.

Public Functions Documentation¶

SolidSyslogTlsFingerprint_Authorise¶

Authorises a peer against count pins, any one of which suffices.

enum SolidSyslogTlsAuthorisation SolidSyslogTlsFingerprint_Authorise (
    const char *const * fingerprints,
    size_t count,
    SolidSyslogTlsDigestFunction digest,
    void * context
)

Pins are parsed here, at the point of comparison, so a list has no fixed capacity. The walk stops at the first pin that matches or is malformed, and reports which. A pin naming a digest digest cannot supply is skipped rather than stopping the walk, because a rotation may pin two certificates under different hashes and a build may have compiled one of them out; where nothing matched and a pin was skipped that way, DIGEST_UNAVAILABLE is reported instead of NO_MATCH. A walk that finishes is NO_MATCH, as is an empty list.

SolidSyslogTlsFingerprint_InspectList¶

Inspects count pins before a handshake, so a stream can refuse a malformed list and warn of a SHA-1 pin once per connection.

enum SolidSyslogTlsFingerprintListState SolidSyslogTlsFingerprint_InspectList (
    const char *const * fingerprints,
    size_t count
)

An empty list is well formed, as is a NULL one with a count of zero; a count with no list behind it, or a NULL pin in one, is malformed.

SolidSyslogTlsFingerprint_ListIsPresent¶

Whether count pins are actually there to be read: a count with no list behind it, or a NULL pin within one, is not.

bool SolidSyslogTlsFingerprint_ListIsPresent (
    const char *const * fingerprints,
    size_t count
)

Credentials backends call this on the configuration they were given, so an integrator is told at Create rather than faulting on the first connection. An empty list is present.

SolidSyslogTlsFingerprint_Parse¶

Parses text in the RFC 5425 §4.2.2 form - an IANA hash label, a colon, then the digest as colon-separated hex pairs, the pairs in either case - intoout .

bool SolidSyslogTlsFingerprint_Parse (
    const char * text,
    struct SolidSyslogTlsFingerprint * out
)

The label itself is lower case, as the IANA registry spells it. Returns false, leaving out unspecified, where text or out is NULL, the label is not a supported algorithm, or the digest is not that algorithm's length in exactly that form.

The documentation for this class was generated from the following file Core/Interface/SolidSyslogTlsFingerprint.h