diff options
Diffstat (limited to 'ldap/c-sdk/include/ldap_ssl.h')
| -rw-r--r-- | ldap/c-sdk/include/ldap_ssl.h | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/ldap/c-sdk/include/ldap_ssl.h b/ldap/c-sdk/include/ldap_ssl.h new file mode 100644 index 000000000..5c786a908 --- /dev/null +++ b/ldap/c-sdk/include/ldap_ssl.h @@ -0,0 +1,254 @@ +/* ***** 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) */ |