---
name: "ssl"
section: "3"
platform: "linux"
package: "libssl-dev"
version: "0.9.6c-2.woody.7"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/ssl/3"
---

# ssl(3)

SSL - OpenSSL SSL/TLS library The OpenSSL **ssl** library implements the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols. It provides a rich API which is documented here. At first the library must be initialized; see *SSL\_library\_init*(3). Then 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. Currently the OpenSSL **ssl** library functions deals with the following data structures: That's a dispatch structure describing the internal **ssl** library methods/functions which implement the various protocol versions (SSLv1, SSLv2 and TLSv1). It's needed to create an **SSL\_CTX**. This structure holds the algorithm information for a particular cipher which are a core part of the SSL/TLS protocol. The available ciphers are configured on a **SSL\_CTX** basis and the actually used ones are then part of the **SSL\_SESSION**. That's the global context structure which is created by a server or client once per program life-time and which holds mainly default values for the **SSL** structures which are later created for the connections. This is a structure containing the current TLS/SSL session details for a connection: **SSL\_CIPHER**s, client and server certificates, keys, etc. 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. Under run-time the application usually deals with this structure which has links to mostly all other structures. Currently the OpenSSL **ssl** library provides the following C header files containing the prototypes for the data structures and and functions: 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 hard-core details on the internals of the SSL API, look inside this header file. That's the sub header file dealing with the SSLv2 protocol only. *Usually you don't have to include it explicitly because* *it's already included by ssl.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*. That's the sub header file dealing with the combined use of the SSLv2 and SSLv3 protocols. *Usually you don't have to include it explicitly because* *it's already included by ssl.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*. Currently the OpenSSL **ssl** library exports 214 API functions. They are documented in the following:\
 **DEALING WITH PROTOCOL METHODS** Here we document the various API functions which deal with the SSL/TLS protocol methods defined in **SSL\_METHOD** structures. Constructor for the SSLv2 SSL\_METHOD structure for a dedicated client. Constructor for the SSLv2 SSL\_METHOD structure for a dedicated server. Constructor for the SSLv2 SSL\_METHOD structure for combined client and server. Constructor for the SSLv3 SSL\_METHOD structure for a dedicated client. Constructor for the SSLv3 SSL\_METHOD structure for a dedicated server. Constructor for the SSLv3 SSL\_METHOD structure for combined client and server. Constructor for the TLSv1 SSL\_METHOD structure for a dedicated client. Constructor for the TLSv1 SSL\_METHOD structure for a dedicated server. Constructor for the TLSv1 SSL\_METHOD structure for combined client and server.\
 **DEALING WITH CIPHERS** Here we document the various API functions which deal with the SSL/TLS ciphers defined in **SSL\_CIPHER** structures. Write a string to *buf* (with a maximum size of *len*) containing a human readable description of *cipher*. Returns *buf*. Determine the number of bits in *cipher*. Because of export crippled ciphers there are two bits: The bits the algorithm supports in general (stored to *alg\_bits*) and the bits which are actually used (the return value). Return the internal name of *cipher* as a string. These are the various strings defined by the *SSL2\_TXT\_xxx*, *SSL3\_TXT\_xxx* and *TLS1\_TXT\_xxx* definitions in the header files. Returns a string like "`"TLSv1/SSLv3"`" or "`"SSLv2"`" which indicates the SSL/TLS protocol version to which *cipher* belongs (i.e. where it was defined in the specification the first time).\
 **DEALING WITH PROTOCOL CONTEXTS** Here we document the various API functions which deal with the SSL/TLS protocol context defined in the **SSL\_CTX** structure. `"long `**SSL\_CTX\_set\_tmp\_rsa\_callback**`(SSL_CTX *`**ctx**`, RSA *(*`**cb**`)(SSL *`**ssl**`, int `**export**`, int `**keylength**`));"`

