ldap_ssl_environment_init()--Initialize SSL for a Secure Connection
Syntax
#include <ldap.h>
#include <ldapssl.h>
int ldap_ssl_environment_init(
char
*keyfile,
char
*keyfile_pw,
int
sslTimeout,
int
*pSSLReasonCode)
Library Name/Service Program: QSYS/QGLDCLNT
Default Public Authority: *USE
Threadsafe: Yes
The ldap_ssl_environment_init() function is used to initialize SSL for a secure connection between a client and server. It has the same parameters as ldap_ssl_client_init() but can be called more than once. It returns LDAP_SUCCESS or the appropriate LDAP error code. It does not return LDAP_SSL_ALREADY_INITIALIZED. An application that requires SSL connections to different servers can initialize environments in separate calls to this function, with different keyring files. The environment created is used by all SSL connections established by calling ldap_ssl_init() until the next call is made to ldap_ssl_environment_init(). Subsequent calls to ldap_ssl_environment_init() do not affect existing SSL connections.
Note: Do not call this function when other threads in this process are starting secure connections.
Authorities and Locks
Read, *R, authority is needed to the selected Certificate Store and Execute, *X, to the associated directories.
Parameters
keyfile
(Input) Specifies the name of a key database file (with "kdb" extension).
The key database file typically contains one or more certificates of
certification authorities (CAs) that are trusted by the client. These types of
X.509 certificates are also known as trusted roots. A key database can also be
used to store the client's private key(s) and associated client certificate(s).
A private key and associated client certificate are required only if the LDAP
server is configured to require client and server authentication. If the LDAP
server is configured to provide only server authentication, a private key and
client certificate are not required.
A fully-qualified path and filename is recommended. If a filename without a
fully-qualified path is specified, the LDAP library will look in the current
directory for the file. The key database file specified here must have been
created using the Digital Certificate Manager (DCM). If a key database is not
supplied, keyfile is NULL, the *SYSTEM Certificate Store is used.
keyfile_pw
(Input) Specifies the password that is used to protect the contents of the
key database. This password is important since it protects the private key
stored in the key database. The password was specified when the key database
was initially created. NULL may be specified if the keyfile does not have a password.
sslTimeout
(Input) Specifies the SSL timeout value in seconds. The timeout value
controls the frequency with which the SSL protocol stack regenerates session
keys. If sslTimeout is set to 0, the default value
SSLV3_CLIENT_TIMEOUT will be used. Otherwise, the value supplied will
be used, provided it is less than or equal to 86,400. If sslTimeout
is greater than 86,400, LDAP_PARAM_ERROR is returned.
pSSLReasonCode
(Output) Specifies a pointer to the SSL Reason Code, which provides
additional information in the event that an error occurs during initialization
of the SSL stack (when ldap_ssl_client_init() is called). See
QSYSINC/H.LDAPSSL for reason codes that can be returned.
Return Value
LDAP_SUCCESS
if the request was successful.
LDAP_NO_MEMORY
if the request was not successful.
LDAP_SSL_INITIALIZE_FAILED
if the request was not successful.
LDAP_PARAM_ERROR
if the timeout value specified is greater than 86400.
LDAP_SSL_NOT_AVAILABLE
if the request was not successful.
Error Conditions
If ldap_ssl_environment_init() is not successful, it returns an
LDAP error code. See LDAP Client API Error
Conditions for possible values for the error codes.
Error Messages
The following message may be sent from this function.
Message ID
Error Message Text
CPF3CF2 E
Error(s) occurred during running of
ldap_ssl_environment_init API.