This type defines a FileType that can be used to access a TrustList.
The CertificateManager uses this type to implement the Pull Model.
Servers use this type when implementing the Push Model.
An instance of a TrustListType shall restrict access to appropriate users or applications. This may be a CertificateManager administrative user that can change the contents of a TrustList, it may be an Administrative user that is reading a TrustList to deploy to an Application host or it may be an Application that can only access the TrustList assigned to it.
The TrustList file is a UA Binary encoded stream containing an instance of TrustListDataType (see 7.8.2.6).
The Open Method shall not support modes other than Read (0x01) and the Write + EraseExisting (0x06).
If a transaction is in progress (see 7.10.7) on another Session then the Server shall return Bad_TransactionPending if Open is called with the Write Mode bit set. If the Server supports transactions then the Server creates a new transaction or continues an existing transaction if Open is called with the Write Mode bit set.
If the SecureChannel is not authenticated the Server shall return Bad_SecurityModeInsufficient.
Servers shall automatically Close TrustLists if there are no calls to Methods on the TrustList Object within the time specified by the ActivityTimeout Property.
The Size Property inherited from FileType has no meaning for TrustList and returns the error code defined in OPC 10000-20.
When a Client opens the file for writing the Server will not actually update the TrustList until the CloseAndUpdate Method is called. Simply calling Close will discard the updates. The bit masks in TrustListDataType structure allow the Client to only update part of the TrustList.
When the CloseAndUpdate Method is called the Server will validate all new Certificates and CRLs. If this validation fails the TrustList is not updated and the Server returns the appropriate Certificate error code (see OPC 10000-4).
Its representation in the AddressSpace is formally defined in Table 22.
Table 22 – TrustListType Definition
|
Attribute |
Value |
||||
|
BrowseName |
0:TrustListType |
||||
|
IsAbstract |
False |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Modelling Rule |
|
Subtype of the 0:FileType defined in OPC 10000-20. |
|||||
|
0:HasProperty |
Variable |
0:LastUpdateTime |
0:UtcTime |
0:PropertyType |
Mandatory |
|
0:HasProperty |
Variable |
0:UpdateFrequency |
0:Duration |
0:PropertyType |
Optional |
|
0:HasProperty |
Variable |
0:ActivityTimeout |
0:Duration |
0:PropertyType |
Optional |
|
0:HasProperty |
Variable |
0:DefaultValidationOptions |
TrustListValidationOptions |
0:PropertyType |
Optional |
|
0:HasComponent |
Method |
0:OpenWithMasks |
Defined in 7.8.2.2. |
Mandatory |
|
|
0:HasComponent |
Method |
0:CloseAndUpdate |
Defined in 7.8.2.3. |
Mandatory |
|
|
0:HasComponent |
Method |
0:AddCertificate |
Defined in 7.8.2.4. |
Mandatory |
|
|
0:HasComponent |
Method |
0:RemoveCertificate |
Defined in 7.8.2.5. |
Mandatory |
|
|
|
|||||
|
Conformance Units |
|||||
|
GDS Certificate Manager Pull Model |
|||||
|
Push Model for Global Certificate and TrustList Management |
|||||
The LastUpdateTime indicates when the TrustList was last updated. The LastUpdateTime shall reflect changes made using the TrustList Object Methods. A TrustList Object in a CertificateManager shall also reflect changes made in other ways.
The LastUpdateTime of a TrustList Object in a CertificateManager allows Clients using the PullManagement to know whether the TrustList has changed since the last time they accessed it. The LastUpdateTime of a TrustList Object in the ServerConfiguration allows administration Clients to check for out of date TrustLists.
The UpdateFrequency Property specifies how often the TrustList needs to be checked for changes. When the CertificateManager specifies this value, all Clients that read a copy of the TrustList should connect to the CertificateManager and check for updates to the TrustList within 2 times the UpdateFrequency. The choice of UpdateFrequency depends on how quickly system changes need to be detected and the performance constraints of the system. UpdateFrequencies that are too long create security risks because of out of date CRLs. UpdateFrequencies that are too short negatively impact system performance. If the TrustList Object is contained within a ServerConfiguration Object then this Property is not present.
The ActivityTimeout Property specifies the maximum elapsed time between the calls to Methods on the TrustList Object after Open or OpenWithMasks is called. If this time elapses the TrustList is automatically closed by the Server and any changes are discarded. The default value is 60 000 milliseconds (1 minute).
The DefaultValidationOptions Property specifies the default options to use when validating Certificates with the TrustList. The TrustListValidationOptions DataType is defined in 7.8.2.8. This Property may be updated by Clients with access to the SecurityAdmin Role.
If auditing is supported, the CertificateManager shall generate the TrustListUpdated AuditEventType (see 7.8.2.11) when the TrustList is updated via the CloseAndUpdate, AddCertificate, RemoveCertificate or ApplyChanges (see 7.10.7) Methods. The Event is only raised once after the asynchronous update process completes.
The OpenWithMasks Method allows a Client to read only the portion of the TrustList.
This Method can only be used to read the TrustList.
After calling this Method, the Client calls Read one or more times to get the TrustList. If the Server is able to detect out of band changes to theTrustList before the Client calls the Close Method, then the next Read returns Bad_InvalidState. If the Server cannot detect out of band changes it shall ensure the Client receives a consistent snapshot.
For PullManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the CertificateAuthorityAdmin Role, the ApplicationSelfAdmin Privilege, or the ApplicationAdmin Privilege (see 7.2).
For PushManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).
Signature
OpenWithMasks(
[in] UInt32 masks
[out] UInt32 fileHandle
);
|
Argument |
Description |
|
masks |
The parts of the TrustList that are include in the file to read. The masks are defined in 7.8.2.7. |
|
fileHandle |
The handle of the newly opened file. |
Method Result Codes (defined in Call Service)
|
Result Code |
Description |
|
Bad_UserAccessDenied |
The current user does not have the rights required. |
|
Bad_TransactionPending |
The TrustList cannot be opened because it is part of a transaction is in progress. |
|
Bad_SecurityModeInsufficient |
The SecureChannel is not authenticated. |
Table 23 specifies the AddressSpace representation for the OpenWithMasks Method.
Table 23 – OpenWithMasks Method AddressSpace Definition
|
Attribute |
Value |
||||
|
BrowseName |
0:OpenWithMasks |
||||
|
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 CloseAndUpdate Method closes the TrustList and applies the changes to the TrustList. It can only be called if the TrustList was opened for writing. If the Close Method is called any cached data is discarded and the TrustList is not changed.
If only part of the TrustList is being updated the Server creates a new TrustList that includes the existing TrustList plus any updates and validates the new TrustList.
The Server shall verify that every Certificate in the new TrustList is valid using the validation process defined in OPC 10000-4. If an invalid Certificate is found the Server shall return an error and shall not replace the existing TrustList.
If the Server does not support transactions it applies the changes immediately and sets applyChangesRequired to FALSE. If the Server supports transactions then the Server creates a new transaction or continues an existing transaction and sets applyChangesRequired to TRUE.
If a transaction exists on the current Session, the Server does not update the TrustList until ApplyChanges (see 7.10.7) is called. Any Clients that read the TrustList before ApplyChanges is called will receive the existing TrustList before the transaction started.
If errors occur, the new TrustList is discarded.
When the TrustList changes the Server shall re-evaluate the Certificate associated with any open Sessions and SecureChannels. Sessions or SecureChannels with an untrusted or revoked Certificate shall be closed. This process may not complete before the Method returns and could take a significant amount of time on systems with limited resources.
The structure uploaded includes a mask (see 7.8.2.7) which specifies which fields are updated. If a bit is not set then the associated field is not changed.
Signature
CloseAndUpdate(
[in] UInt32 fileHandle
[out] Boolean applyChangesRequired
);
|
Argument |
Description |
|
fileHandle |
The handle of the previously opened file. |
|
applyChangesRequired |
If TRUE the ApplyChanges Method (see 7.10.7) shall be called before the new TrustList will be used by the Server. If FALSE the TrustList is now in use. |
Method Result Codes (defined in Call Service)
|
Result Code |
Description |
|
Bad_UserAccessDenied |
The current user does not have the rights required. |
|
Bad_CertificateInvalid |
The Server could not validate all Certificates in the TrustList. The DiagnosticInfo shall specify which Certificate(s) are invalid and the specific error. |
|
Bad_RequestTooLarge |
The changes would result in a TrustList that exceeds the MaxTrustListSize for the Server. |
|
Bad_TransactionPending |
Table 24 specifies the AddressSpace representation for the CloseAndUpdate Method.
Table 24 – CloseAndUpdate Method AddressSpace Definition
|
Attribute |
Value |
||||
|
BrowseName |
0:CloseAndUpdate |
||||
|
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 AddCertificate Method allows a Client to add a single Certificate to the TrustList. The Server shall verify that the Certificate using the validation process defined in OPC 10000-4. If an invalid Certificate is found the Server shall return an error and shall not update the TrustList.
This Method will return a validation error if the Certificate is issued by a CA and the Certificate for the issuer is not in the TrustList.
This Method cannot provide CRLs so issuer Certificates cannot be added with this Method. Instead, CA Certificates and their CRLs shall be managed with the Write Method on the containing TrustList Object.
This Method cannot be called if the containing TrustList Object is open.
This Method returns Bad_TransactionPending if a transaction is in progress (see 7.10.7).
This Method returns Bad_NotWritable if the TrustList Object is read only.
For PullManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the CertificateAuthorityAdmin Role (see 7.2).
For PushManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).
Signature
AddCertificate(
[in] ByteString certificate
[in] Boolean isTrustedCertificate
);
|
Argument |
Description |
|
certificate |
The DER encoded Certificate to add. |
|
isTrustedCertificate |
If TRUE the Certificate is added to the trustedCertificates list. If FALSE Bad_CertificateInvalid is returned. |
Method Result Codes (defined in Call Service)
|
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 Open Method was called with write access and the CloseAndUpdate Method has not been called. |
|
Bad_RequestTooLarge |
The changes would result in a TrustList that exceeds the MaxTrustListSize for the Server. |
|
Bad_TransactionPending |
Transaction has started and ApplyChanges or CancelChanges has not been called. |
|
Bad_SecurityModeInsufficient |
The SecureChannel is not authenticated. |
Table 25 specifies the AddressSpace representation for the AddCertificate Method.
Table 25 – AddCertificate Method AddressSpace Definition
|
Attribute |
Value |
||||
|
BrowseName |
0:AddCertificate |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
0:HasProperty |
Variable |
0:InputArguments |
0:Argument[] |
0:PropertyType |
Mandatory |
The RemoveCertificate Method allows a Client to remove a single Certificate from the TrustList. It returns Bad_InvalidArgument if the thumbprint does not match a Certificate in the TrustList.
If the Certificate is a CA Certificate that has CRLs then all CRLs for that CA are removed as well.
This Method returns Bad_CertificateChainIncomplete if the Certificate is a CA Certificate needed to validate another Certificate in the TrustList.
This Method returns Bad_TransactionPending if a transaction is in progress (see 7.10.7).
This Method returns Bad_NotWritable if the TrustList Object is read only. For PullManagement, this Method shall be called from an authenticated SecureChannel and from a Session that has access to the CertificateAuthorityAdmin Role (see 7.2).
For PushManagement, this Method shall be called from an authenticated SecureChannel and from a Session that has access to the SecurityAdmin Role (see 7.2).
Signature
RemoveCertificate(
[in] String thumbprint
[in] Boolean isTrustedCertificate
);
|
Argument |
Description |
|
Thumbprint |
The CertificateDigest of the Certificate to remove. |
|
isTrustedCertificate |
If TRUE the Certificate is removed from the Trusted Certificates List. If FALSE the Certificate is removed from the Issuer Certificates List. |
Method Result Codes (defined in Call Service)
|
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 Open Method was called with write access and the CloseAndUpdate Method has not been called. |
|
Bad_CertificateChainIncomplete |
The Certificate is needed to validate another Certificate in the TrustList. |
|
Bad_TransactionPending |
Transaction has started and ApplyChanges or CancelChanges has not been called. |
|
Bad_SecurityModeInsufficient |
The SecureChannel is not authenticated. |
Table 26 specifies the AddressSpace representation for the RemoveCertificate Method.
Table 26 – RemoveCertificate Method AddressSpace Definition
|
Attribute |
Value |
||||
|
BrowseName |
0:RemoveCertificate |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
0:HasProperty |
Variable |
0:InputArguments |
0:Argument[] |
0:PropertyType |
Mandatory |
This type defines a DataType which stores the TrustList of a Server. Its values are defined in Table 27.
Table 27 – TrustListDataType Structure
|
Name |
Type |
Description |
|
TrustListDataType |
Structure |
Subtype of the Structure DataType defined in OPC 10000-5 |
|
specifiedLists |
UInt32 |
A bit mask which indicates which lists contain information. The TrustListMasks enumeration in 7.8.2.7 defines the allowed values. |
|
trustedCertificates |
ByteString[] |
The list of Application and CA Certificates which are trusted. |
|
trustedCrls |
ByteString[] |
The CRLs for the Certificates in the trustedCertificates list. |
|
issuerCertificates |
ByteString[] |
The list of CA Certificates which are necessary to validate Certificates. |
|
issuerCrls |
ByteString[] |
The CRLs for the CA Certificates in the issuerCertificates list. |
Its representation in the AddressSpace is defined in Table 28.
Table 28 – TrustListDataType Definition
|
Attribute |
Value |
|||||
|
BrowseName |
0:TrustListDataType |
|||||
|
IsAbstract |
False |
|||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Other |
|
|
Subtype of the 0:Structure DataType defined in OPC 10000-5. |
||||||
|
|
||||||
|
Conformance Units |
||||||
|
GDS Certificate Manager Pull Model |
||||||
|
Push Model for Global Certificate and TrustList Management |
||||||
This is a DataType that defines the values used for the SpecifiedLists field in the TrustListDataType. Its values are defined in Table 29.
Table 29 – TrustListMasks Enumeration
|
Name |
Value |
Description |
|
None |
0 |
No fields are provided. |
|
TrustedCertificates |
1 |
The TrustedCertificates are provided. |
|
TrustedCrls |
2 |
The TrustedCrls are provided. |
|
IssuerCertificates |
4 |
The IssuerCertificates are provided. |
|
IssuerCrls |
8 |
The IssuerCrls are provided. |
|
All |
15 |
All fields are provided. |
Its representation in the AddressSpace is defined in Table 30.
Table 30 – TrustListMasks Definition
|
Attribute |
Value |
|||||
|
BrowseName |
0:TrustListMasks |
|||||
|
IsAbstract |
False |
|||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Other |
|
|
Subtype of the Enumeration DataType defined in OPC 10000-5. |
||||||
|
0:HasProperty |
Variable |
0:EnumValues |
0:EnumValueType [] |
0:PropertyType |
|
|
|
|
||||||
|
Conformance Units |
||||||
|
GDS Certificate Manager Pull Model |
||||||
|
Push Model for Global Certificate and TrustList Management |
||||||
This DataType defines flags for TrustListValidationOptions is formally defined in Table 31.
Table 31 – TrustListValidationOptions Values
|
Value |
Bit No. |
Description |
|
SuppressCertificateExpired |
0 |
Ignore errors related to the validity time of the Certificate. |
|
SuppressHostNameInvalid |
1 |
Ignore mismatches between the host name or ApplicationUri. |
|
SuppressRevocationStatusUnknown |
2 |
Ignore errors if the revocation list cannot be found for the issuer of the Certificate. |
|
SuppressIssuerCertificateExpired |
3 |
Ignore errors if an issuer has an expired Certificate. |
|
SuppressIssuerRevocationStatusUnknown |
4 |
Ignore errors if the revocation list cannot be found for any issuer of issuer Certificates. |
|
CheckRevocationStatusOnline |
5 |
Check the revocation status online. |
|
CheckRevocationStatusOffline |
6 |
Check the revocation status offline. |
If CheckRevocationStatusOnline is set, the Certificate validation process defined in OPC 10000-4 will look for the authorityInformationAccess extension to find an OCSP (RFC 6960) endpoint which can be used to determine if the Certificate has been revoked.
If the OCSP endpoint is not reachable then the Certificate validation process looks for offline CRLs if the CheckRevocationStatusOffline bit is set. Otherwise, validation fails.
The revocation status flags only have meaning for issuer Certificates and are used when validating Certificates issued by that issuer.
The default value for this DataType only has the CheckRevocationStatusOffline bit set.
The TrustListValidationOptions representation in the AddressSpace is defined in Table 32.
Table 32 – TrustListValidationOptions Definition
|
Attribute |
Value |
|||||
|
BrowseName |
0:TrustListValidationOptions |
|||||
|
IsAbstract |
False |
|||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Other |
|
|
Subtype of the 0:UInt32 DataType defined in OPC 10000-5 |
||||||
|
0:HasProperty |
Variable |
0:OptionSetValues |
0:LocalizedText [] |
0:PropertyType |
|
|
|
|
||||||
|
Conformance Units |
||||||
|
GDS Certificate Manager Pull Model |
||||||
|
Push Model for Global Certificate and TrustList Management |
||||||
This SystemOffNormalAlarmType is raised by the Server when the UpdateFrequency elapses and the TrustList has not been updated. This alarm automatically returns to normal when the TrustList is updated.
Table 33 – TrustListOutOfDateAlarmType definition
|
Attribute |
Value |
||||
|
BrowseName |
0:TrustListOutOfDateAlarmType |
||||
|
IsAbstract |
False |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
Subtype of the SystemOffNormalAlarmType defined in OPC 10000-9. |
|||||
|
0:HasProperty |
Variable |
0:TrustListId |
0:NodeId |
0:PropertyType |
Mandatory |
|
0:HasProperty |
Variable |
0:LastUpdateTime |
0:UtcTime |
0:PropertyType |
Mandatory |
|
0:HasProperty |
Variable |
0:UpdateFrequency |
0:Duration |
0:PropertyType |
Mandatory |
|
|
|||||
|
Conformance Units |
|||||
|
GDS Certificate Manager Pull Model |
|||||
|
Push Model for Global Certificate and TrustList Management |
|||||
TrustListId Property specifies the NodeId of the out-of-date TrustList Object.
LastUpdateTime Property specifies when the TrustList was last updated.
UpdateFrequency Property specifies how frequently the TrustList needs to be updated.
This event is raised when a Method that changes the TrustList is called
It is raised when CloseAndUpdate, AddCertificate or RemoveCertificate Method on a TrustListType Object is called.
Its representation in the AddressSpace is formally defined in Table 34.
Table 34 – TrustListUpdateRequestedAuditEventType Definition
|
Attribute |
Value |
|||||
|
BrowseName |
0:TrustListUpdateRequestedAuditEventType |
|||||
|
IsAbstract |
True |
|||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
|
Subtype of the 0:AuditUpdateMethodEventType defined in OPC 10000-5. |
||||||
|
|
||||||
|
Conformance Units |
||||||
|
GDS Certificate Manager Pull Model |
||||||
|
Push Model for Global Certificate and TrustList Management |
||||||
This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantic is defined in OPC 10000-5.
This event is raised when a TrustList is successfully changed.
This is the result of a CloseAndUpdate Method on a TrustListType Object or the result of a ApplyChanges Method on the ServerConfigurationType Object being called.
It shall also be raised when the AddCertificate or RemoveCertificate Method causes an update to the TrustList.
Its representation in the AddressSpace is formally defined inTable 35.
Table 35 – TrustListUpdatedAuditEventType Definition
|
Attribute |
Value |
|||||
|
BrowseName |
0:TrustListUpdatedAuditEventType |
|||||
|
IsAbstract |
True |
|||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
|
Subtype of the 0:AuditUpdateMethodEventType defined in OPC 10000-5. |
||||||
|
0:HasProperty |
Variable |
0:TrustListId |
0:NodeId |
0:PropertyType |
Mandatory |
|
|
|
||||||
|
Conformance Units |
||||||
|
GDS Certificate Manager Pull Model |
||||||
|
Push Model for Global Certificate and TrustList Management |
||||||
This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantic is defined in OPC 10000-5.
The TrustListId Property is the NodeId of the TrustList Object that was changed.