UA Part 6: Mappings - Annex E (informative)Security settings management

Annex E (informative)Security settings management

All OPC UA applications support security; and this means that Administrators need to configure the security settings for the OPC UA application. Clause E.1 describes an XML Schema which can be used to read and update the security settings for an OPC UA application. This schema provides a reference for application developers adding support for security configuration to their applications.

The XML Schema released with this version of the standards can be found here:

http://www.opcfoundation.org/UA/schemas/1.05/SecuredApplication.xsd

NOTE The latest file that is compatible with this version of this specification can be found here:

http://opcfoundation.org/UA/2011/03/SecuredApplication.xsd

The SecuredApplication schema can be supported in two ways:

Providing an XML configuration file that can be edited directly;
Providing an import/export utility that can be run as required;

If the application supports direct editing of an XML configuration file, then that file has exactly one element with the local name ‘SecuredApplication’ and URI equal to the SecuredApplication schema URI. A third-party configuration utility is able to parse the XML file, read and update the ‘SecuredApplication’ element. The administrator ensures that only authorized administrators can update this file. The following is an example of a configuration that can be directly edited:

<s1:SampleConfiguration xmlns:s1="http://acme.com/UA/Sample/Configuration.xsd">

<ApplicationName>ACME UA Server</ApplicationName>

<ApplicationUri>urn:myfactory.com:Machine54:ACME UA Server</ApplicationUri>

<ApplicationName>ACME UA Server</ApplicationName>

<ApplicationUri>urn:myfactory.com:Machine54:ACME UA Server</ApplicationUri>

<ApplicationType>Server_0</ApplicationType>

<StoreType>Windows</StoreType>

<StorePath>LocalMachine\My</StorePath>

<SubjectName>ACME UA Server</SubjectName>

</ApplicationCertificate>

</SecuredApplication>

</s1:SampleConfiguration>

If an application provides an import/export utility, then the import/export file is a document that conforms to the SecuredApplication schema. The administrator ensures that only authorized administrators can run the utility. The following is an example of a file used by an import/export utility:

<?xml version="1.0" encoding="utf-8" ?>

<ApplicationName>ACME UA Server</ApplicationName>

<ApplicationUri>urn:myfactory.com:Machine54:ACME UA Server</ApplicationUri>

<ApplicationType>Server_0</ApplicationType>

<ConfigurationMode>urn:acme.com:ACME Configuration Tool</ConfigurationMode>

<ExecutableFile>%ProgramFiles%\ACME\Bin\ACME UA Server.exe</ExecutableFile>

<StoreType>Windows</StoreType>

<StorePath>LocalMachine\My</StorePath>

<SubjectName>ACME UA Server</SubjectName>

</ApplicationCertificate>

<StoreType>Windows</StoreType>

<StorePath>LocalMachine\UA applications</StorePath>

</TrustedCertificateStore>

<SubjectName>CN=MyFactory CA</SubjectName>

</CertificateIdentifier>

</Certificates>

</TrustedCertificates>

<StoreType>Directory</StoreType>

<StorePath>%CommonApplicationData%\OPC Foundation\RejectedCertificates</StorePath>

</RejectedCertificatesStore>

</SecuredApplication>

E.2 SecuredApplication

The SecuredApplication element specifies the security settings for an application. The elements contained in a SecuredApplication are described in Table E.1.

When an instance of a SecuredApplication is imported into an application the application updates its configuration based on the information contained within it. If unrecoverable errors occur during import an application does not make any changes to its configuration and report the reason for the error.

The mechanism used to import or export the configuration depends on the application. Applications ensure that only authorized users are able to access this feature.

The SecuredApplication element may reference X.509 v3 Certificates which are contained in physical stores. Each application needs to decide whether it uses shared physical stores which the administrator can control directly by changing the location or private stores that can only be accessed via the import/export utility. If the application uses private stores, then the contents of these private stores are copied to the export file during export. If the import file references shared physical stores, then the import/export utility copies the contents of those stores to the private stores.

The import/export utility does not export private keys. If the administrator wishes to assign a new public-private key to the application the administrator places the private key in a store where it can be accessed by the import/export utility. The import/export utility is then responsible for ensuring it is securely moved to a location where the application can access it.

Table E.1 – SecuredApplication

