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 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 configuration parameter RolePermissions contained in the SecurityGroupDataType 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 RolePermissions parameter for the related SecurityGroupType Object, the Server shall return Bad_UserAccessDenied for this Method. The SecurityGroupType is defined in 8.4.
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 SecurityKeyServices setting of WriterGroup, ReaderGroup and DataSetReader.
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 shall be prepared for Publishers using invalid keys until they have called the GetSecurityKeys Method.
Publishers using a central SKS shall call GetSecurityKeys always with StartingTokenId set to 0 and shall call the Method at a period of half the KeyLifetime. They can still request more than one key to bridge longer unavailability time of the SKS.
Subscribers should use a StartingTokenId of 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 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 used according to the SecurityPolicy identified by the SecurityPolicyUri and the protocol associated with the PubSubGroup(s). Further details are defined in 7.2.4.4.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 current key is expected to expire. The current SecurityTokenId equals the FirstTokenId and the current key is the first one in the returned Keys if the passed StartingTokenId is 0. Therefore the Method shall be called with StartingTokenId set to 0 if there is no previous knowledge about the current key. 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 the current key to the next key 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 expects 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 needs to 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 shall 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. |
Table 184 specifies the AddressSpace representation for the GetSecurityKeys Method.
Table 184 – 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 |
|||||