The GlobalDiscoveryServer AddressSpace used for Certificate management is shown in Figure 14. Most of the interactions between the GlobalDiscoveryServer and Application administrator or the Client will be via Methods defined on the Directory folder.
Figure 14 – The Certificate Management AddressSpace for the GlobalDiscoveryServer
This ObjectType is the TypeDefinition for the root of the CertificateManager AddressSpace. It provides additional Methods for Certificate management which are shown in Table 30.
Table 30 – CertificateDirectoryType ObjectType Definition
|
Attribute |
Value |
|||||
|
BrowseName |
CertificateDirectoryType |
|||||
|
Namespace |
GDS (see 3.3) |
|||||
|
IsAbstract |
False |
|||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Modelling Rule |
|
|
Subtype of the DirectoryType defined in 6.3.3. |
||||||
|
|
|
|
|
|
|
|
|
Organizes |
Object |
CertificateGroups |
|
CertificateGroup FolderType |
Mandatory |
|
|
HasComponent |
Method |
StartSigningRequest |
Defined in 7.6.3. |
Mandatory |
||
|
HasComponent |
Method |
StartNewKeyPairRequest |
Defined in 7.6.4. |
Mandatory |
||
|
HasComponent |
Method |
FinishRequest |
Defined in 7.6.5. |
Mandatory |
||
|
HasComponent |
Method |
GetCertificateGroups |
Defined in 7.6.6. |
Mandatory |
||
|
HasComponent |
Method |
GetTrustList |
Defined in 7.6.6. |
Mandatory |
||
|
HasComponent |
Method |
GetCertificateStatus |
Defined in 7.6.8. |
Mandatory |
||
|
HasComponent |
Method |
RevokeCertificate |
Defined in 7.6.8.1 |
Optional |
||
The CertificateGroups Object organizes the Certificate Groups supported by the CertificateManager. It is described in 7.5.17. CertificateManagers shall support the DefaultApplicationGroup and may support the DefaultHttpsGroup or the DefaultUserTokenGroup. CertificateManagers may support additional Certificate Groups depending on their requirements. For example, a CertificateManager with multiple Certificate Authorities would represent each as a CertificateGroupType Object organized by CertificateGroups Folder. Clients could then request Certificates issued by a specific CA by passing the appropriate NodeId to the StartSigningRequest or StartNewKeyPairRequest Methods.
The StartSigningRequest Method is used to request a new a Certificate that is signed by a CA managed by the CertificateManager. This Method is recommended when the caller already has a private key.
The StartNewKeyPairRequest Method is used to request a new Certificate that is signed by a CA managed by the CertificateManager along with a new private key. This Method is used only when the caller does not have a private key and cannot generate one.
The FinishRequest Method is used to check that a Certificate request has been approved by the CertificateManager Administrator. If successful the Certificate and Private Key (if requested) are returned.
The GetCertificateGroups Method returns a list of NodeIds for CertificateGroupType Objects that can be used to request Certificates or Trust Lists for an Application.
The GetTrustList Method returns a NodeId of a TrustListType Object that can be used to read a Trust List for an Application.
The GetCertificateStatus Method checks whether the Application needs to update its Certificate.
StartSigningRequest is used to initiate a request to create a Certificate which uses the private key which the caller currently has. The new Certificate is returned in the FinishRequest response.
Signature
StartSigningRequest(
[in] NodeId applicationId
[in] NodeId certificateGroupId
[in] NodeId certificateTypeId
[in] ByteString certificateRequest
[out] NodeId requestId
);
|
Argument |
Description |
|
applicationId |
The identifier assigned to the Application record by the CertificateManager. |
|
certificateGroupId |
The NodeId of the Certificate Group which provides the context for the new request. If null the CertificateManager shall choose the DefaultApplicationGroup. |
|
certificateTypeId |
The NodeId of the CertificateType for the new Certificate. If null the CertificateManager shall generate a Certificate based on the value of the certificateGroupId argument. |
|
certificateRequest |
A CertificateRequest 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. |
|
requestId |
The NodeId that represents the request. This value is passed to FinishRequest . |
The call returns the NodeId that is passed to the FinishRequest Method.
The certificateGroupId parameter allows the caller to specify a Certificate Group that provides context for the request. If null the CertificateManager shall choose the DefaultApplicationGroup. The set of available Certificate Groups are found in the CertificateGroups folder described in 7.6.2. The Certificate Groups allowed for an Application are returned by the GetCertificateGroups Method (see 7.6.6).
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 Request. 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 CertificateManager shall return Bad_CertificateUriInvalid 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 shall be the private key used to create the SecureChannel).
If auditing is supported, the CertificateManager shall generate the CertificateRequestedAuditEventType (see 7.6.8.1) if this Method succeeds or fails.
Method Result Codes (defined in Call Service)
|
Result Code |
Description |
|
Bad_NotFound |
The applicationId does not refer to a registered Application. |
|
Bad_InvalidArgument |
The certificateGroupId, certificateTypeId or certificateRequest is not valid. The text associated with the error shall indicate the exact problem. |
|
Bad_UserAccessDenied |
The current user does not have the rights required. |
|
Bad_RequestNotAllowed |
The current configuration of the CertificateManager does not allow the request. The text associated with the error should indicate the exact reason. |
|
Bad_CertificateUriInvalid |
The ApplicationUri was not specified in the CSR or does not match the Application record. |
|
Bad_NotSupported |
The signing algorithm, public algorithm or public key size are not supported by the CertificateManager. The text associated with the error shall indicate the exact problem. |
Table 31 specifies the AddressSpace representation for the StartSigningRequest Method.
Table 31 – StartSigningRequest Method AddressSpace Definition
|
Attribute |
Value |
||||
|
BrowseName |
StartSigningRequest |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
HasProperty |
Variable |
InputArguments |
Argument[] |
PropertyType |
Mandatory |
|
HasProperty |
Variable |
OutputArguments |
Argument[] |
PropertyType |
Mandatory |
This Method is used to start a request for a new Certificate and Private Key. The Certificate and private key are returned in the FinishRequest response.
Signature
StartNewKeyPairRequest(
[in] NodeId applicationId
[in] NodeId certificateGroupId
[in] NodeId certificateTypeId
[in] String subjectName
[in] String[] domainNames
[in] String privateKeyFormat
[in] String privateKeyPassword
[out] NodeId requestId
);
|
Argument |
Description |
|
applicationId |
The identifier assigned to the Application Instance by the CertificateManager. |
|
certificateGroupId |
The NodeId of the Certificate Group which provides the context for the new request. If null the CertificateManager shall choose the DefaultApplicationGroup. |
|
certificateTypeId |
The NodeId of the CertificateType for the new Certificate. If null the CertificateManager shall generate a Certificate based on the value of the certificateGroupId argument. |
|
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. The format of the subject name is a sequence of name value pairs separated by a ‘/’. The name shall be one of ‘CN’, ‘O’, ‘OU’, ‘DC’, ‘L’, ‘S’ or ‘C’ and shall be followed by a ‘=’ and then followed by the value. The value may be any printable character except for ‘”’. If the value contains a ‘/’ or a ‘=’ then it shall be enclosed in double quotes (‘”’). |
|
domainNames |
The domain names to include in the Certificate. If not specified the DiscoveryUrls are used to create suitable defaults. |
|
privateKeyFormat |
The format of the private key. The following values are always supported: PFX- PKCS #12 encoded PEM- Base64 encoded DER (see RFC 5958). |
|
privateKeyPassword |
The password to use for the private key. |
|
requestId |
The NodeId that represents the request. This value is passed to FinishRequest. |
The call returns the NodeId that is passed to the FinishRequest Method.
The certificateGroupId parameter allows the caller to specify a Certificate Group that provides context for the request. If null the CertificateManager shall choose the DefaultApplicationGroup. The set of available Certificate Groups are found in the CertificateGroups folder described in 7.6.2. The Certificate Groups allowed for an Application are returned by the GetCertificateGroups Method (see 7.6.6).
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 X.500 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. The domain name field specified in the subject name is a logical domain used to qualify the subject name that may or may not be the same as a domain or IP address in the subjectAltName field of the Certificate.
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.
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.
If auditing is supported, the CertificateManager shall generate the CertificateRequested AuditEventType (see 7.6.8.1) if this Method succeeds or fails.
Method Result Codes (defined in Call Service)
|
Result Code |
Description |
|
Bad_NodeIdUnknown |
The applicationId does not refer to a registered Application. |
|
Bad_InvalidArgument |
The certificateGroupId, certificateTypeId, subjectName, domainNames or privateKeyFormat parameter is not valid. The text associated with the error shall indicate the exact problem. |
|
Bad_UserAccessDenied |
The current user does not have the rights required. |
|
Bad_RequestNotAllowed |
The current configuration of the CertificateManager does not allow the request. The text associated with the error should indicate the exact reason. |
Table 32 specifies the AddressSpace representation for the StartNewKeyPairRequest Method.
Table 32 – StartNewKeyPairRequest Method AddressSpace Definition
|
Attribute |
Value |
||||
|
BrowseName |
StartNewKeyPairRequest |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
HasProperty |
Variable |
InputArguments |
Argument[] |
PropertyType |
Mandatory |
|
HasProperty |
Variable |
OutputArguments |
Argument[] |
PropertyType |
Mandatory |
FinishRequest is used to finish a certificate request started with a call to StartNewKeyPairRequest or StartSigningRequest.
Signature
FinishRequest (
[in] NodeId applicationId
[in] NodeId requestId
[out] ByteString certificate
[out] ByteString privateKey
[out] ByteString[] issuerCertificates
);
|
Argument |
Description |
|
applicationId |
The identifier assigned to the Application Instance by the GDS. |
|
requestId |
The NodeId returned by StartNewKeyPairRequest or StartSigningRequest. |
|
certificate |
The DER encoded Certificate. |
|
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. |
|
issuerCertificates |
The Certificates required to validate the new Certificate. |
This call is passes the NodeId 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 shall 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.
If auditing is supported, the GDS shall generate the CertificateDeliveredAuditEventType (see 7.6.10) if this Method succeeds or if it fails with anything but Bad_NothingToDo.
Method Result Codes (defined in Call Service)
|
Result Code |
Description |
|
Bad_NotFound |
The applicationId does not refer to a registered Application. |
|
Bad_InvalidArgument |
The requestId is does not reference to a valid request for the Application. |
|
Bad_NothingToDo |
There is nothing to do because request has not yet completed. |
|
Bad_UserAccessDenied |
The current user does not have the rights required. |
|
Bad_RequestNotAllowed |
The CertificateManager rejected the request. The text associated with the error should indicate the exact reason. |
Table 33 specifies the AddressSpace representation for the FinishRequest Method.
Table 33 – FinishRequest Method AddressSpace Definition
|
Attribute |
Value |
||||
|
BrowseName |
FinishRequest |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
HasProperty |
Variable |
InputArguments |
Argument[] |
PropertyType |
Mandatory |
|
HasProperty |
Variable |
OutputArguments |
Argument[] |
PropertyType |
Mandatory |
GetCertificateGroups returns the Certificate Groups assigned to Application.
Signature
GetCertificateGroups(
[in] NodeId applicationId
[out] NodeId[] certificateGroupIds
);
|
Argument |
Description |
|
applicationId |
The identifier assigned to the Application by the GDS. |
|
certificateGroupIds |
An identifier for the Certificate Groups assigned to the 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 (see 7.6.7), StartSigningRequest (see 7.6.3) or StartNewKeyPairRequest (see 7.6.4) 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 shall be private key associated with the Certificate assigned to the Application).
Method Result Codes (defined in Call Service)
|
Result Code |
Description |
|
Bad_NotFound |
The applicationId does not refer to a registered Application. |
|
Bad_UserAccessDenied |
The current user does not have the rights required. |
Table 35 specifies the AddressSpace representation for the GetCertificateGroups Method.
Table 34 – GetCertificateGroups Method AddressSpace Definition
|
Attribute |
Value |
||||
|
BrowseName |
GetCertificateGroups |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
HasProperty |
Variable |
InputArguments |
Argument[] |
PropertyType |
Mandatory |
|
HasProperty |
Variable |
OutputArguments |
Argument[] |
PropertyType |
Mandatory |
GetTrustList is used to retrieve the NodeId of a Trust List assigned to an Application.
Signature
GetTrustList(
[in] NodeId applicationId
[in] NodeId certificateGroupId
[out] NodeId trustListId
);
|
Argument |
Description |
|
applicationId |
The identifier assigned to the Application by the GDS. |
|
certificateGroupId |
An identifier for a Certificate Group that the Application belongs to. |
|
trustListId |
The NodeId for a Trust List Object that can be used to download the Trust List assigned to the Application. |
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 shall be private key associated with the Certificate assigned to the Application).
Method Result Codes (defined in Call Service)
|
Result Code |
Description |
|
Bad_NotFound |
The applicationId does not refer to a registered Application. |
|
Bad_InvalidArgument |
The certificateGroupId parameter is not valid. The text associated with the error shall indicate the exact problem. |
|
Bad_UserAccessDenied |
The current user does not have the rights required. |
Table 35 specifies the AddressSpace representation for the GetTrustList Method.
Table 35 – GetTrustList Method AddressSpace Definition
|
Attribute |
Value |
||||
|
BrowseName |
GetTrustList |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
HasProperty |
Variable |
InputArguments |
Argument[] |
PropertyType |
Mandatory |
|
HasProperty |
Variable |
OutputArguments |
Argument[] |
PropertyType |
Mandatory |
GetCertificateStatus is used to check if an Application needs to update its Certificate.
Signature
GetCertificateStatus(
[in] NodeId applicationId
[in] NodeId certificateGroupId
[in] NodeId certificateTypeId
[out] Boolean updateRequired
);
|
Argument |
Description |
|
applicationId |
The identifier assigned to the Application Instance by the GDS. |
|
certificateGroupId |
The NodeId of the Certificate Group which provides the context. If null the CertificateManager shall choose the DefaultApplicationGroup. |
|
certificateTypeId |
The NodeId of the CertificateType for the Certificate. If null the CertificateManager shall select a Certificate based on the value of the certificateGroupId argument. |
|
updateRequired |
TRUE if the Application needs to request a new Certificate from the GDS. FALSE if the Application can keep using the existing Certificate. |
Access permissions that apply to CreateSigningRequest Method shall apply to this Method.
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 shall be private key associated with the Certificate assigned to the Application).
Method Result Codes (defined in Call Service)
|
Result Code |
Description |
|
Bad_NotFound |
The applicationId does not refer to a registered Application. |
|
Bad_InvalidArgument |
The certificateGroupId or certificateTypeId parameter is not valid. The text associated with the error shall indicate the exact problem. |
|
Bad_UserAccessDenied |
The current user does not have the rights required. |
Table 36 specifies the AddressSpace representation for the GetCertificateStatus Method.
Table 36 – GetCertificateStatus Method AddressSpace Definition
|
Attribute |
Value |
||||
|
BrowseName |
GetCertificateStatus |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
HasProperty |
Variable |
InputArguments |
Argument[] |
PropertyType |
Mandatory |
|
HasProperty |
Variable |
OutputArguments |
Argument[] |
PropertyType |
Mandatory |
RevokeCertificate is used to revoke a Certificate issued by the CertificateManager.
This Method requires an encrypted channel and that the Client provides credentials with administrative rights for the application which is having the credentials revoked.
Signature
RevokeCertificate (
[in] NodeId applicationId
[in] ByteString certificate
);
|
Argument |
Description |
|
applicationId |
The identifier assigned to the Application by the CertificateManager. |
|
certificate |
The DER encoded Certificate to revoke. |
Method Result Codes (defined in Call Service)
|
Result Code |
Description |
|
Bad_NotFound |
The applicationId does not refer to a registered Application. |
|
Bad_InvalidArgument |
The certificate is not a Certificate for the specified Application that was issued by the CertificateManager. |
|
Bad_UserAccessDenied |
The current user does not have the rights required. |
Table A specifies the AddressSpace representation for the RevokeCredential Method.
Table 16A – Revoke Method AddressSpace Definition
|
Attribute |
Value |
||||
|
BrowseName |
Revoke |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
HasProperty |
Variable |
InputArguments |
Argument[] |
PropertyType |
Mandatory |
This event is raised when a new certificate request has been accepted or rejected by the GDS.
This can be the result of a StartNewKeyPairRequest or StartSigningRequest Method calls.
Its representation in the AddressSpace is formally defined in Table 37.
Table 37 – CertificateRequestedAuditEventType Definition
|
Attribute |
Value |
|||||
|
BrowseName |
CertificateRequestedAuditEventType |
|||||
|
Namespace |
GDS (see 3.3) |
|||||
|
IsAbstract |
True |
|||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Modelling Rule |
|
|
Subtype of the AuditUpdateMethodEventType defined in OPC 10000-5. |
||||||
|
|
|
|
|
|
|
|
|
HasProperty |
Variable |
CertificateGroup |
NodeId |
PropertyType |
Mandatory |
|
|
HasProperty |
Variable |
CertificateType |
NodeId |
PropertyType |
Mandatory |
|
This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantic is defined in OPC 10000-5.
The CertificateGroup Property specifies the Certificate Group that was affected by the update.
The CertificateType Property specifies the type of Certificate that was updated.
This event is raised when a certificate is delivered by the GDS to a Client.
This is the result of a FinishRequest Method completing successfully.
Its representation in the AddressSpace is formally defined in Table 38.
Table 38 – CertificateDeliveredAuditEventType Definition
|
Attribute |
Value |
|||||
|
BrowseName |
CertificateDeliveredAuditEventType |
|||||
|
Namespace |
GDS (see 3.3) |
|||||
|
IsAbstract |
True |
|||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Modelling Rule |
|
|
Subtype of the AuditUpdateMethodEventType defined in OPC 10000-5. |
||||||
|
|
|
|
|
|
|
|
|
HasProperty |
Variable |
CertificateGroup |
NodeId |
PropertyType |
Mandatory |
|
|
HasProperty |
Variable |
CertificateType |
NodeId |
PropertyType |
Mandatory |
|
This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantic is defined in OPC 10000-5.
The CertificateGroup Property specifies the Certificate Group that was affected by the update.
The CertificateType Property specifies the type of Certificate that was updated.