wolfSSL Initialization/Shutdown

Functions

	Name
int	wolfSSL_shutdown(WOLFSSL * ) この関数は、引数sslのSSLセッションに対してアクティブなSSL/TLS接続をシャットダウンします。 この関数は、ピアに"Close Notify"アラートを送信しようとします。 呼び出し側アプリケーションは、Peerがその"Close Notify"アラートを応答として送信してくるのを待つか、 またはwolfSSL_shutdownから呼び出しが戻った時点で（リソースを保存するために）下層の接続を切断するのを待つことができます。 どちらのオプションもTLS仕様で許されています。シャットダウンした後に下層の接続を再び別のセッションで使用する予定ならば、ピア間で同期を保つために完全な2方向のシャットダウン手順を実行する必要があります。 wolfSSL_shutdown()は、ブロックとノンブロッキングI/Oの両方で動作します。 下層のI/Oがノンブロッキングの場合、wolfSSL_shutdown()が要求を満たすことができなかった場合、wolfSSL_shutdown()はエラーを返します。 この場合、wolfSSL_get_error()への呼び出しはSSL_ERROR_WANT_READまたはSSL_ERROR_WANT_WRITEのいずれかを生成します。 その結果、下層のI/Oが準備ができたら、呼び出し側プロセスはwolfSSL_shutdown()への呼び出しを繰り返す必要があります。
int	wolfSSL_SetServerID(WOLFSSL * ssl, const unsigned char * id, int len, int newSession) この関数はクライアントセッションをサーバーIDと関連付けます。引数newSessionがオンの場合、既存のセッションは再利用されません。
int	wolfSSL_library_init(void ) この関数はwolfSSL_CTX_new()内で内部的に呼び出されます。 この関数はwolfSSL_Init()のラッパーで、wolfSSLがOpenSSL互換層でコンパイルされたときのOpenSSL　API（ssl_library_init）との互換性の為に存在します。 wolfSSL_init()は、より一般的に使用されているwolfSSL初期化機能です。
int	wolfSSL_get_shutdown(const WOLFSSL * ssl) この関数は、Options構造体のcloseNotifyまたはconnResetまたはsentNotifyメンバーのシャットダウン条件をチェックします。 Options構造体はWOLFSSL構造体内にあります。
int	wolfSSL_is_init_finished(WOLFSSL * ssl) この関数は、接続が確立されているかどうかを確認します。
int	wolfSSL_Init(void ) 使用するためにWolfSSLライブラリを初期化します。アプリケーションごとに1回、その他のライブラリへの呼び出しの前に呼び出す必要があります。
int	wolfSSL_Cleanup(void ) さらなる使用からWOLFSSLライブラリを初期化します。ライブラリによって使用されるリソースを解放しますが、呼び出される必要はありません。
int	wolfSSL_SetMinVersion(WOLFSSL * ssl, int version) この関数は、許可されている最小のダウングレードバージョンを設定します。接続が（wolfsslv23_client_methodまたはwolfsslv23_server_method）を使用して、接続がダウングレードできる場合にのみ適用されます。
int	wolfSSL_ALPN_GetProtocol(WOLFSSL * ssl, char ** protocol_name, unsigned short * size) この関数は、サーバーによって設定されたプロトコル名を取得します。
int	wolfSSL_ALPN_GetPeerProtocol(WOLFSSL * ssl, char ** list, unsigned short * listSz) この関数は、alpn_client_listデータをSSLオブジェクトからバッファにコピーします。
int	wolfSSL_MakeTlsMasterSecret(unsigned char * ms, word32 msLen, const unsigned char * pms, word32 pmsLen, const unsigned char * cr, const unsigned char * sr, int tls1_2, int hash_type) この関数はCRとSRの値をコピーしてからWC_PRF（疑似ランダム関数）に渡し、その値を返します。
int	wolfSSL_preferred_group(WOLFSSL * ssl) この関数は、クライアントがTLS v1.3ハンドシェイクで使用することを好む鍵交換グループを返します。この情報を完了した後にこの機能を呼び出して、サーバーがどのグループが予想されるようにこの情報が将来の接続で使用できるようになるかを決定するために、この情報が将来の接続で鍵交換のための鍵ペアを事前生成することができます。

Functions Documentation

function wolfSSL_shutdown

int wolfSSL_shutdown(
    WOLFSSL * 
)

