pamtest(3)

💖 NAME

okay so bestie, you're looking at pamtest(3) from the Library Functions Manual — and it's literally the pamtest API. That's the whole NAME section, no cap. 💅

✨ SYNOPSIS

This is the quick-look menu, and every signature is coming with us — no skipping the boring bits, periodt. 🫶

🧚 Data Structures

• struct pam_testcase — The PAM testcase struction. (yes, that's the spelling in the docs 💀)
• 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)
#define pam_test_flags(op,  expected,  flags)

• pam_test — Initializes a pam_tescase structure. (typo stays iconic 💅)
• pam_test_flags — 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_conv_fn — 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 }
enum pamtest_ops { PAMTEST_AUTHENTICATE, PAMTEST_SETCRED,
    PAMTEST_ACCOUNT, PAMTEST_OPEN_SESSION, PAMTEST_CLOSE_SESSION,
    PAMTEST_CHAUTHTOK, PAMTEST_GETENVLIST = 20, PAMTEST_KEEPHANDLE }

• pamtest_err — The return code of the pamtest function.
• pamtest_ops — The enum which describes the operations performed by pamtest().

👑 Functions

const struct pam_testcase * pamtest_failed_case (struct pam_testcase
    *test_cases)
void pamtest_free_env (char **envlist)
const char * pamtest_strerror (enum pamtest_err perr)
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)
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)

• pamtest_failed_case — Helper you can call if run_pamtest() fails.
• pamtest_free_env — This frees the string array returned by the PAMTEST_GETENVLIST test.
• pamtest_strerror — Returns a string representation of libpamtest error code.
• run_pamtest — Run libpamtest test cases.
• run_pamtest_conv — Run libpamtest test cases.

🌈 Detailed Description

This is the big-picture section, and the actual deets are chilling in the docs below — keep scrolling, bestie. 💜

🧚 Typedef Documentation

pam_conv_fn

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. slay 💅

💅 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

pamtest_failed_case

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 to 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.

pamtest_free_env

void pamtest_free_env (char **envlist)

This frees the string array returned by the PAMTEST_GETENVLIST test.

Parameters

• envlist — The array to free.

pamtest_strerror

const char * pamtest_strerror (enum pamtest_err perr)

Returns 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.

run_pamtest

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.

run_pamtest_conv

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. That's the author tea, bestie. 💅

---

Sign-off: this page is from pam_wrapper, page pamtest(3) — and there's no date line in this footer, so that's the whole footer vibe. mwah 💋