Rework intro and sasl a bit.

Add TLS.sdf (needs to be written)
Reorder chapter

doc/guide/admin/intro.sdf

@@ -8,81 +8,85 @@ software to provide directory services.  This includes details on
 how to configure and run the stand-alone {{TERM:LDAP}} daemon,
 {{slapd}}(8) and the stand-alone LDAP update replication daemon,
 {{slurpd}}(8). It is intended for newcomers and experienced
-administrators alike. This section provides a basic introduction to
+administrators alike.  This section provides a basic introduction
-directory services and, in particular, the directory services provided
+to directory services and, in particular, the directory services
-by {{slapd}}(8).
+provided by {{slapd}}(8).
 
 
 
 H2: What is a directory service?
 
-A directory is specialized database optimized for reading, browsing and
+A directory is specialized database optimized for reading, browsing
-searching.  Directories tend to contain descriptive, attribute-based
+and searching.  Directories tend to contain descriptive, attribute-based
-information and support sophisticated filtering capabilities.  Directories
+information and support sophisticated filtering capabilities.
-generally do not support complicated transaction or roll-back schemes
+Directories generally do not support complicated transaction or
-found in database management systems designed for handling high-volume
+roll-back schemes found in database management systems designed
-complex updates.  Directory updates are typically simple all-or-nothing
+for handling high-volume complex updates.  Directory updates are
-changes, if they are allowed at all.  Directories are tuned to give
+typically simple all-or-nothing changes, if they are allowed at
-quick-response to high-volume lookup or search operations. They may have
+all.  Directories are tuned to give quick-response to high-volume
-the ability to replicate information widely in order to increase
+lookup or search operations. They may have the ability to replicate
-availability and reliability, while reducing response time.  When
+information widely in order to increase availability and reliability,
-directory information is replicated, temporary inconsistencies between
+while reducing response time.  When directory information is
-the replicas may be okay, as long as they get in sync eventually.
+replicated, temporary inconsistencies between the replicas may be
+okay, as long as they get in sync eventually.
 
-There are many different ways to provide a directory service. Different
+There are many different ways to provide a directory service.
-methods allow different kinds of information to be stored in the directory,
+Different methods allow different kinds of information to be stored
-place different requirements on how that information can be referenced,
+in the directory, place different requirements on how that information
-queried and updated, how it is protected from unauthorized access, etc.
+can be referenced, queried and updated, how it is protected from
-Some directory services are {{local}}, providing service to a restricted 
+unauthorized access, etc.  Some directory services are {{local}},
-context (e.g., the finger service on a single machine). Other services are 
+providing service to a restricted context (e.g., the finger service
-global, providing service to a much broader context (e.g., the entire Internet).
+on a single machine). Other services are global, providing service
-Global services are usually {{distributed}}, meaning that the data they
+to a much broader context (e.g., the entire Internet).  Global
-contain is spread across many machines, all of which cooperate to provide
+services are usually {{distributed}}, meaning that the data they
-the directory service. Typically a global service defines a uniform
+contain is spread across many machines, all of which cooperate to
-{{namespace}} which gives the same view of the data no matter where
+provide the directory service. Typically a global service defines
-you are in relation to the data itself.  The Internet {{TERM[expand]DNS}}
+a uniform {{namespace}} which gives the same view of the data no
-is an example of a globally distributed directory service.
+matter where you are in relation to the data itself.  The Internet
+{{TERM[expand]DNS}} is an example of a globally distributed directory
+service.
 
 
 H2: What is LDAP?
 
-{{slapd}}'s model for directory service is based on a global directory
+{{TERM:LDAP}} stands for {{TERM[expand]LDAP}}.  As the name suggests,
-model called {{TERM:LDAP}}.  LDAP stands for {{TERM[expand]LDAP}}.
+it is a lightweight protocol for accessing directory services,
-LDAP is a directory access protocol that runs over
+specifically {{TERM:X.500}}-based directory services.  LDAP runs
-{{TERM:TCP}}/{{TERM:IP}}. The nitty-gritty details of LDAP are defined in
+over {{TERM:TCP}}/{{TERM:IP}} or other connection oriented transfer
+services.  The nitty-gritty details of LDAP are defined in
 {{REF:RFC2251}} "The Lightweight Directory Access Protocol (v3)."
 This section gives an overview of LDAP from a user's perspective.
 