この関数は、引数sslのSSLセッションに対してアクティブなSSL/TLS接続をシャットダウンします。 この関数は、ピアに"Close Notify"アラートを送信しようとします。 呼び出し側アプリケーションは、Peerがその"Close Notify"アラートを応答として送信してくるのを待つか、 またはwolfSSL_shutdownから呼び出しが戻った時点で（リソースを保存するために）下層の接続を切断するのを待つことができます。 どちらのオプションもTLS仕様で許されています。シャットダウンした後に下層の接続を再び別のセッションで使用する予定ならば、ピア間で同期を保つために完全な2方向のシャットダウン手順を実行する必要があります。 wolfSSL_shutdown()は、ブロックとノンブロッキングI/Oの両方で動作します。 下層のI/Oがノンブロッキングの場合、wolfSSL_shutdown()が要求を満たすことができなかった場合、wolfSSL_shutdown()はエラーを返します。 この場合、wolfSSL_get_error()への呼び出しはSSL_ERROR_WANT_READまたはSSL_ERROR_WANT_WRITEのいずれかを生成します。 その結果、下層のI/Oが準備ができたら、呼び出し側プロセスはwolfSSL_shutdown()への呼び出しを繰り返す必要があります。

Parameters:

• ssl wolfSSL_new()を使用して作成されたWOLFSSL構造体へのポインタ

See:

• wolfSSL_free
• wolfSSL_CTX_free

Return:

• SSL_SUCCESS 成功時に返されます。
• SSL_SHUTDOWN_NOT_DONE シャットダウンが終了していない場合に返され、関数を再度呼び出す必要があります。
• SSL_FATAL_ERROR 失敗したときに返されます。より具体的なエラーコードはwolfSSL_get_error()を呼び出します。

Example

#include <wolfssl/ssl.h>

int ret = 0;
WOLFSSL* ssl = 0;
...
ret = wolfSSL_shutdown(ssl);
if (ret != 0) {
    // failed to shut down SSL connection
}

function wolfSSL_SetServerID

int wolfSSL_SetServerID(
    WOLFSSL * ssl,
    const unsigned char * id,
    int len,
    int newSession
)

この関数はクライアントセッションをサーバーIDと関連付けます。引数newSessionがオンの場合、既存のセッションは再利用されません。

Parameters:

• ssl wolfSSL_new()を使用して作成されたWOLFSSL構造体へのポインタ。
• id WOLFSSL_SESSION構造体のServerIDメンバーにコピーされるサーバーIDデータへのポインタ。
• len サーバーIDデータのサイズ
• newSession セッションを再利用するか否かを指定するフラグ。オンの場合、既存のセッションは再利用されません。

See: wolfSSL_set_session

Return:

• SSL_SUCCESS 関数がエラーなしで実行された場合に返されます。
• BAD_FUNC_ARG 引数sslまたは引数idがNULLの場合、または引数lenがゼロ以下の場合に返されます。

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol );
WOLFSSL* ssl = WOLFSSL_new(ctx);
const byte id[MAX_SIZE];  // or dynamically create space
int len = 0; // initialize length
int newSession = 0; // flag to allow
…
int ret = wolfSSL_SetServerID(ssl, id, len, newSession);

if (ret == WOLFSSL_SUCCESS) {
    // The Id was successfully set
}

function wolfSSL_library_init

int wolfSSL_library_init(
    void 
)

この関数はwolfSSL_CTX_new()内で内部的に呼び出されます。 この関数はwolfSSL_Init()のラッパーで、wolfSSLがOpenSSL互換層でコンパイルされたときのOpenSSL　API（ssl_library_init）との互換性の為に存在します。 wolfSSL_init()は、より一般的に使用されているwolfSSL初期化機能です。

See:

• wolfSSL_Init
• wolfSSL_Cleanup

Return:

• SSL_SUCCESS 成功した場合に返されます。に返されます。
• SSL_FATAL_ERROR 失敗したときに返されます。

Example

int ret = 0;
ret = wolfSSL_library_init();
if (ret != SSL_SUCCESS) {
    failed to initialize wolfSSL
}
...

function wolfSSL_get_shutdown

int wolfSSL_get_shutdown(
    const WOLFSSL * ssl
)

この関数は、Options構造体のcloseNotifyまたはconnResetまたはsentNotifyメンバーのシャットダウン条件をチェックします。 Options構造体はWOLFSSL構造体内にあります。

Parameters:

• ssl wolfSSL_new()を使用して作成されたWOLFSSL構造体へのポインタ

See: wolfSSL_SESSION_free

Return:

• 1 SSL_SENT_SHUTDOWNが返されます。
• 2 SSL_RECEIVED_SHUTDOWNが返されます。

