This class stores data required for SSLClient to use mutual authentication.
More...
#include <SSLClientParameters.h>
|
| static SSLClientParameters | fromPEM (const char *cert_pem, const size_t cert_len, const char *key_pem, const size_t key_len) |
| | Create mutual authentication parameters from a PEM certificate and private key. More...
|
| |
| static SSLClientParameters | fromDER (const char *cert_der, const size_t cert_len, const char *key_der, const size_t key_len) |
| | Create mutual authentication parameters from a DER certificate and private key. More...
|
| |
|
| | SSLClientParameters (const char *cert, const size_t cert_len, const char *key, const size_t key_len, bool is_der) |
| |
This class stores data required for SSLClient to use mutual authentication.
SSLClientParameters.h
This file contains a simple utility class to store parameters about an SSL Session for reuse later.
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 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.
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.
◆ SSLClientParameters()
| SSLClientParameters::SSLClientParameters |
( |
const char * |
cert, |
|
|
const size_t |
cert_len, |
|
|
const char * |
key, |
|
|
const size_t |
key_len, |
|
|
bool |
is_der |
|
) |
| |
|
protected |
◆ fromDER()
| SSLClientParameters SSLClientParameters::fromDER |
( |
const char * |
cert_der, |
|
|
const size_t |
cert_len, |
|
|
const char * |
key_der, |
|
|
const size_t |
key_len |
|
) |
| |
|
static |
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.
- Parameters
-
| cert_der | A DER encoded certificate, can be ECC or RSA. |
| cert_len | The number of bytes in cert_der. |
| key_der | A DER encoded private key, can be ECC or RSA. |
| key_len | The number of bytes in key_ders |
- Returns
- An SSLClientParameters context, to be used with SSLClient::setMutualAuthParams.
◆ fromPEM()
| SSLClientParameters SSLClientParameters::fromPEM |
( |
const char * |
cert_pem, |
|
|
const size_t |
cert_len, |
|
|
const char * |
key_pem, |
|
|
const size_t |
key_len |
|
) |
| |
|
static |
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.
- Parameters
-
| 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. |
| cert_len | The number of bytes in cert_pem. |
| 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. |
| key_len | The number of bytes in key_pem |
- Returns
- An SSLClientParameters context, to be used with SSLClient::setMutualAuthParams.
◆ getCertChain()
| const br_x509_certificate* SSLClientParameters::getCertChain |
( |
| ) |
const |
|
inline |
mTLS information used by SSLClient during authentication
◆ getCertType()
| int SSLClientParameters::getCertType |
( |
| ) |
const |
|
inline |
mTLS information used by SSLClient during authentication
◆ getECKey()
| const br_ec_private_key* SSLClientParameters::getECKey |
( |
| ) |
const |
|
inline |
mTLS information used by SSLClient during authentication
◆ getRSAKey()
| const br_rsa_private_key* SSLClientParameters::getRSAKey |
( |
| ) |
const |
|
inline |
mTLS information used by SSLClient during authentication
The documentation for this class was generated from the following files:
1.9.1