Certificate management functions comprise the management and distribution of certificates and Trust Lists for OPC UA Applications. An application that provides the certificate management functions is called CertificateManager. GDS and CertificateManager will typically be combined in one application. The basic concepts regarding Certificate management are described in OPC 10000-2.

There are two primary models for Certificate management: PullManagement and PushManagement. In PullManagement, the application acts as a Client and uses the Methods on the CertificateManager to request and update Certificates and Trust Lists. The application is responsible for ensuring the Certificates and Trust Lists are kept up to date. In PushManagement the application acts as a Server and exposes Methods which the CertificateManager can call to update the Certificates and Trust Lists as required.

The CertificateManager is intended to work in conjunction with different Certificate management services such as Active Directory. The CertificateManager provides a standard OPC UA based information model that all OPC UA Applications can support without needing to know the specifics of a particular Certificate management system.

The CertificateManager should support the following features:

  • Onboarding (first time setup for a device/application);
  • Renewal (renewing expired or compromised certificates);
  • TrustList Update (updating the Trust Lists including the Revocation Lists);
  • Revocation (removing a device/application from the system).

Although it is generally assumed that Client applications will use the Pull model and Server applications will use the Push model, this is not required.

OPC 10000-21 defines the complete process to automatically authenticate and onboard new Devices that depends on the Devices having support built in by the Manufacturer. If this support is not present, Devices and OPC UA Applications have to be manually onboarded using the mechanisms defined in this document.

During manual onboarding, the CertificateManager shall be able to operate in a mode where any Client is allowed to connect securely with any valid Certificate and user credentials are used to determine the rights a Client has; this eliminates the need to configure TrustLists before connecting to the CertificateManager for application setup, Application vendors may decide to build the interaction with the CertificateManager as a separate component, e.g. as part of an administration application with access to the OPC UA configuration of this Application. This is transparent for the CertificateManager and will not be considered further in the rest of this chapter.

Clients shall only connect to a CertificateManager which the Client has been configured to trust. This may require an out of band configuration step which is completed prior to starting the manual onboarding process.

This standard does not define how to administer a CertificateManager but a CertificateManager shall provide an integrated system that includes both push and PullManagement.

CertificateManagers restrict access to many of the features they provide. These restrictions are described either by referring to well-known Roles which a Session must have access to or by referring to Privileges which are assigned to Sessions using mechanisms other than the well-known Roles. The well-known Roles used for CertificateManagers are listed in Table 18.

Table 18 – Well-known Roles for a CertificateManager

Name

Description

CertificateAuthorityAdmin

This Role grants rights to request or revoke any Certificate, update any TrustList or assign CertificateGroups to OPC UA Applications.

RegistrationAuthorityAdmin

This Role grants rights to approve Certificate Signing requests or NewKeyPair requests.

SecurityAdmin

This Role grants the right to change the security configuration of a CertificateManager.

The well-known Roles for Server managed by a CertificateManager are listed in Table 19.

Table 19 – Well-known Roles for Server managed by a CertificateManager

Name

Description

SecurityAdmin

For PushManagement, this Role grants the right to change the security configuration of a Server managed by a CertificateManager.

The Privileges used in for CertificateManagers are listed in Table 20.

Table 20 – Privileges for a CertificateManager

Name

Description

ApplicationSelfAdmin

This Privilege grants an OPC UA Application the right to renew its own Certificate or read its own CertificateGroups and TrustLists.

The Certificate used to create the SecureChannel is used to determine the identity of the OPC UA Application.

ApplicationAdmin

This Privilege grants rights to request or renew Certificates, read TrustLists or CertificateGroups for one or more OPC UA Applications.

The Certificate used to create the SecureChannel is used to determine the identity of the OPC UA Application and the set of OPC UA Applications that it is authorized to manage.

PullManagement is performed by using the CertificateManager information model, in particular the Methods defined in 7.9. The interactions between Application and CertificateManager during PullManagement are illustrated in Figure 14.

image017.png

Figure 14 – The Pull Management Model for Certificates

The Application Administration component may be part of the Client or Server or a standalone utility that understands how the application persists its configuration information in its Configuration Database.

A similar process is used to renew certificates or to periodically update Trust List.

Security in PullManagement requires an encrypted channel and authorized credentials. These credentials may be user credentials for a CertificateAuthorityAdmin or application credentials determined by the Certificate used to create the SecureChannel. Examples of the application credentials include Certificates previously issued to the application being accessed, Device Certificates issued by the Registrar defined in OPC 10000-21 or Certificates isssued to an application with accesss to the ApplicationAdmin Privilege (see 6.2).

PushManagement is targeted at Server applications and relies on Methods defined in 7.10 to get a CertificateRequest which can be passed onto the CertificateManager. After the CertificateManager signs the Certificate the new Certificate is pushed to the Server with the UpdateCertificate Method.

The interactions between a Server Application and CertificateManager during PushManagement are illustrated in Figure 15.

image018.png

Figure 15 – The Push Certificate Management Model

The Administration Component may be part of the CertificateManager or a standalone utility that uses OPC UA to communicate with the CertificateManager (see 7.3 for a more complete description of the interactions required for this use case). The Configuration Database is used by the Server to persist its configuration information. The RegisterApplication Method (or internal equivalent) is assumed to have been called before the sequence in the diagram starts.

A similar process is used to renew certificates or to periodically update Trust List.

Security when using the PushManagement model requires an encrypted channel and a Client with access to the SecurityAdmin Role. For example, SecurityAdmin Role could be mapped to user credentials for an administrator or to a ApplicationInstance Certificate issued to a configuration tool. OPC 10000-21 defines a mechanism to install administrative Client Certificates into the Server TrustList.

Application Setup is the initial installation of an OPC UA Server or Client into a system in which a GDS is available and managing Certificates. Applications using a Client interface can be setup using the PullManagement. Applications using a Server interface can be setup using the PushManagement.

The push and PullManagement are also integrated into OPC 10000-21 which specifies how new Devices can be authenticated when they are added to the network. Once a Device is authenticated the Device is trusted and can use the push or PullManagement without additional administrator credentials.

OPC UA Servers that do not support OPC 10000-21 typically auto-generate a self-signed Certificate when they first start. They may also have a pre-configured TrustList with Applications that are allowed to setup the Server. For example, a machine vendor may use a CA that is used to issue Certificates to Applications used by their field technicians.

For embedded devices, the Server should allow any Client that provides the proper SecurityAdmin credentials to create the secure connection needed for setup using PushManagement. Once the Server has been given its initial TrustList the Server should then restrict access to those Clients with Certificates in the Trust List. A vendor specific process for setup is required if a device restricts the Clients allowed to connect securely.

See Annex G for more specific examples of how to provision an application when OPC 10000-21 is not used.

In this workflow the OPC UA Application that gets Certificates from the CertificateManager is the Client that executes the workflow and the CertificateManager is the Server processing the request in the workflow.

The Application is authenticated with the Certificate signed by the CertificateManager (or the Certificate assigned during registration). The UserTokenType is always Anonymous using the ApplicationSelfAdmin Privilege.

The workflow for PullManagement is shown in Figure 16 and the steps are described in Table 21. The two options for the key pair creation are described in Figure 17. The boxes with blue text indicate Method calls.

image019.png

Figure 16 – Certificate Pull Management Workflow

image020.png

Figure 17 – The Pull Management Private Key Options

The steps of the PullManagement workflow are described in detail in Table 21.

Table 21 – Certificate Pull Management Workflow Steps

Step

Description

Certificate management begin options

The following options are possible to start the PullManagement.

  1. Continue application setup using the Session available from the application registration workflow described in 6.5.
  2. Cyclic check of the application status using a new connection to the CertificateManager. The cycle time is defined by the UpdateFrequency on the related TrustList Object in the CertificateManager.

Connect

Create a connection for option (2). For the connection management with the CertificateManager the Services OpenSecureChannel, CreateSession and ActivateSession are used to create a connection with MessageSecurityMode SignAndEncrypt and an Anonymous user.

Application authentication is used by the CertificateManager to allow OPC UA Applications to access the necessary resources to update themselves using the ApplicationSelfAdmin Privilege.

Required information

The OPC UA Application needs to know the following information to execute the PullManagement workflow

SigningRequestPending

If one or more signing requests are pending for a CertificateGroup, the FinishRequest Method is called directly with the ApplicationId and the RequestId for the pending signing request. The repeat count is set to 0 in this case.

GetCertificateStatus

The Method GetCertificateStatus is called with the ApplicationId and the CertificateGroupId to check if a certificate update is needed. This is repeated for each CertificateType needed for the CertificateGroup.

Update Required

If GetCertificateStatus returns updateRequired set to True for one or more combinations of CertificateGroup and CertificateType, the process for key pair creation is started for the affected combinations.

Create CSR

The application creates a certificate signing request (CSR). It is strongly recommended, that the OPC UA Application creates a new private key for each signing request.

StartSigningRequest

The Method StartSigningRequest is called for each CertificateGroup and CertificateType together with the CSR to request a signed Certificate from the CertificateManager. Each Method call needs it’s own CSR.

As alternative for OPC UA Applications who do not have access to a cryptograhically sufficient entropy source, the Method StartNewKeyPairRequest can be used. In this case the private key is created by the CertificateManager.

Both Methods return a RequestId that can be passed to the FinishRequest Method. The repeat count for FinishRequest is set to a small number like 2.

FinishRequest

The Method FinishRequest is called to check the results of a previous StartSigningRequest or StartNewKeyPairRequest.

The following results are possible:

GetTrustList

If all Certificates for a CertificateGroup are up-to-date, the trust list is checked for updates by calling the Method GetTrustList. The Method returns the NodeId of the TrustList Object for the CertificateGroup. The LastUpdateTime of TrustList Object indicates when the contents of the TrustList changed. When using PullManagement, the Client should check this Property before downloading the TrustList.

TrustListType::Read

The NodeId of the TrustList Object returned by GetTrustList is used to open the TrustList for reading and to read the current content of the TrustList.

Persist TrustList

If a TrustList update or Certificate updates are available, they are persisted for further use by the OPC UA Application. They must be persisted at the same time to ensure a consistent setup.

Repeat for all CertificateGroups