-{{What kind of information can be stored in the directory?}}
+{{What kind of information can be stored in the directory?}} The
-The LDAP information model is based on {{entries}}. An entry is a
+LDAP information model is based on {{entries}}. An entry is a
-collection of attributes that has a globally-unique
+collection of attributes that has a globally-unique {{TERM[expand]DN}}
-{{TERM[expand]DN}} (DN). 
+(DN).  The DN is used to refer to the entry unambiguously. Each of
-The DN is used to refer to the entry unambiguously. Each of the 
+the entry's attributes has a {{type}} and one or more {{values}}.
-entry's attributes has a {{type}} and one or more {{values}}. 
+The types are typically mnemonic strings, like "{{EX:cn}}" for
-The types are typically mnemonic strings, like "{{EX:cn}}" for common
+common name, or "{{EX:mail}}" for email address. The syntax of
-name, or "{{EX:mail}}" for email address. The syntax of values depend
+values depend on the attribute type is.  For example, {{EX:cn}}
-on the attribute type is.  For example, {{EX:cn}} attribute might
+attribute might be the value {{EX:Babs Jensen}}.  A {{EX:mail}}
-be the value {{EX:Babs Jensen}}.  A {{EX:mail}} attribute might
+attribute might contain the value "{{EX:babs@example.com}}". A
-contain the value "{{EX:babs@example.com}}". A {{EX:jpegPhoto}}
+{{EX:jpegPhoto}} attribute would contain a photograph in the JPEG
-attribute would contain a photograph in the JPEG (binary) format.
+(binary) format.
 
-{{How is the information arranged?}}
+{{How is the information arranged?}} In LDAP, directory entries
-In LDAP, directory entries are arranged in a hierarchical tree-like
+are arranged in a hierarchical tree-like structure.  Traditionally,
-structure.  Traditionally, this structure reflected the geographic
+this structure reflected the geographic and/or organizational
-and/or organizational boundaries.  Entries representing countries
+boundaries.  Entries representing countries appeared at the top of
-appeared at the top of the tree. Below them are entries representing
+the tree. Below them are entries representing states and national
-states and national organizations. Below them might be entries
+organizations. Below them might be entries representing organizational
-representing organizational units, people, printers, documents,
+units, people, printers, documents, or just about anything else
-or just about anything else you can think of.  Figure 1.1 shows an
+you can think of.  Figure 1.1 shows an example LDAP directory tree
-example LDAP directory tree using traditional naming.
+using traditional naming.
 
 !import "intro_tree.gif"; align="center"; \
 	title="LDAP directory tree (traditional naming)"
 FT[align="Center"] Figure 1.1: LDAP directory tree (traditional naming)
 
-The tree may also be arranged based upon Internet domain names.  This
+The tree may also be arranged based upon Internet domain names.
-naming approach is becoming increasing popular as it allows for
+This naming approach is becoming increasing popular as it allows
-directory services to be locating using the {{TERM[expand]DNS}}.
+for directory services to be locating using the {{TERM[expand]DNS}}.
 Figure 1.2 shows an example LDAP directory tree using domain-based
 naming.
 
@@ -91,181 +95,210 @@ naming.
 FT[align="Center"] Figure 1.2: LDAP directory tree (Internet naming)
 
 In addition, LDAP allows you to control which attributes are required
-and allowed in an entry through the use of a special attribute called 
+and allowed in an entry through the use of a special attribute
-{{EX:objectClass}}.  The values of the {{EX:objectClass}} attribute
+called {{EX:objectClass}}.  The values of the {{EX:objectClass}}
-determine the {{schema}} rules the entry must obey.
+attribute determine the {{schema}} rules the entry must obey.
 
