---

https.c File Reference

Socket, SSL/TLS, and HTTPS networking routines. More...

Functions
air_err_t	air_socket_alloc (ualloc_t *ua, char *host, int port, air_socket_t **sock)
	Initializes a TCP socket context. More...
air_err_t	air_socket_free (air_socket_t *sock)
	Frees a TCP socket context. If the socket is open, it will be closed prior to being free()-ed. More...
air_err_t	air_socket_isopen (air_socket_t *sock)
	Checks whether the TCP socket is open. More...
air_err_t	air_socket_open (air_socket_t *sock)
	Opens a TCP socket. More...
air_err_t	air_socket_close (air_socket_t *sock)
	Closes a TCP socket. More...
air_err_t	air_socket_send (air_socket_t *sock, air_xbuf_t *in_data)
	Sends a buffer over an established TCP connection. More...
air_err_t	air_socket_recv (air_socket_t *sock, int out_data_max, air_xbuf_t **out_data)
	Receive a buffer over an established TCP connection. More...
air_err_t	air_ssl_init ()
	Initializes the OpenSSL library. More...
air_err_t	air_ssl_alloc (ualloc_t *ua, air_socket_t *sock, air_ssl_socket_t **ssl)
air_err_t	air_ssl_free (air_ssl_socket_t *ssl)
	Deallocates an SSL/TLS socket context. More...
air_err_t	air_ssl_add_peer (air_ssl_socket_t *ssl, X509 *server_cert)
	Adds an X.509 peer certificate against which to validate when SSL/TLS mutual authentication is used. More...
air_err_t	air_ssl_add_issuer (air_ssl_socket_t *ssl, X509 *issuer_cert)
air_err_t	air_ssl_set_credentials (air_ssl_socket_t *ssl, X509 *cert, EVP_PKEY *privkey)
air_err_t	air_ssl_peer_validate (air_ssl_socket_t *ssl)
air_err_t	air_ssl_isopen (air_ssl_socket_t *ssl)
	Checks whether a ssl/tls context has an open socket. More...
air_err_t	air_ssl_open (air_ssl_socket_t *ssl, int peer_auth)
	Opens an SSL/TLS socket. More...
air_err_t	air_ssl_close (air_ssl_socket_t *ssl)
air_err_t	air_ssl_send (air_ssl_socket_t *ssl, air_xbuf_t *in_data)
	Sends a buffer over an established SSL/TLS connection. More...
air_err_t	air_ssl_recv (air_ssl_socket_t *ssl, int out_data_max, air_xbuf_t **out_data)
	Receive a buffer over an established SSL/TLS connection. More...
air_err_t	air_ssl_recv2 (air_ssl_socket_t *ssl, air_xbuf_t *buf)
	alternate form of air_ssl_recv() that uses an xbuf in-place. More...
air_err_t	air_ssl_get_last_ierr_string (air_ssl_socket_t *ssl, air_xbuf_t **err_string)
air_openssl_err_t	air_ssl_get_last_ierr ()
	Returns the last internal error (of OpenSSL). More...
air_err_t	air_crypto_privkey_fload (char *key_fname, EVP_PKEY **privkey)
	Loads a PEM encoded RSA key from disk. More...
air_err_t	air_crypto_crt_fload (char *crt_fname, X509 **cert)
	Loads a PEM encoded X.509 certificate from disk. More...
air_err_t	air_http_make_request (ualloc_t *ua, air_xbuf_t *in_data, char *script, air_xbuf_t **out_data)
	Accepts a buffer and formats it into an HTTP POST request. More...
air_err_t	air_http_parse_reply (air_xbuf_t *in_data, int *http_code, air_xbuf_t **out_data)

---

Detailed Description

Socket, SSL/TLS, and HTTPS networking routines.

Ability to send arbitrary buffers over a TCP socket or SSL/TLS, either raw or formatted as an HTTP POST request.

---

Function Documentation

air_err_t air_socket_alloc (  ualloc_t *    ua, char *    host, int    port, air_socket_t **    sock )