Sets the callback which will be called when a temporary private key is required. The **"export"** flag will be set if the reason for needing a temp key is that an export ciphersuite is in use, in which case, **"keylength"** will contain the required keylength in bits. Generate a key of appropriate size (using ???) and return it. long **SSL\_set\_tmp\_rsa\_callback**(SSL \*ssl, RSA \*(\*cb)(SSL \*ssl, int export, int keylength));

The same as "SSL\_CTX\_set\_tmp\_rsa\_callback", except it operates on an SSL session instead of a context.\
 **DEALING WITH SESSIONS** Here we document the various API functions which deal with the SSL/TLS sessions defined in the **SSL\_SESSION** structures.\
 **DEALING WITH CONNECTIONS** Here we document the various API functions which deal with the SSL/TLS connection defined in the **SSL** structure. [*openssl*(1)](/openssl/1.md), [*crypto*(3)](/crypto/3.md), *SSL\_accept*(3), *SSL\_clear*(3), *SSL\_connect*(3), *SSL\_CIPHER\_get\_name*(3), *SSL\_COMP\_add\_compression\_method*(3), *SSL\_CTX\_add\_extra\_chain\_cert*(3), *SSL\_CTX\_add\_session*(3), *SSL\_CTX\_ctrl*(3), *SSL\_CTX\_flush\_sessions*(3), *SSL\_CTX\_get\_ex\_new\_index*(3), *SSL\_CTX\_get\_verify\_mode*(3), *SSL\_CTX\_load\_verify\_locations*(3) *SSL\_CTX\_new*(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\_cert\_store*(3), *SSL\_CTX\_set\_cert\_verify\_callback*(3), *SSL\_CTX\_set\_cipher\_list*(3), *SSL\_CTX\_set\_client\_CA\_list*(3), *SSL\_CTX\_set\_default\_passwd\_cb*(3), *SSL\_CTX\_set\_info\_callback*(3), *SSL\_CTX\_set\_mode*(3), *SSL\_CTX\_set\_options*(3), *SSL\_CTX\_set\_quiet\_shutdown*(3), *SSL\_CTX\_set\_session\_cache\_mode*(3), *SSL\_CTX\_set\_session\_id\_context*(3), *SSL\_CTX\_set\_ssl\_version*(3), *SSL\_CTX\_set\_timeout*(3), *SSL\_CTX\_set\_tmp\_rsa\_callback*(3), *SSL\_CTX\_set\_tmp\_dh\_callback*(3), *SSL\_CTX\_set\_verify*(3), *SSL\_CTX\_use\_certificate*(3), *SSL\_alert\_type\_string*(3), *SSL\_get\_SSL\_CTX*(3), *SSL\_get\_ciphers*(3), *SSL\_get\_client\_CA\_list*(3), *SSL\_get\_default\_timeout*(3), *SSL\_get\_error*(3), *SSL\_get\_ex\_data\_X509\_STORE\_CTX\_idx*(3), *SSL\_get\_ex\_new\_index*(3), *SSL\_get\_fd*(3), *SSL\_get\_peer\_cert\_chain*(3), *SSL\_get\_rbio*(3), *SSL\_get\_session*(3), *SSL\_get\_verify\_result*(3), *SSL\_get\_version*(3), *SSL\_library\_init*(3), *SSL\_load\_client\_CA\_file*(3), *SSL\_new*(3), *SSL\_pending*(3), *SSL\_read*(3), *SSL\_rstate\_string*(3), *SSL\_session\_reused*(3), *SSL\_set\_bio*(3), *SSL\_set\_connect\_state*(3), *SSL\_set\_fd*(3), *SSL\_set\_session*(3), *SSL\_set\_shutdown*(3), *SSL\_shutdown*(3), *SSL\_state\_string*(3), *SSL\_want*(3), *SSL\_write*(3), *SSL\_SESSION\_free*(3), *SSL\_SESSION\_get\_ex\_new\_index*(3), *SSL\_SESSION\_get\_time*(3), *d2i\_SSL\_SESSION*(3) The [*ssl*(3)](/ssl/3.md) document appeared in OpenSSL 0.9.2