-{{How is the information referenced?}}
+{{How is the information referenced?}} An entry is referenced by
-An entry is referenced by its distinguished name, which is constructed
+its distinguished name, which is constructed by taking the name of
-by taking the name of the entry itself (called the {{TERM[expand]RDN}}
+the entry itself (called the {{TERM[expand]RDN}} or RDN) and
-or RDN) and concatenating the names of its ancestor entries. For
+concatenating the names of its ancestor entries. For example, the
-example, the entry for Barbara Jensen in the Internet naming example
+entry for Barbara Jensen in the Internet naming example above has
-above has an RDN of {{EX:uid=babs}} and a DN of
+an RDN of {{EX:uid=babs}} and a DN of
-{{EX:uid=babs,ou=People,dc=example,dc=com}}". The full DN format is
+{{EX:uid=babs,ou=People,dc=example,dc=com}}". The full DN format
-described in {{REF:RFC2253}}, "Lightweight Directory Access Protocol (v3):
+is described in {{REF:RFC2253}}, "Lightweight Directory Access
-UTF-8 String Representation of Distinguished Names."
+Protocol (v3):  UTF-8 String Representation of Distinguished Names."
 
-{{How is the information accessed?}}
+{{How is the information accessed?}} LDAP defines operations for
-LDAP defines operations for interrogating and updating the directory.
+interrogating and updating the directory.  Operations are provided
-Operations are provided for adding and deleting
+for adding and deleting an entry from the directory, changing an
-an entry from the directory, changing an existing entry, and changing the
+existing entry, and changing the name of an entry. Most of the
-name of an entry. Most of the time, though, LDAP is used to search for
+time, though, LDAP is used to search for information in the directory.
-information in the directory. The LDAP search operation allows some portion
+The LDAP search operation allows some portion of the directory to
-of the directory to be searched for entries that match some criteria specified
+be searched for entries that match some criteria specified by a
-by a search filter. Information can be requested from each entry that matches
+search filter. Information can be requested from each entry that
-the criteria.
+matches the criteria.
 
-For example, you might want to search the entire directory subtree at
+For example, you might want to search the entire directory subtree
-and below {{EX:dc=example,dc=com}} for people with the name {{EX:Barbara
+at and below {{EX:dc=example,dc=com}} for people with the name
-Jensen}}, retrieving the email address of each entry found. LDAP lets
+{{EX:Barbara Jensen}}, retrieving the email address of each entry
-you do this easily.  Or you might want to search the entries directly
+found. LDAP lets you do this easily.  Or you might want to search
-below the {{EX:st=California,c=US}} entry for organizations with the
+the entries directly below the {{EX:st=California,c=US}} entry for
-string {{EX:Acme}} in their name, and that have a fax number. LDAP lets
+organizations with the string {{EX:Acme}} in their name, and that
-you do this too. The next section describes in more detail what you can
+have a fax number. LDAP lets you do this too. The next section
-do with LDAP and how it might be useful to you.
+describes in more detail what you can do with LDAP and how it might
+be useful to you.
 
-{{How is the information protected from unauthorized access?}}
+{{How is the information protected from unauthorized access?}} Some
-Some directory services provide no protection, allowing anyone to see
+directory services provide no protection, allowing anyone to see
 the information. LDAP provides a mechanisms for a client to
 authenticate, or prove its identity to a directory server, paving
-the way for rich access control to protect the information the server
+the way for rich access control to protect the information the
-contains.  LDAP also supports privacy and integrity security
+server contains.  LDAP also supports privacy and integrity security
 services.
 
 
 H2: How does LDAP work?
 
