pam_wrapper  1.0.7
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)   { 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) More...
 

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_testcasepamtest_failed_case (struct pam_testcase *test_cases)
 Helper you can call if run_pamtest() fails. More...
 
void pamtest_free_env (char **envlist)
 This frees the string array returned by the PAMTEST_GETENVLIST test. More...
 
const char * pamtest_strerror (enum pamtest_err perr)
 return a string representation of libpamtest error code. More...
 
enum pamtest_err run_pamtest (const char *service, const char *user, struct pamtest_conv_data *conv_data, struct pam_testcase test_cases[])
 Run libpamtest test cases. More...
 
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[])
 Run libpamtest test cases. More...
 

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

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

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_casesThe 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]envlistThe array to free.

◆ pamtest_strerror()

const char* pamtest_strerror ( enum pamtest_err  perr)

return a string representation of libpamtest error code.

Parameters
[in]perrlibpamtest 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[] 
)

Run libpamtest test cases.

This is using the default libpamtest conversation function.

Parameters
[in]serviceThe PAM service to use in the conversation
[in]userThe user to run conversation as
[in]conv_dataTest-specific conversation data
[in]test_casesList of libpamtest test cases. Must end with PAMTEST_CASE_SENTINEL
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[] 
)

Run libpamtest test cases.

This is using the default libpamtest conversation function.

Parameters
[in]serviceThe PAM service to use in the conversation
[in]userThe user to run conversation as
[in]conv_fnTest-specific conversation function
[in]conv_userdataTest-specific conversation data
[in]test_casesList of libpamtest test cases. Must end with PAMTEST_CASE_SENTINEL
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.
PAMTEST_ERR_KEEPHANDLE
@ PAMTEST_ERR_KEEPHANDLE
Handled internally.
Definition: libpamtest.h:100
PAMTEST_ERR_OP
@ PAMTEST_ERR_OP
Could not run a test case.
Definition: libpamtest.h:96
pam_testcase
The PAM testcase struction.
Definition: libpamtest.h:67
pamtest_conv_data::in_echo_off
const char ** in_echo_off
When the conversation function receives PAM_PROMPT_ECHO_OFF, it reads the auth token from the in_echo...
Definition: libpamtest.h:125
PAMTEST_CLOSE_SESSION
@ PAMTEST_CLOSE_SESSION
run pam_close_session() to end a PAM session
Definition: libpamtest.h:44
PAMTEST_KEEPHANDLE
@ PAMTEST_KEEPHANDLE
This will prevent calling pam_end() and will just return the PAM handle in case_out....
Definition: libpamtest.h:57
pamtest_conv_data::out_info
char ** out_info
Captures messages through PAM_ERROR_MSG.
Definition: libpamtest.h:139
PAMTEST_ERR_INTERNAL
@ PAMTEST_ERR_INTERNAL
Internal error - bad input or similar.
Definition: libpamtest.h:102
PAMTEST_CHAUTHTOK
@ PAMTEST_CHAUTHTOK
run pam_chauthtok() to update the authentication token
Definition: libpamtest.h:46
pamtest_conv_data::in_echo_on
const char ** in_echo_on
When the conversation function receives PAM_PROMPT_ECHO_ON, it reads the input from the in_echo_off a...
Definition: libpamtest.h:130
PAMTEST_ACCOUNT
@ PAMTEST_ACCOUNT
run pam_acct_mgmt() to validate the PAM account
Definition: libpamtest.h:40
PAMTEST_SETCRED
@ PAMTEST_SETCRED
run pam_setcred() to establish/delete user credentials
Definition: libpamtest.h:38
PAMTEST_GETENVLIST
@ PAMTEST_GETENVLIST
If this option is set the test will call pam_getenvlist() and copy the environment into case_out....
Definition: libpamtest.h:52
PAMTEST_ERR_OK
@ PAMTEST_ERR_OK
Testcases returns correspond with input.
Definition: libpamtest.h:90
pamtest_conv_data::out_err
char ** out_err
Captures messages through PAM_TEXT_INFO.
Definition: libpamtest.h:135
run_pamtest
enum pamtest_err run_pamtest(const char *service, const char *user, struct pamtest_conv_data *conv_data, struct pam_testcase test_cases[])
Run libpamtest test cases.
PAMTEST_ERR_START
@ PAMTEST_ERR_START
pam_start() failed
Definition: libpamtest.h:92
pamtest_ops
pamtest_ops
The enum which describes the operations performed by pamtest().
Definition: libpamtest.h:34
PAMTEST_AUTHENTICATE
@ PAMTEST_AUTHENTICATE
run pam_authenticate to authenticate the account
Definition: libpamtest.h:36
pamtest_err
pamtest_err
The return code of the pamtest function.
Definition: libpamtest.h:88
pamtest_free_env
void pamtest_free_env(char **envlist)
This frees the string array returned by the PAMTEST_GETENVLIST test.
Definition: libpamtest.c:120
pam_test
#define pam_test(op, expected)
Initializes a pam_tescase structure.
Definition: libpamtest.h:81
pam_conv_fn
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)
Definition: libpamtest.h:111
PAMTEST_ERR_CASE
@ PAMTEST_ERR_CASE
A testcase failed.
Definition: libpamtest.h:94
PAMTEST_OPEN_SESSION
@ PAMTEST_OPEN_SESSION
run pam_open_session() to start a PAM session
Definition: libpamtest.h:42
pamtest_conv_data
This structure should be used when using run_pamtest, which uses an internal conversation function.
Definition: libpamtest.h:120
pamtest_strerror
const char * pamtest_strerror(enum pamtest_err perr)
return a string representation of libpamtest error code.
Definition: libpamtest.c:152
PAMTEST_ERR_END
@ PAMTEST_ERR_END
pam_end failed
Definition: libpamtest.h:98