The AddressSpace used for PullManagement is shown in Figure 25. Clients interact with the Nodes defined in this model when they need to request or revoke KeyCredentials for themselves or for another application. The KeyCredentialManagement Folder is a well-known Object that appears in the AddressSpace of any Server which supports KeyCredential management.

image028.png

Figure 25 – The Address Space used for Pull KeyCredential Management

This ObjectType represents a Folder that contains KeyCredentialService Objects which may be accessed via the Server. It is defined in Table 83.

Table 83 – KeyCredentialManagementFolderType Definition

Attribute

Value

BrowseName

2:KeyCredentialManagementFolderType

IsAbstract

False

References

NodeClass

BrowseName

TypeDefinition

Modelling Rule

Subtype of the 0:FolderType defined in OPC 10000-5.

0:HasComponent

Object

2:<ServiceName>

2:KeyCredentialServiceType

OptionalPlaceholder

Conformance Units

GDS Key Credential Service Pull Model

This Object contains the KeyCredentialService Objects which may be accessed via the Server. It is the target of an Organizes reference from the Objects Folder defined in OPC 10000-5. It is defined in Table 84.

Table 84 – KeyCredentialManagement Object Definition

Attribute

Value

BrowseName

2:KeyCredentialManagement

TypeDefinition

2:KeyCredentialManagementFolderType defined in 8.5.2.

References

NodeClass

BrowseName

TypeDefinition

Modelling Rule

Conformance Units

GDS Key Credential Service Pull Model

This ObjectType is the TypeDefinition for an Object that allows the management of KeyCredentials. It is defined in Table 85.

Table 85 – KeyCredentialServiceType Definition

Attribute

Value

BrowseName

2:KeyCredentialServiceType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the BaseObjectType defined in OPC 10000-5.

0:HasProperty

Variable

2:ResourceUri

0:String

0:PropertyType

Mandatory

0:HasProperty

Variable

2:ProfileUris

0:String[]

0:PropertyType

Mandatory

0:HasProperty

Variable

2:SecurityPolicyUris

0:String[]

0:PropertyType

Optional

0:HasComponent

Method

2:StartRequest

Defined in 8.5.5.

Mandatory

0:HasComponent

Method

2:FinishRequest

Defined in 8.5.6.

Mandatory

0:HasComponent

Method

2:Revoke

Defined in 8.5.7.

Optional

Conformance Units

GDS Key Credential Service Pull Model

The ResourceUri Property uniquely identifies the resource that accepts the KeyCredentials provided by the KeyCredentialService Object.

The ProfileUris Property specifies URIs assigned in OPC 10000-7 to the authentication mechanism used to communicate with the resource that accepts KeyCredentials provided by the Object. For example, it could specify that the resource returns JWTs using OAuth2 HTTP based APIs. As another example, it could specify an MQTT broker that expects a username/password.

The SecurityPolicyUris Property is the list of SecurityPolicies that may be used when encrypting the KeyCredentials. One of these URIs is passed in the StartRequest Method. If not present, The Server shall support all of the SecurityPoliciesUris returned by GetEndpoints,

The StartRequest Method is used to initiate a request for new KeyCredentials for an application. This request may complete immediately or it can require offline approval by an administrator.

The FinishRequest Method is used to complete a request created by calling StartRequest . If the KeyCredential is available it is returned. If request is not yet completed it returns Bad_NothingToDo.

The Revoke Method is used to revoke a previously issued KeyCredential.

StartRequest is used to request a new KeyCredential.

The KeyCredential secret may be encrypted with the public key of the Certificate supplied in the request. The SecurityPolicyUri specifies the security profile used for the encryption.

This Method shall be called from an encrypted SecureChannel and from a Client that has access to the KeyCredentialAdmin Role, the ApplicationAdmin Privilege, or the ApplicationSelfAdmin Privilege (see 8.2).

Signature

