Mstdlib-1.24.0
TLS Certificates

Typedefs

typedef struct M_tls_x509 M_tls_x509_t
 
typedef enum M_tls_x509_san_type M_tls_x509_san_type_t
 

Enumerations

enum  M_tls_x509_txt_t {
  M_TLS_X509_TXT_COMMONNAME = 1 ,
  M_TLS_X509_TXT_ORGANIZATION = 2 ,
  M_TLS_X509_TXT_COUNTRY = 3 ,
  M_TLS_X509_TXT_STATE = 4 ,
  M_TLS_X509_TXT_ORGANIZATIONALUNIT = 5 ,
  M_TLS_X509_TXT_LOCALITY = 6
}
 
enum  M_tls_x509_sig_alg_t {
  M_TLS_X509_SIG_ALG_SHA1 = 1 ,
  M_TLS_X509_SIG_ALG_SHA256 = 2
}
 
enum  M_tls_x509_san_type {
  M_TLS_X509_SAN_TYPE_DNS = 1 ,
  M_TLS_X509_SAN_TYPE_IP = 2
}
 

Functions

char * M_tls_rsa_generate_key (size_t bits)
 
M_tls_x509_tM_tls_x509_new (const char *rsa_privkey)
 
void M_tls_x509_destroy (M_tls_x509_t *x509)
 
M_bool M_tls_x509_txt_add (M_tls_x509_t *x509, M_tls_x509_txt_t type, const char *text, M_bool append)
 
M_bool M_tls_x509_txt_SAN_add (M_tls_x509_t *x509, M_tls_x509_san_type_t type, const char *text, M_bool append)
 
char * M_tls_x509_write_csr (M_tls_x509_t *x509)
 
M_tls_x509_tM_tls_x509_read_csr (const char *csr)
 
M_tls_x509_tM_tls_x509_read_crt (const char *crt)
 
char * M_tls_x509_selfsign (M_tls_x509_t *x509, M_uint64 valid_secs)
 
char * M_tls_x509_sign (M_tls_x509_t *x509, const char *cacert, const char *caprivkey, M_uint64 valid_secs)
 
M_time_t M_tls_x509_time_start (M_tls_x509_t *x509)
 
M_time_t M_tls_x509_time_end (M_tls_x509_t *x509)
 
char * M_tls_x509_subject_name (M_tls_x509_t *x509)
 
char * M_tls_x509_issuer_name (M_tls_x509_t *x509)
 
char * M_tls_x509_signature (M_tls_x509_t *x509, M_tls_x509_sig_alg_t alg)
 
unsigned char * M_tls_dhparam_generate (size_t bits, size_t *out_len)
 

Detailed Description

Basic TLS certificate functionality. This is primary used to aid in generating self signed certificates programmatically.

Warning
These functions are experimental and unstable. They should not be used in production at this time.

Example generating a CA, server certificate and signing the certificate with the CA.

