2. X.509 Certificates

For an X509 login, X.509 certificates are required for authentication for all interprocess connections between any remote process and the Stone. These certificates are passed in as arguments on the command line, or as login parameters.

Different kinds of certificates are required.

The Stone CA certificate, which acts as a trust anchor. This can be a self-signed certificate or an certificate signed by an external certificate authority.
Host and User CA certificates, which are used to create chained certificates for the Host and User certificates
Host certificates and private keys, which authenticate a remote node to allow remote processes to authenticate with the Stone during startup. Host certificates are named, but the name is optionally restricted to a specific host or set of hosts by an additional CIDR-based address restriction.
User certificates and private keys, which are used to authenticate logins as specific users. When performing an X509 login, the login parameters do not specify a username; the user name is determined from the certificate. The certification also controls the name of the Stone, so the login parameters also do not include the Stone name.
A (CRLs) certificate revocation list. This allows certificates to be reliably revoked. For more information on CRLs, see the section starting here.

The GemStone distribution includes scripts that generate the required certificates. Alternatively, you can create certificates using any tools you wish, provided that the required information is included.

This chapter describes the process of creating certificates using the GemStone scripts.

2.1 Utilities to create Certificates

GemStone’s utilities to create certificates require OpenSSL, but otherwise do not require GemStone or a running Stone. You may use the OpenSSL that is distributed with the GemStone server, or your own OpenSSL installation.

Specific utilities include:

newstone

newstone_csr

newhostCA

newhost

newuserCA

newuser

Trust Anchor Certificate Authority

To create a self-signed stone CA, use the newstone script. If you want an external CA to produce the CA, use the script newstone_csr, which generates a certificate signing request (CSR) which can be used by the external CA to create the stone CA certificate.

While this externally generated stone CA certificate is not self-signed, it is accepted as a trust anchor by GemStone logins, the same way a self-signed stone CA is used.

Either the newstone or the newstone_csr script must be run before the other scripts, since all other scripts are specific to a particular Stone name (and require the -s argument to specify that Stone name).

User and Host Certificates

Each Stone requires certificates for each user and each host, which are specific to that stone.

Before creating user or host certificates, you must generate user and host CA certificates, using the scripts newuserCA and newhostCA. This allows separate control over certificate validity for these different types of entities.

The newuser and newhost scripts then create a chained certificate that is used for authentication.

Certificate Utilities

The GemStone scripts to create X509 certificates for the stone, hosts, and users, are located in the directory $GEMSTONE/bin/x509. It is not required to use these scripts to create certificates, provided the necessary information is included.

These scripts require the following environment variables to be set.

$GEMSTONE or $OPENSSL_PREFIX_DIR
This specifies where to find the OpenSSL executable. $GEMSTONE indicates to use the OpenSSL executable in the GemStone distribution; $OPENSSL_PREFIX_DIR is used to specify your own custom OpenSSL executables. If both variables are defined then $OPENSSL_PREFIX_DIR is used.
$GEMSTONE_CERT_DIR
A writable directory that will be the root directory for the hierarchical directory structure holding certificates and keys that are generated for all stones, users and hosts.

There is an additional, optional environment variable $GEMSTONE_CERT_DEBUG. If this is set, then debugging information is printed to stdout.

The certificate creation scripts include:

newstone -h | [-d daysValid] stoneName
create self-signed certificates for the stone with the given name.

newstone_csr -h | stoneName
create a certificate-signing-request for the stone with the given name.

newhostCA -h | [-d daysValid] -s stoneName
Create a CA certificate for the hosts associated with the Stone named stoneName. The Stone’s certificates must already exist.

newhost -h | [-d daysValid] [-a addr_restriction] -s stoneName certName
Create certificates for the host or hosts described by hostName, specifically associated with the Stone named stoneName. The Stone’s certificates must already exist and the host CA certificate must already exist. By default, the certs named certName can be used on any host to authenticate with stoneName; to restrict the host certs, you must use the -a argument. The -a addr_restriction must be in CIDR notation and will limit the IP address on which this certificate can be used to the specified range. If this argument is omitted, there is no restriction (0.0.0.0/0).

newuserCA -h | [-d daysValid] -s stoneName
Create a CA certificate for the user userName, specifically associated with the Stone named stoneName. The Stone’s certificates must already exist.

