Custom adapter certificates

If desired, the adapter can be configured to use a custom certificate for security instead of the auto-generated self-signed certificate. A certificate, private key, and configuration file are necessary to configure the adapter.  

Note: It is important that the subjectName and applicationUri parameters in the configuration file match the Subject and SubjectAlternativeName URL line in the certificate details.

For an example on how to create these files on a Ubuntu machine, see the Generate a custom certificate and configuration file section below.

Configure adapter security using a custom certificate

To configure the adapter using a custom certificate:

1. In your data source configuration, set UseSecureConnection to true. For more information, see Configure data source.

2. If the adapter has not connected to a data source previously using a secure connection, then the certificate folder locations will not have been generated.

   To do this, set the endpointURL data source parameter to "opc.tcp://dummyserver" as shown below. This step can be skipped if the certificate folder locations have been generated previously.

   [

   {

   "endpointURL": "opc.tcp://dummyserver",

   "useSecureConnection": true

   }

   ]

3. Delete the existing auto-generated public and private certificates in certificate public and private locations, respectively.

4. Add the custom .der file and the .pfx certificate files to certificate public and private locations.

5. Add the Application_Certificate.json configuration file to the component configuration directory.

   Note: The adapter must be restarted for the change to take effect.

6. Repost the data source using the address for the primary server.

   [

   {

   "endpointURL": "opc.tcp://<IP-Address>:<Port>/<TestOPCUAServer>",

   "useSecureConnection": true

   }

   ]

7. Manually move the server certificate from the rejected certificates location to the trusted certificates location using a file explorer or command-line interpreter.

   Linux example using command-line:

   sudo mv /usr/share/OSIsoft/Adapters/OpcUa/Certificates/rejected/certs/'SimulationServer [F9823DCF607063DBCECCF6F8F39FD2584F46AEBB].der' /usr/share/OSIsoft/Adapters/OpcUa/Certificates/trusted/certs/

   Note: Administrator or root privileges are required to perform this operation.

   After the certificate is in the adapter trusted certificates folder, the adapter trusts the server and the connection attempt proceeds in making the connection call to the configured server.

8. Add the adapter certificate to the server's trust store.

Generate a custom certificate and configuration file example

To create the certificate, private key, and configuration file on a Ubuntu machine:

9. Install openssl

   sudo apt install openssl

10. Create a folder named cert. This will hold all of files necessary for generating a certificate, private key, and configuration file.

11. Add the file config.txt shown below to cert. The values in this file can be changed to match the need of the application.

    [ req ]

    default_md = sha256

    prompt = no

    req_extensions = req_ext

    distinguished_name = req_distinguished_name

    [ req_distinguished_name ]

    commonName = TestCertificate

    countryName = US

    organizationName = Aveva

    DC = TestMachine

    [ req_ext ]

    keyUsage=critical,digitalSignature,keyEncipherment,nonRepudiation,dataEncipherment,keyCertSign

    extendedKeyUsage=critical,serverAuth,clientAuth

    basicConstraints=critical,CA:false

    subjectAltName = @alt_names

    [ alt_names ]

    URI.0 = urn:TestMachine:Aveva:OpcUa

    DNS.0 = TestMachine

12. Add the file generate.sh shown below to cert.

    #delete existing certs

    rm -rf out

    mkdir out

    #generate the RSA private key

    openssl genpkey -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out out/priv.key

    #create the CSR

    openssl req -new -nodes -key out/priv.key -config config.txt -nameopt utf8 -utf8 -out out/cert.csr

    #self-sign your CSR

    openssl req -x509 -nodes -in out/cert.csr -days 1826 -key out/priv.key -config config.txt -extensions req_ext -nameopt utf8 -utf8 -out out/cert.crt

    #make PFX

    openssl pkcs12 -export -out out/cert.pfx -inkey out/priv.key -in out/cert.crt

    #Export binary cert format

    openssl x509 -outform der -in out/cert.crt -out out/cert.der

13. Run the generate.sh script to create the .der and .pfx files. They will be located within the created out folder in cert.

14. Add the Application_Certificate.json shown below to cert. If the values in the req_distinguished_name and alt_names sections were changed, then the SubjectName and ApplicationUri need to be updated to match the changes generated in the certificate.

    [

    {

    "SubjectName": "CN=TestCertificate, C=US, O=Aveva, DC=TestMachine",

    "ApplicationUri": "urn:TestMachine:Aveva:OpcUa"

    }

    ]