-LDAP directory service is based on a {{client-server}} model. One or more
+LDAP directory service is based on a {{client-server}} model. One
-LDAP servers contain the data making up the LDAP directory tree. An LDAP
+or more LDAP servers contain the data making up the directory
-client connects to an LDAP server and asks it a question. The server
+information tree (DIT).  The client connects to servers and
-responds with the answer and/or with a pointer to where the client can
+asks it a question.  The server responds with an answer and/or 
-get additional information (typically, another LDAP server). No matter
+with a pointer to where the client can get additional information
-which LDAP server a client connects to, it sees the same view of the
+(typically, another LDAP server).  No matter which LDAP server a
-directory; a name presented to one LDAP server references the same
+client connects to, it sees the same view of the directory; a name
-entry it would at another LDAP server. This is an important feature of
+presented to one LDAP server references the same entry it would at
-a global directory service, like LDAP.
+another LDAP server. This is an important feature of a global
+directory service, like LDAP.
+
+
+H2: What about X.500?
+
+Technically, {{TERM:LDAP}} is a directory access protocol to an
+{{TERM:X.500}} directory service, the {{TERM:OSI}} directory service.
+Initially, LDAP clients accessed gateways to directory service.
+This gateway ran LDAP (between the client and gateway) and X.500's
+{{TERM[expand]DAP}} ({{TERM:DAP}}) (between the gateway and the
+X.500 server.  DAP is a heavyweight protocol that operates over a
+full OSI protocol stack and requires a significant amount of
+computing resources.  LDAP is designed to operate over
+{{TERM:TCP}}/{{TERM:IP}} and provides most of the functionality of
+DAP at a much lower cost.
+
+While LDAP is still used to access X.500 directory service via
+gateways, LDAP is now more commonly directly implemented in X.500
+servers. 
+
+The stand-alone LDAP daemon, or {{slapd}}(8), can be viewed as a
+{{lightweight}} X.500 directory server.  That is, it does not
+implement the X.500's DAP.  As a {{lightweight directory}} server,
+{{slapd}}(8) implements only a subset of the X.500 models.
+
+If you are already running a X.500 DAP service and you want to
+continue to do so, you can probably stop reading this guide.  This
+guide is all about running LDAP via {{slapd}}(8), without running
+X.500 DAP.  If you are not running X.500 DAP, want to stop running
+X.500 DAP, or have no immediate plans to run X.500 DAP, read on.
+
+It is possible to replicate data from an LDAP directory server to
+a X.500 DAP {{TERM:DSA}}.  This requires an LDAP/DAP gateway.
+OpenLDAP does not provide such a gateway, but our replication daemon
+can be used to replicate to such a gateway.  See the {{SECT:Replication
+with slurpd}} chapter of this document for information regarding
+replication.
+
+
+H2: What the difference between LDAPv2 and LDAPv3?
+
+There are two versions of LDAP in use today on the Internet.
+LDAPv3 was developed in late 1990's to replace LDAPv2.  LDAPv3
+adds the following features to LDAP:
+
+ - Strong Authentication via {{TERM:SASL}}
+ - Integrity and Confidential Protections via {{TERM:TLS}} (SSL)
+ - Internationalization through the use of Unicode
+ - Referrals and Continuations
+ - Extensibility (controls and extended operations)
+ - Schema Discovery
+
+Supporting both LDAPv2 and LDAPv3 simultaneously can be problematic
+and generally should be avoided.  As LDAPv3 is more consistenly
+implemented and supports all the features of LDAPv2, use of LDAPv3
+is highly recommended.
 
 
 H2: What is slapd and what can it do?
 
-{{slapd}} is an LDAP directory server that runs on many different
+{{slapd}}(8) is an LDAP directory server that runs on many different
-platforms. You can use it to provide a directory service of your very own.
+platforms. You can use it to provide a directory service of your
-Your directory can contain pretty much anything you want to put in it. You
+very own.  Your directory can contain pretty much anything you want
-can connect it to the global LDAP directory service, or run a service all by
+to put in it. You can connect it to the global LDAP directory
-yourself. Some of slapd's more interesting features and capabilities include:
+service, or run a service all by yourself. Some of slapd's more
+interesting features and capabilities include:
 
-{{B:LDAPv2}} and {{B:LDAPv3}}: {{slapd}} supports both version 2 and 3
+{{B:LDAPv3}}: {{slapd}} implements version 3 of {{TERM[expand]LDAP}}.
-of the {{TERM[expand]LDAP}}.  {{slapd}} provides support
+{{slapd}} supports LDAP over both IPv4 and IPv6.
-for the latest features while maintaining interoperability with
-existing clients.  {{slapd}} supports both IPv4 and IPv6.
 
-{{B:{{TERM[expand]SASL}}}}: {{slapd}} supports
+{{B:{{TERM[expand]SASL}}}}: {{slapd}} supports strong authentication
-strong authentication services through the use of SASL.  {{slapd}}'s
+services through the use of SASL.  {{slapd}}'s SASL implementation
-SASL implementation utilizes {{PRD:Cyrus}} {{PRD:SASL}} software
+utilizes {{PRD:Cyrus}} {{PRD:SASL}} software which supports a number
-which supports a number of mechanisms including
+of mechanisms including DIGEST-MD5, EXTERNAL, and GSSAPI.
-DIGEST-MD5, EXTERNAL, and GSSAPI.
 
-{{B:{{TERM[expand]TLS}}}}: {{slapd}} provides privacy and 
+{{B:{{TERM[expand]TLS}}}}: {{slapd}} provides privacy and integrity
-integrity protections through the use of TLS (or SSL).  {{slapd}}'s
+protections through the use of TLS (or SSL).  {{slapd}}'s TLS
-TLS implementation utilizes {{PRD:OpenSSL}} software.
+implementation utilizes {{PRD:OpenSSL}} software.
 
-{{B:Access control}}: {{slapd}} provides a rich and powerful access 
+{{B:Topology control}}: {{slapd}} allows one to restrict access to
-control facility, allowing you to control access to the information 
+the server based upon network topology.  This feature utilizes
-in your database(s). You can control access to entries based on 
+{{TCP wrappers}}.
+
+{{B:Access control}}: {{slapd}} provides a rich and powerful access
+control facility, allowing you to control access to the information
+in your database(s). You can control access to entries based on
 LDAP authorization information, {{TERM:IP}} address, domain name
-and other criteria.
+and other criteria.  {{slapd}} supports both {{static}} and
-{{slapd}} supports both {{static}} and {{dynamic}} access control
+{{dynamic}} access control information.
-information.
 
 {{B:Internationalization}}: {{slapd}} supports Unicode and language
 tags.
 
-{{B:Choice of databases}}: {{slapd}} comes with a variety of different
+{{B:Choice of databases}}: {{slapd}} comes with a variety of
-backend databases you can choose from. They include
+different backend databases you can choose from. They include
 {{TERM:LDBM}}, a high-performance disk-based embedded database;
-SHELL, a database interface to arbitrary shell scripts; and
+SHELL, a database interface to arbitrary shell scripts; and PASSWD,
-PASSWD, a simple password file database.  LDBM utilizes either
+a simple password file database.  LDBM utilizes either {{PRD:BerkeleyDB}}
-{{PRD:BerkeleyDB}} or {{PRD:GDBM}}.
+or {{PRD:GDBM}}.
 
-{{B:Multiple database instances}}: {{slapd}} can be configured to serve 
+{{B:Multiple database instances}}: {{slapd}} can be configured to
-multiple databases at the same time. This means that a single {{slapd}}
+serve multiple databases at the same time. This means that a single
-server can respond to requests for many logically different portions 
+{{slapd}} server can respond to requests for many logically different
-of the LDAP tree, using the same or different backend databases.
+portions of the LDAP tree, using the same or different backend
+databases.
 
 {{B:Generic modules API}}: If you require even more customization,
-{{slapd}} lets you write your own modules easily. {{slapd}} 
+{{slapd}} lets you write your own modules easily. {{slapd}} consists
-consists of two distinct parts: a front end that handles protocol 
+of two distinct parts: a front end that handles protocol communication
-communication with LDAP clients; and modules which handle specific
+with LDAP clients; and modules which handle specific tasks such as
-tasks such as database operations. Because these two pieces communicate
+database operations. Because these two pieces communicate via a
-via a well-defined {{TERM:C}} {{TERM:API}}, you can write your own
+well-defined {{TERM:C}} {{TERM:API}}, you can write your own
-customized modules
+customized modules which extend {{slapd}} in numerous ways.  Also,
-which extend {{slapd}} in numerous ways.  Also, a number of
+a number of {{programmable database}} modules are provided.  These
-{{programmable database}} modules are provided.  These allow you
+allow you to expose external data sources to {{slapd}} using popular
-to expose external data sources to {{slapd}} using popular programming
+programming languages ({{PRD:Perl}}, {{Shell}}, {{PRD:SQL}}, and
-languages ({{PRD:Perl}}, {{Shell}}, {{PRD:SQL}}, and {{PRD:TCL}}).
+{{PRD:TCL}}).
 
-{{B:Threads}}: {{slapd}} is threaded for high performance. A 
+{{B:Threads}}: {{slapd}} is threaded for high performance. A single
-single multi-threaded {{slapd}} process handles all incoming 
+multi-threaded {{slapd}} process handles all incoming requests,
-requests, reducing the amount of system overhead required.
+reducing the amount of system overhead required.
 
-{{B:Replication}}: {{slapd}} can be configured to maintain replica 
+{{B:Replication}}: {{slapd}} can be configured to maintain replica
 copies of its database. This {{single-master/multiple-slave}}
 replication scheme is vital in high-volume environments where a
 single {{slapd}} just doesn't provide the necessary availability
 or reliability.  {{slapd}} also includes experimental support for
 {{multi-master}} replication.
 
-{{B:Configuration}}: {{slapd}} is highly configurable through a 
+{{B:Configuration}}: {{slapd}} is highly configurable through a
-single configuration file which allows you to change just about 
+single configuration file which allows you to change just about
-everything you'd ever want to change.  Configuration options have 
+everything you'd ever want to change.  Configuration options have
 reasonable defaults, making your job much easier.
 
-{{slapd}} also has its limitations, of course. The main LDBM
+{{slapd}} also has its limitations, of course.  The main LDBM
 database backend does not handle range queries or negation queries
-very well. These features and more will be coming in a future release.
+very well.  These features and more will be coming in a future
-
+release.
-
-H2: What about X.500?
-
-Technically, LDAP is a directory access protocol to an {{TERM:X.500}}
-directory service, the {{TERM:OSI}} directory service.  Initial
-LDAP servers were gateways between LDAP and the X.500 {{TERM[expand]DAP}}
-({{TERM:DAP}}).  DAP is a heavyweight protocol that operates over a full
-OSI protocol stack and requires a significant amount of computing
-resources.  LDAP is designed to operate over {{TERM:TCP}}/{{TERM:IP}}
-and provides most of the functionality of DAP at a much lower cost.
-
-This use of LDAP makes it easy to access the X.500 directory, but still
-requires a full X.500 service to make data available to the many LDAP
-clients being developed. As with full X.500 DAP clients, a full X.500
-DAP server is no small piece of software to operate.
-
-The stand-alone LDAP daemon, or {{slapd}}(8), is meant to remove much
-of the burden from the server side just as LDAP itself removed much of
-the burden from clients. If you are already running a X.500 DAP service
-and you want to continue to do so, you can probably stop reading this
-guide, which is all about running LDAP via {{slapd}}, without running
-X.500 DAP. If you are not running X.500 DAP, want to stop running
-X.500 DAP, or have no immediate plans to run X.500 DAP, read on.
-
-It is possible to replicate data from an LDAP directory 
-server to a X.500 DAP {{TERM:DSA}}.  This requires an LDAP/DAP
-gateway.  OpenLDAP does not provide such a gateway, but our
-replication daemon can be used to replicate to such a gateway.
-See the {{SECT:Replication with slurpd}} chapter of this document
-for information regarding replication.
 
 
 H2: What is slurpd and what can it do?
 
-{{slurpd}}(8) is a daemon that helps {{slapd}} provide 
+{{slurpd}}(8) is a daemon that helps {{slapd}} provide replicated
-replicated service. It is responsible for distributing changes made 
+service. It is responsible for distributing changes made to the
-to the master {{slapd}} database out to the various {{slapd}} 
+master {{slapd}} database out to the various {{slapd}} replicas.
-replicas. It frees {{slapd}} from having to worry that some
+It frees {{slapd}} from having to worry that some replicas might
-replicas might be down or unreachable when a change comes through;
+be down or unreachable when a change comes through; {{slurpd}}
-{{slurpd}} handles retrying failed requests automatically. 
+handles retrying failed requests automatically.  {{slapd}} and
-{{slapd}} and {{slurpd}} communicate through a simple text 
+{{slurpd}} communicate through a simple text file that is used to
-file that is used to log changes.
+log changes.
 
 See the {{SECT:Replication with slurpd}} chapter for information
 about how to configure and run {{slurpd}}(8).

doc/guide/admin/master.sdf

@@ -51,6 +51,12 @@ PB:
 !include "schema.sdf"; chapter
 PB:
 
+!include "sasl.sdf"; chapter
+PB:
+
+!include "tls.sdf"; chapter
+PB:
+
 #!include "tuning.sdf"; chapter
 #PB:
 
@@ -60,9 +66,6 @@ PB:
 !include "replication.sdf"; chapter
 PB:
 
-!include "sasl.sdf"; chapter
-PB:
-
 # Appendices 
 !include "../release/autoconf.sdf"; appendix
 PB:

doc/guide/admin/sasl.sdf

@@ -3,21 +3,22 @@
 
 H1: Using SASL
 
-This chapter details how to make use of SASL to provide authentication.
+OpenLDAP clients and servers are capable of authenticating via the
-OpenLDAP clients and servers are capable of providing authentication
+{{TERM[expand]SASL}} ({{TERM:SASL}}) framework, which is detailed
-via the {{TERM[expand]SASL}} ({{TERM:SASL}}) system, which is
+in {{REF:RFC2222}}.   This chapter describes how to make use of
-explained in {{REF:RFC2222}}. There are several industry standard
+SASL in OpenLDAP.
-authentication mechanisms that can be used with SASL, including
+
-Kerberos V4, GSSAPI, and some of the Digest mechanisms. The standard
+There are several industry standard authentication mechanisms that
-client tools provided with OpenLDAP, such as {{ldapsearch}}(1) and
+can be used with SASL, including Kerberos V4, GSSAPI, and some of
-{{ldapmodify}}(1), will by default attempt to authenticate the user
+the Digest mechanisms. The standard client tools provided with
-to the {{slapd}}(8) server using SASL. Basic authentication service
+OpenLDAP, such as {{ldapsearch}}(1) and {{ldapmodify}}(1), will by
-can be set up by the LDAP administrator with a few steps, allowing
+default attempt to authenticate the user to the {{slapd}}(8) server
-users to be authenticated to the slapd server as their LDAP entry.
+using SASL. Basic authentication service can be set up by the LDAP
-With a few extra steps, some users and services can be allowed to
+administrator with a few steps, allowing users to be authenticated
-exploit SASL's authorization feature, allowing them to authenticate
+to the slapd server as their LDAP entry.  With a few extra steps,
-themselves and then switch their identity to that of another user
+some users and services can be allowed to exploit SASL's authorization
-or service.
+feature, allowing them to authenticate themselves and then switch
+their identity to that of another user or service.
 
 This chapter assumes you have read {{Cyrus SASL for System
 Administrators}}, provided with the {{PRD:Cyrus}} {{PRD:SASL}}
@@ -33,7 +34,7 @@ uses LDAP operations to access information held in an LDAP server
 is an application entity.
 
 
-H2: Security Considerations
+H2: SASL Security Considerations
 
 SASL offers many different authentication mechanisms.  This section
 briefly outlines security considerations.
@@ -458,8 +459,8 @@ search from an LDAP URL, the authorization request fails with
 authorization DN ready to undergo approval.
 
 If the authorization identity was provided in the second form, with
-a "dn:" prefix, the string after the prefix is already in authorization
+a {EX:"dn:"}} prefix, the string after the prefix is already in
-DN form, ready to undergo approval.
+authorization DN form, ready to undergo approval.
 
 
 H3: Authorization rules
