• Home
• Function/Function Block Reference
• PLCnext Controller Function Blocks
• Security
• SEC_VERIFY_DEVICE_IDENTITY

SEC_VERIFY_DEVICE_IDENTITY

Type	Function block
Description	You can use this function block to check whether your IEC program runs on a trusted device. Otherwise, you may take protective measures, for example, to prevent device damage or to avoid know-how piracy. The function block verifies the identity of the device with cryptographic methods and returns details of the device. For the verification, the function block uses the PHOENIX device certificate hierarchy containing the root certificates in PEM-coded format. You can read the PHOENIX device certificate hierarchy from the device using the SEC_TA4PLCNEXT_1ST_GEN function block. In case of successful verification, details about the verified identity are provided at the outputs. To verify the identity, it is checked whether the device contains a matching private key, and whether it can apply this key. If a Secure Element (SE) of the device (for example, a TPM chip) holds the private key, it is ensured that the device is a "real" device as specified by the issuer of the identity. With a rising edge at the EXECUTE input, the string containing the PHOENIX device certificate hierarchy applied to the TRUSTED_CERTIFICATES input is verified. While verification takes place, the BUSY output is set to TRUE. Once the verification is completed, the BUSY output is set to FALSE and the DONE output is set to TRUE if the verification returns a positive result. In case of an error or if the identity could not be verified, the DONE output remains FALSE and the ERROR output is set to TRUE. If ERROR = TRUE, the ERROR_ID output provides details about the error.
Notes on the safety-related use	Certificates which are hard-coded in the IEC program should be applied to the TRUSTED_CERTS input. If, for example, the IEC program reads the certificates from a file, an attacker could run an IEC program on an untrusted controller in the way that a positive verification result of the device identity is returned. The attacker could achieve this by writing a self-defined identity as well as a self-defined number of trusted certificates that match with the identity into the file. PLCnext Technology controllers provide the "IDevID" identity (Initial Secure Device Identifier). This identity is bound to the Secure Element (SE) of the controller. The "IDevID" value (STRING#'IDevID') can be connected to the IDENTITY_NAME input (see the application example below). Other identities are possibly not bound to the Secure Element of the device. In case of a positive verification with connected "IDevID" value, the SUBJECT_SN output provides the name of the device type and the SUBJECT_SN output the serial number of the device.
Parameters	Inputs EXECUTE Data type: BOOL Description: The function block is executed with a rising edge at the input. The verification of the string containing the PEM-coded certificates applied at the TRUSTED_CERTIFICATES input is started. TRUSTED_CERTS Data type: SEC_PEM_CERTIFICATES Description: String containing the root certificates in PEM-coded format that are used to verify the identity of the device. If the certificate of the device identity per certificate chain can be related to one of the contained root certificates and it is successfully checked against a root certificate, the certificate for the device identity is valid. IDENTITY_NAME Data type: STRING Description: IdentityStores name on the device containing the identity to be verified. Use STRING#'IDevID' for the Phoenix Contact identity. Outputs DONE Data type: BOOL Description: After completion of the verification, the output is set to TRUE if the device identity could be successfully verified against the root certificates and thus the device can use the related private key. If EXECUTE is already reset to FALSE, the output is set to TRUE for only one cycle. BUSY Data type: BOOL Description: The output is set to TRUE while the verification of the device identity is performed. After completion of the verification, the output is set to FALSE. SUBJECT Data type: SEC_SUBJECT_STRING Description: Provides the value of the "Subject" field (also named "Owner" or "Issuer") of the certificate that belongs to the identity. The string is returned in RFC2253 format. The value of the output is only valid while DONE = TRUE. Example for a "Subject" field value: pseudonym=ed7e164e95fb0789489dee8fec3dae8de048a09d05f6ce39486c8b0c63862a33,serialNumber=1356809580,CN=AXC F 2152,OU=PHOENIX CONTACT GmbH & Co KG,O=PHOENIX CONTACT,L=Blomberg,ST=NRW,C=DE SUBJECT_CN Data type: STRING Description: Provides the value of the "CN" attribute (CN = Common Name) if contained in the "Subject" field of the certificate (see SUBJECT input). If available, the IEC application itself does not need to search and split the "Subject" field value when using this common name. The value of the output is only valid while DONE = TRUE. Example for a "CN" attribute value (see SUBJECT input for corresponding "Subject" field value): AXC F 2152 SUBJECT_SN Data type: STRING Description: Provides the value of the "serialNumber" attribute if contained in the "Subject" field of the certificate (see SUBJECT input). If available, the IEC application itself does not need to search and split the "Subject" field value when using this serial number. See also the notes concerning the safety-related use of the function block. The value of the output is only valid while DONE = TRUE. Example for a "serialNumber" attribute value (see SUBJECT input for corresponding "Subject" field value): 1356809580 ERROR Data type: BOOL Description: If an error occurred during verification or the verification has returned a negative result, the output is set to TRUE. The ERROR_ID output provides information on the error occurred while ERROR = TRUE. ERROR_ID Data type: SEC_IDENTITY_VALIDATION_ERROR (predefined array) Description: After completion of the verification or if the verification has been aborted, the output returns the error number providing information for the cause of the error. The value of the output is only valid while ERROR = TRUE. Possible values: ERROR_ID (16#....) Description 0000 The device identity was verified successfully with the given trusted certificates. 0100 This error only occurs in case of a programming error when implementing the function block. 0200 The value applied at the TRUSTED_CERTS input is either empty, contains an invalid format or one of the contained certificates is defined in a format that is not supported. 0201 The value applied at the IDENTITY_NAME input is empty or specifies an identity that is not known by the device. 1000 Missing certificate in the identity. 1001 Identity is untrusted. It does not match with the trusted certificates or it has not been issued during the possible validity period. 1002 Device does not contain a matching private key for the identity.
Application example