Skip to main content

TLS Offload

TLS offload APIs are simplified OpenSSL-compatible APIs, and provide an abstraction over SSL_CTX, SSL, and TLS I/O with offload capabilities integrated.

  • Create TLS contexts and sessions
  • Configure offload mode
  • Perform handshake (client/server)
  • Transmit and receive encrypted application data

Example​

Here is an example of using TLS offload APIs.

example_tls_client.cc
#include <libmango.h>

int main() {
  // Create a context for the first DPU device
  mango_context_h context;
  mango_context_create (&context);
  mango_context_set_hw_accel (context, MANGO_HW_ACCEL_DPU, 0);

  // Create a TLS context with DPU offload
  mango_tls_ssl_ctx_h ssl_ctx;
  mango_tls_ssl_ctx_create (&ssl_ctx, MANGO_TLS_MODE_ACCEL_OFFLOAD);

  // Create a TCP socket
  int fd = socket (AF_INET, SOCK_STREAM, 0);
  struct sockaddr_in addr = { ... };
  connect (fd, (struct sockaddr *) &addr, sizeof (addr));

  // Create a TLS session
  mango_tls_ssl_h ssl;
  mango_tls_ssl_create (ssl_ctx, &ssl, fd);

  // Perform TLS handshake
  mango_tls_ssl_connect (ssl);

  // Send data through a secure channel
  char buf[128];
  while (1) {
    mango_tls_ssl_send (ssl, buf, 128, NULL);
    ...
  }

  // Cleanup
  mango_tls_ssl_destory (ssl);
  mango_tls_ssl_ctx_destory (ssl_ctx);
  mango_context_destroy (context);

  return 0;
}

Datatypes​

mango_tls_ssl_ctx_h​

typedef void * mango_tls_ssl_ctx_h;

A handle of mango tls.

mango_tls_ssl_h​

typedef void * mango_tls_ssl_h;

A handle of mango tls.

mango_tls_mode_e​

typedef enum _mango_tls_mode mango_tls_mode_e;

Define available TLS offload mode.

Values

MANGO_TLS_MODE_DEFAULTPure software
MANGO_TLS_MODE_HOST_OFFLOADHost CPU offload (e.g., x86)
MANGO_TLS_MODE_SOC_OFFLOADSoC embedded core offload (e.g., ARM, Xeon-D)
MANGO_TLS_MODE_ACCEL_OFFLOADHW accelerator offload (e.g., FPGA, QAT)

Functions​

mango_tls_ssl_ctx_create​

mango_status_e mango_tls_ssl_ctx_create(mango_tls_ssl_ctx_h *ssl_ctx,
                                        bool is_server,
                                        mango_tls_mode_e mode)

Create a new OpenSSL SSL_CTX for client or server.

Parameters

  • out ssl_ctx The SSL CTX handle.
  • in is_server Set to true for server, false for client.
  • in mode The TLS offload mode.

Returns 0 on success, Otherwise, a negative error value.

mango_tls_ssl_ctx_destory​

mango_status_e mango_tls_ssl_ctx_destory(mango_tls_ssl_ctx_h ssl_ctx)

Destroy and cleanup the SSL_CTX object.

Parameters

  • in ssl_ctx The SSL CTX handle.

Returns 0 on success, Otherwise, a negative error value.

mango_tls_ssl_create​

mango_status_e mango_tls_ssl_create(mango_tls_ssl_ctx_h ssl_ctx,
                                    mango_tls_ssl_h *ssl,
                                    int fd)

Create a new OpenSSL SSL for client or server.

Parameters

  • in ssl_ctx The SSL CTX handle.
  • out ssl The SSL handle.
  • in fd The file descriptor.

Returns 0 on success, Otherwise, a negative error value.

mango_tls_ssl_destory​

mango_status_e mango_tls_ssl_destory(mango_tls_ssl_h ssl)

Free the SSL session object.

Parameters

  • in ssl The SSL CTX handle.

Returns 0 on success, Otherwise, a negative error value.

mango_tls_set_credentials​

mango_status_e mango_tls_set_credentials(mango_tls_ssl_ctx_h ssl_ctx,
                                         const char *cert_path,
                                         const char *key_path)

Set TLS credential paths for certificate and key.

Parameters

  • in ssl_ctx The SSL CTX handle.
  • in cert_path Path to certificate file.
  • in key_path Path to private key file.

Returns 0 on success, Otherwise, a negative error value.

mango_tls_set_mode​

mango_status_e mango_tls_set_mode(mango_tls_ssl_ctx_h ssl_ctx,
                                  mango_tls_mode_e mode)

Set TLS offload mode (handshake or data).

Parameters

  • in ssl_ctx The SSL CTX handle.
  • in mode The TLS offload mode.

Returns 0 on success, Otherwise, a negative error value.

mango_tls_ssl_connect​

mango_status_e mango_tls_ssl_connect(mango_tls_ssl_h ssl)

Perform a TLS handshake as a client.

Parameters

  • in ssl The SSL handle.

Returns 0 on success, Otherwise, a negative error value.

mango_tls_ssl_accept​

mango_status_e mango_tls_ssl_accept(mango_tls_ssl_h ssl)

Accept a TLS handshake on server.

Parameters

  • in ssl The SSL handle.

Returns 0 on success, Otherwise, a negative error value.

mango_tls_ssl_get_fd​

mango_status_e mango_tls_ssl_get_fd(mango_tls_ssl_h ssl, int *fd)

Get the file descriptor of the TCP socket.

Parameters

  • in ssl The SSL handle.
  • out fd The file descriptor referring to the socket.

Returns 0 on success, Otherwise, a negative error value.

mango_tls_ssl_send​

mango_status_e mango_tls_ssl_send(mango_tls_ssl_h ssl,
                                  const void *buf,
                                  size_t len,
                                  size_t *sent)

Send a TLS packet on the socket.

Parameters

  • out ssl The SSL handle.
  • in buf The buffer to be sent.
  • in len The buffer size.
  • out sent The number of bytes sent.

Returns 0 on success, Otherwise, a negative error value.

mango_tls_ssl_recv​

mango_status_e mango_tls_ssl_recv(mango_tls_ssl_h ssl,
                                  void *buf,
                                  size_t len,
                                  size_t *received)

Receive a TLS packet on the socket.

Parameters

  • in ssl The SSL handle.
  • in buf The buffer to be sent.
  • in len The buffer size.
  • out received The number of bytes received.

Returns 0 on success, Otherwise, a negative error value.