SOCSslConnection

構文

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

説明

SSL 通信の設定と状態を保持する構造体です。基本的にはライブラリの内部使用のためのメンバですが、一部、アプリケーション側で設定するべき項目があります。

SOC_EnableSsl() を呼び出す前にアプリケーションは以下のフィールドを設定する必要があります。

メンバ 説明
char* server_name 非NULLの時、証明書のサーバ名(Common Name)との比較が行われ、その結果がコールバック関数に渡される。証明書のサーバ名としてのワイルドカードをサポートしている。
int (*auth_callback)(int, SOCSslConnection*, int) 証明書の認証作業が終わる度に呼び出される。最初のパラメータとしてエラーコードが、二番目のパラメータとしてSOCSslConnectionへのポインタが、三つ目のパラメータとして認証チェーン内の段数(初期値は0)が渡される。
渡されたエラーコードを変更して返すことによってエラーを無視することが出来る。非0を返すと認証は失敗する。
SOCCaInfo** ca_info 信頼するルート証明書の一覧を指定する。
int ca_builtins ca_info で渡したルート証明書の数を指定する。

また、auth_callback に渡される SOCSslConnection* から、以下のフィールドを参照することができます。

メンバ 説明
u8* cert 現在認証作業中の証明書へのポインタ。この証明書を元にして SOCCaInfo を作りルート証明に追加することが出来る。
int certlen cert が示す証明書データの長さ。
char subject[] 証明書の subject。
char issuer[] 証明書の issuer。

auth_callback に渡される第1引数は0が正常を示します。0以外のエラーコードは以下のようになっています。 auth_callback では基本的には第1引数の値をそのまま返り値として返しますが、無視したいエラーがあった場合は そのエラー値をマスクして返すことで SSL の接続処理を継続することができます。

SOC_CERT_OUTOFDATE 現在検証中の証明書は有効期限が切れている。
SOC_CERT_BADSERVER SOCSslConnection.server_name にあらかじめ設定していた接続先のホスト名と証明書の common name が一致しない。
SOC_CERT_NOROOTCA SOCSslConnection.ca_info に設定したルート証明書では現在検証中の証明書チェインを認証できない。
SOC_CERT_BADSIGNATURE 現在検証中の証明書の署名が認証できない。(サーバ側で証明書の作成に失敗しているなど)
SOC_CERT_UNKNOWN_SIGALGORITHM 現在検証中の証明書では知らない署名アルゴリズムが使用されている。
SOC_CERT_UNKNOWN_PUBKEYALGORITHM 現在検証中の証明書では知らない公開鍵暗号のアルゴリズムが使用されている。

SOC_EnableSsl() に渡した SOCSslConnection 構造体は、適用したソケットが完全に終了するまでメモリ領域を確保しておく必要があります。具体的には、SOC_Close() が2回目の0を返すまではメモリ領域を他の用途で使用しないようにしてください。

なお、SSL 関連の用語やサーバ側の設定方法などは、市販の SSL に関する解説書を参照してください。

TwlWiFi ライブラリの SSL では、公開鍵暗号アルゴリズムとして 2048bit までの RSA アルゴリズムを、 共通鍵暗号アルゴリズムとして 128bit までの RC4 アルゴリズムをサポートしてます。

参照

SOCCaInfo, SOC_EnableSsl

履歴

2007/1/19 SOCSslConnection 構造体を保持するべき期間について追記
2005/12/21 初版