The PubSubKeyServiceTypeis formally defined in Table 170.
Table 170– PubSubKeyServiceType definition
Attribute |
Value |
||||
BrowseName |
PubSubKeyServiceType |
||||
IsAbstract |
False |
||||
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
Subtype of BaseObjectType defined in OPC 10000-5. |
|||||
HasComponent |
Method |
GetSecurityKeys |
Defined in 8.3.2. |
Optional |
|
HasComponent |
Method |
GetSecurityGroup |
Defined in 8.3.3. |
Optional |
|
HasComponent |
Object |
SecurityGroups |
|
SecurityGroupFolderType |
Optional |
HasComponent |
Object |
KeyPushTargets |
|
PubSubKeyPushTargetFolderType |
Optional |
Conformance Units |
|||||
PubSub Model SKS |
The PubSubKeyServiceType ObjectTypeis a concrete type and can be used directly.
The SecurityGroupsfolder organizes the Objectsrepresenting the SecurityGroupconfiguration.
The KeyPushTargetsfolder organizes the Objectsrepresenting the PubSubKeyPushTargetconfiguration.
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 |
This Methodprovides a direct lookup of the NodeIdof aSecurityGroupType Objectbased on a SecurityGroupId. It is used by a security administration tool to get the SecurityGroup Objectfor configuration of access permissions for the keys.
The SecurityGroupIdis the identifier for the SecurityGroupin Publishers, Subscribersand the key Server. This Methodreturns the NodeIdof the corresponding SecurityGroup Object Nodeproviding the configuration and diagnostic options for a SecurityGroup.
Signature
GetSecurityGroup(
[in]StringSecurityGroupId,
[out]NodeIdSecurityGroupNodeId
);
Argument |
Description |
SecurityGroupId |
The SecurityGroupIdof the SecurityGroupto lookup. |
SecurityGroupNodeId |
The NodeIdof the SecurityGroupType Object. |
Method Result Codes
ResultCode |
Description |
Bad_NoMatch |
The SecurityGroupId cannot be found in the Server. |
Table 172specifies the AddressSpacerepresentation for the GetSecurityGroup Method.
Table 172– GetSecurityGroup Method AddressSpace definition
Attribute |
Value |
||||
BrowseName |
GetSecurityGroup |
||||
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
HasProperty |
Variable |
InputArguments |
Argument[] |
PropertyType |
Mandatory |
HasProperty |
Variable |
OutputArguments |
Argument[] |
PropertyType |
Mandatory |
ConformanceUnits |
|||||
PubSub Model SKS |