Skip to main content
  1. Home
  2. Apps

Repository: govuk-mobile-backend-config

Backend configuration for GOV.UK mobile app

GitHub
govuk-mobile-backend-config
Ownership
#govuk-apps-notifications
Category
Mobile apps
Links

README

This repository contains static backend config for the GOV.UK mobile apps.

How to use

There are several subprograms that can be run to process the config, allowing for a modular design and running in a variety of contexts - e.g. on CI or local laptop. All of the subcommands can expose help information by running npm start help <subcommand>.

There are some example config version documents in ./dummydata/appinfo

# it is recommended to start here
npm start help

# validate input (a single config version document)
npm start validate "<filename>"

# process a single config version document (outputs to stdout)
npm start generate "<filename>"

# if you want to pipe the output (e.g. to jq)
npm run --silent start generate "<filename>"

# generate a tree of config using the latest version detected
npm start build -- "[options]" "<environment>"

# to generate an output tree using the 'dummydata' directory
npm start build -- production --input-directory ./dummydata

Running KMS locally to test signatures

First install LocalStack if not already installed: brew install localstack/tap/localstack-cli

Start it running: localstack start -d

Pop some LocalStack config in ~/.aws/config:

[localstack]
region=us-east-1
output=json
endpoint_url=http://localhost:4566

Pop some LocalStack credentials in ~/.aws/credentials:

[localstack]
aws_access_key_id=test
aws_secret_access_key=test

Create a KMS key: aws --profile localstack kms create-key --key-usage SIGN_VERIFY --key-spec ECC_NIST_P256 Note the KeyId in the response

‘Download’ the public key using: aws --profile localstack kms get-public-key --key-id <KeyId from previous command>

Store the public key in a .der file using:

mkdir -p ./keys # make sure the keys directory exists
aws --profile localstack kms get-public-key \
    --key-id <KeyId from previous command> \
    --output text \
    --query PublicKey | base64 --decode > ./keys/kms_public.der

(This is the same as using the previous command, then copying the public key, decoding it and storing the result in a file.)

In order to generate LocalStack KMS signatures, store the KeyId in an environment variable called KMS_KEY_ID (you can do this by creating a .env file in this directory).

You can get a list of existing LocalStack keys using: aws --profile localstack kms list-keys

Verifying signatures

Local signing

Under this approach, the application will generate a new public/private key pair at runtime. This uses the Node.js crypto module. A file will be written to ./keys/local_public.der which contains the public key that you can use for verification. To invoke local signing, pass the --local-signature flag to the build command - i.e. npm start build -- production --local-signature --input-directory ./dummydata

KMS signing (using LocalStack)

In order to use this, the you need to set the AWS_PROFILE environment variable in the .env file to localstack. The application will call the LocalStack KMS service to sign config. You can use the public key (retrieved as above and written to ./keys/kms_public.der) to verify signatures locally.

Running the verification script

The script makes use of the very helpful jq which needs to be installed first. You can brew install jq to do this.

# format is ./verifysignature.sh <config-file-location> <public-key-file-location>
./verifysignature.sh ./config.out/appinfo/android ./keys/kms_public.der

The script uses OpenSSL under the hood, and can be used for both local and KMS signatures.

Linting

You can run the linter using npm run lint. This will output a set of warnings. This will run on the CI server so it’s important to fix any linting issues before pushing.

You can automagically fix linting issues with npm run fix.

Testing

Run the tests with npm test which invokes Jest. Check code coverage with npm test -- --coverage=true.

TODO

  • automatically fix lint issues on pre-commit
  • potentially a set of bash scripts that invoke the npm equivalents, or one big one
  • improve test coverage of file handling (essentially becomes integration tests though)