reworked mTLS authentication

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;
   }
 }

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<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);
+}

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
+ * If this struct is provided to SSLClient::SSLClient via SSLClient::setMutualAuthParams,
- * send a client certificate if one is requested by the server. This will happen for all
+ * SSLClient will automatically send a client certificate if one is requested by the server. 
- * SSLClient connections, and may cause issues for websites that do not need mutual authentication---
+ * This will happen for all SSLClient connections, and may cause issues for websites that 
- * as a result, please only turn on mutual authentication if you are sure it is neccesary.
+ * 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);
+     * @brief Create mutual authentication parameters from a DER certificate and private key
-    static SSLClientParameters fromECCDER(const char* cert_der, const char* key_der);
+     * 
-    static SSLClientParameters fromRSAPEM(const char* cert_pem, const char* key_pem);
+     * Use this function to create a mutual tls context from a DER client certificate and DER
-    static SSLClientParameters fromRSADER(const char* cert_der, const char* key_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:
+    /** mTLS information used by SSLClient during authentication */
-    SSLClientParameters(const char* cert, const size_t cert_len, const char* key, const size_t key_len, bool is_der = false);
+    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