From: Peter Marschall <peter@adpm.de>
Date: Sun, 5 Apr 2020 12:20:57 +0000 (+0200)
Subject: ITS#9203 contrib/passwd/argon2: add manual page
X-Git-Tag: OPENLDAP_REL_ENG_2_4_50~12
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=997ff449f02751c512ffe2e2134673b468f11eb3;p=thirdparty%2Fopenldap.git

ITS#9203 contrib/passwd/argon2: add manual page

Add manual page slapd-pw-argon2.5 and make sure it gets installed.

Signed-off-by: Peter Marschall <peter@adpm.de>
---

diff --git a/contrib/slapd-modules/passwd/argon2/Makefile b/contrib/slapd-modules/passwd/argon2/Makefile
index b35d7a36f9..093bd8fb08 100644
--- a/contrib/slapd-modules/passwd/argon2/Makefile
+++ b/contrib/slapd-modules/passwd/argon2/Makefile
@@ -7,6 +7,7 @@ LDAP_LIB = $(LDAP_BUILD)/libraries/libldap_r/libldap_r.la \
 	$(LDAP_BUILD)/libraries/liblber/liblber.la
 
 LIBTOOL = $(LDAP_BUILD)/libtool
+INSTALL = /usr/bin/install
 CC = gcc
 OPT = -g -O2 -Wall
 #DEFS = -DSLAPD_ARGON2_DEBUG
@@ -27,6 +28,7 @@ $(error Unsupported implementation $(implementation))
 endif
 
 PROGRAMS = pw-argon2.la
+MANPAGES = slapd-pw-argon2.5
 LTVER = 0:0:0
 
 #prefix=/usr/local
@@ -38,6 +40,8 @@ ldap_subdir=/openldap
 libdir=$(exec_prefix)/lib
 libexecdir=$(exec_prefix)/libexec
 moduledir = $(libexecdir)$(ldap_subdir)
+mandir = $(exec_prefix)/share/man
+man5dir = $(mandir)/man5
 
 .SUFFIXES: .c .o .lo
 
@@ -53,8 +57,16 @@ pw-argon2.la: pw-argon2.lo
 clean:
 	rm -rf *.o *.lo *.la .libs
 
-install:	$(PROGRAMS)
+install: install-lib install-man FORCE
+
+install-lib: $(PROGRAMS)
 	mkdir -p $(DESTDIR)$(moduledir)
 	for p in $(PROGRAMS) ; do \
 		$(LIBTOOL) --mode=install cp $$p $(DESTDIR)$(moduledir) ; \
 	done
+
+install-man: $(MANPAGES)
+	mkdir -p  $(DESTDIR)$(man5dir)
+	$(INSTALL) -m 644 $(MANPAGES) $(DESTDIR)$(man5dir)
+
+FORCE:
diff --git a/contrib/slapd-modules/passwd/argon2/slapd-pw-argon2.5 b/contrib/slapd-modules/passwd/argon2/slapd-pw-argon2.5
new file mode 100644
index 0000000000..3bb6a43b4c
--- /dev/null
+++ b/contrib/slapd-modules/passwd/argon2/slapd-pw-argon2.5
@@ -0,0 +1,126 @@
+.TH SLAPD-PW-ARGON2 5 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" Copyright 2020 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
+.\" $OpenLDAP$
+.SH NAME
+slapd-pw-argon2 \- Argon2 password module to slapd
+.SH SYNOPSIS
+ETCDIR/slapd.conf
+.RS
+.LP
+.B moduleload pw-argon2
+.RI [ <parameters> ]
+.RE
+.SH DESCRIPTION
+.LP
+The
+.B pw-argon2
+module to
+.BR slapd (8)
+provides support for the use of the key derivation function Argon2,
+that was selected as the winner of the Password Hashing Competition in July 2015,
+in hashed passwords in OpenLDAP.
+.LP
+It does so by providing the additional password scheme
+.B {ARGON2}
+for use in slapd.
+
+.SH CONFIGURATION
+The
+.B pw-argon2
+module does not need any configuration,
+but it can be configured by giving the following parameters:
+.TP
+.BI m= <memory>
+Set memory usage to
+.I <memory>
+kiB.
+If not given, it defaults to
+.BR 4096 .
+.TP
+.BI p= <parallelism>
+Set parallelism to
+.I <parallelism>
+threads.
+If not given, it defaults to
+.BR 1 .
+.TP
+.BI t= <iterations>
+Set the number of iterations to
+.IR <iterations> .
+If not given, it defaults to
+.BR 3 .
+.LP
+After loading the module, the password scheme
+.B {ARGON2}
+will be recognised in values of the
+.I userPassword
+attribute.
+.LP
+You can then instruct OpenLDAP to use this scheme when processing
+the LDAPv3 Password Modify (RFC 3062) extended operations by using the
+.BR password-hash
+option in
+.BR slapd.conf (5):
+.RS
+.LP
+.B password\-hash {ARGON2}
+.RE
+.LP
+
+.SS NOTES
+If you want to use the scheme described here with
+.BR slappasswd (8),
+remember to load the module using its command line options.
+The relevant option/value is:
+.RS
+.LP
+.B \-o
+.BR module\-load = pw-argon2
+.LP
+.RE
+Depending on
+.BR pw-argon2 's
+location, you may also need:
+.RS
+.LP
+.B \-o
+.BR module\-path = \fIpathspec\fP
+.RE
+
+.SH EXAMPLES
+Both userPassword LDAP attributes below encode the password
+.RI ' secret '
+using different salts:
+.EX
+.LP
+userPassword: {ARGON2}$argon2i$v=19$m=4096,t=3,p=1$c2FsdHNhbHQ$DKlexoEJUoZTmkAAC3SaMWk30El9/RvVhlqGo6afIng
+.LP
+userPassword: {ARGON2}$argon2i$v=19$m=4096,t=3,p=1$c2FsdHNhbHRzYWx0$qOCkx9nMeFlaGOO4DUmPDgrlUbgMMuO9T1+vQCFuyzw
+.EE
+
+.SH SEE ALSO
+.BR slapd.conf (5),
+.BR ldappasswd (1),
+.BR slappasswd (8),
+.BR ldap (3),
+.LP
+.UR http://www.OpenLDAP.org/doc/
+"OpenLDAP Administrator's Guide"
+.UE
+.LP
+
+.SH ACKNOWLEDGEMENTS
+This manual page has been written by Peter Marschall based on the
+module's README file written by
+.MT simon@levermann.de
+Simon Levermann
+.ME .
+.LP
+.B OpenLDAP
+is developed and maintained by
+.UR http://www.openldap.org/
+The OpenLDAP Project
+.UE .
+.B OpenLDAP
+is derived from University of Michigan LDAP 3.3 Release.