3.2.10 TLS Functions

The functions described in this section were added in NDB 8.3 to support Transport Layer Security for communications between nodes. Also included in this section is information about two data structures used by some of these functions.

For additional information about TLS support in NDB Cluster, see TLS Link Encryption for NDB Cluster.

ndb_mgm_cert_table_free()

Description

Frees a linked list of certificate descriptions.

Signature
void ndb_mgm_cert_table_free
  (
    struct ndb_mgm_cert_table **list
  )
Parameters
list

A linked list of ndb_mgm_cert_table certificate descriptions

Return value

none

ndb_mgm_connect_tls()

Description

Connects to a management server. This function wraps a call to ndb_mgm_connect(), followed by a call to ndb_mgm_start_tls(). The user must first have called ndb_mgm_set_ssl_ctx() before invoking this function.

Unlike the case with ndb_mgm_connect(), ndb_mgm_connect_tls() cannot be called on a handle which is already connected; such an attempt fails with error NDB_MGM_ALREADY_CONNECTED.

Signature
int ndb_mgm_connect_tls
  (
    NdbMgmHandle handle, 
    int no_retries,
    int retry_delay_in_seconds, 
    int verbose,
    int tls_req_level
  )
Parameters
handle

Management server handle (NdbMgmHandle).

no_retries

Number of times to make connection attempts (0 means connect once).

retry_delay_in_seconds

How long to wait before performing each retry for a connection.

verbose

Print out reports regarding connect retries.

tls_req_level

This parameter can take either of the following two values:

  1. CLIENT_TLS_RELAXED: TLS authentication failures still result in errors, but a missing certificate or server refusal results in a succesful cleartext connection.

  2. CLIENT_TLS_STRICT: Any failure to establish TLS is treated as an error, and the connection is closed.

Return value

none

ndb_mgm_get_tls_stats()

Description

Get server TLS statistics

Signature
int ndb_mgm_get_tls_stats
  (
    NdbMgmHandle handle,
    struct ndb_mgm_tls_stats *result
  )
Parameters
handle

Management server handle (NdbMgmHandle).

result

Pointer to ndb_mgm_tls_stats structure holding result data

Return value

0 on success, -1 on error.

ndb_mgm_has_tls()

Description

Checks whether a connected handle is using TLS.

Signature
int ndb_mgm_has_tls
  (
    NdbMgmHandle handle
  )
Parameters
handle

Management server handle (NdbMgmHandle).

Return value

1 if the handle is using TLS; 0 if it is not.

ndb_mgm_list_certs()

Description

Queries TLS certificates of connected MGM clients

Signature
int ndb_mgm_list_certs
  (
    NdbMgmHandle handle, 
    struct ndb_mgm_cert_table **list
  )
Parameters
handle

Management server handle (NdbMgmHandle).

list

Address of a pointer to an ndb_mgm_cert_table structure.

Return value

One of the following values:

  • > 0: The total number of linked descriptions.

  • 0: Success, but with no TLS connections to report.

  • -1: Error.

ndb_mgm_set_ssl_ctx()

Description

Set an SSL context structure (CTX) for a handle.

Signature
int ndb_mgm_set_ssl_ctx
  (
    NdbMgmHandle handle, 
    struct ssl_ctx_st *ctx
  )
Parameters
handle

Management server handle (NdbMgmHandle).

ctx

SSL_ctx to be used for TLS and HTTPS connections

Return value

0 on success, -1 if CTX has already been set

ndb_mgm_start_tls()

Description

Start TLS by upgrading an open, unencrypted connection to a secure one.

Signature
int ndb_mgm_start_tls
  (
    NdbMgmHandle handle
  )
Parameters
handle

Management server handle (NdbMgmHandle).

Return value

0 on success

ndb_mgm_cert_table

Description

ndb_mgm_cert_table is a linked structure describing a TLS client session.

Definition
struct ndb_mgm_cert_table 
  {
    Uint64 session_id;
    char *peer_address;
    char *cert_serial;
    char *cert_name;
    char *cert_expires;
    struct ndb_mgm_cert_table *next;
  }
Members
session_id

TLS session ID

peer_address

Host making the connection

cert_serial

Certificate serial number

cert_name

Certificate name

cert_expires

Certificate expiration date

next

Pointer to the next ndb_mgm_cert_table in the list

ndb_mgm_tls_stats

Description

The ndb_mgm_tls_stats struct stores server statistics relating to TLS.

Definition
struct ndb_mgm_tls_stats 
  {
    Uint32 accepted; 
    Uint32 upgraded; 
    Uint32 current; 
    Uint32 tls; 
    Uint32 authfail; 
  }
Members
accepted

Total number of client connections accepted

upgraded

Number of client connections upgraded to TLS

current

Total number of current open client sessions

tls

Number of current open client sessions using TLS

authfail

Total number of authorization failures