wolfSSL Initialization/Shutdown

Functions

	Name
int	wolfSSL_shutdown(WOLFSSL * ) この関数は、SSLセッションSSLを使用してアクティブなSSL / TLS接続をシャットダウンします。この関数は、ピアに「Close Notify」アラートを送信しようとします。呼び出し側アプリケーションは、Peerがその「閉じる通知」アラートを応答に送信するのを待つか、または直接wolfssl_shutdownを呼び出した後（リソースを保存するために）wolfssl_shutdownを直接通話した後に基礎となる接続を停止するのを待つことができます。どちらのオプションはTLS仕様で許可されています。将来、基礎となる接続が再び使用される場合、同期をピア間で無傷のまま保つために完全な2方向のシャットダウン手順を実行する必要があります。 wolfssl_shutdown（）は、ブロックと非ブロッキングI / Oの両方で動作します。基礎となるI / Oがノンブロッキングされていない場合、wolfsl_shutdown（）が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互換性（ssl_library_init）に存在します。wolfssl_init（）は、より一般的に使用されているWolfSSL初期化機能です。
int	wolfSSL_get_shutdown(const WOLFSSL * ) この関数は、Options構造体のClosEnotifyまたはConnresetまたはSentNotifyメンバーのシャットダウン条件をチェックします。オプション構造はWolfSSL構造内にあります。
int	wolfSSL_is_init_finished(WOLFSSL * ) この関数は、接続が確立されているかどうかを確認します。
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がその「閉じる通知」アラートを応答に送信するのを待つか、または直接wolfssl_shutdownを呼び出した後（リソースを保存するために）wolfssl_shutdownを直接通話した後に基礎となる接続を停止するのを待つことができます。どちらのオプションはTLS仕様で許可されています。将来、基礎となる接続が再び使用される場合、同期をピア間で無傷のまま保つために完全な2方向のシャットダウン手順を実行する必要があります。 wolfssl_shutdown（）は、ブロックと非ブロッキングI / Oの両方で動作します。基礎となるI / Oがノンブロッキングされていない場合、wolfsl_shutdown（）がwolfssl_shutdown（）のニーズを満たすことができなかった場合、wolfssl_shutdown（）はエラーを返します。この場合、wolfssl_get_error（）への呼び出しはSSL_ERROR_WANT_READまたはSSL_ERROR_WANT_WRITEのいずれかを生成します。その結果、基礎となるI / Oが準備ができたら、呼び出し側プロセスはwolfssl_shutdown（）への呼び出しを繰り返す必要があります。

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メンバーにコピーされる定数バイトポインタ。
• len セッションIDパラメータの長さを表すint型。 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
}

See: wolfSSL_set_session

Return:

• SSL_SUCCESS 関数がエラーなしで実行された場合に返されます。
• BAD_FUNC_ARG wolfssl structまたはidパラメータがnullの場合、またはLenがゼロ以下の場合に返されます。

function wolfSSL_library_init

int wolfSSL_library_init(
    void 
)

この関数はwolfssl_ctx_new（）内で内部的に呼び出されます。この関数はwolfssl_init（）の周囲のラッパーで、wolfsslがOpenSSL互換層でコンパイルされたときにOpenSSL互換性（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 * 
)

この関数は、Options構造体のClosEnotifyまたはConnresetまたはSentNotifyメンバーのシャットダウン条件をチェックします。オプション構造はWolfSSL構造内にあります。

See: wolfSSL_SESSION_free

Return:

• 1 SSL_SENT_SHUTDOWNが返されます。
• 2 ss_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 * 
)

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

See:

• wolfSSL_set_accept_state
• wolfSSL_get_keys
• wolfSSL_set_shutdown

Return:

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

#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構造へのポインタ。 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
}

See: SetMinVersionHelper

Return:

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

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構造に保持されます。 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
}

See:

• TLSX_ALPN_GetRequest
• TLSX_Find

Return:

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

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オブジェクトからのデータがコピーされます。 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
}

See: wolfSSL_UseALPN

Return:

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

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であることを意味します。 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;

}

See:

• wc_PRF
• MakeTlsMasterSecret

Return:

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

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 2023-03-29 at 08:44:33 +0000