From 1114ee9eee65ebb1d62ea611eefac3a782eaed2a Mon Sep 17 00:00:00 2001
From: Olav Morken <olav.morken@uninett.no>
Date: Tue, 24 Apr 2012 05:41:03 +0000
Subject: [PATCH] authcrypt: Add documentation.
Thanks to Dick Visser for writing this document.
git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@3075 44740490-163a-0410-bde0-09ae8108e29a
---
docs/simplesamlphp-idp.txt | 4 +-
docs/simplesamlphp-install.txt | 2 +
modules/authcrypt/docs/authcrypt.txt | 73 ++++++++++++++++++++++++++++
3 files changed, 77 insertions(+), 2 deletions(-)
create mode 100644 modules/authcrypt/docs/authcrypt.txt
diff --git a/docs/simplesamlphp-idp.txt b/docs/simplesamlphp-idp.txt
index 8f110f36e..940165397 100644
--- a/docs/simplesamlphp-idp.txt
+++ b/docs/simplesamlphp-idp.txt
@@ -28,10 +28,10 @@ Authentication module
The next step is to configure the way users authenticate on your IdP. Various modules in the `modules/` directory provides methods for authenticating your users. This is an overview of those that are included in the simpleSAMLphp distribution:
-`authcrypt:Hash`
+[`authcrypt:Hash`](./authcrypt:authcrypt)
: Username & password authentication with hashed passwords.
-`authcrypt:Htpasswd`
+[`authcrypt:Htpasswd`](./authcrypt:authcrypt)
: Username & password authentication against .htpasswd file.
[`authX509:authX509userCert`](./authX509:authX509)
diff --git a/docs/simplesamlphp-install.txt b/docs/simplesamlphp-install.txt
index abcba15d8..95142748b 100644
--- a/docs/simplesamlphp-install.txt
+++ b/docs/simplesamlphp-install.txt
@@ -126,6 +126,8 @@ file, `config.php`, right away:
'auth.adminpassword' => 'setnewpasswordhere',
+ Hashed passwords can also be used here. See the [`authcrypt`](./authcrypt:authcrypt) documentation for more information.
+
- Set a secret salt. This should be a random string. Some parts of the simpleSAMLphp needs this salt to generate cryptographically secure hashes. SimpleSAMLphp will give an error if the salt is not changed from the default value. The command below can help you to generated a random string on (some) unix systems:
tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=32 count=1 2>/dev/null;echo
diff --git a/modules/authcrypt/docs/authcrypt.txt b/modules/authcrypt/docs/authcrypt.txt
new file mode 100644
index 000000000..6c9f6eb26
--- /dev/null
+++ b/modules/authcrypt/docs/authcrypt.txt
@@ -0,0 +1,73 @@
+AuthCrypt
+=========
+
+This module provides two methods for authentication:
+
+`authcrypt:Hash`
+: Username & password authentication with hashed passwords.
+
+`authcrypt:Htpasswd`
+: Username & password authentication against an `.htpasswd` file.
+
+
+`authcrypt:Hash`
+----------------
+
+This is based on `exampleAuth:UserPass`, and adds support for hashed passwords.
+Hashes can be generated with the included command line tool `bin/pwgen.sh`.
+This tool will interactively ask for a password, a hashing algorithm , and whether or not you want to use a salt:
+
+ [user@server simplesamlphp]$ bin/pwgen.php
+ Enter password: hackme
+ The following hashing algorithms are available:
+ md2 md4 md5 sha1 sha224 sha256
+ sha384 sha512 ripemd128 ripemd160 ripemd256 ripemd320
+ whirlpool tiger128,3 tiger160,3 tiger192,3 tiger128,4 tiger160,4
+ tiger192,4 snefru snefru256 gost adler32 crc32
+ crc32b salsa10 salsa20 haval128,3 haval160,3 haval192,3
+ haval224,3 haval256,3 haval128,4 haval160,4 haval192,4 haval224,4
+ haval256,4 haval128,5 haval160,5 haval192,5 haval224,5 haval256,5
+
+ Which one do you want? [sha256]
+ Do you want to use a salt? (yes/no) [yes]
+
+ {SSHA256}y1mj3xsZ4/+LoQyPNVJzXUFfBcLHfwcHx1xxltxeQ1C5MeyEX/RxWA==
+
+Now create an authentication source in `config/authsources.php` and use the resulting string as the password:
+
+ 'example-hashed' => array(
+ 'authCrypt:Hash',
+ 'student:{SSHA256}y1mj3xsZ4/+LoQyPNVJzXUFfBcLHfwcHx1xxltxeQ1C5MeyEX/RxWA==' => array(
+ 'uid' => array('student'),
+ 'eduPersonAffiliation' => array('member', 'student'),
+ ),
+ ),
+
+This example creates a user `student` with password `hackme`, and some attributes.
+
+### Compatibility ###
+The generated hashes can also be used in `config.php` for the administrative password:
+
+ 'auth.adminpassword' => '{SSHA256}y1mj3xsZ4/+LoQyPNVJzXUFfBcLHfwcHx1xxltxeQ1C5MeyEX/RxWA==',
+
+Instead of generating hashes, you can also use existing ones from OpenLDAP, provided that the `userPassword` attribute is stored as MD5, SMD5, SHA, or SSHA.
+
+
+`authCrypt:Htpasswd`
+--------------------
+
+Authenticate users against an [`.htpasswd`](http://httpd.apache.org/docs/2.2/programs/htpasswd.html) file. It can be used for example when you migrate a web site from basic HTTP authentication to simpleSAMLphp.
+
+The simple structure of the `.htpasswd` file does not allow for per-user attributes, but you can define some static attributes for all users.
+
+An example authentication source in `config/authsources.php` could look like this:
+
+ 'htpasswd' => array(
+ 'authcrypt:Htpasswd',
+ 'htpasswd_file' => '/var/www/foo.edu/legacy_app/.htpasswd',
+ 'static_attributes' => array(
+ 'eduPersonAffiliation' => array('member', 'employee'),
+ 'Organization' => array('University of Foo'),
+ ),
+ ),
+
--
GitLab