How-to guide

Manage certificates with GDS

Types usedOpcServerOpcServerSecurityRolesOpcCertificateAclOpcCertificateChangedEventArgs

A Global Discovery Server (GDS) can manage the application certificate and the trust list of a server remotely. This procedure is called GDS Push Management and is defined in OPC UA Part 12. For this, the server provides the methods of the ServerConfiguration object and the trust lists of its certificate groups.

Prerequisites

The methods can be called only if all of the following conditions are met. Otherwise, the server rejects the call with the status BadUserAccessDenied:

• At least one access control entry is assigned to the SecurityAdmin role. Without such an entry, management is turned off.
• The session of the GDS uses an endpoint with the mode SignAndEncrypt. Therefore, offer at least one such endpoint.
• The session is not anonymous, and its identity belongs to the SecurityAdmin role.

For the identity with the SecurityAdmin role, preferably use a certificate instead of a password, and assign the role to this one identity only:

C#

var adminCertificate = OpcCertificateManager.LoadCertificate(adminCertificatePath);
 
var admin = server.Security.CertificateAcl.AddEntry(adminCertificate);
admin.Assign(server.Security.Roles.SecurityAdmin);
server.Security.CertificateAcl.IsEnabled = true;
 
server.CertificateChanged += HandleCertificateChanged;
...
private static void HandleCertificateChanged(
        object sender,
        OpcCertificateChangedEventArgs e)
{
    Console.WriteLine(
            "New certificate: {0} ({1})",
            e.Certificate.Subject,
            e.Certificate.Thumbprint);
}

VB.NET

Dim adminCertificate = OpcCertificateManager.LoadCertificate(adminCertificatePath)

Dim admin = server.Security.CertificateAcl.AddEntry(adminCertificate)
admin.Assign(server.Security.Roles.SecurityAdmin)
server.Security.CertificateAcl.IsEnabled = True

AddHandler server.CertificateChanged, AddressOf HandleCertificateChanged
...
Private Shared Sub HandleCertificateChanged( _
        ByVal sender As Object, _
        ByVal e As OpcCertificateChangedEventArgs)
    Console.WriteLine( _
            "New certificate: {0} ({1})", _
            e.Certificate.Subject, _
            e.Certificate.Thumbprint)
End Sub

With a user name and password identity, enabling management looks like this:

C#

var admin = server.Security.UserNameAcl.AddEntry("admin", password: "password");
admin.Assign(server.Security.Roles.SecurityAdmin);
 
server.Security.UserNameAcl.IsEnabled = true;
server.CertificateChanged += HandleCertificateChanged;
...
private static void HandleCertificateChanged(
        object sender,
        OpcCertificateChangedEventArgs e)
{
    Console.WriteLine("New application certificate: {0}", e.Certificate.Thumbprint);
}

VB.NET

Dim admin = server.Security.UserNameAcl.AddEntry("admin", password:="password")
admin.Assign(server.Security.Roles.SecurityAdmin)

server.Security.UserNameAcl.IsEnabled = True
AddHandler server.CertificateChanged, AddressOf HandleCertificateChanged
...
Private Shared Sub HandleCertificateChanged( _
        ByVal sender As Object, _
        ByVal e As OpcCertificateChangedEventArgs)
    Console.WriteLine("New application certificate: {0}", e.Certificate.Thumbprint)
End Sub

Procedure

Method	Effect
UpdateCertificate	Passes a new application certificate, optionally with a private key and issuer certificates. The server validates and stages it. It takes effect only with ApplyChanges.
CreateSigningRequest	Creates a certificate signing request for the existing key of the server, which the GDS then has its certificate authority sign. The server takes the subject from the GDS; if none is given, it uses the subject of the current certificate. If the subject has no organization (O), the server adds it from OpcServerInfo.CompanyName. The request also contains the application URI and the domain names of the current certificate.
ApplyChanges	Moves the staged certificate into the ApplicationStore, stores the issuer certificates in the TrustedIssuerStore, then disconnects all sessions and uses the new certificate with its private key from then on. The server then raises the CertificateChanged event.
GetRejectedList	Returns the certificates from the RejectedStore, that is, the certificates the server has rejected.
Trust list methods (Open, Read, Write, CloseAndUpdate, AddCertificate, RemoveCertificate)	Read and change the trusted certificates and issuers of the certificate group; the server writes the changes to the TrustedPeerStore or TrustedIssuerStore.

If a certificate group has only one certificate type, the server also accepts CreateSigningRequest and UpdateCertificate without a certificate type.

Limitations

• UpdateCertificate accepts a new private key only in the PEM and PFX formats. The server also reports these two formats to the GDS as the supported formats.
• The common name (CN) in the subject of the new certificate must match that of the previous one, ignoring case. Other parts of the subject may differ, for example an organization that the certificate authority added. If the common name differs, the server rejects the certificate with the status BadSecurityChecksFailed.
• You must not pass issuer certificates with a self-signed certificate. The server validates all other certificates against the issuers passed.
• CreateSigningRequest always creates the request for the existing key. The server does not create a new key: it ignores the regeneratePrivateKey and nonce arguments. It rejects a subject that is not a valid distinguished name with the status BadInvalidArgument.

Impact on operation

ApplyChanges disconnects all existing sessions. Clients then reconnect and must trust the new certificate, for example because they trust the issuing certificate authority. Therefore, plan the certificate change like a maintenance window.