Initializes a TCP socket context. ********************************************************************** Parameters: ua  (IN) memory allocator host  (IN) IP address or hostname of the server port  (IN) TCP port on which to connect to the server socket  (OUT) TCP context Returns: status code of the operation ********************************************************************

air_err_t air_socket_free (  air_socket_t *    sock )

Frees a TCP socket context. If the socket is open, it will be closed prior to being free()-ed. ********************************************************************** Parameters: socket  (IN) TCP context Returns: status code of the operation ********************************************************************

air_err_t air_socket_isopen (  air_socket_t *    sock )

Checks whether the TCP socket is open. ********************************************************************** Parameters: sock  (IN) TCP socket Returns: status code of the operation AIR_E_NULL socket is NULL AIR_E_NONE open AIR_E_NOT_CONN closed ********************************************************************

air_err_t air_socket_open (  air_socket_t *    sock )

Opens a TCP socket. ********************************************************************** Parameters: socket  (OUT) an open TCP connection Returns: status code of the operation ********************************************************************

air_err_t air_socket_close (  air_socket_t *    sock )

Closes a TCP socket. ********************************************************************** Parameters: socket  (IN) an open TCP connection Returns: status code of the operation AIR_E_NONE no error AIR_E_NULL invalid socket AIR_E_NOT_CONN socket is not connected AIR_E_INVALID socket is not valid descriptor ********************************************************************

void air_socket_send (  air_socket_t *    sock, air_xbuf_t *    in_data )

Sends a buffer over an established TCP connection. ********************************************************************** This is a blocking operation. Parameters: socket  an open TCP connection in_data  buffer to send Returns: status code of the operation AIR_E_NONE no error AIR_E_NULL invalid socket AIR_E_NOT_CONN socket is not connected AIR_E_ALREADY async I/O has been selected, should block AIR_E_REFUSED reading-side of the socket is closed AIR_E_FAILED send over the socket failed ********************************************************************

air_err_t air_socket_recv (  air_socket_t *    sock, int    out_data_max, air_xbuf_t **    out_data )

Receive a buffer over an established TCP connection. ********************************************************************** This is a blocking operation. Parameters: sock  an open TCP socket out_data_max  maximum number of bytes to receive out_data  newly allocated buffer to store received message Returns: status code of the operation ********************************************************************

air_err_t air_ssl_init (    )

Initializes the OpenSSL library. ********************************************************************** This function should be called prior to using any other air_ssl_*() or air_crypto_*() routines Returns: status code of the operation ********************************************************************

air_err_t air_ssl_free (  air_ssl_socket_t *    socket )

Deallocates an SSL/TLS socket context. ********************************************************************** Note: The air_socket_t associated with this air_ssl_t is also deallocated Parameters: ssl  (IN/OUT) SSL/TLS to be freed Returns: status code of the operation ********************************************************************

air_err_t air_ssl_add_peer (  air_ssl_socket_t *    socket, X509 *    server_cert )

Adds an X.509 peer certificate against which to validate when SSL/TLS mutual authentication is used. ********************************************************************** Parameters: socket  (IN) SSL/TLS context server_cert  (IN) X.509 certificate of a new server Returns: status code of the operation AIR_E_NONE no error AIR_E_NULL NULL ssl socket structure AIR_E_ALREADY SSL connection has already been established, certificates can only be added on closed connections ********************************************************************

air_err_t air_ssl_peer_validate (  air_ssl_socket_t *    ssl )

air_ssl_cert_validate(air_ssl_socket_t *ssl) default callback to validate a peer certificate Validating the peer certificate is imperative to assuring proper authentication of the peer in the TLS connection. There are a number of checks that should be performed: Assuming that we have a fixed list of CA (issuers) that are trusted, then air_ssl_add_issuer() should be invoked to create this list. If the proper calls to air_ssl_add_issuer() are made, we can be assured that by the time this routine is invoked that the peer certificate has a valid signature from one of these CA. What is desired now is to make sure that the peer certificate is actually one we want to accept based on some predefined list of certificates created by invoking air_ssl_add_peer().

air_err_t air_ssl_isopen (  air_ssl_socket_t *    ssl )

