libwebsockets
Lightweight C library for HTML5 websockets
lws-x509.h File Reference
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

union  lws_tls_cert_info_results
 
struct  lws_tls_cert_info_results.ns
 

Enumerations

enum  lws_tls_cert_info {
  LWS_TLS_CERT_INFO_VALIDITY_FROM , LWS_TLS_CERT_INFO_VALIDITY_TO , LWS_TLS_CERT_INFO_COMMON_NAME , LWS_TLS_CERT_INFO_ISSUER_NAME ,
  LWS_TLS_CERT_INFO_USAGE , LWS_TLS_CERT_INFO_VERIFIED , LWS_TLS_CERT_INFO_OPAQUE_PUBLIC_KEY , LWS_TLS_CERT_INFO_DER_RAW ,
  LWS_TLS_CERT_INFO_AUTHORITY_KEY_ID , LWS_TLS_CERT_INFO_AUTHORITY_KEY_ID_ISSUER , LWS_TLS_CERT_INFO_AUTHORITY_KEY_ID_SERIAL , LWS_TLS_CERT_INFO_SUBJECT_KEY_ID
}
 

Functions

LWS_VISIBLE LWS_EXTERN int lws_x509_create (struct lws_x509_cert **x509)
 
LWS_VISIBLE LWS_EXTERN int lws_x509_parse_from_pem (struct lws_x509_cert *x509, const void *pem, size_t len)
 
LWS_VISIBLE LWS_EXTERN int lws_x509_verify (struct lws_x509_cert *x509, struct lws_x509_cert *trusted, const char *common_name)
 
LWS_VISIBLE LWS_EXTERN int lws_x509_public_to_jwk (struct lws_jwk *jwk, struct lws_x509_cert *x509, const char *curves, int rsabits)
 
LWS_VISIBLE LWS_EXTERN int lws_x509_jwk_privkey_pem (struct lws_context *cx, struct lws_jwk *jwk, void *pem, size_t len, const char *passphrase)
 
LWS_VISIBLE LWS_EXTERN void lws_x509_destroy (struct lws_x509_cert **x509)
 
LWS_VISIBLE LWS_EXTERN int lws_x509_info (struct lws_x509_cert *x509, enum lws_tls_cert_info type, union lws_tls_cert_info_results *buf, size_t len)
 
LWS_VISIBLE LWS_EXTERN int lws_tls_peer_cert_info (struct lws *wsi, enum lws_tls_cert_info type, union lws_tls_cert_info_results *buf, size_t len)
 
LWS_VISIBLE LWS_EXTERN int lws_tls_vhost_cert_info (struct lws_vhost *vhost, enum lws_tls_cert_info type, union lws_tls_cert_info_results *buf, size_t len)
 
LWS_VISIBLE LWS_EXTERN int lws_tls_acme_sni_cert_create (struct lws_vhost *vhost, const char *san_a, const char *san_b)
 
LWS_VISIBLE LWS_EXTERN int lws_tls_acme_sni_csr_create (struct lws_context *context, const char *elements[], uint8_t *csr, size_t csr_len, char **privkey_pem, size_t *privkey_len)
 
LWS_VISIBLE LWS_EXTERN int lws_tls_cert_updated (struct lws_context *context, const char *certpath, const char *keypath, const char *mem_cert, size_t len_mem_cert, const char *mem_privkey, size_t len_mem_privkey)
 

Data Structure Documentation

◆ lws_tls_cert_info_results

union lws_tls_cert_info_results

Definition at line 60 of file lws-x509.h.

+ Collaboration diagram for lws_tls_cert_info_results:
Data Fields
unsigned int verified
time_t time
unsigned int usage
struct lws_tls_cert_info_results.ns ns

◆ lws_tls_cert_info_results.ns

struct lws_tls_cert_info_results.ns

Definition at line 64 of file lws-x509.h.

+ Collaboration diagram for lws_tls_cert_info_results.ns:
Data Fields
int len
char name[64]

Enumeration Type Documentation

◆ lws_tls_cert_info

Enumerator
LWS_TLS_CERT_INFO_VALIDITY_FROM 

fills .time with the time_t the cert validity started from

LWS_TLS_CERT_INFO_VALIDITY_TO 

fills .time with the time_t the cert validity ends at

LWS_TLS_CERT_INFO_COMMON_NAME 

fills up to len bytes of .ns.name with the cert common name

LWS_TLS_CERT_INFO_ISSUER_NAME 

fills up to len bytes of .ns.name with the cert issuer name

LWS_TLS_CERT_INFO_USAGE 

fills verified with a bitfield asserting the valid uses

LWS_TLS_CERT_INFO_VERIFIED 

fills .verified with a bool representing peer cert validity, call returns -1 if no cert

LWS_TLS_CERT_INFO_OPAQUE_PUBLIC_KEY 

the certificate's public key, as an opaque bytestream. These opaque bytestreams can only be compared with each other using the same tls backend, ie, OpenSSL or mbedTLS. The different backends produce different, incompatible representations for the same cert.

LWS_TLS_CERT_INFO_DER_RAW 