#include <mstdlib/mstdlib.h>
#include <mstdlib/mstdlib_tls.h>
#define VALID_SEC (5*365*24*60*60)
int main(int argc, char **argv)
{
char *CA_privkey;
M_tls_x509_t *CA_x509;
char *CA_crt;
char *Server_privkey;
M_tls_x509_t *Server_x509;
M_tls_x509_t *Server_csr_x509;
char *Server_crt;
char *Server_csr;
// Generate our certificate authority.
CA_privkey = M_tls_rsa_generate_key(2048);
CA_x509 = M_tls_x509_new(CA_privkey);
M_tls_x509_txt_add(CA_x509, M_TLS_X509_TXT_COMMONNAME, "MY CA", M_FALSE);
M_tls_x509_txt_add(CA_x509, M_TLS_X509_TXT_ORGANIZATION, "MY ORG", M_FALSE);
M_tls_x509_txt_SAN_add(CA_x509, M_TLS_X509_SAN_TYPE_DNS, "ca.myorg.local", M_FALSE);
CA_crt = M_tls_x509_selfsign(CA_x509, VALID_SEC);
// Generate the server x509
Server_privkey = M_tls_rsa_generate_key(2048);
Server_x509 = M_tls_x509_new(Server_privkey);
M_tls_x509_txt_add(Server_x509, M_TLS_X509_TXT_COMMONNAME, "MY Server", M_FALSE);
M_tls_x509_txt_add(Server_x509, M_TLS_X509_TXT_ORGANIZATION, "MY ORG", M_FALSE);
M_tls_x509_txt_SAN_add(Server_x509, M_TLS_X509_SAN_TYPE_DNS, "server.myorg.local", M_FALSE);
// Generate a server CSR from the server x509.
// Sign the CSR creating a server certificate.
Server_csr = M_tls_x509_write_csr(Server_x509);
Server_csr_x509 = M_tls_x509_read_csr(Server_csr);
Server_crt = M_tls_x509_sign(Server_csr_x509, CA_crt, CA_privkey, VALID_SEC);
M_printf("CA Priv Key:\n%s\n", CA_privkey);
M_printf("CA CRT:\n%s\n", CA_crt);
M_printf("Server Priv Key:\n%s\n", Server_privkey);
M_printf("Server CSR:\n%s\n", Server_csr);
M_printf("Server CRT:\n%s\n", Server_crt);
M_free(Server_csr);
M_free(Server_crt);
M_free(Server_privkey);
M_free(CA_crt);
M_free(CA_privkey);
M_tls_x509_destroy(Server_csr_x509);
M_tls_x509_destroy(Server_x509);
}
ssize_t M_printf(const char *fmt,...)
void M_free(void *ptr) M_FREE(1)
struct M_tls_x509 M_tls_x509_t
Definition: m_tls_certs.h:107
M_bool M_tls_x509_txt_SAN_add(M_tls_x509_t *x509, M_tls_x509_san_type_t type, const char *text, M_bool append)
M_tls_x509_t * M_tls_x509_new(const char *rsa_privkey)
M_tls_x509_t * M_tls_x509_read_csr(const char *csr)
char * M_tls_rsa_generate_key(size_t bits)
char * M_tls_x509_selfsign(M_tls_x509_t *x509, M_uint64 valid_secs)
M_bool M_tls_x509_txt_add(M_tls_x509_t *x509, M_tls_x509_txt_t type, const char *text, M_bool append)
char * M_tls_x509_sign(M_tls_x509_t *x509, const char *cacert, const char *caprivkey, M_uint64 valid_secs)
void M_tls_x509_destroy(M_tls_x509_t *x509)
char * M_tls_x509_write_csr(M_tls_x509_t *x509)
@ M_TLS_X509_TXT_ORGANIZATION
Definition: m_tls_certs.h:113
@ M_TLS_X509_TXT_COMMONNAME
Definition: m_tls_certs.h:112
@ M_TLS_X509_SAN_TYPE_DNS
Definition: m_tls_certs.h:131

Typedef Documentation

◆ M_tls_x509_t

typedef struct M_tls_x509 M_tls_x509_t

◆ M_tls_x509_san_type_t

Enumeration Type Documentation

◆ M_tls_x509_txt_t

X509 certificate text attributes.

Enumerator
M_TLS_X509_TXT_COMMONNAME 

(CN) Name of certificate.

M_TLS_X509_TXT_ORGANIZATION 

(O) Organization owning certificate.

M_TLS_X509_TXT_COUNTRY 

(C) County where the organization is located.

M_TLS_X509_TXT_STATE 

(S) State or providence where the organization is located.

M_TLS_X509_TXT_ORGANIZATIONALUNIT 

(OU) Group within the organization owning the certificate.

M_TLS_X509_TXT_LOCALITY 

(L) State, township, county, etc. where the organizational unit is located.

◆ M_tls_x509_sig_alg_t

Certificate hash algorithm.

Enumerator
M_TLS_X509_SIG_ALG_SHA1 

SHA 1.

M_TLS_X509_SIG_ALG_SHA256 

SHA 256.

◆ M_tls_x509_san_type

Type of subject alternative name.

Enumerator
M_TLS_X509_SAN_TYPE_DNS 

Name is a host name that can be retrieved by DNS.

M_TLS_X509_SAN_TYPE_IP 

Name is an ip address.

Function Documentation

◆ M_tls_rsa_generate_key()

char * M_tls_rsa_generate_key ( size_t  bits)

Generate an RSA private key

Parameters
[in]bitsBit size of the key.
Returns
Buffer containing private key

◆ M_tls_x509_new()

M_tls_x509_t * M_tls_x509_new ( const char *  rsa_privkey)

Create a new x509 certificate.

Parameters
[in]rsa_privkeyRSA private key.
Returns
X509 certificate.
See also
M_tls_rsa_generate_key

