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

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