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

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

enum 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.

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

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

x509	pointer 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

x509	pointer to lws_x509_cert object
pem	pointer to PEM format content
len	length 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

x509	pointer to lws_x509_cert object, may contain multiple
trusted	a single, trusted cert object that we are checking for
common_name	NULL, 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

jwk	pointer to the jwk to initialize and set to the public key
x509	pointer to lws_x509_cert object that has the public key
curves	NULL to disallow EC, else a comma-separated list of valid curves using the JWA naming, eg, "P-256,P-384,P-521".
rsabits	minimum 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

cx	lws_context (for random)
jwk	pointer to the jwk to initialize and set to the public key
pem	pointer to PEM private key in memory
len	length of PEM private key in memory
passphrase	NULL 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

x509	pointer 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

wsi	the connection to query
type	one of LWS_TLS_CERT_INFO_
buf	pointer to union to take result
len	when 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

vhost	the vhost to query
type	one of LWS_TLS_CERT_INFO_
buf	pointer to union to take result
len	when 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

vhost	the vhost to acquire the selfsigned cert
san_a	SAN written into the certificate
san_b	second 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

context	lws_context used for random
elements	array of LWS_TLS_REQ_ELEMENT_COUNT const char *
csr	buffer that will get the b64URL(ASN-1 CSR)
csr_len	max length of the csr buffer
privkey_pem	pointer to pointer allocated to hold the privkey_pem
privkey_len	pointer 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

context	our lws_context
certpath	the filepath to the certificate
keypath	the filepath to the private key of the certificate
mem_cert	copy of the cert in memory
len_mem_cert	length of the copy of the cert in memory
mem_privkey	copy of the private key in memory
len_mem_privkey	length 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.