cryptoki ライブラリの概要

Oracle Solaris 暗号化フレームワーク内のユーザーレベルアプリケーションは、libpkcs#11.so モジュールで提供される cryptoki ライブラリ経由で PKCS #11 関数にアクセスします。pkcs11_softtoken.so モジュールは Oracle Corporation が提供する PKCS #11 ソフトトークン 実装であり、暗号化メカニズムを提供します。このソフトトークンプラグインがメカニズムのデフォルトソースになります。暗号化メカニズムの提供は、サードパーティー製のプラグインを通じて行うことも可能です。

ここでは、このソフトトークンによってサポートされている PKCS #11 関数と戻り値のリストを示します。戻りコードは、フレームワークにプラグインされるプロバイダごとに異なります。また、いくつかの一般的な関数についても説明します。cryptoki ライブラリに含まれるすべての要素の完全な説明が必要な場合は、libpkcs11(3LIB) のマニュアルページを参照するか、RSA Laboratories Web サイトの「PKCS #11: Cryptographic Token Interface Standard」を参照してください。

PKCS #11 関数リスト

次のリストは、Solaris 暗号化フレームワーク内の pkcs11_softtoken.so がサポートする PKCS #11 関数をカテゴリ別に示したものです。

• 一般用途 – C_Initialize()、C_Finalize()、C_GetInfo()、C_GetFunctionList()

• セッション管理 – C_OpenSession()、C_CloseSession()、C_GetSessionInfo()、C_CloseAllSessions()、 C_Login()、C_Logout()

• スロット管理およびトークン管理 – C_GetSlotList()、C_GetSlotInfo()、C_GetMechanismList()、C_GetMechanismInfo()、 C_SetPIN()

• 暗号化と復号化 – C_EncryptInit()、C_Encrypt()、C_EncryptUpdate()、C_EncryptFinal()、C_DecryptInit()、 C_Decrypt()、 C_DecryptUpdate()、C_DecryptFinal()

• メッセージダイジェスト – C_DigestInit()、C_Digest()、C_DigestKey()、C_DigestUpdate()、C_DigestFinal()

• 署名と MAC 適用 – C_Sign()、C_SignInit()、C_SignUpdate()、C_SignFinal()、C_SignRecoverInit()、 C_SignRecover()

• 署名検証 – C_Verify()、C_VerifyInit()、C_VerifyUpdate()、C_VerifyFinal()、C_VerifyRecoverInit()、 C_VerifyRecover()

• 二重目的の暗号化関数 – C_DigestEncryptUpdate()、C_DecryptDigestUpdate()、C_SignEncryptUpdate()、 C_DecryptVerifyUpdate()

• 乱数生成 – C_SeedRandom()、C_GenerateRandom()

• オブジェクト管理 – C_CreateObject()、C_DestroyObject()、C_CopyObject()、C_FindObjects()、 C_FindObjectsInit()、C_FindObjectsFinal()、 C_GetAttributeValue()、C_SetAttributeValue()

• 鍵管理 – C_GenerateKey()、C_GenerateKeyPair()、C_DeriveKey()

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

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

• 「PKCS #11 関数: C_Initialize()」

• 「PKCS #11 関数: C_GetInfo()」

• 「PKCS #11 関数: C_GetSlotList()」

• 「PKCS #11 関数: C_GetTokenInfo()」

• 「PKCS #11 関数: C_OpenSession()」

• 「PKCS #11 関数: C_GetMechanismList()」

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 ライブラリを使用し終わったことを通知します。

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

• CKR_ARGUMENTS_BAD

• CKR_CANT_LOCK

• CKR_CRYPTOKI_ALREADY_INITIALIZED – このエラーは致命的ではありません。

PKCS #11 関数: C_GetInfo()

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

C_GetInfo(CK_INFO_PTR pInfo);

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

• cryptokiVersion = 2, 11

• manufacturerID = Sun Microsystems, Inc.

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

• CKR_ARGUMENTS_BAD

• CKR_CRYPTOKI_NOT_INITIALIZED

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() 呼び出しでは、スロットを取得します。

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

• CKR_ARGUMENTS_BAD

• CKR_BUFFER_TOO_SMALL

• CKR_CRYPTOKI_NOT_INITIALIZED

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() は次のフィールドと値を返します。

• ラベル – Sun Software PKCS#11 softtoken。

• フラグ – CKF_DUAL_CRYPTO_OPERATIONS、CKF_TOKEN_INITIALIZED、CKF_RNG、 CKF_USER_PIN_INITIALIZED、および CKF_LOGIN_REQUIRED。これらのフラグには 1 が設定されます。

• ulMaxSessionCount – CK_EFFECTIVELY_INFINITE が設定されます。

• ulMaxRwSessionCount – CK_EFFECTIVELY_INFINITE が設定されます。

• ulMaxPinLen – 256 が設定されます。

• ulMinPinLen – 1 が設定されます。

• ulTotalPublicMemory には CK_UNAVAILABLE_INFORMATION が設定されます。

• ulFreePublicMemory には CK_UNAVAILABLE_INFORMATION が設定されます。

• ulTotalPrivateMemory には CK_UNAVAILABLE_INFORMATION が設定されます。

• ulFreePrivateMemory には CK_UNAVAILABLE_INFORMATION が設定されます。

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

• CKR_ARGUMENTS_BAD

• CKR_BUFFER_TOO_SMALL

• CKR_CRYPTOKI_NOT_INITIALIZED

• CKR_SLOT_ID_INVALID

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

• CKR_DEVICE_ERROR

• CKR_DEVICE_MEMORY

• CKR_DEVICE_REMOVED

• CKR_TOKEN_NOT_PRESENT

