/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 * 
 * The contents of this file are subject to the Mozilla Public License Version 
 * 1.1 (the "License"); you may not use this file except in compliance with 
 * the License. You may obtain a copy of the License at 
 * http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 * 
 * The Original Code is Mozilla Communicator client code, released
 * March 31, 1998.
 * 
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998-1999
 * the Initial Developer. All Rights Reserved.
 * 
 * Contributor(s):
 * 
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 * 
 * ***** END LICENSE BLOCK ***** */

#if !defined(LDAP_SSL_H)
#define LDAP_SSL_H

/* ldap_ssl.h - prototypes for LDAP over SSL functions */

#ifdef __cplusplus
extern "C" {
#endif

/*
 * these three defines resolve the SSL strength 
 * setting auth weak, diables all cert checking
 * the CNCHECK tests for the man in the middle hack
 */ 
#define LDAPSSL_AUTH_WEAK       0
#define LDAPSSL_AUTH_CERT       1
#define LDAPSSL_AUTH_CNCHECK    2

/*
 * an ExtendedRequest [LDAPv3] specifying the OID for the
 * Start TLS operation: RFC 2830
 */
#define LDAP_EXOP_START_TLS			"1.3.6.1.4.1.1466.20037"

/*
 * Initialize LDAP library for SSL
 */
LDAP * LDAP_CALL ldapssl_init( const char *defhost, int defport,
	int defsecure );

/*
 * Shutdown LDAP library for SSL :
 * Perform necessary cleanup and attempt to shutdown NSS. All existing
 * ld session handles should be ldap_unbind(ld) prior to calling this.
 */	
int LDAP_CALL ldapssl_shutdown();

/* Initialize LDAP library for TLS(SSL) and sends StartTLS extended
 * operation to the Directory Server.
 * Returns LDAP_SUCCESS if all goes well.
 */
int LDAP_CALL ldap_start_tls_s( LDAP *ld, LDAPControl **serverctrls,
 					  LDAPControl **clientctrls );
/*
 * Install I/O routines to make SSL over LDAP possible.
 * Use this after ldap_init() or just use ldapssl_init() instead.
 * Returns 0 if all goes well.
 */
int LDAP_CALL ldapssl_install_routines( LDAP *ld );


/* The next four functions initialize the security code for SSL
 * The first one ldapssl_client_init() does initialization for SSL only
 * The next one supports server authentication using clientauth_init()
 * and allows the caller to specify the ssl strength to use in order to
 * verify the servers's certificate.
 * The next one supports ldapssl_clientauth_init() intializes security 
 * for SSL for client authentication.  The third function initializes
 * security for doing SSL with client authentication, and PKCS, that is, 
 * the third function initializes the security module database (secmod.db).
 * The parameters are as follows:
 * const char *certdbpath - path to the cert file.  This can be a shortcut 
 *     to the directory name, if so cert7.db will be postfixed to the string.
 * void *certdbhandle - Normally this is NULL.  This memory will need 
 *     to be freed.
 * int needkeydb - boolean.  Must be !=0 if client Authentification 
 *     is required
 * char *keydbpath - path to the key database.  This can be a shortcut 
 *     to the directory name, if so key3.db will be postfixed to the string.
 * void *keydbhandle - Normally this is NULL, This memory will need 
 *     to be freed 
 * int needsecmoddb - boolean.  Must be !=0 to assure that the correct 
 *     security module is loaded into memory
 * char *secmodpath - path to the secmod.  This can be a shortcut to the
 *    directory name, if so secmod.db will be postfixed to the string.
 *
 *  These three functions are mutually exclusive.  You can only call 
 *     one.  This means that, for a given process, you must call the
 *     appropriate initialization function for the life of the process.
 */


/*
 * Initialize the secure parts (Security and SSL) of the runtime for use
 * by a client application.  This is only called once.
 * Returns 0 if all goes well.
 */

int LDAP_CALL ldapssl_client_init(
    const char *certdbpath, void *certdbhandle );

/*
 * Initialize the secure parts (Security and SSL) of the runtime for use
 * by a client application using server authentication.  This is only
 * called once.
 *
 * ldapssl_serverauth_init() is a server-authentication only version of
 * ldapssl_clientauth_init().  This function allows the sslstrength
 * to be passed in.  The sslstrength can take one of the following
 * values:
 *
 *      LDAPSSL_AUTH_WEAK: indicate that you accept the server's 
 *                         certificate without checking the CA who
 *                         issued the certificate
 *      LDAPSSL_AUTH_CERT: indicates that you accept the server's 
 *                         certificate only if you trust the CA who
 *                         issued the certificate
 *      LDAPSSL_AUTH_CNCHECK:
 *                         indicates that you accept the server's
 *                         certificate only if you trust the CA who
 *                         issued the certificate and if the value
 *                         of the cn attribute is the DNS hostname
 *                         of the server.  If this option is selected,
 *			   please ensure that the "defhost" parameter
 *			   passed to ldapssl_init() consist of only 
 *			   one hostname and not a list of hosts.
 *			   Furthermore, the port number must be passed
 *			   via the "defport" parameter, and cannot
 *			   be passed via a host:port option. 
 *
 * Returns 0 if all goes well.
 */

int LDAP_CALL ldapssl_serverauth_init(
    const char *certdbpath, void *certdbhandle, const int sslstrength );

/*
 * Initialize the secure parts (Security and SSL) of the runtime for use
 * by a client application that may want to do SSL client authentication.
 * Returns 0 if all goes well.
 */

int LDAP_CALL ldapssl_clientauth_init( 
    const char *certdbpath, void *certdbhandle, 
    const int needkeydb, const char *keydbpath, void *keydbhandle );

/*
 * Initialize the secure parts (Security and SSL) of the runtime for use
 * by a client application that may want to do SSL client authentication.
 *
 * Please see the description of the sslstrength value in the
 * ldapssl_serverauth_init() function above and note the potential
 * problems which can be caused by passing in wrong host & portname 
 * values.  The same warning applies to the ldapssl_advclientauth_init()
 * function.
 *
 * Returns 0 if all goes well.
 */

int LDAP_CALL ldapssl_advclientauth_init( 
    const char *certdbpath, void *certdbhandle, 
    const int needkeydb, const char *keydbpath, void *keydbhandle,  
    const int needsecmoddb, const char *secmoddbpath, 
    const int sslstrength );



/*
 * get a meaningful error string back from the security library
 * this function should be called, if ldap_err2string doesn't 
 * identify the error code.
 */
const char * LDAP_CALL ldapssl_err2string( const int prerrno );


/*
 * Enable SSL client authentication on the given ld.
 * Returns 0 if all goes well.
 */
int LDAP_CALL ldapssl_enable_clientauth( LDAP *ld, char *keynickname,
	char *keypasswd, char *certnickname );

/*
 * Set the SSL strength for an existing SSL-enabled LDAP session handle.
 *
 * See the description of ldapssl_serverauth_init() above for valid
 * sslstrength values. If ld is NULL, the default for new LDAP session
 * handles is set.
 *
 * Returns 0 if all goes well.
 */ 
int LDAP_CALL ldapssl_set_strength( LDAP *ld, int sslstrength );


/*
 * Set or get SSL options for an existing SSL-enabled LDAP session handle.
 * If ld is NULL, the default options used for all future LDAP SSL sessions
 * are the ones affected. The option values are specific to the underlying
 * SSL provider; see ssl.h within the Network Security Services (NSS)
 * distribution for the options supported by NSS (the default SSL provider).
 *
 * The ldapssl_set_option() function should be called before any LDAP
 * connections are created.
 *
 * Both functions return 0 if all goes well.
 */
int LDAP_CALL ldapssl_set_option( LDAP *ld, int option, int on );
int LDAP_CALL ldapssl_get_option( LDAP *ld, int option, int *onp );

/*
 * Import the file descriptor corresponding to the socket of an already
 * open LDAP connection into SSL, and update the socket and session
 * information accordingly. Returns 0 if all goes well.
 */
int LDAP_CALL ldapssl_import_fd ( LDAP *ld, int secure );

/*
 * Reset an LDAP session from SSL to a non-secure status. Basically, 
 * this function undoes the work done by ldapssl_install_routines.
 * Returns 0 if all goes well.
 */
int LDAP_CALL ldapssl_reset_to_nonsecure ( LDAP *ld );

#ifdef __cplusplus
}
#endif
#endif /* !defined(LDAP_SSL_H) */