Merge remote branch 'origin/mdb.master' into OPENLDAP_REL_ENG_2_4

[openldap] / doc / guide / admin / sasl.sdf

diff --git a/doc/guide/admin/sasl.sdf b/doc/guide/admin/sasl.sdf
index daf6123bafde32b7c64ad3ca835ee501dcddb58f..9f8a7a66cd3eb0a12b66294dc34a5e98997078b2 100644 (file)
--- a/doc/guide/admin/sasl.sdf
+++ b/doc/guide/admin/sasl.sdf
@@ -1,5 +1,5 @@
 # $OpenLDAP$
-# Copyright 1999-2011 The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2013 The OpenLDAP Foundation, All Rights Reserved.
 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 
 H1: Using SASL
@@ -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,41 @@ 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 the Subject DN from the client-side certificate.
+Note that DNs are displayed differently by LDAP and by X.509, so
+a certificate issued to
+>      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=<number>+uidNumber=<number>,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