Example

#include <wolfssl/ssl.h>

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = WOLFSSL_new(ctx);
…
int ret;
ret = wolfSSL_get_shutdown(ssl);

if(ret == 1){
    SSL_SENT_SHUTDOWN
} else if(ret == 2){
    SSL_RECEIVED_SHUTDOWN
} else {
    Fatal error.
}

function wolfSSL_is_init_finished

int wolfSSL_is_init_finished(
    WOLFSSL * ssl
)

この関数は、接続が確立されているかどうかを確認します。

Parameters:

• ssl wolfSSL_new()を使用して作成されたWOLFSSL構造体へのポインタ

See:

• wolfSSL_set_accept_state
• wolfSSL_get_keys
• wolfSSL_set_shutdown

Return:

• 0 接続が確立されていない場合、すなわちWolfSSL構造体がNULLまたはハンドシェイクが行われていない場合に返されます。
• 1 接続が確立されていない場合は返されます.WolfSSL構造体はNULLまたはハンドシェイクが行われていません。

Example

#include <wolfssl/ssl.h>

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = wolfSSL_new(ctx);
...
if(wolfSSL_is_init_finished(ssl)){
    Handshake is done and connection is established
}

function wolfSSL_Init

int wolfSSL_Init(
    void 
)

使用するためにWolfSSLライブラリを初期化します。アプリケーションごとに1回、その他のライブラリへの呼び出しの前に呼び出す必要があります。

See: wolfSSL_Cleanup

Return:

• SSL_SUCCESS 成功した場合に返されます。、通話が戻ります。
• BAD_MUTEX_E 返される可能性があるエラーです。

Example

int ret = 0;
ret = wolfSSL_Init();
if (ret != SSL_SUCCESS) {
    failed to initialize wolfSSL library
}

function wolfSSL_Cleanup

int wolfSSL_Cleanup(
    void 
)

さらなる使用からWOLFSSLライブラリを初期化します。ライブラリによって使用されるリソースを解放しますが、呼び出される必要はありません。

See: wolfSSL_Init

Return: SSL_SUCCESS エラーを返しません。

Example

wolfSSL_Cleanup();

function wolfSSL_SetMinVersion

int wolfSSL_SetMinVersion(
    WOLFSSL * ssl,
    int version
)

この関数は、許可されている最小のダウングレードバージョンを設定します。接続が（wolfsslv23_client_methodまたはwolfsslv23_server_method）を使用して、接続がダウングレードできる場合にのみ適用されます。

Parameters:

• ssl wolfSSL_new()を使用して作成されたWOLFSSL構造体へのポインタ

See: SetMinVersionHelper

Return:

• SSL_SUCCESS この関数とそのサブルーチンがエラーなしで実行された場合に返されます。
• BAD_FUNC_ARG SSLオブジェクトがNULLの場合に返されます。サブルーチンでは、良いバージョンが一致しない場合、このエラーはスローされます。

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
WOLFSSL* ssl = WOLFSSL_new(ctx);
int version;  macro representation
…
if(wolfSSL_CTX_SetMinVersion(ssl->ctx, version) != SSL_SUCCESS){
    Failed to set min version
}

function wolfSSL_ALPN_GetProtocol

int wolfSSL_ALPN_GetProtocol(
    WOLFSSL * ssl,
    char ** protocol_name,
    unsigned short * size
)

この関数は、サーバーによって設定されたプロトコル名を取得します。

Parameters:

• ssl wolfSSL_new()を使用して作成されたWolfSSL構造へのポインタ。
• protocol_name プロトコル名を表すCHARへのポインタは、ALPN構造に保持されます。

See:

• TLSX_ALPN_GetRequest
• TLSX_Find

Return:

• SSL_SUCCESS エラーが投げられていない正常な実行に戻りました。
• SSL_FATAL_ERROR 拡張子が見つからなかった場合、またはピアとプロトコルが一致しなかった場合に返されます。2つ以上のプロトコル名が受け入れられている場合は、スローされたエラーもあります。
• SSL_ALPN_NOT_FOUND ピアとプロトコルの一致が見つからなかったことを示す返されました。
• BAD_FUNC_ARG 関数に渡されたnull引数があった場合に返されます。

Example

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
WOLFSSL* ssl = WOLFSSL_new(ctx);
...
int err;
char* protocol_name = NULL;
Word16 protocol_nameSz = 0;
err = wolfSSL_ALPN_GetProtocol(ssl, &protocol_name, &protocol_nameSz);