@@ -479,11 +480,11 @@ authorization DN's entry to tell what authenticated DN a person
 must be coming from in order to switch to that authorization DN.
 The choice of which form to use is up to the administrator. Source
 rules are checked first in the person's authentication DN entry,
-and if none of the saslAuthzTo rules specify the authorization is
+and if none of the {{EX:saslAuthzTo}} rules specify the authorization
-permitted, the saslAuthzFrom rules in the authorization DN entry
+is permitted, the {{EX:saslAuthzFrom}} rules in the authorization
-are then checked. If neither case specifies that the request be
+DN entry are then checked. If neither case specifies that the
-honored, the request is denied with an "inappropriate access"
+request be honored, the request is denied with an "inappropriate
-message. Since the default behaviour is to deny authorization
+access" message. Since the default behaviour is to deny authorization
 requests, rules only specify that a request be allowed; there are
 no negative rules telling what authorizations to deny.
 
@@ -491,10 +492,10 @@ The value(s) in the two attributes are of the same form as the
 output of the replacement pattern of a {{EX:saslRegexp}} directive:
 either a DN or an LDAP URL. For example, if a saslAuthzTo value is
 a DN, that DN is one the authenticated user can authorize to. On
-the other hand, if the saslAuthzTo value is an LDAP URL, the URL
+the other hand, if the {{EX:saslAuthzTo}} value is an LDAP URL,
-is used as an internal search of the LDAP database, and the
+the URL is used as an internal search of the LDAP database, and
-authenticated user can become ANY DN returned by the search. If an
+the authenticated user can become ANY DN returned by the search.
-LDAP entry looked like:
+If an LDAP entry looked like:
 
 >	dn: cn=WebUpdate,dc=example,dc=com
 >	saslAuthzTo: ldap://host/dc=example,dc=com??sub?objectclass=Person
