From 7307de34c993470d4766caa33aa0fe94aecf4ac1 Mon Sep 17 00:00:00 2001 From: Noah Laptop Date: Mon, 2 Mar 2020 10:20:57 -0800 Subject: [PATCH] reworked mTLS authentication --- src/SSLClient.cpp | 1 + src/SSLClientParameters.cpp | 31 +++++++++++- src/SSLClientParameters.h | 99 ++++++++++++++++++++++++++++++------- 3 files changed, 110 insertions(+), 21 deletions(-) diff --git a/src/SSLClient.cpp b/src/SSLClient.cpp index 284e0f9..e68a182 100644 --- a/src/SSLClient.cpp +++ b/src/SSLClient.cpp @@ -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; } } diff --git a/src/SSLClientParameters.cpp b/src/SSLClientParameters.cpp index 244d427..c988a8f 100644 --- a/src/SSLClientParameters.cpp +++ b/src/SSLClientParameters.cpp @@ -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 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 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 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& 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& 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(cert, cert + cert_len) : make_vector_pem(cert, cert_len)) , m_cert_struct{ const_cast(reinterpret_cast(m_cert.data())), m_cert.size() } - , m_key{ make_key_from_der(is_der ? std::vector(key, key + key_len) : make_vector_pem(key, key_len)) } {} \ No newline at end of file + , m_key_struct{ make_key_from_der( is_der ? std::vector(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); +} \ No newline at end of file diff --git a/src/SSLClientParameters.h b/src/SSLClientParameters.h index 15f74cb..90edb71 100644 --- a/src/SSLClientParameters.h +++ b/src/SSLClientParameters.h @@ -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: + /** + * @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); - /* - 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 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 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 \ No newline at end of file