Initial commit

author: Laurent Bercot <ska-skaware@skarnet.org> 2018-02-04 23:22:53 +0000
committer: Laurent Bercot <ska-skaware@skarnet.org> 2018-02-04 23:22:53 +0000
commit: 03012f54b1bcd31e0b817fc0222a9a47709c4018 (patch)
tree: d53c568d1e14bae1e1e0efadab8b0bf3e66982aa /doc
download: pamela-03012f54b1bcd31e0b817fc0222a9a47709c4018.tar.xz
4 files changed, 337 insertions, 0 deletions
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 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>pamela: building an application</title>
+    <meta name="Description" content="pamela: building an application" />
+    <meta name="Keywords" content="pamela PAM Linux-PAM library" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">pamela</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> Building an application with pamela instead of Linux-PAM </h1>
+
+<h2> Prerequisites </h2>
+
+<ul>
+ <li> The pamela package must have been properly built and installed;
+in particular, the <a href="pamelad.html">pamelad</a> binary must
+have been properly linked against Linux-PAM's <tt>libpam.so</tt>. </li>
+ <li> The <tt>security/pam_appl.h</tt> header, usually installed in
+<tt>/usr/include</tt>, must be a symlink to pamela's
+<tt>pamela/pam.h</tt> header. This can be achieved by running
+<tt>make install-symlink</tt> after <tt>make install</tt> when
+building the pamela package. </li>
+ <li> The application must strictly follow the
+<a href="http://www.linux-pam.org/Linux-PAM-html/adg-interface-by-app-expected.html">Linux-PAM
+specification</a>. Note that the page claims that the
+<tt>pam_set_item()</tt> function is declared in <tt>security/pam_modules.h</tt>,
+but it is a mistake: like every PAM function used by applications, it
+is declared in <tt>security/pam_appl.h</tt>. </li>
+ <li> The pamela headers and library must be installed, as well as the
+<a href="//skarnet.org/software/skalibs/">skalibs</a> headers and library. </li>
+</ul>
+
+<h2> Compiling </h2>
+
+<ul>
+ <li> Make sure that the pamela headers and the skalibs headers
+are visible in your header search path, and that the
+Linux-PAM headers <em>are not</em>. </li>
+ <li> 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. </li>
+</ul>
+
+<h2> Linking </h2>
+
+<ul>
+ <li> Make sure the pamela library, as well as the skalibs
+library, are visible in your library search path. </li>
+ <li> Do not add <tt>-lpam</tt> to your linking command line.
+Instead, add <tt>-lpamela -lskarnet</tt>. Depending on the
+libc you're using, you may have to add <tt>-lrt</tt> too. </li>
+ <li> 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
+<a href="pamelad.html">pamelad</a> 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. </li>
+ <li> Check your application binary's dynamic library dependencies
+after it has been built. If your binary depends on <tt>libpam</tt>,
+it has been incorrectly made! Your binary should depend on
+<tt>libpamela</tt> and <tt>libskarnet</tt>, but not <tt>libpam</tt>.
+If you have chosen to link against the static version of pamela
+and skalibs, you may not even see the <tt>libpamela</tt> and
+<tt>libskarnet</tt> dependencies. </li>
+</ul>
+
+<h2> Programming </h2>
+
+<ul>
+ <li> pamela strictly implements the
+<a href="http://www.linux-pam.org/Linux-PAM-html/adg-interface-by-app-expected.html">Linux-PAM
+API</a> </li>
+ <li> The <tt>pam_start()</tt> function will spawn a
+<a href="pamelad.html">pamelad</a> binary running as a child of
+the application, until <tt>pam_end()</tt> is called. At that point
+the zombie is reaped. </li>
+ <li> If the <a href="pamelad.html">pamelad</a> binary is killed
+during the PAM session, all PAM calls will return PAM_ABORT.
+The application should then just exit, or call <tt>pam_end()</tt>
+to free resources: nothing more can be done with the session. </li>
+</ul>
+
+<h2> Running </h2>
+
+<ul>
+ <li> 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 <a href="pamelad.html">pamelad</a> binary will then drop
+its privileges and run under this uid/gid. </li>
+</ul>
+
+</body>
+</html>
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 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>pamela - a secure PAM implementation</title>
+    <meta name="Description" content="pamela - a secure PAM implementation" />
+    <meta name="Keywords" content="pamela PAM linux pluggable authentication modules unix login laurent bercot skarnet" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> pamela </h1>
+
+<p style="text-align:right;"><small><em>don't crack this root of mine</em></small></p>
+
+<h2> What is it&nbsp;? </h2>
+
+<p>
+ pamela stands for PAM Encapsulated Loading Architecture.
+</p>
+
+<p>
+ It is a library implementing Linux-PAM's
+<a href="http://www.linux-pam.org/Linux-PAM-html/adg-interface-by-app-expected.html"><tt>security/pam_appl.h</tt></a>
+header, for applications to use instead of the default Linux-PAM
+<tt>security/pam_appl.h</tt> header. pamela wraps all PAM calls and
+deports them to a <a href="pamelad.html">pamelad</a> binary running
+as a child of the application, which performs the real calls to
+Linux-PAM.
+</p>
+
+<p>
+ 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.
+</p>
+
+<hr />
+
+<h2> Installation </h2>
+
+<h3> Requirements </h3>
+
+<ul>
+ <li> A POSIX-compliant system with a standard C development environment,
+that supports Linux-PAM - (so, probably a Linux system) </li>
+ <li> GNU make, version 3.81 or later </li>
+ <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> version
+2.6.3.2 or later. It's a build-time requirement and a run-time
+requirement. </li>
+ <li> <a href="http://www.linux-pam.org/">Linux-PAM</a> version 1.3.0
+or later. It's a build-time requirement and a run-time requirement. </li>
+</ul>
+
+<h3> Licensing </h3>
+
+<p>
+ pamela is free software. It is available under the
+<a href="http://opensource.org/licenses/ISC">ISC license</a>.
+</p>
+
+<h3> Download </h3>
+
+<ul>
+ <li> <!-- The current released version of pamela is <a href="pamela-0.0.1.0.tar.gz">0.0.1.0</a>. -->
+ pamela is a work in progress: there is no numbered version yet. </li>
+ <li> You can checkout a copy of the
+<a href="//git.skarnet.org/cgi-bin/cgit.cgi/pamela/">pamela
+git repository</a>:
+<pre> git clone git://git.skarnet.org/pamela </pre> </li>
+ <li> There's also a
+<a href="https://github.com/skarnet/pamela">GitHub mirror</a>
+of the utmps git repository. </li>
+</ul>
+
+<h3> Compilation </h3>
+
+<ul>
+ <li> See the enclosed INSTALL file for installation details. </li>
+ <li> Please note that the build process expects <tt>security/pam_appl.h</tt>
+to be a Linux-PAM header. Because of this, pamela's <tt>make install</tt>
+does not overwrite <tt>security/pam_appl.h</tt>; instead, the header
+exposing PAM functionality is named <tt>pamela/pam.h</tt>. When you are
+positive you can replace the <tt>security/pam_appl.h</tt> header,
+the <tt>make install-symlink</tt> command will do it for you. </li>
+</ul>
+
+<h3> Upgrade notes </h3>
+
+<ul>
+ <li> <a href="upgrade.html">This page</a> lists the differences to be aware of between
+the previous versions of pamela and the current one. </li>
+</ul>
+
+<hr />
+
+<h2> Reference </h2>
+
+<h3> Commands </h3>
+
+<ul>
+<li><a href="pamelad.html">The <tt>pamelad</tt> internal program</a></li>
+</ul>
+
+<h3> Libraries </h3>
+
+<ul>
+<li> <a href="building.html">How to build an application with pamela</a> </li>
+<li> <a href="http://www.linux-pam.org/Linux-PAM-html/adg-interface-by-app-expected.html">The
+public interface to Linux-PAM</a> is implemented by the pamela library. </li>
+</ul>
+
+<hr />
+
+<a name="related">
+<h2> Related resources </h2>
+</a>
+
+<h3> pamela discussion </h3>
+
+<ul>
+ <li> <tt>pamela</tt> is discussed on the
+<a href="//skarnet.org/lists.html#skaware">skaware</a> mailing-list. </li>
+</ul>
+
+</body>
+</html>
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 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>pamela: the pamelad internal program</title>
+    <meta name="Description" content="pamela: the pamelad internal program" />
+    <meta name="Keywords" content="pamela command pamelad program internal libexec PAM module loader" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">pamela</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The pamelad program </h1>
+
+<p>
+pamelad is a helper program spawned by the pamela library, at <tt>pam_start()</tt> time.
+It communicates with the main application process, reading requests from it,
+performing PAM calls, and returning results to the application process.
+</p>
+
+<h2> Interface </h2>
+
+<p>
+ pamelad is not meant to be called directly. It is an <em>unexported</em>
+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.
+</p>
+
+<p>
+ pamelad is declared as a <em>libexec</em> binary, so it will probably be
+installed in <tt>/usr/libexec/pamelad</tt> or <tt>/usr/lib/pamela/pamelad</tt>,
+depending on the admin/distribution's preferences.
+</p>
+
+<p>
+ pamelad is run with two arguments, which are the <em>service_name</em> and
+<em>user</em> arguments given to the <tt>pam_start()</tt> call. This will
+display in a <tt>ps</tt> output, which is fine since this information is
+not confidential.
+</p>
+
+<p>
+ pamelad runs as the same uid and gid as the application. However, to
+increase security of applications running as root:
+</p>
+
+<ul>
+ <li> If the application runs as gid 0 and the PAMELA_GID environment
+variable is set, then pamelad will run with a gid set to <tt>$PAMELA_GID</tt>. </li>
+ <li> If the application runs as uid 0 and the PAMELA_UID environment
+variable is set, then pamelad will run with a uid set to <tt>$PAMELA_UID</tt>. </li>
+</ul>
+
+<p>
+ 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.
+</p>
+
+</body>
+</html>
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 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>How to upgrade pamela</title>
+    <meta name="Description" content="How to upgrade pamela" />
+    <meta name="Keywords" content="pamela installation upgrade" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">pamela</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> What has changed in pamela </h1>
+
+<h2> in 0.0.1.0 </h2>
+
+<p>
+ Initial release.
+</p>
+
+</body>
+</html>
author	Laurent Bercot <ska-skaware@skarnet.org>	2018-02-04 23:22:53 +0000
committer	Laurent Bercot <ska-skaware@skarnet.org>	2018-02-04 23:22:53 +0000
commit	03012f54b1bcd31e0b817fc0222a9a47709c4018 (patch)
tree	d53c568d1e14bae1e1e0efadab8b0bf3e66982aa /doc
download	pamela-03012f54b1bcd31e0b817fc0222a9a47709c4018.tar.xz