.TH "pamtest" 3 "pam_wrapper" \" -*- nroff -*-
.ad l
.nh
.SH NAME
pamtest \- The pamtest API
.SH SYNOPSIS
.br
.PP
.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBpam_testcase\fP"
.br
.RI "The PAM testcase struction\&. "
.ti -1c
.RI "struct \fBpamtest_conv_data\fP"
.br
.RI "This structure should be used when using run_pamtest, which uses an internal conversation function\&. "
.in -1c
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBpam_test\fP(op,  expected)   { op, expected, 0, 0, { \&.envlist = NULL } }"
.br
.RI "Initializes a pam_tescase structure\&. "
.ti -1c
.RI "#define \fBpam_test_flags\fP(op,  expected,  flags)   { op, expected, flags, 0, { \&.envlist = NULL } }"
.br
.RI "Initializes a CMUnitTest structure with additional PAM flags\&. "
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef int(* \fBpam_conv_fn\fP) (int num_msg, const struct pam_message **msg, struct pam_response **resp, void *appdata_ptr)"
.br
.RI "PAM conversation function, defined in pam_conv(3) "
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBpamtest_err\fP { \fBPAMTEST_ERR_OK\fP, \fBPAMTEST_ERR_START\fP, \fBPAMTEST_ERR_CASE\fP, \fBPAMTEST_ERR_OP\fP, \fBPAMTEST_ERR_END\fP, \fBPAMTEST_ERR_KEEPHANDLE\fP, \fBPAMTEST_ERR_INTERNAL\fP }"
.br
.RI "The return code of the pamtest function\&. "
.ti -1c
.RI "enum \fBpamtest_ops\fP { \fBPAMTEST_AUTHENTICATE\fP, \fBPAMTEST_SETCRED\fP, \fBPAMTEST_ACCOUNT\fP, \fBPAMTEST_OPEN_SESSION\fP, \fBPAMTEST_CLOSE_SESSION\fP, \fBPAMTEST_CHAUTHTOK\fP, \fBPAMTEST_GETENVLIST\fP = 20, \fBPAMTEST_KEEPHANDLE\fP }"
.br
.RI "The enum which describes the operations performed by pamtest()\&. "
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "const struct \fBpam_testcase\fP * \fBpamtest_failed_case\fP (struct \fBpam_testcase\fP *test_cases)"
.br
.RI "Helper you can call if \fBrun_pamtest()\fP fails\&. "
.ti -1c
.RI "void \fBpamtest_free_env\fP (char **envlist)"
.br
.RI "This frees the string array returned by the PAMTEST_GETENVLIST test\&. "
.ti -1c
.RI "const char * \fBpamtest_strerror\fP (enum \fBpamtest_err\fP perr)"
.br
.RI "return a string representation of libpamtest error code\&. "
.ti -1c
.RI "enum \fBpamtest_err\fP \fBrun_pamtest\fP (const char *service, const char *user, struct \fBpamtest_conv_data\fP *conv_data, struct \fBpam_testcase\fP test_cases[], pam_handle_t *pam_handle)"
.br
.RI "Run libpamtest test cases\&. "
.ti -1c
.RI "enum \fBpamtest_err\fP \fBrun_pamtest_conv\fP (const char *service, const char *user, \fBpam_conv_fn\fP conv_fn, void *conv_userdata, struct \fBpam_testcase\fP test_cases[], pam_handle_t *pam_handle)"
.br
.RI "Run libpamtest test cases\&. "
.in -1c
.SH "Detailed Description"
.PP 



.SH "Typedef Documentation"
.PP 
.SS "typedef int(* pam_conv_fn) (int num_msg, const struct pam_message **msg, struct pam_response **resp, void *appdata_ptr)"

.PP
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\&. 
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBpamtest_err\fP"

.PP
The return code of the pamtest function\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIPAMTEST_ERR_OK \fP\fP
Testcases returns correspond with input\&. 
.TP
\fB\fIPAMTEST_ERR_START \fP\fP
pam_start() failed 
.TP
\fB\fIPAMTEST_ERR_CASE \fP\fP
A testcase failed\&. Use pamtest_failed_case 
.TP
\fB\fIPAMTEST_ERR_OP \fP\fP
Could not run a test case\&. 
.TP
\fB\fIPAMTEST_ERR_END \fP\fP
pam_end failed 
.TP
\fB\fIPAMTEST_ERR_KEEPHANDLE \fP\fP
Handled internally\&. 
.TP
\fB\fIPAMTEST_ERR_INTERNAL \fP\fP
Internal error - bad input or similar\&. 
.SS "enum \fBpamtest_ops\fP"

.PP
The enum which describes the operations performed by pamtest()\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIPAMTEST_AUTHENTICATE \fP\fP
run pam_authenticate to authenticate the account 
.TP
\fB\fIPAMTEST_SETCRED \fP\fP
run pam_setcred() to establish/delete user credentials 
.TP
\fB\fIPAMTEST_ACCOUNT \fP\fP
run pam_acct_mgmt() to validate the PAM account 
.TP
\fB\fIPAMTEST_OPEN_SESSION \fP\fP
run pam_open_session() to start a PAM session 
.TP
\fB\fIPAMTEST_CLOSE_SESSION \fP\fP
run pam_close_session() to end a PAM session 
.TP
\fB\fIPAMTEST_CHAUTHTOK \fP\fP
run pam_chauthtok() to update the authentication token 
.TP
\fB\fIPAMTEST_GETENVLIST \fP\fP
If this option is set the test will call pam_getenvlist() and copy the environment into case_out\&.envlist\&. 
.TP
\fB\fIPAMTEST_KEEPHANDLE \fP\fP
This will prevent calling pam_end() and will just return the PAM handle in case_out\&.ph\&. 
.SH "Function Documentation"
.PP 
.SS "const struct \fBpam_testcase\fP * pamtest_failed_case (struct \fBpam_testcase\fP * test_cases)"

.PP
Helper you can call if \fBrun_pamtest()\fP fails\&. If PAMTEST_ERR_CASE is returned by \fBrun_pamtest()\fP you should call this function get a pointer to the failed test case\&.
.PP
\fBParameters\fP
.RS 4
\fItest_cases\fP The array of tests\&.
.RE
.PP
\fBReturns\fP
.RS 4
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\&. 
.RE
.PP

.SS "void pamtest_free_env (char ** envlist)"

.PP
This frees the string array returned by the PAMTEST_GETENVLIST test\&. 
.PP
\fBParameters\fP
.RS 4
\fIenvlist\fP The array to free\&. 
.RE
.PP

.SS "const char * pamtest_strerror (enum \fBpamtest_err\fP perr)"

.PP
return a string representation of libpamtest error code\&. 
.PP
\fBParameters\fP
.RS 4
\fIperr\fP libpamtest error code
.RE
.PP
\fBReturns\fP
.RS 4
String representation of the perr argument\&. Never returns NULL\&. 
.RE
.PP

.PP
References \fBPAMTEST_ERR_CASE\fP, \fBPAMTEST_ERR_END\fP, \fBPAMTEST_ERR_INTERNAL\fP, \fBPAMTEST_ERR_KEEPHANDLE\fP, \fBPAMTEST_ERR_OK\fP, \fBPAMTEST_ERR_OP\fP, and \fBPAMTEST_ERR_START\fP\&.
.SS "enum \fBpamtest_err\fP run_pamtest (const char * service, const char * user, struct \fBpamtest_conv_data\fP * conv_data, struct \fBpam_testcase\fP test_cases[], pam_handle_t * pam_handle)"

.PP
Run libpamtest test cases\&. This is using the default libpamtest conversation function\&.
.PP
\fBParameters\fP
.RS 4
\fIservice\fP The PAM service to use in the conversation
.br
\fIuser\fP The user to run conversation as
.br
\fIconv_data\fP Test-specific conversation data
.br
\fItest_cases\fP List of libpamtest test cases\&. Must end with PAMTEST_CASE_SENTINEL
.br
\fIpam_handle\fP The PAM handle to use to run the tests
.RE
.PP
.PP
.nf
int main(void) {
    int rc;
    const struct pam_testcase tests[] = {
        pam_test(PAM_AUTHENTICATE, PAM_SUCCESS),
    };

    rc = run_pamtest(tests, NULL, NULL);

    return rc;
}
.fi
.PP
.PP
\fBReturns\fP
.RS 4
PAMTEST_ERR_OK on success, else the error code matching the failure\&. 
.RE
.PP

.SS "enum \fBpamtest_err\fP run_pamtest_conv (const char * service, const char * user, \fBpam_conv_fn\fP conv_fn, void * conv_userdata, struct \fBpam_testcase\fP test_cases[], pam_handle_t * pam_handle)"

.PP
Run libpamtest test cases\&. This is using the default libpamtest conversation function\&.
.PP
\fBParameters\fP
.RS 4
\fIservice\fP The PAM service to use in the conversation
.br
\fIuser\fP The user to run conversation as
.br
\fIconv_fn\fP Test-specific conversation function
.br
\fIconv_userdata\fP Test-specific conversation data
.br
\fItest_cases\fP List of libpamtest test cases\&. Must end with PAMTEST_CASE_SENTINEL
.br
\fIpam_handle\fP The PAM handle to use to run the tests
.RE
.PP
.PP
.nf
int main(void) {
    int rc;
    const struct pam_testcase tests[] = {
        pam_test(PAM_AUTHENTICATE, PAM_SUCCESS),
    };

    rc = run_pamtest(tests, NULL, NULL);

    return rc;
}
.fi
.PP
.PP
\fBReturns\fP
.RS 4
PAMTEST_ERR_OK on success, else the error code matching the failure\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for pam_wrapper from the source code\&.