◆ M_tls_x509_destroy()

void M_tls_x509_destroy ( M_tls_x509_t x509)

Destroy an x509 certificate.

Parameters
[in]x509Certificate.

◆ M_tls_x509_txt_add()

M_bool M_tls_x509_txt_add ( M_tls_x509_t x509,
M_tls_x509_txt_t  type,
const char *  text,
M_bool  append 
)

Add a text entry to the certificate of the requested type.

Parameters
[in]x509Certificate.
[in]typeType of attribute.
[in]textText to put in attribute.
[in]appendM_TRUE to append. M_FALSE to replace if the attribute already exists.
Returns
M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_x509_txt_SAN_add()

M_bool M_tls_x509_txt_SAN_add ( M_tls_x509_t x509,
M_tls_x509_san_type_t  type,
const char *  text,
M_bool  append 
)

Add subject alternative name to a certificate.

Parameters
[in]x509Certificate.
[in]typeType of attribute.
[in]textText to put in attribute.
[in]appendM_TRUE to append. M_FALSE to replace if the attribute already exists.
Returns
M_TRUE on success, otherwise M_FALSE on error.

◆ M_tls_x509_write_csr()

char * M_tls_x509_write_csr ( M_tls_x509_t x509)

Generate a CSR from an x509 certificate.

Parameters
[in]x509Certificate.
Returns
String on success, otherwise NULL on error.

◆ M_tls_x509_read_csr()

M_tls_x509_t * M_tls_x509_read_csr ( const char *  csr)

Read a CSR request.

Parameters
[in]csrCSR requested.
Returns
x509 certificate on success, otherwise NULL on error.

◆ M_tls_x509_read_crt()

M_tls_x509_t * M_tls_x509_read_crt ( const char *  crt)

Read a PEM-encoded certificate.

Parameters
[in]crtCertificate.
Returns
x509 certificate on success, otherwise NULL on error.

◆ M_tls_x509_selfsign()

char * M_tls_x509_selfsign ( M_tls_x509_t x509,
M_uint64  valid_secs 
)

Self-sign the certificate.

Signs using SHA 256 algorithm.

Parameters
[in]x509Certificate.
[in]valid_secsThe validity period for the certificate in seconds.
Returns
Buffer containing x509 certificate.

◆ M_tls_x509_sign()

char * M_tls_x509_sign ( M_tls_x509_t x509,
const char *  cacert,
const char *  caprivkey,
M_uint64  valid_secs 
)

Sign the certificate

Signs using SHA 256 algorithm.

Parameters
[in]x509Certificate.
[in]cacertCA certificate to use for signing.
[in]caprivkeyCA certificate private key.
[in]valid_secsThe validity period for the certificate in seconds.
Returns
Buffer containing signed x509 certificate.

◆ M_tls_x509_time_start()

M_time_t M_tls_x509_time_start ( M_tls_x509_t x509)

Get the start time (not before) of a certificate.

Parameters
[in]x509Certificate.
Returns
Time.

◆ M_tls_x509_time_end()

M_time_t M_tls_x509_time_end ( M_tls_x509_t x509)

Get the end time (not after) of a certificate.

Parameters
[in]x509Certificate.
Returns
Time.

◆ M_tls_x509_subject_name()

char * M_tls_x509_subject_name ( M_tls_x509_t x509)

Get the subject name of a certificate.

Parameters
[in]x509Certificate.
Returns
String.

◆ M_tls_x509_issuer_name()

char * M_tls_x509_issuer_name ( M_tls_x509_t x509)

Get the issuer name of a certificate.

Parameters
[in]x509Certificate.
Returns
String.

◆ M_tls_x509_signature()

char * M_tls_x509_signature ( M_tls_x509_t x509,
M_tls_x509_sig_alg_t  alg 
)

Retrieves the signature/digest of the x509 certificate.

Useful for matching clients to certificates

Parameters
[in]x509Certificate.
[in]algAlgorithm to use for signature calculation.
Returns
String.

◆ M_tls_dhparam_generate()

unsigned char * M_tls_dhparam_generate ( size_t  bits,
size_t *  out_len 
)

Generate DH parameters.

Could take a very long time, should probably occur in its own thread to not block program execution.

Parameters
[in]bitsBit size of the parameters.
[out]out_lenLength of the output.
Returns
dhparams.