Guralp Systems Limited
MAN-EAM-1100 - CD1.1 Tools for Platinum

Chapter 11. Authentication Management

Both the subframe generator (gdi2cd11) and the sender (data-out-cd11) support authenticated operation. In this mode of operation, a hardware cryptography engine signs a hash of a channel subframe or a CD1.1 frame and this signature is appended to the data for transmission. A receiver can then verify the signature against the engine's public key to ensure the data originated on a specific digitiser.

Güralp currently support the Spyrus Lynks card as the hardware cryptography engine.

11.1 Process Overview

To begin, the cryptographic engine is used to generate a key-pair. The private key is held in hardware and can never be retrieved (i.e. it will never be visible in the file-system of the digitiser).

The public key is also held in hardware but can be retrieved at will, and is used to make a certificate signing request (CSR). The next step in the process is to generate a CSR, which is then sent to the certificate authority (CA) to be signed, forming a certificate.

The certificate can then be used by standard cryptographic tools to verify data signed by the corresponding private key. This process also yields an authentication key ID, which identifies the private key used to sign a given frame or subframe, and can be used to locate a corresponding certificate.

Once a key-pair has been generated, gdi2cd11 and data-out-cd11 are signalled to sign subframes and frames using the newly-generated private key and authentication key ID. This signalling usually occurs after the corresponding certificate has been installed in the receiver.

The digitiser provides both command line and web interface tools to perform these tasks. The command line tools include a wrapper script which automates the key-pair generation and activation aspects of the process, making unmanned station operation possible.

11.2 Spyrus Lynks operation

The operator controls the Spyrus card either through a command line utility, spyrus_util, or through the web interface (under Configuration→Networking→Spyrus Lynks).

11.2.1 Card initialisation

Before a card can be used, it must be initialised with a set of pin numbers and, if necessary, a root certificate. Then, at least one key pair should be generated and, again if necessary, a corresponding certificate installed. For CD1.1 operation, the Spyrus card is used in “loose” mode, which does not require any certificates to be uploaded to the card at all.

Initialising the card will destroy any previously installed keys.

To initialise the card using the web interface, fill out the three PIN phrases in the Card initialisation box, set Key validation mode to “Certificates are optional” and click .

To initialise the card from the command line, run:

spyrus_util --init --loose --sso-pin 1234 --user-pin 1234

entering the PIN numbers as desired. The operator will be asked to confirm the operation by entering yes before the command proceeds. This must be entered as three, lowercase letters, exactly as shown.

11.2.2 Key-pair generation

On the web interface, a new key can be generated in the section entitled “New key generation” by clicking . The first free slot, as identified in the on-screen text, will be used:

From the command-line, the spyrus_util tool can the used. The slot must be specified with the --index argument. The command format is:

spyrus_util --keygen --index 3 --dsaparam /etc/spyrus/dsaparam.pem.local

This example generates a key in slot 3 and outputs the PEM encoded public key to the terminal (on STDOUT). Note the use of the --dsaparam option to provide precomputed DSA parameters; if these are not specified, the card can take approximately one minute to generate one-shot parameters for the new key.

11.2.3 Public key retrieval

To retrieve the public key from an existing slot use the following command:

spyrus_util --getkey --index 3

11.2.4 Key deletion

Keys can be deleted through the web interface: find the corresponding slot in the list under “Card certificates” and click .

11.2.5 Certificate signing requests

In order to verify data signed by a private key, it is necessary to generate a certificate signing request (CSR) for forwarding to a certificate authority (CA) for signing.

To do this through the web interface, locate the key in the list and click the corresponding button.

The following screen is displayed:

Complete the form with the required values. If you are generating several keys, click the button to avoid having to enter the same information multiple times. The parameters that you have entered will be stored in the file /etc/spyrus/reqparam.local.

When the form is complete, click to create a request in a format suitable for emailing and then click to download the request to your PC. It can then be mailed to a suitable certification authority.

When finished, click to return to the main Spyrus configuration screen.

To generate a certificate signing request from the command line, the spyrus_util command should be used. By default the command outputs the PEM encoded request to the terminal (STDOUT) so it may be convenient to supply the --out file.pem option to redirect the output to a file:

