The Registrar described in 7 is a Server that implements the Information Model shown in Figure 9. This Information Model allows new Devices to use pull management described in 7.2 to authenticate themselves. It also allows Endpoints for new Devices to be manually registered for PushManagement when no multicast discovery mechanism is available.

image012.gif

Figure 9 – Registrar Address Space for Onboarding Workflow

The DeviceRegistrarType ObjectType represents an entity that provides the services needed when authenticating Devices on a network. The ObjectType is defined in Table 17.

Table 17 – DeviceRegistrarType Definition

Attribute

Value

BrowseName

2:DeviceRegistrarType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

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

0:HasComponent

Method

2:ProvideIdentities

Defined in 9.2.3.

Mandatory

0:HasComponent

Method

2:UpdateSoftwareStatus

Defined in 9.2.4.

Mandatory

0:HasComponent

Method

2:RegisterDeviceEndpoint

Defined in 9.2.5.

Mandatory

0:HasComponent

Method

2:GetManagers

Defined in9.2.6.

Mandatory

0:HasComponent

Method

2:RegisterManagedApplication

Defined in 9.2.8.

Mandatory

0:HasComponent

Object

2:Administration

2:DeviceRegistrarAdminType

Optional

Conformance Units

Onboarding Registrar PullManagement

The ProvideIdentities Method allows a Device to request that it be authenticated so it can have access to the network.

The UpdateSoftwareStatus Method is used by the SoftwareUpdateManager to tell the Registrar that the Device has up to date software.

The RegisterDeviceEndpoint Method allows an administration Client to provide the location of a Device on the network that needs to be authenticated. The expectation is calling this Method would start a background task register the Device using PullManagement. If an administration Client needs to register many Devices it can call the RegisterDeviceEndpoint Method multiple times in a single Call request.

The GetManagers Method returns the location of the SoftwareUpdateManager and CertificateManager which an authenticated DCA needs to use to complete the onboarding process.

The RegisterManagedApplication Method allows the DCA to register Applications that it needs to manage with the Registrar.

The Administration Object allows an administration Client to manage Tickets and Certificates received out of band that are needed for the automated registration process.

The ProvideIdentities Method allows a Device to request that it be authenticated so it can have access to the network. It is called by a Device using PullManagement to provide the Registrar with its DeviceIdentity Certificates. The Registrar follows the process described in 7 to select and validate one of the Certificates.

This Method shall be called from an authenticated SecureChannel.

Signature

ProvideIdentities (

[in]0:ByteString [] identities,

[in]0:ByteString [] issuers,

[in]0:EncodedTicket [] tickets,

[out]0:ByteString selectedIdentity,

[out]2:BaseTicketType matchingTicket,

[out]0:NodeId applicationId,

[out]2:ManagerDescriptionsoftwareUpdateManager

);

Argument

Description

identities

The DER encoded DeviceIdentity Certificates issued to the Device.

The first Certificates shall be the IDevID Certificates.

issuers

The DER encoded Certificates needed to verify the DeviceIdentity Certificates.

Certificates that cannot be verified are ignored.

tickets

The signed Tickets stored on the Device.

This argument may be null. If the Registrar returns a Bad_TicketRequired error this Method needs to called again with any available Tickets.

Tickets that cannot be verified are ignored.

selectedIdentity

The DER encoded DeviceIdentity Certificate that the DCA needs to use to complete the registration process.

matchingTicket

The Ticket describing the Device which the Registrar accepted.

applicationId

The identifier assigned by the CertificateManager to the Device.

This identifier is needed to request Certificates from the CertificateManager.

softwareUpdateManager

The Endpoint for the SoftwareUpdateManager which the caller contacts to complete the onboarding process.

Set to NULL if a software update is not required or not supported.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_CertificateInvalid

None of the identity Certificates can be verified.

Bad_TicketRequired

The Device has to provide a Ticket before it can be accepted.

Bad_NotFound

No valid Ticket was found.

Table 18 specifies the AddressSpace representation for the ProvideIdentities Method.

Table 18 – ProvideIdentities Method AddressSpace Definition

Attribute

Value

BrowseName

2:ProvideIdentities

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

HasProperty

Variable

0:InputArguments

0:Argument []

0:PropertyType

Mandatory

HasProperty

Variable

0:OutputArguments

0:Argument []

