OATH-LDAP

1. Architecture
2. Models
3. Secure Enrollment
   1. Objectives
   2. Process
4. Bulk Enrollment
   1. Operational and security considerations
   2. Prerequisites
   3. Process
   4. Using oath-ldap-tool

Architecture

slapd

The OpenLDAP server implementation (see also slapd(8)

back-sock

slapd backend also useable as overlay which sends some LDAP requests to an external demon via Unix domain socket (see also slapd-sock(5))

OTP validator

The component validating the OTP values which runs on a slapd provider. It is the only component which has access to clear-text user password and OATH shared secret and updates the HOTP counter. Does not need any IP network access.

bind proxy

This component runs on a slapd consumers, which are by design read-only, and relays LDAP simple bind requests to one of several slapd providers.

web browser

Normal web browser used by the OTP admin to access the enrollment web app.

enrollment web app

A simple web application for resetting OATH token device entries to start enrollment

enrollment client

A hardened device where you plug in the OATH hardware token (e.g. Yubikey) to be initialized. Especially users shall not enter their normal password at this device.

LDAP client

Any LDAP client software which checks user's password and OTP by sending a LDAP simple bind request.

Models

• A person is not an user account!
• When an OTP token is physically handed out to a person the owner attribute (or similar) in the oathToken entry is set to register the device for its owner (see also enrollment process).
• Each account may be associated with an oathToken to force two-factor authentication for this particular user account.

Secure Enrollment

Objectives

• The shared secret (seed) and the user's password shall not be present in clear at the same time on any system (except in the small external OTP validator demon).
• The shared secret shall never be displayed on screen (QR code enrollment is considered harmful).
• Pre-configured shared secrets on devices shall not be used.
• The OTP admin shall not be able to initialize a token for a user.
• The user shall not be able to initialize a token without the help of a OTP admin.
• True randomness of shared keys must be ensured.

Process

• The user requests a OATH token (reset) by personally asking an OTP admin. Typically both meet in person.
• Only for first time OTP users or if an additional device is needed:
  • The OTP admin adds a new OATH token device entry and registers the person entry of the user (not the account!) as owner of the device.
  • OTP admin hands out the device to the user.
• The OTP admin resets the OATH token device entry using the OATH enrollment application.
• The OATH enrollment application...
  • generates a random enrollment password for the OATH token which is only valid for a couple of minutes.
  • sends the first part of the enrollment password via e-mail to the user and displays the second part to the OTP admin.
• OTP admin hands out the second part of the random enrollment password and a special enrollment hardware (laptop, or similar) to the user.
• The user starts the enrollment hardware. An enrollment software is automatically started.
• The user plugs in the OATH token into the enrollment hardware and enters the first and second part of the enrollment password. When resetting an formerly initialized OATH token the user also enters the token configuration code.
• The enrollment software...
  • binds to the LDAP server as token entry with the enrollment password.
  • retrieves the effective OATH token parameters (policy) including the master public key from the LDAP server.
  • generates a new random OATH shared secret and stores it in the token device.
  • encrypts OATH shared secret with the master public key.
  • stores the encrypted OATH shared secret into the OATH token device entry via LDAP.
• The user plugs off the OATH token from the enrollment hardware.
• The user returns the enrollment hardware to the OTP admin.
• The user starts using the OATH token.

Bulk Enrollment Process

In some situations it may be required to ship pre-keyed token devices, e.g. during an initial rollout.

Operational and security considerations

• In general it is highly recommended to follow the secure enrollment process.
  Thus you should write down a very clear rationale why it is not possible in your situation and why you have to use bulk enrollment instead.
• The bulk enrollment must be conducted by fully trusted and educated personnel!
• The bulk enrollment must be conducted in a secure environment:
  • Use dedicated, freshly installed computers.
  • The system used for key-generation (ykinit) must have sufficient entropy for the random number generator.
  • Lock the office when absent.
  • Do not use modified software.
• The pre-keyed token devices have to be shipped to the users in secure envelopes! Encourage users to immediately report damage of envelopes.
• Bear in mind that shipping is generally a security risk!
• Note that shipping to other countries can be a tricky logistic challenge. Make yourself familiar with customs regulations, especially those for cryptographic devices. In many cases it can be easier to let users buy new devices locally and work from there.
• Prepare decent documentation with all necessary details for your auditor, preferrably before conducting the bulk enrollment.

Prerequisites

• Requires oath-ldap-tool 1.3.0 or newer.
• Prepare a list of owner IDs to register token devices with.

Process

Steps done with oath-ldap-tool either sequentially on one system or as a pipeline with three systems:

• ykreset:
  Remove pre-configured slots from brand-new Yubikeys tokens.
• ykadd:
  The tokens are added to OATH-LDAP servers and associated with a owner (person).
  After that store the tokens in a separate box for freshly added tokens. Ownership is saved in OATH-LDAP, no need to keep track of token ownership externally.
• ykinit:
  The shared secrets are generated and stored in OATH-LDAP server and the hardware tokens.
  After that store the tokens in a separate box for ready-to-ship tokens.
• ykcheck:
  Check whether generating correct OTP values works and display token owner (person).
  After that put token into envelope with personal name / address of token owner.

Using oath-ldap-tool

The relevant sub-commands can be invoked with argument -c or --continue for continuous operation interactively running until you hit Ctrl+C key combination.

For all commands below replace "..." with the following command-line arguments:

    --continue --ca-certs /path/to/trusted-cacerts.pem --ldap-url ldaps:/// --admin-dn 

Example for Æ-DIR with search base ou=ae-dir:

    --continue \
    --ca-certs /path/to/trusted-cacerts.pem \
    --ldap-url ldaps://ae-dir-p1.example.com/cn=otp,ou=ae-dir \
    --admin-dn uid=xkcd,ou=ae-dir

ykreset

Sub-command ykreset is used to remove the pre-configured slots on brand-new Yubikey devices.

oath-ldap-tool ykreset -f -c -o ""

ykadd

Sub-command ykadd is used to add OATH token entries based on a LDIF template file. Without argument -o or --owner it will interactively ask for an owner ID.

oath-ldap-tool ykadd ... --ldif-template /path/to/aedir-hotp-yubikey-template.ldif

See also: Examples for aedir-hotp-yubikey-template.ldif

ykinit

Sub-command ykinit is used to generate a shared secret, send it to OATH-LDAP server and store it into the Yubikey. Furthermore the Yubikey device is proteced with a randomly generated access code which is displayed in the output. The access code is stored in the token entry encrypted with the same key like the shared secret.

oath-ldap-tool ykinit ...

ykcheck

Sub-command ykinit is used to test whether generating correct OTP values correctly works and if these values are valid. Furthermore contact information of owner is displayed which can be used for shipping the device to the right owner.

oath-ldap-tool ykcheck ...