> tibemsSSLParams
> Type
> Purpose
> Group parameters representing a client identity.
> Remarks
> These parameters apply when creating SSL connections to the EMS server.

> Function | Description | Page
> tibemsSSLParams_AddIssuerCert | Add one or more issuer certificates to the SSL parameter object. | 232
> tibemsSSLParams_AddTrustedCert | Add one or more trusted certificates to the SSL parameter object. | 234
> tibemsSSLParams_Create | Create a new SSL parameter object. | 236
> tibemsSSLParams_Destroy | Destroy an SSL parameter object. | 237
> tibemsSSLParams_GetIdentity | Get the client identity that an SSL parameter object represents. | 238
> tibemsSSLParams_GetPrivateKey | Get the private key from an SSL parameter object. | 239
> tibemsSSLParams_SetAuthOnly | Limit the use of SSL to improve performance. | 240
> tibemsSSLParams_SetCiphers | Set the cipher suites for SSL connections. | 241
> tibemsSSLParams_SetExpectedHostName | Set the expected host name. | 242
> tibemsSSLParams_SetHostNameVerifier | Set the host name verifier function. | 243
> tibemsSSLParams_SetIdentity | Set the identity of the client program. | 244
> tibemsSSLParams_SetPrivateKey | Set the client’s private key. | 245
> tibemsSSLParams_SetRandData tibemsSSLParams_SetRandEGD tibemsSSLParams_SetRandFile | Settings for generating random data. | 246
> tibemsSSLParams_SetVerifyHost | Sets flags that enable client verification of the host certificate or host name. | 248

> 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

> Parameter | Description
> SSLParams | Add the certificates to this SSL parameter object.
> data | Use the certificate data at this location.
> size | Length of the certificate data (in bytes).
> encoding | Interpret the certificate data using this encoding; for values, see Table 13, Certificate Encodings.
> filename | Read the certificate data from this file.

> 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

> Parameter | Description
> SSLParams | Add the certificates to this SSL parameter object.
> data | Use the certificate data at this location.
> size | Length of the certificate data (in bytes).
> encoding | Interpret the certificate data using this encoding; for values, see Table 13, Certificate Encodings.
> filename | Read the certificate data from this file.

> 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

> Parameter | Description
> SSLParams | Destroy this SSL parameter object.

> 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

> Parameter | Description
> SSLParams | Get the identity from this SSL parameter object.
> data | The function stores in this location a pointer to the identity data within the tibemsSSLParams object.
> size | The function stores the length (in bytes) of the identity data in this location.
> encoding | The function stores the encoding of the identity data in this location; for values, see Table 13, Certificate Encodings.

> 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

> Parameter | Description
> SSLParams | Get the private key from this SSL parameter object.
> data | The function stores in this location a pointer to the key data within the tibemsSSLParams object.
> size | The function stores the length (in bytes) of the key data in this location.
> encoding | The function stores the encoding of the key data in this location; for values, see Table 13, Certificate Encodings.

> 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

> Parameter | Description
> SSLParams | Set the value in this SSL parameter object.
> auth_only | 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

> Parameter | Description
> SSLParams | Set the value in this SSL parameter object.
> ciphers | Specify the cipher suites that the client can use. 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

> Parameter | Description
> SSLParams | Set the value in this SSL parameter object.
> expected_hostname | Use this value.

> 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

> Parameter | Description
> SSLParams | Set the value in this SSL parameter object.
> verifier | Use this verifier function.
> closure | 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

> Parameter | Description
> SSLParams | Set the value in this SSL parameter object.
> data | Data must include the client’s certificate and private key. It may optionally include issuer certificates.
> size | Supply the size (in bytes) of the data.
> filename | Read identity data from this file.
> encoding | Interpret the certificate data using this encoding; for values, see Table 13, Certificate Encodings.

> 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

> Parameter | Description
> SSLParams | Set the value in this SSL parameter object.
> data | Private key data.
> size | Supply the size (in bytes) of the data.
> filename | Read private key data from this file.
> encoding | Interpret the data using this encoding; for values, see Table 13, Certificate Encodings.

> 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

> Parameter | Description
> SSLParams | Set the value in this SSL parameter object.
> rand_data | Supply random data as a character string.
> size | Supply the length (in bytes) of the random data string.
> rand_file | Read random data from this file.
> rand_egd_path | 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

> Parameter | Description
> SSLParams | Set the value in this SSL parameter object.
> verify | 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

Copyright © TIBCO Software Inc. All Rights Reserved.