0:PropertyType

Mandatory

The UpdateSoftwareStatus Method allows a Client to provide the firmware status for a Device on the network.

The Client may be the SoftwareUpdateManager (see 4.2.5) or other administrative application that allows a human to provide information about a manual process.

This Method shall be called from an authenticated SecureChannel and from a Session that has access to the SoftwareUpdateAdmin Role (see 4.2.6).

Signature

UpdateSoftwareStatus(

[in]0:String productInstanceUri,

[in]0:Boolean status,

[in]0:String softwareRevision

);

Argument

Description

productInstanceUri

The unique identifier for the Device.

status

The status of the software.

If TRUE the firmware is up to date, otherwise, an update is required before the Device can be used on the network.

softwareRevision

The version of the software which is running on the Device (status=TRUE) or needs to be installed on the Device (status=FALSE).

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The Session does not have the permissions needed to call the Method.

Bad_NotFound

The productInstanceUri does not refer to a known Device.

Table 19 specifies the AddressSpace representation for the UpdateSoftwareStatus Method.

Table 19 – UpdateSoftwareStatus Method AddressSpace Definition

Attribute

Value

BrowseName

2:UpdateSoftwareStatus

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument []

0:PropertyType

Mandatory

The RegisterDeviceEndpoint Method allows a Client to provide the location of a Device on the network that needs to be authenticated.

The Client may be an engineering tool or other administrative application that allows a human to provide information that cannot be discovered automatically.

Once the Registrar knows the location of a Device it schedules a task that uses PushManagement to complete the onboarding process.

This Method shall be called from an authenticated SecureChannel and from a Session that has access to the RegistrarAdmin Role (see 4.2.6).

Signature

RegisterDeviceEndpoint (

[in]0:ApplicationDescription application

);

Argument

Description

application

The Server which allows a Device to be authenticated via the Push Model.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The Session does not have the permissions needed to call the Method.

Table 20 specifies the AddressSpace representation for the RegisterDeviceEndpoint Method.

Table 20 – RegisterDeviceEndpoint Method AddressSpace Definition

Attribute

Value

BrowseName

2:RegisterDeviceEndpoint

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:InputArguments

0:Argument []

0:PropertyType

Mandatory

The GetManagers Method allows a Registrar to provide the location of other managers on a network which are needed to support onboarding of Devices. The managers have network Endpoints that may support non-OPC UA protocols. The DCA has knowledge of what managers it can use and what protocol they use.

The response is a list of ManagerDescriptions that includes a URI which defines the purpose of the manager and a flag indicating whether the DCA is required to interact with the manager to complete the onboarding process.

Each ManagerDescription has 1 or more URLs which are network Endpoints accessible to the DCA.

This Method shall be called from an authenticated SecureChannel and from a Session that has access to the DCA Privilege (see 4.2.6).

Signature

GetManagers (

[out]2:ManagerDescription [] managers

);

Argument

Description

managers

The managers which the DCA has access to.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The Session does not have the permissions needed to call the Method.

Table 21 specifies the AddressSpace representation for the GetManagers Method.

Table 21 – GetManagers Method AddressSpace Definition

Attribute

Value

BrowseName

2:GetManagers

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

0:HasProperty

Variable

0:OutputArguments

0:Argument []

0:PropertyType

Mandatory

The ManagerDescription provides metadata and the location of a manager on the network such as a SoftwareUpdateManager or a CertificateManager.

The following purposeUris are defined by this specification:

http://opcfoundation.org/UA/Onboarding/CertificateManager

http://opcfoundation.org/UA/Onboarding/SoftwareUpdateManager

Other purposes may be defined by the Registrar.

The fields of this DataType are defined in Table 7.

Table 22 – ManagerDescription Structure

Name

Type

Description

ManagerDescription

0:Structure

Subtype of the Structure DataType defined in OPC 10000-5.

name

0:LocalizedText

A human readable name for the manager.

isRequired

0:Boolean

If TRUE then interaction with this manager is required to complete the onboarding process.

purposeUri

0:UriString

A unique identifier for the purpose of the manager.

protocolUri

0:UriString

A unique identifier for the communication protocol used by the manager endpoints. If not specified the protocol is OPC UA.

endpointUrls

0:String []

A list of network endpoints.

Its representation in the AddressSpace is defined in Table 23.

