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.6. 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 Object of the PubSubGroup Object.

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, Subscribersmust be prepared for Publishersusing invalid keys until they have called the GetSecurityKeys Method. Publishersusing a central SKS shall call GetSecurityKeysat 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 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 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 SecurityTokenIdthat is incremented by 1 for every key returned.

TimeToNextKey

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

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 CurrentKeyto FutureKeysand 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 Subscribermust expect that the Publishersuse the next key. Due to network latency, out of order delivery and the use of keys for several Publishers, a Subscribermust 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 Subscribermust 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.