cryptoki ライブラリの概要
Solaris 暗号化フレームワーク内のユーザーレベルアプリケーションは、libpkcs11.so モジュールで提供される cryptoki ライブラリ経由で PKCS #11 関数にアクセスします。pkcs11_softtoken.so モジュールは Sun Microsystems, Inc. が提供する PKCS #11 ソフトトークン実装であり、さまざまな暗号化機構を提供します。このソフトトークンプラグインが機構のデフォルトソースになります。暗号化機構の提供は、Sun 以外のプラグインを通じて行うことも可能です。
ここでは、このソフトトークンによってサポートされている 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 を使用するための関数のうち、次のものについて説明します。
注 –
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() は次の戻り値を使用します。
-
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() 呼び出しでは、スロットを取得します。
注 –
スロットの順序は保証されません。スロットの順序は、PKCS #11 ライブラリを読み込むたびに変わる可能性があります。
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 関数
Solaris 暗号化フレームワークでは、標準の PKCS #11 関数のほかに、次の 2 つの簡易関数が提供されています。
拡張 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() によって、鍵オブジェクトの属性フラグが機構の種類に従って設定されます。
- © 2010, Oracle Corporation and/or its affiliates