C++ Based OPC UA Client/Server SDK  1.5.5.355
Public Member Functions | List of all members
UaClientSdk::UaCertificateDirectoryObject Class Reference
UA Client SDK » UA Client Library

The UaCertificateDirectoryObject class manges a UA Client side interaction with a Global Directory Service (GDS) More...

#include <uacertificatedirectoryobject.h>

Public Member Functions

 UaCertificateDirectoryObject (UaSession *pSession)
 Constructs a CertificateDirectory object used to communicate with a Global Directory Service (GDS) More...
 
virtual ~UaCertificateDirectoryObject ()
 Destroys the CertificateDirectory object.
 
UaStatus findApplications (ServiceSettings &serviceSettings, const UaString &applicationUri, OpcUaGds::ApplicationRecordDataTypes &applications)
 FindApplications is used to find the ApplicationId for an OPC UA Application known to the GDS. More...
 
UaStatus getApplication (ServiceSettings &serviceSettings, const UaNodeId &applicationId, OpcUaGds::ApplicationRecordDataType &application)
 GetApplication is used to get the application record for an OPC UA Application known to the GDS. More...
 
UaStatus registerApplication (ServiceSettings &serviceSettings, const OpcUaGds::ApplicationRecordDataType &application, UaNodeId &applicationId)
 RegisterApplication is used to register a new Application with a GDS. More...
 
UaStatus unregisterApplication (ServiceSettings &serviceSettings, const UaNodeId &applicationId)
 This Method is used to remove an Application from a GDS server. More...
 
UaStatus updateApplication (ServiceSettings &serviceSettings, const OpcUaGds::ApplicationRecordDataType &application)
 This Method is used to update an existing Application in a GDS server. More...
 
UaStatus getCertificateGroups (ServiceSettings &serviceSettings, const UaNodeId &applicationId, UaNodeIdArray &certificateGroupIds)
 This method returns the certificate groups assigned to an Application. More...
 
UaStatus getCertificateTypesForGroup (ServiceSettings &serviceSettings, const UaNodeId &certificateGroupId, UaNodeIdArray &certificateTypes)
 This method is used to retrieve CertificateTypes that can be applied for a CertificateGroup. More...
 
UaStatus startSigningRequest (ServiceSettings &serviceSettings, const UaNodeId &applicationId, const UaNodeId &certificateGroupId, const UaNodeId &certificateTypeId, UaByteString &certificateRequest, UaNodeId &requestId)
 This method is used to create a signed certificate with a certificate sign request. More...
 
UaStatus startNewKeyPairRequest (ServiceSettings &serviceSettings, const UaNodeId &applicationId, const UaNodeId &certificateGroupId, const UaNodeId &certificateTypeId, const UaString &subjectName, const UaStringArray &domainNames, const UaString &privateKeyFormat, const UaString &privateKeyPassword, UaNodeId &requestId)
 This Method is used to start a request for a new Certificate and Private Key. More...
 
UaStatus finishRequest (ServiceSettings &serviceSettings, const UaNodeId &applicationId, const UaNodeId &requestId, UaByteString &certificate, UaByteString &privateKey, UaByteStringArray &issuerCertificates)
 FinishRequest is used to finish a certificate request started with a call to StartNewKeyPairRequest or StartSigningRequest. More...
 
UaStatus getTrustList (ServiceSettings &serviceSettings, const UaNodeId &applicationId, const UaNodeId &certificateGroupId, UaNodeId &trustListId)
 This Method is used to retrieve the NodeId of a TrustList assigned to an Application. More...
 
UaStatus getCertificateStatus (ServiceSettings &serviceSettings, const UaNodeId &applicationId, const UaNodeId &certificateGroupId, const UaNodeId &certificateTypeId, OpcUa_Boolean &updateRequired)
 FinishRequest is used to finish a certificate request started with a call to StartNewKeyPairRequest or StartSigningRequest. More...
 

Detailed Description

The UaCertificateDirectoryObject class manges a UA Client side interaction with a Global Directory Service (GDS)

There are two main parts of GDS functionality provided through this class.

The one part is the registration and management of OPC UA applications in the GDS through the methods defined by the DirectoryType. This includes register, update and unregister an application.