if(err == SSL_SUCCESS){
    // Sent ALPN protocol
}

function wolfSSL_ALPN_GetPeerProtocol

int wolfSSL_ALPN_GetPeerProtocol(
    WOLFSSL * ssl,
    char ** list,
    unsigned short * listSz
)

この関数は、alpn_client_listデータをSSLオブジェクトからバッファにコピーします。

Parameters:

• ssl wolfSSL_new()を使用して作成されたWolfSSL構造へのポインタ。
• list バッファへのポインタ。SSLオブジェクトからのデータがコピーされます。

See: wolfSSL_UseALPN

Return:

• SSL_SUCCESS 関数がエラーなしで実行された場合に返されます。SSLオブジェクトのALPN_CLIENT_LISTメンバーがLISTパラメータにコピーされました。
• BAD_FUNC_ARG listまたはlistszパラメーターがnullの場合に返されます。
• BUFFER_ERROR リストバッファに問題がある場合は（NULLまたはサイズが0の場合）に問題がある場合に返されます。
• MEMORY_ERROR メモリを動的に割り当てる問題がある場合に返されます。

Example

#import <wolfssl/ssl.h>

WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method);
WOLFSSL* ssl = wolfSSL_new(ctx);
…
#ifdef HAVE_ALPN
char* list = NULL;
word16 listSz = 0;
…
err = wolfSSL_ALPN_GetPeerProtocol(ssl, &list, &listSz);

if(err == SSL_SUCCESS){
    List of protocols names sent by client
}

function wolfSSL_MakeTlsMasterSecret

int wolfSSL_MakeTlsMasterSecret(
    unsigned char * ms,
    word32 msLen,
    const unsigned char * pms,
    word32 pmsLen,
    const unsigned char * cr,
    const unsigned char * sr,
    int tls1_2,
    int hash_type
)

この関数はCRとSRの値をコピーしてからWC_PRF（疑似ランダム関数）に渡し、その値を返します。

Parameters:

• ms マスターシークレットはアレイ構造に保持されています。
• msLen マスターシークレットの長さ。
• pms マスター前の秘密はアレイ構造に保持されています。
• pmsLen マスタープレマスターシークレットの長さ。
• cr クライアントのランダム
• sr サーバーのランダムです。
• tls1_2 バージョンが少なくともTLSバージョン1.2であることを意味します。

See:

• wc_PRF
• MakeTlsMasterSecret

Return:

• 0 成功した
• BUFFER_E バッファのサイズにエラーが発生した場合に返されます。
• MEMORY_E サブルーチンが動的メモリを割り当てることができなかった場合に返されます。

Example

WOLFSSL* ssl;

called in MakeTlsMasterSecret and retrieves the necessary
information as follows:

int MakeTlsMasterSecret(WOLFSSL* ssl){
int ret;
ret = wolfSSL_makeTlsMasterSecret(ssl->arrays->masterSecret, SECRET_LEN,
ssl->arrays->preMasterSecret, ssl->arrays->preMasterSz,
ssl->arrays->clientRandom, ssl->arrays->serverRandom,
IsAtLeastTLSv1_2(ssl), ssl->specs.mac_algorithm);
…
return ret;

}

function wolfSSL_preferred_group

int wolfSSL_preferred_group(
    WOLFSSL * ssl
)

この関数は、クライアントがTLS v1.3ハンドシェイクで使用することを好む鍵交換グループを返します。この情報を完了した後にこの機能を呼び出して、サーバーがどのグループが予想されるようにこの情報が将来の接続で使用できるようになるかを決定するために、この情報が将来の接続で鍵交換のための鍵ペアを事前生成することができます。

Parameters:

• ssl wolfSSL_new()を使用して作成されたWOLFSSL構造体へのポインタ。

See:

• wolfSSL_UseKeyShare
• wolfSSL_CTX_set_groups
• wolfSSL_set_groups
• wolfSSL_CTX_set1_groups_list
• wolfSSL_set1_groups_list

Return:

• BAD_FUNC_ARG sslがNULLの場合、またはTLS v1.3を使用していない場合。
• SIDE_ERROR サーバーで呼び出された場合。
• NOT_READY_ERROR ハンドシェイクが完了する前に呼び出された場合。

Example

int ret;
int group;
WOLFSSL* ssl;
...
ret = wolfSSL_CTX_set1_groups_list(ssl)
if (ret < 0) {
    // failed to get group
}
group = ret;

---

Updated on 2024-11-21 at 02:35:59 +0000