Repeat the process for all CertificateGroups.

Disconnect

Disconnect from CertificateManager.

In this workflow the CertificateManager is the Client that executes the steps and the OPC UA Application is the Server that is processing the request in the sequence. The workflow is started if the CertificateManager determines that an update is required.

The workflow for PushManagement is shown in Figure 18. The two options for the key pair creation are described in Figure 19. The boxes with blue text indicate Method calls.

image021.png

Figure 18 – The Certificate Push Management Workflow

image022.png

Figure 19 – The Push Management Private Key Options

The common information model defines types that are used in both the Push and the Pull Model.

This type defines a FileType that can be used to access a Trust List.

The CertificateManager uses this type to implement the Pull Model.

Servers use this type when implementing the Push Model.

An instance of a TrustListType shall restrict access to appropriate users or applications. This may be a CertificateManager administrative user that can change the contents of a Trust List, it may be an Administrative user that is reading a TrustList to deploy to an Application host or it may be an Application that can only access the TrustList assigned to it.

The TrustList file is a UA Binary encoded stream containing an instance of TrustListDataType (see 7.8.2.6).

The Open Method shall not support modes other than Read (0x01) and the Write + EraseExisting (0x06).

If a transaction is in progress (see 7.10.6) then the Server shall return Bad_TransactionPending if Open is called with Write Mode bit set.

Servers shall automatically Close TrustLists if there are no calls to Methods on the TrustList Object within the time specified by the ActivityTimeout Property.

The Size Property inherited from FileType has no meaning for TrustList and returns the error code defined in OPC 10000-20.

When a Client opens the file for writing the Server will not actually update the TrustList until the CloseAndUpdate Method is called. Simply calling Close will discard the updates. The bit masks in TrustListDataType structure allow the Client to only update part of the Trust List.

When the CloseAndUpdate Method is called the Server will validate all new Certificates and CRLs. If this validation fails the TrustList is not updated and the Server returns the appropriate Certificate error code (see OPC 10000-4).

Table 22 – TrustListType Definition

Attribute

Value

BrowseName

0:TrustListType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:FileType defined in OPC 10000-20.

0:HasProperty

Variable

0:LastUpdateTime

0:UtcTime

0:PropertyType

Mandatory

0:HasProperty

Variable

0:UpdateFrequency

0:Duration

0:PropertyType

Optional

0:HasProperty

Variable

0:ActivityTimeout

0:Duration

0:PropertyType

Optional

0:HasProperty

Variable

0:DefaultValidationOptions

TrustListValidationOptions

0:PropertyType

Optional

0:HasComponent

Method

0:OpenWithMasks

Defined in 7.8.2.2.

Mandatory

0:HasComponent

Method

0:CloseAndUpdate

Defined in 7.8.2.3.

Mandatory

0:HasComponent

Method

0:AddCertificate

Defined in 7.8.2.4.

Mandatory

0:HasComponent

Method

0:RemoveCertificate

Defined in 7.8.2.5.

Mandatory

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

The LastUpdateTime indicates when the TrustList was last updated. The LastUpdateTime shall reflect changes made using the TrustList Object Methods. A TrustList Object in a CertificateManager shall also reflect changes made in other ways.

The LastUpdateTime of a TrustList Object in a CertificateManager allows Clients using the PullManagement to know whether the TrustList has changed since the last time they accessed it. The LastUpdateTime of a TrustList Object in the ServerConfiguration allows administration Clients to check for out of date TrustLists.

The UpdateFrequency Property specifies how often the TrustList needs to be checked for changes. When the CertificateManager specifies this value, all Clients that read a copy of the TrustList should connect to the CertificateManager and check for updates to the TrustList within 2 times the UpdateFrequency. The choice of UpdateFrequency depends on how quickly system changes need to be detected and the performance constraints of the system. UpdateFrequencies that are too long create security risks because of out of date CRLs. UpdateFrequencies that are too short negatively impact system performance. If the TrustList Object is contained within a ServerConfiguration Object then this Property is not present.

The ActivityTimeout Property specifies the maximum elapsed time between the calls to Methods on the TrustList Object after Open or OpenWithMasks is called. If this time elapses the TrustList is automatically closed by the Server and any changes are discarded. The default value is 60 000 milliseconds (1 minute).

The DefaultValidationOptions Property specifies the default options to use when validating Certificates with the TrustList. The TrustListValidationOptions DataType is defined in 7.8.2.8. This Property may be updated by Clients with access to the SecurityAdmin Role.

If auditing is supported, the CertificateManager shall generate the TrustListUpdated AuditEventType (see 7.8.2.11) when the CloseAndUpdate, AddCertificate or RemoveCertificate Methods are called.

The OpenWithMasks Method allows a Client to read only the portion of the Trust List.

This Method can only be used to read the Trust List.

After calling this Method, the Client calls Read one or more times to get the TrustList. If the Server is able to detect out of band changes to theTrustList before the Client calls the Close Method, then the next Read returns Bad_InvalidState. If the Server cannot detect out of band changes it shall ensure the Client receives a consistent snapshot.

For PullManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the CertificateAuthorityAdmin Role, the ApplicationSelfAdmin Privilege, or the ApplicationAdmin Privilege (see 7.2).

For PushManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).

Signature

OpenWithMasks(

[in] UInt32 masks

[out] UInt32 fileHandle

);

Argument

Description

masks

The parts of the TrustList that are include in the file to read.

The masks are defined in 7.8.2.7.

fileHandle

The handle of the newly opened file.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The current user does not have the rights required.

Bad_InvalidState

The TrustList has already been opened.

Bad_TransactionPending

The TrustList cannot be opened because it is part of a transaction is in progress.

Table 23 specifies the AddressSpace representation for the OpenWithMasks Method.

Table 23 – OpenWithMasks Method AddressSpace Definition

Attribute

Value

BrowseName

0:OpenWithMasks

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

The CloseAndUpdate Method closes the TrustList and applies the changes to the TrustList. It can only be called if the TrustList was opened for writing. If the Close Method is called any cached data is discarded and the TrustList is not changed.

If only part of the TrustList is being updated the Server creates a new TrustList that includes the existing TrustList plus any updates and validates the new TrustList.

The Server shall verify that every Certificate in the new TrustList is valid using the validation process defined in OPC 10000-4. If an invalid Certificate is found the Server shall return an error and shall not replace the existing TrustList.

If the Server does not support transactions it applies the changes immediately and sets applyChangesRequired to FALSE. If the Server supports transactions then the Server creates a new transaction or continues an existing transaction and sets applyChangesRequired to TRUE.

If a transaction exists, the Server does not update the TrustList until ApplyChanges (see 7.10.6) is called. Any Clients that read the TrustList before ApplyChanges is called will receive the existing TrustList before the transaction started.

If errors occur, the new TrustList is discarded.

When the TrustList changes the Server shall re-evaluate the Certificate associated with any open Sessions. Sessions with an untrusted or revoked Certificate shall be closed.

The structure uploaded includes a mask (see 7.8.2.7) which specifies which fields are updated. If a bit is not set then the associated field is not changed.

Signature

CloseAndUpdate(

[in] UInt32 fileHandle

[out] Boolean applyChangesRequired

);

Argument

Description

fileHandle

The handle of the previously opened file.

applyChangesRequired

If TRUE the ApplyChanges Method (see 7.10.6) shall be called before the new TrustList will be used by the Server. If FALSE the TrustList is now in use.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The current user does not have the rights required.

Bad_CertificateInvalid

The Server could not validate all Certificates in the TrustList.

The DiagnosticInfo shall specify which Certificate(s) are invalid and the specific error.

Bad_ChangesPending

Changes are queued on another Session (see 7.10.6)

Table 24 specifies the AddressSpace representation for the CloseAndUpdate Method.

Table 24 – CloseAndUpdate Method AddressSpace Definition

Attribute

Value

BrowseName

0:CloseAndUpdate

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

The AddCertificate Method allows a Client to add a single Certificate to the Trust List. The Server shall verify that the Certificate using the validation process defined in OPC 10000-4. If an invalid Certificate is found the Server shall return an error and shall not update the Trust List.

This Method will return a validation error if the Certificate is issued by a CA and the Certificate for the issuer is not in the Trust List.

This Method cannot provide CRLs so issuer Certificates cannot be added with this Method. Instead, CA Certificates and their CRLs shall be managed with the Write Method on the containing TrustList Object.

This Method cannot be called if the containing TrustList Object is open.

This Method returns Bad_TransactionPending if a transaction is in progress (see 7.10.6).

This Method returns Bad_NotWritable if the TrustList Object is read only.

For PullManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the CertificateAuthorityAdmin Role (see 7.2).

For PushManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).

Signature

AddCertificate(

[in] ByteString certificate

[in] Boolean isTrustedCertificate

);

Argument

Description

certificate

The DER encoded Certificate to add.

isTrustedCertificate

If TRUE the Certificate is added to the trustedCertificates list.

If FALSE Bad_CertificateInvalid is returned.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The current user does not have the rights required.

Bad_CertificateInvalid

The certificate to add is invalid.

Bad_InvalidState

The Open Method was called with write access and the CloseAndUpdate Method has not been called.

Bad_TransactionPending

Transaction has started and ApplyChanges or CancelChanges has not been called.

Table 25 specifies the AddressSpace representation for the AddCertificate Method.

Table 25 – AddCertificate Method AddressSpace Definition

Attribute

Value

BrowseName

0:AddCertificate

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

The RemoveCertificate Method allows a Client to remove a single Certificate from the Trust List. It returns Bad_InvalidArgument if the thumbprint does not match a Certificate in the Trust List.

If the Certificate is a CA Certificate that has CRLs then all CRLs for that CA are removed as well.

This Method returns Bad_TransactionPending if a transaction is in progress (see 7.10.6).

This Method returns Bad_NotWritable if the TrustList Object is read only.For PullManagement, this Method shall be called from an authenticated SecureChannel and from a Session that has access to the CertificateAuthorityAdmin Role (see 7.2).

For PushManagement, this Method shall be called from an authenticated SecureChannel and from a Session that has access to the SecurityAdmin Role (see 7.2).

Signature

RemoveCertificate(

[in] String thumbprint

[in] Boolean isTrustedCertificate

);