spyrus_util --request --index 3 --out newreq.pem commonName="Bob Dunlop"

Note also the override of the commonName request subject component. To check the current subject options and values you can use the command:

spyrus_util --request --help

or simply examine the file /etc/spyrus/reqparam.local.

11.3 CD1.1 operation

The gdi2cd11 module must be correctly configured in order to use authentication (see section 6.2.1 for details). Required options are:

The data-out-cd11 module must also be configured to use authentication (see chapter 8.3.1 for details). Required options are:

It is possible to use the digitiser's web or command-line configuration tools to enable/disable authentication and to change the slot and key IDs. However, doing this will interrupt the data flow, because the data service must be restarted for changes to take effect.

Because of this, there is also a command line tool (cd11-management-tool, which is documented in section 10.2.5) for switching the authentication key ID and slot at runtime without interrupting the data flow. This tool is not capable of altering other aspects of the configuration.

It is also possible to operate on the Spyrus card using the spyrus_util tool while signing is in progress. Operations which cause signing to fail (reinitialising the card, or deleting or replacing the key-pair in active use for signing) will interrupt data flow, as subframes/frames are never sent without a signature if authentication is enabled. However, it is possible to generate or modify key-pairs in inactive slots without impeding data flow.

11.3.1 cd11-spyrus-tool.sh

A high-level wrapper script, cd11-spyrus-tool.sh, combines operation of the spyrus_util program and the cd11-management-tool program into a single program invocation. It is intended to be used in unmanned stations and corresponds directly to the IMS2.0 GENERATE_KEYPAIR and START_KEYPAIR commands.

Note: The adc-command tool, as documented in the Platinum manual, can be used to implement IMS2.0 calibration commands.

The script will operate on slot 1 and slot 2 of the Spyrus card, alternating between the two. The remaining card slots are not touched by the script and can be used for any purpose.

If run with no arguments, the script produces a help message:

Usage:

/usr/sbin/cd11-spyrus-tool.sh <command> [params]

Manages keys in slot 1 and slot 2 of the Spyrus card.

Interacts with spyrus_util and cd11-management-tool.

Commands:

help

init_card

generate_keypair

start_keypair

init_card command:

/usr/sbin/cd11-spyrus-tool.sh init_card [<pin>]

Re-initialises the card, destroying any keys or certificates

it may hold. Takes one parameter, the PIN number to use.

This will default to 1234 if unspecified.

generate_keypair command:

/usr/sbin/cd11-spyrus-tool.sh generate_keypair \

<csr_common_name> [<dsa_parameter_filename>]

Generates a new keypair in the inactive slot, returning a

CSR on stdout. The first parameter is the commonName field

to use in the CSR, and could be the station's ID code. The

second, optional parameter is the name of a file containing

DSA parameters.

start_keypair command:

/usr/sbin/cd11-spyrus-tool.sh start_keypair <auth_key_id>

Switches the active slot. The authentication key ID value to

use must be specified as a parameter.

The init_card command can be used to reinitialise the Spyrus card. This will destroy all private and public keys held by the card, and will interrupt signing and thus data flow. It takes an optional PIN number, which defaults to 1234 if not specified.

The generate_keypair command can be used to generate a new private/public key pair and corresponding certificate signing request (CSR). It must be passed the common name to use in the CSR (typically the site name) and may optionally be passed the file name of a file containing DSA parameters (for speeding up keypair generation). The digitiser has its own DSA parameter file as well, or will generate new parameters if this does not exist.

The script tracks which slot to use for new keypair generation. If no keypair has been generated and activated at all, new generation will take place in slot 1. Otherwise, new generation will take place in the inactive slot (slot 1 or slot 2).

The start_keypair command will toggle the active slot. A keypair must have been generated in the inactive slot or this will interrupt data flow as signing will fail. If no slot is currently active, it activates slot 1; otherwise, it toggles between slot 1 and slot 2.

start_keypair will update the configuration of all instances of gdi2cd11 and data-out-cd11 to use the newly-activated slot and the specified authentication key ID. As soon as the command has completed, any further signing operations will use the new key-pair and ID.