9.8. LCAP Over SSL
The section explains how to configure secure communication between LOCKSS boxes in a network.
Some LOCKSS networks, such as the Global LOCKSS Network (GLN), are open, in the sense that anyone may join and set up a LOCKSS box to participate in that network. The LOCKSS polling protocol (LCAP) includes several security measures to prevent rogue players from disrupting the network, but it is also possible to create a closed network, where only authorized nodes are allowed to participate. This document describes the steps needed to set up such a network.
In order to ensure that only authorized nodes may participate, each node is issued a private key, and all nodes are provided the set of corresponding public keys. This allows all inter-node communication to be both encrypted and authenticated, using SSL.
Note
The Classic LOCKSS system (version 1.x) does not support PKCS12, so if building keystores for a network that includes classic LOCKSS nodes, JCEKS should be selected.
9.8.1. Generating Keystores
The authority in charge of the private LOCKSS network (PLN) must create and distribute Java keystores to all participants. Each box receives two keystores: one containing its own private key (along with a password file containing the secret password for the private key) and another containing the public certificates for each of the boxes in the network. There are two methods available to create these keystores:
A Command Line Tool run in the LOCKSS development environment.
An Interactive Tool invoked in a running LOCKSS node.
In both cases, the admin creating the keystores must know the complete set of hostnames of boxes in the network. More hosts can be added at any time, but a new public keystore must be created and distributed to each box.
9.8.1.1. Command Line Tool
To use the command line tool:
Clone the lockss-core and laaws-dev-scripts projects from GitHub, in sibling directories.
Build
lockss-core
.In the root directory of
lockss-core
, run this command:../laaws-dev-scripts/bin/runclass org.lockss.keystore.EditKeyStores -s pubkeystore.pkcs12 -o keydir box1.pln.org ... boxN.pln.org
This will create, in the directory
keydir
, a public keystore namedpubkeystore.pkcs12
, and a pair of filesboxK.pln.org.pkcs12
andboxK.pln.org.pass
for each one of theN
host namesbox1.pln.org
throughboxN.pln.org
.To add additional hosts, provide the existing public keystore as the value of the
-s
argument, and list the new hosts. The new public keys will be added to the existing public keystore.
9.8.1.2. Interactive Tool
Bring up a LOCKSS stack, either in the production environment or
runcluster
. In the UI, select .Enter the hostname of each of the LOCKSS boxes in the Hostnames text box, then click the Generate Keystores button. A .tgz or a .zip file will be generated and offered for download. This file will contain the private keystore and password file for each host, as well as the shared public keystore.
To add additional hosts, use the Browse button to supply the existing public keystore, and enter the new hosts in the Hostnames text box. The downloaded file will contain the private keystore and password files for each new host, as well as the updated shared public keystore, which must be installed on all hosts.
9.8.2. Installing the Keystores
Securely transmit to each box its two files and the public keystore. Put them in
~lockss/lockss-installer/config/keys
, and set the owner and group tolockss:lockss
and the permissions to600
.Restart the stack and check that it is now using SSL. In the UI, select SSL: TLSv1.2, Client Auth.
. The page should showAfter a few hours, select
to ensure that each box is successfully originating and accepting connections from all the other boxes.