xref: /freebsd/contrib/pam-krb5/tests/fakepam/README (revision bf6873c5786e333d679a7838d28812febf479a8a)

                          PAM Testing Framework

Overview

    The files in this directory provide a shim PAM library that's used for
    testing and a test framework used to exercise a PAM module.

    This library and its include files define the minimum amount
    of the PAM module interface so that PAM modules can be tested without
    such problems as needing configuration files in /etc/pam.d or needing
    changes to the system configuration to run a testing PAM module
    instead of the normal system PAM modules.

    The goal of this library is that all PAM code should be able to be
    left unchanged and the code just linked with the fakepam library
    rather than the regular PAM library.  The testing code can then call
    pam_start and pam_end as defined in the fakepam/pam.h header file and
    inspect internal PAM state as needed.

    The library also provides an interface to exercise a PAM module via an
    interaction script, so that as much of the testing process as possible
    is moved into simple text files instead of C code.  That test script
    format supports specifying the PAM configuration, the PAM interfaces
    to run, the expected prompts and replies, and the expected log
    messages.  That interface is defined in fakepam/script.h.

Fake PAM Library

    Unfortunately, the standard PAM library for most operating systems
    does not provide a reasonable testing framework.  The primary problem
    is configuration: the PAM library usually hard-codes a configuration
    location such as /etc/pam.conf or /etc/pam.d/<application>.  But there
    are other problems as well, such as capturing logging rather than
    having it go to syslog and inspecting PAM internal state to make sure
    that it's updated properly by the module.

    This library implements some of the same API as the system PAM library
    and uses the system PAM library headers, but the underlying
    implementation does not call the system PAM library or dynamically
    load modules.  Instead, it's meant to be linked into a single
    executable along with the implementation of a PAM module.  It does not
    provide most of the application-level PAM interfaces (so one cannot
    link a PAM-using application against it), just the interfaces called
    by a module.  The caller of the library can then call the module API
    (such as pam_sm_authenticate) directly.

    All of the internal state maintained by the PAM library is made
    available to the test program linked with this library.  See
    fakepam/pam.h for the data structures.  This allows verification that
    the PAM module is setting the internal PAM state properly.

  User Handling

    In order to write good test suites, one often has to be able to
    authenticate as a variety of users, but PAM modules may expect the
    authenticating user to exist on the system.  The fakepam library
    provides a pam_modutil_getpwnam (if available) or a getpwnam
    implementation that returns information for a single user (and user
    unknown for everyone else).  To set the information for the one valid
    user, call the pam_set_pwd function and provide a struct passwd that
    will be returned by pam_modutil_getpwnam.

    The fakepam library also provides a replacement krb5_kuserok function
    for testing PAM modules that use Kerberos.  This source file should
    only be included in packages that are building with Kerberos.  It
    implements the same functionality as the default krb5_kuserok
    function, but looks for .k5login in the home directory configured by
    the test framework instead of using getpwnam.

    Only those two functions are intercepted, so if the module looks up
    users in other ways, it may still bypass the fakepam library and look
    at system users.

  Output Handling

    The fakepam library intercepts the PAM functions that would normally
    log to syslog and instead accumulates the output in a static string
    variable.  To retrieve the logging output so far, call pam_output,
    which returns a struct of all the output strings up to that point and
    resets the accumulated output.

