This chapter specifies the OPC UA Information Model for a Security Key Service (SKS). The functionality and behaviour of an SKS is described in 5.4.3. It defines the distribution framework for cryptographic keys used for message security.

The SKS can be a network service used to manage keys for all Publishers and Subscribers or it can be part of a Publisher to manage the keys for the NetworkMessages sent by this Publisher.

Figure 34 depicts the ObjectTypes and their components used to represent the PublishSubscribe Object.

image037.png

Figure 34 – PublishSubscribe Object Types Overview

The PublishSubscribe Object is the root node for all PubSub related configuration Objects. It is an instance of the PubSubKeyServiceType or the PublishSubscribeType and a component of the Server Object.

The PubSubKeyServiceType defines the Method for access to security keys and the related management of SecurityGroups. This ObjectType is used for the PublishSubscribe Object if only the Security Key Service functionality is provided. If the PubSub configuration functionality is provided, the PublishSubscribeType is used instead.

The SecurityGroups are organized by the SecurityGroupFolderType and represented by instances of the SecurityGroupType.

The PublishSubscribeType contains the entry points for the PubSub configuration model defined in clause 9.

To provide interoperability between Publishers, Subscribers, Security Key Services and configuration tools, all PubSub related Objects shall be exposed through an Object called “PublishSubscribe” that is of the type PubSubKeyServiceType or a subtype. This Object shall be a component of the Server Object. It is formally defined in Table 99.

Table 99 – PublishSubscribe Object Definition

Attribute

Value

BrowseName

PublishSubscribe

References

Node Class

BrowseName

DataType

TypeDefinition

Modelling Rule

ComponentOf the Server Object defined in OPC 10000-5.

HasTypeDefinition

ObjectType

PubSubKeyServiceType

The PubSubKeyServiceType is formally defined in Table 100.

Table 100 – PubSubKeyServiceType Definition

Attribute

Value

BrowseName

PubSubKeyServiceType

IsAbstract

False

References

Node Class

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of BaseObjectType defined in OPC 10000-5.

HasComponent

Method

GetSecurityKeys

Defined in 8.4.

Optional

HasComponent

Method

GetSecurityGroup

Defined in 8.7.

Optional

HasComponent

Object

SecurityGroups

SecurityGroupFolderType

Optional

The PubSubKeyServiceType ObjectType is a concrete type and can be used directly.

The SecurityGroups folder organizes the Objects representing the SecurityGroup configuration.

This Method is used to retrieve the security keys for a SecurityGroup.

This Method is required to access the security keys of a PubSubGroup where the SecurityGroup manages the security keys for PubSubGroups. The MessageSecurity Object of the PubSubGroup Object contains the SecurityGroupId that shall be passed to this Method in order to access the keys for the PubSubGroup. Note that multiple PubSubGroups can share a SecurityGroupId.

The Permission of the SecurityGroupType Object for the SecurityGroupId controls the access to the security keys for the SecurityGroupId. If the user used to call this Method does not have the Call Permission set for the related SecurityGroupType Object, the Server shall return Bad_UserAccessDenied for this Method. The SecurityGroupType is defined in 8.6. Encryption is required for this Method. The Method shall return Bad_SecurityModeInsufficient if the communication is not encrypted.

The information necessary to access the Server that implements the GetSecurityKeys Method for the SecurityGroup is also contained in the MessageSecurity Object of the PubSubGroup Object.

The GetSecurityKeys Method can be implemented by a Publisher or by a central SKS. In both cases, the well-known NodeIds for the PublishSubscribe Object and the related GetSecurityKeys Method are used to call the GetSecurityKeys Method.

If the Publisher implements the GetSecurityKeys Method and the related SecurityGroup management, the keys are made invalid immediately after a SecurityGroup is removed or keys for a SecurityGroup are revoked.

If a central SKS implements the GetSecurityKeys Method and the related SecurityGroup management, the keys are no longer valid after a SecurityGroup is removed or keys for a SecurityGroup are revoked. However, Subscribers must be prepared for Publishers using invalid keys until they have called the GetSecurityKeys Method. Publishers using a central SKS shall call GetSecurityKeys at a period of half the KeyLifetime.

Signature

GetSecurityKeys (

[in]String SecurityGroupId

[in]UInt32 StartingTokenId

[in]UInt32 RequestedKeyCount

[out]String SecurityPolicyUri

[out]IntegerId FirstTokenId

[out]ByteString[]Keys

[out]Duration TimeToNextKey

[out]Duration KeyLifetime

);