The second part is the creation and access to application instance certificates and trust list managed by the GDS through methods defined by the CertificateDirectoryType. This includes to request, sign or renew an application instance certificate and to check the state of these requests. In addition it provides the method to get the trust list for the OPC UA application.

Constructor & Destructor Documentation

UaClientSdk::UaCertificateDirectoryObject::UaCertificateDirectoryObject ( UaSession *  pSession)

Constructs a CertificateDirectory object used to communicate with a Global Directory Service (GDS)

A UaSession connected to the GDS must be passed in. Some of the methods on the GDS may not require a special user, however most of the methods require special Client’s user credentials. Therefore it is required to configure the UaSession object with the right user token.

Parameters
[in]pSessionThe UaSession object used to communicate with the GDS

Member Function Documentation

UaStatus UaClientSdk::UaCertificateDirectoryObject::findApplications ( ServiceSettings &  serviceSettings,
const UaString &  applicationUri,
OpcUaGds::ApplicationRecordDataTypes &  applications 
)

FindApplications is used to find the ApplicationId for an OPC UA Application known to the GDS.

In normal situations the list of records returned will not have more than one entry, however, system configuration errors can create situations where the GDS has multiple entries for a single ApplicationUri. If this happens a human will likely have to look at records to determine which record is the true match for the ApplicationUri.

If the returned array is null or zero length then the GDS does not have an entry for the ApplicationUri.

Used to access the method FindApplications of the Directory object in a GDS server. The method is defined by the DirectoryType.

Parameters
[in,out]serviceSettingsThe general service settings like timeout. See ServiceSettings for more details.
[in]applicationUriThe ApplicationUri that identifies the Application of interest
[out]applicationsA list of application records that match the ApplicationUri
UaStatus UaClientSdk::UaCertificateDirectoryObject::finishRequest ( ServiceSettings &  serviceSettings,
const UaNodeId &  applicationId,
const UaNodeId &  requestId,
UaByteString &  certificate,
UaByteString &  privateKey,
UaByteStringArray &  issuerCertificates 
)

FinishRequest is used to finish a certificate request started with a call to StartNewKeyPairRequest or StartSigningRequest.

Used to access the method FinishRequest of the Directory object in a GDS server. The method is defined by the CertificateDirectoryType in the GDS information model.

This call is passes the requestId returned by a previous call to startNewKeyPairRequest or startSigningRequest.

It is expected that a client will periodically call this method until the GDS has approved the request.

This method can be invoked by a configuration tool which has provided user credentials with necessary access permissions. It can also be invoked by the Application that owns the Certificate (e.g. the private key used to create the channel must be the same as the private key used to sign the request passed to startSigningRequest).

The method shall only be called via a SecureChannel with encryption enabled.

Parameters
[in,out]serviceSettingsThe general service settings like timeout. See ServiceSettings for more details.
[in]applicationIdThe identifier assigned to the ApplicationInstance by the GDS.
[in]requestIdThe NodeId returned by startNewKeyPairRequest or startSigningRequest.
[out]certificateThe DER encoded Certificate.
[out]privateKeyThe private key encoded in the format requested. If a password was supplied the blob is protected with it. This field is null if no private key was requested.
[out]issuerCertificatesThe Certificates required to validate the new Certificate.
UaStatus UaClientSdk::UaCertificateDirectoryObject::getApplication ( ServiceSettings &  serviceSettings,
const UaNodeId &  applicationId,
OpcUaGds::ApplicationRecordDataType &  application 
)

GetApplication is used to get the application record for an OPC UA Application known to the GDS.

Used to access the method GetApplication of the Directory object in a GDS server. The method is defined by the DirectoryType.

Parameters
[in,out]serviceSettingsThe general service settings like timeout. See ServiceSettings for more details.
[in]applicationIdThe ApplicationId that identifies the Application of interest
[out]applicationThe application record that match the ApplicationId
UaStatus UaClientSdk::UaCertificateDirectoryObject::getCertificateGroups ( ServiceSettings &  serviceSettings,
const UaNodeId &  applicationId,
UaNodeIdArray &  certificateGroupIds 
)

This method returns the certificate groups assigned to an Application.