Scripted PAM Testing

    Also provided as part of the fakepam library is a test framework for
    testing PAM modules.  This test framework allows most of the testing
    process to be encapsulated in a text configuration file per test,
    rather than in a tedious set of checks and calls written in C.

  Test API

    The basic test API is to call either run_script (to run a single test
    script) or run_script_dir (to run all scripts in a particular
    directory).  Both take a configuration struct that controls how the
    PAM library is set up and called.

    That configuration struct takes the following elements:

    user
        The user as which to authenticate, passed into pam_start and also
        substituted for the %u escape.  This should match the user whose
        home directory information is configured using pam_set_pwd if that
        function is in use.

    password
        Only used for the %p escape.  This is not used to set the
        authentication token in the PAM library (see authtok below).

    newpass
        Only used for the %n escape.

    extra
        An array of up to 10 additional strings used by the %0 through %9
        escapes when parsing the configuration file, as discussed below.

    authtok
        Sets the default value of the PAM_AUTHTOK data item.  This will be
        set immediately after initializing the PAM library and before
        calling any PAM module functions.

    authtok
        Like authtok, but for the PAM_OLDAUTHTOK data item.

    callback
        This, and the associated data element, specifies a callback that's
        called at the end of processing of the script before calling
        pam_end.  This can be used to inspect and verify the internal
        state of PAM.  The data element is an opaque pointer passed into
        the callback.

  Test Script Basic Format

    Test scripts are composed of one or more sections.  Each section
    begins with:

        [<section>]

    starting in column 1, where <section> is the name of the section.  The
    valid section types and the format of their contents are described
    below.

    Blank lines and lines starting with # are ignored.

    Several strings undergo %-escape expansion as mentioned below.  For
    any such string, the following escapes are supported:

        %i      Current UID (not the UID of the target user)
        %n      New password
        %p      Password
        %u      Username
        %0      extra[0]
        ...
        %9      extra[9]

    All of these are set in the script_config struct.

    Regular expression matching is supported for output lines and for
    prompts.  To mark an expected prompt or output line as a regular
    expression, it must begin and end with a slash (/).  Slashes inside
    the regular expression do not need to be escaped.  If regular
    expression support is not available in the C library, those matching
    tests will be skipped.

  The [options] Section

    The [options] section contains the PAM configuration that will be
    passed to the module.  These are the options that are normally listed
    in the PAM configuration file after the name of the module.  The
    syntax of this section is one or more lines of the form:

        <group> = <options>

    where <group> is one of "account", "auth", "password", or "session".
    The options are space-delimited and may be either option names or
    option=value pairs.

  The [run] Section

    The [run] section specifies what PAM interfaces to call.  It consists
    of one or more lines in the format:

        <call> = <status>

    where <call> is the PAM call to make and <status> is the status code
    that it should return.  <call> is one of the PAM module interface
    functions without the leading "pam_sm_", so one of "acct_mgmt",
    "authenticate", "setcred", "chauthtok", "open_session", or
    "close_session".  The return status is one of the PAM constants
    defined for return status, such as PAM_IGNORE or PAM_SUCCESS.  The
    test framework will ensure that the PAM call returns the appropriate
    status.

    The <call> may be optionally followed by an open parentheses and then
    a list of flags separated by |, or syntactically:

        <call>(<flag>|<flag>|...) = <status>

    In this form, rather than passing a flags value of 0 to the PAM call,
    the test framework will pass the combination of the provided flags.
    The flags are PAM constants without the leading PAM_, so (for example)
    DELETE_CRED, ESTABLISH_CRED, REFRESH_CRED, or REINITIALIZE_CRED for
    the "setcred" call.

    As a special case, <call> may be "end" to specify flags to pass to the
    pam_end call (such as PAM_DATA_SILENT).

  The [end] Section

    The [end] section defines how to call pam_end.  It currently takes
    only one setting, flags, the syntax of which is:

        flags = <flag>|<flag>

    This allows PAM_DATA_SILENT or other flags to be passed to pam_end
    when running the test script.

  The [output] Section

    The [output] section defines the logging output expected from the
    module.  It consists of zero or more lines in the format:

        <priority> <output>
        <priority> /<regex>/

    where <priority> is a syslog priority and <output> is the remaining
    output or a regular expression to match against the output.  Valid
    values for <priority> are DEBUG, INFO, NOTICE, ERR, and CRIT.
    <output> and <regex> may contain spaces and undergoes %-escape
    expansion.

    The replacement values are taken from the script_config struct passed
    as a parameter to run_script or run_script_dir.

    If the [output] section is missing entirely, the test framework will
    expect there to be no logging output from the PAM module.

    This defines the logging output, not the prompts returned through the
    conversation function.  For that, see the next section.

  The [prompts] Section

    The [prompts] section defines the prompts that the PAM module is
    expected to send via the conversation function, and the responses that
    the test harness will send back (if any).  This consists of zero or
    more lines in one of the following formats:

        <type> = <prompt>
        <type> = /<prompt>/
        <type> = <prompt>|<response>
        <type> = /<prompt>/|<response>

    The <type> is the style of prompt, chosen from "echo_off", "echo_on",
    "error_msg", and "info".  The <prompt> is the actual prompt sent and
    undergoes %-escape expansion.  It may be enclosed in slashes (/) to
    indicate that it's a regular expression instead of literal text.  The
    <response> if present (and its presence is signaled by the |
    character) contains the response sent back by the test framework and
    also undergoes %-escape expansion.  The response starts with the final
    | character on the line, so <prompt> regular expressions may freely
    use | inside the regular expression.

    If the [prompts] section is present and empty, the test harness will
    check that the PAM module does not send any prompts.  If the [prompts]
    section is absent entirely, the conversation function passed to the
    PAM module will be NULL.

License

    This file is part of the documentation of rra-c-util, which can be
    found at <https://www.eyrie.org/~eagle/software/rra-c-util/>.

    Copyright 2011-2012, 2020-2021 Russ Allbery <eagle@eyrie.org>

    Copying and distribution of this file, with or without modification,
    are permitted in any medium without royalty provided the copyright
    notice and this notice are preserved.  This file is offered as-is,
    without any warranty.