Gautam-Notes

Revision as of 08:55, 20 June 2011 by Gautam (talk | contribs)



Certificates

2-way SSL (mutual authentication) using X.509 certificates

Two-way SSL authentication, also commonly referred to as SSL mutual authentication, is the combination of server and client authentication. The authentication that is occurring is mutual, or two-way, because the server is authenticating itself to the client, and the client is authenticating itself to the server.

For a server authenticating itself to the client, the client must trust the CA who signed the server's certificate.

For a client authenticating itself to the server, the server must trust the CA who signed the client's certificate.

Note1: The detailed document is available on the Zimbra server docs/certauth.txt

Note2: Steps and examples used below are mainly for QA or dev environment.

1. Create a Certificate Authority (CA) Certificate

(A). First, we create a 2048-bit private key to use when creating our CA.

 mkdir /tmp/cert; cd /tmp/cert
 /opt/zimbra/openssl/bin/openssl genrsa -des3 -out ca.key 2048

The pass phrase will be requested whenever you use this certificate for anything, so make sure you remember it. This will create a file called /tmp/cert/ca.key, containing our certificate authority private key.

(B). Next, we create a master certificate based on this key, to use when signing other certificates:

 /opt/zimbra/openssl/bin/openssl req -config /opt/zimbra/openssl/ssl/openssl.cnf -new -x509 -days 1001 -key ca.key -out ca.cer

This will create our CA certificate and store it as /tmp/cert/ca.cer

(C). Create and sign(self-sign) a certificate from the certificate request

 /opt/zimbra/openssl/bin/openssl x509 -req -days 365 -in ca.csr -out ca.crt -signkey ca.key


2. Create a Client Certificate

(A). Create a private key

  /opt/zimbra/openssl/bin/openssl genrsa -out user1.key 2048

(B). Create a certificate request

Note: the most important information is the Email Address. It must be the email address of the Zimbra user.

  /opt/zimbra/openssl/bin/openssl req -new -key user1.key -out user1.csr
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:California
Locality Name (eg, city) []:Saratoga
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example Company
Organizational Unit Name (eg, section) []:Engineering
Common Name (eg, YOUR name) []:user one
Email Address []:user1@domain.local

(C). Sign the user certificate request using the CA created in 1 and create the user certificate

  /opt/zimbra/openssl/bin/openssl ca -in user1.csr -cert ca.crt -keyfile ca.key -out user1.crt -policy policy_anything


3. Import the Client Certificate into Web Browsers

Web browsers like Firefox and IE can't use the certificates in the PEM format that is generated by OpenSSL. Consequently, we'll need to export the user certificate to file formats that can be imported by web browsers.

(A). Import the client certificate in PKCS#12 format Firefox and Internet Explorer 6.0 support the PKCS#12 certificate format. Use the following command to convert the user certificate to this format.

  /opt/zimbra/openssl/bin/openssl pkcs12 -export -clcerts -in user1.crt -inkey user1.key -out user1.p12

Copy the user1.p12 file to a location where you can access it from your web browser via the file system.

(B). To import a certificate in Firefox (Firefox 3.6 Mac):

- Firefox -> preferences
- Click on the Advanced tab
- Under Certificates, select "Ask me every time" for "When a server requests my personal certificate".
- Click on "View Certificates"
- Click on the "Your Certificates" tab
- Click on "import"
- Use the browse button to select the user1.p12 file.  You will be prompted for the password entered in 3. (A).


4. Import the CA certificate that signed the client certificate in ZCS's keystore or truststore.

Preferred way: - 'addcacert' appends an otherwise untrusted ssl certificate to the cacerts file.

 /opt/zimbra/bin/zmcertmgr addcacert <certfile>


5. Configure Zimbra server to request client certificate

(A). Make sure zimbraMailMode on server is *not* http

  zmprov gs {server} zimbraMailMode

It is OK as long as zimbraMailMode is not "http".

(B). Configure SSL port for client certificate

Client certificate authentication happens during SSL handshake and is a configuration on the SSL connector(port). The regular SSL(zimbraMailSSLPort) and admin(zimbraAdminPort) port should *not* be configured to request client certificate, because SSL mutual authentication will interfere with other authentication options on the same port.

SSL mutual authentication must be configured on its own port (e.g. 9443).

To configure the SSL mutual authentication port:

  $ zmprov ms {server} zimbraMailSSLClientCertPort {port}

(C). Two modes are supported for client certificate:

WantClientAuth and NeedClientAuth.

Do a "zmprov desc -a zimbraMailSSLClientCertMode" for description of this attribute and difference between the two modes.

To configure the client certification mode:

  $ zmprov ms {server} zimbraMailSSLClientCertMode WantClientAuth

or

  $ zmprov ms {server} zimbraMailSSLClientCertMode NeedClientAuth


6. Restart mailbox server

  $ zmmailboxdctl restart


Note: SSL mutual authentication flow

- In the handshake the server first proves to the client who it is by signing a
  random challenge sent by the client and returning the corresponding public
  certificate so that the client can check the signature.
  
  In dev/QA environment, the server certificate is a self-signed certificate, if 
  you have not accepted it before in your browser, just accept it (e.g. on Firefox,
  follow the usual "I understand the risks -> add exception, ...").
  If the server certificate is signed by a well known CA, and the CA that signed 
  the server certificate is already in the known Authorities in the browser, 
  you should not be prompted to accept the server certificate.
     
- Then, client certification is requested by the server.  The server sends out 
  descriptions of all the client-issuing-authorities which it has in its key/trust store.
   
- The client now inspects the client certificates which are in the browser and
  attempts to find a match.  A 'match' is a client certificate which was signed by
  one of the authorities which the server says it is already aware of.
  
- At this point, Firefox should display a dialog for you to select a client cert.  
  Select the user1.p12 one imported in step II. 3. (B).
  Firefox now signs the server's random challenge, and returns it and the 
  client's public certificate. 
     
- The server checks that the client certificate was indeed issued by an
  authority it trusts, and checks the signing of the random challenge, dates etc..  
  
- Now the handshake and the "authentication" of user is complete.  
  ZCS will do the "authorization" by looking up the user in ZCS's directory.
  Currently ZCS uses the EMAILADDRESS field of the subject in the client certificate 
  as the only lookup key.  If the value of EMAILADDRESS matches a Zimbra user's 
  primary email address or one of the aliases and the account is in a state good for 
  logging in, the user will be let in.


Testing ZWC for authentication

SSL mutual authentication is supported for Zimbra WEB Client(ZWC) and admin console by browsing directly to the certauth servlet (without the virtual host and login/logout redirect settings)

Request URL

   https://{server}:{zimbraMailSSLClientCertPort}/certauth

or

   https://{server}:{zimbraMailSSLClientCertPort}/certauth/admin



Single Sign On

SPNEGO The SPNEGO SSO feature allows AD domain users to enter their Zimbra mailbox without having to re-authenticate themselves to Zimbra by entering their Zimbra credentials.

 HKEY_LOCAL_MACHINE\SOFTWARE\Zimbra\StorePassword = 0
Jump to: navigation, search