Chapter 7 Connection : tibemsSSLParams

tibemsSSLParams
Type
Purpose
Group parameters representing a client identity.
Remarks
These parameters apply when creating SSL connections to the EMS server.
 
tibemsSSLParams_AddIssuerCert
Function
Purpose
Add one or more issuer certificates to the SSL parameter object.
C Declaration
tibems_status tibemsSSLParams_AddIssuerCert(
    tibemsSSLParams SSLParams,
    const void* data,
    tibems_int size,
    tibems_int encoding );
 
tibems_status tibemsSSLParams_AddIssuerCertFile(
    tibemsSSLParams SSLParams,
    const char* filename,
    tibems_int encoding );
COBOL Call
CALL "tibemsSSLParams_AddIssuerCert"
USING BY VALUE SSLParams,
BY REFERENCE data,
BY VALUE size,
BY REFERENCE encoding,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsSSLParams_AddIssuerCertFile"
USING BY VALUE SSLParams,
BY REFERENCE filename,
BY VALUE encoding,
RETURNING tibems-status
END-CALL.
 
SSLParams has usage pointer.
COBOL does not support tibemsSSLParams_AddIssuerCertFile in release 5.1.
Parameters
 
Remarks
Issuer certificates are certificates that authenticate the client’s certificate; the certificate authority (CA) that issued the client’s certificate supplies these. SSL clients must supply them during the SSL handshake, so your program must set them.
If the parameter object already has issuer certificates, this call adds to that set; it does not overwrite them.
tibemsSSLParams_AddTrustedCert
Function
Purpose
Add one or more trusted certificates to the SSL parameter object.
C Declaration
tibems_status tibemsSSLParams_AddTrustedCert(
    tibemsSSLParams SSLParams,
    const void* data,
    tibems_int size,
    tibems_int encoding );
 
tibems_status tibemsSSLParams_AddTrustedCertFile(
    tibemsSSLParams SSLParams,
    const char* filename,
    tibems_int encoding );
COBOL Call
CALL "tibemsSSLParams_AddTrustedCert"
USING BY VALUE SSLParams,
BY REFERENCE data,
BY VALUE size,
BY VALUE encoding,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsSSLParams_AddTrustedCertFile"
USING BY VALUE SSLParams,
BY REFERENCE filename,
BY VALUE encoding,
RETURNING tibems-status
END-CALL.
 
SSLParams has usage pointer.
COBOL does not support tibemsSSLParams_AddTrustedCertFile in release 5.1.
Parameters
 
Remarks
Trusted certificates are certificates that authenticate the server’s certificate; the certificate authority (CA) that issued the server’s certificate supplies these. SSL clients may verify them during the SSL handshake; if your program verifies host certificates (see tibemsSSLParams_SetVerifyHost on page 248), then you must register trusted certificates as well.
If the parameter object already has trusted certificates, this call adds to that set; it does not overwrite them.
tibemsSSLParams_Create
Function
Purpose
Create a new SSL parameter object.
C Declaration
tibemsSSLParams tibemsSSLParams_Create(void);
COBOL Call
CALL "tibemsSSLParams_Create"
RETURNING SSLParams
END-CALL.
 
SSLParams has usage pointer.
tibemsSSLParams_Destroy
Function
Purpose
Destroy an SSL parameter object.
C Declaration
void tibemsSSLParams_Destroy(
    tibemsSSLParams SSLParams );
COBOL Call
CALL "tibemsSSLParams_Destroy"
USING BY VALUE SSLParams
END-CALL.
 
SSLParams has usage pointer.
Parameters
 
tibemsSSLParams_GetIdentity
Function
Purpose
Get the client identity that an SSL parameter object represents.
C Declaration
tibems_status tibemsSSLParams_GetIdentity(
    tibemsSSLParams SSLParams,
    const void** data,
    tibems_int* size,
    tibems_int* encoding );
COBOL Call
CALL "tibemsSSLParams_GetIdentity"
     USING BY VALUE SSLParams,
           BY REFERENCE data,
           BY REFERENCE size,
           BY REFERENCE encoding,
           RETURNING tibems-status
END-CALL.
 
SSLParams and data have usage pointer.
Parameters
 