the certificate's raw DER representation. If it's too big, -1 is returned and the size will be returned in buf->ns.len. If the certificate cannot be found -1 is returned and 0 in buf->ns.len.

LWS_TLS_CERT_INFO_AUTHORITY_KEY_ID 

If the cert has one, the key ID responsible for the signature

LWS_TLS_CERT_INFO_AUTHORITY_KEY_ID_ISSUER 

If the cert has one, the issuer responsible for the signature

LWS_TLS_CERT_INFO_AUTHORITY_KEY_ID_SERIAL 

If the cert has one, serial number responsible for the signature

LWS_TLS_CERT_INFO_SUBJECT_KEY_ID 

If the cert has one, the cert's subject key ID

Definition at line 25 of file lws-x509.h.

25 {
58};
@ LWS_TLS_CERT_INFO_AUTHORITY_KEY_ID
Definition: lws-x509.h:50
@ LWS_TLS_CERT_INFO_VERIFIED
Definition: lws-x509.h:36
@ LWS_TLS_CERT_INFO_VALIDITY_TO
Definition: lws-x509.h:28
@ LWS_TLS_CERT_INFO_AUTHORITY_KEY_ID_ISSUER
Definition: lws-x509.h:52
@ LWS_TLS_CERT_INFO_OPAQUE_PUBLIC_KEY
Definition: lws-x509.h:39
@ LWS_TLS_CERT_INFO_ISSUER_NAME
Definition: lws-x509.h:32
@ LWS_TLS_CERT_INFO_USAGE
Definition: lws-x509.h:34
@ LWS_TLS_CERT_INFO_SUBJECT_KEY_ID
Definition: lws-x509.h:56
@ LWS_TLS_CERT_INFO_COMMON_NAME
Definition: lws-x509.h:30
@ LWS_TLS_CERT_INFO_VALIDITY_FROM
Definition: lws-x509.h:26
@ LWS_TLS_CERT_INFO_DER_RAW
Definition: lws-x509.h:45
@ LWS_TLS_CERT_INFO_AUTHORITY_KEY_ID_SERIAL
Definition: lws-x509.h:54

Function Documentation

◆ lws_x509_create()

LWS_VISIBLE LWS_EXTERN int lws_x509_create ( struct lws_x509_cert **  x509)

lws_x509_create() - Allocate an lws_x509_cert object

Parameters
x509pointer to lws_x509_cert pointer to be set to allocated object

Allocates an lws_x509_cert object and set *x509 to point to it.

◆ lws_x509_parse_from_pem()

LWS_VISIBLE LWS_EXTERN int lws_x509_parse_from_pem ( struct lws_x509_cert *  x509,
const void *  pem,
size_t  len 
)

lws_x509_parse_from_pem() - Read one or more x509 certs in PEM format from memory

Parameters
x509pointer to lws_x509_cert object
pempointer to PEM format content
lenlength of PEM format content

Parses PEM certificates in memory into a native x509 representation for the TLS library. If there are multiple PEM certs concatenated, they are all read into the same object and exist as a "chain".

IMPORTANT for compatibility with mbedtls, the last used byte of pem must be '\0' and the len must include it.

Returns 0 if all went OK, or nonzero for failure.

◆ lws_x509_verify()

LWS_VISIBLE LWS_EXTERN int lws_x509_verify ( struct lws_x509_cert *  x509,
struct lws_x509_cert *  trusted,
const char *  common_name 
)

lws_x509_verify() - Validate signing relationship between one or more certs and a trusted CA cert

Parameters
x509pointer to lws_x509_cert object, may contain multiple
trusteda single, trusted cert object that we are checking for
common_nameNULL, or required CN (Common Name) of x509

Returns 0 if the cert or certs in x509 represent a complete chain that is ultimately signed by the cert in trusted. Returns nonzero if that's not the case.

◆ lws_x509_public_to_jwk()

LWS_VISIBLE LWS_EXTERN int lws_x509_public_to_jwk ( struct lws_jwk jwk,
struct lws_x509_cert *  x509,
const char *  curves,
int  rsabits 
)

lws_x509_public_to_jwk() - Copy the public key out of a cert and into a JWK

Parameters
jwkpointer to the jwk to initialize and set to the public key
x509pointer to lws_x509_cert object that has the public key
curvesNULL to disallow EC, else a comma-separated list of valid curves using the JWA naming, eg, "P-256,P-384,P-521".
rsabitsminimum number of RSA bits required in the cert if RSA

Returns 0 if JWK was set to the certificate public key correctly and the curve / the RSA key size was acceptable. Automatically produces an RSA or EC JWK depending on what the cert had.

◆ lws_x509_jwk_privkey_pem()

LWS_VISIBLE LWS_EXTERN int lws_x509_jwk_privkey_pem ( struct lws_context *  cx,
struct lws_jwk jwk,
void *  pem,
size_t  len,
const char *  passphrase 
)

lws_x509_jwk_privkey_pem() - Copy a private key PEM into a jwk that has the public part already

Parameters
cxlws_context (for random)
jwkpointer to the jwk to initialize and set to the public key
pempointer to PEM private key in memory
lenlength of PEM private key in memory
passphraseNULL or passphrase needed to decrypt private key