StartRequest (

[in] String applicationUri

[in] ByteString publicKey

[in] String securityPolicyUri

[in] NodeId[] requestedRoles

[out] NodeId requestId

);

Argument

Description

applicationUri

The applicationUri of the application receiving the KeyCredentials.

The request is rejected applicationUri does not uniquely identify an application known to the GDS (see 6.6.6).

If the requestor is not the same as the application used to create the Secure Channel then a Certificate should be provided.

publicKey

A Public Key used to encrypt the returned KeyCredential secret. For RSA SecurityPolicies this is the DER encoded form of an X.509 v3 Certificate as described in OPC 10000-6. For ECC SecurityPolicies this is an ephemeral key created by the owner of the KeyCredentials.

Not specified if no encryption is required.

If the securityPolicyUri is provided this field shall be provided.

securityPolicyUri

The SecurityPolicy used to encrypt the secret.

If the certificate is provided this field shall be provided.

requestedRoles

A list of Roles which should be assigned to the KeyCredential.

If not provided the Server chooses suitable defaults.

The Server ignores Roles which it does not recognize or if the caller is not authorized to request access to the Role.

requestId

A unique identifier for the request.

This identifier shall be passed to the FinishRequest (see 8.5.6).

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_NotFound

The applicationUri is not known to the GDS.

Bad_ConfigurationError

The applicationUri is used by multiple records in the GDS.

Bad_CertificateInvalid

The Certificate is invalid.

Bad_SecurityPolicyRejected

The SecurityPolicy is unrecognized or not allowed or does not match the Certificate.

Bad_UserAccessDenied

The current user does not have the rights required.

Bad_SecurityModeInsufficient

The SecureChannel is not encrypted.

Table 86 specifies the AddressSpace representation for the StartRequest Method.

Table 86 – StartRequest Method AddressSpace Definition

Attribute

Value

BrowseName

2:StartRequest

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

FinishRequest is used to retrieve a KeyCredential.

If a Certificate was provided in the request then the KeyCredential secret is encrypted using an asymmetric encryption algorithm specified by the SecurityPolicyUri provided in the request.

The credentialId is the identifier, such as a user name, which often needs to be presented when using the credentialSecret.

The credentialSecret is a UA Binary encoded form of one of the EncryptedSecret DataTypes defined in OPC 10000-4. If the securityPolicyUri requires an RSA Certificate then the RsaEncryptedSecret DataType is used. If the securityPolicyUri requires an ECC Certificate then the EccEncryptedSecret DataType is used.

The Signing Certificate is owned by the source of the KeyCredential. The KeyCredentialService determines the most appropriate Certificate to use.

If the return code is Bad_RequestNotComplete then the request has not been processed and the Client should call again. It is expected that a Client will periodically call this Method until the KeyCredentialService has completed the request.

This Method shall be called from an encrypted SecureChannel and from a Client that has access to the KeyCredentialAdmin Role, the ApplicationAdmin Privilege, or the ApplicationSelfAdmin Privilege (see 8.2). In addition, this Method shall only be called SecureChannel using that same Certificate that Client used to call StartRequest.

Signature

FinishRequest (

[in] NodeId requestId

[in] Boolean cancelRequest

[out] String credentialId

[out] ByteString credentialSecret

[out] String certificateThumbprint

[out] String securityPolicyUri

[out] NodeId[] grantedRoles

);

Argument

Description

requestId

The identifier returned from a previous call to StartRequest.

cancelRequest

If TRUE the request is cancelled and no KeyCredentials are returned.

If FALSE the normal processing proceeds.

credentialId

The unique identifier for the KeyCredential.

credentialSecret

The secret associated with the KeyCredential.

certificateThumbprint

The thumbprint of the Certificate used to encrypt the secret for RSA SecurityPolicies. Set to NULL for ECC SecurityPolicies.

securityPolicyUri

The SecurityPolicy used to create the credentialSecret.

grantedRoles

A list of Roles which have been granted to KeyCredential.

If empty then the information is not relevant or not available.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_InvalidArgument

