Oracle Solaris セキュリティーサービス開発ガイド

PKCS #11 を使用するための関数

ここでは、PKCS #11 を使用するための関数のうち、次のものについて説明します。


注 –

libpkcs11.so ライブラリではすべての PKCS #11 関数が利用可能になっています。C_GetFunctionList() 関数を使用して利用可能な関数のリストを取得する必要はありません。


PKCS #11 関数: C_Initialize()

C_Initialize() は PKCS #11 ライブラリを初期化します。C_Initialize() の構文は次のとおりです。

C_Initialize(CK_VOID_PTR pInitArgs);

pInitArgs は、空値 NULL_PTR または CK_C_INITIALIZE_ARGS 構造体へのポインタです。NULL_PTR が指定された場合、ライブラリは Solaris の相互排他ロックをロックプリミティブとして使用することで、複数スレッドによる内部共有構造体へのアクセスを制御します。Solaris 暗号化フレームワークは相互排他ロックを受け入れないことに注意してください。この実装版の cryptoki ライブラリは、マルチスレッド処理を安全かつ効率的に処理しますので、NULL_PTR を使用することをお勧めします。またアプリケーション内で、pInitArgs を使用して CKF_LIBRARY_CANT_CREATE_OS_THREADS などのフラグを設定することも可能です。C_Finalize() は、アプリケーションが PKCS #11 ライブラリを使用し終わったことを通知します。


注 –

C_Finalize() は決してライブラリ内から呼び出してはいけません。一般に、C_Finalize() を呼び出してセッションをクローズすることはアプリケーションの責任です。


CKR_FUNCTION_FAILED、CKR_GENERAL_ERROR、CKR_HOST_MEMORY、CKR_OK に加え、C_Initialize() は次の戻り値を使用します。

PKCS #11 関数: C_GetInfo()

C_GetInfo() は、cryptoki ライブラリに関する開発元情報とバージョン情報を取得します。C_GetInfo() の構文は次のとおりです。

C_GetInfo(CK_INFO_PTR pInfo);

C_GetInfo() は次の値を返します。

CKR_FUNCTION_FAILED、CKR_GENERAL_ERROR、CKR_HOST_MEMORY、CKR_OK に加え、C_GetInfo() は次の戻り値を使用します。

PKCS #11 関数: C_GetSlotList()

C_GetSlotList() は、利用可能なスロットのリストを取得します。pkcs11_softtoken.so 以外の暗号化プロバイダがインストールされていない場合、C_GetSlotList() から返されるのは、デフォルトのスロットだけです。C_GetSlotList() の構文は次のとおりです。

C_GetSlotList(CK_BBOOL tokenPresent, CK_SLOT_ID_PTR pSlotList, 
CK_ULONG_PTR pulCount);

tokenPresent に TRUE を設定した場合、トークンが存在するスロットだけに検索対象が限定されます。

pSlotList に NULL_PTR を設定した場合、C_GetSlotlist() はスロット数だけを返します。pulCount はスロット数を格納する場所へのポインタです。

pSlotList にスロットを格納するバッファーへのポインタを設定した場合、*pulCount には CK_SLOT_ID 要素の予想最大数を設定します。戻り時には、*pulCount に CK_SLOT_ID 要素の実際の個数が設定されます。

通常、PKCS #11 アプリケーションは C_GetSlotList() を 2 回呼び出します。1 回目の C_GetSlotList() 呼び出しでは、メモリーを割り当てる目的でスロット数を取得します。そして 2 回目の C_GetSlotList() 呼び出しでは、スロットを取得します。


注 –

スロットの順序は保証されません。スロットの順序は、PKCS #11 ライブラリを読み込むたびに変わる可能性があります。


CKR_FUNCTION_FAILED、CKR_GENERAL_ERROR、CKR_HOST_MEMORY、CKR_OK に加え、C_GetSlotlist() は次の戻り値を使用します。

PKCS #11 関数: C_GetTokenInfo()

C_GetTokenInfo() は、特定のトークンに関する情報を取得します。 C_GetTokenInfo() の構文は次のとおりです。

C_GetTokenInfo(CK_SLOT_ID slotID, CK_TOKEN_INFO_PTR pInfo);

slotID は、目的のトークンに対するスロットの ID です。slotID は、C_GetSlotList() から返された有効な ID でなければなりません。pInfo は、トークン情報を格納する場所へのポインタです。

pkcs11_softtoken.so がインストールされている唯一のプロバイダである場合、C_GetTokenInfo() は次のフィールドと値を返します。

CKR_FUNCTION_FAILED、CKR_GENERAL_ERROR、CKR_HOST_MEMORY、CKR_OK に加え、C_GetSlotlist() は次の戻り値を使用します。

次の戻り値は、プラグインされたハードウェアトークンに関するものです。

PKCS #11 関数: C_OpenSession()

C_OpenSession() を使えば、アプリケーションは特定のスロット内の特定のトークンとの間で暗号化セッションを開始できます。C_OpenSession() の構文は次のとおりです。

C_OpenSession(CK_SLOT_ID slotID, CK_FLAGS flags, CK_VOID_PTR pApplication, 
CK_NOTIFY Notify, CK_SESSION_HANDLE_PTR phSession);

slotID はスロットの ID です。flags は、セッションを読み書き可能にするか、あるいは読み取り専用にするかを示します。pApplication は、アプリケーションによってコールバック用として定義されたポインタです。Notify には、オプションのコールバック関数のアドレスが格納されます。phSession は、セッションハンドルの格納場所へのポインタです。

CKR_FUNCTION_FAILED、CKR_GENERAL_ERROR、CKR_HOST_MEMORY、CKR_OK に加え、C_OpenSession() は次の戻り値を使用します。

次の戻り値は、プラグインされたハードウェアトークンに関するものです。

PKCS #11 関数: C_GetMechanismList()

C_GetMechanismList() は、指定されたトークンがサポートする機構タイプのリストを取得します。C_GetMechanismList() の構文は次のとおりです。

C_GetMechanismList(CK_SLOT_ID slotID, CK_MECHANISM_TYPE_PTR pMechanismList, 
CK_ULONG_PTR pulCount);

slotID は、目的のトークンに対するスロットの ID です。pulCount は機構数を格納する場所へのポインタです。pMechanismList に NULL_PTR を設定した場合、*pulCount に機構数が返されます。それ以外の場合、*pulCount にはリストのサイズを、pMechanismList にはリストを格納するバッファーへのポインタを、それぞれ設定する必要があります。

PKCS #11 ソフトトークンがプラグインされている場合、C_GetMechanismList() から返されるサポート機構リストは、次のとおりです。

CKR_FUNCTION_FAILED、CKR_GENERAL_ERROR、CKR_HOST_MEMORY、CKR_OK に加え、C_GetSlotlist() は次の戻り値を使用します。

次の戻り値は、プラグインされたハードウェアトークンに関するものです。