Remarks
A client identity includes a certificate and private key; it may also include issuer certificates (optional).
tibemsSSLParams_GetPrivateKey
Function
Purpose
Get the private key from an SSL parameter object.
C Declaration
tibems_status tibemsSSLParams_GetPrivateKey(
    tibemsSSLParams SSLParams,
    const void** data,
    tibems_int* size,
    tibems_int* encoding );
COBOL Call
CALL "tibemsSSLParams_GetPrivateKey"
     USING BY VALUE SSLParams,
           BY REFERENCE data,
           BY REFERENCE size,
           BY REFERENCE encoding,
           RETURNING tibems-status
END-CALL.
 
SSLParams and data have usage pointer.
Parameters
 
tibemsSSLParams_SetAuthOnly
Function
Purpose
Limit the use of SSL to improve performance.
C Declaration
tibems_status tibemsSSLParams_SetAuthOnly(
    tibemsSSLParams SSLParams,
    tibems_bool auth_only );
COBOL Call
CALL "tibemsSSLParams_SetAuthOnly"
     USING BY VALUE SSLParams,
           BY VALUE auth_only,
           RETURNING tibems-status
END-CALL.
 
SSLParams has usage pointer.
Parameters
 
TIBEMS_TRUE instructs the SSL parameter object to request a connection that uses SSL only for authentication.
TIBEMS_FALSE instructs the SSL parameter object to request a connection that uses SSL to secure all data.
Remarks
For background information, see SSL Authentication Only in TIBCO Enterprise Message Service User’s Guide
tibemsSSLParams_SetCiphers
Function
Purpose
Set the cipher suites for SSL connections.
C Declaration
tibems_status tibemsSSLParams_SetCiphers(
    tibemsSSLParams SSLParams,
    const char* ciphers );
COBOL Call
CALL "tibemsSSLParams_SetCiphers"
     USING BY VALUE SSLParams,
           BY REFERENCE ciphers,
           RETURNING tibems-status
END-CALL.
 
SSLParams has usage pointer.
Parameters
 
Supply a colon-separated list of cipher names. Names may be either OpenSSL names, or longer descriptive names.
For a list of supported cipher suites, see Supported Cipher Suites in TIBCO Enterprise Message Service User’s Guide.
tibemsSSLParams_SetExpectedHostName
Function
Purpose
Set the expected host name.
C Declaration
tibems_status tibemsSSLParams_SetExpectedHostName(
    tibemsSSLParams SSLParams,
    const char* expected_hostname );
COBOL Call
CALL "tibemsSSLParams_SetExpectedHostName"
     USING BY VALUE SSLParams,
           BY REFERENCE expected-hostname,
           RETURNING tibems-status
END-CALL.
 
SSLParams has usage pointer.
Parameters
 
Remarks
This parameter applies when establishing an SSL connection to the EMS server. If host name verification is enabled, an application-specific verifier function checks that the actual host name where the server is running is the same as this expected host name.
See Also
tibemsSSLParams_SetHostNameVerifier on page 243
tibemsSSLParams_SetVerifyHost on page 248
tibemsSSLHostNameVerifier on page 250
tibemsSSLParams_SetHostNameVerifier
Function
Purpose
Set the host name verifier function.
C Declaration
tibems_status tibemsSSLParams_SetHostNameVerifier(
    tibemsSSLParams SSLParams,
    tibemsSSLHostNameVerifier verifier,
    const void* closure );
COBOL Call
CALL "tibemsSSLParams_SetHostNameVerifier"
     USING BY VALUE SSLParams,
           BY VALUE verifier,
           BY REFERENCE closure,
           RETURNING tibems-status
END-CALL.
 
SSLParams and verifier have usage pointer.
Parameters
 
Supply application-specific data. Each call to the verifier function passes this data as an argument.
Remarks
When creating a connection to the EMS server, an application-specific verifier function checks that the actual host name where the server is running is the same as this expected host name.
See Also
tibemsSSLParams_SetExpectedHostName on page 242
tibemsSSLParams_SetVerifyHost on page 248
tibemsSSLHostNameVerifier on page 250
tibemsSSLParams_SetIdentity
Function
Purpose
Set the identity of the client program.
C Declaration
tibems_status tibemsSSLParams_SetIdentity(
    tibemsSSLParams SSLParams,
    const void* data,
    tibems_int size,
    tibems_int encoding );
 
tibems_status tibemsSSLParams_SetIdentityFile(
    tibemsSSLParams SSLParams,
    const char* filename,
    tibems_int encoding );