Element	Type	Description
ApplicationName	String	A human readable name for the application. Applications allow this value to be read or changed.
ApplicationUri	String	A globally unique identifier for the instance of the application. Applications allow this value to be read or changed.
ApplicationType	ApplicationType	The type of application. May be one of Server_0; Client_1; ClientAndServer_2; DiscoveryServer_3; Applications do not provide this value. Applications do not allow this value to be changed.
ProductName	String	A name for the product. Applications provide this value. Applications do not allow this value to be changed.
ConfigurationMode	String	Indicates how the application should be configured. An empty or missing value indicates that the configuration file can be edited directly. The location of the configuration file is not provided in this case. Any other value is a URI that identifies the configuration utility. The vendor documentation explains how to use this utility. Applications provide this value. Applications do not allow this value to be changed.
LastExportTime	UtcTime	When the configuration was exported by the import/export utility. It may be omitted if applications allow direct editing of the security configuration.
ConfigurationFile	String	The full path to a configuration file used by the application. Applications do not provide this value if an import/export utility is used. Applications do not allow this value to be changed. Permissions set on this file control who has rights to change the configuration of the application.
ExecutableFile	String	The full path to an executable file for the application. Applications may not provide this value. Applications do not allow this value to be changed. Permissions set on this file control who has rights to launch the application.
ApplicationCertificate	CertificateIdentifier	The identifier for the Application Instance Certificate. Applications allow this value to be read or changed. This identifier may reference a Certificate store that contains the private key. If the private key is not accessible to outside applications this value contain the X.509 v3 Certificate for the application. If the configuration utility assigns a new private key this value reference the store where the private key is placed. The import/export utility may delete this private key if it moves it to a secure location accessible to the application. Applications allow Administrators to enter the password required to access the private key during the import operation. The exact mechanism depends on the application. Applications report an error if the ApplicationCertificate is not valid.
TrustedCertificateStore	CertificateStoreIdentifier	The location of the CertificateStore containing the Certificates of applications or Certificate Authorities (CAs) which can be trusted. Applications allow this value to be read or changed. This value is a reference to a physical store which can be managed separately from the application. applications that support shared physical stores check this store for changes whenever they validate a Certificate. The Administrator is responsible for verifying the signature on all Certificates placed in this store. This means the application may trust Certificates in this store even if they cannot be verified back to a trusted root. Administrators place any CA certificates used to verify the signature in the IssuerStore or the IssuerList. This will allow applications to properly verify the signatures. The application check the revocation status of the Certificates in this store if the Certificate was issued by a CA. The application looks for the offline Certificate Revocation List (CRL) for a CA in the store where it found the CA Certificate. The location of an online CRL for CA is specified with the CRLDistributionPoints (OID= 2.5.29.31) X.509 v3 Certificate extension. The ValidationOptions parameter is used to specify which revocation list should be used for CAs in this store.
TrustedCertificates	CertificateList	A list of Certificates for applications for CAs that can be trusted. Applications allow this value to be read or changed. The value is an explicit list of Certificates which is private to the application. It is used when the application does not support shared physical Certificate stores or when Administrators need to specify ValidationOptions for individual Certificates. If the TrustedCertificateStore and the TrustedCertificates parameters are both specified, then the application uses the TrustedCertificateStore for checking trust relationships. The TrustedCertificates parameter is only used to lookup ValidationOptions for individual Certificates. It may also be used to provide CRLs for CA certificates. If the TrustedCertificateStore is not specified, then TrustedCertificates parameter contains the complete X.509 v3 Certificate for each entry.
IssuerStore	CertificateStoreIdentifier	The location of the CertificateStore containing CA Certificates which are not trusted but are needed to check signatures on Certificates. Applications allow this value to be read or changed. This value is a reference to a physical store which can be managed separately from the application. Applications that support shared physical stores check this store for changes whenever they validate a Certificate. This store may also contain CRLs for the CAs.
IssuerCertificates	CertificateList	A list of Certificates for CAs which are not trusted but are needed to check signatures on Certificates. Applications allow this value to be read or changed. The value is an explicit list of Certificates which is private to the application. It is used when the application does not support shared physical Certificate stores or when Administrators need to specify ValidationOptions for individual Certificates. If the IssuerStore and the IssuerCertificates parameters are both specified, then the application uses the IssuerStore for checking signatures. The IssuerCertificates parameter is only used to lookup ValidationOptions for individual Certificates. It may also be used to provide CRLs for CA certificates.
RejectedCertificatesStore	CertificateStoreIdentifier	The location of the shared CertificateStore containing the Certificates of applications which were rejected. Applications allow this value to be read or changed. Applications add the DER encoded Certificate into this store whenever it rejects a Certificate because it is untrusted or if it failed one of the validation rules which can be suppressed (see Clause E.6). Applications do not add a Certificate to this store if it was rejected for a reason that cannot be suppressed (e.g. Certificate revoked).
BaseAddresses	String []	A list of URLs for the Endpoints supported by a Server. Applications allow these values to be read or changed. If a Server does not support the scheme for a URL it ignores it. This list can have multiple entries for the same URL scheme. The first entry for a scheme is the base URL. The rest are assumed to be DNS aliases that point to the first URL. It is the responsibility of the Administrator to configure the network to route these aliases correctly.
SecurityProfileUris	SecurityProfile []	A list of SecurityPolicyUris supported by a Server. The URIs are defined as security Profiles in OPC 10000-7. Applications allow these values to be read or changed. Applications allow the Enabled flag to be changed for each SecurityProfile that it supports. If the Enabled flag is false, the Server do not allow connections using the SecurityProfile. If a Server does not support a SecurityProfile it ignores it.
Extensions	xs:any []	A list of vendor defined Extensions attached to the security settings. Applications ignore Extensions that they do not recognize. Applications that update a file containing Extensions do not delete or modify extensions that they do not recognize.

