Managing Plugins

This document offers information about managing plugins in a LOCKSS network.

Managing Plugin Signing Credentials

If you are building and hosting the plugins used in your LOCKSS network, you will need to manage plugin signing credentials:

Each individual who will be building plugins from source code and signing them cryptographically will need to create a plugin signing key. A signing key is made of two parts: a private key which only the individual has access to and is used to sign files (in this case JAR files, which are specialized Zip files containing XML and Java code assets), and a public key which can be used by others or by software to verify a signed file was authentically signed by the corresponding private key.
You will need to collect the valid public keys for your network into a plugin signing keystore. By hosting this keystore on your network's configuration server (props server) and referencing it in your network's main configuration file (lockss.xml), nodes in the network will become aware of which signatures are valid and load plugins that come from authorized sources.

Creating a Plugin Signing Key

To generate a plugin signing key and add it to your network's plugin signing keystore, you will need:

Python 3.9 or greater. (Type python3 -V to check if Python is installed, and what version.
Git. (Type git --version to see if Git is installed.)
Java Development Kit (JDK) 17. (Type javac -version to check if the JDK is installed, and what version. Note that the presence of java is not sufficient to know if the JDK is installed in addition to the JRE.)
The file path to your network's plugin signing keystore, represented here as <mynetworkkeystore.keystore. (If you are creating it for the first time, this will be the path where the initial keystore will be created, or maybe you are using a starter plugin signin keystore like the plugin signing keystore of the LOCKSS Program, in which case it will be a path to it.)

Follow these steps:

If you have not already, use Git to clone the laaws-dev-scripts project from GitHub.
1. Type:
```
git clone https://github.com/lockss/laaws-dev-scripts
```
  This will create a laaws-dev-scripts directory in the current directory.
2. Go into this laaws-dev-scripts directory:
```
cd laaws-dev-scripts
```
3. Switch to the develop branch:
```
git switch develop
```
Relative to the laaws-dev-scripts directory, run:
```
python3 bin/generate-signing-key.py
```
You will be prompted for a variety of input parameters:
- Your organization, for example Stanford University.
- Your unit within the organization, for example Stanford University Libraries. Leave blank if not applicable to your organizational structure.
- Your organization's city or locality, for example Stanford.
- Your organization's state or province, for example California. Leave blank if not applicable to your locality.
- Your organization's country expressed as a two-letter ISO 3166 code, for example US for the United States.
- Your full name.
- An alphanumeric alias for your key. An alias will be unique in a keystore, and the public and private key files generated by this process will be named after this alias. Your network may have a naming convention for these aliases, such as a lowercase Linux username or lowercase university identifier, possibly followed by a hyphen and a lowercase identifier for your network (perhaps inspired by its Web domain). Example: flastname-myorg, where f represents the first letter of the first name, lastname represents the last name, and myorg represents the network (perhaps myorg.net on the Web).
- A passphrase for your private key, which must have at least 6 characters. You will also be prompted to retype it to confirm.
The script will display output from the keytool key management tool representing your newly generated key. You will then be asked whether to add the newly generated key to a keystore; enter Y for "yes". Further interactive prompts will follow:
- The path to the network plugin signing keystore.
- The password of the plugin signing keystore. If this file does not exist yet, you are setting this initial password and you will be prompted to retype it to confirm.
- Whether you trust the key you are importing into the keystore. A representation of the key by the keytool key management tool is again displayed, and it should match the one from above. If satisfied, enter yes.
The result of this process is two files (in the current directory), named after the alias supplied above:
- The file <alias>.keystore: this is your private key. Save it somewhere safe; the path to it will be needed by Turtles, the tool that builds, signs and deploys plugins.
- The file <alias>.cer: this is your public key. Save it with your private key. You will not need it routinely but you may need it to supply your plugin signing credentials to create or regenerate a keystore of plugin signing keys.
Additionally, the plugin signing keystore supplied will have been modified to include your public key (or the keystore will have been created at the given path, if new).

Deploying a Plugin Signing Keystore

Whether you added a new plugin signing key to the network plugin signing keystore or created the network plugin signing keystore for the first time, you need to disseminate the plugin signing keystore to the nodes in your network by making a copy of it into the directory served by your Web server as the configuration server (props server) and referencing it in your network configuration file (lockss.xml). Set the following properties:

org.lockss.plugin.keystore.location: The URL of the network plugin signing keystore on the configuration server (props server).
org.lockss.plugin.keystore.password: The network plugin signing keystore password.