rpifwcrypto: Initial revision

Client side library and application for the Raspberry Pi firmware
cryptography service. The firmware mailbox based crypto service
provides limited support for cryptographic operations using
a ECDSA P-256 stored in OTP (using rpi-otp-private-key).

The current operations are
* Get number of OTP keys
* Get status for key
* Set status for a key (runtime lock)
* ECDSA SHA256 signature
* HMAC SHA256 (max message size 2KB)
  e.g. LUKS passphrase = HMAC(device-unique-ley, serial64 + EMMC CID)

 rpifwcrypto is a command line application designed to allow the
 crypto operations to be easily used in shell scripts.

 rpifwcrypto.h provides a library interface so that this can be
 embedded in other applications.

 Direct usage of mailbox API (vcmailbox) is not recommended
 because this is a new feature and the mailbox API is not frozen.

Author: timg236

CMakeLists.txt

@@ -15,3 +15,4 @@ add_subdirectory(raspinfo)
 add_subdirectory(vcgencmd)
 add_subdirectory(vclog)
 add_subdirectory(vcmailbox)
+add_subdirectory(rpifwcrypto)

README.md

@@ -18,13 +18,16 @@ A collection of scripts and simple applications
 * [piolib](piolib/) - A library for accessing the Pi 5's PIO hardware.
 * [raspinfo](raspinfo/) - A short script to dump information about the Pi. Intended for
     the submission of bug reports.
+* [rpifwcrypto](rpifwcrypto/) - A command line application and shared library for the
+    firmware cryptography service. Intended for use with Raspberry Pi Connect and
+    secure-boot provisioner.
 * [vclog](vclog/) - A tool to get VideoCore 'assert' or 'msg' logs
     with optional -f to wait for new logs to arrive.
 
 
 **Build Instructions**
 
-Install the prerequisites with "sudo apt install cmake device-tree-compiler libfdt-dev" - you need at least version 3.10 of cmake. Run the following commands to build and install everything, or see the README files in the subdirectories to just build utilities individually:
+Install the prerequisites with "sudo apt install cmake device-tree-compiler libfdt-dev libgnutls28-dev" - you need at least version 3.10 of cmake. Run the following commands to build and install everything, or see the README files in the subdirectories to just build utilities individually:
 
  - *cmake .*
     N.B. Use *cmake -DBUILD_SHARED_LIBS=1 .* to build the libraries in the subprojects (libdtovl, gpiolib and piolib) as shared (as opposed to static) libraries.

rpifwcrypto/CMakeLists.txt

@@ -0,0 +1,29 @@
+cmake_minimum_required(VERSION 3.10...3.27)
+include(GNUInstallDirs)
+
+set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall -Wextra -Werror")
+
+# Set project name
+project(rpifwcrypto)
+
+# Find GnuTLS package
+find_package(GnuTLS REQUIRED)
+
+option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
+
+# Create the shared library
+add_library(rpifwcrypto rpifwcrypto.c)
+target_sources(rpifwcrypto PUBLIC rpifwcrypto.h)
+set_target_properties(rpifwcrypto PROPERTIES PUBLIC_HEADER rpifwcrypto.h)
+set_target_properties(rpifwcrypto PROPERTIES SOVERSION 0)
+
+# Create the executable
+add_executable(rpi-fw-crypto main.c)
+target_link_libraries(rpi-fw-crypto rpifwcrypto ${GNUTLS_LIBRARIES})
+target_include_directories(rpi-fw-crypto PRIVATE ${GNUTLS_INCLUDE_DIRS})
+
+# Install rules
+install(TARGETS rpi-fw-crypto RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+install(TARGETS rpifwcrypto
+        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

rpifwcrypto/README.md

@@ -0,0 +1,43 @@
+
+# rpifwcrypto
+
+The Raspberry Pi Firmware Cryptography service is a mailbox based API
+that allows a limited set of cryptographic operations to be performed
+by the firmware without exposing private keys to userspace.
+
+The initial implementation is designed to support PiConnect and
+provides an ECDSA P-256 SHA256 signature API.
+
+A SHA256 HMAC API is provided to provide basic support for derived keys
+instead of using the raw device unique private key
+e.g. HMAC(serial-number + EMMC CID) could be used for a LUKS passphrase.
+
+Although this service can be used via raw vcmailbox commands the
+recommended API is either the command line rpi-fw-crypto application
+or the librpifwcrypto.so shared library.
+
+**Build Instructions**
+Install prerequisites with "sudo apt install cmake libgnutls28-dev"" - you need at least version 3.10.
+
+ - *mkdir build*
+ - *cd build*
+ - *cmake ..*
+ - *make*
+ - *sudo make install*
+
+**Usage**
+
+* rpi-fw-crypto -h                                                              (Displays usage instructions for all operations)
+* rpi-fw-crypto get-num-otp-keys                                                (Returns the number of OTP key slots)
+* rpi-fw-crypto sign --in message.bin --key-id 1 --alg ec --out sig.bin         (Signs message.bin with the device unique OTP key (id 1))
+* rpi-fw-crypto get-key-status 1                                                (Gets the status of key-id 1)
+* rpi-fw-crypto set-key-status 1 LOCKED                                         (Blocks the raw OTP read API on this key until the device is rebooted)
+* rpi-fw-crypto hmac --in message.bin --key-id 1 --out hmac.bin                 (Generates the SHA256 HMAC of message.bin and OTP key id 1)
+
+** Notes **
+The device unique private key can be provisioned with the `rpi-otp-private-key` utility.
+This MUST be a raw ECDSA P-256 key and not just a random number.
+
+This service is not a hardware security module and the current implementation
+does not protect the key and/or OTP from being accessed directly with root level privileges.
+It just removes the need to expose the key to userspace (e.g. initramfs) scripts.