From 446dbddae224cb68422825445b3cbdeb6606aa81 Mon Sep 17 00:00:00 2001 From: Sumit Bose Date: Mon, 15 Feb 2010 15:05:07 +0100 Subject: Add documentation for PAM response messages --- .gitignore | 1 + src/doxy.config.in | 4 +- src/providers/data_provider.h | 69 +++++++++++++ src/sss_client/sss_cli.h | 219 ++++++++++++++++++++++++++++++++++++++---- 4 files changed, 273 insertions(+), 20 deletions(-) diff --git a/.gitignore b/.gitignore index 8550ae315..478cd7f60 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ config.rpath config.h config.h.in cscope.out +doxy.config Makefile Makefile.in Makefile.in.in diff --git a/src/doxy.config.in b/src/doxy.config.in index 6c1474963..a9070e5b9 100644 --- a/src/doxy.config.in +++ b/src/doxy.config.in @@ -578,7 +578,9 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = @srcdir@/confdb +INPUT = @srcdir@/confdb \ + @srcdir@/providers/data_provider.h \ + @srcdir@/sss_client/sss_cli.h # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is diff --git a/src/providers/data_provider.h b/src/providers/data_provider.h index c43b9885d..661bd986a 100644 --- a/src/providers/data_provider.h +++ b/src/providers/data_provider.h @@ -56,8 +56,77 @@ #define DP_METHOD_REGISTER "RegisterService" #define DP_METHOD_ONLINE "getOnline" #define DP_METHOD_GETACCTINFO "getAccountInfo" +/** + * @defgroup pamHandler PAM DBUS request + * @ingroup sss_pam + * + * The PAM responder send all the data it has received from the PAM client to + * the authentication backend with a DBUS message. + * + * As a response it expects basically a PAM return value (see pam(3) for + * details) and the name of the domain. The backend may send any number of + * additional messages (see ...) which are forwarded by the PAM responder to + * the PAM client. + * @{ + */ + +/** Then pamHandler Request + * + * The following two functions can help you to pack and unpack the DBUS + * message for a PAM request. If it is necessary to create the DBUS message by + * hand it must have the following elements: + * + * @param DBUS_TYPE_INT32 PAM Command, see #sss_cli_command for allowed values + * @param DBUS_TYPE_STRING Name of the Domain + * @param DBUS_TYPE_STRING User name, this value is send by the PAM client and + * contains the value of the PAM item PAM_USER + * @param DBUS_TYPE_STRING Service name, this value is send by the PAM client + * and contains the value of the PAM item PAM_SERVICE + * @param DBUS_TYPE_STRING TTY name this value is send by the PAM client and + * contains the value of the PAM item PAM_TTY + * @param DBUS_TYPE_STRING Remote user, this value is send by the PAM client + * and contains the value of the PAM item PAM_RUSER + * @param DBUS_TYPE_STRING Remote host, this value is send by the PAM client + * and contains the value of the PAM item PAM_RHOST + * @param DBUS_TYPE_UINT32 Type of the authentication token, see #sss_authtok_type + * for allowed values + * @param DBUS_TYPE_ARRAY__(BYTE) Authentication token, DBUS array which + * contains the authentication token, it is not required that passwords have a + * trailing \\0, this value is send by the PAM client and contains the value of + * the PAM item PAM_AUTHTOK or PAM_OLDAUTHTOK if the PAM command is + * #SSS_PAM_CHAUTHTOK or #SSS_PAM_CHAUTHTOK_PRELIM + * @param DBUS_TYPE_UINT32 Type of the new authentication token, see + * #sss_authtok_type for allowed values + * @param DBUS_TYPE_ARRAY__(BYTE) New authentication token, DBUS array which + * contains the new authentication token for a password change, it is not + * required that passwords have a trailing \\0, this value is send by the PAM + * client and contains the value of the PAM item PAM_AUTHTOK if the PAM + * command is #SSS_PAM_CHAUTHTOK or #SSS_PAM_CHAUTHTOK_PRELIM + * @param DBUS_TYPE_INT32 Privileged flag is set to a non-zero value if the + * PAM client connected to the PAM responder via the privileged pipe, i.e. if + * the PAM client is running with root privileges + * @param DBUS_TYPE_UINT32 + * + * @retval DBUS_TYPE_UINT32 PAM return value, PAM_AUTHINFO_UNAVAIL is used to + * indicate that the provider is offline and that the PAM responder should try + * a chached authentication, for all other return value see the man pages for + * the corresponding PAM service functions + * @retval DBUS_TYPE_STRING Domain Name + * @retval DBUS_TYPE_ARRAY__(STRUCT) (optional) Zero more more additional + * messages, here the DBUS_TYPE_STRUCT is build of a DBUS_TYPE_UINT32 holding + * an identifier (see #response_type) and DBUS_TYPE_G_BYTE_ARRAY with the data + * of the message. + */ + + #define DP_METHOD_PAMHANDLER "pamHandler" +/** + * @} + */ /* end of group pamHandler */ + + + #define DP_ERR_OK 0 #define DP_ERR_OFFLINE 1 #define DP_ERR_TIMEOUT 2 diff --git a/src/sss_client/sss_cli.h b/src/sss_client/sss_cli.h index 33ef2a44e..522e0792a 100644 --- a/src/sss_client/sss_cli.h +++ b/src/sss_client/sss_cli.h @@ -37,6 +37,13 @@ typedef int errno_t; #define SSS_NSS_PROTOCOL_VERSION 1 #define SSS_PAM_PROTOCOL_VERSION 3 +/** + * @defgroup sss_cli_command SSS client commands + * @{ + */ + +/** The allowed commands a SSS client can send to the SSSD */ + enum sss_cli_command { /* null */ SSS_CLI_NULL = 0x0000, @@ -136,21 +143,78 @@ enum sss_cli_command { #endif /* PAM related calls */ - SSS_PAM_AUTHENTICATE = 0x00F1, - SSS_PAM_SETCRED = 0x00F2, - SSS_PAM_ACCT_MGMT = 0x00F3, - SSS_PAM_OPEN_SESSION = 0x00F4, - SSS_PAM_CLOSE_SESSION = 0x00F5, - SSS_PAM_CHAUTHTOK = 0x00F6, - SSS_PAM_CHAUTHTOK_PRELIM = 0x00F7, + SSS_PAM_AUTHENTICATE = 0x00F1, /**< see pam_sm_authenticate(3) for + * details */ + SSS_PAM_SETCRED = 0x00F2, /**< see pam_sm_setcred(3) for + * details */ + SSS_PAM_ACCT_MGMT = 0x00F3, /**< see pam_sm_acct_mgmt(3) for + * details */ + SSS_PAM_OPEN_SESSION = 0x00F4, /**< see pam_sm_open_session(3) for + * details */ + SSS_PAM_CLOSE_SESSION = 0x00F5, /**< see pam_sm_close_session(3) for + *details */ + SSS_PAM_CHAUTHTOK = 0x00F6, /**< second run of the password change + * operation where the PAM_UPDATE_AUTHTOK + * flag is set and the real change may + * happen, see pam_sm_chauthtok(3) for + * details */ + SSS_PAM_CHAUTHTOK_PRELIM = 0x00F7, /**< first run of the password change + * operation where the PAM_PRELIM_CHECK + * flag is set, see pam_sm_chauthtok(3) + * for details */ }; +/** + * @} + */ /* end of group sss_cli_command */ + + +/** + * @defgroup sss_pam SSSD and PAM + * + * SSSD offers authentication and authorization via PAM + * + * The SSSD provides a PAM client modules pam_sss which can be called from the + * PAM stack of the operation system. pam_sss will collect all the data about + * the user from the PAM stack and sends them via a socket to the PAM + * responder of the SSSD. The PAM responder selects the appropriate backend + * and forwards the data via DBUS to the backend. The backend preforms the + * requested operation and sends the result expressed by a PAM return value + * and optional additional information back to the PAM responder. Finally the + * PAM responder forwards the response back to the client. + * + * @{ + */ + +/** + * @} + */ /* end of group sss_pam */ + +/** + * @defgroup sss_authtok_type Authentication Tokens + * @ingroup sss_pam + * + * To indicate to the components of the SSSD how to handle the authentication + * token the client sends the type of the authentication token to the SSSD. + * + * @{ + */ + +/** The different types of authentication tokens */ + enum sss_authtok_type { - SSS_AUTHTOK_TYPE_EMPTY = 0x0000, - SSS_AUTHTOK_TYPE_PASSWORD = 0x0001, + SSS_AUTHTOK_TYPE_EMPTY = 0x0000, /**< No authentication token + * available */ + SSS_AUTHTOK_TYPE_PASSWORD = 0x0001, /**< Authentication token is a + * password, it may or may no contain + * a trailing \\0 */ }; +/** + * @} + */ /* end of group sss_authtok_type */ + #define SSS_START_OF_PAM_REQUEST 0x4d415049 #define SSS_END_OF_PAM_REQUEST 0x4950414d @@ -182,21 +246,138 @@ enum sss_status { SSS_STATUS_SUCCESS }; +/** + * @defgroup sss_pam_cli Responses to the PAM client + * @ingroup sss_pam + * @{ + */ + +/** + * @defgroup response_type Messages from the server + * @ingroup sss_pam_cli + * + * SSSD can send different kind of information back to the client. + * A response from the SSSD can contain 0 or more messages. Each message + * contains a type tag and the size of the message data, both are unsigned + * 32-bit integer values, followed be the message specific data. + * + * If the message is generated by a backend it is send back to the PAM + * responder via a D-BUS message in an array of D-BUS structs. The struct + * consists of a DBUS_TYPE_UINT32 for the tag and a DBUS_TYPE_ARRAY to hold + * the message. + * + * Examples: + * - #SSS_PAM_ENV_ITEM, + * 
+ *    ------------------------------------
+ *    | uint32_t | uint32_t | uint8_t[4] |
+ *    | 0x03     | 0x04     | a=b\\0      |
+ *    ------------------------------------
+ *
+ * @{ + */ + +/** Types of different messages */ + enum response_type { - SSS_PAM_SYSTEM_INFO = 0x01, - SSS_PAM_DOMAIN_NAME, - SSS_PAM_ENV_ITEM, /* only pam environment */ - SSS_ENV_ITEM, /* only user environment */ - SSS_ALL_ENV_ITEM, /* pam and user environment */ - SSS_PAM_USER_INFO + SSS_PAM_SYSTEM_INFO = 0x01, /**< Message for the system log. + * @param String, zero terminated. */ + SSS_PAM_DOMAIN_NAME, /**< Name of the domain the user belongs too. + * This messages is generated by the PAM responder. + * @param String, zero terminated, with the domain + * name. */ + SSS_PAM_ENV_ITEM, /**< Set and environment variable with pam_putenv(3). + * @param String, zero terminated, of the form + * name=value. See pam_putenv(3) for details. */ + SSS_ENV_ITEM, /**< Set and environment variable with putenv(3). + * @param String, zero terminated, of the form + * name=value. See putenv(3) for details. */ + SSS_ALL_ENV_ITEM, /**< Set and environment variable with putenv(3) and + * pam_putenv(3). + * @param String, zero terminated, of the form + * name=value. See putenv(3) and pam_putenv(3) for + * details. */ + SSS_PAM_USER_INFO /**< A message which should be displayed to the user. + * @param User info message, see #user_info_type + * for details. */ }; +/** + * @defgroup user_info_type User info messages + * @ingroup response_type + * + * To achieve a consistent user experience and to facilitate + * internationalization all messages show to the user are generate by the PAM + * client and not by the SSSD server components. To indicate what message the + * client should display to the user SSSD can send a #SSS_PAM_USER_INFO message + * where the data part contains one of the following tags as an unsigned + * 32-bit integer value and optional data. + * + * Examples: + * - #SSS_PAM_USER_INFO_OFFLINE_CHPASS + * 
+ *    ----------------------------------
+ *    | uint32_t | uint32_t | uint32_t |
+ *    | 0x06     | 0x01     | 0x03     |
+ *    ----------------------------------
+ *
+ * - #SSS_PAM_USER_INFO_CHPASS_ERROR + * 
+ *    ----------------------------------------------------------
+ *    | uint32_t | uint32_t | uint32_t | uint32_t | uint8_t[3] |
+ *    | 0x06     | 0x05     | 0x04     | 0x03     | abc        |
+ *    ----------------------------------------------------------
+ *
+ * @{ + */ + +/** Different types of user messages */ + enum user_info_type { - SSS_PAM_USER_INFO_OFFLINE_AUTH = 0x01, - SSS_PAM_USER_INFO_OFFLINE_AUTH_DELAYED, - SSS_PAM_USER_INFO_OFFLINE_CHPASS, - SSS_PAM_USER_INFO_CHPASS_ERROR + SSS_PAM_USER_INFO_OFFLINE_AUTH = 0x01, /**< Inform the user that the + * authentication happened offline. + * This message is generated by the + * PAM responder. + * @param Time when the cached + * password will expire in seconds + * since the UNIX Epoch as returned + * by time(2) as long long. A value + * of zero indicates that the + * cached password will never + * expire. */ + SSS_PAM_USER_INFO_OFFLINE_AUTH_DELAYED, /**< Tell the user how low a new + * authentication is delayed. This + * message is generated by the PAM + * responder. + * @param Time when an + * authentication is allowed again + * in seconds since the UNIX Epoch + * as returned by time(2) as long + * long. */ + SSS_PAM_USER_INFO_OFFLINE_CHPASS, /**< * Tell the user that it is not + * possible to change the password while + * the system is offline. This message + * is generated by the PAM responder. */ + SSS_PAM_USER_INFO_CHPASS_ERROR /**< Tell the user that a password change + * failed and optionally give a reason. + * @param Size of the message as unsigned + * 32-bit integer value. A value of 0 + * indicates that no message is following. + * @param String with the specified + * length. */ }; +/** + * @} + */ /* end of group user_info_type */ + +/** + * @} + */ /* end of group response_type */ + +/** + * @} + */ /* end of group sss_pam_cli */ + enum nss_status sss_nss_make_request(enum sss_cli_command cmd, struct sss_cli_req_data *rd, -- cgit