INSTALL

Contents of this file
---------------------
 
 * Introduction
 * Solution stack
 * Prerequisites
 * syslog-ng
 * OpenSSH
 * OpenLDAP
 * pam_openssh_x509
 * PuTTY-CAC 0.62
 * Trusted CA's store
 * Overview


Introduction
------------

This file describes how to setup an environment from scratch to get familiar
with pam_openssh_x509.

Note that in a production environment some steps would be done automatically.
Examples are the creation and distribution of x509 certificates. In addition,
components like the LDAP server, the logging facility and the SSH client are
exchangeable and don't need to be the the same implementations as used here.

For a quick setup the 'samples' directory included with the package holds
configurations needed for the installation steps.

When copying setup instructions below, make sure that the paths are relative to
the root directory of the package. All steps have been tested on a Raspberry PI
running Arch Linux. Paths might have to be adjusted for other distributions.


Solution stack
--------------

 * syslog-ng 3.5.6
 * PAM 0.83
 * OpenSSL >= 1.0.1j
 * OpenSSH >= 6.2
 * libldap 2.4.40
 * OpenLDAP 2.4.40
 * libConfuse 2.7
 * pam_openssh_x509
 * PuTTY-CAC 0.62
 * check >= 0.9.10


Prerequisites
-------------

Make sure there is a local user 'pox509-test-user'.


syslog-ng
---------

1) Install syslog-ng.

2) Create directories for log files:
   $ mkdir /var/log/ssh
   $ mkdir /var/log/slapd

3) Copy config:
   $ cp samples/syslog-ng.conf /etc/syslog-ng/


OpenSSH
-------

1) Install OpenSSH with PAM support.

2) We are running a second instance of OpenSSH here in order to fall back
   to the standard one without pam_openssh_x509 support. Configuration goes
   into a new directory:
   $ mkdir /usr/local/etc/ssh

3) Copy sshd_config:
   $ cp samples/sshd_config /usr/local/etc/ssh/

4) Create directory for users public keys:
   $ mkdir /usr/local/etc/ssh/keystore

   In this directory every user gets a subdirectory named after their UID. The
   authorized_keys file will be stored there.

5) Create keystore for 'pox509-test-user':
   $ mkdir /usr/local/etc/ssh/keystore/pox509-test-user

   /!\ As the authorized_keys file will be managed by pam_openssh_x509, we have
   to make sure that noone besides root can change the authorized_keys file.
   Standard permissions (755) with ownership root:root should be fine.

7) Run OpenSSH:
   $ /usr/bin/sshd -f /usr/local/etc/ssh/sshd_config

8) (optional) Make sure PAM support is disabled for other OpenSSH instances
   running on the same machine, as they would use the modules as well.


OpenLDAP
--------

1) Install OpenLDAP.

2) Perform the following steps:
   $ rm -f /etc/openldap/slapd.conf
   $ mkdir '/var/lib/openldap/dc=ssh,dc=hq'
   $ mv /var/lib/openldap/openldap-data/DB_CONFIG.example \
     /var/lib/openldap/dc\=ssh\,dc\=hq/DB_CONFIG
   $ rm -rf /var/lib/openldap/openldap-data/
   $ mkdir /run/openldap

3) Create new suffix:
   $ slapadd -l samples/slapd.ldif -F /etc/openldap/slapd.d/ -n0 

4) Start OpenLDAP server:
   $ /usr/bin/slapd

5) Create initial directory structure:
   $ ldapadd -h localhost -p 389 -D cn=directory_manager,dc=ssh,dc=hq \
     -w test123 -f samples/pam_openssh_x509_test_initial.ldif

   DIT layout:
     dn: dc=ssh,dc=hq
     dn: ou=groups,dc=ssh,dc=hq
     dn: ou=people,dc=ssh,dc=hq

   The groups tree will hold objects that represent the OpenSSH servers
   whereas the person tree holds the person objects including their x509
   certificates.

