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 ++++++++++++++++++++++++++++++++++++++++ doc/index.html | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/pamelad.html | 68 +++++++++++++++++++++++++++ doc/upgrade.html | 28 +++++++++++ 4 files changed, 337 insertions(+) create mode 100644 doc/building.html create mode 100644 doc/index.html create mode 100644 doc/pamelad.html create mode 100644 doc/upgrade.html (limited to 'doc') 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.

+ + + diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..3c2f58c --- /dev/null +++ b/doc/index.html @@ -0,0 +1,138 @@ + + + + + + + pamela - a secure PAM implementation + + + + + + +

+Software
+skarnet.org +

+ +

pamela

+ +

don't crack this root of mine

+ +

What is it ?

+ +

+ pamela stands for PAM Encapsulated Loading Architecture. +

+ +

+ It is a library implementing Linux-PAM's +security/pam_appl.h +header, for applications to use instead of the default Linux-PAM +security/pam_appl.h header. pamela wraps all PAM calls and +deports them to a pamelad binary running +as a child of the application, which performs the real calls to +Linux-PAM. +

+ +

+ The advantage of this setup is that it reduces the application's +attack surface considerably. Instead of loading modules into the +application's address space, PAM loads modules into the small, +dedicated pamelad binary, whose main source code is less than 400 +lines long. Also, if the application runs as root, the pamelad +binary can run as an unprivileged user, so modules cannot be used +for privilege elevation. +

+ +

Installation

+ +

Requirements

+ +

A POSIX-compliant system with a standard C development environment, +that supports Linux-PAM - (so, probably a Linux system)
GNU make, version 3.81 or later
skalibs version +2.6.3.2 or later. It's a build-time requirement and a run-time +requirement.
Linux-PAM version 1.3.0 +or later. It's a build-time requirement and a run-time requirement.

+ +

Licensing

+ +

+ pamela is free software. It is available under the +ISC license. +

+ +

Download

+ +

+ pamela is a work in progress: there is no numbered version yet.
You can checkout a copy of the +pamela +git repository: +
```
 git clone git://git.skarnet.org/pamela 
```
There's also a +GitHub mirror +of the utmps git repository.

+ +

Compilation

+ +

See the enclosed INSTALL file for installation details.
Please note that the build process expects security/pam_appl.h +to be a Linux-PAM header. Because of this, pamela's make install +does not overwrite security/pam_appl.h; instead, the header +exposing PAM functionality is named pamela/pam.h. When you are +positive you can replace the security/pam_appl.h header, +the make install-symlink command will do it for you.

+ +

Upgrade notes

+ +

This page lists the differences to be aware of between +the previous versions of pamela and the current one.

+ +

Reference

+ +

Commands

+ +

The pamelad internal program

+ +

Libraries

+ +

How to build an application with pamela
The +public interface to Linux-PAM is implemented by the pamela library.

+ +

+ + +

Related resources

+ + +

pamela discussion

+ +

pamela is discussed on the +skaware mailing-list.

+ + + diff --git a/doc/pamelad.html b/doc/pamelad.html new file mode 100644 index 0000000..5d93c27 --- /dev/null +++ b/doc/pamelad.html @@ -0,0 +1,68 @@ + + + + + + pamela: the pamelad internal program + + + + + + +

+pamela
+Software
+skarnet.org +

+ +

The pamelad program

+ +

+pamelad is a helper program spawned by the pamela library, at pam_start() time. +It communicates with the main application process, reading requests from it, +performing PAM calls, and returning results to the application process. +

+ +

Interface

+ +

+ pamelad is not meant to be called directly. It is an unexported +program, i.e. a program that the package's library is supposed to find, but +that users should not run. Ideally it's kept outside of users' PATH variable. +

+ +

+ pamelad is declared as a libexec binary, so it will probably be +installed in /usr/libexec/pamelad or /usr/lib/pamela/pamelad, +depending on the admin/distribution's preferences. +

+ +

+ pamelad is run with two arguments, which are the service_name and +user arguments given to the pam_start() call. This will +display in a ps output, which is fine since this information is +not confidential. +

+ +

+ pamelad runs as the same uid and gid as the application. However, to +increase security of applications running as root: +

+ +

If the application runs as gid 0 and the PAMELA_GID environment +variable is set, then pamelad will run with a gid set to $PAMELA_GID.
If the application runs as uid 0 and the PAMELA_UID environment +variable is set, then pamelad will run with a uid set to $PAMELA_UID.

+ +

+ pamelad makes the real calls to Linux-PAM. Keep that in mind when +configuring your PAM authorizations: if you're using the PAMELA_UID and +PAMELA_GID variables, make sure the uid/gid are not used anywhere else, +and give the proper PAM authorizations to that uid/gid pair instead of root. +

+ + + diff --git a/doc/upgrade.html b/doc/upgrade.html new file mode 100644 index 0000000..2d4ba44 --- /dev/null +++ b/doc/upgrade.html @@ -0,0 +1,28 @@ + + + + + + How to upgrade pamela + + + + + + +

+pamela
+Software
+skarnet.org +

+ +

What has changed in pamela

+ +

in 0.0.1.0

+ +

+ Initial release. +

+ + + -- cgit v1.2.3