newuser -h | [-d daysValid] [-a addr_restriction] -s stoneName userName
Create certificates for the GemStone user userName, allowing login to a stone named stoneName. The Stone’s certificates must already exist and the user CA certificate must already exist. addr_restriction must be in CIDR notation and will limit the IP address from which users can login (note that this limits the nodes for both the client application and the Gem). If this argument is omitted, there is no restriction (0.0.0.0/0).

The newstone script must be run before the other scripts. They can be run on any node, they do not need to be run on the specific host.

If the certificates are created correctly, the command returns status code 0, and prints no results. If an error occurs, the details are displayed.

Limiting the period for which a certificate is valid

Certificates generated by GemStone scripts are by default valid for 30 days. You can specify the period of validity for certificates and CA certificates by using the -d argument to any of the scripts. For a login to succeed, all chained certs and CA certs must be valid.

A day is a 24-hour period starting from the time the certificate is created. You may examine the validity period of a pem file, along with other details, using:

unix> openssl x509 -in certfilename.pem -text

Limiting the IP addresses for Hosts and Users

You may also further control access by specifying the subnet for a certificate, so that only nodes on that subnet may use that certificate. These authorizations are embedded in the certificates, and are configured using an argument to the newhost and newuser scripts.

Address restrictions are specified using subnet masking with CIDR (Classless Inter-Domain Routing) notation. This notation includes a final /N with the number of bits to mask in the IP address. So for example, 0.0.0.0/0 indicates no restriction, 10.94.141.45/32 limits to a single IP address, and 10.94.141.0/24 limits to any host in the subnet 10.94.141.x.

Restricting nodes on which a host certificate can be used

By default, host certificates can be used to start an X509-secured NetLDI on any node. You can restrict the certificates so that they are only valid for a single node or for a subnet of nodes, using the -a argument to the newhost script. For example:

unix> $GEMSTONE/bin/x509/newhost -s gs64stone -a "10.94.141.0/24" stn_host

The resulting certificate and private key can be used on any node that has an IP address within the subnet 10.94.141.x.

Restricting nodes on which Gem or Application can run

Likewise, you can limit the nodes from which a particular user can login by creating the user certificates using the newuser -a argument.

Note that the user certificate subnet limits the nodes for the application client, as well as the Gem host node, if the application client and Gem host are different nodes.

When the user certificate is restricted to a limited address range, the login parameters may still specify the NetLDI using localhost or other 127.x.x.x addresses (loopback addresses, and therefore always the same host on both ends of the connection). The remote NetLDI will not apply the subnet restriction to the loopback address, and will fork the Gem. The remote Gem uses the same user certificate to authenticate with the HostAgent on the Stone’s node, using the IP address of the node it is on, that is, the remote Gem’s node. As long as the user certificate address restriction allows the IP address of the Gem’s node, this connection will be allowed.

Example certificate creation

If you have a stone named gs64stone that will be running on the node named stn_host, and will be starting the remote cache on another node named remote_host, the minimal set of certificates to login as DataCurator can be created using the following:

unix> setenv GEMSTONE_CERT_DIR $GEMSTONE/data

unix> $GEMSTONE/bin/x509/newstone gs64stone

unix> $GEMSTONE/bin/x509/newhostCA -s gs64stone

unix> $GEMSTONE/bin/x509/newhost -s gs64stone stn_host

unix> $GEMSTONE/bin/x509/newhost -s gs64stone remote_host

unix> $GEMSTONE/bin/x509/newuserCA -s gs64stone

unix> $GEMSTONE/bin/x509/newuser -s gs64stone DataCurator

These operations create the certificates and private keys and empty CRL (certificate revocation list) that are needed for both the remote NetLDI, the Stone’s NetLDI, and the X509 login.

2.2 Examine and delete certificates

A hierarchy of certificates and other supporting files is created within the directory specified by $GEMSTONE_CERT_DIR. Once the certificates are generated by the scripts, there is no specific meaning to location within the hierarchy, and you may move these files elsewhere, or use them where they are via the full path within the hierarchy.

Certificate directory structure

The scripts create a directory structure under $GEMSTONE_CERT_DIR, holding the various certificate files that are needed as well as other OpenSSL generated files. This structure is:

