OCaml bindings for the Linux-PAM library
This provides OCaml bindings for the Linux-PAM (Pluggable Authentication Modules for Linux) library. It allows OCaml programs to delegate authentication tasks to the Linux-PAM framework.
Published: 14 Jun 2023
#+TITLE: Pam * Overview *Pam* provides the necessary functions for OCaml programs to interact with the Linux Pluggable Authentication Modules (PAM) system. It allows applications to make use of existing Linux PAM modules for authentication, authorization or even setting up the application session similar to other applications like sshd. For clarity, we will use /Pam/ to refer to the OCaml library and /Linux-PAM/ to refer to the native PAM stack in this document. * Details The library is designed to look similar to functions in the Linux-PAM library. For details on how PAM is used, please kindly refer to the Linux-PAM Application Developer's Guide (http://www.linux-pam.org/Linux-PAM-html/Linux-PAM_ADG.html) or the manpages of specific pam functions. The function names should be similar enough if not exactly identical. The Pam library implements most of the functions required by applications to interact with the Linux-PAM system. It does not mean to implement every function provided in the PAM C-library. However, it should be complete enough for most uses. There are several functions implemented in a slightly different way: 1. ~pam_start~ requires a /conversation/ function argument with an interface different from the one in the C library. It requires a function which takes an argument of ~(Pam_conv.Message.t, string) Result.t list~ while the corresponding C library requires a function which takes an argument of ~pam_message~ array only (see ~man 3 pam_conv~). The extra ~Result.t~ is for the /Pam/ library to report error if it fails to convert any ~pam_message~ structure in C into ~Pam_conv.Message.t~ in OCaml. 2. ~pam_start~ also behaves differently when it fails to start a new pam session. Instead of leaving the cleanup to the caller, it will also call ~pam_end~ to close and clean up the session. The design itself aims at making it more trivial to chain successful pam operations and populate the errors without handling the cleanup explicitly. 3. ~pam_unsetenv~ is newly introduced and not in the Linux-PAM stack. This function allows the application developer to clear a PAM environment explicitly. This function is done via ~pam_putenv~ with a specific key notation. We think an explicit function is better than relying on any notation. * Examples There are some sample codes in the ~examples~ directory which illustrate how /Pam/ works.