If you are interested in customizing parts of your Solo, and you have a Solo Hacker, this page is for you.
Custom Attestation key
The attestation key is used in the FIDO2 makeCredential or U2F register requests. It signs newly generated credentials. The certificate associated with the attestation key is output with newly created credentials.
Platforms or services can use the attestation feature to enforce specific authenticators to be used. This is typically a use case for organizations and isn't seen in the wild for consumer use cases.
Attestation keys are typically the same for at least 100K units of a particular authenticator model. This is so they don't contribute a significant fingerprint that platforms could use to identify the user.
If you don't want to use the default attestation key that Solo builds with, you can create your own and program it.
Creating your attestation key pair
Since we are generating keys, it's important to use a good entropy source. You can use the True RNG on your Solo to generate some good random numbers.
# Run for 1 second, then hit control-c solo key rng raw > seed.bin
First we will create a self signed key pair that acts as the root of trust. This won't go on the authenticator, but will sign the keypair that does.
Please change the root certification information as needed. You may change the ECC curve.
curve=prime256v1 country=US state=Maine organization=OpenSourceSecurity unit="Root CA" CN=example.com firstname.lastname@example.org # generate EC private key openssl ecparam -genkey -name "$curve" -out root_key.pem -rand seed.bin # generate a "signing request" openssl req -new -key root_key.pem -out root_key.pem.csr -subj "/C=$country/ST=$state/O=$organization/OU=$unit/CN=example.com/emailAddress=$email" # self sign the request openssl x509 -trustout -req -days 18250 -in root_key.pem.csr -signkey root_key.pem -out root_cert.pem -sha256 # convert to smaller size format DER openssl x509 -in root_cert.pem -outform der -out root_cert.der # print out information and verify openssl x509 -in root_cert.pem -text -noout
You need to create a extended certificate for the device certificate to work with FIDO2. You need to create this
v3.ext, and add these options to it.
subjectKeyIdentifier=hash authorityKeyIdentifier=keyid,issuer basicConstraints=CA:FALSE keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
Now to generate & sign the attestation key pair that will go on your device, or maybe 100,000 devices :). Note you must use a prime256v1 curve for this step, and you must leave the unit/OU as "Authenticator Attestation".
country=US state=Maine organization=OpenSourceSecurity unit="Authenticator Attestation" CN=example.com email@example.com # generate EC private key openssl ecparam -genkey -name "$curve" -out device_key.pem -rand seed.bin # generate a "signing request" openssl req -new -key device_key.pem -out device_key.pem.csr -subj "/C=$country/ST=$state/O=$organization/OU=$unit/CN=example.com/emailAddress=$email" # sign the request openssl x509 -req -days 18250 -in device_key.pem.csr -extfile v3.ext -CA root_cert.pem -CAkey root_key.pem -set_serial 01 -out device_cert.pem -sha256 # convert to smaller size format DER openssl x509 -in device_cert.pem -outform der -out device_cert.der # Verify the device certificate details openssl x509 -in device_cert.pem -text -noout
Let's verify that the attestation key and certificate are valid, and that they can be verified with the root key pair.
echo 'challenge $RANDOM' > chal.txt # check that they are valid key pairs openssl dgst -sha256 -sign device_key.pem -out sig.txt chal.txt openssl dgst -sha256 -verify <(openssl x509 -in device_cert.pem -pubkey -noout) -signature sig.txt chal.txt openssl dgst -sha256 -sign "root_key.pem" -out sig.txt chal.txt openssl dgst -sha256 -verify <(openssl x509 -in root_cert.pem -pubkey -noout) -signature sig.txt chal.txt # Check they are a chain openssl verify -verbose -CAfile "root_cert.pem" "device_cert.pem"
If the checks succeed, you are ready to program the device attestation key and certificate.
Programming an attestation key and certificate
Convert the DER format of the device attestation certificate to "C" bytes using our utility script. You may first need to
first install prerequisite python modules (
pip install -r tools/requirements.txt).
python tools/gencert/cbytes.py device_cert.der
Copy the byte string portion into the
attestation.c source file of Solo. Overwrite the development or "default" certificate that is already there.
Now build the Solo firmware, either a secure or hacker build. You will need to produce a
bootloader.hex file and a
Print your attestation key in a hex string format.
python tools/print_x_y.py device_key.pem
solo.hex, and attestion key into one firmware file.
solo mergehex --attestation-key <attestation-key-hex-string> bootloader.hex solo.hex all.hex
Now you have a newly create
all.hex file with a custom attestation key. You can program this
with Solo in DFU mode.