Usage of client certificates from an external certification authority¶

The import of client certificates from an external certification authority can be done via a certificate signing request (CSR) or via the direct import of a PFX file (available from CODESYS SP18 or higher). In both cases, the certificates are imported via the ‘CODESYS Security Agent’. The client certificate must be imported under ‘Own Certificates’, the root certificate and all dependent certificates of the certificate chain must be imported under ‘Trusted Certificates’.

Import of client certificates via CSR¶

A Certificate Signing Request (CSR) is used to request a certificate for the owner’s public key from a certification authority, whereby the owner’s private key remains secret. The configuration of the ‘Common Name (CN)’ of the certificate is done in IEC via the function block TLSContext using the input ciCertInfo. The use case name sUseCaseName can be freely selected.

Example of TLSContext configuration¶

_sCipherList : NBS.CIPHER_LIST := STRUCT(psList := ADR('HIGH'), udiSize := 5);
sCertInfo : STRING := 'MyCommonName';
_ciDefaultCertInfo : NBS.CERT_INFO := STRUCT(psInfo := ADR(sCertInfo), udiSize := LEN(sCertInfo));

defaultTLSContext : NBS.TLSContext := (
    ciCertInfo := _ciDefaultCertInfo,
    ePurpose := NBS.PURPOSE.CLIENT_SIDE,
    itfCertVerifer := 0,
    sCipherList := _sCipherList,
    sHostname := 'MyHostName',
    sTLSVersion := '1.2',
    sUseCaseName := 'MyUseCase',
    udiVerificationMode := 14 // 14: Request client certificate only whithin initial handshake
);
AWSIoTClient_0: AWS_IOT.AWSIoTClient := (itfTLSContext := defaultTLSContext);

After the project has been loaded and started on the controller with the configured TLS context, the CSR file can be exported.

The export is done via the PLC shell of the device with the following steps:

Enter cert-getapplist → A component with ‘MyCommonName’ and ‘MyUseCase’and a number is displayed.

cert-createcsr <number>, where the number from step 1 must be used. The generation of the CSR file may take a few seconds (see Device → Log).

(Device → Files), copy the CSR file from the cert/export directory to the local file system.

The CSR file can now be used for the certificate signing request. The certificate issued by the certification authority can be imported with the ‘CODESYS Security Agent’ under ‘Own Certificates’.

Hint

If a certificate is deleted, then the private key is also deleted. In this case, the certificate signing request must be repeated.

Import of client certificates with private key¶

From CODESYS version SP18, client certificates with private key can be imported directly. The import can be done by PFX file via the ‘CODESYS Security Agent’. The PFX file can be created with OpenSSL from the certificate and the private key. The password will be used later for the import via the ‘CODESYS Security Agent’.

Example of creating a PFX file¶

openssl pkcs12 -export -out zertifikat.pfx -inkey privateKey.key -in zertifikat.crt

The PFX file can be imported with the ‘CODESYS Security Agent’ under ‘Own Certificates’. The certificate is loaded by the PLC via the ‘Common Name (CN)’. The configuration of the ‘Common Name (CN)’ of the certificate is done in IEC via the TLSContext function block using the ciCertInfo input. The use case name sUseCaseName can be freely selected.

Example of TLS context configuration¶

_sCipherList : NBS.CIPHER_LIST := STRUCT(psList := ADR('HIGH'), udiSize := 5);
sCertInfo : STRING := 'AWS IoT Certificate';
_ciDefaultCertInfo : NBS.CERT_INFO := STRUCT(psInfo := ADR(sCertInfo), udiSize := LEN(sCertInfo));

defaultTLSContext : NBS.TLSContext := (
    ciCertInfo := _ciDefaultCertInfo,
    ePurpose := NBS.PURPOSE.CLIENT_SIDE,
    itfCertVerifer := 0,
    sCipherList := _sCipherList,
    sHostname := 'MyHostName',
    sTLSVersion := '1.2',
    sUseCaseName := 'MyUseCase',
    udiVerificationMode := 14 // 14: Request client certificate only whithin initial handshake
);
AWSIoTClient_0: AWS_IOT.AWSIoTClient := (itfTLSContext := defaultTLSContext);