.. _credentials-gsi:

======================================
Managing credentials: GSI certificates
======================================

For GSI certificate-based authentication, mdtmFTP uses the same
security model as `Globus Toolkit`_.  As of January 2018, Globus
Toolkit is retired, and now it is succeeded by software maintained by
`Grid Community Forum`_ (GCF). For a detailed discussion about GSI
security, please refer to the `GCF document`_ section on `Configuring
Security for GridFTP`_.

Setting up GSI secuirty involves two tasks:

* To intall and configure user credentials.
* To install and configure host credentials.

.. _Globus Toolkit: http://toolkit.globus.org/
.. _Grid Community Forum: https://gridcf.org/

.. _GCF document: https://gridcf.org/gct-docs/
.. _Configuring Security for GridFTP: https://gridcf.org/gct-docs/latest/gridftp/admin/index.html#gridftp-admin-config-security


.. _user-credentials:

User credentials
================

.. _CILogon: https://cilogon.org/
.. _CILogon FAQ entry: https://www.cilogon.org/faq#h.p_ID_106

Requesting and installing user certificates on the client side
--------------------------------------------------------------

`CILogon`_ issues user certificates. We recommend requesting user
certificates from CILogon. Or you can choose to request user
certificates from your preferred CAs.

A user can obtain and install an CILogon user certicate by following the steps below:

1. go to `CILogon`_ to obtain a user certificate.

2. install the obtained certificate in the user's home directory, ``~/.globus/usercred.p12``, 

3. use ``chmod`` to protect it from unauthorized access:

.. code-block:: console

   $ chmod 0600 ~/.globus/usercred.p12

