ANSI C Based OPC UA Client/Server SDK  1.9.0.430
Object Types

TrustListType

Reference NodeClass BrowseName DataType ValueRank TypeDefinition ModellingRule
HasSupertype ObjectType FileType  
HasComponent Method AddCertificate Optional
HasComponent Method CloseAndUpdate Optional
HasProperty Variable LastUpdateTime UtcTime Scalar PropertyType Mandatory
HasComponent Method OpenWithMasks Mandatory
HasComponent Method RemoveCertificate Optional

Defines a FileType that can be used to access a trust list.

The CertificateManager uses this type to implement the Pull Model.

Servers use this type when implementing the Push Model.

An instance of a TrustListType must restrict access to appropriate users or applications. This may be a CertificateManager administrative user that can change the contents of a trust list, it may be an administrative user that is reading a trust list to deploy to an application host or it may be an application that can only access the trust list assigned to it.

The trust list file is a UA Binary encoded stream containing an instance of TrustListDataType.

The Open method shall not support modes other than Read (0x01) and the Write + EraseExisting (0x06).

When a Client opens the file for writing, the Server will not actually update the trust list until the CloseAndUpdate method is called. Simply calling Close will discard the updates. The bit masks in the TrustListDataType structure allow the Client to only update part of the trust list.

When the CloseAndUpdate method is called, the Server will validate all new Certificates and CRLs. If this validation fails, the trust list is not updated and the Server returns the appropriate certificate error code.

If auditing is supported, the CertificateManager shall generate the TrustListUpdatedAuditEventType when the CloseAndUpdate, AddCertificate or RemoveCertificate methods are called.

Variable LastUpdateTime

Indicates when the trust list was last updated via trust list object methods.

This can be used to determine whether a device has an up to date trust list or to detect unexpected modifications. Out of band changes are not necessarily reported by this value.

Method OpenWithMasks

Allows a Client to read only the portion of the trust list.

This method can only be used to read the trust list.

Method Result Codes

Result Code Description
Bad_UserAccessDenied The current user does not have the rights required.

Input Arguments

Argument DataType ValueRank Description
Masks UInt32 Scalar The parts of the trust list that are to be included in the file to read.

Output Arguments

Argument DataType ValueRank Description
FileHandle UInt32 Scalar The handle of the newly opened file.

Method CloseAndUpdate

Closes the file and applies the changes to the trust list.

This method can only be called if the file was opened for writing. If the Close method is called, any cached data is discarded and the trust list is not changed.

The Server shall verify that every certificate in the new trust list is valid according to the mandatory rules defined in Part 4 of the OPC UA Specification. If an invalid certificate is found, the Server shall return an error and shall not update the trust list. If only part of the trust list is being updated, the Server creates a temporary trust list that includes the existing trust list plus any updates and validates the temporary trust list.

If the file cannot be processed, this method still closes the file and discards the data before returning an error. This method is required if the Server supports updates to the trust list.

The structure uploaded includes a mask that specifies which fields are updated. If a bit is not set, the associated field is not changed.

Method Result Codes

Result Code Description
Bad_UserAccessDenied The current user does not have the rights required.
Bad_CertificateInvalid The Server could not validate all certificate s in the trust list. The DiagnosticInfo shall specify which certificate (s) are invalid and the specific error.

Input Arguments

Argument DataType ValueRank Description
FileHandle UInt32 Scalar The handle of the previously opened file.

Output Arguments

Argument DataType ValueRank Description
ApplyChangesRequired Boolean Scalar A flag indicating whether the ApplyChanges method must be called before the new trust list will be used by the Server.

Method AddCertificate

Allows a Client to add a single certificate to the trust list.

The Server shall verify that the certificate is valid according to the mandatory rules defined in Part 4 of the OPC UA Specification. If an invalid certificate is found, the Server shall return an error and shall not update the trust list.

This method cannot be called if the file object is open.

Method Result Codes

Result Code Description
Bad_UserAccessDenied The current user does not have the rights required.
Bad_CertificateInvalid The certificate to add is invalid.
Bad_InvalidState The object is opened.

Input Arguments

