pam_wrapper: The pamtest API

pam_wrapper

Data Structures | Macros | Typedefs | Enumerations | Functions
The pamtest API

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

## Macros
#define | pam_test(op, expected)
| Initializes a pam_tescase structure.
#define | pam_test_flags(op, expected, 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 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. More...
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(). More...

## 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

## ◆ 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.

## Enumeration Type Documentation

## ◆ pamtest_err

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.

## ◆ pamtest_ops

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 get a pointer to the failed test case.

Parameters

  [in] | 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

  [in] | envlist | The array to free.

## ◆ pamtest_strerror()

const char * pamtest_strerror | ( | enum pamtest_err | perr | ) |

return a string representation of libpamtest error code.

Parameters

  [in] | 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

  [in] | service | The PAM service to use in the conversation
  [in] | user | The user to run conversation as
  [in] | conv_data | Test-specific conversation data
  [in] | test_cases | List of libpamtest test cases. Must end with PAMTEST_CASE_SENTINEL
  [in] | 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;
}
pam_test
#define pam_test(op, expected)
Initializes a pam_tescase structure.
Definition libpamtest.h:82
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.
pam_testcase
The PAM testcase struction.
Definition libpamtest.h:68

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

  [in] | service | The PAM service to use in the conversation
  [in] | user | The user to run conversation as
  [in] | conv_fn | Test-specific conversation function
  [in] | conv_userdata | Test-specific conversation data
  [in] | test_cases | List of libpamtest test cases. Must end with PAMTEST_CASE_SENTINEL
  [in] | 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.