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

Functions
DllExport char *	eid_vwr_get_use_flags (const char *label, X509 *cert)
	Get the X.509v3 Key Usage field of the given certificate. More...
DllExport char *	eid_vwr_detail_cert (const char *label, X509 *cert)
	Get a printable version of the certificate's distinguished name (DN). More...
DllExport char *	eid_vwr_describe_cert (const char *label, X509 *cert)
	Get a useful label for the certificate. More...
DllExport int	eid_vwr_check_data_validity (const void *photo, int plen, const void *photohash, int hashlen, const void *datafile, int datfilelen, const void *datasig, int datsiglen, const void *addrfile, int addfilelen, const void *addrsig, int addsiglen, const void *rrncert, int certlen)
	Check that the data on the card is correctly signed. More...
DllExport void	eid_vwr_dumpcert (int fd, const void *derdata, int len, enum dump_type how)
	Write the given certificate to a file descriptor. More...
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 certificate. More...
DllExport enum eid_vwr_result	eid_vwr_verify_rrncert (const void *certificate, size_t certlen)
	Verify the validity of the RRN certificate. More...
DllExport char *	eid_vwr_x509_get_details (const void *certificate, size_t certlen)
	Produce a human-readable version of the certificate. More...

Detailed Description

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

Enumeration Type Documentation

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

DllExport int eid_vwr_check_data_validity	(	const void *	photo,
		int	plen,
		const void *	photohash,
		int	hashlen,
		const void *	datafile,
		int	datfilelen,
		const void *	datasig,
		int	datsiglen,
		const void *	addrfile,
		int	addfilelen,
		const void *	addrsig,
		int	addsiglen,
		const void *	rrncert,
		int	certlen
	)

Check that the data on the card is correctly signed.

This method will:

• Take a hash of the photo, and compare it against the passed photo hash
• Verify the identity signature (which contains the photo hash) against the passed identity signature file
• Concatenate the passed identity file to the passed address file in the correct manner, and verify the passed address signature against the result

Warning

the validity of the RRN certificate is not checked by this function.

See also

eid_vwr_verify_rrncert() verifies the RRN certificate

Parameters

photo	the contents of the binary data with label "PHOTO_FILE"
plen	the length in bytes of the preceding parameter
photohash	the contents of the binary data with label "photo_hash"
hashlen	the length in bytes of the preceding parameter
datafile	the contents of the binary data with label "DATA_FILE"
datfilelen	the length in bytes of the preceding parameter
datasig	the contents of the binary data with label "SIGN_DATA_FILE"
datsiglen	the length in bytes of the preceding parameter
addrfile	the contents of the binary data with label "ADDRESS_FILE"
addfilelen	the length in bytes of the preceding parameter
addrsig	the contents of the binary data with label "SIGN_ADDRESS_FILE"
addsiglen	the length in bytes of the preceding parameter
rrncert	the contents of the binary data with label CERT_RN_FILE (i.e., the RRN certificate)
certlen	the length in bytes of the preceding parameter

Returns

0 if one of the above-described tests indicates invalid data, or 1 if all tests were successful.

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.

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.

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

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.

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

This function will verify the validity of a 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.

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

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.

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.