Checks whether a ssl/tls context has an open socket. ********************************************************************** Parameters: ssl  (IN) SSL/TLS context Returns: status code of the operation AIR_E_NULL ssl context is NULL AIR_E_NONE open AIR_E_NOT_CONN closed ********************************************************************

air_err_t air_ssl_open (  air_ssl_socket_t *    ssl, int    peer_auth )

Opens an SSL/TLS socket. ********************************************************************** Parameters: ssl  (IN/OUT) SSL/TLS context peer_auth  (IN) should the peer's certificate be required? Returns: status code of the operation AIR_E_NONE no error AIR_E_NULL NULL ssl socket structure AIR_E_NOMEM failed to allocate memory AIR_E_FAILED failed to open socket (maybe authentication?) AIR_E_AUTH authentication failed ********************************************************************

air_err_t air_ssl_send (  air_ssl_socket_t *    ssl, air_xbuf_t *    in_data )

Sends a buffer over an established SSL/TLS connection. ********************************************************************** This is a blocking operation. Parameters: ssl  open SSL/TLS context/socket in_data  buffer to send Returns: status code of the operation AIR_E_NONE no error AIR_E_NULL invalid socket AIR_E_FAILED failed to write to the socket ********************************************************************

air_err_t air_ssl_recv (  air_ssl_socket_t *    ssl, int    out_data_max, air_xbuf_t **    out_data )

Receive a buffer over an established SSL/TLS connection. ********************************************************************** This is a blocking operation. Parameters: ssl  an open SSL/TLS socket out_data_max  maximum number of bytes to receive out_data  buffer to store received message Returns: status code of the operation AIR_E_NONE no error AIR_E_NULL invalid socket AIR_E_NOMEM memory allocation failed AIR_E_FAILED nothing received from the socket ********************************************************************

air_err_t air_ssl_recv2 (  air_ssl_socket_t *    ssl, air_xbuf_t *    buf )

alternate form of air_ssl_recv() that uses an xbuf in-place. Parameters: ssl  SSL connection buf  xbuf to which to append bytes we read Returns: An error code: AIR_E_NONE: Success - there is additional data in buf AIR_E_EOF: Other end closed the connection AIR_E_FAILED: SSL/TLS failure of some sort This reads from an SSL connection in-place onto the end of an existing xbuf.

air_openssl_err_t air_ssl_get_last_ierr (    )

Returns the last internal error (of OpenSSL). ********************************************************************** This is not thread safe, since the call to ERR_get_error() is safe. Returns: status code of the operation AIR_E_NONE no error ********************************************************************

air_err_t air_crypto_privkey_fload (  char *    key_fname, EVP_PKEY **    privkey )

Loads a PEM encoded RSA key from disk. ********************************************************************** Parameters: key_fname  (IN) filename of a private key privkey  (OUT) a private key Returns: status code of the operation AIR_E_NONE no error AIR_E_NULL invalid file name AIR_E_NOMEM failure to allocate a new OpenSSL BIO AIR_E_INVALID invalid file name, or a PEM encoded private key was not found in the specified file ********************************************************************

air_err_t air_crypto_crt_fload (  char *    crt_fname, X509 **    cert )

Loads a PEM encoded X.509 certificate from disk. ********************************************************************** Parameters: key_fname  (IN) filename of an X.509 certificate privkey  (OUT) an X.509 certificate Returns: status code of the operation AIR_E_NONE no error AIR_E_NULL invalid file name AIR_E_NOMEM failure to allocate a new OpenSSL BIO AIR_E_INVALID invalid file name, or a PEM encoded certificate was not found in the specified file ********************************************************************

air_err_t air_http_make_request (  ualloc_t *    ua, air_xbuf_t *    in_data, char *    script, air_xbuf_t **    out_data )

Accepts a buffer and formats it into an HTTP POST request. ********************************************************************** Parameters: in_data  (IN) buffer to send script  (IN) name of the file to which to send the POST request ua  (IN) custom memory allocater out_data  (OUT) newly allocated buffer containing the response Returns: status code of the operation AIR_E_NONE no error AIR_E_NULL empty send buffer (in_data), or file name (script) for the POST request ********************************************************************

---

libair v0.3.33