A Go web service that digitally signs device assertion details.
The application can be run in three modes: signing service, admin service and system-user assertion services. All the web services operate under unencrypted HTTP connections, so these should not be exposed to a public network as-is. The services should be protected by web server front-end services, such as Apache, that provide secure HTTPS connections. Also, the admin service does not include authentication nor authorisation, so this service will typically be made available on a restricted network with some authentication front-end on the web server e.g. SSO. Typically, the services will only be available on a restricted network at a factory, though, with additional security measures, the signing service could be made available on a public network.
Some deployment recommendations are provided
Are you using one of the many systems that support snaps? A pre-built snap is available from the Snap store.
$ sudo snap install serial-vaultThe service needs a PostgreSQL database to run, so:
- Install PostgreSQL and create a database.
- Set up the config file, using
settings.yamlas a guide. - Configure the snap using the
settings.yamlfile:
$ cat /path/to/settings.yaml | sudo /snap/bin/serial-vault.config
$ sudo systemctl restart snap.serial-vault.service.serviceThe snap will create the tables in the database on restart, as soon as it has a valid database connection.
The service mode (signing or admin) is defined in the settings.yaml file. The selected service should be accessible on port :8080 or :8081:
- Signing Service: http://localhost:8080/v1/version
- Admin Service: http://localhost:8081/
- System-User Service: http://localhost:8082/
The Admin and System-User services' CSRF protection sends a cookie over a secure channel. If the cookie is to be sent over an insecure channel, it is needed to workaround it by setting the environment variable:
$ export CSRF_SECURE=disableWhen modified that environment variable is set, consider that the current web session must be invalidated in order to changes take effect. That could require a browser restart. NEVER set this configuration in production environments.
If you have a Go development environment set up, Go get it:
$ go get github.com/CanonicalLtd/serial-vault- Install PostgreSQL and create a database.
- Set up the config file, using
settings.yamlas a guide. - Create the database tables:
$ cd serial-vault $ go run cmd/serial-vault-admin/main.go database --config=/path/to/settings.yaml
$ cd serial-vault
$ go run cmd/serial-vault/main.go -config=/path/to/settings.yaml -mode=signingThe application has an admin service that can be run by using mode=admin.
Juju greatly simplifies the deployment of the Serial Vault. A charm bundle is available at the charm store, which deploys everything apart from the Apache front-end units. There is an example of using Juju in the Deployment Guidelines.
The Juju charm uses a snap that is available at the Snap store
$ git clone https://github.com/CanonicalLtd/serial-vault
$ cd serial-vault/docker-compose
$ docker-compose up
# remove containers after try
$ docker-compose kill && docker-compose rmFollow the instructions to install Go.
- Install the build packages
sudo apt-get install build-essential libssl-dev
# For TPM2.0 (optional)
sudo apt-get install tpm2-tools-
Install NVM Install the Node Version Manager that will allow a specific version of Node.js to be installed. Follow the installation instructions.
-
Install the latest stable Node.js and npm The latest stable (LTS) version of Node can be found on the Node website.
# Overview of available commands
nvm help
# Install the latest stable version
nvm install lts/*
# Select the version to use
nvm ls
nvm use lts/*- Install the nodejs dependencies
cd serial-vault
npm install# Select the version to use
nvm ls
nvm use lts/*
npm run buildnpm testReturn the version of the serial vault service.
{
"version":"0.1.0",
}- version: the version of the serial vault service (string)
Returns a nonce that is needed for the 'serial' request.
{
"request-id": "abc123456",
"success": true,
"message": ""
}- success: whether the request was successful (bool)
- message: error message from the request (string)
- request-id: unique string that is needed for serial requests (string)
The request-id is a nonce that can only be used once and must be used before it expires (typically 600 seconds).
Generate a serial assertion signed by the brand key.
Takes the details from the device as a serial-request assertion and generates a signed serial assertion.
The message must be the serial-request assertion format and is best generated using the snapd libraries.
type: serial-request
brand-id: System
model: Router 3400
device-key:
WkUDQbqFCKZBPvKbwR...
request-id: abc123456
body-length: 10
sign-key-sha3-384: UytTqTvREVhx...
HW-DETAILS
serial: A1228ML
AcLBUgQAAQoABgUCV7R2C...
- brand-id: the Account ID of the manufacturer (string)
- model: the name of the device (string)
- device-key: the encoded type and public key of the device (string)
- request-id: the nonce returned from the /v1/nonce method (string)
- signature: the signed data
- serial: serial number of the device (string)
The HW-DETAILS are optional hardware details in YAML format, but must include the 'serial' tag as that is a mandatory part of the serial assertion.
The method returns a signed serial assertion using the key from the vault.
Find the model pivot details for a device.
Takes the serial assertion from a device and returns the model pivot details for the device.
The serial assertion of the manufacturer's device.
The method returns details of the model pivot, to convert the device to a reseller model.
Generate the model assertion for the pivoted model for a device.
Takes the serial assertion from a device and returns the model assertion for the pivoted model of the device.
The serial assertion of the manufacturer's device.
The method returns details of the model assertion of the pivoted model, to convert the device to a reseller model.
Generate the serial assertion for the pivoted model for a device.
Takes the serial assertion from a device and returns the serial assertion for the pivoted model of the device.
The serial assertion of the manufacturer's device.
The method returns details of the serial assertion of the pivoted model, to convert the device to a reseller model.