pamtest(3)

NAME
pamtest - The pamtest API

SYNOPSIS

  Data Structures
struct pam_testcase
The PAM testcase struction.
struct pamtest_conv_data
This structure should be used when using run_pamtest, which uses an internal conversation function.

  Macros
#define pam_test(op, expected) { op, expected, 0, 0, { .envlist = NULL } }
Initializes a pam_tescase structure.
#define pam_test_flags(op, expected, flags) { op, expected, flags, 0, { .envlist = NULL } }
Initializes a CMUnitTest structure with additional PAM flags.

  Typedefs
typedef int(* pam_conv_fn) (int num_msg, const struct pam_message **msg, struct pam_response **resp, void *appdata_ptr)
PAM conversation function, defined in pam_conv(3)

  Enumerations
enum pamtest_err { PAMTEST_ERR_OK, PAMTEST_ERR_START, PAMTEST_ERR_CASE, PAMTEST_ERR_OP, PAMTEST_ERR_END, PAMTEST_ERR_KEEPHANDLE, PAMTEST_ERR_INTERNAL }
The return code of the pamtest function.
enum pamtest_ops { PAMTEST_AUTHENTICATE, PAMTEST_SETCRED, PAMTEST_ACCOUNT, PAMTEST_OPEN_SESSION, PAMTEST_CLOSE_SESSION, PAMTEST_CHAUTHTOK, PAMTEST_GETENVLIST = 20, PAMTEST_KEEPHANDLE }
The enum which describes the operations performed by pamtest().

  Functions
const struct pam_testcase * pamtest_failed_case (struct pam_testcase *test_cases)
Helper you can call if run_pamtest() fails.
void pamtest_free_env (char **envlist)
This frees the string array returned by the PAMTEST_GETENVLIST test.
const char * pamtest_strerror (enum pamtest_err perr)
return a string representation of libpamtest error code.
enum pamtest_err run_pamtest (const char *service, const char *user, struct pamtest_conv_data *conv_data, struct pam_testcase test_cases[], pam_handle_t *pam_handle)
Run libpamtest test cases.
enum pamtest_err run_pamtest_conv (const char *service, const char *user, pam_conv_fn conv_fn, void *conv_userdata, struct pam_testcase test_cases[], pam_handle_t *pam_handle)
Run libpamtest test cases.

Detailed Description

Typedef Documentation

  typedef int(* pam_conv_fn) (int num_msg, const struct pam_message **msg, struct pam_response **resp, void *appdata_ptr)

PAM conversation function, defined in pam_conv(3) This is just a typedef to use in our declarations. See man pam_conv(3) for more details.

Enumeration Type Documentation

  enum pamtest_err

The return code of the pamtest function.

Enumerator

PAMTEST_ERR_OK
    Testcases returns correspond with input.

PAMTEST_ERR_START
    pam_start() failed

PAMTEST_ERR_CASE
    A testcase failed. Use pamtest_failed_case

PAMTEST_ERR_OP
    Could not run a test case.

PAMTEST_ERR_END
    pam_end failed

PAMTEST_ERR_KEEPHANDLE
    Handled internally.

PAMTEST_ERR_INTERNAL
    Internal error - bad input or similar.

  enum pamtest_ops

The enum which describes the operations performed by pamtest().

Enumerator

PAMTEST_AUTHENTICATE
    run pam_authenticate to authenticate the account

PAMTEST_SETCRED
    run pam_setcred() to establish/delete user credentials

PAMTEST_ACCOUNT
    run pam_acct_mgmt() to validate the PAM account

PAMTEST_OPEN_SESSION
    run pam_open_session() to start a PAM session

PAMTEST_CLOSE_SESSION
    run pam_close_session() to end a PAM session

PAMTEST_CHAUTHTOK
    run pam_chauthtok() to update the authentication token

PAMTEST_GETENVLIST
    If this option is set the test will call pam_getenvlist() and copy the environment into case_out.envlist.

PAMTEST_KEEPHANDLE
    This will prevent calling pam_end() and will just return the PAM handle in case_out.ph.

Function Documentation

  const struct pam_testcase * pamtest_failed_case (struct pam_testcase * test_cases)

Helper you can call if run_pamtest() fails. If PAMTEST_ERR_CASE is returned by run_pamtest() you should call this function get a pointer to the failed test case.

Parameters
    test_cases The array of tests.

Returns
    a pointer to the array of test_cases[] that corresponds to the first test case where the expected error code doesn't match the real error code.

  void pamtest_free_env (char ** envlist)

This frees the string array returned by the PAMTEST_GETENVLIST test.

Parameters
    envlist The array to free.

  const char * pamtest_strerror (enum pamtest_err perr)

return a string representation of libpamtest error code.

Parameters
    perr libpamtest error code

Returns
    String representation of the perr argument. Never returns NULL.

References PAMTEST_ERR_CASE, PAMTEST_ERR_END, PAMTEST_ERR_INTERNAL, PAMTEST_ERR_KEEPHANDLE, PAMTEST_ERR_OK, PAMTEST_ERR_OP, and PAMTEST_ERR_START.

  enum pamtest_err run_pamtest (const char * service, const char * user, struct pamtest_conv_data * conv_data, struct pam_testcase test_cases[], pam_handle_t * pam_handle)

Run libpamtest test cases. This is using the default libpamtest conversation function.

Parameters
    service The PAM service to use in the conversation
    user The user to run conversation as
    conv_data Test-specific conversation data
    test_cases List of libpamtest test cases. Must end with PAMTEST_CASE_SENTINEL
    pam_handle The PAM handle to use to run the tests

int main(void) {
    int rc;
    const struct pam_testcase tests[] = {
        pam_test(PAM_AUTHENTICATE, PAM_SUCCESS),
    };
    rc = run_pamtest(tests, NULL, NULL);
    return rc;
}

Returns
    PAMTEST_ERR_OK on success, else the error code matching the failure.

  enum pamtest_err run_pamtest_conv (const char * service, const char * user, pam_conv_fn conv_fn, void * conv_userdata, struct pam_testcase test_cases[], pam_handle_t * pam_handle)

Run libpamtest test cases. This is using the default libpamtest conversation function.

Parameters
    service The PAM service to use in the conversation
    user The user to run conversation as
    conv_fn Test-specific conversation function
    conv_userdata Test-specific conversation data
    test_cases List of libpamtest test cases. Must end with PAMTEST_CASE_SENTINEL
    pam_handle The PAM handle to use to run the tests

int main(void) {
    int rc;
    const struct pam_testcase tests[] = {
        pam_test(PAM_AUTHENTICATE, PAM_SUCCESS),
    };
    rc = run_pamtest(tests, NULL, NULL);
    return rc;
}

Returns
    PAMTEST_ERR_OK on success, else the error code matching the failure.

Author

Generated automatically by Doxygen for pam_wrapper from the source code.