CONTENTS
==========
I.	INTRO
II.	IMPLEMENTATION DETAILS
III.	REQUIREMENTS
IV.	INSTALLATION & CONFIGURATION
V.	SSHD CONFIGURATION
VI.	LDAP CONFIGURATION
VII.	THE sshPublicKey OBJECT CLASS
VIII.	OS SPECIFIC NOTES

I. INTRO
---------

Using the AuthorizedKeysCommand configuration keyword, sshd can be
configured to requests users' public keys from external programs run
on the local host for public-key authentication (see sshd_config(5)).

The getpk tools, getpk(8) and getpkd(8), are a pair of small
client/server utilities that run on the local host to serve requests
from sshd(8) (or other programs) for public keys stored in an LDAP
directory entry.

The primary design requirement was to maintain state information on
the LDAP servers' availability, obviating any dependencies on layer-3
proxies (e.g. VIPs) between clients running sshd(8) and clusters of
redundant of LDAP servers.

Similarly to other common authentication management tools (nslcd,
saslauthd, sssd) the getpkd(8) daemon can be configured with a list of
LDAP servers, and it provides failover and failback functionality as
their availability status changes.

The getpk tools have been tested successfully on OpenBSD 6.0 and 6.1,
FreeBSD 11.0, Debian Linux 8.7, and Centos 7.3.  See section VIII 'OS
SPECIFIC NOTES' for OS specific idiosyncrasies. 


II. IMPLEMENTATION DETAILS
----------------------------

getpkd(8) is a server daemon that listens on the local, unix domain
socket at /tmp/getpkd/getpkd.sock.  A client request consists of a
single username.  A server reply consists of one or more lines of
'authorized keys' output retrieved from the LDAP directory entry for
the given username.

For public key authentication using sshd(8), public keys in the LDAP
entry must be stored in the authorized_keys format as described in the
section AUTHORIZED_KEYS in the sshd(8) manpage.

The client program, getpk(8), is a simple command-line tool that can
be used by programs that can't communicate directly with the getpkd(8)
daemon.  It takes a username as its only argument and initiates a
client request to getpkd(8).  It writes the server's reply
unmodified to STDOUT.

The following diagram shows the data flow between sshd(8), the getpk
tools and a host running OpenLDAP's slapd server daemon.  

 ---------------------------------------------------
|                 CLIENT HOST                       | 
|                                                   |       ---------------
|  ------           -------           --------      |      |  LDAP server  |
| | sshd | <-----> | getpk | <-----> |        |     |      |               |
|  ------           -------          |        |     |      |     -------   |
|                   -------          | getpkd | <---|------|--> | slapd |  | 
|                  |  foo  | <-----> |        |     |      |     -------   |
|                   -------          |        |     |       ---------------
|                                     --------      |
|                                                   |
 ---------------------------------------------------

Both getpk(8) and getpkd(8) run on the same host as the sshd server.  In
this example, sshd(8) executes getpk(8) with the username to
authenticate as the only arg.  getpk(8) initiates a request to getpkd(8)
which fetches the public key for that user from the LDAP server.
Results of the query are passed back to getpk(8) unmodified which in
turn passes them back to sshd(8). 

The program `foo' is an example of an application written to talk
directly to getpkd(8).

The primary purpose of the server daemon, getpkd(8), is to obviate any
need for layer-3 proxies (e.g., VIPs) between the client and the LDAP
servers.  getpkd(8) maintains state information about the availability
of the LDAP servers it has been configured to query and ensures
redundancy through failover/failback mechanisms when the status of
servers' availability changes.

getpkd(8) expects public keys to be a value assigned to the `authkey'
attribute in the user's LDAP directory entry.  The getpk tools include
an LDAP schema that defines the sshPublicKey object class with the
authkey attribute.

See the section VI 'LDAP CONFIGURATION' for installing the schema on
OpenLDAP's slapd server.  See section VII 'THE sshPublicKey OBJECT
CLASS' for additional details.

III. REQUIREMENTS
-----------------

