TLS API Implementation
Keywords: developers

Subsections

- Library Initialization and Cleanup
- Manipulating TLS Contexts
- Performing Post-Connection Verification
- Manipulating TLS Connections

#
TLS API Implementation

To facilitate the use of additional TLS libraries, all OpenSSL-specific code has been implemented within src/lib/tls.c. In turn, a generic TLS API is exported.

##
Library Initialization and Cleanup

    int init_tls (void);

Performs TLS library initialization, including seeding of the PRNG. PRNG seeding has not yet been implemented for win32.

    int cleanup_tls (void);

Performs TLS library cleanup.

##
Manipulating TLS Contexts

    TLS_CONTEXT  *new_tls_context (const char *ca_certfile,
            const char *ca_certdir, const char *certfile,
            const char *keyfile, const char *dhfile, bool verify_peer);

Allocates and initalizes a new opaque TLS_CONTEXT structure. The TLS_CONTEXT structure maintains default TLS settings from which TLS_CONNECTION structures are instantiated. In the future the TLS_CONTEXT structure may be used to maintain the TLS session cache. ca_certfile and ca_certdir arguments are used to initialize the CA verification stores. The certfile and keyfile arguments are used to initialize the local certificate and private key. If dhfile is non-NULL, it is used to initialize Diffie-Hellman ephemeral keying. If verify_peer is true , client certificate validation is enabled.

    void free_tls_context (TLS_CONTEXT *ctx);

Deallocated a previously allocated TLS_CONTEXT structure.

##
Performing Post-Connection Verification

    bool tls_postconnect_verify_host (TLS_CONNECTION *tls, const char *host);

Performs post-connection verification of the peer-supplied x509 certificate. Checks whether the subjectAltName and commonName attributes match the supplied host string. Returns true if there is a match, false otherwise.

    bool tls_postconnect_verify_cn (TLS_CONNECTION *tls, alist *verify_list);

Performs post-connection verification of the peer-supplied x509 certificate. Checks whether the commonName attribute matches any strings supplied via the verify_list parameter. Returns true if there is a match, false otherwise.

##
Manipulating TLS Connections

    TLS_CONNECTION *new_tls_connection (TLS_CONTEXT *ctx, int fd);

Allocates and initializes a new TLS_CONNECTION structure with context ctx and file descriptor fd.

    void free_tls_connection (TLS_CONNECTION *tls);

Deallocates memory associated with the tls structure.

    bool tls_bsock_connect (BSOCK *bsock);

Negotiates a a TLS client connection via bsock. Returns true if successful, false otherwise. Will fail if there is a TLS protocol error or an invalid certificate is presented

    bool tls_bsock_accept (BSOCK *bsock);

Accepts a TLS client connection via bsock. Returns true if successful, false otherwise. Will fail if there is a TLS protocol error or an invalid certificate is presented.

    bool tls_bsock_shutdown (BSOCK *bsock);

Issues a blocking TLS shutdown request to the peer via bsock. This function may not wait for the peer's reply.

    int tls_bsock_writen (BSOCK *bsock, char *ptr, int32_t nbytes);

Writes nbytes from ptr via the TLS_CONNECTION associated with bsock. Due to OpenSSL's handling of EINTR, bsock is set non-blocking at the start of the function, and restored to its original blocking state before the function returns. Less than nbytes may be written if an error occurs. The actual number of bytes written will be returned.

    int tls_bsock_readn (BSOCK *bsock, char *ptr, int32_t nbytes);

Reads nbytes from the TLS_CONNECTION associated with bsock and stores the result in ptr. Due to OpenSSL's handling of EINTR, bsock is set non-blocking at the start of the function, and restored to its original blocking state before the function returns. Less than nbytes may be read if an error occurs. The actual number of bytes read will be returned.