A certificate group provides a trust list and one or more CertificateTypes which may be assigned to an Application. The values returned by this method are passed to the getTrustList, startSigningRequest or startNewKeyPairRequest methods.

This method can be invoked by a configuration tool which has provided user credentials with necessary access permissions. It can also be invoked by the application identified by the applicationId (e.g. the private key used to create the channel must be private key associated with the certificate assigned to the application).

Parameters
[in,out]serviceSettingsThe general service settings like timeout. See ServiceSettings for more details.
[in]applicationIdThe identifier assigned to the Application record by the Directory.
[out]certificateGroupIdsIdentifiers for the certificate groups assigned to the application
UaStatus UaClientSdk::UaCertificateDirectoryObject::getCertificateStatus ( ServiceSettings &  serviceSettings,
const UaNodeId &  applicationId,
const UaNodeId &  certificateGroupId,
const UaNodeId &  certificateTypeId,
OpcUa_Boolean &  updateRequired 
)

FinishRequest is used to finish a certificate request started with a call to StartNewKeyPairRequest or StartSigningRequest.

Used to access the method FinishRequest of the Directory object in a GDS server. The method is defined by the CertificateDirectoryType in the GDS information model.

This method can be invoked by a configuration tool which has provided user credentials with necessary access permissions. It can also be invoked by the Application identified by the applicationId (e.g. the private key used to create the channel must be private key associated with the Certificate assigned to the Application).

Parameters
[in,out]serviceSettingsThe general service settings like timeout. See ServiceSettings for more details.
[in]applicationIdThe identifier assigned to the ApplicationInstance by the GDS.
[in]certificateGroupIdThe NodeId of the certificate group that the Application belongs to. If null the GDS will choose the DefaultApplicationGroup.
[in]certificateTypeIdThe NodeId of the CertificateType for the Certificate to check. If null the GDS will select a Certificate based on the value of the certificateGroupId argument.
[out]updateRequiredTRUE if the Application needs to request a new Certificate from the GDS. FALSE if the Application can keep using the existing Certificate.
UaStatus UaClientSdk::UaCertificateDirectoryObject::getCertificateTypesForGroup ( ServiceSettings &  serviceSettings,
const UaNodeId &  certificateGroupId,
UaNodeIdArray &  certificateTypes 
)

This method is used to retrieve CertificateTypes that can be applied for a CertificateGroup.

The method returns the value of the CertificateTypes property of the CertificateGroup object identified by certificateGroupId. The certificateGroupId is returned from getCertificateGroups.

Parameters
[in,out]serviceSettingsThe general service settings like timeout. See ServiceSettings for more details.
[in]certificateGroupIdThe NodeId of the certificate group to request the certificate types for.
[out]certificateTypesThe certificate types that can be applied for the certificate group.
UaStatus UaClientSdk::UaCertificateDirectoryObject::getTrustList ( ServiceSettings &  serviceSettings,
const UaNodeId &  applicationId,
const UaNodeId &  certificateGroupId,
UaNodeId &  trustListId 
)

This Method is used to retrieve the NodeId of a TrustList assigned to an Application.

Used to access the method GetTrustList of the Directory object in a GDS server. The method is defined by the CertificateDirectoryType in the GDS information model.

Access permissions also apply to the Trust List Objects which are returned by this Method. This Trust List includes any Certificate Revocation Lists (CRLs) associated with issuer Certificates in the Trust List.

This method can be invoked by a configuration tool which has provided user credentials with necessary access permissions. It can also be invoked by the Application identified by the applicationId (e.g. the private key used to create the channel must be private key associated with the Certificate assigned to the Application).

Parameters
[in,out]serviceSettingsThe general service settings like timeout. See ServiceSettings for more details.
[in]applicationIdThe identifier assigned to the Application by the Directory.
[in]certificateGroupIdThe NodeId of the certificate group that the Application belongs to.
[out]trustListIdThe NodeId for a TrustList Object that can be used to download the TrustList assigned to the Application.
UaStatus UaClientSdk::UaCertificateDirectoryObject::registerApplication ( ServiceSettings &  serviceSettings,
const OpcUaGds::ApplicationRecordDataType &  application,
UaNodeId &  applicationId 
)

RegisterApplication is used to register a new Application with a GDS.