COBOL Call
CALL "tibemsSSLParams_SetIdentity"
     USING BY VALUE tibemsSSLParams,
           BY REFERENCE data,
           BY VALUE size,
           BY VALUE encoding,
           RETURNING tibems-status
END-CALL.
 
CALL "tibemsSSLParams_SetIdentityFile"
     USING BY VALUE SSLParams,
           BY REFERENCE filename,
           BY VALUE encoding,
           RETURNING tibems-status
END-CALL.
 
SSLParams has usage pointer.
COBOL does not support tibemsSSLParams_SetIdentityFile in release 5.1.
Parameters
 
tibemsSSLParams_SetPrivateKey
Function
Purpose
Set the client’s private key.
C Declaration
tibems_status tibemsSSLParams_SetPrivateKey(
    tibemsSSLParams SSLParams,
    const void* data,
    tibems_int size,
    tibems_int encoding );
 
tibems_status tibemsSSLParams_SetPrivateKeyFile(
    tibemsSSLParams SSLParams,
    const char* filename,
    tibems_int encoding );
COBOL Call
CALL "tibemsSSLParams_SetPrivateKey"
USING BY VALUE SSLParams,
BY REFERENCE data,
BY VALUE size,
BY VALUE encoding,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsSSLParams_SetPrivateKeyFile"
USING BY VALUE SSLParams,
BY REFERENCE filename,
BY VALUE encoding,
RETURNING tibems-status
END-CALL.
 
SSLParams has usage pointer.
COBOL does not support tibemsSSLParams_SetPrivateKeyFile in release 5.1.
Parameters
 
tibemsSSLParams_SetRandData
Function
Purpose
Settings for generating random data.
C Declaration
tibems_status tibemsSSLParams_SetRandData(
    tibemsSSLParams SSLParams,
    const char* rand_data,
    tibems_int size );
 
tibems_status tibemsSSLParams_SetRandFile(
    tibemsSSLParams SSLParams,
    const char* rand_file );
 
tibems_status tibemsSSLParams_SetRandEGD(
    tibemsSSLParams SSLParams,
    const char* rand_egd_path );
COBOL Call
CALL "tibemsSSLParams_SetRandData"
USING BY VALUE SSLParams,
BY REFERENCE rand-data,
BY VALUE size,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsSSLParams_SetRandFile"
USING BY VALUE SSLParams,
BY REFERENCE rand-file,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsSSLParams_SetRandEGD"
USING BY VALUE SSLParams,
BY REFERENCE rand-egd-path,
RETURNING tibems-status
END-CALL.
 
SSLParams has usage pointer.
COBOL does not support tibemsSSLParams_SetRandFile in release 5.1.
Parameters
 
Supply the file pathname of an entropy gathering daemon, which generates random data.
Remarks
These three functions represent three ways to inject crucial random data into SSL computations. Every program must select one of these ways. If an entropy gathering daemon is available on the host computer, we recommend using it.
tibemsSSLParams_SetVerifyHost
Function
Purpose
Sets flags that enable client verification of the host certificate or host name.
C Declaration
tibems_status tibemsSSLParams_SetVerifyHost(
    tibemsSSLParams SSLParams,
    tibems_bool verify );
 
tibems_status tibemsSSLParams_SetVerifyHostName(
    tibemsSSLParams params,
    tibems_bool verify );
COBOL Call
CALL "tibemsSSLParams_SetVerifyHost"
USING BY VALUE SSLParams,
BY VALUE verify,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsSSLParams_SetVerifyHostName"
USING BY VALUE SSLParams,
BY VALUE verify,
RETURNING tibems-status
END-CALL.
SSLParams has usage pointer.
Parameters
 
TIBEMS_TRUE enables verification.
TIBEMS_FALSE disables verification.
Remarks
Both of verification actions are enabled by default (unless a program explicitly disables them).
tibemsSSLParams_SetVerifyHost enables checking that the server host’s certificate was signed by a trusted CA; see tibemsSSLParams_AddTrustedCert on page 234).
tibemsSSLParams_SetVerifyHostName enables checking the server’s actual host name against an expected server host name; see tibemsSSLParams_SetExpectedHostName on page 242.
See Also
tibemsSSLParams_SetHostNameVerifier on page 243
tibemsSSLHostNameVerifier on page 250