• CKR_TOKEN_NOT_RECOGNIZED

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() は次の戻り値を使用します。

• CKR_ARGUMENTS_BAD

• CKR_CRYPTOKI_NOT_INITIALIZED

• CKR_SLOT_ID_INVALID

• CKR_TOKEN_WRITE_PROTECTED – 読み取り専用のトークンで戻されます。

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

• CKR_DEVICE_ERROR

• CKR_DEVICE_MEMORY

• CKR_DEVICE_REMOVED

• CKR_SESSION_COUNT

• CKR_SESSION_PARALLEL_NOT_SUPPORTED

• CKR_SESSION_READ_WRITE_SO_EXISTS

• CKR_TOKEN_NOT_PRESENT

• CKR_TOKEN_NOT_RECOGNIZED

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() から返されるサポートメカニズムリストは、次のとおりです。

• CKM_AES_CBC

• CKM_AES_CBC_PAD

• CKM_AES_ECB

• CKM_AES_KEY_GEN

• CKM_DES_CBC

• CKM_DES_CBC_PAD

• CKM_DES_ECB

• CKM_DES_KEY_GEN

• CKM_DES_MAC

• CKM_DES_MAC_GENERAL

• CKM_DES3_CBC

• CKM_DES3_CBC_PAD

• CKM_DES3_ECB

• CKM_DES3_KEY_GEN

• CKM_DH_PKCS_DERIVE

• CKM_DH_PKCS_KEY_PAIR_GEN

• CKM_DSA

• CKM_DSA_KEY_PAIR_GEN

• CKM_DSA_SHA_1

• CKM_MD5

• CKM_MD5_KEY_DERIVATION

• CKM_MD5_RSA_PKCS

• CKM_MD5_HMAC

• CKM_MD5_HMAC_GENERAL

• CKM_PBE_SHA1_RC4_128

• CKM_PKCS5_PBKD2

• CKM_RC4

• CKM_RC4_KEY_GEN

• CKM_RSA_PKCS

• CKM_RSA_X_509

• CKM_RSA_PKCS_KEY_PAIR_GEN

• CKM_SHA_1

• CKM_SHA_1_HMAC_GENERAL

• CKM_SHA_1_HMAC

• CKM_SHA_1_KEY_DERIVATION

• CKM_SHA_1_RSA_PKCS

• CKM_SSL3_KEY_AND_MAC_DERIVE

• CKM_SSL3_MASTER_KEY_DERIVE

• CKM_SSL3_MASTER_KEY_DERIVE_DH

• CKM_SSL3_MD5_MAC

• CKM_SSL3_PRE_MASTER_KEY_GEN

• CKM_SSL3_SHA1_MAC

• CKM_TLS_KEY_AND_MAC_DERIVE

• CKM_TLS_MASTER_KEY_DERIVE

• CKM_TLS_MASTER_KEY_DERIVE_DH

• CKM_TLS_PRE_MASTER_KEY_GEN

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

• CKR_ARGUMENTS_BAD

• CKR_BUFFER_TOO_SMALL

• CKR_CRYPTOKI_NOT_INITIALIZED

• CKR_SLOT_ID_INVALID

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

• CKR_DEVICE_ERROR

• CKR_DEVICE_MEMORY

• CKR_DEVICE_REMOVED

• CKR_TOKEN_NOT_PRESENT

• CKR_TOKEN_NOT_RECOGNIZED

拡張 PKCS #11 関数

Oracle Solaris 暗号化フレームワークでは、標準の PKCS #11 関数のほかに、次の 2 つの簡易関数が提供されています。

• 「拡張 PKCS #11 関数: SUNW_C_GetMechSession()」

• 「拡張 PKCS #11 関数: SUNW_C_KeyToObject」

拡張 PKCS #11 関数: SUNW_C_GetMechSession()

SUNW_C_GetMechSession() は、簡易関数です。この関数はまず、Solaris 暗号化フレームワークを初期化します。続いてこの関数は、指定されたメカニズムとの間でセッションを開始します。SUNW_C_GetMechSession() の構文は次のとおりです。

SUNW_C_GetMechSession(CK_MECHANISM_TYPE mech, C\
K_SESSION_HANDLE_PTR hSession)

mech パラメータでは、使用するメカニズムを指定します。hSession は、セッションの格納場所へのポインタです。

SUNW_C_GetMechSession() は内部的に、C_Initialize() を呼び出して cryptoki ライブラリを初期化します。続いて SUNW_C_GetMechSession() は、C_GetSlotList() と C_GetMechanismInfo() を使って利用可能なスロットを検索し、指定されたメカニズムを備えたトークンを見つけ出します。目的のメカニズムが見つかった場合、SUNW_C_GetMechSession() は C_OpenSession() を呼び出してセッションをオープンします。

SUNW_C_GetMechSession() は何度も呼び出す必要はありません。しかし、仮に SUNW_C_GetMechSession() を複数回呼び出したとしても、特に問題は生じません。

拡張 PKCS #11 関数: SUNW_C_KeyToObject

SUNW_C_KeyToObject() は、秘密鍵オブジェクトを作成します。呼び出し元のプログラムは、使用すべきメカニズムと未処理の鍵データを指定する必要があります。SUNW_C_KeyToObject() は内部的に、指定されたメカニズムに対する鍵の種類を決定します。C_CreateObject() によって汎用的な鍵オブジェクトが作成されます。続いて SUNW_C_KeyToObject() は、 C_GetSessionInfo() と C_GetMechanismInfo() を呼び出してスロットとメカニズムの情報を取得します。そして、C_SetAttributeValue() によって、鍵オブジェクトの属性フラグがメカニズムの種類に従って設定されます。