OpenSSL-based helper functions

Files
file	certhelpers.h
	Certificate helper functions. Linux/OSX only.
file	verify_cert.h
	Helper functions to deal with certificate validation using OpenSSL. Linux/OSX only.

Enumerations
enum	dump_type { DUMP_DER , DUMP_PEM }

Functions
DllExport char *	eid_vwr_get_use_flags (const char *label, X509 *cert)
	Get the X.509v3 Key Usage field of the given certificate.
DllExport char *	eid_vwr_detail_cert (const char *label, X509 *cert)
	Get a printable version of the certificate's distinguished name (DN).
DllExport char *	eid_vwr_describe_cert (const char *label, X509 *cert)
	Get a useful label for the certificate.
DllExport void	eid_vwr_dumpcert (int fd, const void *derdata, int len, enum dump_type how)
	Write the given certificate to a file descriptor.
DllExport enum eid_vwr_result	eid_vwr_verify_cert (const void *certificate, size_t certlen, const void *ca, size_t calen, const void *(*perform_ocsp_request)(char *, void *, long, long *, void **), void(*free_ocsp_request)(void *))
	Verify the validity of a leaf certificate.
DllExport enum eid_vwr_result	eid_vwr_verify_cert_full (const void *certificate, size_t certlen, const void *ca, size_t calen, const void *(*perform_ocsp_request)(char *, void *, long, long *, void **), void(*free_ocsp_request)(void *), uint64_t flags)
	Verify the validity of a leaf certificate, specifying options.
DllExport enum eid_vwr_result	eid_vwr_verify_int_cert (const void *certificate, size_t certlen, const void *root, size_t rootlen, const void *(*perform_http_request)(char *, long *, void **), void(free_http_request)(void *))
	Verify the validity of an intermediate certificate.
DllExport enum eid_vwr_result	eid_vwr_verify_rrncert (const void *certificate, size_t certlen, const void *root_cert, size_t rootlen)
	Verify the validity of the RRN certificate.
DllExport enum eid_vwr_result	eid_vwr_verify_root_cert (const void *certificate, size_t certlen)
	Verify the validity of the root certificate.
DllExport char *	eid_vwr_x509_get_details (const void *certificate, size_t certlen)
	Produce a human-readable version of the certificate.
DllExport void	eid_vwr_check_signature (const void *pubkey, size_t pubkeylen, const void *signature, size_t siglen, const void *data, size_t datalen)
	helper function to verify that an ECDSA signature is correct.

Detailed Description

These functions are available on GNU/Linux and OS X only.

Enumeration Type Documentation

dump_type

enum dump_type

File type to be used when dumping data to a file

Enumerator
DUMP_DER	Dump using ASN.1 Distinguished Encoding Rules (DER)
DUMP_PEM	Dump in PEM format.

Function Documentation

eid_vwr_check_signature()

DllExport void eid_vwr_check_signature	(	const void *	pubkey,
		size_t	pubkeylen,
		const void *	signature,
		size_t	siglen,
		const void *	data,
		size_t	datalen
	)

helper function to verify that an ECDSA signature is correct.

Parameters

pubkey	the public (ECDSA) key to be used, in X9.62 raw format
pubkeylen	the length of pubkey
signature	the signature to verify
siglen	the length of signature

Note

this method only verifies that the signature is correct, nothing more; notably, it does not verify that the key is trusted or anything of the sorts.

eid_vwr_describe_cert()

DllExport char * eid_vwr_describe_cert	(	const char *	label,
		X509 *	cert
	)

Get a useful label for the certificate.

Parameters

label	a fallback label, to be used if nothing better can be found
cert	the certificate to parse

Returns

the certificate's Common Name field, or a copy of the value of the label parameter if the certificate has no common name. Should be free()d by the caller when no longer needed.

eid_vwr_detail_cert()

DllExport char * eid_vwr_detail_cert	(	const char *	label,
		X509 *	cert
	)

Get a printable version of the certificate's distinguished name (DN).

Parameters

label	not used
cert	the certificate to parse

Returns

a multi-line version of the certificate's distinguished name, as displayed on the eID Viewer's "certificates" pane. Should be free()d by the caller when no longer needed.

eid_vwr_dumpcert()

DllExport void eid_vwr_dumpcert	(	int	fd,
		const void *	derdata,
		int	len,
		enum dump_type	how
	)

Write the given certificate to a file descriptor.

Parameters

fd	the filedescriptor to write to
derdata	the certificate in DER format
len	the length in bytes of the preceding parameter
how	which format to use when writing

eid_vwr_get_use_flags()

DllExport char * eid_vwr_get_use_flags	(	const char *	label,
		X509 *	cert
	)

Get the X.509v3 Key Usage field of the given certificate.