This Method can only be invoked by authorized users defined through the UaSession passed during the creation of this ApplicationManager object.

Used to access the method RegisterApplication of the Directory object in a GDS server. The method is defined by the DirectoryType in the GDS information model.

Parameters
[in,out]serviceSettingsThe general service settings like timeout. See ServiceSettings for more details.
[in]applicationThe application information that is to be stored in the GDS database. It contains the following information:
  • ApplicationUri: The globally unique identifier for the application instance
  • ApplicationType: The type of application with the possible values SERVER, CLIENT, CLIENTANDSERVER and DISCOVERYSERVER
  • ApplicationNames: An array of localized descriptive name for the application
  • ProductUri: The globally unique identifier for the product
  • DiscoveryUrls: A list of URLs for the discovery Endpoints provided by the application. Empty for type CLIENT
  • ServerCapabilities: The list of server capabilities supported by the Server
[out]applicationIdA unique identifier for the registered Application. This identifier is persistent and is used in other Methods used to administer the application.
UaStatus UaClientSdk::UaCertificateDirectoryObject::startNewKeyPairRequest ( ServiceSettings &  serviceSettings,
const UaNodeId &  applicationId,
const UaNodeId &  certificateGroupId,
const UaNodeId &  certificateTypeId,
const UaString &  subjectName,
const UaStringArray &  domainNames,
const UaString &  privateKeyFormat,
const UaString &  privateKeyPassword,
UaNodeId &  requestId 
)

This Method is used to start a request for a new Certificate and Private Key.

The new Certificate is returned in the finishRequest response. The call to this method returns the NodeId that is passed to the finishRequest method.

Used to access the method StartNewKeyPairRequest of the Directory object in a GDS server. The method is defined by the CertificateDirectoryType in the GDS information model.

The certificateGroupId parameter allows the caller to specify a certificate group that provides context for the request. If null the GDS shall choose the DefaultApplicationGroup. The set of available certificate groups are found in the CertificateGroups folder. The Certificate Groups allowed for an Application are returned by the getCertificateGroups method.

The certificateTypeId parameter specifies the type of Certificate to return. The permitted values are specified by the CertificateTypes Property of the Object specified by the certificateGroupId parameter.

The subjectName parameter is a sequence of X500 name value pairs separated by a '/'. For example: CN=ApplicationName/OU=Group/O=Company.

If the certificateType is a subtype of ApplicationCertificateType the Certificate subject name shall have an organization (O=) or domain name (DC=) field. The public key length shall meet the length restrictions for the CertificateType.

If the certificateType is a subtype of HttpsCertificateType the Certificate common name (CN=) shall be the same as a domain from a DiscoveryUrl which uses HTTPS and the subject name shall have an organization (O=) field. The public key length shall be greater than or equal to 1024 bits.

If the subjectName is blank or null the CertificateManager generates a suitable default.

The domainNames parameter is list of domains to be includes in the Certificate. If it is null or empty the GDS uses the DiscoveryUrls of the Server to create a list. For Clients the domainNames are omitted from the Certificate if they are not explicitly provided.

The privateKeyFormat specifies the format of the private key returned. All CertificateManager implementations shall support "PEM" and "PFX".

The privateKeyPassword specifies the password on the private key. The CertificateManager shall not persist this information and shall discard it once the new private key is generated.

This Method can be invoked by a configuration tool which has provided user credentials with necessary access permissions.

Parameters
[in,out]serviceSettingsThe general service settings like timeout. See ServiceSettings for more details.
[in]applicationIdThe identifier assigned to the Application by the Directory.
[in]certificateGroupIdThe NodeId of the certificate group which provides the context for the new request. If null the GDS shall choose the DefaultApplicationGroup.
[in]certificateTypeIdThe NodeId of the CertificateType for the Certificate to generate. If null the GDS shall generate a Certificate based on the value of the certificateGroupId argument.
[in]subjectNameThe subject name to use for the Certificate. If not specified the ApplicationName and/or domainNames are used to create a suitable default value.
[in]domainNamesThe domain names to include in the Certificate.
[in]privateKeyFormatThe format of the private key. The following values are always supported: PFX - PKCS #12 encoded or PEM - Base64 encoded.
[in]privateKeyPasswordThe password to use for the private key.
[out]requestIdThe NodeId that represents the request. This value is passed to FinishRequest.
UaStatus UaClientSdk::UaCertificateDirectoryObject::startSigningRequest ( ServiceSettings &  serviceSettings,
const UaNodeId &  applicationId,
const UaNodeId &  certificateGroupId,
const UaNodeId &  certificateTypeId,
UaByteString &  certificateRequest,
UaNodeId &  requestId 
)

