3. Getting Connected
X509 logins require a number of steps to ensure the supporting processes are setup with the appropriate certificates.
This chapter is organized to provide a summary of the instructions, followed by examples. The examples describe a Stone named devstone running on a node named alcatraz, the Stone’s node. The remote x509 Gem is running on fiji.
GemStone NetLDIs can be named, or accessed via port numbers. Named NetLDIs must be setup in the hosts NIS for each node. For simplicity, the following examples use a port number, 54321.
3.1 Setup and Login
The following instructions will help you setup the Stone and NetLDI and login an X509-secure session.
It is assumed you have generated scripts has described in the previous chapter. You may use certificates that were generated using GemStone scripts, or certificates generated in other ways provided they are correctly composed.
1. Configuring the Stone and the remote node
To begin with, you should have a GemStone/S 64 Bit installation on both the Stone’s node and on the remote cache node, and you should have setup and started a Stone process.
Before starting the process of setting up a X509 login, you might want to verify that your system is configured so you can perform a remote, non-X509 login between the remote and Stone’s node.
Since unsecured NetLDIs do not support X509 logins, and vice versa, you must either use a different port to start the X509-secured NetLDI on the Stone and remote nodes, or shut down the unsecured NetLDIs and restart using the process described in this chapter.
2. Setup script and log directories
X509 logins require a number of certificates to be available; some are needed on the Stone’s node, some on the remote node, and some on both nodes.
While there are a number of ways to manage the certificates, the simplest is to create new flat directories in which to place the required certificate files, and access these via an environment variable. These examples use $MyStoneCertDir and $MyRemoteCertDir.
On the Stone’s Node
Create a directory on the Stone’s node, and define an environment variable, for example $MyStoneCertDir, that points to the directory. Then copy the required certificate files to that directory.
Using the example certificates created in the previous step, on the Stone’s node, you would perform the following copy operations:
cp $GEMSTONE_CERT_DIR/stones/devstone/stoneCA/stoneCA-devstone.cert.pem $MyStoneCertDir
cp $GEMSTONE_CERT_DIR/stones/devstone/stoneCA/hostCA-userCA-combined-devstone.crl.pem $MyStoneCertDir
cp $GEMSTONE_CERT_DIR/stones/devstone/hosts/alcatraz/alcatraz.chain.pem $MyStoneCertDir
cp $GEMSTONE_CERT_DIR/stones/devstone/hosts/alcatraz/alcatraz.privkey.pem $MyStoneCertDir
On the Remote Node
Likewise, create a directory on the remote node, and define an environment variable there to point to this directory, $MyRemoteCertDir. Copy the following files to that directory:
export MyRemoteCertDir=dirName
cp $GEMSTONE_CERT_DIR/stones/devstone/stoneCA/stoneCA-devstone.cert.pem $MyRemoteCertDir
cp $GEMSTONE_CERT_DIR/stones/devstone/hosts/fiji/fiji.chain.pem $MyRemoteCertDir
cp $GEMSTONE_CERT_DIR/stones/devstone/hosts/fiji/fiji.privkey.pem $MyRemoteCertDir
cp $GEMSTONE_CERT_DIR/stones/devstone/users/DataCurator/DataCurator.chain.pem $MyRemoteCertDir
cp $GEMSTONE_CERT_DIR/stones/devstone/users/DataCurator/DataCurator.privkey.pem $MyRemoteCertDir
Setup log directories
There are a few differences in how X509 process handle child process log files.
With X509-secured NetLDIs, the startnetldi -D argument, which specifies a directory for child process logs, is required. Since the -D argument overrides the default use of the home directory, this means that gem log files do not get written to the home directory
To make log management easier, it is recommended to create log file directories for the Stone’s node and the remote node, and direct all related logs to that directory.
These examples use the environment variables $remoteLogDir and $stoneLogDir to refer to these directories.
fiji> mkdir $GEMSTONE/logs
fiji> export remoteLogDir=$GEMSTONE/logs
alcatraz> mkdir $GEMSTONE/logs
alcatraz> export stoneLogDir=$GEMSTONE/logs
3. Start certificate-only NetLDI on the Stone’s Node
The Stone must be running before you start the x509-secured NetLDI.
On the Stone’s node, you must start the NetLDI in certificate-only mode, using the arguments -S -U -R -J and -L in addition to any other startnetldi arguments. The -D argument is also required, to set the directory for log files. Do not use the -E argument.
For details on the startnetldi arguments, see Utility details for X509.
This NetLDI should be started as the same user as the one that started the Stone.
Example
This example specifies that the NetLDI’s log file and the log files created by child processes should be written under $stoneLogDir.
alcatraz> startnetldi -D $stoneLogDir -l $stoneLogDir/54321.log
-S -U $MyStoneCertDir/alcatraz.chain.pem
-R $MyStoneCertDir/alcatraz.privkey.pem
-J $MyStoneCertDir/stoneCA-devstone.cert.pem
-L $MyStoneCertDir/hostCA-userCA-combined-devstone.crl.pem 54321
4. Start certificate-only NetLDI on the Remote Node
With X509 logins, the certificate-only remote cache on a particular node must be started up and running before it can be used by a Gem to login. This is unlike ordinary logins in which the remote cache is only started up when a Gem logs in.
The NetLDI on the remote node has the responsibility of starting up the remote cache, which it does on instructions by the starthostagent utility on the Stone’s node.
Define or select a configuration file
Since the NetLDI is starting the remote cache, not the Gem, you must include a configuration file for the NetLDI, which includes the parameters used to configure the remote cache. To use the default configuration parameter values, you may pass in an empty file, or any configuration file.
The list of options used by remote caches is here.
In addition to cache configuration, the NETLDI_PORT_RANGE is specific to remote x509-secured NetLDIs. You may include a value for NETLDI_PORT_RANGE to specify the upper and lower bounds (inclusive) of the sockets that the remote Gem will listen on for connections initiated from its Host Agent on the Stone’s node.
NETLDI_PORT_RANGE = 50000, 50020;
Start the Remote NetLDI
For the remote certificate-only startnetldi, you must include the arguments -S -U -R -J which allow you to pass in the required certificates, and the -D argument for the log file location.
In addition, unlike with the startnetldi that is executed on the Stone’s node, you must also pass in the remote configuration file using the -E argument.
For details on the startnetldi arguments, see startnetldi.
5. Start the HostAgent on the Stone’s node
Once the remote and Stone’s NetLDI are running, you must execute the starthostagent utility, on the Stone’s node, to complete the startup.
Executing starthostagent initiates a number of important tasks. It requests that the Stone’s x509 NetLDI do the following:
- The Stone’s NetLDI mutually authenticates with the remote x509 NetLDI;
- The Host Agent on the Stone’s node starts up and log in;
- The remote NetLDI starts the remote cache
The starthostagent utility requires a number of arguments to allow it to securely connect the local and remote NetLDIs:
- the name (or IP) of the remote node, using argument to -m.
- the name (or port) that the remote NetLDI is listening on, using argument to -n.
- the name (or port) that the Stone’s NetLDI is listening on, using argument to -N.
- credentials to authenticate with the remote NetLDI, using -U -R -J
Example
Note that since in our examples the Stone and Remote NetLDIs are both using the same port number, the -N stoneNetLDI and -n remoteNetLDI arguments are the same.
alcatraz> starthostagent -m fiji -N 54321 -n 54321
-U $MyStoneCertDir/alcatraz.chain.pem
-R $MyStoneCertDir/alcatraz.privkey.pem
-J $MyStoneCertDir/stoneCA-devstone.cert.pem
Flow of Operations during HostAgent startup
The following diagram lists the internal steps that occur as a results of starthostagent.
Figure 3.1 Remote Cache and NetLDI startup
In this diagram, the steps are as follows:
1. The user starts the remote NetLDI using appropriate flags including the certificate flags. These arguments configure the NetLDI to start in certificate-only mode, listen on a public port, and await connection.
2. The user invokes starthostagent with the appropriate arguments, specifying the node and remote NetLDI to connect to, and the required certificate files. The starthostagent process contacts the already-running cert-only NetLDI on the Stone's node.
3. The Stone’s NetLDI starts (forks) the HostAgent.
4. The HostAgent creates the session in the Stone (logs in) as the user HostAgentUser.
5. The HostAgent attaches the extents (similar to the way the pages servers for a remote node attach the extents).
6. The HostAgent contacts the remote NetLDI on its public port, and performs mutual authentication using host credentials, creating secure connection (A).
7. The HostAgent connects and authenticates with the remote NetLDI again, and requests to fork a remote cache pageserver. The secure connection this creates, (B), is for the remote cache page server.
8. The remote NetLDI forks the remote cache page server. The secure socket (B) from the remote NetLDI to the HostAgent is inherited by the cache pageserver.
9. The cache page server starts associated processes to support the remote cache, as in ordinary remote cache startup.
Secure connection (A) between the HostAgent and the remote NetLDI remains active for use during logins.
6. Login
Logins can be done from topaz, GBS, GCI commands, and GemStone Smalltalk external session classes. Only RPC logins can be done using the secure protocol.
The X509 login requires a set of parameters that are distinct from those used for ordinary logins. The Stone name, GemStone user name and password, and host username and password are not required and must not be set, and NetLDI details are not included in the Gem’s NRS (e.g., gemnetid); the NetLDI (of the Gem host) is specified in the form hostname:netldiName.
In topaz, there are commands to set these parameters. For example:
topaz > set cert $MyRemoteCertDir/DataCurator.chain.pem
topaz > set key $MyRemoteCertDir/DataCurator.privkey.pem
topaz > set cacert $MyRemoteCertDir/stoneCA-devstone.cert.pem
topaz > set netldi localhost:54321
topaz > login
Setting any of these X509 login parameters clears the login parameters used for ordinary logins (gemstone, username, password, etc.). Likewise, setting any of the ordinary login parameters unsets the X509 login parameters.
The Gem will run on the host specified by the set netldi command, which does not need to be the same host as the topaz client. Rather than localhost, you may specify the host name or IP of another host that is running a certificate-only NetLDI.
If there are no gems running on the remote cache, after the timeout specified by STN_REMOTE_CACHE_TIMEOUT, the remote cache and HostAgent are shut down. You must execute the starthostagent script again (Step 5., above) to restart the remote cache and HostAgent.
Both ordinary and X509 logins are allowed to the stone, but ordinary logins cannot use the certificate-only NetLDIs. The X509-secured remote shared page cache does not support ordinary Gems, so ordinary logins cannot start a Gem on a node where a certificate-based remote shared page cache exists.
Flow of Operations during Login
The following diagram shows the flow of operations when a remove X509 secured Gem logs in.
The X509 login process differs considerably from ordinary remote cache login, since the NetLDI startup has already created the remote cache processes, and the socket connections are initiated from the Stone’s node.
Secure connections (A) and (B) are established during the setup step in the previous diagram.
1. The application (via GCI library code) requests an X509 login. The remote NetLDI performs mutual authentication with the application, and establishes the secure connection (C1).
2. The remote NetLDI listens on port N, selected from the range specified by NETLDI_PORT_RANGE. The Gem will accept a connection on that port in step (5).
3. The remote NetLDI forks the Gem, which inherits connection (C), now (C2), and listening port N.
4. The NetLDI informs the HostAgent via pre-existing persistent secure connection (A) that there is a Gem awaiting login at port N.
5. The HostAgent contacts the Gem on listening port N, and the connection is mutually authenticated; the Gem using user credentials and the HostAgent using host credentials, establishing secure connection (D).
6. The HostAgent creates the session in the Stone (logs in), for the userId provided in the user certificate. No GemStone password is used. The Gem does not maintain a connection directly to the Stone.
7. The HostAgent starts a page server thread to service the remote Gem.
8. The HostAgent provides a final reply to the Gem (on the secure connection (D)), indicating that the login is complete. The Gem returns from the login call, and the application is logged in.
Troubleshooting startup failures
In most cases, details of login failures are not reported, for security reasons.
- If you have trouble starting the Stone’s NetLDI, check the log file, and verify the existence, location, and validity of the certificate files.
- If you have trouble starting the Remote NetLDI, first check the remote NetLDI log file. Note that some errors, such as not being able to find the -E configuration file, are reported earlier in the log; be sure to read the entire log file, not merely the final statements.
- If the starthostagent script fails, verify that the Stone was started using a keyfile that allows X509 logins.
Check the HostAgent log file on the Stone’s node, which may contain error reports. The HostAgent log is located in the directory specified by -D argument to startnetldi, and has the name hostagent-StoneName-RemoteNode-PIDStoneNodeName.log.
- If the topaz login fails, check your parameters. The set netldi hostname must be the name of the Gem’s node, not the Stone’s node. The error message will also let you know if one or another of the required certs is missing.
Objects hidden by Object filtering
Default object filtering restricts the objects you can access in your remote session, and may make your application objects inaccessible. See Chapter 4 for a full description of object filtering.
An example script to allow objects to be transmitted to X509 remote caches is here.
3.2 X509 logins from Topaz
X509 login parameters
The login command now can be used with two distinct sets of parameters.
- For classic logins, the parameters are unchanged.
- For secure X509 logins, new and distinct parameters are required.
The required parameters for X509 certificate login (RPC only) are:
SET CERT: certfilepath
SET CACERT: cacertfilepath
SET KEY: privkeyfilepath
SET NETLDI: host:port
The following parameters are optional, but if used, apply only to X509 logins:
LOGFILE: gemlogfilepath
EXTRAGEMARGS: gemargs
DIRECTORY: dirname
The GemStone user name and the stone name are specified in the certificates, and are not entered in topaz by the user, and the GemStone user’s password is not needed.
With X509 logins, NRS is not used in any of the parameters. To specify the directory and log file name and any arguments to be passed to the gem, specific set commands are used.
If any of the X509 login parameters are set, the ordinary parameters are cleared, and the login command will perform an X509 login; if any of the ordinary parameters are set, the X509 parameters are cleared, and login performs a classic login.
The full set of new set commands are:
CACERT[:] cacertfilepath
Sets the path to the X509 certificate authority (CA) certificate to be used for login. The certificate must be in PEM format.
CERT[:] certfilepath
Sets the path to the X509 certificate to be used for login. The certificate must be in PEM format.
DIRECTORY[:] dirname
Set the name of the working directory for the RPC gem created by a certificate login. Also specifies the directory in which the Gem log will be written; if not specified, the log file is put into the directory provided in the startnetldi -D argument.
EXTRAGEMARGS[:] gemargs
Sets a list of extra command line arguments to be used when starting an RPC gem for a certificate login.
KEY[:] privkeyfilepath
Sets the path to the private key for the certificate specified by the SET CERT: command. The key must be in PEM format and must not be protected by a passphrase.
LOGFILE[:] gemlogfilepath
Set the name of the RPC gem's log file for certificate logins. If not specified, the default log file name is used.
NETLDI[:] hostname:port
Sets the hostname and port number for the certificate-only NetLDI to be used for X509 login. The format must include a the name or IP of the host, a colon, and the port or NetLDI service name. For example,
topaz> set netldi fiji.gemtalksystems.com:54321
That this is the Gem host’s NetLDI. The Gem will be started on the specified node fiji. You may use localhost to specify the Gem should be on the same node as the topaz process.
While the user certificate may include an address restriction, using localhost and other addresses 127.x.x.x (loopback addresses) are allowed, for running Gems on the same node. The address restrictions are applied when the Gem authenticates with the HostAgent.
The commands to set X509 parameters may be set in the .topazini file, or may be passed in on the command line using -X -n.
topaz arguments to configure X509 parameters on command line
Rather than specifying the certificates using the set command, you may pass them in on the command line using the topaz -X argument. The -X is only valid for RPC sessions, and takes a string containing three semicolon-delimited paths. For example:
'stoneCA-devstone.cert.pem;DataCurator.chain.pem;DataCurato r.privkey.pem'
The order is significant; the CA, cert, and private key must be in that order.
To set all the X509 login parameters required for login, you must also use the -n argument to specify the NetLDI name and port.
topaz -X '$MyCertDir/stoneCA-devstone.cert.pem;$MyCertDir/DataCurator.chain.pem;$MyCertDir/DataCurator.privkey.pem' -n localhost:54321
Status command
The topaz status command includes a section with the parameter information:
X509 Login Certificate Information:
Certificate________ '$MyRemoteCertDir/DataCurator.chain.pem'
CaCertificate______ '$MyRemoteCertDir/stoneCA-devstone.cert.pem'
Key________________ '$MyRemoteCertDir/DataCurator.privkey.pem'
Netldi_____________ 'localhost:54321'
Directory__________ ''
LogFile____________ ''
ExtraGemArgs_______ ''
3.3 X509 logins using the GCI interface
To perform X509 logins, use the GciX509Login function, which uses an instance of the C++ class GciX509LoginArg to hold the login parameters.
(BoolType) GciX509Login( GciX509LoginArg *args);
class CLS_EXPORT GciX509LoginArg
public:
const char *netldiHostOrIp;
const char *netldiNameOrPort;
const char *privateKey;
const char *cert;
const char *caCert;
const char *extraGemArgs;
const char *dirArg;
const char *logArg;
unsigned int loginFlags;
BoolType argsArePemStrings;
BoolType executedSessionInit; // output
If argsArePemStrings is true, the privateKey, cert, and caCert are strings in PEM format. If false, these are strings containing the name of a file that is in PEM format.
3.4 X509 logins using GBS
GemBuilder for Smalltalk/VW v8.4 supports X509-Secured logins with a parameters class, GbsX509SessionParameters. Instances of this class may be created programmatically, or by using the GUI tools. Once instances are created and added to the set of available login parameters, login and logout can be done as usual using the GBS Launcher.
When creating an instance of GbsX509SessionParameters using the GBS Launcher, a dialog asks if the new parameters are for X509 login, and brings up the appropriate dialog.
To programmatically create a new instance of GbsX509SessionParameters, execute an expression such as:
| params |
params := GbsX509SessionParameters new.
params
caCert: 'stoneCA-devstone.cert.pem';
cert: 'DataCurator.chain.pem';
privateKey: 'DataCurator.privkey.pem';
netldiHostOrIp: 'fiji';
netldiNameOrPort: '54321'.
GBSM addParameters: params.
Once the parameters are created, they can be used in the GBS Launcher or programmatically as ordinary parameters. For example, you can login using an expression such as:
session := GBSM loginWithParameters: params.
As with topaz, there are additional option arguments to allow you to configure the Gem log and other arguments. The following are also may be set in an instance of GbsX509SessionParameters. Currently, these can only be specified programmatically.
extraGemArgs:
dirArg:
logArg:
GemBuilder for Smalltalk/VA does not support X509-Secured logins.
3.5 X509 logins using External Sessions
The classes GsX509ExternalSession and GemStoneX509Parameters are variant of GsExternalSession and GemStoneParameters, which allow you to specify X509 certificates as login credentials rather than user id and password.
GsX509ExternalSessions are not supported on AIX.
topaz 1> run
| params session |
params := GemStoneX509Parameters
newFromPemFilesWithNetldiPort: '54321'
netldiHost: 'localhost'
certificate: 'DataCurator.chain.pem'
caCertificate: 'stoneCA-devstone.cert.pem'
privateKey: 'DataCurator.privkey.pem'.
session := GsX509ExternalSession newWithX509Parameters: params.
session login.
%
3.6 Local Logins
The preceding instructions describe how to login a remote session, that is, with the Gem process on a different node than the Stone’s node; remote logins constitute the greater security exposure.
X509-secured logins are also with the Gem on the Stone’s node. This configuration can include a client that is also on the Stone’s note, or on a remote node.
For a user certificate to be used for GciX509Login where the Gem is on the Stone’s node, any -a argument to the certificate creation script newuser must specify either 0.0.0.0/0 or an address 127.0.x.x.
X509 logins with Gem on the Stone’s node are not allowed by SystemUser.