Argument DataType ValueRank Description
Certificate ByteString Scalar The DER encoded certificate to add.
IsTrustedCertificate Boolean Scalar If TRUE, the certificate is added to the trusted certificate s list.
If FALSE, the certificate is added to the Issuer certificate s list.

Method RemoveCertificate

Allows a Client to remove a single certificate from the trust list.

This method returns Bad_InvalidArgument if the thumbprint does not match a certificate in the trust list.

This method cannot be called if the file object is open.

Method Result Codes

Result Code Description
Bad_UserAccessDenied The current user does not have the rights required.
Bad_InvalidArgument The certificate to remove was not found.
Bad_InvalidState The object is opened.

Input Arguments

Argument DataType ValueRank Description
Thumbprint String Scalar The SHA1 hash of the certificate to remove.
IsTrustedCertificate Boolean Scalar If TRUE, the certificate is removed from the trusted certificate s list.
If FALSE, the certificate is removed from the Issuer certificate s list.

CertificateGroupType

Reference NodeClass BrowseName DataType ValueRank TypeDefinition ModellingRule
HasSupertype ObjectType BaseObjectType  
HasProperty Variable CertificateTypes NodeId OneDimension PropertyType Mandatory
HasComponent Object TrustList TrustListType Mandatory

A type used for objects which represent certificate groups in the address space.

A certificate group is a context that contains a trust list and one or more certificate s that can be assigned to an application. This type exists to allow an application which has multiple trust lists and/or application certificate s to express them in its AddressSpace.

The TrustList object is the trust list associated with the certificate group.

Object TrustList

The trust list associated with the certificate group.

Variable CertificateTypes

Specifies the NodeIds of the CertificateTypes which may be assigned to applications which belong to the certificate group.

For example, a certificate group with the NodeId of RsaMinApplicationCertificateType and the NodeId RsaSha256ApplicationCertificate specified allows an application to have one ApplicationInstance certificate for each type. Abstract base types may be used in this value and indicate that any subtype is allowed. If this list is empty, the certificate group does not allow certificate s to be assigned to applications (i.e. the Certificate Group exists to allow the associated trust list to be read or updated). All CertificateTypes for a given certificate group shall be subtypes of a single common type which shall be either ApplicationCertificateType or HttpsCertificateType.

CertificateType

Reference NodeClass BrowseName DataType ValueRank TypeDefinition ModellingRule
HasSupertype ObjectType BaseObjectType  

An abstract base type for types that describe the purpose of a certificate.

ApplicationCertificateType

Reference NodeClass BrowseName DataType ValueRank TypeDefinition ModellingRule
HasSupertype ObjectType CertificateType  

An abstract base type for types that describe the purpose of an ApplicationInstance certificate.

HttpsCertificateType

Reference NodeClass BrowseName DataType ValueRank TypeDefinition ModellingRule
HasSupertype ObjectType CertificateType  

This type is used to describe Certificates that are intended for use as HTTPS certificates.

RsaMinApplicationCertificateType

Reference NodeClass BrowseName DataType ValueRank TypeDefinition ModellingRule
HasSupertype ObjectType ApplicationCertificateType  

This type is used to describe Certificates intended for use as an ApplicationInstance certificate.

They shall have an RSA key size of 1024 or 2048 bits and are signed with a SHA1 hash. All applications which support the Basic128Rsa15 and Basic256 profiles (see Part 7 of the OPC UA Specification) need a certificate of this type.

RsaSha256ApplicationCertificateType

Reference NodeClass BrowseName DataType ValueRank TypeDefinition ModellingRule
HasSupertype ObjectType ApplicationCertificateType  

This type is used to describe certificate s intended for use as an ApplicationInstance certificate.

They shall have an RSA key size of 2048, 3072 or 4096 bits and are signed with a SHA256 hash. All applications which support the Basic256Sha256 profile (see Part 7 of the OPC UA Specification) need a certificate of this type.

ServerConfigurationType

