$Header: /data/cvsroot/mail/elmme+/shared_libs/tls/README.ME+,v 1.8 2002/01/13 17:58:04 hurtta Exp $

Shared library
==============

Shared library libelmme-tls.so provides POP's STLS and IMAPs STARTTLS command.

Source of shared library libelmme-tls.so does not contain any cryptography 
itself. Compiling that library requires that OpenSSL 0.9.6 is installed.

Note however that resulting binary libelmme-tls.so (when linked with OpenSSL
0.9.6) includes cryptography. Check OpenSSL 0.9.6 documentation and (other 
sources) for various patents (and other) issues.

(You may note change on Finnish export control at 12.3.2001.
 http://www.vn.fi/ktm/2/vientivalvonta/1_25.htm (Finnish))

To use that library add "tls" to "use-library" -elmrc option. For example

use-library = tls


"use-library" keyword may also list other librariers. If there is any other
library and you just give

use-library = tls

that removes other libraries from use.

RFC 2595: Using TLS with IMAP, POP3 and ACAP 
============================================

STLS and STARTTLS commands are defined on RFC 2595. 
libelmme-tls.so does NOT fulfill requirements of 
RFC 2595.

At least following requirements are NOT fullfilled:

-  2.3. Clear-Text Password Requirements
-  2.4. Server Identity Check

Mail services config
====================

Files libdir/elm.mailservices and ~/.elm/mail.services
can be used specify some libelmme-tls.so parameters.
These is one such parameter

    starttls-version

It gots on following values: none, ssl or tls.
"none" disables use of STLS or STARTTLS command.
"ssl" says that SSL protocol should be used after
STLS or STARTTLS command and "tls" says that TLS
protocol should be used after STLS or STARTTLS 
command. "tls" is default.

These paramater names need to be prefixed with library
tag (ie. "tls:").

  Cyrys Imapd 2.0.12         requires "tls".
  CommuniGate Pro 3.3.1      requires "ssl".
  CommuniGate Pro 3.4.6      works also with "tls".
  Cyrys Imapd 2.0.14         works also with "ssl".

So to talk with Communigate Pro 3.3.x server you need
something like following

server.host.name    *       tls:starttls-version=ssl

on ~/.elm/mail.services (or global elm.mailservices)
file. In place of "*" you can use "pop" or "imap" to
force particular protocol.

On case of multiple conflicting settings, last setting
take precedence. For example

cyrus   *       tls:starttls-version=ssl
cyrus   POP     tls:starttls-version=tls

is treated as

cyrus   POP     tls:starttls-version=tls

elm.rc Config file
==================

Files libdir/elm.rc and ~/.elm/.elmrc
can be used specify some libelmme-tls.so parameters.
These is two such parameters

    rand-file
    rand-egd

"rand-file" paramater tells from which file PRNG (pseudo
random number generator) state is  readed. That file 
is overwritten with new PRNG state. That parameter
takes following kind values

	(not set)	Uses OpenSSL's default 
			($RANDFILE or $HOME/.rnd)
	{rc}/file	Use file on ~/.elm directory
	$RANDFILE	Use file pointed by envronment variable
	~/file		Use file on home directory
	=file		Use file on folder directory
			(WARNING: File is overwritten with
			 random data)
	none		Indicates that PRNG state file should
			not be readed or written. 

You perhaps should set rand-file=none on systems, where
/dev/urandom exists (because OpenSSL uses /dev/urandom 
device to  seed PRNG state, if that device exists.)

"rand-egd" gives path to unix socket from where 
entropy gathering daemon (EGD) should be queried.
Dafault value "none" means that EGD is not available.
You should use EGD if /dev/urandom is not available.

Section of these paramaters names to be prefixed with library
tag (ie. "tls:"). Shared library specific parameters go after
other parameters on config file.  For example

tls:
rand-file = none

WARNING: If you have insufficient entropy (ie /dev/urandom
not available, rand-file does not exists and rand-egd is 
not given), STARTTLS fails, but rand-file is still written.

On next time STARTTLS succees altough there actually was no 
entrypy on rand-file. So on first time when you use 
libelmme-tls.so, be sure that rand-egd is set (and EGD is 
working) if your system does not provide /dev/urandom device.


Debug output
-------------

For debug option

        -d {class}={debugfile}:{level}

{class} value tls can be used for produce debug output for
shared library libelmme-tls.so.
