This section is devoted to guide the users through the installation, configuration and usage of a GSI SSH client on the local PC. This is a basic step to access a PRACE Door Node as well as, in some cases, a PRACE Home Site or a PRACE Execution. Please refer to this section for an overview of the terminology used.
All GSI SSH clients, independently from the user’s platform, have some prerequisites. The user should deploy in his/her local home folder the following:
- a personal X.509 User Certificate;
- a certificate for each trusted CA (Certification Authority);
More details on each item will follow.
Personal eScience certificate
GSI SSH authentication is based on X.509 eScience User Certificates (See FAQ for information on Certificates). For Globus services the default location of a personal certificate is the $HOME/.globus folder (%HOMEPATH% on Windows systems). In order to create it, the command to type in a new shell of Unix/Linux/Macintosh OS X is:
while the Windows equivalent is
GSI SSH clients support only PEM and PKCS12 formats.
In PEM format, the User certificate is split in two parts. The private key is contained by default in a file named userkey.pem, whose access should be limited to the owner. Otherwise, an error will be issued when trying to connect to a system. The other part of the credential is the public certificate, stored in the usercert.pem file. No particular rules regarding the file permissions apply here. For example, on Unix/Linux/OS X this translates to:
chmod 700 /.globus chmod 400 /.globus/*.pem
The PKCS12 format merges the private key and the public certificate in one file, usercred.p12 by default.
It is not mandatory to provide the User certificate in both formats, one is enough.
In order to convert a PKCS12 certificate into a PEM one, the OpenSSL command line tool should be emplyed. It is native on Unix, Linux and Macintosh OS X operating systems. For Windows machines there is a pre-compiled binary version that can be downloaded from this link. Please choose the latest version for the right platform (32 or 64 bit), usually the Light distribution package (i.e. not for software developers) is suitable.
Once the command line tool is installed, the instructions to type are:
openssl pkcs12 -in usercred.p12 -out usercert.pem -clcerts -nokeys openssl pkcs12 -in usercred.p12 -out userkey.pem -nocerts
where usercred.p12 is the original file. The PKCS12 format is usually adopted by browsers, so the source file is most likely the result of an export operation. Each OpenSSL command requires the user to type the password entered when the PKCS12 file has been created.
The conversion from PEM to PKCS12 can be obtained typing
openssl pkcs12 -export -in usercert.pem -inkey userkey.pem -out usercred.p12
where usercert.pem and userkey.pem are already available. The user will be asked to enter the password protecting the private userkey and to type (and confirm) a password for the newly created PKCS12 file.
The conversion from PEM format to PKCS12 can also be handled by means of GSISSH-Term. This is particulary convenient for Windows, where the usage of a command line tool is not straightforward. Once GSISSH-Term has been setup and started, selecting Tools->Keygen, the following dialogue box will be shown:
From the Action drop-down menu, please select Convert PEM to PKCS12 and click on the Convert button. Please note that the PEM files should be in the default location and named according the explained convention.
If the convention on filenames or default location can not be respected, then it is possible to set up the environment in order to access the desired PEM files. The environment variable X509_USER_CERT should point to the public certificate, while the private key should be identified by the environment variable X509_USER_KEY. For example, in a bash shell on a Unix-like system:
export X509_USER_CERT=/home/certs/pubcert.pem export X509_USER_KEY=/home/certs/privkey.pem
The restrictions on the file permissions of the private key still apply.
The term "CA certificates" refers to the grid credentials identifying the entities issuing grid certificates for users, services and hosts. Users are asked to maintain a copy on their platform since the GSI SSH protocol requires to check the identity of the server the client is trying to contact. For reference, the default location of a system-wide installation is the folder /
There are many alternative ways for the users to fulfill this requirement:
- direct download from SURFSARA. The correct section of the page is titled GLOBUS certs, where the folder’s content is archived as a tarball. This detail makes this method rather inconvenient for Windows systems. Moreover, the user has to take care that the content of the archive is deployed in the correct location. The above mentioned webpage also contains the SHA1 and PGP signatures for integrity check of the distribution.
- the GSI-SSHTerm client handles this aspect automatically. Every time it is started, it checks if the folder is present, starting a download in the background (completely transparent to the user) if needed;
- the MyProxy service can be used to retrieve the CA certificates. This implies the usage of a command line tool, unfortunately not available on Windows. The command to type is
myproxy-get-trustroots -s <address of the MyProxy server>, where the target hosts are px.grid.sara.nl or myproxy.lrz.de. The switch -v can be added to inspect the progress of the operation. If the command is run as root, then the destination folder is the default one for system-wide installations. In all other cases, the target is in the user’s $HOME, as specified above;
- Linux users can install the distribution by means of their favourite package manager directly from the European Grid Policy Management Authority (EuGridPMA). There are instructions for both APT and RPM based. Once the package manager has been configured with the new repository, the package ca_policy_igtf-classic needs to be installed. The CA certificates will be available for all users in the system-wide location.
For clarity, the following table summarizes the options available for each platform:
|Linux/Unix||Macintosh OS X||Windows|
|Direct download from SURFSARA||X||X||–|
|Retrieval from MyProxy||X||X||–|
The CA certificates folder should be kept up to date regularly, for example daily or weekly. According to the chosen deployment method, the respective actions to refresh the distribution are:
- donwload again the complete archive. A custom script is a convenient way to handle this task;
- GSI-SSHTerm does not need any user intervention, it checks if the distribution is outdated everytime it is started;
- run again the command
myproxy-get-trustroots -s <address of the MyProxy server>, the latest version available on the MyProxy server is fetched. Also in this case a custom script or a cronjob could help;
- a package update will keep in sync the distribution, adding new CAs and removing the dismissed ones.
Optionally, the fetch-crl tool can be installed. With this tool the list of revoked certificates will be kept up-to-date (these are certificates which shouldn’t be trusted anymore even if there end date is still validated). On a client system it would mean that the certificate of the system that you access will be checked against this list. This list always must be kept up-to-date on a server system. It is not currently packaged, so it should be installed from the original archive. The operation is pretty smooth since there is no need to compile any code. The tool also installs a cron job for daily updates of the CA certificats distribution.
GSI SSH clients
Users willing to log into a PRACE system via GSI SSH are invited to refer to one of these two clients:
- GSI-SSH command line tool, based on the compilation of the Globus Toolkit. It is available on Linux, Unix and Macintosh OS X but not on Windows. It requires some intervention in order to manage the CA certificates, however, users familiar with the regular OpenSSH login program will find the same functionalities with the same syntax (for example, -p for port selection or -X for secure X11 forwarding). Please not also that this client is installed on all PRACE Door Nodes to reach other PRACE resources. Please refer to the page dedicated to this tool for the details;
- GSISSH-Term, a Java based tool available on Linux, Unix, Macintosh OS X and Windows. It manages automatically the CA certificates and it integrates many of the command line tool features (i.e. X11 forwarding, MyProxy management) in a point-and-click interface. Moreover, since GSISSH-Term is launched as a Java webstart application, the most updated version is always delivered. All the necessary details are explained on a dedicated page.
The following table summarises the features of the two clients so that users can easily compare them and choose accordingly.
|GSI SSH command line tool||GSISSH-Term|
|Available on Linux/Unix/OS X||X||X|
|Available on Windows||–||X|
|Automatic management of CA certificates||–||X|
|Integrated MyProxy Tool||–||X|