@@ -506,15 +507,16 @@ could authorize to any other LDAP entry under the search base
 
 H4: Notes on Authorization rules
 
-An LDAP URL in a saslAuthzTo or saslAuthzFrom attribute will return
+An LDAP URL in a {{EX:saslAuthzTo}} or {{EX:saslAuthzFrom}} attribute
-a list of DN's, and that list must be linearly scanned. Searches
+will return a set of DNs.  Each DN returned will be checked.
-which return a long list can cause the authorization process to
+Searches which return a large set can cause the authorization
-take an uncomfortably long time. Also, searches should be performed
+process to take an uncomfortably long time. Also, searches should
-on attributes that have been indexed by slapd.
+be performed on attributes that have been indexed by slapd.
 
-To help produce more sweeping rules for saslAuthzFrom and saslAuthzTo,
+To help produce more sweeping rules for {{EX:saslAuthzFrom}} and
-the values of these attributes are allowed to be DN's with regular
+{{EX:saslAuthzTo}}, the values of these attributes are allowed to
-expression characters in them. This means a source rule like
+be DNs with regular expression characters in them. This means a
+source rule like
 
 >	saslAuthzTo: uid=.*,dc=example,dc=com
 

doc/guide/admin/tls.sdf

@@ -0,0 +1,10 @@
+# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
+
+H1: Using TLS
+
+OpenLDAP clients and servers are capable of using
+Transport Layer Security {{TERM:TLS}} framework to provide
+integrity and confidentiality protections and to support
+LDAP authentication via SASL EXTERNAL. 
+