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

Data Structures

• TCP/IP API Data Structures
• IP Security Data Structures
• TCP/IP Cryptographic API Data Structures
• TCP/IP Device Driver API Data Structures

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;

Comments

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

spErrorCode

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

spPkiFlags

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.

spState

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

spEvent

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)

spFuncIdx

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.

spHandshakeMsgType

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

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V2.04	V2.04

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;

Comments

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

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V2.05	V2.05