Errata exists for this version of the document.
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. |