Errata exists for this version of the document.

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.

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.