Argument

Description

Thumbprint

The CertificateDigest of the Certificate to remove.

isTrustedCertificate

If TRUE the Certificate is removed from the Trusted Certificates List.

If FALSE the Certificate is removed from the Issuer Certificates List.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The current user does not have the rights required.

Bad_InvalidArgument

The certificate to remove was not found.

Bad_InvalidState

The Open Method was called with write access and the CloseAndUpdate Method has not been called.

Bad_TransactionPending

Transaction has started and ApplyChanges or CancelChanges has not been called.

Table 26 specifies the AddressSpace representation for the RemoveCertificate Method.

Table 26 – RemoveCertificate Method AddressSpace Definition

Attribute

Value

BrowseName

0:RemoveCertificate

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

This type defines a DataType which stores the TrustList of a Server. Its values are defined in Table 27.

Table 27 – TrustListDataType Structure

Name

Type

Description

TrustListDataType

Structure

Subtype of the Structure DataType defined in OPC 10000-5

specifiedLists

UInt32

A bit mask which indicates which lists contain information.

The TrustListMasks enumeration in 7.8.2.7 defines the allowed values.

trustedCertificates

ByteString[]

The list of Application and CA Certificates which are trusted.

trustedCrls

ByteString[]

The CRLs for the Certificates in the trustedCertificates list.

issuerCertificates

ByteString[]

The list of CA Certificates which are necessary to validate Certificates.

issuerCrls

ByteString[]

The CRLs for the CA Certificates in the issuerCertificates list.

Its representation in the AddressSpace is defined in Table 28.

Table 28 – TrustListDataType Definition

Attribute

Value

BrowseName

0:TrustListDataType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Other

Subtype of the 0:Structure DataType defined in OPC 10000-5.

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This is a DataType that defines the values used for the SpecifiedLists field in the TrustListDataType. Its values are defined in Table 29.

Table 29 – TrustListMasks Enumeration

Name

Value

Description

None

0

No fields are provided.

TrustedCertificates

1

The TrustedCertificates are provided.

TrustedCrls

2

The TrustedCrls are provided.

IssuerCertificates

4

The IssuerCertificates are provided.

IssuerCrls

8

The IssuerCrls are provided.

All

15

All fields are provided.

Its representation in the AddressSpace is defined in Table 30.

Table 30 – TrustListMasks Definition

Attribute

Value

BrowseName

0:TrustListMasks

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Other

Subtype of the Enumeration DataType defined in OPC 10000-5.

0:HasProperty

Variable

0:EnumValues

0:EnumValueType []

0:PropertyType

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This DataType defines flags for TrustListValidationOptions is formally defined in Table 31.

Table 31 – TrustListValidationOptions Values

Value

Bit No.

Description

SuppressCertificateExpired

0

Ignore errors related to the validity time of the Certificate.

SuppressHostNameInvalid

1

Ignore mismatches between the host name or ApplicationUri.

SuppressRevocationStatusUnknown

2

Ignore errors if the revocation list cannot be found for the issuer of the Certificate.

SuppressIssuerCertificateExpired

3

Ignore errors if an issuer has an expired Certificate.

SuppressIssuerRevocationStatusUnknown

4

Ignore errors if the revocation list cannot be found for any issuer of issuer Certificates.

CheckRevocationStatusOnline

5

Check the revocation status online.

CheckRevocationStatusOffline

6

Check the revocation status offline.

If CheckRevocationStatusOnline is set, the Certificate validation process defined in OPC 10000-4 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 Certificate validation process looks for offline CRLs if the CheckRevocationStatusOffline bit is set. Otherwise, validation fails.

The revocation status flags only have meaning for issuer Certificates and are used when validating Certificates issued by that issuer.

The default value for this DataType only has the CheckRevocationStatusOffline bit set.

The TrustListValidationOptions representation in the AddressSpace is defined in Table 32.

Table 32 – TrustListValidationOptions Definition

Attribute

Value

BrowseName

0:TrustListValidationOptions

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Other

Subtype of the 0:UInt32 DataType defined in OPC 10000-5

0:HasProperty

Variable

0:OptionSetValues

0:LocalizedText []

0:PropertyType

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This SystemOffNormalAlarmType is raised by the Server when the UpdateFrequency elapses and the TrustList has not been updated. This alarm automatically returns to normal when the TrustList is updated.

Table 33 – TrustListOutOfDateAlarmType definition

Attribute

Value

BrowseName

0:TrustListOutOfDateAlarmType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the SystemOffNormalAlarmType defined in OPC 10000-9.

0:HasProperty

Variable

0:TrustListId

0:NodeId

0:PropertyType

Mandatory

0:HasProperty

Variable

0:LastUpdateTime

0:UtcTime

0:PropertyType

Mandatory

0:HasProperty

Variable

0:UpdateFrequency

0:Duration

0:PropertyType

Mandatory

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

TrustListId Property specifies the NodeId of the out-of-date TrustList Object.

LastUpdateTime Property specifies when the TrustList was last updated.

UpdateFrequency Property specifies how frequently the TrustList needs to be updated.

This event is raised when a Method that changes the TrustList is called

It is raised when CloseAndUpdate, AddCertificate or RemoveCertificate Method on a TrustListType Object is called.

Its representation in the AddressSpace is formally defined in Table 34.

Table 34 – TrustListUpdateRequestedAuditEventType Definition

Attribute

Value

BrowseName

0:TrustListUpdateRequestedAuditEventType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the 0:AuditUpdateMethodEventType defined in OPC 10000-5.

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantic is defined in OPC 10000-5.

This event is raised when a TrustList is successfully changed.

This is the result of a CloseAndUpdate Method on a TrustListType Object or the result of a ApplyChanges on the ServerConfigurationType Object being called.

It shall also be raised when the AddCertificate or RemoveCertificate Method causes an update to the Trust List.

Its representation in the AddressSpace is formally defined inTable 35.

Table 35 – TrustListUpdatedAuditEventType Definition

Attribute

Value

BrowseName

0:TrustListUpdatedAuditEventType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the 0:AuditEventType defined in OPC 10000-5.

0:HasProperty

Variable

0:TrustListId

0:NodeId

0:PropertyType

Mandatory

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This EventType inherits all Properties of the AuditEventType. Their semantic is defined in OPC 10000-5.

This ObjectType is used for Objects which represent CertificateGroups in the AddressSpace. A CertificateGroup is a context that contains a TrustList and one or more CertificateTypes that can be assigned to an Application. This ObjectType allows an Application which has multiple TrustLists and/or ApplicationInstance Certificates to express them in its AddressSpace.

A CertificateManager can have many CertificateGroups which manage CertificateTypes and TrustLists for the applications in the system.

A Server has one or more CertificateGroups which specify the CertificateTypes and TrustLists managed by the Server. Typically, there is a mapping between a CertificateGroup in a Server and a CertificateGroup in the CertificateManager. The mechanisms for creating that mapping are outside the scope of this specification.

This type is defined in Table 36.

Table 36 – CertificateGroupType Definition

Attribute

Value

BrowseName

0:CertificateGroupType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the BaseObjectType defined in OPC 10000-5.

0:HasComponent

Object

0:TrustList

0:TrustListType

Mandatory

0:HasProperty

Variable

0:CertificateTypes

0:NodeId[]

0:PropertyType

Mandatory

0:HasComponent

Object

0:CertificateExpired

0:CertificateExpirationAlarmType

Optional

0:HasCondition

ObjectType

0:CertificateExpirationAlarmType

0:HasComponent

Object

0:TrustListOutOfDate

0:TrustListOutOfDateAlarmType

Optional

0:HasComponent

Method

0:GetRejectedList

Defined in 7.8.3.2.

Optional

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

The TrustList Object is the TrustList associated with the CertificateGroup.

The CertificateTypes Property specifies the NodeIds of the CertificateTypes which may be assigned to Applications which belong to the CertificateGroup. For example, a CertificateGroup with the NodeId of RsaMinApplicationCertificateType (see 7.8.4.4) and the NodeId RsaSha256ApplicationCertificate (see 7.8.4.5) specified allows an Application to have one Application Instance Certificates for each type. Abstract base types may be used in this value and indicate that any subtype is allowed. If this list is empty then the CertificateGroup does not allow Certificates to be assigned to Applications (i.e. a UserToken CertificateGroup only exists to allow the associated TrustList to be read or updated). All CertificateTypes for a given CertificateGroup shall be subtypes of a single common type which shall be either ApplicationCertificateType or HttpsCertificateType.

The CertificateExpired Object is an Alarm which is raised when a Certificate associated with the CertificateGroup is about to expire. If multiple Certificates are about to expiry an Alarm for each Certificate is raised. The CertificateExpirationAlarmType is defined in OPC 10000-9.

The TrustListOutOfDate Object is an Alarm which is raised when the TrustList has not been updated within the period specified by the UpdateFrequency (see 7.8.2.1). The TrustListOutOfDateAlarmType is defined in 7.8.2.9.

The GetRejectedList Method returns the list of Certificates that have been rejected by the Server when using the TrustList associated with the CertificateGroup. It can be used to track activity or allow administrators to move a rejected Certificate into the Trust List. This Method shall only be present on CertificateGroups which are part of the ServerConfiguration Object defined in 7.10.2.

GetRejectedList Method returns the list of Certificates that have been rejected by the Server.

No rules are defined for how the Server updates this list or how long a Certificate is kept in the list. It is recommended that every valid but untrusted Certificate be added to the rejected list as long as storage is available. Servers can delete entries from the list returned if the maximum message size is not large enough to allow the entire list to be returned.

Servers only add Certificates to this list that have no unsuppressed validation errors but are not trusted.

For PullManagement, this Method is not present on the CertificateGroup.

For PushManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).

Signature

GetRejectedList(

[out] ByteString[] certificates

);

Argument

Description

certificates

The DER encoded form of the Certificates rejected by the Server.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The current user does not have the rights required.

Table 37 specifies the AddressSpace representation for the GetRejectedList Method.

Table 37 – GetRejectedList Method AddressSpace Definition

Attribute

Value

BrowseName

0:GetRejectedList

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

This type is used for Folders which organize Certificate Groups in the AddressSpace. This type is defined in Table 38.

