lmoskala/SSLClient
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

reworked mTLS authentication

Browse source
This commit is contained in:
Noah Laptop 2020-03-02 10:20:57 -08:00
parent 34af9c0d9b
commit 7307de34c9
3 changed files with 110 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
src/SSLClient.cpp
View file

@ -687,6 +687,7 @@ void SSLClient::m_print_br_error(const unsigned br_error_code, const DebugLevel
case BR_ERR_X509_FORBIDDEN_KEY_USAGE: Serial.println("Key Usage extension prohibits intended usage."); break;
case BR_ERR_X509_WEAK_PUBLIC_KEY: Serial.println("Public key found in certificate is too small."); break;
case BR_ERR_X509_NOT_TRUSTED: Serial.println("Chain could not be linked to a trust anchor."); break;
case 296: Serial.println("Server denied access (did you setup mTLS correctly?)"); break;
default: Serial.print("Unknown error code: "); Serial.println(br_error_code); break;
}
}

31
src/SSLClientParameters.cpp
View file

@ -19,7 +19,15 @@ static void ssl_pem_decode_callback(void *dest_ctx, const void *src, size_t len)
ctx->index += len;
}
static const std::vector<char> make_vector_pem(const char* data, const size_t len) {
/**
* Utility function to create a vector of the DER encoded bytes from a PEM
* certificate. Useful if we would like to decode certificates that have
* been transmitted over the internet.
* @param data PEM certificate bytes, including the "BEGIN" and "END" statements.
* @param len Number of characters to process, MUST include a whole certificate.
* @return A vector of bytes representing the certificate in DER format.
*/
static std::vector<char> make_vector_pem(const char* data, const size_t len) {
if (data == nullptr || len < 80) return {};
// initialize the bearssl PEM context
br_pem_decoder_context pctx;
@ -54,6 +62,14 @@ static const std::vector<char> make_vector_pem(const char* data, const size_t le
return temp;
}
/**
* Use the br_skey api family to decode a private key into the important numbers.
* This function supports both RSA and EC private keys, and returns a context
* which can be used by BearSSL later to authenticate with mTLS.
* @param der DER encoded certificate, as a vector of bytes.
* @returns context used by BearSSL to store information about the keys. You can
* use the br_skey_* family of APIs to access information from this context.
*/
static br_skey_decoder_context make_key_from_der(const std::vector<char>& der) {
br_skey_decoder_context out;
br_skey_decoder_init(&out);
@ -61,7 +77,18 @@ static br_skey_decoder_context make_key_from_der(const std::vector<char>& der) {
return out;
}
/* See SSLClientParams.h */
SSLClientParameters::SSLClientParameters(const char* cert, const size_t cert_len, const char* key, const size_t key_len, bool is_der)
: m_cert(is_der ? std::vector<char>(cert, cert + cert_len) : make_vector_pem(cert, cert_len))
, m_cert_struct{ const_cast<unsigned char*>(reinterpret_cast<const unsigned char*>(m_cert.data())), m_cert.size() }
, m_key{ make_key_from_der(is_der ? std::vector<char>(key, key + key_len) : make_vector_pem(key, key_len)) } {}
, m_key_struct{ make_key_from_der( is_der ? std::vector<char>(key, key + key_len) : make_vector_pem(key, key_len) ) } {}
/* See SSLClientParams.h */
SSLClientParameters SSLClientParameters::fromPEM(const char* cert_pem, const size_t cert_len, const char* key_pem, const size_t key_len) {
return SSLClientParameters(cert_pem, cert_len, key_pem, key_len, false);
}
/* See SSLClientParams.h */
SSLClientParameters SSLClientParameters::fromDER(const char* cert_der, const size_t cert_len, const char* key_der, const size_t key_len) {
return SSLClientParameters(cert_der, cert_len, key_der, key_len, true);
}

99
src/SSLClientParameters.h
View file

@ -34,41 +34,102 @@
#define SSLClientParameters_H_
/**
* \brief This class stores data required for SSLClient to use mutual authentication.
* @brief This class stores data required for SSLClient to use mutual authentication.
*
* TLS mutual authentication is a process in which both the server and client
* perform cryptographic operations to verify the authenticity of eachother, for more
* information check out this article: https://medium.com/sitewards/the-magic-of-tls-x509-and-mutual-authentication-explained-b2162dec4401 .
* If this struct is provided to SSLClient::SSLClient, SSLClient will automatically
* send a client certificate if one is requested by the server. This will happen for all
* SSLClient connections, and may cause issues for websites that do not need mutual authentication---
* as a result, please only turn on mutual authentication if you are sure it is neccesary.
* If this struct is provided to SSLClient::SSLClient via SSLClient::setMutualAuthParams,
* SSLClient will automatically send a client certificate if one is requested by the server.
* This will happen for all SSLClient connections, and may cause issues for websites that
* do not need mutual authentication---as a result, please only turn on mutual
* authentication if you are sure it is neccesary.
*
* At the moment SSLClient only supports mutual authentication using ECC client certificates.
* SSLClientParameters supports both ECC and RSA client certificates. I recommend using
* ECC certificates if possible, as SSLClientParameters will make a copy of both the
* certificate and the private key in memory, and ECC keys tend to be smaller than RSA ones.
*/
class SSLClientParameters {
public:
/*
static SSLClientParameters fromECCPEM(const char* cert_pem, const char* key_pem);
static SSLClientParameters fromECCDER(const char* cert_der, const char* key_der);
static SSLClientParameters fromRSAPEM(const char* cert_pem, const char* key_pem);
static SSLClientParameters fromRSADER(const char* cert_der, const char* key_der);
/**
* @brief Create mutual authentication parameters from a PEM certificate and private key
*
* Use this function to create a mutual tls context from a PEM client certificate and PEM
* private key. This function will convert the PEM certificates into DER format (creating
* a copy in the process), extract the needed information from the private key, and store
* that information into a SSLClientParameters object. Given the certifiate and key parsed
* correctly, you can then use SSLClient::setMutualAuthParams at the begining of your sketch
* to enable mTLS with SSLClient. This function supports both ECC and RSA certificate/private
* keys (use EC keys wherever possible, as they are signifigantly smaller and faster), however
* SSLClient only supports the p256, p384, and p512 curves for ECC.
*
* Because SSLClientParameters creates a copy of both the certificate and key, you do not
* need to ensure that the data pointed to by cert_pem or key_pem is accessible after
* this function (i.e. you can free them afterwards).
*
* Please note that if the certificate or private key are incorrect, this function will not
* report an error, and instead SSLClient will fall back to regular TLS when making a
* connection.
*
* @param cert_pem A PEM formatted certificate, including the "BEGIN" and "END" header/footers.
* Can be ECC or RSA. cert_pem supports both LF and CRLF for endlines, but all other constraints
* on a valid PEM file apply.
* @param cert_len The number of bytes in cert_pem.
* @param key_pem A PEM formatted private key, including the "BEGIN" and "END" header/footers.
* Can be ECC or RSA. key_pem supports both LF and CRLF for endlines, but all other constraints \
* on a valid PEM file apply.
* @param key_len The number of bytes in key_pem
* @return An SSLClientParameters context, to be used with SSLClient::setMutualAuthParams.
*/
static SSLClientParameters fromPEM(const char* cert_pem, const size_t cert_len, const char* key_pem, const size_t key_len);
/**
* @brief Create mutual authentication parameters from a DER certificate and private key
*
* Use this function to create a mutual tls context from a DER client certificate and DER
* private key. This function will copy the certificate and private key, extract the needed
* information from the private key, and store both that information and the copied cert
* into a SSLClientParameters object. Given the key parsed correctly, you can then use
* SSLClient::setMutualAuthParams at the begining of your sketch to enable mTLS with SSLClient.
* This function supports both ECC and RSA certificate/private keys (use EC keys wherever
* possible, as they are signifigantly smaller and faster), however SSLClient only supports
* the p256, p384, and p512 curves for ECC.
*
* Because SSLClientParameters creates a copy of both the certificate and key, you do not
* need to ensure that the data pointed to by cert_der or key_der is accessible after
* this function (i.e. you can free them afterwards).
*
* Please note that if the private key is incorrect, this function will not
* report an error, and instead SSLClient will fall back to regular TLS when making a
* connection.
*
* @param cert_der A DER encoded certificate, can be ECC or RSA.
* @param cert_len The number of bytes in cert_der.
* @param key_der A DER encoded private key, can be ECC or RSA.
* @param key_len The number of bytes in key_ders
* @return An SSLClientParameters context, to be used with SSLClient::setMutualAuthParams.
*/
static SSLClientParameters fromDER(const char* cert_der, const size_t cert_len, const char* key_der, const size_t key_len);
/** mTLS information used by SSLClient during authentication */
const br_x509_certificate* getCertChain() const { return &m_cert_struct; }
int getCertType() const { return br_skey_decoder_key_type(&m_key); }
const br_ec_private_key* getECKey() const { return br_skey_decoder_get_ec(&m_key); }
const br_rsa_private_key* getRSAKey() const { return br_skey_decoder_get_rsa(&m_key); }
// protected:
SSLClientParameters(const char* cert, const size_t cert_len, const char* key, const size_t key_len, bool is_der = false);
/** mTLS information used by SSLClient during authentication */
int getCertType() const { return br_skey_decoder_key_type(&m_key_struct); }
/** mTLS information used by SSLClient during authentication */
const br_ec_private_key* getECKey() const { return br_skey_decoder_get_ec(&m_key_struct); }
/** mTLS information used by SSLClient during authentication */
const br_rsa_private_key* getRSAKey() const { return br_skey_decoder_get_rsa(&m_key_struct); }
protected:
SSLClientParameters(const char* cert, const size_t cert_len, const char* key, const size_t key_len, bool is_der);
private:
const std::vector<char> m_cert;
const br_x509_certificate m_cert_struct;
const br_skey_decoder_context m_key;
const br_skey_decoder_context m_key_struct;
};
#endif