(For details, see `CILogon FAQ entry`_: "Can I download a CILogon
certificate to my computer?".)

The ``usercred.p12`` file is password protected when it is downloaded
from CILogon. For simplicity of use, you may want to derive a
password-free ``userkey.pem`` and ``usercert.pem`` from
``~/.globus/usercred.p12``:

.. code-block:: console

   $ cd ~/.globus
   $ openssl pkcs12 -in usercred.p12 -nokeys -out usercert.pem
   $ openssl pkcs12 -in usercred.p12 -nocerts -out userkey.pem
   $ chmod 0600 userkey.pem

Enter password for ``~/.globus/usercred.p12`` when prompted.  The
resulting key and certificate will be password-free.

Setting up trust paths for user certificates on the server side
---------------------------------------------------------------

To verify CILogon user certificates, you need to install CILogon CA bundle, 
available at the `download site`_, on the server side.

.. _download site: https://ca.cilogon.org/downloads

Download the CA bundle:

.. code-block:: console

  $ cd ~
  $ wget https://cilogon.org/cilogon-ca-certificates.tar.gz

Create the directory ``/etc/grid-security/certificates`` if it doesn't
exist:

.. code-block:: console

  $ sudo mkdir -p /etc/grid-security/certificates

Install CILogon CA bundle in ``/etc/grid-security/certificates``:

.. code-block:: console

  $ cd /etc/grid-security/certificates
  $ sudo tar zxvf ~/cilogon-ca-certificates.tar.gz --strip-components 2


.. _set-up-cn-ln-map:

Granting access to mdtmFTP server on the server side
----------------------------------------------------

To grant access to mdtmFTP server for a given user, you need
edit ``/etc/grid-security/grid-mapfile`` to create the mapping
between the user's certificate and a local user account on the server side.

1. Obtain the user's certificate Common Name (CN) from ``usercert.pem``:

.. code-block:: console

   $ openssl x509 -in ~/.globus/usercert.pem -noout -subject
   subject=DC = org, DC = cilogon, C = US, O = Fermi National Accelerator Laboratory, OU = People, CN = BDE User, CN = UID:bdeuser

2. Map the certificate CN to a local user account.
A line like below need to be added in ``/etc/grid-security/grid-mapfile``:

.. code-block:: console

   "/DC=org/DC=cilogon/C=US/O=Fermi National Accelerator Laboratory/OU=People/CN=MDTM User/CN=UID:mdtmftp" mdtmftp

Note: please do not map user certificates to ``root``.

Host credentials
================

.. _request-host-cert:

Requesting and intalling host certificates on the server side
-------------------------------------------------------------

You need request a host certificate for each mdtmFTP server host. 
We recommend requesting host certificates from one of the following
CAs:


Install host key and certificate files in:

* ``/etc/grid-security/hostkey.pem``
* ``/etc/grid-security/hostcert.pem``

Set appropriate ownship and permission for ``hostkey.pem`` and ``hostcert.pem``:

.. code-block:: console

	$ cd /etc/grid-security
	$ sudo chown root:root hostcert.pem hostkey.pem
	$ sudo chmod 0600 hostkey.pem
	$ sudo chmod 0644 hostcert.pem


.. _trust-path-for-host-cert:

Setting up trust paths for host certificates on the client side
---------------------------------------------------------------

You may request host certificates from one or multiple CAs. 
To verify host certificates on the client side, all related CA 
certificates must be insatlled under the path ``/etc/grid-security/certificates``
on the client side.

If you are using a host certificate signed by InCommon or LetsEncrypt,
you can simply install CILogon CA bundle,  available at the `download site`_. 
The CILogon CA bundle includes InCommon and LetsEncrypt's CA certificates.

.. _download site: https://ca.cilogon.org/downloads

Download the CA bundle:

.. code-block:: console

  $ cd ~
  $ wget https://cilogon.org/cilogon-ca-certificates.tar.gz

Create the directory ``/etc/grid-security/certificates`` if it doesn't
exist:

.. code-block:: console

  $ sudo mkdir -p /etc/grid-security/certificates

Install CILogon CA bundle in ``/etc/grid-security/certificates``:

.. code-block:: console

  $ cd /etc/grid-security/certificates
  $ sudo tar zxvf ~/cilogon-ca-certificates.tar.gz --strip-components 2


If you are using host certificates signed by a SimpleCA instance, you
will need to add the instance's CA certificate to your trust path, in
``/etc/grid-security/certificate``.  You can install the certificate
by installing the RPM or DEB package created by running the
``grid-ca-package`` command in your SimpleCA node.  See notes under
:ref:`dtn-trust-simpleca` for details.


.. _test-with-gsissh:

Verifying trust paths
=====================

You can verify whether user and host credentials have been correctly configured 
by using `GSI-enabled OpenSSH`_, also known as ``gsissh``.

.. _GSI-enabled OpenSSH: http://grid.ncsa.illinois.edu/ssh/

Follow the below steps:

1. Install gsissh server on mdtmFTP server host:

   .. code-block:: console

      $ sudo yum install gsi-openssh-server

2. On the server host, change the default gsissh port

   With the default configuration in ``/etc/gsisshd/sshd_config``,
   gsissh will attempt to run on port 22, but it will likely conflict
   with any "regular" ssh services that we have on that port. Pleae
   change the default gsissh port:

   .. code-block:: console

      $ sudo vim /etc/gsisshd/sshd_config # Change port to 2202

3. On the server host, start gsissh server in debug mode:

   .. code-block:: console

      $ sudo systemctl stop gsisshd
      $ sudo /usr/sbin/gsisshd -d

4. Install gsissh client on mdtmFTP client host:

   .. code-block:: console

      $ sudo yum install gsi-openssh-clients

5. From the client, try connecting to the server:

   .. code-block:: console

      $ gsissh -p 2202 $USER@$HOST \
          -o PasswordAuthentication=no \
          -o PubkeyAuthentication=no \
          -o GSSAPIAuthentication=yes

   Replace ``$USER`` and ``$HOST`` as appropriate.

If the above steps worked well, you will get a shell on the host.
Otherwise, use the debug messages from both the client and the server
to figure out what went wrong.

If things went well, and if you need gsissh again, you can enable and
start the service:

.. code-block:: console

  $ sudo systemctl enable gsisshd
  $ sudo systemctl start gsisshd