Table 38 – CertificateGroupFolderType Definition

Attribute

Value

BrowseName

0:CertificateGroupFolderType

IsAbstract

False

References

Node

Class

BrowseName

Data

Type

TypeDefinition

Modelling Rule

Subtype of the FolderType defined in OPC 10000-5.

0:HasComponent

Object

0:DefaultApplicationGroup

0:CertificateGroupType

Mandatory

0:HasComponent

Object

0:DefaultHttpsGroup

0:CertificateGroupType

Optional

0:HasComponent

Object

0:DefaultUserTokenGroup

0:CertificateGroupType

Optional

0:Organizes

Object

0:<AdditionalGroup>

0:CertificateGroupType

OptionalPlaceholder

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

The DefaultApplicationGroup Object represents the default Certificate Group for Applications. It is used to access the default Application Trust List and to define the CertificateTypes allowed for the ApplicationInstanceCertificate. This Object shall specify the ApplicationCertificateType NodeId (see 7.8.4.2) as a single entry in the CertificateTypes list or it shall specify one or more subtypes of ApplicationCertificateType.

The DefaultHttpsGroup Object represents the default Certificate Group for HTTPS communication. It is used to access the default HTTPS Trust List and to define the CertificateTypes allowed for the HTTPS Certificate. This Object shall specify the HttpsCertificateType NodeId (see 7.8.4.3) as a single entry in the CertificateTypes list or it shall specify one or more subtypes of HttpsCertificateType.

This DefaultUserTokenGroup Object represents the default Certificate Group for validating user credentials. It is used to access the default user credential Trust List and to define the CertificateTypes allowed for user credentials Certificate. This Object shall leave CertificateTypes list empty.

This type is an abstract base type for types that describe the purpose of a Certificate. This type is defined in Table 39.

Table 39 – CertificateType Definition

Attribute

Value

BrowseName

0:CertificateType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:BaseObjectType defined in OPC 10000-5.

0:HasSubtype

ObjectType

0:ApplicationCertificateType

Defined in 7.8.4.2.

0:HasSubtype

ObjectType

0:HttpsCertificateType

Defined in 7.8.4.3.

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This type is an abstract base type for types that describe the purpose of an ApplicationInstanceCertificate. This type is defined in Table 40.

Table 40 – ApplicationCertificateType Definition

Attribute

Value

BrowseName

0:ApplicationCertificateType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the CertificateType defined in 7.8.4.

0:HasSubtype

ObjectType

0:RsaMinApplicationCertificateType

Defined in 7.8.4.4.

0:HasSubtype

ObjectType

0:RsaSha256ApplicationCertificateType

Defined in 7.8.4.5.

0:HasSubtype

ObjectType

0:EccApplicationCertificateType

Defined in 7.8.4.6.

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This type is used to describe Certificates that are intended for use as HTTPS Certificates. This type is defined in Table 41.

Table 41 – HttpsCertificateType Definition

Attribute

Value

BrowseName

