Back to index

lightning-sunbird  0.9+nobinonly
ldap_ssl.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is Mozilla Communicator client code, released
00015  * March 31, 1998.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-1999
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #if !defined(LDAP_SSL_H)
00039 #define LDAP_SSL_H
00040 
00041 /* ldap_ssl.h - prototypes for LDAP over SSL functions */
00042 
00043 #ifdef __cplusplus
00044 extern "C" {
00045 #endif
00046 
00047 /*
00048  * these three defines resolve the SSL strength 
00049  * setting auth weak, diables all cert checking
00050  * the CNCHECK tests for the man in the middle hack
00051  */ 
00052 #define LDAPSSL_AUTH_WEAK       0
00053 #define LDAPSSL_AUTH_CERT       1
00054 #define LDAPSSL_AUTH_CNCHECK    2
00055 
00056 
00057 /*
00058  * Initialize LDAP library for SSL
00059  */
00060 LDAP * LDAP_CALL ldapssl_init( const char *defhost, int defport,
00061        int defsecure );
00062 
00063 /*
00064  * Install I/O routines to make SSL over LDAP possible.
00065  * Use this after ldap_init() or just use ldapssl_init() instead.
00066  */
00067 int LDAP_CALL ldapssl_install_routines( LDAP *ld );
00068 
00069 
00070 /* The next four functions initialize the security code for SSL
00071  * The first one ldapssl_client_init() does initialization for SSL only
00072  * The next one supports server authentication using clientauth_init()
00073  * and allows the caller to specify the ssl strength to use in order to
00074  * verify the servers's certificate.
00075  * The next one supports ldapssl_clientauth_init() intializes security 
00076  * for SSL for client authentication.  The third function initializes
00077  * security for doing SSL with client authentication, and PKCS, that is, 
00078  * the third function initializes the security module database (secmod.db).
00079  * The parameters are as follows:
00080  * const char *certdbpath - path to the cert file.  This can be a shortcut 
00081  *     to the directory name, if so cert7.db will be postfixed to the string.
00082  * void *certdbhandle - Normally this is NULL.  This memory will need 
00083  *     to be freed.
00084  * int needkeydb - boolean.  Must be !=0 if client Authentification 
00085  *     is required
00086  * char *keydbpath - path to the key database.  This can be a shortcut 
00087  *     to the directory name, if so key3.db will be postfixed to the string.
00088  * void *keydbhandle - Normally this is NULL, This memory will need 
00089  *     to be freed 
00090  * int needsecmoddb - boolean.  Must be !=0 to assure that the correct 
00091  *     security module is loaded into memory
00092  * char *secmodpath - path to the secmod.  This can be a shortcut to the
00093  *    directory name, if so secmod.db will be postfixed to the string.
00094  *
00095  *  These three functions are mutually exclusive.  You can only call 
00096  *     one.  This means that, for a given process, you must call the
00097  *     appropriate initialization function for the life of the process.
00098  */
00099 
00100 
00101 /*
00102  * Initialize the secure parts (Security and SSL) of the runtime for use
00103  * by a client application.  This is only called once.
00104  */
00105 
00106 int LDAP_CALL ldapssl_client_init(
00107     const char *certdbpath, void *certdbhandle );
00108 
00109 /*
00110  * Initialize the secure parts (Security and SSL) of the runtime for use
00111  * by a client application using server authentication.  This is only
00112  * called once.
00113  *
00114  * ldapssl_serverauth_init() is a server-authentication only version of
00115  * ldapssl_clientauth_init().  This function allows the sslstrength
00116  * to be passed in.  The sslstrength can take one of the following
00117  * values:
00118  *
00119  *      LDAPSSL_AUTH_WEAK: indicate that you accept the server's 
00120  *                         certificate without checking the CA who
00121  *                         issued the certificate
00122  *      LDAPSSL_AUTH_CERT: indicates that you accept the server's 
00123  *                         certificate only if you trust the CA who
00124  *                         issued the certificate
00125  *      LDAPSSL_AUTH_CNCHECK:
00126  *                         indicates that you accept the server's
00127  *                         certificate only if you trust the CA who
00128  *                         issued the certificate and if the value
00129  *                         of the cn attribute is the DNS hostname
00130  *                         of the server.  If this option is selected,
00131  *                      please ensure that the "defhost" parameter
00132  *                      passed to ldapssl_init() consist of only 
00133  *                      one hostname and not a list of hosts.
00134  *                      Furthermore, the port number must be passed
00135  *                      via the "defport" parameter, and cannot
00136  *                      be passed via a host:port option. 
00137  */
00138 
00139 int LDAP_CALL ldapssl_serverauth_init(
00140     const char *certdbpath, void *certdbhandle, const int sslstrength );
00141 
00142 /*
00143  * Initialize the secure parts (Security and SSL) of the runtime for use
00144  * by a client application that may want to do SSL client authentication.
00145  */
00146 
00147 int LDAP_CALL ldapssl_clientauth_init( 
00148     const char *certdbpath, void *certdbhandle, 
00149     const int needkeydb, const char *keydbpath, void *keydbhandle );
00150 
00151 /*
00152  * Initialize the secure parts (Security and SSL) of the runtime for use
00153  * by a client application that may want to do SSL client authentication.
00154  *
00155  * Please see the description of the sslstrength value in the
00156  * ldapssl_serverauth_init() function above and note the potential
00157  * problems which can be caused by passing in wrong host & portname 
00158  * values.  The same warning applies to the ldapssl_advclientauth_init()
00159  * function.
00160  */
00161 
00162 int LDAP_CALL ldapssl_advclientauth_init( 
00163     const char *certdbpath, void *certdbhandle, 
00164     const int needkeydb, const char *keydbpath, void *keydbhandle,  
00165     const int needsecmoddb, const char *secmoddbpath, 
00166     const int sslstrength );
00167 
00168 
00169 
00170 /*
00171  * get a meaningful error string back from the security library
00172  * this function should be called, if ldap_err2string doesn't 
00173  * identify the error code.
00174  */
00175 const char * LDAP_CALL ldapssl_err2string( const int prerrno );
00176 
00177 
00178 /*
00179  * Enable SSL client authentication on the given ld.
00180  */
00181 int LDAP_CALL ldapssl_enable_clientauth( LDAP *ld, char *keynickname,
00182        char *keypasswd, char *certnickname );
00183 
00184 #ifdef __cplusplus
00185 }
00186 #endif
00187 #endif /* !defined(LDAP_SSL_H) */
00188 
00189 
00190 
00191 
00192