This method is used to create a signed certificate with a certificate sign request.

The new Certificate is returned in the finishRequest response. The call to this method returns the NodeId that is passed to the finishRequest method.

Used to access the method StartSigningRequest of the Directory object in a GDS server. The method is defined by the CertificateDirectoryType in the GDS information model.

The certificateGroupId parameter allows the caller to specify a certificate group that provides context for the request. If null the GDS shall choose the DefaultApplicationGroup. The set of available certificate groups are found in the CertificateGroups folder. The Certificate Groups allowed for an Application are returned by the getCertificateGroups method.

The certificateTypeId parameter specifies the type of Certificate to return. The permitted values are specified by the CertificateTypes Property of the Object specified by the certificateGroupId parameter.

The certificateRequest parameter is a DER encoded Certificate Signing Request (CSR). The subject name, subject alternative name and public key are copied into the new Certificate. If the certificateTypeId is a subtype of ApplicationCertificateType the subject name shall have an organization (O=) or domain name (DC=) field. The public key length shall meet the length restrictions for the CertificateType. If the certificateType is a subtype of HttpsCertificateType the Certificate common name (CN=) shall be the same as a domain from a DiscoveryUrl which uses HTTPS and the subject name shall have an organization (O=) field. The public key length shall be greater than or equal to 1024 bits.

The ApplicationUri shall be specified in the CSR. The GDS shall return BadCertificateUriInvalid if the stored ApplicationUri for the application is different from what is in the CSR.

For Servers, the list of domain names shall be specified in the CSR. The domains shall include the domain(s) in the DiscoveryUrls known to the CertificateManager.

This Method can be invoked by a configuration tool which has provided user credentials with necessary access permissions. It can also be invoked by the application that owns the private key used to sign the CertificateRequest (e.g. the private key must be the private key used to create the SecureChannel).

Parameters
[in,out]serviceSettingsThe general service settings like timeout. See ServiceSettings for more details.
[in]applicationIdThe identifier assigned to the Application record by the Directory.
[in]certificateGroupIdThe NodeId of the certificate group which provides the context for the new request. If null the GDS shall choose the DefaultApplicationGroup.
[in]certificateTypeIdThe NodeId of the CertificateType for the Certificate to generate. If null the GDS shall generate a Certificate based on the value of the certificateGroupId argument.
[in]certificateRequestA certificate signing request containing the certificate data and used to prove possession of the Private Key. It is a PKCS #10 encoded blob in DER format. This blob shall include the subjectAltName extension that is in the Certificate.
[out]requestIdThe NodeId that represents the request. This value is passed to finishRequest.
UaStatus UaClientSdk::UaCertificateDirectoryObject::unregisterApplication ( ServiceSettings &  serviceSettings,
const UaNodeId &  applicationId 
)

This Method is used to remove an Application from a GDS server.

This Method can only be invoked by authorized users.

Used to access the method UnregisterApplication of the Directory object in a GDS server. The method is defined by the DirectoryType in the GDS information model.

Parameters
[in,out]serviceSettingsThe general service settings like timeout. See ServiceSettings for more details.
[in]applicationIdThe identifier assigned to the ApplicationInstance by the Directory.
UaStatus UaClientSdk::UaCertificateDirectoryObject::updateApplication ( ServiceSettings &  serviceSettings,
const OpcUaGds::ApplicationRecordDataType &  application 
)

This Method is used to update an existing Application in a GDS server.

This Method can only be invoked by authorized users.

Used to access the method UpdateApplication of the Directory object in a GDS server. The method is defined by the DirectoryType in the GDS information model.

Parameters
[in,out]serviceSettingsThe general service settings like timeout. See ServiceSettings for more details.
[in]applicationThe identifier assigned to the ApplicationInstance by the Directory.
The documentation for this class was generated from the following files: