git.sur5r.net Git - openldap/blob - contrib/slapd-modules/passwd/sha2/README

   1 SHA-512 OpenLDAP support
   2 ------------------------
   3
   4 slapd-sha2.c provides support for SHA-512, SHA-384 and SHA-256 hashed passwords in
   5 OpenLDAP. For instance, one could have the LDAP attribute:
   6
   7 userPassword: {SHA512}vSsar3708Jvp9Szi2NWZZ02Bqp1qRCFpbcTZPdBhnWgs5WtNZKnvCXdhztmeD2cmW192CF5bDufKRpayrW/isg==
   8
   9 or:
  10
  11 userPassword: {SHA384}WKd1ukESvjAFrkQHznV9iP2nHUBJe7gCbsrFTU4//HIyzo3jq1rLMK45dg/ufFPt
  12
  13 or:
  14
  15 userPassword: {SHA256}K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=
  16
  17 all of which encode the password 'secret'.
  18
  19
  20 Building
  21 --------
  22
  23 1) Customize the OPENLDAP variable in Makefile to point to the OpenLDAP
  24 source root.
  25
  26 For initial testing you might also want to edit CCFLAGS to define
  27 SLAPD_SHA2_DEBUG, which enables logging to stderr (don't leave this on
  28 in production, as it prints passwords in cleartext).
  29
  30 2) Run 'make' to produce slapd-sha2.so
  31
  32 3) Copy slapd-sha2.so somewhere permanent.
  33
  34 4) Edit your slapd.conf (eg. /etc/ldap/slapd.conf), and add:
  35
  36 moduleload ...path/to/slapd-sha2.so
  37
  38 5) Restart slapd.
  39
  40
  41 Configuring
  42 -----------
  43
  44 The {SHA256}, {SHA384} and {SHA512} password schemes should now be recognised.
  45
  46 You can also tell OpenLDAP to use one of these new schemes when processing LDAP
  47 Password Modify Extended Operations, thanks to the password-hash option in
  48 slapd.conf. For example:
  49
  50 password-hash   {SHA256}
  51
  52
  53 Testing
  54 -------
  55
  56 A quick way to test whether it's working is to customize the rootdn and
  57 rootpw in slapd.conf, eg:
  58
  59 rootdn          "cn=admin,dc=example,dc=com"
  60 # This encrypts the string 'secret'
  61
  62 rootpw  {SHA256}K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=
  63
  64 Then to test, run something like:
  65
  66 ldapsearch -b "dc=example,dc=com" -D "cn=admin,dc=example,dc=com" -x -w secret
  67
  68
  69 -- Test hashes:
  70
  71 Test hashes can be generated with openssl:
  72
  73 $ echo -n "secret" | openssl dgst -sha256 -binary | openssl enc -base64
  74 K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=
  75 $ echo -n "secret" | openssl dgst -sha384 -binary | openssl enc -base64
  76 WKd1ukESvjAFrkQHznV9iP2nHUBJe7gCbsrFTU4//HIyzo3jq1rLMK45dg/ufFPt
  77 $ echo -n "secret" | openssl dgst -sha512 -binary | openssl enc -base64
  78 vSsar3708Jvp9Szi2NWZZ02Bqp1qRCFpbcTZPdBhnWgs5WtNZKnvCXdhztmeD2cm
  79 W192CF5bDufKRpayrW/isg==
  80
  81 (join those lines up to form the full hash)
  82
  83
  84
  85 Alternatively we could modify an existing user's password with
  86 ldapmodify, and then test binding as that user:
  87
  88 $ ldapmodify -D "cn=admin,dc=example,dc=com" -x -W
  89 Enter LDAP Password:
  90 dn: uid=jturner,ou=People,dc=example,dc=com
  91 changetype: modify
  92 replace: userPassword
  93 userPassword: {SHA512}vSsar3708Jvp9Szi2NWZZ02Bqp1qRCFpbcTZPdBhnWgs5WtNZKnvCXdhztmeD2cmW192CF5bDufKRpayrW/isg==
  94
  95 modifying entry "uid=jturner,ou=People,dc=example,dc=com"
  96
  97 $ ldapsearch -b "dc=example,dc=com" -D "uid=jturner,ou=People,dc=example,dc=com" -x -w secret
  98
  99
 100 Debugging
 101 ---------
 102
 103 To see what's going on, recompile with SLAPD_SHA2_DEBUG (use the
 104 commented-out CCFLAGS in Makefile), and then run slapd from the console
 105 to see stderr:
 106
 107 $ sudo /etc/init.d/slapd stop
 108 Stopping OpenLDAP: slapd.
 109 $ sudo /usr/sbin/slapd -f /etc/ldap/slapd.conf -h ldap://localhost:389 -d 256
 110 @(#) $OpenLDAP$
 111         buildd@palmer:/build/buildd/openldap2.3-2.4.9/debian/build/servers/slapd
 112 /etc/ldap/slapd.conf: line 123: rootdn is always granted unlimited privileges.
 113 /etc/ldap/slapd.conf: line 140: rootdn is always granted unlimited privileges.
 114 slapd starting
 115 ...
 116 Validating password
 117   Password to validate: secret
 118   Hashes to: K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=
 119   Stored password scheme: {SHA256}
 120   Stored password value: K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=
 121   -> Passwords match
 122 conn=0 op=0 BIND dn="cn=admin,dc=example,dc=com" mech=SIMPLE ssf=0
 123 conn=0 op=0 RESULT tag=97 err=0 text=
 124 conn=0 op=1 SRCH base="dc=example,dc=com" scope=2 deref=0 filter="(objectClass=*)"
 125 conn=0 fd=12 closed (connection lost)
 126
 127 ---
 128
 129 This work is part of OpenLDAP Software <http://www.openldap.org/>.
 130
 131 Copyright 2009-2011 The OpenLDAP Foundation.
 132 All rights reserved.
 133
 134 Redistribution and use in source and binary forms, with or without
 135 modification, are permitted only as authorized by the OpenLDAP
 136 Public License.
 137
 138 A copy of this license is available in the file LICENSE in the
 139 top-level directory of the distribution or, alternatively, at
 140 <http://www.OpenLDAP.org/license.html>.
 141
 142 ---
 143
 144 ACKNOWLEDGEMENT:
 145 This work was initially developed by Jeff Turner for inclusion in
 146 OpenLDAP Software, based upon the SHA2 implementation independently
 147 developed by Aaron Gifford.
 148