The requestId is does not reference to a valid request for the Application.

Bad_RequestNotComplete

The request has not been processed by the Server yet.

Bad_UserAccessDenied

The current user does not have the rights required.

Bad_RequestNotAllowed

The KeyCredential manager rejected the request.

The text associated with the error should indicate the exact reason.

Bad_SecurityModeInsufficient

The SecureChannel is not encrypted.

Table 87 specifies the AddressSpace representation for the FinishRequest Method.

Table 87 – FinishRequest Method AddressSpace Definition

Attribute

Value

BrowseName

2:FinishRequest

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument[]

0:PropertyType

Mandatory

0:HasProperty

Variable

0:OutputArguments

0:Argument[]

0:PropertyType

Mandatory

Revoke is used to revoke a KeyCredential used by a Client or Server.

KeyCredentials shall be deleted when revoked.

This Method shall be called from an encrypted SecureChannel and from a Client that has access to the KeyCredentialAdmin Role, the ApplicationAdmin Privilege, or the ApplicationSelfAdmin Privilege (see 8.2).

Signature

Revoke (

[in] String credentialId

);

Argument

Description

credentialId

The unique identifier for the KeyCredential.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_InvalidArgument

The credentialId is does not reference a valid KeyCredential.

Bad_UserAccessDenied

The current user does not have the rights required.

Bad_SecurityModeInsufficient

The SecureChannel is not encrypted.

Table 88 specifies the AddressSpace representation for the RevokeCredential Method.

Table 88 – Revoke Method AddressSpace Definition

Attribute

Value

BrowseName

2:Revoke

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

HasProperty

Variable

0:InputArguments

Argument[]

0:PropertyType

Mandatory

This abstract event is raised when an operation affecting KeyCredentials occur

This Event and it subtypes are security related and Servers shall only report them to users authorized to view security related audit events.

Its representation in the AddressSpace is formally defined in Table 90.

Table 89 – KeyCredentialAuditEventType Definition

Attribute

Value

BrowseName

0:KeyCredentialAuditEventType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:AuditUpdateMethodEventType defined in OPC 10000-5.

0:HasProperty

Variable

ResourceUri

String

0:PropertyType

Mandatory

Conformance Units

GDS Key Credential Service Pull Model

This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantic is defined in OPC 10000-5.

The ResourceUri Property specifies the URI for the resource which accepts the KeyCredential.

This event is raised when a new KeyCredential request has been accepted or rejected by the Server.

This can be the result of a StartRequest Method call.

Its representation in the AddressSpace is formally defined in Table 90.

Table 90 – KeyCredentialRequestedAuditEventType Definition

Attribute

Value

BrowseName

2:KeyCredentialRequestedAuditEventType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:KeyCredentialAuditEventType defined in 8.5.8.

Conformance Units

GDS Key Credential Service Pull Model

This EventType inherits all Properties of the KeyCredentialAuditEventType.

This event is raised when a KeyCredential is delivered by the Server to an application.

This is the result of a FinishRequest Method completing.

Its representation in the AddressSpace is formally defined in Table 91.

Table 91 – KeyCredentialDeliveredAuditEventType Definition

Attribute

Value

BrowseName

2:KeyCredentialDeliveredAuditEventType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:KeyCredentialAuditEventType defined in 8.5.8.

Conformance Units

GDS Key Credential Service Pull Model

This EventType inherits all Properties of the KeyCredentialAuditEventType.

This event is raised when a KeyCredential is revoked.

This is the result of a RevokeKeyCredential Method completing.

Its representation in the AddressSpace is formally defined in Table 92.

Table 92 – KeyCredentialRevokedAuditEventType Definition

Attribute

Value

BrowseName

2:KeyCredentialRevokedAuditEventType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 0:KeyCredentialAuditEventType defined in 8.5.8.

Conformance Units

GDS Key Credential Service Pull Model

This EventType inherits all Properties of the KeyCredentialAuditEventType.