Class for handling X509 certificates. More...

#include <uapkicertificate.h>

Public Types
enum	Extension
	Extensions Enumeration.

enum	SignatureAlgorithm
	SignaturAlgorithm Enumeration.

Public Member Functions
	UaPkiCertificate (const UaPkiCertificateInfo &info, const UaPkiIdentity &subject, const UaPkiRsaKeyPair &subjectKeyPair, bool bCACert=false, SignatureAlgorithm signatureAlgorithm=SignatureAlgorithm_Sha256)
	Creates a new self-signed certificate. More...

	UaPkiCertificate (const UaPkiCertificateInfo &info, const UaPkiIdentity &subject, const UaPkiPublicKey &subjectPublicKey, const UaPkiCertificate &issuerCert, const UaPkiPrivateKey &issuerPrivateKey, bool bCACert=false, SignatureAlgorithm signatureAlgorithm=SignatureAlgorithm_Sha256)
	Creates a certificate signed by the passed issuer. More...

UaPkiCertificate &	operator= (const UaPkiCertificate &copy)
	Assigns another UaPkiCertificate to the current instance. More...

bool	operator== (const UaPkiCertificate &other)
	Compares the current instance to another certificate. More...

UaPkiPublicKey	publicKey () const
	Returns the public key of the certificate. More...

UaString	commonName () const
	Returns the certificate's commonName field. More...

UaPkiIdentity	subject () const
	Returns the certificate subject identity. More...

UaPkiIdentity	issuer () const
	Returns the certificate issuer identity. More...

UaPkiCertificateInfo	info () const
	Returns information from the X509v3 extension subjectAltName. More...

UaDateTime	validFrom () const
	Returns the start date of the certificate's valid time period. More...

UaDateTime	validTo () const
	Returns the end date of the certificate's valid time period. More...

UaString	serialNumber () const
	Returns the certificate's serial number. More...

bool	isValid () const
	Returns true if the the certificate is valid and not expired. More...

bool	sign (const UaPkiCertificate &issuerCert, const UaPkiPrivateKey &issuerPrivateKey, SignatureAlgorithm signatureAlgorithm=SignatureAlgorithm_Sha256)
	Signs the certificate using the passed certificate and private key. More...

UaByteArray	toDER () const
	Encodes the certificate in DER format. More...

UaByteString	toByteStringDER () const
	Encodes the certificate in DER format. More...

int	toDERFile (const char *szFile) const
	Stores the certificate in a DER encoded file. More...

int	toDERFile (const UaString &sFile) const
	Stores the certificate in a DER encoded file. More...

int	toPEMFile (const char *szFile) const
	Stores the certificate in a PEM encoded file. More...

int	toPEMFile (const UaString &sFile) const
	Stores the certificate in a PEM encoded file. More...

UaByteArray	thumbPrint () const
	Creates the SHA1 thumbprint of the certificate. More...

UaString	createCertificateFilePath (const UaString &basePath) const
	Creates a filepath that can be used to save a certificate to a file. More...

UaPkiCSR	createCSR (const UaPkiPrivateKey &subjectPrivateKey, SignatureAlgorithm signatureAlgorithm)
	Creates a certificate signing request. More...

int	toWindowsStore (WindowsStoreLocation location, const UaString &sStoreName) const
	Stores the certificate in the given windows certificate store. More...

int	toWindowsStoreWithPrivateKey (WindowsStoreLocation location, const UaString &sStoreName, const UaPkiRsaKeyPair &subjectKeyPair) const
	Stores the certificate and its private key in the given windows certificate store. More...

Static Public Member Functions
static UaByteArray	thumbPrint (const UaByteArray &DERData)
	Creates the SHA1 thumbprint of the DER encoded certificate data. More...

static UaPkiCertificate	fromDER (const UaByteArray &DERdata)
	Loads a certificate from a DER encoded byte array. More...

static UaPkiCertificate	fromDER (const UaByteString &DERdata)
	Loads a certificate from a DER encoded bytestring. More...

static UaPkiCertificate	fromDERFile (const char *szFile)
	Loads a certificate from a DER encoded file. More...

static UaPkiCertificate	fromDERFile (const UaString &sFile)
	Loads a certificate from a DER encoded file. More...

static UaPkiCertificate	fromPEMFile (const char *szFile)
	Loads a certificate from a PEM encoded file. More...

static UaPkiCertificate	fromPEMFile (const UaString &sFile)
	Loads a certificate from a PEM encoded file. More...