E.3 CertificateIdentifier

The CertificateIdentifier element describes an X.509 v3 Certificate. The Certificate can be provided explicitly within the element or the element can specify the location of the CertificateStore that contains the Certificate. The elements contained in a CertificateIdentifier are described in Table E.2.

Table E.2 – CertificateIdentifier

Element	Type	Description
StoreType	String	The type of CertificateStore that contains the Certificate. Predefined values are "Windows" and "Directory". If not specified, the RawData element is specified.
StorePath	String	The path to the CertificateStore. The syntax depends on the StoreType. If not specified, the RawData element is specified.
SubjectName	String	The SubjectName for the Certificate. The Common Name (CN) component of the SubjectName. The SubjectName represented as a string that complies with Section 3 of RFC 4514. Values that do not contain '=' characters are presumed to be the Common Name component.
Thumbprint	String	The CertificateDigest for the Certificate formatted as a hexadecimal string. Case is not significant.
RawData	ByteString	The DER encoded Certificate. The CertificateIdentifier is invalid if the information in the DER Certificate conflicts with the information specified in other fields. Import utilities reject configurations containing invalid Certificates. This field is not specified if the StoreType and StorePath are specified.
ValidationOptions	Int32	The options to use when validating the Certificate. The possible options are described in E.6.
OfflineRevocationList	ByteString	A Certificate Revocation List (CRL) associated with an Issuer Certificate. The format of a CRL is defined by RFC 5280. This field is only meaningful for Issuer Certificates.
OnlineRevocationList	String	A URL for an Online Revocation List associated with an Issuer Certificate. This field is only meaningful for Issuer Certificates.

A "Windows" StoreType specifies a Windows Certificate store.

The syntax of the StorePath has the form:

[\\HostName\]StoreLocation[\(ServiceName | UserSid)]\StoreName

where:

HostName – the name of the machine where the store resides.

StoreLocation – one of LocalMachine, CurrentUser, User or Service

ServiceName – the name of a Windows Service.

UserSid – the SID for a Windows user account.

StoreName – the name of the store (e.g. My, Root, Trust, CA, etc.).

Examples of Windows StorePaths are:

\\MYPC\LocalMachine\My

\CurrentUser\Trust

\\MYPC\Service\My UA Server\UA applications

\User\S-1-5-25\Root

A "Directory" StoreType specifies a directory on disk which contains files with DER encoded Certificates. The name of the file is the CertificateDigest for the Certificate. Only public keys may be placed in a "Directory" Store. The StorePath is an absolute file system path with a syntax that depends on the operating system.

If a "Directory" store contains a ‘certs’ subdirectory, then it is presumed to be a structured store with the subdirectories described in Table E.3.