1.   The getpkd(8) daemon requires libldap and related libraries from the
     OpenLDAP project (http://www.openldap.org).  Your system most likely
     has a package that installs these libraries.

     For Debian 8.7, if TLS functionality is desired then the OpenLDAP 
     libraries cannot be linked to the GnuTLS library.  See section VIII 
     'OS SPECIFIC NOTES'.

2.   To compile the getpkd tools, gcc and GNU make are required.  Also,
     the header file `ldap.h' must exist.  Depending on your target system,
     this may require installing an openldap development package.

3.   getpkd(8) runs as the unprivileged user `getpk'.  It is therefore
     necessary to create a user and group with this name on your target
     system before installation.

     For security reasons, the getpk user's shell should be set to
     /sbin/nologin and the home directory to /var/empty (or whatever
     equivalents exist on your system for unprivileged user accounts).

4.   Public keys in the LDAP directory must be assigned to the
     `authkey' attribute.  Use the included sshPublicKey.schema or write a
     schema definition that defines an object class with this attribute
     name.  See the section VI 'LDAP CONFIGURATION'.

5.   sshd(8) requires owner and group settings of root:root (or
     root:wheel) on the directory where getpk(8) is installed.  See section
     VIII 'OS SPECIFIC NOTES' for how this requirement affects installation
     on Debian systems. 


IV. INSTALLATION & CONFIGURATION
----------------------------------

The getpk tools have been successfully compiled on OpenBSD 6.0 and
6.1, FreeBSD 11, Debian Linux 8.7 and Centos 7.3.

If your system's linker is unable to find the libraries modify the
`libs' variable in the Makefile to point to the location where the
ldap libraries are installed.

After satisfying the requirements defined in section II, change to the
src/ directory and run

    make all
     
and as a privileged user 

    make install

(on BSDs, use gmake);

If all goes well, the result will be 2 new binaries.  On Centos/BSDs
these are:

    /usr/local/sbin/getpk	
    /usr/local/sbin/getpkd

on Debian:
    /opt/getpktools/getpk
    /opt/getpktools/getpkd

(Section VIII of this document describes the rationale for the install
location on Debian systems.) 

A config file is automatically installed as:
    /etc/getpkd.conf

These manpages are placed under /usr/local/
    getpk(8)
    getpkd(8)
    getpkd.conf(5)

See the getpkd.conf(5) man page for details on configuring getpkd(8). 


V. SSHD CONFIGURATION
-----------------------

sshd(8) must be configured to use getpk(8) to obtain public keys (see
sshd_config(5)).

For BSDs/RHEL systems, add these settings to sshd_config:

     AuthorizedKeysCommand	/usr/local/sbin/getpk
     AuthorizedKeysCommandUser	getpk

On Debian, the value for AuthorizedKeysCommand should be set to
/opt/getpktools/getpk.

Also, confirm that sshd(8) is configured to use public key
authentication (it's turned on by default) and then restart sshd(8). 


VI. LDAP CONFIGURATION
----------------------
getpkd(8) searches the LDAP directory for a DN with the uid attribute
that matches the username being queried.  This typically requires LDAP
entries to use either the posixAccount or inetOrgPerson object class. 

Public keys are expected to be a value assigned to the authkey
attribute in a user's LDAP entry.  The file sshPublicKey.schema
defines the sshPublicKey object class with the authkey attribute.  The
authkey attribute may hold multiple keys. 

The format of the key should conform to the authorized_keys format as
described in the manpage for sshd(8). 

To use the sshPublicKey object class with OpenLDAP's slapd server,
copy the file sshPublicKey.schema to OpenLDAP's schema directory and
configure slapd to include the new object class (see slapd.conf(5)). 

See the next section for more information on the sshPublicKey object
class. 

VII. THE sshPublicKey OBJECT CLASS
--------------------------------

The sshPublicKey object class provided with getpk tools defines 4 attributes:

authkey         - a value conforming to the authorized_keys format as described
                  in the manpage for sshd(8)
fingerprint 	- fingerprint of the key
keytype         - e.g., `ecdsa-sha2-nistp256', `ecdsa-sha2-nistp384',
                 `ecdsa-sha2-nistp521', `ssh-ed25519', `ssh-dss' or `ssh-rsa'
keylen		- number of bits in the key

All attributes may contain multiple values.  Note however that there is
no inherent way for an LDAP operation to associate multiple values of
one attribute to values in another attribute - e.g., if the authkey
attribute contains 2 keys, and the fingerprint attribute contains 2
different values, there is no way for an LDAP search operation to map
the keys to their corresponding fingerprints.  The program initiating
the request must determine those associations based on the results of
the LDAP search operation (if possible).

At this time, getpkd(8) only queries the LDAP server for the authkey
attribute's values.  It is the only value required for OpenSSH public
key authentication.

VIII. OS SPECIFIC NOTES
-------------------------
OpenBSD
-------
The getpk tools use pledge(2) to restrict their operations.
Therefore, they will not compile on OpenBSD releases prior to 5.9. 

FreeBSD
--------
(none)

CentOS
-------
(none)

Debian Linux
-------------
1.   sshd(8) requires that the program specified by the 
     'AuthorizedKeysCommand' be in a directory owned by root with a group
      owner id of `0' (typically 'root' or 'wheel').

     Debian Linux sets group ownership of /usr/local/sbin to 'staff' 
     (gid 50), therefore, in order to install the getpk tool into a 
     working location on these systems, the Makefile creates the directory
     /opt/getpktools with the requisite permissions and installs the
     binaries there.  The binaries may be moved to any other location in
     the filesystem that meets sshd(8)'s requirements for owner/group
     settings.

2.   The OpenLDAP libraries packaged for Debian are linked with the GnuTLS 
     library for TLS operations.  The version of this library installed 
     on Debian 8.7 (and earlier verions?) has initialization functions 
     that break some security features and cause getpkd to fail when 
     configured to use TLS.

     To use TLS with getpkd, rebuild the LDAP libraries, configuring support
     for TLS using some other library (libssl has been tested successfully).
     By default, the Makefile expects to find the LDAP libraries in 
     /usr/local/lib