Add documentation for PAM response messages

1 files changed, 200 insertions, 19 deletions

diff --git a/src/sss_client/sss_cli.h b/src/sss_client/sss_cli.h
index 33ef2a44..522e0792 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,