11. Custom PKI authentication

xGT allows sites to configure their authentication process by writing a custom PAM module. PAM modules are C/C++ libraries compiled as shared objects that comply with the PAM module interface specification. This link https://medium.com/@avirzayev/linux-pam-how-to-create-an-authentication-module-cc132115bdc5 provides an introduction on how to create custom PAM modules.

xGT interfaces with PAM modules using the standard interface provided by PAM. Currently, xGT only supports interfacing with a custom PAM module when using PKI authentication with mutual TLS validation (see Encrypted Connections to xGT and PKI Authentication for more details).

The principal entry point in a custom PAM module for authentication is the function pam_sm_authenticate():

PAM_EXTERN int pam_sm_authenticate(pam_handle_t *pamh, int, int,
                                   const char **)

xGT will communicate a conversation structure to the PAM module. The structure can be retrieved as follows:

const void *pamConv = nullptr;

// Retrieve conversation structure provide by the application.
const int success = pam_get_item(pamh, PAM_CONV, &pamConv);

const pam_conv *pconv = reinterpret_cast<const pam_conv *>(pamConv);

if (pconv->appdata_ptr == nullptr)
  return PAM_AUTH_ERR;

The custom structure used by xGT can be retrieved from the appdata_ptr field:

XgtInfo &xgtInfo = *reinterpret_cast<XgtInfo *>(pconv->appdata_ptr);

The XgtInfo structure has the following fields:

struct XgtInfo {
  // xGT user ID coming from the client.  Can be modified by the module.
  std::string identity_;
  // xGT "credentials" coming from the client.  Will be filled with the PKI x509
  // certificate raw data coming from the connection.
  const std::string credentials_;
  // Set of groups to be mapped to the user ID, to be provided by the PAM
  // module.
  std::set<std::string> groups_;
  // Set of labels to be mapped to the user ID, to be provided by the PAM
  // module.
  std::set<std::string> labels_;
};

The credentials_ field contains the PKI x509 certificate provided by the client connection to xGT.

The PAM module can modify the identity_ field to indicate what the user name will be for the connection.

In addition, the PAM module should provide at least the set of security labels to be used for the connection (see User Labels and Validation for more details about security labels). The PAM module can also optionally provide the “groups” to be used for the user. The groups correspond to the UNIX or LDAP group membership for the user identity. For the purposes of custom PKI authentication, the groups are not currently required or used by xGT.

Valid or invalid authentication can be communicated to xGT by having the pam_sm_authenticate() function return the constants PAM_SUCCESS or PAM_AUTH_ERR respectively.

All other PAM entry points can be provided by the module as well:

PAM_EXTERN int pam_sm_setcred(
    pam_handle_t *,
    int, int, const char **);

PAM_EXTERN int pam_sm_acct_mgmt(
    pam_handle_t *,
    int, int, const char **);

PAM_EXTERN int pam_sm_open_session(
    pam_handle_t *,
    int, int, const char **);

PAM_EXTERN int pam_sm_close_session(
    pam_handle_t *,
    int, int, const char **);

PAM_EXTERN int pam_sm_chauthtok(
    pam_handle_t *,
    int, int, const char **);

Trovares can provide sample C++ code and a makefile that implements a custom PAM module for PKI authentication upon request.