--- name: "libressl-ssl" section: "3" platform: "linux" package: "libressl" version: "4.4.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/libressl-ssl" --- # libressl-ssl(3) OpenSSL TLS library ## NAME **ssl** – OpenSSL TLS library ## DESCRIPTION The **ssl** library implements the Transport Layer Security (TLS) protocol, the successor to the Secure Sockets Layer (SSL) protocol. An *SSL\_CTX* object is created as a framework to establish TLS/SSL enabled connections (see SSL\_CTX\_new(3)). Various options regarding certificates, algorithms, etc., can be set in this object. When a network connection has been created, it can be assigned to an *SSL* object. After the *SSL* object has been created using SSL\_new(3), SSL\_set\_fd(3) or SSL\_set\_bio(3) can be used to associate the network connection with the object. Then the TLS/SSL handshake is performed using SSL\_accept(3) or SSL\_connect(3) respectively. SSL\_read(3) and SSL\_write(3) are used to read and write data on the TLS/SSL connection. SSL\_shutdown(3) can be used to shut down the TLS/SSL connection. ## DATA STRUCTURES Currently the **ssl** library functions deal with the following data structures: - *SSL\_METHOD* (SSL Method) That's a dispatch structure describing the internal **ssl** library methods/functions which implement the various protocol versions. It's needed to create an *SSL\_CTX*. See TLS\_method(3) for constructors. - *SSL\_CIPHER* (SSL Cipher) This structure holds the algorithm information for a particular cipher which is a core part of the SSL/TLS protocol. The available ciphers are configured on an *SSL\_CTX* basis and the actually used ones are then part of the *SSL\_SESSION*. - *SSL\_CTX* (SSL Context) That's the global context structure which is created by a server or client once per program lifetime and which holds mainly default values for the *SSL* structures which are later created for the connections. - *SSL\_SESSION* (SSL Session) This is a structure containing the current TLS/SSL session details for a connection: *SSL\_CIPHER*s, client and server certificates, keys, etc. - *SSL* (SSL Connection) That's the main SSL/TLS structure which is created by a server or client per established connection. This actually is the core structure in the SSL API. At run-time the application usually deals with this structure which has links to mostly all other structures. ## HEADER FILES Currently the **ssl** library provides the following C header files containing the prototypes for the data structures and functions: - *ssl.h* That's the common header file for the SSL/TLS API. Include it into your program to make the API of the **ssl** library available. It internally includes both more private SSL headers and headers from the *crypto* library. Whenever you need hardcore details on the internals of the SSL API, look inside this header file. - *ssl3.h* That's the sub header file dealing with the SSLv3 protocol only. Usually you don't have to include it explicitly because it's already included by *ssl.h*. - *tls1.h* That's the sub header file dealing with the TLSv1 protocol only. Usually you don't have to include it explicitly because it's already included by *ssl.h*. ## API FUNCTIONS ### Ciphers The following pages describe functions acting on *SSL\_CIPHER* objects: SSL\_get\_ciphers(3), SSL\_get\_current\_cipher(3), SSL\_CIPHER\_get\_name(3) ### Protocol contexts The following pages describe functions acting on *SSL\_CTX* objects. Constructors and destructors: SSL\_CTX\_new(3), SSL\_CTX\_set\_ssl\_version(3), SSL\_CTX\_free(3) Certificate configuration: SSL\_CTX\_add\_extra\_chain\_cert(3), SSL\_CTX\_get0\_certificate(3), SSL\_CTX\_load\_verify\_locations(3), SSL\_CTX\_set\_cert\_store(3), SSL\_CTX\_set\_cert\_verify\_callback(3), SSL\_CTX\_set\_client\_cert\_cb(3), SSL\_CTX\_set\_default\_passwd\_cb(3), SSL\_CTX\_set\_tlsext\_status\_cb(3) Session configuration: SSL\_CTX\_add\_session(3), SSL\_CTX\_flush\_sessions(3), SSL\_CTX\_sess\_number(3), SSL\_CTX\_sess\_set\_cache\_size(3), SSL\_CTX\_sess\_set\_get\_cb(3), SSL\_CTX\_sessions(3), SSL\_CTX\_set\_session\_cache\_mode(3), SSL\_CTX\_set\_timeout(3), SSL\_CTX\_set\_tlsext\_ticket\_key\_cb(3) Various configuration: SSL\_CTX\_get\_ex\_new\_index(3), SSL\_CTX\_set\_tlsext\_servername\_callback(3) ### Common configuration of contexts and connections The functions on the following pages each come in two variants: one to directly configure a single *SSL* connection and another to be called on an *SSL\_CTX* object, to set up defaults for all future *SSL* connections created from that context. Protocol and algorithm configuration: SSL\_CTX\_set\_alpn\_select\_cb(3), SSL\_CTX\_set\_cipher\_list(3), SSL\_CTX\_set\_min\_proto\_version(3), SSL\_CTX\_set\_options(3), SSL\_CTX\_set\_security\_level(3), SSL\_CTX\_set\_tlsext\_use\_srtp(3), SSL\_CTX\_set\_tmp\_dh\_callback(3), SSL\_CTX\_set1\_groups(3) Certificate configuration: SSL\_CTX\_add1\_chain\_cert(3), SSL\_CTX\_get\_verify\_mode(3), SSL\_CTX\_set\_client\_CA\_list(3), SSL\_CTX\_set\_max\_cert\_list(3), SSL\_CTX\_set\_verify(3), SSL\_CTX\_use\_certificate(3), SSL\_get\_client\_CA\_list(3) SSL\_set1\_param(3) Session configuration: SSL\_CTX\_set\_generate\_session\_id(3), SSL\_CTX\_set\_session\_id\_context(3) Various configuration: SSL\_CTX\_ctrl(3), SSL\_CTX\_set\_info\_callback(3), SSL\_CTX\_set\_mode(3), SSL\_CTX\_set\_msg\_callback(3), SSL\_CTX\_set\_quiet\_shutdown(3), SSL\_CTX\_set\_read\_ahead(3), SSL\_set\_max\_send\_fragment(3) ### Sessions The following pages describe functions acting on *SSL\_SESSION* objects. Constructors and destructors: SSL\_SESSION\_new(3), SSL\_SESSION\_free(3) Accessors: SSL\_SESSION\_get\_compress\_id(3), SSL\_SESSION\_get\_ex\_new\_index(3), SSL\_SESSION\_get\_id(3), SSL\_SESSION\_get\_protocol\_version(3), SSL\_SESSION\_get\_time(3), SSL\_SESSION\_get0\_peer(3), SSL\_SESSION\_has\_ticket(3), SSL\_SESSION\_set1\_id\_context(3) Encoding and decoding: d2i\_SSL\_SESSION(3), PEM\_read\_SSL\_SESSION(3), SSL\_SESSION\_print(3) ### Connections The following pages describe functions acting on *SSL* connection objects: Constructors and destructors: SSL\_new(3), SSL\_dup(3), SSL\_free(3), BIO\_f\_ssl(3) To change the configuration: SSL\_clear(3), SSL\_set\_SSL\_CTX(3), SSL\_copy\_session\_id(3), SSL\_set\_bio(3), SSL\_set\_connect\_state(3), SSL\_set\_fd(3), SSL\_set\_session(3), SSL\_set1\_host(3), SSL\_set\_verify\_result(3) To inspect the configuration: SSL\_get\_certificate(3), SSL\_get\_default\_timeout(3), SSL\_get\_ex\_new\_index(3), SSL\_get\_fd(3), SSL\_get\_rbio(3), SSL\_get\_SSL\_CTX(3) To transmit data: DTLSv1\_listen(3), SSL\_accept(3), SSL\_connect(3), SSL\_do\_handshake(3), SSL\_read(3), SSL\_read\_early\_data(3), SSL\_renegotiate(3), SSL\_shutdown(3), SSL\_write(3) To inspect the state after a connection is established: SSL\_export\_keying\_material(3), SSL\_get\_client\_random(3), SSL\_get\_ex\_data\_X509\_STORE\_CTX\_idx(3), SSL\_get\_peer\_cert\_chain(3), SSL\_get\_peer\_certificate(3), SSL\_get\_server\_tmp\_key(3), SSL\_get\_servername(3), SSL\_get\_session(3), SSL\_get\_shared\_ciphers(3), SSL\_get\_verify\_result(3), SSL\_get\_version(3), SSL\_session\_reused(3) To inspect the state during ongoing communication: SSL\_get\_error(3), SSL\_get\_shutdown(3), SSL\_get\_state(3), SSL\_num\_renegotiations(3), SSL\_pending(3), SSL\_rstate\_string(3), SSL\_state\_string(3), SSL\_want(3) ### Utility functions SSL\_alert\_type\_string(3), SSL\_dup\_CA\_list(3), SSL\_load\_client\_CA\_file(3) ### Obsolete functions OPENSSL\_init\_ssl(3), SSL\_COMP\_get\_compression\_methods(3), SSL\_CTX\_set\_tmp\_rsa\_callback(3), SSL\_library\_init(3), SSL\_set\_tmp\_ecdh(3) ## SEE ALSO [openssl(1)](/openssl/1.md), [crypto(3)](/crypto/3.md), [tls\_init(3)](/tls_init/3.md) ## HISTORY The **ssl** document appeared in OpenSSL 0.9.2.