IMPORTANT for compatibility with mbedtls, the last used byte of pem must be '\0' and the len must include it.

Returns 0 if the private key was successfully added to the JWK, else nonzero if failed.

The PEM image in memory is zeroed down on both successful and failed exits. The caller should take care to zero down passphrase if used.

◆ lws_x509_destroy()

LWS_VISIBLE LWS_EXTERN void lws_x509_destroy ( struct lws_x509_cert **  x509)

lws_x509_destroy() - Destroy a previously allocated lws_x509_cert object

Parameters
x509pointer to lws_x509_cert pointer

Deallocates an lws_x509_cert object and sets its pointer to NULL.

◆ lws_x509_info()

LWS_VISIBLE LWS_EXTERN int lws_x509_info ( struct lws_x509_cert *  x509,
enum lws_tls_cert_info  type,
union lws_tls_cert_info_results buf,
size_t  len 
)

◆ lws_tls_peer_cert_info()

LWS_VISIBLE LWS_EXTERN int lws_tls_peer_cert_info ( struct lws *  wsi,
enum lws_tls_cert_info  type,
union lws_tls_cert_info_results buf,
size_t  len 
)

lws_tls_peer_cert_info() - get information from the peer's TLS cert

Parameters
wsithe connection to query
typeone of LWS_TLS_CERT_INFO_
bufpointer to union to take result
lenwhen result is a string, the true length of buf->ns.name[]

lws_tls_peer_cert_info() lets you get hold of information from the peer certificate.

Return 0 if there is a result in buf, or nonzero indicating there was no cert, or another problem.

This function works the same no matter if the TLS backend is OpenSSL or mbedTLS.

◆ lws_tls_vhost_cert_info()

LWS_VISIBLE LWS_EXTERN int lws_tls_vhost_cert_info ( struct lws_vhost *  vhost,
enum lws_tls_cert_info  type,
union lws_tls_cert_info_results buf,
size_t  len 
)

lws_tls_vhost_cert_info() - get information from the vhost's own TLS cert

Parameters
vhostthe vhost to query
typeone of LWS_TLS_CERT_INFO_
bufpointer to union to take result
lenwhen result is a string, the true length of buf->ns.name[]

lws_tls_vhost_cert_info() lets you get hold of information from the vhost certificate.

Return 0 if there is a result in buf, or nonzero indicating there was no cert, or another problem.

This function works the same no matter if the TLS backend is OpenSSL or mbedTLS.

◆ lws_tls_acme_sni_cert_create()

LWS_VISIBLE LWS_EXTERN int lws_tls_acme_sni_cert_create ( struct lws_vhost *  vhost,
const char *  san_a,
const char *  san_b 
)

lws_tls_acme_sni_cert_create() - creates a temp selfsigned cert and attaches to a vhost

Parameters
vhostthe vhost to acquire the selfsigned cert
san_aSAN written into the certificate
san_bsecond SAN written into the certificate

Returns 0 if created and attached to the vhost. Returns nonzero if problems, and frees all allocations before returning.

On success, any allocations are destroyed at vhost destruction automatically.

◆ lws_tls_acme_sni_csr_create()

LWS_VISIBLE LWS_EXTERN int lws_tls_acme_sni_csr_create ( struct lws_context *  context,
const char *  elements[],
uint8_t *  csr,
size_t  csr_len,
char **  privkey_pem,
size_t *  privkey_len 
)

lws_tls_acme_sni_csr_create() - creates a CSR and related private key PEM

Parameters
contextlws_context used for random
elementsarray of LWS_TLS_REQ_ELEMENT_COUNT const char *
csrbuffer that will get the b64URL(ASN-1 CSR)
csr_lenmax length of the csr buffer
privkey_pempointer to pointer allocated to hold the privkey_pem
privkey_lenpointer to size_t set to the length of the privkey_pem

Creates a CSR according to the information in elements, and a private RSA key used to sign the CSR.

The outputs are the b64URL(ASN-1 CSR) into csr, and the PEM private key into privkey_pem.

Notice that elements points to an array of const char *s pointing to the information listed in the enum above. If an entry is NULL or an empty string, the element is set to "none" in the CSR.

Returns 0 on success or nonzero for failure.

◆ lws_tls_cert_updated()

LWS_VISIBLE LWS_EXTERN int lws_tls_cert_updated ( struct lws_context *  context,
const char *  certpath,
const char *  keypath,
const char *  mem_cert,
size_t  len_mem_cert,
const char *  mem_privkey,
size_t  len_mem_privkey 
)

lws_tls_cert_updated() - update every vhost using the given cert path

Parameters
contextour lws_context
certpaththe filepath to the certificate
keypaththe filepath to the private key of the certificate
mem_certcopy of the cert in memory
len_mem_certlength of the copy of the cert in memory
mem_privkeycopy of the private key in memory
len_mem_privkeylength of the copy of the private key in memory

Checks every vhost to see if it is the using certificate described by the the given filepaths. If so, it attempts to update the vhost ssl_ctx to use the new certificate.

Returns 0 on success or nonzero for failure.