Reference NodeClass BrowseName DataType ValueRank TypeDefinition ModellingRule
HasSupertype ObjectType BaseObjectType  
HasComponent Method ApplyChanges Mandatory
Organizes Object CertificateGroups CertificateGroupFolderType Mandatory
HasComponent Method CreateSigningRequest Mandatory
HasComponent Method GetRejectedList Mandatory
HasProperty Variable MaxTrustListSize UInt32 Scalar PropertyType Mandatory
HasProperty Variable MulticastDnsEnabled Boolean Scalar PropertyType Mandatory
HasProperty Variable ServerCapabilities String OneDimension PropertyType Mandatory
HasProperty Variable SupportedPrivateKeyFormats String OneDimension PropertyType Mandatory
HasComponent Method UpdateCertificate Mandatory

This type defines an ObjectType which represents the configuration of a Server which supports Push Management.

There is always exactly one instance in the Server address space.

Variable SupportedPrivateKeyFormats

Specifies the PrivateKey formats supported by the Server.

Possible values include “PEM” (see RFC 5958, txt file) or “PFX” (see PKCS #12, pdf file). The array is empty if the Server does not allow external Clients to update the PrivateKey.

Variable MaxTrustListSize

The maximum size of the trust list in bytes.

0 means no limit.

Variable MulticastDnsEnabled

If TRUE, the Server announces itself using multicast DNS.

It can be changed by writing to the variable.

Method UpdateCertificate

Used to update a certificate for a Server.

There are the following three use cases for this method.

  • The new certificate was created based on a signing request created with the method CreateSigningRequest. In this case, there is no PrivateKey provided.
  • A new PrivateKey and certificate were created outside the Server and both are updated with this method.
  • A new certificate was created and signed with the information from the old Certificate. In this case, there is no PrivateKey provided.

The Server shall do all normal integrity checks on the certificate and all of the issuer certificates. If errors occur, the Bad_SecurityChecksFailed error is returned.

The Server shall report an error if the public key does not match the existing certificate and PrivateKey was not provided.

This method requires an encrypted channel and that the Client provides credentials with administrative rights on the Server.

This method may require the ApplyChanges method to be called.

Method Result Codes

Result Code Description
Bad_InvalidArgument The CertificateTypeId or certificateGroupId is not valid.
Bad_CertificateInvalid The certificate is invalid or the format is not supported.
Bad_NotSupported The PrivateKey is invalid or the format is not supported.
Bad_UserAccessDenied The current user does not have the rights required.
Bad_SecurityChecksFailed Some failure occurred verifying the integrity of the certificate.

Input Arguments

Argument DataType ValueRank Description
CertificateGroupId NodeId Scalar The NodeId of the certificate group object which is affected by the update.
If null the DefaultApplicationGroup is used.
CertificateTypeId NodeId Scalar The type of certificate being updated.
The set of permitted types is specified by the CertificateTypes property belonging to the certificate group.
Certificate ByteString Scalar The DER encoded certificate which replaces the existing certificate.
IssuerCertificates ByteString OneDimension The issuer certificates needed to verify the signature on the new certificate.
PrivateKeyFormat String Scalar The format of the private key (PEM or PFX).
If the privateKey is not specified the privateKeyFormat is null or empty.
PrivateKey ByteString Scalar The private key encoded in the PrivateKeyFormat.

Output Arguments

Argument DataType ValueRank Description
ApplyChangesRequired Boolean Scalar Indicates that the ApplyChanges method must be called before the new certificate will be used.

Variable ServerCapabilities

Specifies the capabilities which the Server supports.

The value is the same as the value reported to the LocalDiscoveryServer when the Server calls the RegisterServer2 Service.

Method CreateSigningRequest

Asks the Server to create a PKCS #10 DER encoded certificate request that is signed with the Server’s private key.

This request can be then used to request a certificate from a CA that expects requests in this format. See RFC 2986 (txt file) for a description of PKCS #10.

This method requires an encrypted channel and that the Client provides credentials with administrative rights on the Server.

Method Result Codes

Result Code Description
Bad_InvalidArgument The CertificateTypeId, certificateGroupId or SubjectName is not valid.
Bad_UserAccessDenied The current user does not have the rights required.

Input Arguments

Argument DataType ValueRank Description
CertificateGroupId NodeId Scalar The NodeId of the certificate group object which is affected by the request.
If null, the DefaultApplicationGroup is used.
CertificateTypeId NodeId Scalar The type of certificate being requested.
The set of permitted types is specified by the CertificateTypes property belonging to the certificate group.
SubjectName String Scalar The subject name to use in the certificate request.
If not specified, the SubjectName from the current certificate is used.
RegeneratePrivateKey Boolean Scalar Flag indicating whether to create a new private key.
If TRUE, the Server shall create a new private key which it stores until the matching signed certificate is uploaded with the UpdateCertificate method. Previously created private keys may be discarded if UpdateCertificate was not called before calling this method again. If FALSE, the Server uses its existing private key.
Nonce ByteString Scalar Additional entropy which the caller shall provide if RegeneratePrivateKey is TRUE.
It shall be at least 32 bytes long.

Output Arguments

Argument DataType ValueRank Description
CertificateRequest ByteString Scalar The PKCS #10 DER encoded certificate request.

Method ApplyChanges

Used to tell the Server to apply any security changes.

This method should only be called if a previous call to a method that changed the configuration returns ApplyChangesRequired=true (see UpdateCertificate).

ApplyChanges can have different meanings depending on the Server architecture. In the ideal case it would only require the endpoints to be closed and reopened. However, it could require a complete Server shutdown and restart.

This method requires an encrypted channel and that the Client provides credentials with administrative rights on the Server.

Method Result Codes

Result Code Description
Bad_UserAccessDenied The current user does not have the rights required.

Method GetRejectedList

Returns the list of Certificates that have been rejected by the Server.

No rules are defined for how the Server updates this list or how long a certificate is kept in the list. It is recommended that every valid but untrusted certificate be added to the rejected list as long as storage is available. Servers should omit older entries from the list returned if the maximum message size is not large enough to allow the entire list to be returned.

This method requires an encrypted channel and that the Client provides credentials with administrative rights on the Server.

Method Result Codes

Result Code Description
Bad_UserAccessDenied The current user does not have the rights required.

Output Arguments

Argument DataType ValueRank Description
Certificates ByteString OneDimension The DER encoded form of the Certificates rejected by the Server.

Object CertificateGroups

The CertificateGroups object organizes the certificate groups supported by the Server.

It is described in CertificateGroupFolderType.

Servers shall support the DefaultApplicationGroup and may support the DefaultHttpsGroup or the DefaultUserTokenGroup. Servers may support additional certificate groups depending on their requirements. For example, a Server with two network interfaces may need a different trust list for each interface. The second trust list would be represented as a new CertificateGroupType object organized by CertificateGroups Folder.

CertificateGroupFolderType

Reference NodeClass BrowseName DataType ValueRank TypeDefinition ModellingRule
HasSupertype ObjectType FolderType  
Organizes Object <CertificateGroup> CertificateGroupType MandatoryPlaceholder
HasComponent Object DefaultApplicationGroup CertificateGroupType Mandatory
HasComponent Object DefaultHttpsGroup CertificateGroupType Optional
HasComponent Object DefaultUserTokenGroup CertificateGroupType Optional

This type is used for Folders which organize certificate groups in the address space.

Object DefaultApplicationGroup

Represents the default certificate group for applications.

This object is used to access the default application trust list and to define the CertificateTypes allowed for the ApplicationInstance certificate. It shall specify the ApplicationCertificateType NodeId as a single entry in the CertificateTypes list, or it shall specify one or more subtypes of ApplicationCertificateType.

Object DefaultHttpsGroup

Represents the default certificate group for HTTPS communication.

This object is used to access the default HTTPS trust list and to define the CertificateTypes allowed for the HTTPS certificate. It shall specify the HttpsCertificateType NodeId as a single entry in the CertificateTypes list or it shall specify one or more subtypes of HttpsCertificateType.

Object DefaultUserTokenGroup

Represents the default certificate group for validating user credentials.

This object is used to access the default user credential trust list and to define the CertificateTypes allowed for user credentials certificate. trust list and to define the CertificateTypes allowed for user credentials certificate. This object shall leave CertificateTypes list empty.