Editing Test Day:2010-10-14 OpenLDAP/NSS

[[Category:Test Days]]
[[Category:QA Templates]]

{|border="1"
|-style="color: white; background-color: #3074c2; font-weight: bold" 
| DATE || TIME || WHERE
|-
| '''2010-10-14''' || From ''09:00'' to ''21:00'' UTC (5am -> 5pm EDT) || [irc://irc.freenode.net/fedora-test-day #fedora-test-day] ([http://webchat.freenode.net/?channels=fedora-test-day webirc])
|-
|}

{{admon/note | Can't make the date? | If you come to this page before or after the test day is completed, your testing is still valuable, and you can use the information on this page to test, file any bugs you find at [http://bugzilla.redhat.com Bugzilla], and add your results to the results section. If this page is more than a month old when you arrive here, please check the [[QA/Test_Days|current schedule]] and see if a similar but more recent Test Day is planned or has already happened.}}

== What to test? ==

Today's installment of Fedora Test Day will focus on '''OpenLDAP with TLS encryption'''. OpenLDAP in Fedora 14 uses Mozilla NSS instead of OpenSSL crypto backend. This change should have no effect for users, but to be sure we want to test OpenLDAP server and as many programs using OpenLDAP libraries (libldap) as possible.

== Who's available ==

The following cast of characters will be available testing, workarounds, bug fixes, and general discussion ...
* Development - Jan Zeleny ([[User:jzeleny|jzeleny]]), Jan Vcelak ([[User:jvcelak|jvcelak]]), Rich Megginson ([[User:rmeggins|rmeggins]])
* Quality Assurance - Ondrej Moris ([[User:omoris|omoris]])

== Prerequisite for Test Day == 

# '''Fedora 14''' (or Rawhide) system
# <code>openldap</code> and <code>openldap-clients</code> packages
# optionally for testing server: <code>openldap-servers</code> package
# at least one application from [[#Packages_list|package list]] below

== Packages list ==

<div style="float:left;margin-right:20pt">

===== Priority 1 (the most important) =====

{|
! Package
! Taken by
! Notes
|-
| openldap-clients
| 
| 
|-
| openldap-servers
| 
| 
|-
| am-utils
| 
| 
|-
| audit
| 
| 
|-
| autofs
| 
| 
|-
| krb5-workstation
| 
| 
|-
| nss_ldap
| 
| 
|-
| nss-pam-ldapd
| 
| 
|-
| openssh
| mvadkert
| 
|-
| pam_ldap
| 
| 
|-
| python-ldap
| 
| 
|-
| ruby-ldap
| 
| 
|-
| sssd
| 
| 
|-
| sudo
| 
| 
|-
| libuser
| mvadkert
| 
|-
| nfs-utils-lib
| 
| 
|-
| quota
| 
| 
|-
|}

</div>
<div style="float:left;margin-right:20pt">

===== Priority 2 =====

{|
! Package
! Taken by
! Notes
|-
| bdii
| 
| 
|-
| bind-dyndb-ldap
| 
| 
|-
| bind
| 
| 
|-
| cups
| 
| 
|-
| curl
| 
| 
|-
| dhcp
| 
| 
|-
| dirmngr
| 
| 
|-
| httpd
| 
| 
|-
| lighttpd
| 
| 
|-
| mod_authz_ldap
| 
| 
|-
| mod_perl
| 
| 
|-
| mod_revocator
| 
| 
|-
| openvpn-auth-ldap
| 
| 
|-
| php
| 
| 
|-
| postgresql
| 
| 
|-
| proftpd
| 
| 
|-
| pure-ftpd
| 
| 
|-
|}

</div>
<div style="float:left;margin-right:20pt">

===== Priority 3 =====

{|
! Package
! Taken by
! Notes
|-
| cyrus-imapd
| 
| 
|-
| cyrus-sasl
| 
| 
|-
| dbmail
| 
| 
|-
| dovecot
| 
| 
|-
| exim
| 
| 
|-
| freeradius
| 
| 
|-
| jabberd
| 
| 
|-
| sendmail
| 
| 
|-
| samba
| 
| 
|-
| samba4
| 
| 
|-
| ocspd
| 
| 
|-
| pdns
| 
| 
|-
| postfix
| 
| 
|-
| ss5
| 
| 
|-
| zabbix
| 
| 
|-
| &nbsp;
| 
| 
|-
| &nbsp;
| 
| 
|}

</div>
<div style="float:left;margin-right:20pt">

===== Priority 4 =====

{|
! Package
! Taken by
! Notes
|-
| activemq-cpp
| 
| 
|-
| apr-util
| 
| 
|-
| ipa
| 
| 
|-
| asterisk
| 
| 
|-
| callweaver
| 
| 
|-
| cluster
| 
| 
|-
| dspam
| 
| 
|-
| nagios-plugins
| 
| 
|-
| nufw
| 
| 
|-
| opal
| 
| 
|-
| openser
| 
| 
|-
| opensips
| 
| 
|-
| squid
| 
| 
|-
| virtuoso-opensource
| 
| 
|-
| zarafa
| 
| 
|-
| &nbsp;
| 
| 
|-
| &nbsp;
| 
| 
|}

</div>
<div style="float:left;margin-right:20pt;border:none">

===== Priority 5 =====

{|
! Package
! Taken by
! Notes
|-
| alpine
| 
| 
|-
| claws-mail
| 
| 
|-
| ekiga
| 
| 
|-
| evolution-exchange
| 
| 
|-
| evolution
| 
| 
|-
| GConf2
| 
| 
|-
| gq
| 
| 
|-
| gnupg
| 
| 
|-
| gnupg2
| 
| 
|-
| kdesvn
| 
| 
|-
| ldapvi
| 
| 
|-
| myproxy
| 
| 
|-
| rapidsvn
| 
| 
|-
| seahorse
| 
| 
|-
| subcommander
| 
| 
|-
| sylpheed
| 
| 
|-
| wine
| 
| 
|-
|}

</div>
<div style="float:left;margin-right:20pt">

===== Priority 6 (the least important) =====

{|
! Package
! Taken by
! Notes
|-
| echoping
| 
| 
|-
| kdebase3
| 
| 
|-
| kdepimlibs
| 
| 
|-
| log4cxx
| 
| 
|-
| migrationtools
| 
| 
|-
| ovaldi
| 
| 
|-
| pathfinder
| 
| 
|-
| ptlib
| 
| 
|-
| root
| 
| 
|-
|}

</div>
<hr style="clear:both;border:none;" />

== Testing environment ==

=== Update your machine ===

If you're running Fedora 14, make sure you have all the current updates for it installed, using the update manager.

=== Kickstart / Live DVD ===

We recommend the testing to be done in virtual machine, using a Fedora 14 network install as installation medium.  Boot and installation images are available ([http://download.fedoraproject.org/pub/fedora/linux/releases/test/14-Beta/Fedora/i386/iso/Fedora-14-Beta-i386-netinst.iso i386], [http://download.fedoraproject.org/pub/fedora/linux/releases/test/14-Beta/Fedora/x86_64/iso/Fedora-14-Beta-x86_64-netinst.iso x86_64])

If you want to download Live medium, we have two LiveCDs available for you [http://kparal.fedorapeople.org/testdays/2010-10-14_OpenLDAP_NSS/ here].
These images contain LiveCDs with shortcuts to IRC and this wiki page. They also have all Priority 1 programs pre-installed in case you want to test one of them.

=== Available testing servers ===

{{admon/note|You can use your server|You don't have to use our testing servers. Feel free to configure yours, we provide [[#OpenLDAP_Server_2|nice step by step guide.]]}}

{{admon/caution|Servers are not ready|Servers are running, some data will be loaded soon.}}

{|
! server !! service !! package version || base DN
|-
| openldap01.fedoraproject.org || OpenLDAP + OpenSSL || openldap-servers-2.4.21-11.fc13.x86_64 || dc=silver,dc=testday
|-
| openldap02.fedoraproject.org || 389 Directory Server || 389-ds-base-1.2.7.a1 || dc=example,dc=com
|-
| openldap03.fedoraproject.org || OpenLDAP + MozNSS ||  openldap-servers-2.4.22-7.fc14.x86_64  || dc=gold,dc=testday
|}

Download [http://jvcelak.fedorapeople.org/testday-101014/cacert.pem OpenLDAP Testday CA certificate] (PEM format). Certificates of testing servers are signed by this CA.

== How to test? ==

Choose one of applications in the list above and mark it on this page by adding your name into "Taken by" column. Perform some testing. Below is a table of features what might be tested. The table lists common OpenLDAP based applications and the TLS options used. The table lists some features which are supported by <code>ldap.conf</code> file. If your application uses OpenLDAP and is able to configure it to use TLS/SSL, you will probably have similar configuration options.

You can use our [[#Available_servers|prepared LDAP server]] for your testing.

==== Example configurations ====

===== OpenLDAP command line tools =====

* Application: <code>ldapsearch</code>, <code>ldapmodify</code>, et. al.
* Default config file: <code>/etc/openldap/ldap.conf</code>, <code>~/.ldaprc</code>
* Manual page: ldap.conf
* [[#Libldap|Step by step configuration]]

Use the -Z (prefer TLS) or -ZZ (require TLS) command line options to use StartTLS with ldap:// URIs.

{|
! Config option !! Description !! Example
|-
| URI
| LDAP URI - use ldaps:// for LDAPS, or use ldap:// with -Z cmd line flag for starttls
| ldaps://ldap.example.com:636/
|-
| TLS_CACERT
| Full path and filename of file containing CA certificates to use
| /etc/pki/tls/certs/ca-bundle.crt
|-
| TLS_CACERTDIR
| Full path name of directory containing CA certificates in separate files
| /etc/openldap/cacerts
|-
| TLS_CERT
| Full path name and file name of client cert file
| /home/user/myusercert.pem
|-
| TLS_KEY
| Full path name and file name of cert private key file - must be unencrypted
| /home/user/myuserkey.pem
|-
| TLS_CIPHER_SUITE
| Specifies TLS cipher suites to use
| HIGH:MEDIUM:+SSLv3
|-
| TLS_REQCERT
| Specifies what checks to perform on server certs
| demand
|}

===== OpenLDAP server =====

* Default config file: <code>/etc/openldap/slapd.d/cn=config.ldif</code>
* Manual page: slapd-config
* [[#OpenLDAP_2|Step by step configuration]]

Use the -H command line option to have slapd listen for LDAPS requests (e.g. slapd -H ldaps://hostname ....)

{|
! Config option !! Description !! Example
|-
| olcTLSCACertificateFile
| Full path and filename of file containing CA certificates to use
| /etc/pki/tls/certs/ca-bundle.crt
|-
| olcTLSCACertificatePath
| Full path name of directory containing CA certificates in separate files
| /etc/openldap/cacerts
|-
| olcTLSCertificateFile
| Full path name and file name of server cert file
| /home/user/myusercert.pem
|-
| olcTLSCertificateKeyFile
| Full path name and file name of server private key file - must be unencrypted
| /home/user/myuserkey.pem
|-
| olcTLSCipherSuite
| Specifies TLS cipher suites to use
| HIGH:MEDIUM:+SSLv3
|-
| olcTLSVerifyClient
| Specifies what checks to perform on incoming client certs
| demand
|}

For OpenLDAP server, we also need to test server-to-server interactions that use TLS. For example, test replication from a server using Mozilla NSS to another server using OpenSSL using LDAPS or StartTLS. Try a back-ldap or back-meta configuration using TLS/SSL.

===== pam_ldap/nss_ldap =====

* Default config file: <code>/etc/ldap.conf</code>
* Manual page: nss_ldap

{|
! Config option !! Description !! Example
|-
| uri
| LDAP URI - use ldaps:// for LDAPS, or use ldap:// with ssl start_tls option (see below)
| uri ldaps://ldap.example.com:636/
|-
| ssl on,off,start_tls
| off - no TLS ; on - use LDAPS ; start_tls - use LDAP with the StartTLS operation (recommended)
| ssl start_tls
|-
| tls_cacertfile
| Full path and filename of file containing CA certificates to use
| tls_cacertfile /etc/pki/tls/certs/ca-bundle.crt
|-
| tls_cacertdir
| Full path name of directory containing CA certificates in separate files
| tls_cacertdir /etc/openldap/cacerts
|-
| tls_cert
| Full path name and file name of client cert file for client cert auth (SASL/EXTERNAL)
| tls_cert /path/to/myusercert.pem
|-
| tls_key
| Full path name and file name of client cert private key file - must be unencrypted
| tls_key /path/to/myuserkey.pem
|-
| tls_ciphers
| Specifies TLS cipher suites to use
| tls_ciphers HIGH:MEDIUM:+SSLv3
|-
| tls_checkpeer yes,no
| check the server cert or no
| tls_checkpeer yes
|}

=== Finishing test ===

After you perform testing, it is important to report results. A special section '''Test Results''' is available. Here you should write: what program have you tested, what was tested (i.e. what tests were performed) and what was the result. After you fill this report, please add a mark into "Notes" column in package list:

{| border="0"
|-
| {{result|pass}} || in case everything was ok
|-
| {{result|warn}} || in case there was probably something wrong
|-
| {{result|fail}} || in case the test failed
|}

In the latter two cases a description of what went wrong should be available in [[#Test Results|Test Results]] section below.

== Step by step configurations ==

=== Libldap  ===

{{admon/note|Many applications uses libldap setting|This describes how to setup trusted certificate authorities. Server certificates signed by these will be accepted. If you want to do testing with our testday servers, you will have to add at least our CA certificate.}}

There are more possibilities of configuring trusted CAs. The easiest way is probably using TLS_CACERTDIR directory (<code>/etc/openldap/cacerts</code> in this example) with certificate files in PEM format.<br />
You can do it your way - may the force (<code>man ldap.conf</code>) be with you. Directory with MozNSS cert database, and one bundle CA file are supported as well.

# install OpenLDAP client tools to have some simple tool for your configuration testing: <code>yum install openldap-clients</code>
# you need hash for each certificate, you can use <code>c_hash</code> tool:
#* run: <code>/etc/pki/tls/misc/c_hash /path/to/cert.pem</code>
#* you should get something like: ''537ced62.0 => /path/to/cert.pem''
# create symlink in CA certs directory:
#* <code>ln -s /path/to/cert.pem /etc/openldap/cacerts/537ced62.0</code>
# repeat previous steps for each CA you trust
# make sure, all certificates are readable for all users trough created symlinks
# update <code>/etc/openldap/ldap.conf</code>
#* add: TLS_CACERTDIR /etc/openldap/cacerts
#* optionally, you can set up default server (URI) and search base (BASE)

If you have a lot of certificates, you can use <code>c_rehash</code> tool from openssl-perl package.

=== OpenLDAP server ===

{{admon/note|This is an optional step|You don't have to set up your server. You can use our testday servers.)}}

{{admon/warning|Usual mistakes|Do not leave any empty lines in OpenLDAP server configuration files (everything in <code>/etc/openldap/slapd.d</code>).<br />
No olcTLS* option must be the last line in your database configuration or your server will not start (bug #641946), possible workaround is adding one extra line with comment (starting <code>#</code>).}}

Quick help: <code>man slapd-config</code>

# install OpenLDAP server: <code>yum install openldap-servers</code>
# choose and set your server base DN, e.g. ''dc=copper,dc=testday''
# generate admin (manager) user password hash:<br/><code>slappasswd</code>
# update /etc/openldap/slapd.d/cn=config/olcDatabase={1}bdb.ldif
#* olcSuffix: dc=copper,dc=testday
#* olcRootDN: cn=Manager,dc=copper,dc=testday
#* olcRootPW: <admin-user-password-hash>
# update /etc/openldap/slapd.d/cn=config/{2}monitor.ldif
#* olcAccess: {0}to *  by dn.base="cn=manager,dc=copper,dc=testday" read  by * non
# start your server: <code>service slapd start</code>
# try your serve functionality
#* <code>ldapsearch -H ldap://localhost -x -b "" -s base "(objectclass=*)" namingContexts</code>
#* you should get: <code>namingContexts: dc=copper,dc=testday</code>
# create base nodes
#* download example [http://jvcelak.fedorapeople.org/testday-101014/root_copper.ldif root DN nodes] (LDIF)
#* update DNs in that file
#* import that file into the database: <br/><code>ldapadd -x -D "cn=Manager,dc=copper,dc=testday" -W -f root.ldif</code>
# install BDB configuration file
#* <code>cp /usr/share/openldap-servers/DB_CONFIG.example /var/lib/ldap/DB_EXAMPLE</code>
# restart your server: <code>service slapd restart</code>
# '''your server is now configured and running without TLS'''
# generate certificates for your server (if you don't have any), we offer you [[#Generating_certificates|step by step guide]]
# update <code>/etc/openldap/slapd.d/cn=config.ldif</code>, add following options (customised):
#* olcTLSCACertificateFile: /etc/openldap/certs/cacert.pem
#* olcTLSCertificateFile: /etc/openldap/certs/server.pem
#* olcTLSCertificateKeyFile: /etc/openldap/certs/server.pem
# make your certificates readable for <code>ldap</code> user
# enable at least ldaps:// interface in <code>/etc/sysconfig/ldap</code>:
#* SLAPD_LDAP=yes (default)
#* SLAPD_LDAPS=yes
#* SLAPD_LDAPI=yes (optional)
# restart your server: <code>service slapd restart</code>
# '''your server is running with TLS support'''
# test that your configuration is working
#* without TLS: ldapsearch -x -H ldap://localhost -b "dc=copper,dc=testday"
#* with TLS: ldapsearch -x -H ldaps://localhost -b "dc=copper,dc=testday"

=== Generating certificates ===

There are more possibilities. The easiest way is installing '''TinyCA''' GUI, which will handle everything you need. You need not perform this task on your testing system.

# install TinyCA: <code>yum install tinyca2</code>
# create new certification authority
# create new certificate request
#* select 'Requests' tab
#* right-click into the emtpy list of requests and select 'New Request'
#* use pre-filled values, set 'Common Name' to match your server hostname
#* set some pass-phrase (which will be removed anyway)
#* click 'OK'
# sign the certificate request
#* right-click on the certificate request and select 'Sign Request', 'Sign Request (Server)'
#* you will be prompted for CA password
#* signed certificate will appear under 'Certificates' tab
# export your key + certificate for server
#* open 'Keys' tab
#* right click on appropriate key and select 'Export'
#* select export location (file)
#* Export Format: PEM
#* Without Passphrase: Yes
#* Include Certificate (PEM): Yes
#* click 'Save', provide your certificate pass-phrase password
# export your CA certificate
#* open 'CA' tab
#* click on 'Export CA' icon in toolbar
#* set filename, select PEM format and click on 'Save'
# configure your server to use your key and certificate
# configure your server and any clients to use/accept your CA

You can also test certificates generated by sub CAs. And client certificate authorization.

== Test Results ==
 After you are finished testing, please file a testing report below. The first report can
 be used as an example how it should look like. If you encounter any issue, please first
 consult it on IRC. If it will be verified as a bug, file a bugzilla against openldap
 component and add a note about it to your report.

'''Tested program: abcd-1.5-3-fc14.x86_64'''
* tried against all referential servers
* tried TLS connection with and without client certificate
* all test were tun with option CDEF turned on
* all test were running fine, except one
* bug #123456 was filed
* bug #123457 was filed