Back to Aurora Vision Library Lite website

You are here: Start » System » OPC UA » OPCUAClient_SetupSecurityCertificates

OPCUAClient_SetupSecurityCertificates


Header: STD.h
Namespace: avl

Configures the security layers of OPC UA client to server connections for this application

Syntax

void avl::OPCUAClient_SetupSecurityCertificates
(
	const atl::String& inApplicationURI,
	const atl::File& inApplicationCertificate,
	const atl::File& inPrivateKey,
	const atl::Directory& inTrustedCertStore,
	const atl::Directory& inIssuerCertStore,
	const atl::Directory& inRevokedCertStore,
	avl::OpcUaCertificateHandling::Type inCertificateAction
)

Parameters

Name Type Default Description
Input value inApplicationURI const String& The URI identifying this application instance that the certificate refers to
Input value inApplicationCertificate const File& Path to this applications public certificate file
Input value inPrivateKey const File& Path to this applications private key file
Input value inTrustedCertStore const Directory& Path to the directory containing trusted certificate files (.crt, .pem or .der files)
Input value inIssuerCertStore const Directory& Path to the directory containing certificate files of trusted certificate issuers (.crt, .pem or .der files)
Input value inRevokedCertStore const Directory& Path to the directory containing revoked certificate list files for certificate issuers (.crl files)
Input value inCertificateAction OpcUaCertificateHandling::Type Verify Local application certificate verification and creation action to take during the security settings initialization

Description

This filter must be invoked before OPCUAClient_Connect filters when encryption, signing and/or client/server identity verification is required on the OPC UA connections. Only one instance of this filter is required in the program, even when working with multiple OPC UA connections.

The purpose of this filter is to set up the client's security certificate, security related configuration and the server certificate verification chain.

All certificates referenced to this filter (both client certificate and server verification chain) must be in the X.509 version 3 format and stored in files in PEM or DER container formats.

Please note that this filter performs minimal verifications of the input data and certificate contents. Most configuration and/or certificate related errors will manifest itself during the connection attempt (after invoking the OPCUAClient_Connect filter).

The inApplicationURI input (required) must specify the OPC UA Application URI that the client will identify itself with to the server. This URI is usually specified in the Uniform Resource Name (URN) format (e.g. "urn:my_application_domain:my_application_name"). This URI must match the URI in the Subject Alternative Name field of the client application certificate.

The inApplicationCertificate and inPrivateKey inputs (required) specify paths to the application public certificate and the private key files accordingly.

The inTrustedCertStore input (required) specifies a path to the directory containing trusted certificate files. All files with extension .pem, .der, .cer and .crt in this directory are loaded and considered trusted when verifying the server certificates.

The inIssuerCertStore input (optional) specifies a path to the directory containing issuers certificate files. All files with extension .pem, .der, .cer and .crt in this directory are loaded and used in verification of server certificates.

The inRevokedCertStore input (required when inIssuerCertStore is specified) specifies a path to the directory containing certificate revocation list files. A single revocation file must have the extension .crl and must correspond to a single issuer certificate in the issuers certificate store.

The inCertificateAction input determines if this filter should perform verification of the local application certificate and private key pair specified by the inApplicationCertificate and inPrivateKey inputs, and what actions to perform depending of the verification results:

  • None - This filter will not attempt to load and will not perform any verification of the application certificate. Lack of the certificate files or invalid certificate will still result in an error during a connection attempt.
  • Verify - This filter will load and verify the application public certificate and private key for validity, consistency with the OPC UA requirements and consistency with the application configuration. Missing files and verification errors will be immediately reported with an IOError exception.
  • VerifyAndCreateMissing - similar to Verify, but when the public certificate file does not exists this filter, instead of reporting an error, will attempt to generate a new public certificate and private key pair, and save them in the files specified on the inApplicationCertificate and inPrivateKey inputs (see below for details). The filter will still report an error when the certificate exists and is invalid.
  • VerifyAndRecreateExpired - similar to VerifyAndCreateMissing, but the public certificate and private key will also be automatically recreated and overridden when the existing (and otherwise valid) certificate is expired.

When automatically creating a new application certificate this filter will create a self signed certificate with 2048bit RSA key, valid for 5 years and compatible with the application URI specified on the inApplicationURI input. This certificate will have to be manually trusted on the OPC UA server after automatic creation or recreation.

Errors

This filter will throw a DomainError exception when any of the required inputs is left empty or when any of the certificate store directories, pointed to by the inputs, does not exists, and IOError exception when optional local application certificate verification fails.

See Also