SOCSslConnection

C Specification

#include <nitroWiFi/soc.h>
typedef struct SOCSslConnection;

Description

This structure maintains the settings and state for SSL communication. Although this member is generally for use internally to the library, there are some settings that should be performed within the application.

The application must set the following fields prior to calling the SOC_EnableSsl function.

Member Description
char* server_name When the value is not NULL, it is compared with the certificate's server name (Common Name) and the result of the comparison is passed to the callback function. Supports wildcards for the certificate's server name.
int (*auth_callback)(int, SOCSslConnection*, int) This is called each time the certificate authentication task ends. An error code is passed as the first parameter, the pointer to SOCSslConnection is passed as the second parameter, and the number of steps in the authentication chain (initial value = 0) is passed as the third parameter.
Errors can be ignored by changing a passed error code and returning it. Authentication fails if a non-zero value is returned.
SOCCaInfo** ca_info Specifies a list of trusted root certificates.
int ca_builtins Specifies the number of root certificates passed by ca_info.

The following fields can be referenced from SOCSslConnection* functions passed to auth_callback:

Member Description
u8* cert A pointer to the certificate currently being authenticated. SOCCaInfo can be made from this certificate and added to the root certificate.
int certlen The data length of the certificate indicated by cert.
char subject[] Certificate subject.
char issuer[] Certificate issuer.

A normal state is indicated when the first argument passed to auth_callback is 0. Numbers other than 0 are error codes and are as follows. Although auth_callback will basically return the value of the first argument as a return value, error values can be masked to allow SSL connection process to continue if there are errors you wish to ignore.

SOC_CERT_OUTOFDATE The date for the certificate being authenticated has expired.
SOC_CERT_BADSERVER The target host name, set in advance in SOCSslConnection.server_name, and the common name for the certificate do not match.
SOC_CERT_NOROOTCA The root certificate set in SOCSslConnection.ca_info cannot authenticate the certificate chain currently under authentication.
SOC_CERT_BADSIGNATURE The signature for the certificate under authentication cannot be verified. (Creation of the certificate failed on the server, etc.)
SOC_CERT_UNKNOWN_SIGALGORITHM The certificate under authentication uses an unknown signature algorithm.
SOC_CERT_UNKNOWN_PUBKEYALGORITHM The certificate under authentication uses an unknown public key encryption algorithm.

For more information on SSL terminology and server setting methods, please see any number of SSL references commercially available.

The NitroWiFi Library SSL supports the RSA algorithm up to 2048 bits for public key encryption and the RC4 algorithm up to 128 bits for shared key encryption.

See Also

SOCCaInfo, SOC_EnableSsl

Revision History

12/21/2005 Initial version.