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.