From 855e82ba6d0f4d0216ffb4ac5eb7c40d3613ccc7 Mon Sep 17 00:00:00 2001 From: Howard Chu Date: Sat, 19 Feb 2011 00:03:06 +0000 Subject: [PATCH] ITS#6839 TLS/ldapi/SASL-EXTERNAL notes from Andrew Findlay --- doc/guide/admin/runningslapd.sdf | 23 ++++++++++++++++- doc/guide/admin/sasl.sdf | 42 +++++++++++++++++++++++++++++--- doc/guide/preamble.sdf | 1 + doc/man/man8/slapd.8 | 16 ++++++++++++ 4 files changed, 78 insertions(+), 4 deletions(-) diff --git a/doc/guide/admin/runningslapd.sdf b/doc/guide/admin/runningslapd.sdf index 76d44c327c..30e0204e2c 100644 --- a/doc/guide/admin/runningslapd.sdf +++ b/doc/guide/admin/runningslapd.sdf @@ -36,7 +36,16 @@ This option specifies alternative listener configurations. The default is {{EX:ldap:///}} which implies {{TERM:LDAP}} over {{TERM:TCP}} on all interfaces on the default LDAP port 389. You can specify specific host-port pairs or other protocol schemes (such -as {{EX:ldaps://}} or {{EX:ldapi://}}). For example, {{EX:-h +as {{EX:ldaps://}} or {{EX:ldapi://}}). + +!block table +URL Protocol Transport +ldap:/// LDAP TCP port 389 +ldaps:/// LDAP over SSL TCP port 636 +ldapi:/// LDAP IPC (Unix-domain socket) +!endblock + +For example, {{EX:-h "ldaps:// ldap://127.0.0.1:666"}} will create two listeners: one for the (non-standard) {{EX:ldaps://}} scheme on all interfaces on the default {{EX:ldaps://}} port 636, and one for the standard @@ -45,6 +54,18 @@ on port 666. Hosts may be specified using using hostnames or {{TERM:IPv4}} or {{TERM:IPv6}} addresses. Port values must be numeric. +For LDAP over IPC, the pathname of the Unix-domain socket can be encoded +in the URL. Note that directory separators must be +URL-encoded, like any other characters that are special to URLs. +Thus the socket {{EX:/usr/local/var/ldapi}} must be encoded as + +> ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi + +ldapi: is described in detail in {{Using LDAP Over IPC Mechanisms}} [{{REF:Chu-LDAPI}}] + +Note that the ldapi:/// transport is not widely implemented: non-OpenLDAP clients +may not be able to use it. + > -n This option specifies the service name used for logging and diff --git a/doc/guide/admin/sasl.sdf b/doc/guide/admin/sasl.sdf index daf6123baf..6dde65b3f3 100644 --- a/doc/guide/admin/sasl.sdf +++ b/doc/guide/admin/sasl.sdf @@ -72,10 +72,13 @@ and large enterprises. Use of {{SECT:GSSAPI}} and {{SECT:KERBEROS_V4}} are discussed below. The EXTERNAL mechanism utilizes authentication services provided -by lower level network services such as {{TERM:TLS}} (TLS). When +by lower level network services such as {{TERM[expand]TLS}} ({{TERM:TLS}}). When used in conjunction with {{TERM:TLS}} {{TERM:X.509}}-based public -key technology, EXTERNAL offers strong authentication. Use of -EXTERNAL is discussed in the {{SECT:Using TLS}} chapter. +key technology, EXTERNAL offers strong authentication. +TLS is discussed in the {{SECT:Using TLS}} chapter. + +EXTERNAL can also be used with the {{EX:ldapi:///}} transport, as +Unix-domain sockets can report the UID and GID of the client process. There are other strong authentication mechanisms to choose from, including {{TERM:OTP}} (one time passwords) and {{TERM:SRP}} (secure @@ -289,6 +292,39 @@ The server will infer an authorization identity from authentication identity (as described below). +H3: EXTERNAL + +The SASL EXTERNAL mechanism makes use of an authentication performed +by a lower-level protocol: usually {{TERM:TLS}} or Unix {{TERM:IPC}} + +Each transport protocol returns Authentication Identities in its own +format: + +H4: TLS Authentication Identity Format + +This is usually the Subject DN from the client-side certificate. +The order of the components will be changed to follow LDAP conventions, +so a certificate issued to {{EX:C=gb, O=The Example Organisation, CN=A Person}} +will produce an authentication identity of: + +> cn=A Person,o=The Example Organisation,c=gb + +Note that you must set a suitable value for TLSVerifyClient to make the server +request the use of a client-side certificate. Without this, the SASL EXTERNAL +mechanism will not be offered. +Refer to the {{SECT:Using TLS}} chapter for details. + +H4: IPC (ldapi:///) Identity Format + +This is formed from the Unix UID and GID of the client process: + +> gidNumber=+uidNumber=,cn=peercred,cn=external,cn=auth + +Thus, a client process running as {{EX:root}} will be: + +> gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth + + H3: Mapping Authentication Identities The authentication mechanism in the slapd server will use SASL diff --git a/doc/guide/preamble.sdf b/doc/guide/preamble.sdf index afa7870d9c..0bbbf9478c 100644 --- a/doc/guide/preamble.sdf +++ b/doc/guide/preamble.sdf @@ -308,4 +308,5 @@ RFC4518|PS|Lightweight Directory Access Protocol (LDAP): Internationalized Strin RFC4519|PS|Lightweight Directory Access Protocol (LDAP): Schema for User Applications|http://www.rfc-editor.org/rfc/rfc4519.txt RFC4520|BCP|IANA Considerations for LDAP|http://www.rfc-editor.org/rfc/rfc4520.txt RFC4533|X|The Lightweight Directory Access Protocol (LDAP) Content Synchronization Operation|http://www.rfc-editor.org/rfc/rfc4533.txt +Chu-LDAPI|ID|Using LDAP Over IPC Mechanisms|http://tools.ietf.org/html/draft-chu-ldap-ldapi-00 !endblock diff --git a/doc/man/man8/slapd.8 b/doc/man/man8/slapd.8 index c5ae6370ce..89b4ce8f21 100644 --- a/doc/man/man8/slapd.8 +++ b/doc/man/man8/slapd.8 @@ -193,6 +193,22 @@ options. Hosts may be specified by name or IPv4 and IPv6 address formats. Ports, if specified, must be numeric. The default ldap:// port is \fB389\fP and the default ldaps:// port is \fB636\fP. +For LDAP over IPC, +.B name +is the name of the socket, and no +.B port +is required, nor allowed; note that directory separators must be +URL-encoded, like any other characters that are special to URLs; +so the socket + + /usr/local/var/ldapi + +must be specified as + + ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi + +The default location for the IPC socket is LOCALSTATEDIR/run/ldapi + The listener permissions are indicated by "x\-mod=\-rwxrwxrwx", "x\-mod=0777" or "x\-mod=777", where any of the "rwx" can be "\-" to suppress the related permission, while any -- 2.39.5