$GEMSTONE_CERT_DIR

	stones

		aStoneName

			stoneCA

				stoneCA-aStoneName.cert.pem

				stoneCA-aStoneName.privkey.pem

				hostCA-userCA-combined-aStoneName.crl.pem

				<other file/s>

			hosts

				aHostname

					aHostname.chain.pem

					aHostname.privkey.pem

					<other file/s>

			users

				aUserName

					aUserName.chain.pem

					aUserName.privkey.pem

					<other file/s>

You may copy the files from the given locations or use them in place, or rename them as needed.

For clarity, the instructions recommend putting the files into a new directory and defining another environment variable, to avoid long directory paths, and to make commands more readable.

Duplicates and Deleting certificates

You may not create a certificate if a certificate for the given stone, host or user already exists.

You can delete an existing certificate, or all certificates, manually from the directories. This keeps the certificate directories less cluttered, but to ensure that a certificate was not copied and cannot be used, you will need to revoke the certificate.

The following scripts are provided for convenience in reporting and removing unnecessary certificate flies:

lsstone -h | stoneName
List the Stone names for which certificates have been created.

lshost -h | -s stoneName
List the host names for which certificates have been created for the given Stone.

lsuser -h | -s stoneName
List the user names for which certificates have been created for the given Stone.

rmstone -h | [-f] stoneName
Remove the certificates for the stone with the given name. This will prompt for confirmation; use the -f option to force remove without confirmation.

rmhost -h | [-f] -s stoneName hostName
Remove the certificates for the host hostName associated with the given Stone. This will prompt for confirmation; use the -f option to force remove without confirmation.

rmuser -h | [-f] -s stoneName userName
Remove the certificates for the user userName associated with the given Stone. This will prompt for confirmation; use the -f option to force remove without confirmation.

2.3 Certificate revocation list

A CRL (Certificate revocation list) is a list of digital certificates that have been revoked by the CA (certificate issuing certificate authority), and should no longer be trusted. CRLs are PEM files and like certificates, multiple CRLs can be combined in a single CRL file.

Only leaf certificates (certificates for users and hosts) can be revoked.

A CRL is now required by startnetldi for an x509-secured NetLDI on the Stone’s node; this may initially be an empty CRL. An empty CRL file contains no revoked certs, but is a PEM file signed by the CA; this is necessary to ensure that the CRL is genuine.

The GemStone x509 certificate creation scripts now will automatically create an empty CRL when the host and user CAs are created. These are automatically combined into a single PEM file with the name

hostCA-userCA-combined-stoneName.crl.pem

When a host or user certificate is revoked, use the new scripts revokehost or revokeuser to revoke the cert; you must then restart the NetLDI on the Stone’s node, passing in the updated CRL file.

You will also need to manually stop the HostAgent supporting the revoked remote host, and any logged in sessions for the revoked user.

scripts to revoke host and user

The following scripts have been added, to allow you to revoke a host or user certificate.

revokehost -h | -s stoneName hostName
revoke a host certificate.

revokeuser -h | -s stoneName userName
revoke a user certificate

Revoking a cert causes the cert and key to be moved into the revoked directory. There, a new subdirectory is created with a the name of the host or user, and a timestamp in the directory name.

For example:

unix> $GEMSTONE/bin/x509/revokehost -s gs64stone lark

[Info]: Certificate /certs/stones/gs64stone/hosts/lark/lark.cert.pem has been revoked.

[Info]: Combined Certificate Revocation List (CRL) /certs/stone

s/gs64stone/stoneCA/hostCA-userCA-combined-gs64stone.crl.pem has been updated.

[Info]: Please distribute the new CRL to all appropriate locations.

After this, the directory /certs/stones/gs64stone/hosts/lark/ has been moved to /certs/stones/gs64stone/hosts/revoked/lark.revokedOn.May-22-2018-17-23-14/.

Applying updated CRL

Revoking a cert updates the file hostCA-userCA-combined-stoneName.crl.pem.

1. This updated CRL file should get copied into the directory in which your certs are located, overwriting the existing one.

2. Stop the Stone’s NetLDI and restart it using the -L option, passing in the updated CRL.

3. You must stop and restart the HostAgent process for the revoked host, or all HostAgents, by killing the process or using methods such as:

System stopHostAgents

System stopHostAgentSession:

Note that as of this alpha version, the HostAgents must be manually restarted using the starthostagent script.