#include <nitroWiFi/soc.h>
typedef struct SOCSslConnection;
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.
12/21/2005 Initial version.