ITS#8205 - contrib/smbk5pwd: add man page, install it too

[openldap] / contrib / slapd-modules / passwd / totp / slapo-totp.5

diff --git a/contrib/slapd-modules/passwd/totp/slapo-totp.5 b/contrib/slapd-modules/passwd/totp/slapo-totp.5
new file mode 100644 (file)
index 0000000..de590e6
--- /dev/null
+++ b/contrib/slapd-modules/passwd/totp/slapo-totp.5
@@ -0,0 +1,131 @@
+.TH SLAPO-TOTP 5 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" Copyright 2015 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
+.\" $OpenLDAP$
+.SH NAME
+slapo-totp \- TOTP password support overlay to slapd
+.SH SYNOPSIS
+ETCDIR/slapd.conf
+.RS
+.LP
+moduleload
+.B lastbind
+.LP
+moduleload
+.B totp
+.LP
+...
+.LP
+database ...
+.LP
+...
+.LP
+overlay
+.B lastbind
+.LP
+overlay
+.B totp
+.RE
+.SH DESCRIPTION
+.LP
+The
+.B totp
+overlay to
+.BR slapd (8)
+provides support for RFC 6238 TOTP Time-based One
+Time Passwords in OpenLDAP using SHA-1, SHA-256, and SHA-512 hashes.
+.LP
+It does so by providing the following additional password schemes for use in slapd:
+.RS
+.TP
+.B {TOTP1}
+TOTP with SHA-1 as hash function.
+This algorithm is compatible with Google Authenticator.
+.TP
+.B {TOTP256}
+TOTP with SHA-256 as hash function
+.TP
+.B {TOTP512}
+TOTP with SHA-512 as hash function
+.RE
+
+.SH CONFIGURATION
+The
+.B totp
+overlay does not need any configuration beyond loading the module and
+defining it as an overlay where the users reside.
+.LP
+After that, the password schemes
+{TOTP1}, {TOTP256}, and {TOTP512}
+will be recognised in values of the
+.I userPassword
+attribute.
+.LP
+You can then instruct OpenLDAP to use these schemes when processing
+the LDAPv3 Password Modify (RFC 3062) extended operations by using the
+.BR password-hash
+option in
+.BR slapd.conf (5).
+
+.SH NOTES
+When using the
+.B lastbind
+overlay together with the
+.B totp
+overlay, the former one needs to be loaded first.
+.LP
+If you want to use the schemes described here with
+.BR slappasswd (8),
+don't forget to load the module using its command line options.
+The relevant option/value is:
+.RS
+.LP
+.B \-o
+.BR module\-load = totp
+.LP
+.RE
+Depending on
+.BR totp 's
+location, you may also need:
+.RS
+.LP
+.B \-o
+.BR module\-path = \fIpathspec\fP
+.RE
+
+
+.SH EXAMPLES
+For instance, one could have the LDAP attribute:
+.LP
+.EX
+userPassword: {TOTP1}GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
+.EE
+.LP
+which encodes the key
+.RB ' 12345678901234567890 '.
+.LP
+To make {TOTP1} the password algorithm used in Password Modify extended operations,
+simply set this line in slapd.conf(5):
+.LP
+.EX
+password-hash   {TOTP1}
+.EX
+
+.SH SEE ALSO
+.BR slapd.conf (5),
+.BR ldappasswd (1),
+.BR slappasswd (8),
+.BR ldap (3),
+.LP
+"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
+.LP
+
+.SH ACKNOWLEDGEMENTS
+This manual page has been writen by Peter Marschall based on the
+module's README file written by Howard Chu.
+.LP
+.B OpenLDAP
+is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
+.B OpenLDAP
+is derived from University of Michigan LDAP 3.3 Release.
+