Argument

Description

SecurityGroupId

The identifier for the SecurityGroup. It shall be unique within the Security Key Service.

StartingTokenId

The current token is requested by passing 0.

It can be a SecurityTokenId from the past to get a key valid for previously sent messages.

If the StartingTokenId is unknown, the oldest available tokens are returned.

RequestedKeyCount

The number of requested keys which should be returned in the response. If 0 is requested, no future keys are returned. If the caller requests a number larger than the Security Key Service permits, then the SKS shall return the maximum it allows.

SecurityPolicyUri

The URI for the set of algorithms and key lengths used to secure the messages. The SecurityPolicies are defined in OPC 10000-7.

FirstTokenId

The SecurityTokenId of the first key in the array of returned keys.

The SecurityTokenId appears in the header of messages secured with a Key. It starts at 1 and is incremented by 1 each time the KeyLifetime elapses even if no keys are requested. If the SecurityTokenId increments past the maximum value of UInt32 it restarts at 1.

If the caller has key material from previous GetSecurityKeys Method calls, the FirstTokenId is used to match the existing list with the fetched list and to eliminate duplicates.

If the FirstTokenId is unknown, the existing list shall be discarded and replaced.

Keys

An ordered list of keys that are used when the KeyLifetime elapses.

If the current key was requested, the first key in the array is used to secure the messages. This key is not used directly since the protocol associated with the PubSubGroup(s) specifies an algorithm to generate distinct keys for different types of cryptography operations. Further details are defined in 7.2.2.2.3.

The SecurityTokenId associated with the first key in the list is the FirstTokenId. All following keys have a SecurityTokenId that is incremented by 1 for every key returned.

TimeToNextKey

The time, in milliseconds, before the CurrentKey is expected to expire.

If a Publisher uses this Method to get the keys from a SKS, the TimeToNextKey and KeyLifetime are used to calculate the time the Publisher shall use the next key. The TimeToNextKey defines the time when to switch from CurrentKey to FutureKeys and the KeyLifetime defines when to switch from one future key to the next future key.

For a Subscriber the TimeToNextKey and KeyLifetime are used to calculate the time the Subscriber must expect that the Publishers use the next key. Due to network latency, out of order delivery and the use of keys for several Publishers, a Subscriber must expect some overlap time where NetworkMessages are received that are using the previous or the next key.

TimeToNextKey and KeyLifetime are also used to calculate the time until Publisher and Subscriber must fetch new keys.

KeyLifetime

The lifetime of a key in milliseconds.

The returned keys may expire earlier if the keys are discarded for some reason. An unplanned key rotation is indicated in the NetworkMessage header before the next key is used to give the Subscriber some time to fetch new keys.

If the CurrentTokenId in the message is not recognized the receiver shall call this Method again to get new keys.

Method Result Codes

ResultCode

Description

Bad_NotFound

The SecurityGroupId is unknown.

Bad_UserAccessDenied

The caller is not allowed to request the keys for the SecurityGroup.

Bad_SecurityModeInsufficient

The communication channel is not using encryption.

This Method provides a direct lookup of the NodeId of a SecurityGroupType Object based on a SecurityGroupId. It is used by a security administration tool to get the SecurityGroup Object for configuration of access permissions for the keys.

The SecurityGroupId is the identifier for the SecurityGroup in Publishers, Subscribers and the key Server. This Method returns the NodeId of the corresponding SecurityGroup Object Node providing the configuration and diagnostic options for a SecurityGroup.

Signature

GetSecurityGroup (

[in]StringSecurityGroupId

[out]NodeIdSecurityGroupNodeId

);

Argument

Description

SecurityGroupId

The SecurityGroupId of the SecurityGroup to lookup.

SecurityGroupNodeId

The NodeId of the SecurityGroupType Object.

Method Result Codes

ResultCode

Description

Bad_NoMatch

The SecurityGroupId cannot be found in the Server.

The SecurityGroupType is formally defined in Table 101.

The Permission of the SecurityGroupType Objects controls the access to the security keys for the SecurityGroup through the Method GetSecurityKeys. The GetSecurityKeys Method is defined in 8.4.

Table 101 – SecurityGroupType Definition

Attribute

Value

BrowseName

SecurityGroupType

IsAbstract

False

References

Node Class

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of BaseObjectType defined in OPC 10000-5.

HasProperty

Variable

SecurityGroupId

