Building an application with pamela instead of Linux-PAM

Prerequisites

The pamela package must have been properly built and installed; in particular, the pamelad binary must have been properly linked against Linux-PAM's libpam.so.
The security/pam_appl.h header, usually installed in /usr/include, must be a symlink to pamela's pamela/pam.h header. This can be achieved by running make install-symlink after make install when building the pamela package.
The application must strictly follow the Linux-PAM specification. Note that the page claims that the pam_set_item() function is declared in security/pam_modules.h, but it is a mistake: like every PAM function used by applications, it is declared in security/pam_appl.h.
The pamela headers and library must be installed, as well as the skalibs headers and library.

Compiling

Make sure that the pamela headers and the skalibs headers are visible in your header search path, and that the Linux-PAM headers are not.
If the compilation fails, please report the issue to the skaware mailing-list. pamela is a work in progress, and there may be compatibility issues that still need to be fixed.

Linking

Make sure the pamela library, as well as the skalibs library, are visible in your library search path.
Do not add -lpam to your linking command line. Instead, add -lpamela -lskarnet. Depending on the libc you're using, you may have to add -lrt too.
It is possible to statically link a binary using pamela: the pamela and skalibs libraries do not use any dynamic loading, and are suitable for static linking. Only the pamelad binary uses dynamic module loading and needs to be dynamically linked, and that is decided at pamela build time, not at your application's build time.
Check your application binary's dynamic library dependencies after it has been built. If your binary depends on libpam, it has been incorrectly made! Your binary should depend on libpamela and libskarnet, but not libpam. If you have chosen to link against the static version of pamela and skalibs, you may not even see the libpamela and libskarnet dependencies.

Programming

pamela strictly implements the Linux-PAM API
The pam_start() function will spawn a pamelad binary running as a child of the application, until pam_end() is called. At that point the zombie is reaped.
If the pamelad binary is killed during the PAM session, all PAM calls will return PAM_ABORT. The application should then just exit, or call pam_end() to free resources: nothing more can be done with the session.

Running

If your application runs as root, you can set the PAMELA_UID and PAMELA_GID environment variables to a non-zero numeric uid and a nonzero numeric gid prior to running it. The pamelad binary will then drop its privileges and run under this uid/gid.

My application is not working with pam_foobar.so!

A pamela-type architecture can only work if modules do not try to do anything fancy outside of the official PAM communication channels. In particular, if it sets global state, it will not work. PAM modules that

modify their process' environment
change their process' uid and gid
change their process' namespace
change the working directory
or any similar action impacting global data of the process

will not, and cannot, be supported by pamela. The only solution is to rewrite these modules so they communicate the change they wish to make via the official PAM API, and have the application perform the change itself. PAM provides a way to do this: the conversation function, which exchanges data between PAM and the application. Currently, only four types of messages are officially specified by PAM, but the mechanism is easily extensible and was designed for this. pamela fully supports customized conversation functions with any message type.