Table 23 – ManagerDescription Definition

Attribute

Value

BrowseName

2:ManagerDescription

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Other

Subtype of the Structure DataType defined in OPC 10000-5.

Conformance Units

Onboarding Registrar PullManagement

The RegisterManagedApplication Method allows a DCA using pull management to register an application that it manages. The Registrar creates whatever records are needed in the CertificateManager and returns the ApplicationIds which are needed to request Certificates and TrustLists for the Application.

The ProtocolUri is only specified when the Application does not support OPC UA. It indicates what protocol the Application supports.

The Registrar shall have some mechanism to verify that a DCA is authorized to manage Application (e.g. DNS name check, pre-populated permission list, human review, et. al.). If the DCA is not authorized the Registrar returns Bad_RequestNotAllowed.

This Method shall be called from an authenticated SecureChannel and from a Session that has access to the DCA Privilege (see 4.2.6).

Signature

RegisterManagedApplication (

[in]3:ApplicationRecordDataType application,

[in]0:UriString protocolUri,

[out]0:NodeId applicationId

);

Argument

Description

application

The application to register.

protocolUri

The URI identifying the protocol supported by a non-OPC UA Application.

applicationId

The applicationId assigned to the application.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The caller does not have the rights to call the Method.

Bad_RequestNotAllowed

The caller is not allowed to manage the specified Application.

Table 24 specifies the AddressSpace representation for the RegisterManagedApplication Method.

Table 24 – RegisterManagedApplication Method AddressSpace Definition

Attribute

Value

BrowseName

2:RegisterManagedApplication

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

The DeviceRegistrar Object is a well-known Object that is present in the AddressSpace of a Server that is a Registrar. It is formally defined in Table 25.

Table 25 – DeviceRegistrar Definition

Attribute

Value

BrowseName

2:DeviceRegistrar

TypeDefinition

2:DeviceRegistrarType defined in 9.2.2.

References

Node Class

BrowseName

DataType

TypeDefinition

Modelling Rule

OrganizedBy the Objects Object defined in OPC 10000-5.

Conformance Units

Onboarding Registrar PullManagement

The DeviceRegistrarAdminType ObjectType that provides an interface to manage the TrustLists and Tickets used by the Registrar when authenticating Devices on a network. The ObjectType is defined in Table 26

Table 26 – DeviceRegistrarAdminType Definition

Attribute

Value

BrowseName

2:DeviceRegistrarAdminType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the BaseObjectType defined in OPC 10000-5.

0:HasComponent

Method

2:RegisterTickets

Defined in 9.2.11.

Mandatory

0:HasComponent

Method

2:UnregisterTickets

Defined in 9.2.12.

Mandatory

0:HasComponent

Object

2:TicketAuthorities

0:TrustListType

Mandatory

0:HasComponent

Object

2:DeviceIdentityAuthorities

0:TrustListType

Mandatory

Conformance Units

Onboarding Registrar Administration

The RegisterTickets Method allows an administration Client to provide a list of Tickets for Devices and Composites that it is expecting to install on the network. Any Device which matches one of these Tickets will be accepted automatically.

The UnregisterTickets Method allows an administration Client to remove Tickets for Devices and Composites that it previously provided. Removing Tickets does not affect Devices that were previously accepted using the Tickets.

The TicketAuthorities Object allows an administration Client to manage the Certificates for authorities that sign Tickets. If a Device provides a Ticket, it is accepted automatically if and only if the signing Certificate is in this list.

The DeviceIdentityAuthorities Object allows an RegistrarAdmin manage the trusted DeviceIdentity Certificates. This list can contain individual DeviceIdentity Certificates that have a valid Ticket or it can contain the issuers for DeviceIdentity Certificates that are provided out of band.

The RegisterTickets Method allows an administration Client to provide a list of Tickets for Devices and Composites that it is expecting to install on the network. Any Device which can be correlated with one of these Tickets will be accepted automatically.

This Method validates each Ticket. Invalid Tickets are rejected. Validation errors are returned in the results output argument.

This Method shall be called from a Session that has access to the RegistrarAdmin Role (see 4.2.6).

Signature

RegisterTickets (

[in]0:EncodedTicket [] tickets,

[out]0:StatusCode []results

);

Argument

Description

tickets

The signed Tickets which should be treated as trusted.

results

