How to use the “auth” command to sign a Pixhawk Board with your Certificate of Authenticity¶
The essence of this process is an RSA private/public key pair and a signing process that uses these keys to put some unique information onto every PX4 board.
Public/Private Key/s, SD Card, and Logging¶
The “auth” command will
- read a properly prepared public/private key data from the SD card
- use the key off the SD card to create the Certificate-Of-Authenticity (COA) in the One-Time_programmable (OTP) ROM.
- log the results to a log file on the SD card, for your records. (optional)
The bootloader must identify itself as revision 4 or later for this to work.
eg: px_uploader.py should say something like: “Found board xxxx bootloader rev 4 on /xxxxxxx “
The firmware must contain a directory Firmware/src/systemcmds/auth and have a recent “auth.c”.
- typically made and uploaded with “make px4fmu-v1_auth upload”, or similar.
- verify you have a suitable version of the firmware loaded on your PX4 by connecting to the nsh in the usual way, and typing ‘auth’[enter]
- the “auth” command can do a bunch of stuff related to reading/writing/verifying/signing/logging of OTP data. It’s the main tool you’ll use ( see below). It can read/write public/private key data from SD card, or it can use a “hardcoded” TEST version.
Preparing SD card (one time only)¶
Using a tool on linux or OSX called ssh-keygen make a new “pair” of 1024bit RSA keyfiles like this:
ssh-keygen -t rsa -b 1024 -f rsa1024
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase): [just press enter]
Enter same passphrase again: [just press enter, again]
- This is
- your PRIVATE key - do not share this file. back it up and keep it safe.
- This is your
- PUBLIC key - share it with all GCS makers, etc.
Format the private key file to suit the PX4:
Copy the rsa1024 to a new file, called “privatekey.txt”
Edit the file with a text editor to remove the first and last lines of the file (they say
-----BEGIN RSA PRIVATE KEY-----and
-----END RSA PRIVATE KEY-----) and save it.
Copy the privatekey.txt to a SD card which you will insert into a PX4 that is setup as per above. Do not use this method for the public key. See below.
Make the public key file on the SD card:
With the SD card inserted, and the PX4 booted, use the nsh shell, and type:
this will use the privatekey.txt on the SD card, and create a publickey.txt on the SD card (this file is needed for many of the auth commands to work).
Validate it works¶
There are lots of options to the “auth” command that you can use to test your configuration.
The only really *hazardous* options are
-k. Avoid these till you are sure everything else seems to be going well.
It is a good idea to reboot each time you use the ‘auth’ command, as it’s very aggressive on RAM usage.
When you are sure you have everything OK, run
auth -k -l(it will write a new COA to OTP, and lock it) and optionally
auth -vto verify it worked.
Automate running the ‘auth’ script from the SD card¶
- Make an “etc” folder on the SD card if one is not already there.
- Make a rc, or rc.txt file ( either works ) on the SD card, in the /etc folder if one is not already there.
- Edit the rc.txt file, and put the
auth -k -lcommand in the file as you wish it to be run.
- (When booted with this card inserted it will make the PX4 flash the OTP area with the COA and log the results to OTPCertificates.log)