From 03012f54b1bcd31e0b817fc0222a9a47709c4018 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sun, 4 Feb 2018 23:22:53 +0000 Subject: Initial commit --- doc/building.html | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 doc/building.html (limited to 'doc/building.html') diff --git a/doc/building.html b/doc/building.html new file mode 100644 index 0000000..649dc43 --- /dev/null +++ b/doc/building.html @@ -0,0 +1,103 @@ + + + + + + pamela: building an application + + + + + + +

+pamela
+Software
+skarnet.org +

+ +

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.

+ + + -- cgit v1.3.1