The result of the Ticket validation process described in 6.4.

If validation fails the returned value is Bad_TicketInvalid.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The Client is not authorized to update the set of known Tickets.

Table 27 specifies the AddressSpace representation for the RegisterTickets Method.

Table 27 – RegisterTickets Method AddressSpace Definition

Attribute

Value

BrowseName

2:RegisterTickets

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

The UnregisterTickets Method allows a RegistrarAdmin to remove Tickets for Devices and Composites that it previously provided. Removing Tickets does not affect Devices that were previously accepted using the Tickets.

If the Ticket does not exist an error is returned in the results output argument.

If an error processing a Ticket occurs the error for that Ticket is returned in the results argument. If a Ticket does not exist the error is Bad_NotFound.

This Method shall be called from a Session that has access to the RegistrarAdmin Role (see 4.2.6).

Signature

UnregisterTickets (

[in]0:EncodedTicket []tickets,

[out]0:StatusCode []results

);

Argument

Description

tickets

The signed Tickets which should no longer be treated as trusted.

results

Indicates whether a previously registered Ticket was found.

If not found the returned value is Bad_NotFound.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_UserAccessDenied

The Client is not authorized to update the set of known Tickets.

Table 28 specifies the AddressSpace representation for the UnregisterTickets Method.

Table 28 – UnregisterTickets Method AddressSpace Definition

Attribute

Value

BrowseName

2:UnregisterTickets

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

This abstract Event is a base type for events raised when a change affecting Device registration occurs.

This Event and its subtypes are security related and Servers shall only report them to Sessions with access to the SecurityAdmin Role.

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

Table 29 – DeviceRegistrationAuditEventType Definition

Attribute

Value

BrowseName

2:DeviceRegistrationAuditEventType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

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

0:HasProperty

Variable

2:ProductInstanceUri

0:UriString

0:PropertyType

Mandatory

0:HasSubtype

ObjectType

2:DeviceIdentityAcceptedAuditEventType

Defined in 9.2.14.

0:HasSubtype

ObjectType

2:DeviceSoftwareUpdatedAuditEventType

Defined in 9.2.15.

Conformance Units

Onboarding Registrar PullManagement

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

The ProductInstanceUri Property specifies the identity for the Device that was affected by the change.

This abstract Event is raised when the Registrar accepts a DeviceIdentity. This occurs when the Registrar finds a matching validated Ticket and is able to validate a DeviceIdentity Certificate.

This Event and it subtypes are security related and Servers shall only report them to Sessions with access to the SecurityAdmin Role.

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

Table 30 – DeviceIdentityAcceptedAuditEventType Definition

Attribute

Value

BrowseName

2:DeviceIdentityAcceptedAuditEventType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 2:DeviceRegistrationAuditEventType defined in 9.2.13

0:HasProperty

Variable

2:Certificate

0:ByteString

0:PropertyType

Mandatory

0:HasProperty

Variable

2:Ticket

0:EncodedTicket

0:PropertyType

Mandatory

0:HasProperty

Variable

2:Composite

0:EncodedTicket

0:PropertyType

Mandatory

Conformance Units

Onboarding Registrar PullManagement

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

The Certificate Property is the DER encoded form of the DeviceIdentity Certificate that was validated.

The Ticket Property is the signed Ticket (see 8.1) that matches the DeviceIdentity Certificate.

The Composite Property is the signed Ticket (see 8.1) for the Composite that contains the Device.

This abstract Event is raised when the Registrar receives the Device software status has changed.

This Event and it subtypes are security related and Servers shall only report them to Sessions with access to the SecurityAdmin Role.

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

Table 31 – DeviceSoftwareUpdatedAuditEventType Definition

Attribute

Value

BrowseName

2:DeviceSoftwareUpdatedAuditEventType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

Modelling Rule

Subtype of the 2:DeviceRegistrationAuditEventType defined in 9.2.13.

0:HasProperty

Variable

2:Status

0:Boolean

0:PropertyType

Mandatory

0:HasProperty

Variable

2:SoftwareRevision

0:String

0:PropertyType

Mandatory

Conformance Units

Onboarding Registrar PullManagement

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

The Status Property is the TRUE if the Device firmware is up to date.

The SoftwareRevision Property is the version of the firmware that was installed (if Status=TRUE) or needs to be installed (Status=FALSE).