String

PropertyType

Mandatory

HasProperty

Variable

KeyLifetime

Duration

PropertyType

Mandatory

HasProperty

Variable

SecurityPolicyUri

String

PropertyType

Mandatory

HasProperty

Variable

MaxFutureKeyCount

UInt32

PropertyType

Mandatory

HasProperty

Variable

MaxPastKeyCount

UInt32

PropertyType

Mandatory

The Property SecurityGroupId contains the identifier for the SecurityGroup used in the key exchange Methods GetSecurityKeys and SetSecurityKeys in the PubSubGroupType.

The Property KeyLifetime defines the lifetime of a key in milliseconds.

The Property SecurityPolicyUri is the identifier for a SecurityPolicy. SecurityPolicies define the set of algorithms and key lengths used to secure the messages exchanged in the context of the SecurityGroup. The SecurityPolicies are defined in OPC 10000-7.

The Property MaxFutureKeyCount defines the maximum number of future keys returned by the Method GetSecurityKeys.

The Property MaxPastKeyCount defines the maximum number of historical keys stored by the SKS. The historical keys are necessary to allow Subscribers to request keys for older NetworkMessages.

The SecurityGroupFolderType is formally defined Table 102.

Table 102 – SecurityGroupFolderType Definition

Attribute

Value

BrowseName

SecurityGroupFolderType

IsAbstract

False

References

Node Class

BrowseName

TypeDefinition

Modelling Rule

Subtype of FolderType defined in OPC 10000-5.

Organizes

Object

<SecurityGroupFolderName>

SecurityGroup FolderType

OptionalPlaceholder

HasComponent

Object

<SecurityGroupName>

SecurityGroupType

OptionalPlaceholder

HasComponent

Method

AddSecurityGroup

Defined in 8.8.

Mandatory

HasComponent

Method

RemoveSecurityGroup

Defined in 8.9.

Mandatory

The SecurityGroupFolderType ObjectType is a concrete type and can be used directly.

Instances of the SecurityGroupFolderType can contain SecurityGroup Objects or other instances of the SecurityGroupFolderType. This can be used to build a tree of folder Objects used to organize the configured SecurityGroups.

The SecurityGroup Objects are added as components to the instance of the SecurityGroupFolderType. A SecurityGroup Object is referenced only from one folder. If the folder is deleted, all referenced SecurityGroup Objects are deleted with the folder.

This Method is used to add a SecurityGroupType Object to the SecurityGroupFolderType Object.

The Client shall be authorized to modify the configuration for the PubSub functionality when invoking this Method on the Server.

Signature

AddSecurityGroup (

[in]StringSecurityGroupName

[in]DurationKeyLifetime

[in]StringSecurityPolicyUri

[in]UInt32MaxFutureKeyCount

[in]UInt32MaxPastKeyCount

[out]StringSecurityGroupId

[out]NodeIdSecurityGroupNodeId

);

Argument

Description

SecurityGroupName

Name of the SecurityGroup to add.

KeyLifetime

The lifetime of a key in milliseconds

SecurityPolicyUri

The SecurityPolicy used for the SecurityGroup.

MaxFutureKeyCount

The maximum number of future keys returned by the Method GetSecurityKeys.

MaxPastKeyCount

The maximum number of historical keys stored by the SKS

SecurityGroupId

The identifier for the SecurityGroup.

SecurityGroupNodeId

The NodeId of the added SecurityGroupType Object.

Method Result Codes

ResultCode

Description

Bad_NodeIdExists

A SecurityGroup with the name already exists.

Bad_UserAccessDenied

The Session user is not allowed to configure the object.

This Method is used to remove a SecurityGroupType Object from the SecurityGroupFolderType Object.

The Client shall be authorized to modify the configuration for the PubSub functionality and for the SecurityGroup to delete when invoking this Method on the Server.

See 8.4 for details on the lifetime of keys previously issued for this SecurityGroup.

Signature

RemoveSecurityGroup (

[in]NodeIdSecurityGroupNodeId

);

Argument

Description

SecurityGroupNodeId

NodeId of the SecurityGroupType Object to remove from the Server

Method Result Codes

ResultCode

Description

Bad_NodeIdUnknown

The SecurityGroupNodeId is unknown.

Bad_NodeIdInvalid

The SecurityGroupNodeId is not a NodeId of a SecurityGroupType Object.

Bad_UserAccessDenied

The Session user is not allowed to delete the SecurityGroupType Object.