diff options
| 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/building.html | |
| download | pamela-03012f54b1bcd31e0b817fc0222a9a47709c4018.tar.xz | |
Initial commit
Diffstat (limited to 'doc/building.html')
| -rw-r--r-- | doc/building.html | 103 |
1 files changed, 103 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> |