Security Overview#
This chapter describes essential security features in Simplicity Commander.
Security Store#
Security Store is the location where all files generated and used by the security commands in Simplicity Commander are stored. You can find the path to Security Store with the commander security getpath command. Unless the --nostore option is used with security commands, Simplicity Commander will store all keys, certificates, and configuration files seen in Security Store. Descriptions of the files appear below.
access_certificate.bin: certificate delegating permission to unlock debug access of a device.
archive folder: folder used to store all outdated files (for example, all files in the challenge folder are moved here when a challenge is rolled).
cert_key.pem: private key used to sign unlock token.
cert_pubkey.pem: public key used in certificate. Public key corresponding to cert_key.pem.
certificate_authorization.json: configuration file used to define authorizations given by access certificate. May be edited.
challenge_xxx folder: folder used to store files related to a challenge.
unlock_payload_xxx.bin: payload used to unlock secure debug access.
unlock_command_to_be_signed_dd_mm_yyyy.bin: command token that needs to be signed with cert_key.pem
command_key.pem: private command key used to sign access certificate.
command_pubkey.pem: public command key stored on device. Public key corresponding to command_key.pem.
user_configuration.json: configuration file used in write config. May be edited.
When running the commander security unlock command, Simplicity Commander will use all available files to attempt to unlock the debug access. If anything is missing, you will be asked to provide the file as an option to the command. The file will then be stored in Security Store, unless the --nostore option is used.
Access Certificate#
An access certificate is used to delegate access to a single device to another key, which is called a certificate key. This scheme supports security models where the command key is kept in a secure location, while the certificate key can be used with more lenient security practices.
The access certificate contains the serial number of the device it applies to, a description of what actions it gives access to, and the public certificate key. An outline of the access certificate is illustrated in the following figure.
The device serial number uniquely identifies each device. It can be displayed by executing the commander security status command. The certificate_authorizations.json file sets the authorizations for the certificate. The current version of Simplicity Commander does not support any modifications to the authorization file, but it will be available in future versions. The private certificate key corresponding to the public certificate key in the certificate is used to generate a signature required to unlock debug access. For more information, see Challenge and Command Signing. The certificate is authenticated by signing it with the private command key corresponding to the public command key written to the device. The signing of the certificate may be done by passing an unsigned certificate to a Hardware Security Module (HSM) containing the private key or by providing the private key to Simplicity Commander (that is, for development) using the --command-key option.
Challenge and Command Signing#
The part of the data that needs to be signed to create a valid unlock command is called the challenge. Secure Element generates this random data. It remains unchanged until it is updated to a new random value by the security rollchallenge command.
By updating the challenge, any existing command signatures are effectively invalidated because part of the data the signature encompasses has changed. This allows the owner of the device to give debug access to someone else for a limited amount of time.
A command signature is created by signing a binary containing the data fields in yellow in the following figure; Simplicity Commander sets the unlock command ID, command parameters, and the security challenge using the private key corresponding to the public key in the access certificate.
The [security gencommand](/simplicity-commander/{build-docspace-version}/simplicity-commander-commands/security-commands#generate-unsigned-command-file) command creates a file containing these elements, but does not include the signature. If the certificate private key is not available to the user, the signature must be obtained from another party—for example, an HSM. If the user possesses the certificate private key, Security Commander can create the signed unlock command using the [security unlock](06-simplicity-commander-commands.md#secure-debug-unlock) command. By passing the command signature and the access certificate to the Debug Challenge interface, the debug interface is temporarily unlocked until the next power-on or pin reset.