Table E.3 – Structured directory store

Subdirectory	Description
certs	Contains the DER encoded X.509 v3 Certificates. The files have a .der file extension.
private	Contains the private keys. The format of the file may be application specific. PEM encoded files should have a .pem extension. PKCS#12 encoded files should have a .pfx extension. The root file name is the same as the corresponding public key file in the certs directory.
crl	Contains the DER encoded CRL for any CA Certificates found in the certs or ca directories. The files have a .crl file extension.

Each Certificate is uniquely identified by its Thumbprint. The SubjectName or the distinguished SubjectName may be used to identify a Certificate to a human; however, they are not unique. The SubjectName may be specified in conjunction with the Thumbprint or the RawData. If there is an inconsistency between the information provided, then the CertificateIdentifier is invalid. Invalid CertificateIdentifiers are handled differently depending on where they are used.

It is recommended that the SubjectName always be specified.

A Certificate revocation list (CRL) contains a list of certificates issued by a CA that are no longer trusted. These lists should be checked before an application can trust a Certificate issued by a trusted CA. The format of a CRL is defined by RFC 5280.

Offline CRLs are placed in a local Certificate store with the Issuer Certificate. Online CRLs may exist but the protocol depends on the system. An online CRL is identified by a URL.

E.4 CertificateStoreIdentifier

The CertificateStoreIdentifier element describes a physical store containing X.509 v3 Certificates. The elements contained in a CertificateStoreIdentifier are described in Table E.4.

Table E.4 – CertificateStoreIdentifier

Element	Type	Description
StoreType	String	The type of CertificateStore that contains the Certificate. Predefined values are "Windows" and "Directory".
StorePath	String	The path to the CertificateStore. The syntax depends on the StoreType. See E.3 for a description of the syntax for different StoreTypes.
ValidationOptions	CertificateValidationOptions	The options to use when validating the Certificates contained in the store. The possible options are described in E.6.

All Certificates are placed in a physical store which can be protected from unauthorized access. The implementation of a store can vary and will depend on the application, development tool or operating system. A Certificate store may be shared by many applications on the same machine.

Each Certificate store is identified by a StoreType and a StorePath. The same path on different machines identifies a different store.

E.5 CertificateList

The CertificateList element is a list of Certificates. The elements contained in a CertificateList are described in Table E.5.

Table E.5 – CertificateList

Element	Type	Description
Certificates	CertificateIdentifier []	The list of Certificates contained in the Trust List
ValidationOptions	CertificateValidationOptions	The options to use when validating the Certificates contained in the store. These options only apply to Certificates that have ValidationOptions with the UseDefaultOptions bit set. The possible options are described in E.6.

E.6 CertificateValidationOptions

The CertificateValidationOptions control the process used to validate a Certificate. Any Certificate can have validation options associated. If none are specified, the ValidationOptions for the store or list containing the Certificate are used. The possible options are shown in Table E.6. Note that suppressing any validation step can create security risks which are discussed in more detail in OPC 10000-2. An audit log entry is created if any error is ignored because a validation option is suppressed.

Table E.6 – CertificateValidationOptions

Field	Bit	Description
SuppressCertificateExpired	0	Ignore errors related to the validity time of the Certificate or its issuers.
SuppressHostNameInvalid	1	Ignore mismatches between the host name or ApplicationUri.
SuppressRevocationStatusUnknown	2	Ignore errors if the issuer’s revocation list cannot be found.
CheckRevocationStatusOnline	3	Check the revocation status online. If set, the validator will look for the authorityInformationAccess extension to find an OCSP (RFC 6960) endpoint which can be used to determine if the Certificate has been revoked. If the OCSP endpoint is not reachable then the validator will look for offline CRLs if the CheckRevocationStatusOffline bit is set. Otherwise, validation fails. This option is specified for Issuer Certificates and used when validating Certificates issued by that Issuer.
CheckRevocationStatusOffline	4	Check the revocation status offline. If set the validator will look a CRL in the Certificate Store where the CA Certificate was found. Validation fails if a CRL is not found. This option is specified for Issuer Certificates and used when validating Certificates issued by that Issuer.
UseDefaultOptions	5	If set the CertificateValidationOptions from the CertificateList is used. If a Certificate does not belong to a CertificateList then the default is 0 for all bits.