@CHIP-RTOS - Data Structures used in TCP/IP SSL API

    IPC@CHIP® Documentation Index

Data Structures

Here are the structures and other data types used by the TCP/IP SSL API.
All constants and data structures are defined in the TCPIPAPI.H header file.

Related : Contents :

  • SslProblemS

  • SslProblemS

    SSL handshake problems are reported using the following structure type.

    typedef struct tag_SslProblem
        int             spErrorCode;
        unsigned        spPkiFlags;     // Certificate error flags.
        unsigned char   spState;
        unsigned char   spEvent;
        unsigned char   spFuncIdx;
        unsigned char   spHandshakeMsgType;
    } SslProblemS;


    This structure is defined in tcpip.h.   The elements are used as follows:

      TCP/IP stack error code, or one of these extended error codes (400 series) which are specific to SSL.

      If non-zero, a bit field indicating problems dealing with PKI certificates. The bits are these flags bit wise OR'ed together.

      Example: PKI_CERT_BADCERT , bit 0x01.

      When non-zero, this is the state of SSL handshake state machine when the failure occurred. The set of possible states depends on whether the socket is for an SSL server or an SSL client.

      An SSL server has the following 9 states:

        1 - Initial state
        2 - Received the regular Client Hello
        3 - Received the resuming Client Hello
        4 - Received the client certificate
        5 - Received the client KE
        6 - Received the client certificate verify
        7 - Received the regular change cipher
        8 - Received the resuming change cipher
        9 - Server Opened

      An SSL client has the following 11 states:

        1 - Initial state
        2 - Sent Hello
        3 - Received regular server Hello
        4 - Received the resuming server Hello
        5 - Received the server certificate
        6 - Received server certificate request
        7 - Received server key exchange
        8 - Sent client Finished to server
        9 - Received the resuming change cipher
        10 - Received the resuming change cipher
        11 - Client Opened


      When non-zero, this enumerator indicates either the SSL handshake state machine event that preceded the failure (values less than 10), or the alert signal received (values 10 through 119) or sent (values above 120, where the actual alert sent was 120 less than the reported spEvent value). The set of events depends on whether the socket is for an SSL server or an SSL client.

      An SSL server detects the following 7 events:

        1 - Client regular Hello received
        2 - Client resume Hello received
        3 - Client certificate received
        4 - Received client key exchange
        5 - Certificate received from client verified
        6 - Received change cipher from client
        7 - Handshake finished received

      An SSL client detects the following 9 events:

        1 - Sent Hello message out to server
        2 - Server regular Hello received
        3 - Server resume Hello received
        4 - Certificate from server received and parsed
        5 - Certificate request from server received
        6 - Received server key exchange
        7 - Hello done
        8 - Server Change Cipher handshake message parsed
        9 - Server finished message received and parsed

      Alert codes: Greater or equal to 10 ...

      Typically the alert codes correspond to specific problems encountered during the key negotiations. Received alert codes will appear in the spEvent member with the numbers as listed below from RFC 5246 section 7.2 "Alert Protocol" .

      Alert codes that were sent out from the @chiprtos appear in the spEvent member with an extra 120 added to the alert code listed in the RFC 5246. For example, 160 corresponds to "Handshake Failure" alert code 40. So the 120 bias differentiates whether our side or the peer side was the one detecting the problem which lead to an alert.

      Note: These alert codes were added to the reporting in @chiprtos version 2.05.   (Prior @chiprtos only reported the above state machine events.)

      This list of alert codes is not complete. Only those which might be expected when operating with the @chiprtos SSL are cited here. Refer to the RFC for a more complete list. The alert codes with descriptions stated here within paranthesis are never sent out by the @chiprtos, but they could possibly be received.

        10 - Unexpected message
        20 - Bad record MAC
        22 - Record overflow
        40 - Handshake failure
        41 - No certificate
        42 - Bad certificate
        43 - (Unsupported certificate)
        44 - (Certificate revoked)
        45 - (Certificate expired)
        46 - (Certificate unknown)
        47 - (Illegal parameter)
        48 - (Unknown Certificate Authority (CA))
        49 - (Access denied)
        50 - (Decode error)
        51 - (Decrypt error)
        70 - (Protocol version)
        71 - (Issufficient security)
        80 - (Internal error)
        90 - (User canceled)
        100 - No renegotiation
        110 - (Unsupported extension)


      When spState is non-zero, this index indicates what function within the SSL handshake state machine was executed at the failure. The set of functions depends on whether the socket is for an SSL server or an SSL client.

      An SSL server's state machine uses 9 action functions which do the following:

        0 - Server Pre Reply
        1 - Send server Hello.
        2 - Send certificate.
        3 - Build key exchange data.
        4 - Build certificate request.
        5 - Build and send server hello done.
        6 - Build server change cipher message.
        7 - Build and send FINISHED handshake message.
        8 - Send queued data.

      An SSL client's state machine uses 8 action functions:

        0 - Send Client Hello.
        1 - Client Pre Reply
        2 - Send Certificate.
        3 - Send key exchange.
        4 - Build the certificate verify handshake message.
        5 - Build the client change cipher message.
        6 - Build and send FINISHED handshake message.
        7 - Send queued data.


      This byte indicates the context of the incoming message that was processed at the time an error was detected. It is the handshake protocol byte extracted from the incoming SSL message.

      One of the following values would be expected for a SSL Server.

        1 - Client Hello
        11 - Client Certificate
        15 - Certificate verify
        16 - Client Key Exchange
        20 - Handshake finished

      For a SSL client, one of the following values would be expected.

        0 - Hello Request
        2 - Server Hello
        11 - Server Certificate
        12 - Server Key Exchange
        13 - Certificate request
        14 - Server Hello done
        20 - Handshake finished

    Related Topics

    SSL_CheckProblem() API - Read out SSL problem status report.

    Supported since or modified in @CHIP-RTOS version


    Top of list
    Index page


    typedef struct tag_ssl_session_new_entry
      char far *    certIdentity; // SSL server/client own certificate name
      unsigned int  maxCaches;    // Maximum number of caches for this session
      int           version;      // The SSL version number for this session
                                  // Bit0: SSL 3.0
                                  // Bit1: TLS 1.0
                                  // Bit2: TLS 1.1
                                  // Bit3: TLS 1.2
    } SSL_SESSION_NEW_Entry;


    If the value in maxCaches is zero, there is no cache at all. That means there is no connection resumption at all. Note that each cache entry will consume about 118 bytes memory.

    The version bit field parameter specifies which Secure Socket Layer (SSL) or Transport Layer Security (TLS) protocols shall be permitted during this session.

    Warning :

      The SSL 3.0 protocol is no longer considered secure. Therefore setting bit 0 in the version parameter is not recommended.

    Related Topics

    API function SSL_SessionNew() - Open a new SSL session

    Supported since or modified in @CHIP-RTOS version


    Top of list
    Index page

    End of document