Open Secure Connection with SSL-TLS

Requirements

To open a secure HTTP connection with µC/HTTP-client, the below requirements are needed:

A network security module (such as Mocana - NanoSSL) is necessary
The µC/TCP-IP stack needs to be configure accordingly (see Section Transport Layer Security Configuration).
The client side needs to install certificate authorities to authenticate the identity of each public key certificate sent by servers.

Please refer to section Secure Sockets TLS or SSL for an example on how to use µC/TCP-IP to open a secure socket for a client application.

µC/HTTP-client parameters

µC/HTTP-client offers two parameters to configure the secure connection:

The first parameter is optional and give the option to specify the Common Name linked to the Secure Certificate to identify it with the certificate authorities. If this parameter is not set the server host name will be used.

The second parameter is mandatory to open a secure connection and therefore when this parameter is specified, the µC/HTTP-client stack will assume that the connection to open must be secured. The parameter specified the hook function used by the secure module to ask the upper application to verify and validate the public key certificate send by the server.

Both parameters must be configure with the function HTTPc_ConnSetParam.

Example

Listing - Secure Connection Example Code

HTTPc_CONN_OBJ  conn;


/*
*********************************************************************************************************
*                                       HTTPcEx_ConnPrepare()
*
* Description : Example function to prepare the HTTPc Connection.
*
* Argument(s) : p_conn  Pointer to HTTPc Connection object to set up.
*
* Return(s)   : DEF_YES, if Connection preparation successful.
*               DEF_NO,  otherwise.
*********************************************************************************************************
*/

CPU_BOOLEAN  HTTPcEx_ConnPrepare (HTTPc_CONN_OBJ  *p_conn)
{ 
	HTTPc_ERR   err;

                                                                /* ---------------- INIT NEW CONNECTION --------------- */
    HTTPc_ConnClr(p_conn, &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* --------------- SET CONN'S CALLBACKS --------------- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_CONN_CONNECT_CALLBACK,
                      &HTTPcEx_ConnConnectCallback,
                      &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK,
                      &HTTPcEx_ConnCloseCallback,
                      &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                                /* --------- SET CONNECTION SECURE PARAMETERS --------- */
	HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_SECURE_TRUST_CALLBACK
                      &HTTPcEx_ConnSecureCallback,
                      &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }

    return (DEF_OK);
}


/*
*********************************************************************************************************
*                                       HTTPcEx_ConnCloseCallback()
*
* Description : Example Callback Function to validate public key from server.
*
* Argument(s) : p_cert_dn   Pointer to certificate distinguished name.
* 
*               reason      Reason why certificate is not trusted:
*                               NET_SOCK_SECURE_UNTRUSTED_BY_CA
*                               NET_SOCK_SECURE_EXPIRE_DATE
*                               NET_SOCK_SECURE_INVALID_DATE
*                               NET_SOCK_SECURE_SELF_SIGNED
*
* Return(s)   : DEF_YES, if certificate is valid.
*               DEF_NO,  otherwise.
*********************************************************************************************************
*/

CPU_BOOLEAN  HTTPcEx_ConnCloseCallback (void                              *p_cert_dn,
                                        NET_SOCK_SECURE_UNTRUSTED_REASON   reason)
{
    return (DEF_YES);
}