Contents of this file
---------------------

 * Introduction
 * Operating model
 * Module stack
 * Installation
 * Contribute
 * Bug report / Feature request
 * License
 * Contact


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

pam_openssh_x509 is a collection of PAM modules that paired with a PKI provides
a fully automated solution for the management of OpenSSH keys.

pam_openssh_x509 enables you to...

 * Reduce your costs yet improving security by using synergies of already
   established processes.
 * Centrally manage access to OpenSSH servers.
 * Raise the security level of OpenSSH keys to the same as x509 certificates.
 * Highly protect private keys by using Smartcard technology.
 * Periodically update key material without manual interaction.
 * Revoke keys in a standard way.
 * Gain back control of the key creation process.
 * Be completely independent of changes to OpenSSH itself by using a long
   established and supported standard interface.
 * Simply implement two factor authentication.
 * Adopt to different environments by the usage of policies.
 * Reveal the theft of private keys and make it hard to duplicate them.
 * KEEP IT SIMPLE \o/

For more information on how to make the most out of pam_openssh_x509 see the
next section.


Operating model
---------------

The idea behind pam_openssh_x509 is to make managed x509 certificates
accessible for OpenSSH public key authentication. Contrary to other approaches
the source code of OpenSSH remains untouched, making it relatively independent
from changes to OpenSSH. It also supports components usually found in larger
enterprises, creating an integrated solution for the OpenSSH key management.
Therefore it circumvents the installation and maintenance of an extensive
software layer for managing OpenSSH key material. Yet, it raises the security
level of the keys and reduces costs.

The operating model consists of the following components:

 * PKI
 * LDAP server
 * Smartcard technology (optional)
 * SSH client supporting Smartcards (e.g. PuTTY-CAC) (optional)
 * pam_openssh_x509


The tasks of the components can be described as follows:

The PKI...

 * Is responsible for the management of the lifecycle of x509 certificates.
 * Creates the private key in a secure manner. E.g. it makes sure that
   private keys will be created on the Smartcard using a known key creation
   procedure.
 * Re-keys in regular intervals.
 * Maintains processes for key revocation.
 * Publishes x509 certificates to the LDAP server.

The LDAP server...

 * Stores all x509 certificates.
 * Maintains a list of all OpenSSH servers.
 * Holds access permissions for the OpenSSH servers.

The Smartcard...

 * Generates and stores the private key.
 * Is used for authentication.

The SSH client supporting Smartcards...

 * Will use the private key inside the Smartcard to create the digital
   signature used for authentication instead of a private key kept inside the
   filesystem


For the usage of pam_openssh_x509 the PKI has to store the x509 certificates at
the user object in the LDAP server. Every OpenSSH server will be represented as
a group in a distinct tree in the LDAP server. Access permission to an OpenSSH
server is then granted through a group membership.

pam_openssh_x509 makes sure that the public key of the x509 certificate is
synchronized to the server. It does so only after access permissions have been
checked and the certificate has been validated.


Module stack
------------

pam_openssh_x509 is made up of the following modules:

pam_openssh_x509_base.so

 * Checks access permissions through LDAP groups.
 * Validates x509 certificate.
 * Converts the public key to into the OpenSSH key format.
 * Creates and updates the data transfer object passed to downstream modules
   with all determined information.

pam_openssh_x509_audit.so (optional)

 * Logs information from the data transfer object.

pam_openssh_x509_validate.so

 * Keeps the policy that evaluates the data transfer object and updates the
   authorized_keys file.


The base module collects all the information needed to synchronize keys and
grant or revoke server access. All data is stored in a data transfer object
that is made accessible for downstream modules.

The audit module is a passive component that only logs the content of the data
transfer object.

The validation module performs the actual modification of the authorized_keys
file. It can be adjusted for differing environments. For example, while an
expired user certificate may not cause any trouble in a testing environment, it
would certainly gain significance in production. The validation module is the
only module that has to be adjusted to individual needs.


Installation
------------

see INSTALL


Contribute
----------

You like the project and want to join? Feel free to become part of it.
Any help is highly appreciated! We're always searching for:

 * Developers
 * Code reviewers
 * Tester
 * Testing environments
 * Feature requests
 * Feedback
 * Web designers
 * ASCII art

You have other skills that might help improving the project?
Don't hesitate contacting us!


Bug report / Feature request
----------------------------

see Contact


License
-------

see COPYING / COPYING.LESSER


Contact
-------

Questions? Suggestions? Just wanna say Hi?
Reach us over the following channels:

* IRC: #pam_openssh_x509 @ freenode  or /query flix
* E-Mail: seroland86@gmail.com
* Github: https://github.com/flix-

#EOF