6) Add user 'pox509-test-user' with x509 certificate to person tree:
   $ ldapadd -h localhost -p 389 -D cn=directory_manager,dc=ssh,dc=hq \
     -w test123 -f samples/pam_openssh_x509_test_add_user.ldif

7) Add OpenSSH server with identifier 'pox509-test-server' to groups tree:
   $ ldapadd -h localhost -p 389 -D cn=directory_manager,dc=ssh,dc=hq \
     -w test123 -f samples/pam_openssh_x509_test_add_server.ldif

8) Grant user 'pox509-test-user' access to OpenSSH server with the
   identifier 'pox509-test-server':
   $ ldapmodify -h localhost -p 389 -D cn=directory_manager,dc=ssh,dc=hq \
     -w test123 -f samples/pam_openssh_x509_test_authorize_user.ldif

9) Check LDAP content:
   $ ldapsearch -LLL -h localhost -p 389 -D cn=directory_manager,dc=ssh,dc=hq \
     -w test123 -b dc=ssh,dc=hq objectclass=*

   Expected output:
     dn: dc=ssh,dc=hq
     objectClass: top
     objectClass: dcObject
     objectClass: organization
     dc: ssh
     o: ssh headquarter

     dn: ou=people,dc=ssh,dc=hq
     objectClass: top
     objectClass: organizationalUnit
     ou: people

     dn: ou=groups,dc=ssh,dc=hq
     objectClass: top
     objectClass: organizationalUnit
     ou: groups
     
     dn: uid=pox509-test-user,ou=people,dc=ssh,dc=hq
     objectClass: top
     objectClass: person
     objectClass: organizationalPerson
     objectClass: inetOrgPerson
     uid: pox509-test-user
     givenName: pox509-test-user
     sn: pox509-test-user
     cn: pox509-test-user
     userCertificate;binary:: MIIC+...<omitted>   

     dn: cn=pox509-test-server,ou=groups,dc=ssh,dc=hq
     objectClass: top
     objectClass: groupOfNames
     cn: pox509-test-server
     description: pox509-test-server
     member: uid=__LAST_MAN_STANDING__
     member: uid=pox509-test-user,ou=people,dc=ssh,dc=hq

   $ ldapsearch -LLL -h localhost -p 389 -D cn=directory_manager,dc=ssh,dc=hq \
     -w test123 -b ou=people,dc=ssh,dc=hq uid=pox509-test-user memberOf

   Expected output:
     dn: uid=pox509-test-user,ou=people,dc=ssh,dc=hq
     memberOf: cn=pox509-test-server,ou=groups,dc=ssh,dc=hq

pam_openssh_x509
----------------

1) Build and install modules:
   $ ./configure --libdir=/lib/security --disable-dependency-tracking
   $ make
   $ make check
   $ sudo make install

2) Copy pam_openssh_x509 configuration file:
   $ cp samples/pam_openssh_x509.conf /usr/local/etc/ssh/

3) Copy PAM configuration:
   $ cp -i samples/sshd /etc/pam.d/


PuTTY-CAC
---------

Connect to the OpenSSH server using the private key in 10-ee_user_1_key.pem.
In production, use the private key inside the Smartcard for signing.


Trusted CA's store
------------------

1) Create directory where trusted CA's shall be kept:
   $ mkdir /usr/local/etc/ssh/cacerts

2) Copy whole CA trust chain:
   $ cp samples/00-ca_root_cert.pem /usr/local/etc/ssh/cacerts
   $ cp samples/01-ca_int_user_cert.pem /usr/local/etc/ssh/cacerts 

3) Create symlink hashes:
   $ c_rehash /usr/local/etc/ssh/cacerts


Overview
--------

Log files:
   /var/log/ssh/sshd_5580.log
   /var/log/ssh/pam_openssh_x509.log
   /var/log/slapd/slapd.log

Keystore:
   /usr/local/etc/ssh/keystore/

Configurations:
   /usr/local/etc/ssh/sshd_config
   /usr/local/etc/ssh/pam_openssh_x509.conf
   /etc/pam.d/sshd
   /etc/syslog-ng/syslog-ng.conf

#EOF