summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorSumit Bose <sbose@redhat.com>2010-02-15 15:05:07 +0100
committerStephen Gallagher <sgallagh@redhat.com>2010-02-19 16:10:06 -0500
commit446dbddae224cb68422825445b3cbdeb6606aa81 (patch)
tree5fd0e068eb90854cd94541cb50fe0eea9fb6f493 /src
parent953e07b7c43bc9bb7c7616180b1ba1730e22c59a (diff)
downloadsssd-446dbddae224cb68422825445b3cbdeb6606aa81.tar.gz
sssd-446dbddae224cb68422825445b3cbdeb6606aa81.tar.xz
sssd-446dbddae224cb68422825445b3cbdeb6606aa81.zip
Add documentation for PAM response messages
Diffstat (limited to 'src')
-rw-r--r--src/doxy.config.in4
-rw-r--r--src/providers/data_provider.h69
-rw-r--r--src/sss_client/sss_cli.h219
3 files changed, 272 insertions, 20 deletions
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,
+ * <pre>
+ * ------------------------------------
+ * | uint32_t | uint32_t | uint8_t[4] |
+ * | 0x03 | 0x04 | a=b\\0 |
+ * ------------------------------------
+ * </pre>
+ * @{
+ */
+
+/** 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
+ * <pre>
+ * ----------------------------------
+ * | uint32_t | uint32_t | uint32_t |
+ * | 0x06 | 0x01 | 0x03 |
+ * ----------------------------------
+ * </pre>
+ * - #SSS_PAM_USER_INFO_CHPASS_ERROR
+ * <pre>
+ * ----------------------------------------------------------
+ * | uint32_t | uint32_t | uint32_t | uint32_t | uint8_t[3] |
+ * | 0x06 | 0x05 | 0x04 | 0x03 | abc |
+ * ----------------------------------------------------------
+ * </pre>
+ * @{
+ */
+
+/** 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,