README.md

   1 Intro
   2 =====
   3
   4 This is just a simple PAM module and test code for it. There really isn't much to it, but it does make a good example of how to get started with a PAM module.
   5
   6 To build, either use the build scripts or use these commands:
   7
   8 **Build the PAM module**
   9
  10 `gcc -fPIC -fno-stack-protector -c src/mypam.c`
  11
  12 `sudo ld -x --shared -o /lib/security/mypam.so mypam.o`
  13
  14 The first command builds the object file in the current directory and the second links it with PAM. Since it's a shared library, PAM can use it on the fly without having to restart.
  15
  16 **Build Test**
  17
  18 `g++ -o pam_test src/test.c -lpam -lpam_misc`
  19
  20 OR
  21
  22 `gcc -o pam_test src/test.c -lpam -lpam_misc`
  23
  24 The test program is valid C, so it could be compiled using gcc or g++. I like g++ better because I'll probably want to extend it and I like C++ better.
  25
  26 Simple Usage
  27 ------------
  28
  29 The build scripts will take care of putting your module where it needs to be, `/lib/security`, so the next thing to do is edit config files.
  30
  31 The config files are located in `/etc/pam.d/` and the one I edited was `/etc/pam.d/common-auth`.
  32
  33 The test application tests auth and account functionality (although account isn't very interesting). At the top of the pam file (or anywhere), put these lines:
  34
  35         auth sufficient mypam.so
  36         account sufficient mypam.so
  37
  38 I think the account part should technically go in `/etc/pam.d/common-account`, but I put mine in the same place so I'd remember to take them out later.
  39
  40 To run the test program, just do: `pam_test backdoor` and you should get some messages saying that you're authenticated! Maybe this is how Sam Flynn 'hacked' his father's computer in TRON Legacy =D.
  41
  42 Resources
  43 =========
  44
  45 I found these resources especially helpful:
  46
  47 O'Reilly Guides:
  48 ----------------
  49
  50 These guides give brief overviews about PAM and how to write modules.  This is useful if you already have a little knowledge.
  51
  52 * [Writing PAM Modules, Part One](http://linuxdevcenter.com/pub/a/linux/2002/05/02/pam_modules.html)
  53 * [Writing PAM Modules, Part Two](http://linuxdevcenter.com/pub/a/linux/2002/05/23/pam_modules.html)
  54 * [Writing PAM Modules, Part Three](http://linuxdevcenter.com/pub/a/linux/2002/05/30/pam_modules.html)
  55
  56 Others
  57 ------
  58
  59 Good example for simple authentication.  I adapted this one in my simple PAM module.
  60
  61 [2-factor authentication & writing PAM modules](http://ben.akrin.com/?p=1068)
  62
  63 Gives an example program that uses PAM. I adapted this for testing my PAM module.
  64
  65 [Example PAM application](http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/adg-example.html)