diff --git a/kokoro/alpine/fetch_dependencies.sh b/kokoro/alpine/fetch_dependencies.sh index 9ac650c4..136f44a0 100755 --- a/kokoro/alpine/fetch_dependencies.sh +++ b/kokoro/alpine/fetch_dependencies.sh @@ -2,5 +2,5 @@ set -e apk add --no-cache \ - alpine-sdk meson \ + alpine-sdk meson pandoc-cli \ openssl-dev glib-dev linux-pam-dev diff --git a/kokoro/rodete/fetch_dependencies.sh b/kokoro/rodete/fetch_dependencies.sh index 15833a98..bb4cef3c 100755 --- a/kokoro/rodete/fetch_dependencies.sh +++ b/kokoro/rodete/fetch_dependencies.sh @@ -4,5 +4,5 @@ set -e export DEBIAN_FRONTEND=noninteractive apt-get update apt-get install -y --no-install-recommends \ - build-essential meson pkg-config \ + build-essential meson pkg-config pandoc \ libssl-dev libglib2.0-dev libpam0g-dev libpam-wrapper libpamtest0-dev diff --git a/login/README.md b/login/README.md index ac6eb9f2..85f23147 100644 --- a/login/README.md +++ b/login/README.md @@ -55,44 +55,6 @@ This error means that `glome-login` could not figure out what service key to use. This most likely means that you have not specified a service key in the configuration file (by default `/etc/glome/config`). -# PAM module - -`pam_glome.so` library implements the PAM authentication module for the -[GLOME Login](../docs/glome-login.md) protocol. - -## Installation - -1. Install the library into the system dependent location for PAM modules - (for example `/lib/security/pam_glome.so`). -1. Enable and configure PAM module for a specific service (for example - `/etc/pam.d/login`): - -``` -auth requisite pam_glome.so -``` - -## Usage - -PAM module supports the following options: - -* `config_path=PATH` - location of the configuration file to parse (defaults to - `/etc/glome/config`) -* `key=KEY` - use hex-encoded `KEY` as the service key (defaults to key - from configuration file) -* `key_version=N` - use `N` for the service key version (defaults to key - version from configuration file) -* `prompt=PROMPT` - challenge prompt (defaults to prompt from configuration - file) -* `debug` - enable verbose logging -* `print_secrets` - enable logging of secrets (INSECURE!) -* `host_id=NAME` - use `NAME` as the host-id -* `ephemeral_key=KEY` - use hex-encoded `KEY` instead of the ephemeral - secret key (INSECURE!) - -## Troubleshooting - -PAM module uses error tags to communicate errors in the syslog messages. - # Docker Dockerfile included in the repository creates a Docker image that can be used diff --git a/login/meson.build b/login/meson.build index 96328c6b..ef9adda0 100644 --- a/login/meson.build +++ b/login/meson.build @@ -91,6 +91,18 @@ if get_option('pam-glome') install : true, install_dir : join_paths(get_option('libdir'), 'security')) + pandoc = find_program('pandoc', required : false) + if pandoc.found() + custom_target( + 'pam_glome.8', + input : 'pam.8.md', + output : 'pam_glome.8', + command : [pandoc, '--standalone', '--to', 'man', '@INPUT@'], + capture : true, + install : true, + install_dir : join_paths(get_option('mandir'), 'man8')) + endif + if get_option('tests') libpamtest = dependency('libpamtest', required : false) if libpamtest.found() diff --git a/login/pam.8.md b/login/pam.8.md new file mode 100644 index 00000000..767d6c46 --- /dev/null +++ b/login/pam.8.md @@ -0,0 +1,109 @@ +% PAM_GLOME(8) GLOME Login PAM module manual + +# NAME + +pam_glome - PAM Authentication Module for GLOME Login protocol + +# SYNOPSIS + +**pam_glome.so** [config_path=*path*] [key=*hex_key*] [key_version=*n*] +[min_authcode_len=*n*] [prompt=*message*] [debug] [host_id=*name*] +[host_id_type=*type*] [print_secrets] [ephemeral_key=*hex_key*] + +# DESCRIPTION + +The **pam_glome** module implements the client-side authentication for the +**Generic Low-Overhead Message Exchange (GLOME)** Login protocol. It provides +cryptographic challenge-response authentication mechanism that can be used to +secure serial consoles or as a second factor for standard login services. + +During the authentication process, the module displays a challenge URL. The +user then uses a GLOME-compatible client to generate an authorization code, +which they provide at the prompt. + +The module reads settings from a configuration file (`/etc/glome/config` by +default) and allows specific settings to be overridden via PAM options. + +# OPTIONS + +For all options listed below, hyphens (**-**) and underscores (**\_**) can be +used interchangeably in the parameter names. + +config_path=*path* +: Specify the location of the GLOME configuration file. + Defaults to `/etc/glome/config`. + +key=*hex_key* +: Use the provided hex-encoded string as the service key. This overrides + any key specified in the configuration file. + +key_version=*n* +: Specify the version of the service key to use. This value is embedded in the + challenge prefix to inform the server which private key to use for + authorization. + +min_authcode_len=*n* +: Enforce a minimum required length for the authorization code. The default + and minimum allowed value is 10. + +prompt=*message* +: Override the default challenge prompt displayed to the user. + +debug +: Enable more verbose log messages in syslog. + +host_id=*name* +: Set the host identifier used in the GLOME Login protocol. When unset, fully + qualified local hostname is used. If the hostname cannot be determined, it + falls back to the hardware product UUID from DMI. + +host_id_type=*type* +: Specify the type of the host identifier to use in the GLOME Login protocol. + +print_secrets +: Enable logging of secrets to syslog. **WARNING: This is insecure and + should only be used for debugging.** + +ephemeral_key=*hex_key* +: Use the provided hex-encoded string as the ephemeral secret key instead + of generating new key for each challenge. **WARNING: This is insecure and + intended for testing purposes only.** + +# MODULE TYPE PROVIDED + +Only the **auth** module type is provided. + +# RETURN VALUES + +PAM_SUCCESS +: The provided GLOME authorization code is valid for the given challenge. + +PAM_AUTH_ERR +: Authentication failed. This could be due to an incorrect GLOME authorization + code or an error was encountered. + +# EXAMPLES + +To enable GLOME authentication as a mandatory modules for the login service, +add the following line to `/etc/pam.d/login`: + +- `auth required pam_glome.so` + +To enable debug logging with a specific configuration file use: + +- `auth required pam_glome.so debug config_path=/etc/glome/custom.cfg` + +# SECURITY NOTES + +The module includes a specific check for OpenSSH "fake passwords." When OpenSSH +is configured to disallow a login (for example, via `PermitRootLogin no`), it +may provide a decoy token to the PAM stack to prevent timing attacks. +**pam_glome** detects this token using a constant-time comparison and reject +the attempt immediately. + +# SEE ALSO + +**glome-login**(1), **glome**(1). + +GLOME source code and all documentation may be downloaded from +.