C++ Based OPC UA Client/Server SDK
1.5.5.355
|
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... | |
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.
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.
[in] | pSession | The UaSession object used to communicate with the GDS |
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.
[in,out] | serviceSettings | The general service settings like timeout. See ServiceSettings for more details. |
[in] | applicationUri | The ApplicationUri that identifies the Application of interest |
[out] | applications | A 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.
[in,out] | serviceSettings | The general service settings like timeout. See ServiceSettings for more details. |
[in] | applicationId | The identifier assigned to the ApplicationInstance by the GDS. |
[in] | requestId | The NodeId returned by startNewKeyPairRequest or startSigningRequest. |
[out] | certificate | The DER encoded Certificate. |
[out] | privateKey | The 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] | issuerCertificates | The 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.
[in,out] | serviceSettings | The general service settings like timeout. See ServiceSettings for more details. |
[in] | applicationId | The ApplicationId that identifies the Application of interest |
[out] | application | The 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).
[in,out] | serviceSettings | The general service settings like timeout. See ServiceSettings for more details. |
[in] | applicationId | The identifier assigned to the Application record by the Directory. |
[out] | certificateGroupIds | Identifiers 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).
[in,out] | serviceSettings | The general service settings like timeout. See ServiceSettings for more details. |
[in] | applicationId | The identifier assigned to the ApplicationInstance by the GDS. |
[in] | certificateGroupId | The NodeId of the certificate group that the Application belongs to. If null the GDS will choose the DefaultApplicationGroup. |
[in] | certificateTypeId | The 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] | updateRequired | TRUE 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.
[in,out] | serviceSettings | The general service settings like timeout. See ServiceSettings for more details. |
[in] | certificateGroupId | The NodeId of the certificate group to request the certificate types for. |
[out] | certificateTypes | The 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).
[in,out] | serviceSettings | The general service settings like timeout. See ServiceSettings for more details. |
[in] | applicationId | The identifier assigned to the Application by the Directory. |
[in] | certificateGroupId | The NodeId of the certificate group that the Application belongs to. |
[out] | trustListId | The 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.
[in,out] | serviceSettings | The general service settings like timeout. See ServiceSettings for more details. |
[in] | application | The application information that is to be stored in the GDS database. It contains the following information:
|
[out] | applicationId | A 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.
[in,out] | serviceSettings | The general service settings like timeout. See ServiceSettings for more details. |
[in] | applicationId | The identifier assigned to the Application by the Directory. |
[in] | certificateGroupId | The NodeId of the certificate group which provides the context for the new request. If null the GDS shall choose the DefaultApplicationGroup. |
[in] | certificateTypeId | The 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] | subjectName | The subject name to use for the Certificate. If not specified the ApplicationName and/or domainNames are used to create a suitable default value. |
[in] | domainNames | The domain names to include in the Certificate. |
[in] | privateKeyFormat | The format of the private key. The following values are always supported: PFX - PKCS #12 encoded or PEM - Base64 encoded. |
[in] | privateKeyPassword | The password to use for the private key. |
[out] | requestId | The 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).
[in,out] | serviceSettings | The general service settings like timeout. See ServiceSettings for more details. |
[in] | applicationId | The identifier assigned to the Application record by the Directory. |
[in] | certificateGroupId | The NodeId of the certificate group which provides the context for the new request. If null the GDS shall choose the DefaultApplicationGroup. |
[in] | certificateTypeId | The 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] | certificateRequest | A 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] | requestId | The 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.
[in,out] | serviceSettings | The general service settings like timeout. See ServiceSettings for more details. |
[in] | applicationId | The 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.
[in,out] | serviceSettings | The general service settings like timeout. See ServiceSettings for more details. |
[in] | application | The identifier assigned to the ApplicationInstance by the Directory. |