static UaPkiCSR	createCSR (const UaPkiCertificateInfo &info, const UaPkiIdentity &subject, const UaPkiRsaKeyPair &subjectKeyPair, SignatureAlgorithm signatureAlgorithm, bool bCACert=false)
	Creates a certificate signing request based on the passed parameters. More...

static UaPkiCertificate	fromCSR (const UaPkiCSR &inCSR, const UaPkiCertificate &issuerCert, const UaPkiPrivateKey &issuerPrivateKey, long validTime, long serialNumber, SignatureAlgorithm signatureAlgorithm)
	Creates and signs a certificate based on the passed signing request. More...

static UaPkiCertificate	fromWindowsStore (WindowsStoreLocation location, const UaString &sStoreName, const UaByteArray &baThumbprint)
	Gets a certificate from the given windows certificate store. More...

static UaPkiCertificate	fromWindowsStoreWithPrivateKey (WindowsStoreLocation location, const UaString &sStoreName, const UaByteArray &baThumbprint, UaPkiRsaKeyPair &subjectKeyPair)
	Gets a certificate and its private key from the given windows certificate store. More...

static int	deleteFromWindowsStore (WindowsStoreLocation location, const UaString &sStoreName, const UaByteArray &baThumbprint)
	Deletes a certificate from the given windows certificate store. More...

static UaPkiCertificate	nextCertInWindowsStore (WindowsStoreLocation location, const UaString &sStoreName, const UaPkiCertificate &previous=UaPkiCertificate())
	Iterates over the certificates in a windows certificate store. More...

static UaDateTime	convertAsn1UtcTimeToDateTime (const char szAsn1UtcTime, bool pbOK=0)
	Converts an ASN.1 UTC Time String to a OPC UA DateTime. More...

static UaDateTime	convertAsn1GeneralizedTimeToDateTime (const char szAsn1GeneralizedTime, bool pbOK=0)
	Converts an ASN.1 Generalized Time String to a OPC UA DateTime. More...

Detailed Description

Class for handling X509 certificates.

This class encapsulates OpenSSL X509 functionality and simplifies the certificate handling.

The following sample code demonstrates how to create a self signed certificate:

UaPkiIdentity        ident;
UaPkiCertificateInfo info;
int                  bits = 2048;
ident.commonName = "MyGreatUaApp";
ident.organization = "ACME";
ident.organizationUnit = "Development Department";
ident.locality = "Schwabach";
ident.state = "Bavaria";
ident.country = "DE";
info.URI = "urn:myhostname:ACME:MyGreatUaApp";
info.IP = ""; // optional IP of no DNS is available
info.DNS = "opcua.acme.com";
info.validTime = 3600*24*365*5; // 5 years
info.serialNumber = 123;
// create key pair
UaPkiRsaKeyPair keyPair(bits);
// store key pair in a PEM encoded file without password
keyPair.toPEMFile("/path/to/mykey.pem", 0);
// create new certificate
UaPkiCertificate newCert(info, ident, keyPair);
// store certificate in a DER encoded file
newCert.toDERFile("/path/to/mycert.der");

The following sample code demonstrates how to store a certificate as file, e.g. in the application trust list:

void storeTrustedCertificate(const UaByteString& trustedCertificate, const UaString& sTrustListLocation)
{
    // Assign certificate byte string to UaPkiCertificate class
    UaByteArray      derCertificate(*(const OpcUa_ByteString*)trustedCertificate);
    UaPkiCertificate cert = UaPkiCertificate::fromDER(derCertificate);
    // Create file name for the certificate
    // Use the thumbprint as file name
    UaString sThumbPrint = cert.thumbPrint().toHex();
    UaString sFileName = sTrustListLocation;
    sFileName += "/";
    sFileName += sThumbPrint;
    sFileName += ".der";
    // Store certificate
    cert.toDERFile(sFileName.toUtf8());
}

Constructor & Destructor Documentation

UaPkiCertificate::UaPkiCertificate	(	const UaPkiCertificateInfo &	info,
		const UaPkiIdentity &	subject,
		const UaPkiRsaKeyPair &	subjectKeyPair,
		bool	bCACert = `false`,
		SignatureAlgorithm	signatureAlgorithm = `SignatureAlgorithm_Sha256`
	)

Creates a new self-signed certificate.

Use this constructor for creating self-signed and CA certificates.

Parameters

[in]	info	UA Application information.
[in]	subject	The identity of the certificate owner.
[in]	subjectKeyPair	The key pair of the certificate owner.
[in]	bCACert	If false (default), a self-signed certificate is created; if true, a CA certificate is created.
[in]	signatureAlgorithm	The algorithm used to sign the certificate. Default is SignatureAlgorithm_Sha256.

UaPkiCertificate::UaPkiCertificate	(	const UaPkiCertificateInfo &	info,
		const UaPkiIdentity &	subject,
		const UaPkiPublicKey &	subjectPublicKey,
		const UaPkiCertificate &	issuerCert,
		const UaPkiPrivateKey &	issuerPrivateKey,
		bool	bCACert = `false`,
		SignatureAlgorithm	signatureAlgorithm = `SignatureAlgorithm_Sha256`
	)

Creates a certificate signed by the passed issuer.

Use this constructor for creating CA signed certificates.

Parameters

[in]	info	UA Application information.
[in]	subject	The identity of the certificate owner.
[in]	subjectPublicKey	The public key of the certificate owner.
[in]	issuerCert	The issuer's certificate.
[in]	issuerPrivateKey	The issuer's private key for signing the new certificate.
[in]	bCACert	If false (default), an end entity certificate is created; if true, a CA certificate is created.
[in]	signatureAlgorithm	The algorithm used to sign the certificate. Default is SignatureAlgorithm_Sha256.

Member Function Documentation

UaString UaPkiCertificate::commonName ( ) const

Returns the certificate's commonName field.

This functions is provided for convenience and returns the same as UaPkiCertificate::subject().commonName.

UaDateTime UaPkiCertificate::convertAsn1GeneralizedTimeToDateTime	(	const char *	szAsn1GeneralizedTime,
		bool *	pbOK = `0`
	)

static

Converts an ASN.1 Generalized Time String to a OPC UA DateTime.

This is done by converting the ASN.1 Generalized Format (YYYYMMDDHHMMSS.fffZ) to an ISO8601 String ("YYYY-MM-DDThh:mm:ssZ") and then calling OpcUa_DateTime_GetDateTimeFromString().

UaDateTime UaPkiCertificate::convertAsn1UtcTimeToDateTime	(	const char *	szAsn1UtcTime,
		bool *	pbOK = `0`
	)

static

Converts an ASN.1 UTC Time String to a OPC UA DateTime.

This is done by converting the ASN.1 UTC Format (YYMMDDHHMMSSZ) to an ISO8601 String ("YYYY-MM-DDThh:mm:ssZ") and then calling OpcUa_DateTime_GetDateTimeFromString().

UaString UaPkiCertificate::createCertificateFilePath ( const UaString & basePath ) const

Creates a filepath that can be used to save a certificate to a file.

The fileName is created by appending the thumprint and the file extension ".der" to the commonName. The CertificateFilePath is created by appending the fileName to the basePath followed by a separator. Any characters that are not allowed in a fileName are removed from the commonName before. Example: C:-machine [D9041C0B5896C4BD3C7E814F4684D751DC3004CC].der

Returns: the file path for the certificate

UaPkiCSR UaPkiCertificate::createCSR	(	const UaPkiPrivateKey &	subjectPrivateKey,
		SignatureAlgorithm	signatureAlgorithm
	)

Creates a certificate signing request.

All fields of the CSR are filled using the information contained in the certificate.

Parameters

subjectPrivateKey	The private key matching the certificate, needed for signing the CSR.
signatureAlgorithm	The algorithm used to sign the certificate.

Returns: The created CSR.

UaPkiCSR UaPkiCertificate::createCSR	(	const UaPkiCertificateInfo &	info,
		const UaPkiIdentity &	subject,
		const UaPkiRsaKeyPair &	subjectKeyPair,
		SignatureAlgorithm	signatureAlgorithm,
		bool	bCACert = `false`
	)

static

Creates a certificate signing request based on the passed parameters.

Parameters

info	UA Application information.
subject	The identity of the certificate owner.
subjectKeyPair	The key pair of the certificate owner; the public key is included in the CSR, the private key is only needed for signing it.
signatureAlgorithm	The algorithm used to sign the certificate.
bCACert	If false (default), a self-signed certificate is created; if true, a CA certificate is created.

Returns: The created CSR.

int UaPkiCertificate::deleteFromWindowsStore	(	WindowsStoreLocation	location,
		const UaString &	sStoreName,
		const UaByteArray &	baThumbprint
	)

static

Deletes a certificate from the given windows certificate store.

Returns: Returns 0 if the method succeeded, otherwise -1.

Parameters

[in]	location	The system store location.
[in]	sStoreName	The name of the certificate store to search in.
[in]	baThumbprint	The thumbprint of the certificate to delete.

UaPkiCertificate UaPkiCertificate::fromCSR	(	const UaPkiCSR &	inCSR,
		const UaPkiCertificate &	issuerCert,
		const UaPkiPrivateKey &	issuerPrivateKey,
		long	validTime,
		long	serialNumber,
		SignatureAlgorithm	signatureAlgorithm
	)

static

Creates and signs a certificate based on the passed signing request.

Parameters

inCSR	The CSR to create the certificate from.
issuerCert	The certificate of the issuer that signs the new certificate.
issuerPrivateKey	The private key of the issuer used for signing the new certificate.
validTime	The time in seconds this certificate should be valid.
serialNumber	The serial number of the certificate. If set to 0, the return value of time() is used.
signatureAlgorithm	The algorithm used to sign the certificate.

Returns: The created certificate.

UaPkiCertificate UaPkiCertificate::fromDER ( const UaByteArray & DERdata )

static

Loads a certificate from a DER encoded byte array.

Returns: A new UaPkiCertificate instance.

Parameters

[in] DERdata The DER data; typically received from the OPC UA protocol.

UaPkiCertificate UaPkiCertificate::fromDER ( const UaByteString & DERdata )

static

Loads a certificate from a DER encoded bytestring.

Returns: A new UaPkiCertificate instance.

Parameters

[in] DERdata The DER data; typically received from the OPC UA protocol.

UaPkiCertificate UaPkiCertificate::fromDERFile ( const char * szFile )

static

Loads a certificate from a DER encoded file.

Returns: A new UaPkiCertificate instance.

Parameters

[in] szFile The file name (local 8 bit encoding).

UaPkiCertificate UaPkiCertificate::fromDERFile ( const UaString & sFile )

static

Loads a certificate from a DER encoded file.

Returns: A new UaPkiCertificate instance.

Parameters

[in] sFile The file name (UTF8 encoding).

UaPkiCertificate UaPkiCertificate::fromPEMFile ( const char * szFile )

static

Loads a certificate from a PEM encoded file.

Returns: A new UaPkiCertificate instance.

Parameters

[in] szFile The file name (local 8 bit encoding).

UaPkiCertificate UaPkiCertificate::fromPEMFile ( const UaString & sFile )

static

Loads a certificate from a PEM encoded file.

Returns: A new UaPkiCertificate instance.

Parameters

[in] sFile The file name (UTF8 encoding).

UaPkiCertificate UaPkiCertificate::fromWindowsStore	(	WindowsStoreLocation	location,
		const UaString &	sStoreName,
		const UaByteArray &	baThumbprint
	)

static

Gets a certificate from the given windows certificate store.

Returns: The certificate if it has been found. Else, a NULL certificate is returned.

Parameters

[in]	location	The system store location.
[in]	sStoreName	The name of the certificate store to search in.
[in]	baThumbprint	The thumbprint of the certificate to load.

UaPkiCertificate UaPkiCertificate::fromWindowsStoreWithPrivateKey	(	WindowsStoreLocation	location,
		const UaString &	sStoreName,
		const UaByteArray &	baThumbprint,
		UaPkiRsaKeyPair &	subjectKeyPair
	)

static

Gets a certificate and its private key from the given windows certificate store.

Returns: The certificate if it has been found. Else, a NULL certificate is returned.

Parameters

[in]	location	The system store location.
[in]	sStoreName	The name of the certificate store to search in.
[in]	baThumbprint	The thumbprint of the certificate to load.
[out]	subjectKeyPair	This will contain the certificate's private key on success.

UaPkiCertificateInfo UaPkiCertificate::info ( ) const

Returns information from the X509v3 extension subjectAltName.

This function does not fill UaPkiCertificateInfo::validTime, use validFrom() and validTo() functions instead.

UaPkiIdentity UaPkiCertificate::issuer ( ) const

Returns the certificate issuer identity.

bool UaPkiCertificate::isValid ( ) const

Returns true if the the certificate is valid and not expired.

UaPkiCertificate UaPkiCertificate::nextCertInWindowsStore	(	WindowsStoreLocation	location,
		const UaString &	sStoreName,
		const UaPkiCertificate &	previous = `UaPkiCertificate()`
	)

static

Iterates over the certificates in a windows certificate store.

Returns: The certificate if one has been found. Else, a NULL certificate is returned.

Parameters

[in]	location	The system store location.
[in]	sStoreName	The name of the certificate store to get the certificate from.
[in]	previous	This parameter must be an empty UaPkiCertificate on the first call of the function. Set this parameter to the certificate returned by the last call of this function to get the next certificate in the store.

UaPkiCertificate & UaPkiCertificate::operator= ( const UaPkiCertificate & copy )

Assigns another UaPkiCertificate to the current instance.

Parameters

copy	An existing UaPkiCertificate structure.

Returns: The current instance

bool UaPkiCertificate::operator== ( const UaPkiCertificate & other )

Compares the current instance to another certificate.

Returns: True if no certificate is NULL and both have the same content

UaPkiPublicKey UaPkiCertificate::publicKey ( ) const

Returns the public key of the certificate.

UaString UaPkiCertificate::serialNumber ( ) const

Returns the certificate's serial number.

Returns: The serial number as hex encoded string.

bool UaPkiCertificate::sign	(	const UaPkiCertificate &	issuerCert,
		const UaPkiPrivateKey &	issuerPrivateKey,
		SignatureAlgorithm	signatureAlgorithm = `SignatureAlgorithm_Sha256`
	)

Signs the certificate using the passed certificate and private key.

Replaces the certificate issuer and all affected certificate extensions.

Returns: True if signing was successful.

UaPkiIdentity UaPkiCertificate::subject ( ) const

Returns the certificate subject identity.

UaByteArray UaPkiCertificate::thumbPrint ( ) const

Creates the SHA1 thumbprint of the certificate.

Returns: A UaByteArray containing the thumbprint of the certificate.

UaByteArray UaPkiCertificate::thumbPrint ( const UaByteArray & DERData )

static

Creates the SHA1 thumbprint of the DER encoded certificate data.

This method is provided for convenience but behaves like the function above. This avoid the temporary creation of an UaPkiCertificate instance if you have already DER encoded data.

Returns: A UaByteArray containing the thumbprint of the certificate.

Parameters

[in] DERData The DER encoded certificate.

UaByteString UaPkiCertificate::toByteStringDER ( ) const

Encodes the certificate in DER format.

This is used to send a certificate over OPC UA.

Returns: UaByteString with DER data.

UaByteArray UaPkiCertificate::toDER ( ) const

Encodes the certificate in DER format.

This is used to send a certificate over OPC UA.

Returns: UaByteArray with DER data.

int UaPkiCertificate::toDERFile ( const char * szFile ) const

Stores the certificate in a DER encoded file.

This is used for certificate management.

Returns: error code

Parameters

[in] szFile The file name of the DER encoded file to create (local 8 bit encoding).

int UaPkiCertificate::toDERFile ( const UaString & sFile ) const

Stores the certificate in a DER encoded file.

This is used for certificate management.

Returns: error code

Parameters

[in] sFile The file name of the DER encoded file to create (UTF8 encoding).

int UaPkiCertificate::toPEMFile ( const char * szFile ) const

Stores the certificate in a PEM encoded file.

This is used for certificate management.

Returns: error code

Parameters

[in] szFile The file name of the PEM encoded file to create (local 8 bit encoding).

int UaPkiCertificate::toPEMFile ( const UaString & sFile ) const

Stores the certificate in a PEM encoded file.

This is used for certificate management.

Returns: error code

Parameters

[in] sFile The file name of the PEM encoded file to create (UTF8 encoding).

int UaPkiCertificate::toWindowsStore	(	WindowsStoreLocation	location,
		const UaString &	sStoreName
	)		const

Stores the certificate in the given windows certificate store.

The windows certificate store identifies the certificate by all its information, so no name parameter is needed.

Returns: Returns 0 if the method succeeded, otherwise -1.

Parameters

[in]	location	The system store location.
[in]	sStoreName	The name of the certificate store to use.

int UaPkiCertificate::toWindowsStoreWithPrivateKey	(	WindowsStoreLocation	location,
		const UaString &	sStoreName,
		const UaPkiRsaKeyPair &	subjectKeyPair
	)		const

Stores the certificate and its private key in the given windows certificate store.

The windows certificate store identifies the certificate by all its information, so no name parameter is needed. If the store does not exist it will be created.

Returns: Returns 0 if the method succeeded, otherwise -1.

Parameters

[in]	location	The system store location.
[in]	sStoreName	The name of the certificate store to use.
[in]	subjectKeyPair	The key pair of the certificate subject to store with the certificate.

UaDateTime UaPkiCertificate::validFrom ( ) const

Returns the start date of the certificate's valid time period.

UaDateTime UaPkiCertificate::validTo ( ) const

Returns the end date of the certificate's valid time period.

The documentation for this class was generated from the following files:

C:/work/uasdkcpp/src/uabase/uapkicpp/uapkicertificate.h
C:/work/uasdkcpp/src/uabase/uapkicpp/uapkicertificate.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation