pam_wrapper: include/libpamtest.h Source File

pam_wrapper

libpamtest.h
1/*
2 * Copyright (c) 2015 Andreas Schneider <asn@samba.org>
3 * Copyright (c) 2015 Jakub Hrozek <jakub.hrozek@posteo.se>
4 *
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation, either version 3 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19#ifndef __LIBPAMTEST_H_
20#define __LIBPAMTEST_H_
21
22#include <stddef.h>
23#include <stdint.h>
24#include <security/pam_appl.h>
25
35 enum pamtest_ops {
37 PAMTEST_AUTHENTICATE,
39 PAMTEST_SETCRED,
41 PAMTEST_ACCOUNT,
43 PAMTEST_OPEN_SESSION,
45 PAMTEST_CLOSE_SESSION,
47 PAMTEST_CHAUTHTOK,
48
53 PAMTEST_GETENVLIST = 20,
58 PAMTEST_KEEPHANDLE,
59};
60
61
68 struct pam_testcase {
69 enum pamtest_ops pam_operation; /* The pam operation to run */
70 int expected_rv; /* What we expect the op to return */
71 int flags; /* Extra flags to pass to the op */
72
73 int op_rv; /* What the op really returns */
74
75 union {
76 char **envlist; /* output of PAMTEST_ENVLIST */
77 pam_handle_t *ph; /* output of PAMTEST_KEEPHANDLE */
78 } case_out; /* depends on pam_operation, mostly unused */
79};
80
82#define pam_test(op, expected) { op, expected, 0, 0, { .envlist = NULL } }
84#define pam_test_flags(op, expected, flags) { op, expected, flags, 0, { .envlist = NULL } }
85
89 enum pamtest_err {
91 PAMTEST_ERR_OK,
93 PAMTEST_ERR_START,
95 PAMTEST_ERR_CASE,
97 PAMTEST_ERR_OP,
99 PAMTEST_ERR_END,
101 PAMTEST_ERR_KEEPHANDLE,
103 PAMTEST_ERR_INTERNAL,
104};
105
112 typedef int (*pam_conv_fn)(int num_msg,
113 const struct pam_message **msg,
114 struct pam_response **resp,
115 void *appdata_ptr);
116
121 struct pamtest_conv_data {
126 const char **in_echo_off;
131 const char **in_echo_on;
135 char **out_err;
139 char **out_info;
140};
141
142#ifdef DOXYGEN
176 enum pamtest_err run_pamtest_conv(const char *service,
177 const char *user,
178 pam_conv_fn conv_fn,
179 void *conv_userdata,
180 struct pam_testcase test_cases[],
181 pam_handle_t *pam_handle);
182#else
183#define run_pamtest_conv(service, user, conv_fn, conv_data, test_cases, pam_handle) \
184 _pamtest_conv(service, user, conv_fn, conv_data, test_cases, sizeof(test_cases)/sizeof(test_cases[0], pam_handle)
185#endif
186
187#ifdef DOXYGEN
219 enum pamtest_err run_pamtest(const char *service,
220 const char *user,
221 struct pamtest_conv_data *conv_data,
222 struct pam_testcase test_cases[],
223 pam_handle_t *pam_handle);
224#else
225#define run_pamtest(service, user, conv_data, test_cases, pam_handle) \
226 _pamtest(service, user, conv_data, test_cases, sizeof(test_cases)/sizeof(test_cases[0]), pam_handle)
227#endif
228
229#ifdef DOXYGEN
242 const struct pam_testcase *pamtest_failed_case(struct pam_testcase *test_cases);
243#else
244#define pamtest_failed_case(test_cases) \
245 _pamtest_failed_case(test_cases, sizeof(test_cases) / sizeof(test_cases[0]))
246#endif
247
255const char *pamtest_strerror(enum pamtest_err perr);
256
262void pamtest_free_env(char **envlist);
263
264
265/* Internal function protypes */
266enum pamtest_err _pamtest_conv(const char *service,
267 const char *user,
268 pam_conv_fn conv_fn,
269 void *conv_userdata,
270 struct pam_testcase test_cases[],
271 size_t num_test_cases,
272 pam_handle_t *pam_handle);
273
274enum pamtest_err _pamtest(const char *service,
275 const char *user,
276 struct pamtest_conv_data *conv_data,
277 struct pam_testcase test_cases[],
278 size_t num_test_cases,
279 pam_handle_t *pam_handle);
280
281const struct pam_testcase *_pamtest_failed_case(struct pam_testcase test_cases[],
282 size_t num_test_cases);
283
286#endif /* __LIBPAMTEST_H_ */
pamtest_failed_case
const struct pam_testcase * pamtest_failed_case(struct pam_testcase *test_cases)
Helper you can call if run_pamtest() fails.
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:112
pamtest_strerror
const char * pamtest_strerror(enum pamtest_err perr)
return a string representation of libpamtest error code.
Definition: libpamtest.c:157
pamtest_free_env
void pamtest_free_env(char **envlist)
This frees the string array returned by the PAMTEST_GETENVLIST test.
Definition: libpamtest.c:125
pamtest_ops
pamtest_ops
The enum which describes the operations performed by pamtest().
Definition: libpamtest.h:35
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.
pamtest_err
pamtest_err
The return code of the pamtest function.
Definition: libpamtest.h:89
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.
PAMTEST_OPEN_SESSION
@ PAMTEST_OPEN_SESSION
run pam_open_session() to start a PAM session
Definition: libpamtest.h:43
PAMTEST_SETCRED
@ PAMTEST_SETCRED
run pam_setcred() to establish/delete user credentials
Definition: libpamtest.h:39
PAMTEST_CHAUTHTOK
@ PAMTEST_CHAUTHTOK
run pam_chauthtok() to update the authentication token
Definition: libpamtest.h:47
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:53
PAMTEST_AUTHENTICATE
@ PAMTEST_AUTHENTICATE
run pam_authenticate to authenticate the account
Definition: libpamtest.h:37
PAMTEST_CLOSE_SESSION
@ PAMTEST_CLOSE_SESSION
run pam_close_session() to end a PAM session
Definition: libpamtest.h:45
PAMTEST_ACCOUNT
@ PAMTEST_ACCOUNT
run pam_acct_mgmt() to validate the PAM account
Definition: libpamtest.h:41
PAMTEST_KEEPHANDLE
@ PAMTEST_KEEPHANDLE
This will prevent calling pam_end() and will just return the PAM handle in case_out....
Definition: libpamtest.h:58
PAMTEST_ERR_END
@ PAMTEST_ERR_END
pam_end failed
Definition: libpamtest.h:99
PAMTEST_ERR_CASE
@ PAMTEST_ERR_CASE
A testcase failed.
Definition: libpamtest.h:95
PAMTEST_ERR_START
@ PAMTEST_ERR_START
pam_start() failed
Definition: libpamtest.h:93
PAMTEST_ERR_KEEPHANDLE
@ PAMTEST_ERR_KEEPHANDLE
Handled internally.
Definition: libpamtest.h:101
PAMTEST_ERR_INTERNAL
@ PAMTEST_ERR_INTERNAL
Internal error - bad input or similar.
Definition: libpamtest.h:103
PAMTEST_ERR_OP
@ PAMTEST_ERR_OP
Could not run a test case.
Definition: libpamtest.h:97
PAMTEST_ERR_OK
@ PAMTEST_ERR_OK
Testcases returns correspond with input.
Definition: libpamtest.h:91
pam_testcase
The PAM testcase struction.
Definition: libpamtest.h:68
pamtest_conv_data
This structure should be used when using run_pamtest, which uses an internal conversation function.
Definition: libpamtest.h:121
pamtest_conv_data::out_err
char ** out_err
Captures messages through PAM_ERROR_MSG.
Definition: libpamtest.h:135
pamtest_conv_data::out_info
char ** out_info
Captures messages through PAM_TEXT_INFO.
Definition: libpamtest.h:139
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:131
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:126