diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/guide/admin/security.sdf | 398 |
1 files changed, 398 insertions, 0 deletions
diff --git a/doc/guide/admin/security.sdf b/doc/guide/admin/security.sdf new file mode 100644 index 0000000..63bf6a1 --- /dev/null +++ b/doc/guide/admin/security.sdf @@ -0,0 +1,398 @@ +# $OpenLDAP$ +# Copyright 1999-2021 The OpenLDAP Foundation, All Rights Reserved. +# Portions Copyright 2008 Andrew Findlay. +# COPYING RESTRICTIONS APPLY, see COPYRIGHT. + +H1: Security Considerations + +OpenLDAP Software is designed to run in a wide variety of computing +environments from tightly-controlled closed networks to the global +Internet. Hence, OpenLDAP Software supports many different security +mechanisms. This chapter describes these mechanisms and discusses +security considerations for using OpenLDAP Software. + +H2: Network Security + +H3: Selective Listening + +By default, {{slapd}}(8) will listen on both the IPv4 and IPv6 "any" +addresses. It is often desirable to have {{slapd}} listen on select +address/port pairs. For example, listening only on the IPv4 address +{{EX:127.0.0.1}} will disallow remote access to the directory server. +E.g.: + +> slapd -h ldap://127.0.0.1 + +While the server can be configured to listen on a particular interface +address, this doesn't necessarily restrict access to the server to +only those networks accessible via that interface. To selective +restrict remote access, it is recommend that an {{SECT:IP Firewall}} +be used to restrict access. + +See {{SECT:Command-line Options}} and {{slapd}}(8) for more +information. + + +H3: IP Firewall + +{{TERM:IP}} firewall capabilities of the server system can be used +to restrict access based upon the client's IP address and/or network +interface used to communicate with the client. + +Generally, {{slapd}}(8) listens on port 389/tcp for {{F:ldap://}} +sessions and port 636/tcp for {{F:ldaps://}}) sessions. {{slapd}}(8) +may be configured to listen on other ports. + +As specifics of how to configure IP firewall are dependent on the +particular kind of IP firewall used, no examples are provided here. +See the document associated with your IP firewall. + + +H3: TCP Wrappers + +{{slapd}}(8) supports {{TERM:TCP}} Wrappers. TCP Wrappers provide +a rule-based access control system for controlling TCP/IP access +to the server. For example, the {{host_options}}(5) rule: + +> slapd: 10.0.0.0/255.0.0.0 127.0.0.1 : ALLOW +> slapd: ALL : DENY + +allows only incoming connections from the private network {{F:10.0.0.0}} +and localhost ({{F:127.0.0.1}}) to access the directory service. + +Note: IP addresses are used as {{slapd}}(8) is not normally +configured to perform reverse lookups. + +It is noted that TCP wrappers require the connection to be accepted. +As significant processing is required just to deny a connection, +it is generally advised that IP firewall protection be used instead +of TCP wrappers. + +See {{hosts_access}}(5) for more information on TCP wrapper rules. + + +H2: Data Integrity and Confidentiality Protection + +{{TERM[expand]TLS}} (TLS) can be used to provide data integrity and +confidentiality protection. OpenLDAP supports negotiation of +{{TERM:TLS}} ({{TERM:SSL}}) via both StartTLS and {{F:ldaps://}}. +See the {{SECT:Using TLS}} chapter for more information. StartTLS +is the standard track mechanism. + +A number of {{TERM[expand]SASL}} (SASL) mechanisms, such as +{{TERM:DIGEST-MD5}} and {{TERM:GSSAPI}}, also provide data integrity +and confidentiality protection. See the {{SECT:Using SASL}} chapter +for more information. + + +H3: Security Strength Factors + +The server uses {{TERM[expand]SSF}}s (SSF) to indicate the relative +strength of protection. A SSF of zero (0) indicates no protections +are in place. A SSF of one (1) indicates integrity protection are +in place. A SSF greater than one (>1) roughly correlates to the +effective encryption key length. For example, {{TERM:DES}} is 56, +{{TERM:3DES}} is 112, and {{TERM:AES}} 128, 192, or 256. + +A number of administrative controls rely on SSFs associated with +TLS and SASL protection in place on an LDAP session. + +{{EX:security}} controls disallow operations when appropriate +protections are not in place. For example: + +> security ssf=1 update_ssf=112 + +requires integrity protection for all operations and encryption +protection, 3DES equivalent, for update operations (e.g. add, delete, +modify, etc.). See {{slapd.conf}}(5) for details. + +For fine-grained control, SSFs may be used in access controls. +See the {{SECT:Access Control}} section for more information. + + +H2: Authentication Methods + +H3: "simple" method + +The LDAP "simple" method has three modes of operation: + +* anonymous, +* unauthenticated, and +* user/password authenticated. + +Anonymous access is requested by providing no name and no password +to the "simple" bind operation. Unauthenticated access is requested +by providing a name but no password. Authenticated access is +requested by providing a valid name and password. + +An anonymous bind results in an {{anonymous}} authorization +association. Anonymous bind mechanism is enabled by default, but +can be disabled by specifying "{{EX:disallow bind_anon}}" in +{{slapd.conf}}(5). + +Note: Disabling the anonymous bind mechanism does not prevent +anonymous access to the directory. To require authentication to +access the directory, one should instead specify "{{EX:require authc}}". + +An unauthenticated bind also results in an {{anonymous}} authorization +association. Unauthenticated bind mechanism is disabled by default, +but can be enabled by specifying "{{EX:allow bind_anon_cred}}" in +{{slapd.conf}}(5). As a number of LDAP applications mistakenly +generate unauthenticated bind request when authenticated access was +intended (that is, they do not ensure a password was provided), +this mechanism should generally remain disabled. + +A successful user/password authenticated bind results in a user +authorization identity, the provided name, being associated with +the session. User/password authenticated bind is enabled by default. +However, as this mechanism itself offers no eavesdropping protection +(e.g., the password is set in the clear), it is recommended that +it be used only in tightly controlled systems or when the LDAP +session is protected by other means (e.g., TLS, {{TERM:IPsec}}). +Where the administrator relies on TLS to protect the password, it +is recommended that unprotected authentication be disabled. This +is done using the {{EX:security}} directive's {{EX:simple_bind}} +option, which provides fine grain control over the level of confidential +protection to require for {{simple}} user/password authentication. +E.g., using {{EX:security simple_bind=56}} would require {{simple}} +binds to use encryption of DES equivalent or better. + +The user/password authenticated bind mechanism can be completely +disabled by setting "{{EX:disallow bind_simple}}". + +Note: An unsuccessful bind always results in the session having +an {{anonymous}} authorization association. + + +H3: SASL method + +The LDAP {{TERM:SASL}} method allows the use of any SASL authentication +mechanism. The {{SECT:Using SASL}} section discusses the use of SASL. + +H2: Password Storage + +LDAP passwords are normally stored in the {{userPassword}} attribute. +{{REF:RFC4519}} specifies that passwords are not stored in encrypted +(or hashed) form. This allows a wide range of password-based +authentication mechanisms, such as {{EX:DIGEST-MD5}} to be used. +This is also the most interoperable storage scheme. + +However, it may be desirable to store a hash of password instead. +{{slapd}}(8) supports a variety of storage schemes for the administrator +to choose from. + +Note: Values of password attributes, regardless of storage scheme +used, should be protected as if they were clear text. Hashed +passwords are subject to {{dictionary attacks}} and {{brute-force +attacks}}. + +The {{userPassword}} attribute is allowed to have more than one value, +and it is possible for each value to be stored in a different form. +During authentication, {{slapd}} will iterate through the values +until it finds one that matches the offered password or until it +runs out of values to inspect. The storage scheme is stored as a prefix +on the value, so a hashed password using the Salted SHA1 ({{EX:SSHA}}) +scheme looks like: + +> userPassword: {SSHA}DkMTwBl+a/3DQTxCYEApdUtNXGgdUac3 + +The advantage of hashed passwords is that an attacker which +discovers the hash does not have direct access to the actual password. +Unfortunately, as dictionary and brute force attacks are generally +quite easy for attackers to successfully mount, this advantage is +marginal at best (this is why all modern Unix systems use shadow +password files). + +The disadvantages of hashed storage is that they are non-standard, may +cause interoperability problem, and generally preclude the use +of stronger than Simple (or SASL/PLAIN) password-based authentication +mechanisms such as {{EX:DIGEST-MD5}}. + +H3: SSHA password storage scheme + +This is the salted version of the SHA scheme. It is believed to be the +most secure password storage scheme supported by {{slapd}}. + +These values represent the same password: + +> userPassword: {SSHA}DkMTwBl+a/3DQTxCYEApdUtNXGgdUac3 +> userPassword: {SSHA}d0Q0626PSH9VUld7yWpR0k6BlpQmtczb + +H3: CRYPT password storage scheme + +This scheme uses the operating system's {{crypt(3)}} hash function. +It normally produces the traditional Unix-style 13 character hash, but +on systems with {{EX:glibc2}} it can also generate the more secure +34-byte MD5 hash. + +> userPassword: {CRYPT}aUihad99hmev6 +> userPassword: {CRYPT}$1$czBJdDqS$TmkzUAb836oMxg/BmIwN.1 + +The advantage of the CRYPT scheme is that passwords can be +transferred to or from an existing Unix password file without having +to know the cleartext form. Both forms of {{crypt}} include salt so +they have some resistance to dictionary attacks. + +Note: Since this scheme uses the operating system's {{crypt(3)}} +hash function, it is therefore operating system specific. + +H3: MD5 password storage scheme + +This scheme simply takes the MD5 hash of the password and stores it in +base64 encoded form: + +> userPassword: {MD5}Xr4ilOzQ4PCOq3aQ0qbuaQ== + +Although safer than cleartext storage, this is not a very secure +scheme. The MD5 algorithm is fast, and because there is no salt the +scheme is vulnerable to a dictionary attack. + +H3: SMD5 password storage scheme + +This improves on the basic MD5 scheme by adding salt (random data +which means that there are many possible representations of a given +plaintext password). For example, both of these values represent the +same password: + +> userPassword: {SMD5}4QWGWZpj9GCmfuqEvm8HtZhZS6E= +> userPassword: {SMD5}g2/J/7D5EO6+oPdklp5p8YtNFk4= + +H3: SHA password storage scheme + +Like the MD5 scheme, this simply feeds the password through an SHA +hash process. SHA is thought to be more secure than MD5, but the lack +of salt leaves the scheme exposed to dictionary attacks. + +> userPassword: {SHA}5en6G6MezRroT3XKqkdPOmY/BfQ= + +H3: SASL password storage scheme + +This is not really a password storage scheme at all. It uses the +value of the {{userPassword}} attribute to delegate password +verification to another process. See below for more information. + +Note: This is not the same as using SASL to authenticate the LDAP +session. + +H2: Pass-Through authentication + +Since OpenLDAP 2.0 {{slapd}} has had the ability to delegate password +verification to a separate process. This uses the {{sasl_checkpass(3)}} +function so it can use any back-end server that Cyrus SASL supports for +checking passwords. The choice is very wide, as one option is to use +{{saslauthd(8)}} which in turn can use local files, Kerberos, an IMAP +server, another LDAP server, or anything supported by the PAM mechanism. + +The server must be built with the {{EX:--enable-spasswd}} +configuration option to enable pass-through authentication. + +Note: This is not the same as using a SASL mechanism to +authenticate the LDAP session. + +Pass-Through authentication works only with plaintext passwords, as +used in the "simple bind" and "SASL PLAIN" authentication mechanisms.}} + +Pass-Through authentication is selective: it only affects users whose +{{userPassword}} attribute has a value marked with the "{SASL}" +scheme. The format of the attribute is: + +> userPassword: {SASL}username@realm + +The {{username}} and {{realm}} are passed to the SASL authentication +mechanism and are used to identify the account whose password is to be +verified. This allows arbitrary mapping between entries in OpenLDAP +and accounts known to the backend authentication service. + +It would be wise to use access control to prevent users from changing +their passwords through LDAP where they have pass-through authentication +enabled. + + +H3: Configuring slapd to use an authentication provider + +Where an entry has a "{SASL}" password value, OpenLDAP delegates the +whole process of validating that entry's password to Cyrus SASL. All +the configuration is therefore done in SASL config files. + +The first +file to be considered is confusingly named {{slapd.conf}} and is +typically found in the SASL library directory, often +{{EX:/usr/lib/sasl2/slapd.conf}} This file governs the use of SASL +when talking LDAP to {{slapd}} as well as the use of SASL backends for +pass-through authentication. See {{EX:options.html}} in the {{PRD:Cyrus SASL}} +docs for full details. Here is a simple example for a server that will +use {{saslauthd}} to verify passwords: + +> mech_list: plain +> pwcheck_method: saslauthd +> saslauthd_path: /var/run/sasl2/mux + +H3: Configuring saslauthd + +{{saslauthd}} is capable of using many different authentication +services: see {{saslauthd(8)}} for details. A common requirement is to +delegate some or all authentication to another LDAP server. Here is a +sample {{EX:saslauthd.conf}} that uses Microsoft Active Directory (AD): + +> ldap_servers: ldap://dc1.example.com/ ldap://dc2.example.com/ +> +> ldap_search_base: cn=Users,DC=ad,DC=example,DC=com +> ldap_filter: (userPrincipalName=%u) +> +> ldap_bind_dn: cn=saslauthd,cn=Users,DC=ad,DC=example,DC=com +> ldap_password: secret + +In this case, {{saslauthd}} is run with the {{EX:ldap}} authentication +mechanism and is set to combine the SASL realm with the login name: + +> saslauthd -a ldap -r + +This means that the "username@realm" string from the {{userPassword}} +attribute ends up being used to search AD for +"userPrincipalName=username@realm" - the password is then verified by +attempting to bind to AD using the entry found by the search and the +password supplied by the LDAP client. + +H3: Testing pass-through authentication + +It is usually best to start with the back-end authentication provider +and work through {{saslauthd}} and {{slapd}} towards the LDAP client. + +In the AD example above, first check that the DN and password that +{{saslauthd}} will use when it connects to AD are valid: + +> ldapsearch -x -H ldap://dc1.example.com/ \ +> -D cn=saslauthd,cn=Users,DC=ad,DC=example,DC=com \ +> -w secret \ +> -b '' \ +> -s base + +Next check that a sample AD user can be found: + +> ldapsearch -x -H ldap://dc1.example.com/ \ +> -D cn=saslauthd,cn=Users,DC=ad,DC=example,DC=com \ +> -w secret \ +> -b cn=Users,DC=ad,DC=example,DC=com \ +> "(userPrincipalName=user@ad.example.com)" + +Check that the user can bind to AD: + +> ldapsearch -x -H ldap://dc1.example.com/ \ +> -D cn=user,cn=Users,DC=ad,DC=example,DC=com \ +> -w userpassword \ +> -b cn=user,cn=Users,DC=ad,DC=example,DC=com \ +> -s base \ +> "(objectclass=*)" + +If all that works then {{saslauthd}} should be able to do the same: + +> testsaslauthd -u user@ad.example.com -p userpassword +> testsaslauthd -u user@ad.example.com -p wrongpassword + +Now put the magic token into an entry in OpenLDAP: + +> userPassword: {SASL}user@ad.example.com + +It should now be possible to bind to OpenLDAP using the DN of that +entry and the password of the AD user. + |