Parameters

label	not used
cert	the certificate to parse

Returns

a string representation of the X.509v3 Key Usage field, as produced by OpenSSL. Should be free()d by the caller when no longer needed.

eid_vwr_verify_cert()

DllExport enum eid_vwr_result eid_vwr_verify_cert	(	const void *	certificate,
		size_t	certlen,
		const void *	ca,
		size_t	calen,
		const void *(*)(char *, void *, long, long *, void **)	perform_ocsp_request,
		void(*)(void *)	free_ocsp_request
	)

Verify the validity of a leaf certificate.

This function will verify the validity of a leaf certificate by checking signatures, ensuring they're signed by a valid root certificate, and performing an OCSP request against the OCSP server.

Parameters

certificate	the X.509 certificate to check, in DER format.
certlen	the length (in bytes) of certificate.
ca	the CA certificate by which the certificate is signed
calen	the length (in bytes) of ca
perform_ocsp_request	a pointer to a function which should perform an HTTP POST request and return the reply. It should return the data as returned by the OCSP server. Its parameters are: the URL for the OCSP server the data that should be sent (by way of an HTTP POST request) to the OCSP server the length of the above data a pointer to store the length of the returned body a pointer to store a handle to the request (which may, but is not required to, be the same as as the return value).
free_ocsp_request	called when the return value of perform_ocsp_request is no longer needed. Its parameter will be the data which was returned in perform_ocsp_request's last parameter.

eid_vwr_verify_cert_full()

DllExport enum eid_vwr_result eid_vwr_verify_cert_full	(	const void *	certificate,
		size_t	certlen,
		const void *	ca,
		size_t	calen,
		const void *(*)(char *, void *, long, long *, void **)	perform_ocsp_request,
		void(*)(void *)	free_ocsp_request,
		uint64_t	flags
	)

Verify the validity of a leaf certificate, specifying options.

This function will do the same thing as eid_vwr_verify_cert(), except that it allows to specify options through the "flags" parameter.

Valid options include:

• EID_VWR_NO_OCSP_ALLOWLIST: Specify that the OCSP URL should not be checked against a whitelist of known OCSP URLs.

eid_vwr_verify_int_cert()

DllExport enum eid_vwr_result eid_vwr_verify_int_cert	(	const void *	certificate,
		size_t	certlen,
		const void *	root,
		size_t	rootlen,
		const void *(*)(char *, long *, void **)	perform_http_request,
		void(free_http_request)(void *)
	)

Verify the validity of an intermediate certificate.

This function will verify the validity of an intermediate certificate by checking signatures, ensuring they're signed by a valid root certificate, and performing a CRL check against the correct CRL.

Parameters

certificate	the X.509 certificate to check, in DER format.
certlen	the length (in bytes) of certificate.
root	the root certificate by which the certificate is signed
rootlen	the length (in bytes) of root.
perform_http_request	a pointer to a function which should perform an HTTP GET request and return the reply. It should return the data as returned by the webserver in question. Its parameters are: The URL of the resource to retrieve A pointer to store the length of the returned body A pointer to store a handle to the request (which may, but is not required to, be the same as the return value).
free_http_request	called when the return value of perform_http_request is no longer needed. Its parameter will be the data which was returned in perform_http_request's last parameter.

eid_vwr_verify_root_cert()

DllExport enum eid_vwr_result eid_vwr_verify_root_cert	(	const void *	certificate,
		size_t	certlen
	)

Verify the validity of the root certificate.

This function will verify the validity of the root certificate by checking if the certificate can be found in the trust store.

Parameters

certificate	the X.509 certificate to check, in DER format
certlen	the length (in bytes) of certificate.

Since

v5.0

eid_vwr_verify_rrncert()

DllExport enum eid_vwr_result eid_vwr_verify_rrncert	(	const void *	certificate,
		size_t	certlen,
		const void *	root_cert,
		size_t	rootlen
	)

Verify the validity of the RRN certificate.

This function will verify the validity of the RRN certificate by checking that the certificate is signed by a valid root certificate.

Note

This function will not perform an OCSP request, since the root CA does not have an OCSP server.

Parameters

certificate	the X.509 certificate to check, in DER format.
certlen	the length (in bytes) of certificate.

eid_vwr_x509_get_details()

DllExport char * eid_vwr_x509_get_details	(	const void *	certificate,
		size_t	certlen
	)

Produce a human-readable version of the certificate.

This function will call OpenSSL's X509_print_ex() function on the given certificate which produces the output as produced by the command-line call "openssl x509 -in <certificate> -text".

Parameters

certificate	the certificate for which to get details
certlen	the length of certificate

Returns

a text representation of the certificate. Should be free()d when no longer required.