This Methodis used to retrieve the security keys for a SecurityGroup.

This Methodis required to access the security keys of a PubSubGroupwhere the SecurityGroupmanages the security keys for PubSubGroups. The MessageSecurity Object of the PubSubGroup Objectcontains the SecurityGroupIdthat shall be passed to this Methodin order to access the keys for the PubSubGroup. Note that multiple PubSubGroupscan share a SecurityGroupId.

The Permissionof the SecurityGroupType Objectfor the SecurityGroupIdcontrols the access to the security keys for the SecurityGroupId. If the user used to call this Methoddoes not have the Call Permissionset for the related SecurityGroupType Object, the Servershall return Bad_UserAccessDeniedfor this Method. The SecurityGroupTypeis defined in 8.4.

Encryption is required for this Method. The Methodshall return Bad_SecurityModeInsufficient if the communication is not encrypted.

The information necessary to access the Serverthat implements the GetSecurityKeys Methodfor the SecurityGroupis also contained in the MessageSecurity settingof WriterGroup, ReaderGroup and DataSetReader.

The GetSecurityKeys Methodcan be implemented by a Publisheror by a central SKS. In both cases, the well-known NodeIdsfor the PublishSubscribe Objectand the related GetSecurityKeys Methodare used to call the GetSecurityKeys Method.

If thePublisher implements theGetSecurityKeys Method and the relatedSecurityGroup management, the keys are made invalid immediately after a SecurityGroupis removed or keys for a SecurityGroupare revoked.

If a central SKS implements theGetSecurityKeys Method and the relatedSecurityGroup management, the keys are no longer valid after a SecurityGroupis removed or keys for a SecurityGroupare revoked. However, Subscribersshall be prepared for Publishersusing invalid keys until they have called the GetSecurityKeys Method.

Publishersusing a central SKS shall call GetSecurityKeysalways with StartingTokenIdset to 0 and shall call the Methodat a period of half the KeyLifetime. They can still request more than one key to bridge longer unavailability time of the SKS.

Subscribersshould use a StartingTokenIdof 0 the first time they call GetSecurityKeys. Subsequent call to request older or future keys can use specific StartingTokenIds.

Signature

GetSecurityKeys(

[in]String SecurityGroupId,

[in]IntegerId 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 and the related current key is requested by passing 0.

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

If the StartingTokenIdis 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 Servicepermits, 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 SecurityPoliciesare defined in OPC 10000-7.

FirstTokenId

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

The SecurityTokenIdappears in the header of messages secured with a Key. It starts at 1 and is incremented by 1 each time the KeyLifetimeelapses even if no keys are requested. If the SecurityTokenIdincrements past the maximum value of UInt32it restarts at 1.

If the caller has key material from previous GetSecurityKeys Methodcalls, the FirstTokenIdis used to match the existing list with the fetched list and to eliminate duplicates.

If the FirstTokenIdis 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 used according to the SecurityPolicy identified by the SecurityPolicyUriand the protocol associated with the PubSubGroup(s). Further details are defined in 7.2.2.4.3.

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

TimeToNextKey

The time, in milliseconds, before the current keyis expected to expire. The current SecurityTokenIdequals the FirstTokenIdand the current key is the first one in the returned Keysif the passed StartingTokenIdis 0. Therefore the Methodshall be called with StartingTokenIdset to 0 if there is no previous knowledge about the current key.

If a Publisheruses this Methodto get the keys from a SKS, the TimeToNextKeyand KeyLifetimeare used to calculate the time the Publishershall use the next key. The TimeToNextKeydefines the time when to switch from the current key to the next key and the KeyLifetimedefines when to switch from one future key to the next future key.

For a Subscriberthe TimeToNextKeyand KeyLifetimeare used to calculate the time the Subscriberexpects that the Publishersuse the next key. Due to network latency, out of order delivery and the use of keys for several Publishers, a Subscriberneeds to expect some overlap time where NetworkMessagesare received that are using the previous or the next key.

TimeToNextKeyand KeyLifetimeare also used to calculate the time until Publisherand Subscribershall 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 NetworkMessageheader before the next key is used to give the Subscribersome time to fetch new keys.

If the CurrentTokenIdin the message is not recognized the receiver shall call this Methodagain to get new keys.

Method Result Codes

ResultCode

Description

Bad_NotFound

The SecurityGroupIdis unknown.

Bad_UserAccessDenied

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

Bad_SecurityModeInsufficient

The communication channel is not using encryption.

Table 171specifies the AddressSpacerepresentation for the GetSecurityKeys Method.

Table 171– GetSecurityKeys Method AddressSpace definition

Attribute

Value

BrowseName

GetSecurityKeys

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

HasProperty

Variable

InputArguments

Argument[]

PropertyType

Mandatory

HasProperty

Variable

OutputArguments

Argument[]

PropertyType

Mandatory

ConformanceUnits

PubSub Model SKS