0:HttpsCertificateType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:CertificateType defined in 7.8.4.

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an RSA key size of 1024 or 2048 bits. All Applications which support the Basic128Rsa15 and Basic256 profiles (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 42.

Table 42 – RsaMinApplicationCertificateType Definition

Attribute

Value

BrowseName

0:RsaMinApplicationCertificateType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:ApplicationCertificateType defined in 7.8.4.2

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an RSA key size of 2048, 3072 or 4096 bits. All Applications which support the Basic256Sha256 profile (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 43.

Table 43 – RsaSha256ApplicationCertificateType Definition

Attribute

Value

BrowseName

0:RsaSha256ApplicationCertificateType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:ApplicationCertificateType defined in 7.8.4.2

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC Public Key. Applications which support the ECC profiles (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 44.

Table 44 – EccApplicationCertificateType Definition

Attribute

Value

BrowseName

0:EccApplicationCertificateType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:ApplicationCertificateType defined in 7.8.4.2.

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC nistP256 Public Key. Applications which support the ECC NIST P256 curve profiles (see OPC 10000-7) shall have a Certificate of this type or a Certificate of the EccNistP384ApplicationCertificateType defined in 7.8.4.8. This type is defined in Table 45.

Table 45 – EccNistP256ApplicationCertificateType Definition

Attribute

Value

BrowseName

0:EccNistP256ApplicationCertificateType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:EccApplicationCertificateType defined in 7.8.4.6.

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC nistP384 Public Key. Applications which support the ECC NIST P384 curve profiles (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 46.

Table 46 – EccNistP384ApplicationCertificateType Definition

Attribute

Value

BrowseName

0:EccNistP384ApplicationCertificateType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:EccApplicationCertificateType defined in 7.8.4.6.

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC brainpoolP256r1 Public Key. Applications which support the ECC brainpoolP256r1 curve profiles (see OPC 10000-7) shall have a Certificate of this type or a Certificate of the EccBrainpoolP384r1ApplicationCertificateType defined in 7.8.4.10. This type is defined in Table 47.

Table 47 – EccBrainpoolP256r1ApplicationCertificateType Definition

Attribute

Value

BrowseName

0:EccBrainpoolP256r1ApplicationCertificateType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:EccApplicationCertificateType defined in 7.8.4.6.

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC brainpoolP384r1 Public Key. Applications which support the ECC brainpoolP384r1 curve profiles (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 48.

Table 48 – EccBrainpoolP384r1ApplicationCertificateType Definition

Attribute

Value

BrowseName

0:EccBrainpoolP384r1ApplicationCertificateType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:EccApplicationCertificateType defined in 7.8.4.6.

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC curve25519 Public Key. Applications which support the ECC curve25519 curve profiles (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 49.

Table 49 – EccCurve25519ApplicationCertificateType Definition

Attribute

Value

BrowseName

0:EccCurve25519ApplicationCertificateType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:EccApplicationCertificateType defined in 7.8.4.6.

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC curve448 Public Key. Applications which support the ECC curve448 curve profiles (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 50.

Table 50 – EccCurve448ApplicationCertificateType Definition

Attribute

Value

BrowseName

0:EccCurve448ApplicationCertificateType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:EccApplicationCertificateType defined in 7.8.4.6.

Conformance Units

GDS Certificate Manager Pull Model

Push Model for Global Certificate and TrustList Management

The GlobalDiscoveryServer AddressSpace used for Certificate management is shown in Figure 20. Most of the interactions between the GlobalDiscoveryServer and Application administrator or the Client will be via Methods defined on the Directory folder.

image023.png

Figure 20 – The Certificate Management AddressSpace for the GlobalDiscoveryServer

This ObjectType is the TypeDefinition for the root of the CertificateManager AddressSpace. It provides additional Methods for Certificate management which are shown in Table 51.

Table 51 – CertificateDirectoryType ObjectType Definition

Attribute

Value

BrowseName

2:CertificateDirectoryType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 2:DirectoryType defined in 6.6.3.

0:Organizes

Object

2:CertificateGroups

0:CertificateGroup

FolderType

Mandatory

0:HasComponent

Method

2:StartSigningRequest

Defined in 7.9.3.

Mandatory

0:HasComponent

Method

2:StartNewKeyPairRequest

Defined in 7.9.4.

Mandatory

0:HasComponent

Method

2:FinishRequest

Defined in 7.9.5.

Mandatory

0:HasComponent

Method

2:RevokeCertificate

Defined in 7.9.6.

Optional

0:HasComponent

Method

2:GetCertificateGroups

Defined in 7.9.7.

Mandatory

0:HasComponent

Method

2:GetCertificates

Defined in 7.9.8.

Optional

0:HasComponent

Method

2:GetTrustList

Defined in 7.9.9.

Mandatory

0:HasComponent

Method

2:GetCertificateStatus

Defined in 7.9.10.

Mandatory

0:HasComponent

Method

2:CheckRevocationStatus

Defined in 7.9.11.

Optional

Conformance Units

GDS Certificate Manager Pull Model

The CertificateGroups Object organizes the CertificateGroups supported by the CertificateManager. It is described in 7.8.4.6. CertificateManagers shall support the DefaultApplicationGroup and may support the DefaultHttpsGroup or the DefaultUserTokenGroup. CertificateManagers may support additional CertificateGroups depending on their requirements. For example, a CertificateManager with multiple Certificate Authorities would represent each as a CertificateGroupType Object organized by CertificateGroups Folder. Clients could then request Certificates issued by a specific CA by passing the appropriate NodeId to the StartSigningRequest or StartNewKeyPairRequest Methods.

CertificateGroups assigned by the CertificateManager to specific applications are persisted by PullManagement Clients. These Clients use the NodeIds to relate their local configuration to the CertificateGroup in the CertificateManager.

The StartSigningRequest Method is used to request a new a Certificate that is signed by a CA managed by the CertificateManager. This Method is recommended when the caller already has a private key.

The StartNewKeyPairRequest Method is used to request a new Certificate that is signed by a CA managed by the CertificateManager along with a new private key. This Method is used only when the caller does not have a private key and cannot generate one.

The FinishRequest Method is used to check that a Certificate request has been approved by an entity with access to the RegistrationAuthorityAdmin Role. If successful the Certificate and Private Key (if requested) are returned.

The GetCertificateGroups Method returns a list of NodeIds for CertificateGroupType Objects that can be used to request Certificates or Trust Lists for an Application.

The GetCertificates Method returns a list of Certificates assigned to the Application for a CertificateGroup.

The GetTrustList Method returns a NodeId of a TrustListType Object that belongs to a CertificateGroup assigned to an Application.

The GetCertificateStatus Method checks whether the Application needs to update the Certificate identified in the call.

The CheckRevocationStatus Method checks the revocation status of a Certificate.

StartSigningRequest is used to initiate a request to create a Certificate which uses the private key which the caller currently has. The new Certificate is returned in the FinishRequest response.

Signature

StartSigningRequest(

[in] NodeId applicationId

[in] NodeId certificateGroupId

[in] NodeId certificateTypeId

[in] ByteString certificateRequest

[out] NodeId requestId

);

Argument

Description

applicationId

The identifier assigned to the Application record by the CertificateManager.

certificateGroupId

The NodeId of the CertificateGroup which provides the context for the new request.

If null the CertificateManager shall choose the DefaultApplicationGroup.

certificateTypeId

The NodeId of the CertificateType for the new Certificate.

If null the CertificateManager shall generate a Certificate based on the value of the certificateGroupId argument.

certificateRequest

A CertificateRequest used to prove possession of the Private Key.

It is a PKCS #10 encoded blob in DER format.

If the CertificateRequest is for an ApplicationInstance Certificate then it shall include all fields required by OPC 10000-6 such as the subjectAltName.

requestId

The NodeId that represents the request.

This value is passed to FinishRequest .

The call returns the NodeId that is passed to the FinishRequest Method.

The certificateGroupId parameter allows the caller to specify a CertificateGroup that provides context for the request. If null the CertificateManager shall choose the DefaultApplicationGroup. If the Application does not currently belong to the requested CertificateGroup the CertificateManager shall verify that the Application is allowed to join the CertificateGroup and then, if permitted, add the Application to the CertificateGroup. The CertificateGroup verification and assignment may occur anytime before FinishRequest returns success.

The set of available CertificateGroups are found in the CertificateGroups folder described in 7.9.2. The CertificateGroups allowed for an Application are returned by the GetCertificateGroups Method (see 7.9.7).

The certificateTypeId parameter specifies the type of Certificate to return. The permitted values are specified by the CertificateTypes Property of the Object specified by the certificateGroupId parameter.

The certificateRequest parameter is a DER encoded CertificateRequest. The subject, subjectAltName and Public Key are copied into the new Certificate.

If the certificateTypeId is a subtype of ApplicationCertificateType the subject conforms to the requirements defined in OPC 10000-6. The public key length shall meet the length restrictions for the CertificateType. If the certificateType is a subtype of HttpsCertificateType the Certificate common name (CN=) shall be the same as a domain from a DiscoveryUrl which uses HTTPS and the subject shall have an organization (O=) field.

The ApplicationUri shall be specified in the CSR. The CertificateManager shall return Bad_CertificateUriInvalid if the stored ApplicationUri for the Application is different from what is in the CSR.

The subject in the CSR may be ignored by the CertificateManager. The CertificateManager may update the subject to comply with policy requirements and to ensure global uniqueness.

Any bits set in basicConstraints or extendedKeyUsage fields in the CSR are ignored by the CertificateManager. The CertificateManager uses values that are appropriate and compliant with the specification.

For Servers, the list of domain names shall be specified in the CSR. The domains shall include the domain(s) in the DiscoveryUrls known to the CertificateManager.

This Method shall be called from an encrypted SecureChannel and from a Session that has access to the CertificateAuthorityAdmin Role, the ApplicationAdmin Privilege, or the ApplicationSelfAdmin Privilege (see 7.2).

If auditing is supported, the CertificateManager shall generate the CertificateRequested AuditEventType (see 7.9.12) if this Method succeeds or fails.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_NotFound

The applicationId does not refer to a registered Application.

Bad_InvalidArgument

One or more of the certificateGroupId, certificateTypeId or certificateRequest arguments is not valid.

The text associated with the error shall indicate the exact problem.

Bad_UserAccessDenied

The current user does not have the rights required.

Bad_RequestNotAllowed

The current configuration of the CertificateManager does not allow the request.

The text associated with the error should indicate the exact reason.

Bad_CertificateUriInvalid

The ApplicationUri was not specified in the CSR or does not match the Application record.

Bad_NotSupported

The signing algorithm, public algorithm or public key size are not supported by the CertificateManager. The text associated with the error shall indicate the exact problem.

Table 52 specifies the AddressSpace representation for the StartSigningRequest Method.

Table 52 – StartSigningRequest Method AddressSpace Definition

Attribute

Value

BrowseName

2:StartSigningRequest

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

This Method is used to start a request for a new Certificate and Private Key. The Certificate and Private Key. are returned in the FinishRequest response.

Signature

StartNewKeyPairRequest(

[in] NodeId applicationId

[in] NodeId certificateGroupId

[in] NodeId certificateTypeId

[in] String subjectName

[in] String[] domainNames

[in] String privateKeyFormat

[in] String privateKeyPassword

[out] NodeId requestId

);

Argument

Description

applicationId

The identifier assigned to the Application Instance by the CertificateManager.

certificateGroupId

The NodeId of the CertificateGroup which provides the context for the new request.

If null the CertificateManager shall choose the DefaultApplicationGroup.

certificateTypeId

The NodeId of the CertificateType for the new Certificate.

If null the CertificateManager shall generate a Certificate based on the value of the certificateGroupId argument.

subjectName

The subject to use for the Certificate.

If not specified the ApplicationName and/or domainNames are used to create a suitable default value.

The format of the subject is a sequence of name value pairs separated by a ‘/’. The name shall be one of ‘CN’, ‘O’, ‘OU’, ‘DC’, ‘L’, ‘S’ or ‘C’ and shall be followed by a ‘=’ and then followed by the value. The value may be any printable character except for ‘”’. If the value contains a ‘/’ or a ‘=’ then it shall be enclosed in double quotes (‘”’).

domainNames

The domain names to include in the Certificate.

If not specified the DiscoveryUrls are used to create suitable defaults.

privateKeyFormat

The format of the private key.

The following values are always supported:

PFX- PKCS #12 encoded

PEM- PKCS #8 Base64 encoded DER (see RFC 5958).

privateKeyPassword

The password to use for the private key.

requestId

The NodeId that represents the request.

This value is passed to FinishRequest.

The call returns the NodeId that is passed to the FinishRequest Method.

The certificateGroupId parameter allows the caller to specify a CertificateGroup that provides context for the request. If null the CertificateManager shall choose the DefaultApplicationGroup. If the Application does not currently belong to the requested CertificateGroup the CertificateManager shall verify that the Application is allowed to join the CertificateGroup and then, if permitted, add the Application to the CertificateGroup.

The set of available CertificateGroups are found in the CertificateGroups folder described in 7.9.2. The CertificateGroups allowed for an Application are returned by the GetCertificateGroups Method (see 7.9.7).

The certificateTypeId parameter specifies the type of Certificate to return. The permitted values are specified by the CertificateTypes Property of the Object specified by the certificateGroupId parameter.

The subjectName parameter is a sequence of X.500 name value pairs separated by a ‘/’. For example: CN=ApplicationName/OU=Group/O=Company.

If the certificateType is a subtype of ApplicationCertificateType the Certificate subject shall have an organization (O=) or domain name (DC=) field. The public key length shall meet the length restrictions for the CertificateType. The domain name field specified in the subject is a logical domain used to qualify the subject that may or may not be the same as a domain or IP address in the subjectAltName field of the Certificate.

If the certificateType is a subtype of HttpsCertificateType the Certificate common name (CN=) shall be the same as a domain from a DiscoveryUrl which uses HTTPS and the subject shall have an organization (O=) field.

If the subjectName is blank or null the CertificateManager generates a suitable default.

The requested subject may be ignored by the CertificateManager. The CertificateManager may update the subject to comply with policy requirements and to ensure global uniqueness.

The domainNames parameter is list of domains to be includes in the Certificate. If it is null or empty the GDS uses the DiscoveryUrls of the Server to create a list. For Clients the domainNames are omitted from the Certificate if they are not explicitly provided.

The privateKeyFormat specifies the format of the private key returned. All CertificateManager implementations shall support “PEM” and “PFX”.

The privateKeyPassword specifies the password on the private key. The CertificateManager shall not persist this information and shall discard it once the new private key is generated.

This Method shall be called from an encrypted SecureChannel and from a Session that has access to the CertificateAuthorityAdmin Role, the ApplicationAdmin Privilege, or the ApplicationSelfAdmin Privilege (see 7.2).

If auditing is supported, the CertificateManager shall generate the CertificateRequested AuditEventType (see 7.9.12) if this Method succeeds or fails.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_NodeIdUnknown

The applicationId does not refer to a registered Application (deprecated).

Bad_NotFound

The applicationId does not refer to a registered Application.

Bad_InvalidArgument

One or more of the certificateGroupId, certificateTypeId, subjectName, domainNames or privateKeyFormat parameters is not valid.

The text associated with the error shall indicate the exact problem.

Bad_UserAccessDenied

The current user does not have the rights required.

Bad_RequestNotAllowed

The current configuration of the CertificateManager does not allow the request.

The text associated with the error should indicate the exact reason.

Table 53 specifies the AddressSpace representation for the StartNewKeyPairRequest Method.

Table 53 – StartNewKeyPairRequest Method AddressSpace Definition

Attribute

Value

BrowseName

2:StartNewKeyPairRequest

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

FinishRequest is used to finish a certificate request started with a call to StartNewKeyPairRequest or StartSigningRequest.

Signature

FinishRequest (

[in] NodeId applicationId

[in] NodeId requestId

[out] ByteString certificate

[out] ByteString privateKey

[out] ByteString[] issuerCertificates

);

Argument

Description

applicationId

The identifier assigned to the Application Instance by the GDS.

requestId

The NodeId returned by StartNewKeyPairRequest or StartSigningRequest.

certificate

The DER encoded Certificate.

privateKey

The private key encoded in the format requested.

If a password was supplied the blob is protected with it.

This field is null if no private key was requested.

issuerCertificates

The Certificates required to validate the new Certificate.

This call is passes the NodeId returned by a previous call to StartNewKeyPairRequest or StartSigningRequest.

It is expected that a Client will periodically call this Method until an entity with access to the RegistrationAuthorityAdmin Role has approved the request.

This Method shall be called from an encrypted SecureChannel and from a Session that has access to the CertificateAuthorityAdmin Role, the ApplicationAdmin Privilege, or the ApplicationSelfAdmin Privilege (see 7.2). In addition, the Client Certificate shall be the same as the one used to call StartSigningRequest or StartNewKeyPairRequest.

If auditing is supported, the GDS shall generate the CertificateDeliveredAuditEventType (see 7.9.13) if this Method succeeds or if it fails with anything but Bad_NothingToDo.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_NotFound

The applicationId does not refer to a registered Application.

Bad_InvalidArgument

The requestId is does not reference to a valid request for the Application.

Bad_NothingToDo

There is nothing to do because request has not yet completed.

Bad_UserAccessDenied

The current user does not have the rights required.

Bad_RequestNotAllowed

The CertificateManager rejected the request.

The text associated with the error should indicate the exact reason.

Table 54 specifies the AddressSpace representation for the FinishRequest Method.

Table 54 – FinishRequest Method AddressSpace Definition

Attribute

Value

BrowseName

2:FinishRequest

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

RevokeCertificate is used to revoke a Certificate issued by the CertificateManager.

When a Certificate is revoked it shall be removed from any TrustLists that it is in and TrustLists with the issuer Certificate shall be updated with the new CRL.

Certificates assigned to an Application are automatically revoked when the UnregisterApplication Method is called (see 6.6.8).

This Method shall be called from an authenticated SecureChannel and from a Client that has access to the CertificateAuthorityAdmin Role (see 7.2).

Signature

RevokeCertificate (

[in] NodeId applicationId

[in] ByteString certificate

);

Argument

Description

applicationId

The identifier assigned to the Application by the CertificateManager.

certificate

The DER encoded Certificate to revoke.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_NotFound

The applicationId does not refer to a registered Application.

Bad_InvalidArgument

The certificate is not a Certificate for the specified Application that was issued by the CertificateManager.

Bad_UserAccessDenied

The current user does not have the rights required.

Table 55 specifies the AddressSpace representation for the RevokeCertificate Method.

Table 55 – RevokeCertificate Method AddressSpace Definition

Attribute

Value

BrowseName

2:RevokeCertificate

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

GetCertificateGroups returns the CertificateGroups assigned to Application.

Signature

GetCertificateGroups(

[in] NodeId applicationId

[out] NodeId[] certificateGroupIds

);

Argument

Description

applicationId

The identifier assigned to the Application by the GDS.

certificateGroupIds

An identifier for the CertificateGroups assigned to the Application.

A CertificateGroup provides a TrustList and one or more CertificateTypes which may be assigned to an Application.

This Method shall be called from an authenticated SecureChannel and from a Client that has access to the CertificateAuthorityAdmin Role, the ApplicationAdmin Privilege, or the ApplicationSelfAdmin Privilege (see 7.2).

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_NotFound

The applicationId does not refer to a registered Application.

Bad_UserAccessDenied

The current user does not have the rights required.

Table 58 specifies the AddressSpace representation for the GetCertificateGroups Method.

Table 56 – GetCertificateGroups Method AddressSpace Definition

Attribute

Value

BrowseName

2:GetCertificateGroups

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

GetCertificates returns the Certificates assigned to Application and associated with the CertificateGroup.

This Method shall be called from an authenticated SecureChannel and from a Client that has access to the CertificateAuthorityAdmin Role, the ApplicationAdmin Privilege, or the ApplicationSelfAdmin Privilege (see 7.2).

Signature

GetCertificates(

[in] NodeId applicationId

[in] NodeId certificateGroupId

[out] NodeId[] certificateTypeIds

[out] ByteString[] certificates

);

Argument

Description

applicationId

The identifier assigned to the Application by the GDS.

certificateGroupId

An identifier for the CertificateGroup that the Certificates belong to.

If null, the CertificateManager shall return the Certificates for all CertificateGroups assigned to the Application.

certificateTypeIds

The CertificateTypes that currently have a Certificate assigned.

The length of this list is the same as the length as certificates list.

certificates

A list of DER encoded Certificates assigned to Application.

This list only includes Certificates that are currently valid.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_NotFound

The applicationId does not refer to a registered Application.

Bad_InvalidArgument

The certificateGroupId is not recognized or not valid for the Application.

Bad_UserAccessDenied

The current user does not have the rights required.

Table 57 specifies the AddressSpace representation for the GetCertificates Method.

Table 57 – GetCertificates Method AddressSpace Definition

Attribute

Value

BrowseName

2:GetCertificates

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

GetTrustList is used to retrieve the NodeId of a TrustList assigned to an Application.

Signature

GetTrustList(

[in] NodeId applicationId

[in] NodeId certificateGroupId

[out] NodeId trustListId

);

Argument

Description

applicationId

The identifier assigned to the Application by the GDS.

certificateGroupId

An identifier for a CertificateGroup that the Application belongs to.

If null, the CertificateManager shall return the trustListId for a suitable default group for the Application.

trustListId

The NodeId for a TrustList Object that can be used to download the TrustList assigned to the Application.

Access permissions also apply to the TrustList Objects which are returned by this Method. This TrustList includes any Certificate Revocation Lists (CRLs) associated with issuer Certificates in the Trust List.

This Method shall be called from an authenticated SecureChannel and from a Client that has access to the CertificateAuthorityAdmin Role, the ApplicationAdmin Privilege, or the ApplicationSelfAdmin Privilege (see 7.2).

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_NotFound

The applicationId does not refer to a registered Application.

Bad_InvalidArgument

The certificateGroupId parameter is not valid.

The text associated with the error shall indicate the exact problem.

Bad_UserAccessDenied

The current user does not have the rights required.

Table 58 specifies the AddressSpace representation for the GetTrustList Method.

Table 58 – GetTrustList Method AddressSpace Definition

Attribute

Value

BrowseName

2:GetTrustList

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

GetCertificateStatus is used to check if an Application needs to update its Certificate.

This Method shall be called from an authenticated SecureChannel and from a Client that has access to the CertificateAuthorityAdmin Role, the ApplicationAdmin Privilege, or the ApplicationSelfAdmin Privilege (see 7.2).

Signature

GetCertificateStatus(

[in] NodeId applicationId

[in] NodeId certificateGroupId

[in] NodeId certificateTypeId

[out] Boolean updateRequired

);

Argument

Description

applicationId

The identifier assigned to the Application Instance by the GDS.

certificateGroupId

The NodeId of the CertificateGroup which provides the context.

If null the CertificateManager shall choose the DefaultApplicationGroup.

certificateTypeId

The NodeId of the CertificateType for the Certificate.

If null the CertificateManager shall select a Certificate based on the value of the certificateGroupId argument.

updateRequired

TRUE if the Application needs to request a new Certificate from the GDS.

FALSE if the Application can keep using the existing Certificate.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_NotFound

The applicationId does not refer to a registered Application.

Bad_InvalidArgument

The certificateGroupId or certificateTypeId parameter is not valid.

The text associated with the error shall indicate the exact problem.

Bad_UserAccessDenied

The current user does not have the rights required.

Table 59 specifies the AddressSpace representation for the GetCertificateStatus Method.

Table 59 – GetCertificateStatus Method AddressSpace Definition

Attribute

Value

BrowseName

2:GetCertificateStatus

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

CheckRevocationStatus Method is used to check the revocation status of an Certificate.

Clients or Servers may use this Method if the issuer Certificate has a crlDistributionPoint extension, an authorityInformationAccess extension (see RFC 6960) or the TrustList is configured to require online Certificate revocation checks (see 7.8.2.1).

The CertificateManager will typically use a protocol such as OCSP (see RFC 6960) to verify the Certificate status using the endpoint in the CDP extension, however, it may also optimize performance by maintaining a cache of recently verified Certificate and/or maintaining it’s own offline CRLs. The validityTime parameter provides guidance on how long a result can be kept in a local cache.

The caller shall perform all validation checks other than the revocation status check (see OPC 10000-4) on the Certificate before calling this Method. The CertificateManager shall check the Signature on the Certificate and may do additional validation.

This Method shall be called from an authenticated SecureChannel.

Signature

CheckRevocationStatus (

[in] ByteString certificate

[out] StatusCode certificateStatus

[out] UtcTime validityTime

);

Argument

Description

INPUTS

certificate

The DER encoded form of the Certificate to check.

OUTPUTS

certificateStatus

The first error encountered when validating the Certificate.

validityTime

When the result expires and should be rechecked.

DateTime.MinValue is this is unknown.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The current user does not have the rights required.

Table 60 specifies the AddressSpace representation for the CheckRevocationStatus Method.

Table 60 – CheckRevocationStatus Method AddressSpace Definition

Attribute

Value

BrowseName

2:CheckRevocationStatus

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

This event is raised when a new certificate request has been accepted or rejected by the CertificateManager.

This can be the result of a StartNewKeyPairRequest or StartSigningRequest Method calls.

Its representation in the AddressSpace is formally defined in Table 61.

Table 61 – CertificateRequestedAuditEventType Definition

Attribute

Value

BrowseName

2:CertificateRequestedAuditEventType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:AuditUpdateMethodEventType defined in OPC 10000-5.

0:HasProperty

Variable

2:CertificateGroup

0:NodeId

0:PropertyType

Mandatory

0:HasProperty

Variable

2:CertificateType

0:NodeId

0:PropertyType

Mandatory

Conformance Units

GDS Certificate Manager Pull Model

This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantic is defined in OPC 10000-5.

The CertificateGroup Property specifies the CertificateGroup that was affected by the update.

The CertificateType Property specifies the type of Certificate that was updated.

This event is raised when a certificate is delivered by the CertificateManager to a Client.

This is the result of a FinishRequest Method completing successfully.

Its representation in the AddressSpace is formally defined in Table 62.

Table 62 – CertificateDeliveredAuditEventType Definition

Attribute

Value

BrowseName

2:CertificateDeliveredAuditEventType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:AuditUpdateMethodEventType defined in OPC 10000-5.

0:HasProperty

Variable

2:CertificateGroup

0:NodeId

0:PropertyType

Mandatory

0:HasProperty

Variable

2:CertificateType

0:NodeId

0:PropertyType

Mandatory

Conformance Units

GDS Certificate Manager Pull Model

This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantic is defined in OPC 10000-5.

The CertificateGroup Property specifies the CertificateGroup that was affected by the update.

The CertificateType Property specifies the type of Certificate that was updated.

If a Server supports PushManagement it is required to support an information model as part of its AddressSpace. It shall support the ServerConfiguration Object shown in Figure 21.

image024.png

Figure 21 – The AddressSpace for the Server that supports Push Management

The CertificateGroups and TrustLists used by a Server may be updated as part of a transaction where multiple Methods are invoked, however, no changes will have any effect until ApplyChanges is called (see 7.10.6). These transactions are created automatically and the Server returns applyChangesRequired =TRUE in a Method response to tell the Client that a transaction is active. Servers that do not support transactions return applyChangesRequired =FALSE and apply any changes before returning a Method response.

If a Method called within a transaction fails (e.g. a parameter was invalid) the transaction state shall not change and all previous changes are applied when ApplyChanges is called.

Once a transaction is created, a Server shall queue the changes in the order that they were requested within the current Session. When ApplyChanges is called the Server verifies that all the changes are consistent and can be applied without errors. If any errors are found then all changes are discarded. If no errors are found, the Server applies all changes.

If errors occur they are reported in the TransactionDiagnostics Object (see 7.10.11).

The life cycle of a transaction is shown in Figure 22.

image025.png

Figure 22 – The Transaction Lifecycle when using PushManagement

Servers that implement the transaction model shall support the CancelChanges Method and always set applyChangesRequired to TRUE.

Servers that support the transaction model are expected to support exactly one active transaction. Once a transaction has started in Session all other Sessions will not be able to modify TrustLists or Certificates. Transactions are automatically cancelled when the Session that created it is closed or when the CancelChanges Method is called.

If the transaction model is not supported and applyChangesRequired is TRUE then the behaviour of the Server for multiple changes is undefined.

If applyChangesRequired is FALSE then any changes are applied before the Method response is sent.

This Object allows access to the Server’s configuration and it is the target of an HasComponent reference from the Server Object defined in OPC 10000-5.

This Object and its immediate children shall be visible (i.e. browse access is available) to users who can access the Server Object. The children of the CertificateGroups Object should only be visible to Clients with access to the SecurityAdmin Role.

Its representation in the AddressSpace is formally defined in Table 63.

Table 63 – ServerConfiguration Object Definition

Attribute

Value

BrowseName

0:ServerConfiguration

TypeDefinition

0:ServerConfigurationType defined in 7.10.3.

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Conformance Units

Push Model for Global Certificate and TrustList Management

This type defines an ObjectType which represents the configuration of a Server which supports PushManagement. Its values are defined in Table 64. There is always exactly one instance in the Server AddressSpace.

Table 64 – ServerConfigurationType Definition

Attribute

Value

BrowseName

0:ServerConfigurationType

IsAbstract

False

References

NodeClass

BrowseName

DataType

Type

Definition

Modelling Rule

Subtype of the BaseObjectType defined in OPC 10000-5.

0:HasProperty

Variable

0:ApplicationUri

0:UriString

0:PropertyType

Optional

0:HasProperty

Variable

0:ProductUri

0:UriString

0:PropertyType

Optional

0:HasProperty

Variable

0:ApplicationType

0:ApplicationType

0:PropertyType

Optional

0:HasProperty

Variable

0:ServerCapabilities

0:String[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:SupportedPrivateKeyFormats

0:String[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:MaxTrustListSize

0:UInt32

0:PropertyType

Mandatory

0:HasProperty

Variable

0:MulticastDnsEnabled

0:Boolean

0:PropertyType

Mandatory

0:HasProperty

Variable

0:HasSecureElement

0:Boolean

0:PropertyType

Optional

0:HasComponent

Method

0:UpdateCertificate

See 7.10.4.

Mandatory

0:HasComponent

Method

0:GetCertificates

See 7.10.5.

Optional

0:HasComponent

Method

0:ApplyChanges

See 7.10.6.

Mandatory

0:HasComponent

Method

0:CancelChanges

See 7.10.8.

Optional

0:HasComponent

Method

0:CreateSigningRequest

See 7.10.7.

Mandatory

0:HasComponent

Method

0:GetRejectedList

See 7.10.9.

Mandatory

0:HasComponent

Method

0:ResetToServerDefaults

See 7.10.10.

Optional

0:HasComponent

Object

0:CertificateGroups

0:CertificateGroupFolderType

Mandatory

0:HasComponent

Object

0:TransactionDiagnostics

0:TransactionDiagnosticsType

Optional

Conformance Units

Push Model for Global Certificate and TrustList Management

The CertificateGroups Object organizes the Certificate Groups supported by the Server. It is described in 7.8.4.6. Servers shall support the DefaultApplicationGroup and may support the DefaultHttpsGroup or the DefaultUserTokenGroup. Servers may support additional Certificate Groups depending on their requirements. For example, a Server with two network interfaces should have a different Trust List for each interface. The second Trust List would be represented as a new CertificateGroupType Object organized by CertificateGroups Folder.

The ApplicationUri Property specifies the ApplicationUri assigned to the Server. It can be updated by a Client with access to the SecurityAdmin Role.

The ProductUri Property specifies the ProductUri for the Server that appears in the ApplicationDescription. It is read-only.

The ApplicationType Property specifies the ApplicationType for the Server that appears in the ApplicationDescription. It is read-only.

The ServerCapabilities Property specifies the capabilities from Annex D which the Server supports. The value is the same as the value reported to the LocalDiscoveryServer when the Server calls the RegisterServer2 Service.

The SupportedPrivateKeyFormats specifies the PrivateKey formats supported by the Server. Possible values include “PEM” (see RFC 5958) or “PFX” (see PKCS #12). The array is empty if the Server does not allow external Clients to update the PrivateKey.

The MaxTrustListSize is the maximum size of the Trust List in bytes. 0 means no limit. The default is 65 535 bytes.

If MulticastDnsEnabled is TRUE then the Server announces itself using multicast DNS. It can be changed by writing to the Variable.

If HasSecureElement is TRUE then the Server has access to hardware based secure storage for the PrivateKeys associated with its Certificates.

The UpdateCertificate Method is used to update a Certificate.

The GetCertificates Method returns the Certificates assigned to each of the CertificateTypes in a CertificateGroup.

The ApplyChanges Method is used complete changes made to CertificateGroups and/or TrustLists within the context of a transaction.

The CancelChanges Method is used to cancel an existing transaction.

The CreateSigningRequest Method asks the Server to create a PKCS #10 encoded Certificate Request that is signed with the Server’s private key.

The GetRejectedList Method returns the list of Certificates which have been rejected by the Server. It can be used to track activity or allow administrators to move a rejected Certificate into the Trust List. This Method is the a shortcut for the GetRejectedList Method (see 7.8.3.2) on the DefaultApplicationGroup CertificateGroup (see 7.8.3.3).

The ResetToServerDefaults Method is used reset the Server security configuration to a default state.

The TransactionDiagnostics Object reports detailed error information for the current or most recently completed transaction. The TransactionDiagnostics Object is only visible to Clients with access to the SecurityAdmin Role.

UpdateCertificate is used to update a Certificate for a Server.

There are the following three use cases for this Method:

The Server shall do all normal integrity checks on the Certificate and all of the issuer Certificates. If errors occur the Bad_SecurityChecksFailed error is returned.

The Server shall report an error if the public key does not match the existing Certificate and the privateKey was not provided.

If the Server returns applyChangesRequired =FALSE then it is indicating that it is able to satisfy the requirements specified for the ApplyChanges Method.

This Method shall be called from an encrypted SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).

Signature

UpdateCertificate(

[in] NodeId certificateGroupId

[in] NodeId certificateTypeId

[in] ByteString certificate

[in] ByteString[] issuerCertificates

[in] String privateKeyFormat

[in] ByteString privateKey

[out] Boolean applyChangesRequired

);

Argument

Description

certificateGroupId

The NodeId of the Certificate Group Object which is affected by the update.

If null the DefaultApplicationGroup is used.

certificateTypeId

The type of Certificate being updated. The set of permitted types is specified by the CertificateTypes Property belonging to the Certificate Group.

certificate

The DER encoded Certificate which replaces the existing Certificate.

issuerCertificates

The issuer Certificates needed to verify the signature on the new Certificate.

privateKeyFormat

The format of the Private Key (PKCS #12 encoded and PKCS #8 Base64 encoded DER (see RFC 5958) ). If the privateKey is not specified the privateKeyFormat is null or empty.

privateKey

The Private Key encoded in the privateKeyFormat.

applyChangesRequired

Indicates that the ApplyChanges Method shall be called before the new Certificate will be used.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_InvalidArgument

The certificateTypeId or certificateGroupId is not valid.

Bad_CertificateInvalid

The Certificate is invalid or the format is not supported.

Bad_NotSupported

The PrivateKey is invalid or the format is not supported.

Bad_UserAccessDenied

The current user does not have the rights required.

Bad_SecurityChecksFailed

Some failure occurred verifying the integrity of the Certificate.

Table 65 specifies the AddressSpace representation for the UpdateCertificate Method.

Table 65 – UpdateCertificate Method AddressSpace Definition

Attribute

Value

BrowseName

0:UpdateCertificate

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

HasProperty

Variable

InputArguments

Argument[]

PropertyType

Mandatory

HasProperty

Variable

OutputArguments

Argument[]

PropertyType

Mandatory

GetCertificates returns the Certificates assigned to CertificateTypes associated with a CertificateGroup.

This Method shall be called from an authenticated SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).

Signature

GetCertificates(

[in] NodeId certificateGroupId

[out] NodeId[] certificateTypeIds

[out] ByteString[] certificates

);

Argument

Description

certificateGroupId

The identifier for the CertificateGroup.

certificateTypeIds

The CertificateTypes that currently have a Certificate assigned.

The length of this list is the same as the length as certificates list.

An empty list if the CertificateGroup does not have any CertificateTypes.

certificates

A list of DER encoded Certificates assigned to CertificateGroup.

The certificateType for the Certificate is specified by the corresponding element in the certificateTypes parameter.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The current user does not have the rights required.

Bad_InvalidArgument

The certificateGroupId is not valid.

Table 66 specifies the AddressSpace representation for the GetCertificates Method.

Table 66 – GetCertificates Method AddressSpace Definition

Attribute

Value

BrowseName

0:GetCertificates

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

ApplyChanges returns Bad_InvalidState if any TrustLIst is still open for writing. No changes were be applied and ApplyChanges can be called again after the TrustList is closed.

If a Session is closed or abandoned then the transaction is closed and all pending changes are discarded.

If ApplyChanges is called and there is no active transaction then the Server returns Bad_NothingToDo. If there is an active transaction, however, no changes are pending the result is Good and the transaction is closed.

When a Server Certificate or TrustList changes active SecureChannels are not immediately affected. This ensures the caller of ApplyChanges can get a response to the Method call. Once the Method response is returned the Server shall force existing SecureChannels affected by the changes to renegotiate and use the new Server Certificate and/or TrustLists.

Servers may close SecureChannels without discarding any Sessions or Subscriptions. This will seem like a network interruption from the perspective of the Client and the Client reconnect logic (see OPC 10000-4) allows them to recover their Session and Subscriptions. Note that some Clients may not be able to reconnect because they are no longer trusted.

Other Servers may need to do a complete shutdown. In these cases, the Server shall advertise its intent to interrupt connections by setting the SecondsTillShutdown and ShutdownReason Properties in the ServerStatus Variable.

If a TrustList change only affects UserIdentity associated with a Session then Servers shall re-evaluate the UserIdentity and if it is no longer valid the Session and associated Subscriptions are closed.

This Method shall be called from an authenticated SecureChannel and from the Session that created the transaction and has access to the SecurityAdmin Role (see 7.2).

Signature

ApplyChanges();

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The current user does not have the rights required.

Table 67 specifies the AddressSpace representation for the ApplyChanges Method.

Table 67 – ApplyChanges Method AddressSpace Definition

Attribute

Value

BrowseName

0:ApplyChanges

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

CreateSigningRequest Method asks the Server to create a PKCS #10 DER encoded Certificate Request that is signed with the Server’s private key. This request can be then used to request a Certificate from a CA that expects requests in this format.

Servers shall support one active and one new key pair for each combination of certificateGroupId and certificateTypeId. If this Method is called multiple times with the same certificateGroupId and certificateTypeId then any previously generated new key pair, that has not been made active, is discarded. If a key pair is made active by a call to UpdateCertificate then the previously active key pair is deleted.

This Method shall be called from an encrypted SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).

Signature

CreateSigningRequest(

[in]NodeId certificateGroupId

[in]NodeId certificateTypeId

[in]String subjectName

[in]Boolean regeneratePrivateKey

[in]ByteString nonce

[out]ByteString certificateRequest

);

Argument

Description

certificateGroupId

The NodeId of the Certificate Group Object which is affected by the request.

If null the DefaultApplicationGroup is used.

certificateTypeId

The type of Certificate being requested. The set of permitted types is specified by the CertificateTypes Property belonging to the Certificate Group.

subjectName

The subject name to use in the Certificate Request.

If not specified the SubjectName from the current Certificate is used.

The format of the subjectName is defined in 7.9.4.

regeneratePrivateKey

If TRUE the Server shall create a new Private Key which it stores until the matching signed Certificate is uploaded with the UpdateCertificate Method. Previously created Private Keys may be discarded if UpdateCertificate was not called before calling this method again. If FALSE the Server uses its existing Private Key.

nonce

Additional entropy which the caller shall provide if regeneratePrivateKey is TRUE. It shall be at least 32 bytes long.

certificateRequest

The PKCS #10 DER encoded Certificate Request.

If the CertificateRequest is for an ApplicationInstance Certificate then it shall include all fields required by OPC 10000-6 such as the subjectAltName.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_InvalidArgument

One or more of the certificateTypeId, certificateGroupId, nonce, or subjectName paremeters is not valid.

Bad_UserAccessDenied

The current user does not have the rights required.

Table 68 specifies the AddressSpace representation for the CreateSigningRequest Method.

Table 68 – CreateSigningRequest Method AddressSpace Definition

Attribute

Value

BrowseName

0:CreateSigningRequest

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

CancelChanges is used to tell the Server to discard changes to theTrustLists or Certificates which were waiting for the Client to ApplyChanges.

This Method shall be called from an authenticated SecureChannel and from the Session that created the transaction and has access to the SecurityAdmin Role (see 7.2).

Signature

CancelChanges();

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The current user does not have the rights required.

Table 67 specifies the AddressSpace representation for the CancelChanges Method.

Table 69 – CancelChanges Method AddressSpace Definition

Attribute

Value

BrowseName

0:CancelChanges

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

GetRejectedList Method returns the list of Certificates that have been rejected by the Server.

No rules are defined for how the Server updates this list or how long a Certificate is kept in the list. It is recommended that every valid but untrusted Certificate be added to the rejected list as long as storage is available. Servers should omit older entries from the list returned if the maximum message size is not large enough to allow the entire list to be returned.

This Method shall be called from an authenticated SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).

Signature

GetRejectedList(

[out] ByteString[] certificates

);

Argument

Description

certificates

The DER encoded form of the Certificates rejected by the Server.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The current user does not have the rights required.

Table 70 specifies the AddressSpace representation for the GetRejectedList Method.

Table 70 – GetRejectedList Method AddressSpace Definition

Attribute

Value

BrowseName

0:GetRejectedList

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

The ResetToServerDefaults Method resets the Server configuration to its default settings.

The following actions occur:

Servers may extend this list with additional actions when appropriate.

If the Server is running on a Device that supports OPC 10000-21 the Device is placed in a state where the Onboarding process has to restart. If the Device does not support OPC 10000-21, the Server repeats the Application Setup process described in Annex G.

After this Method completes the Server shall set the ServerState to SHUTDOWN and the shutdownReason to a localized message that warns Clients that their credentials may not work when the Server restarts. The Server should set the secondsTillShutdown to a time that gives the Client a chance to receive the response to this Method.

Note that the default configuration for a Server is set by configuration and is not necessarily the “factory default”. For example, a machine builder could update the default configuration to ensure that the Server can still communicate with other Servers within the machine after the reset.

The mechanisms for setting the default configuration is vendor specific.

This Method shall be called from an authenticated SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).

Signature

ResetToServerDefaults ();

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The current user does not have the rights required.

Table 71 specifies the AddressSpace representation for the ResetToServerDefaults Method.

Table 71 – ResetToServerDefaults Method AddressSpace Definition

Attribute

Value

BrowseName

0:ResetToServerDefaults

This type defines an ObjectType which represents the diagnostics for the last transaction (see 7.10.1. If no transaction has started the values of all Variables have a status of Bad_OutOfService. All existing results are discarded when a new transaction starts.

Table 72 – TransactionDiagnosticsType Definition

Attribute

Value

BrowseName

0:TransactionDiagnosticsType

IsAbstract

False

References

NodeClass

BrowseName

DataType

Type

Definition

Modelling Rule

Subtype of the BaseObjectType defined in OPC 10000-5.

0:HasProperty

Variable

0:StartTime

0:UtcTime

0:PropertyType

Mandatory

0:HasProperty

Variable

0:EndTime

0:UtcTime

0:PropertyType

Mandatory

0:HasProperty

Variable

0:Result

0:StatusCode

0:PropertyType

Mandatory

0:HasProperty

Variable

0:AffectedTrustLists

0:NodeId []

0:PropertyType

Mandatory

0:HasProperty

Variable

0:AffectedCertificateGroups

0:NodeId []

0:PropertyType

Mandatory

0:HasProperty

Variable

0:Errors

0:TransactionErrorType []

0:PropertyType

Mandatory

Conformance Units

Push Model for Global Certificate and TrustList Management

The StartTime Property indicates when transaction started. It has a status of Bad_OutOfService if a transaction has not started

The EndTime Property indicates when transaction ended. It has a value of DateTime.MinValue if the transaction has not completed.

The Result Property indicates the overall transaction result. It has a status of Bad_InvalidState if a transaction has started but not completed. If the transaction has completed the status is Good and the value is the StatusCode that was returned from the ApplyChanges Method. If the CancelChanges Method was called the value is Bad_RequestCancelledByClient.

The AffectedTrustLists Property specifies the NodeIds of the TrustLists that are included in the transaction. It is updated each time as soon as a TrustList is added to the transaction.

The AffectedCertificateGroups Property specifies the NodeIds of the CertificateGroups are included in the transaction. It is updated each time as soon as a CertificateGroup is added to the transaction.

The Errors Property has a list of errors that occurred when the changes were applied. Empty if no errors occurred. The TransactionErrorType is defined in 7.10.12.

This type defines a DataType which stores an error that occurred when processing a transaction. Its values are defined in Table 73.

Table 73 – TransactionErrorType Structure

Name

Type

Description

TransactionErrorType

Structure

Subtype of the Structure DataType defined in OPC 10000-5

targetId

NodeId

The NodeId of the Object that had the error. It is either a TrustListId or a CertificateGroupId.

error

StatusCode

The code describing the error.

message

LocalizedText

A description of the error. It should include enough information to allow the Client to understand which Certificate(s) and/or CRL(s) are the source of the problem.

Its representation in the AddressSpace is defined in Table 74.

Table 74 – TransactionErrorType Definition

Attribute

Value

BrowseName

0:TransactionErrorType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Other

Subtype of the 0:Structure DataType defined in OPC 10000-5.

Conformance Units

Push Model for Global Certificate and TrustList Management

This event is raised when the UpdateCertificate Method is called

Its representation in the AddressSpace is formally defined in Table 75.

Table 75 – CertificateUpdateRequestedAuditEventType Definition

Attribute

Value

BrowseName

0:CertificateUpdateRequestedAuditEventType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the 0:AuditUpdateMethodEventType defined in OPC 10000-5.

Conformance Units

Push Model for Global Certificate and TrustList Management

This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantic is defined in OPC 10000-5.

This event is raised when a Certificate is actually changed.

This is the result of a sucessful call to UpdateCertificate or ApplyChanges on a ServerConfigurationType Object.

Its representation in the AddressSpace is formally defined in Table 76.

Table 76 – CertificateUpdatedAuditEventType Definition

Attribute

Value

BrowseName

0:CertificateUpdatedAuditEventType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the 0:AuditEventType defined in OPC 10000-5.

0:HasProperty

Variable

0:CertificateGroup

0:NodeId

0:PropertyType

Mandatory

0:HasProperty

Variable

0:CertificateType

0:NodeId

0:PropertyType

Mandatory

Conformance Units

Push Model for Global Certificate and TrustList Management

This EventType inherits all Properties of the AuditEventType. Their semantic is defined in OPC 10000-5.

The CertificateGroup Property specifies the CertificateGroup that was affected by the update.

The CertificateType Property specifies the type of Certificate that was updated.