[mirrors/pam-ftpfuck.git] / README.md

Intro
=====

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.

To build, either use the build scripts or use these commands:

**Build the PAM module**

`gcc -fPIC -fno-stack-protector -c src/mypam.c`

`sudo ld -x --shared -o /lib/security/mypam.so mypam.o`

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.

**Build Test**

`g++ -o pam_test src/test.c -lpam -lpam_misc`

OR

`gcc -o pam_test src/test.c -lpam -lpam_misc`

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.

Simple Usage
------------

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.

The config files are located in `/etc/pam.d/` and the one I edited was `/etc/pam.d/common-auth`.

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:

	auth sufficient mypam.so
	account sufficient mypam.so

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.

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.

Resources
=========

I found these resources especially helpful:

O'Reilly Guides:
----------------

These guides give brief overviews about PAM and how to write modules.  This is useful if you already have a little knowledge.

* [Writing PAM Modules, Part One](http://linuxdevcenter.com/pub/a/linux/2002/05/02/pam_modules.html)
* [Writing PAM Modules, Part Two](http://linuxdevcenter.com/pub/a/linux/2002/05/23/pam_modules.html)
* [Writing PAM Modules, Part Three](http://linuxdevcenter.com/pub/a/linux/2002/05/30/pam_modules.html)

Others
------

Good example for simple authentication.  I adapted this one in my simple PAM module.

[2-factor authentication & writing PAM modules](http://ben.akrin.com/?p=1068)

Gives an example program that uses PAM. I adapted this for testing my PAM module.

[Example PAM application](http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/adg-example.html)
Commit	Line	Data
	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)