Oracle Solaris 暗号化フレームワークのユーザーレベルのアプリケーションは、libpkcs11.so モジュールで提供されている cryptoki ライブラリ経由で、PKCS #11 関数にアクセスします。pkcs11_softtoken.so モジュールは Oracle Corporation が提供する PKCS #11 ソフトトークン実装であり、暗号化メカニズムを提供します。このソフトトークンプラグインがメカニズムのデフォルトソースになります。暗号化メカニズムの提供は、サードパーティー製のプラグインを通じて行うことも可能です。
このセクションでは、このソフトトークンによってサポートされている PKCS #11 関数と戻り値のリストを示します。戻りコードは、フレームワークにプラグインされるプロバイダごとに異なります。また、このセクションではいくつかの一般的な関数についても説明します。cryptoki ライブラリのすべての要素の完全な説明については、libpkcs11(3LIB) を参照してください。
すべてのプロバイダに直接バインディングが使用されていることを確認します。詳細は、ld(1) およびOracle Solaris 11.3 リンカーとライブラリガイドを参照してください。
次のリストは、Oracle 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 を使用するための関数のうち、次のものについて説明します。
C_Initialize() は PKCS #11 ライブラリを初期化します。C_Initialize() の構文は次のとおりです。
C_Initialize(CK_VOID_PTR pInitArgs);
pInitArgs は、空値 NULL_PTR または CK_C_INITIALIZE_ARGS 構造体へのポインタです。NULL_PTR が指定された場合、ライブラリは Oracle Solaris の相互排他ロックをロックプリミティブとして使用することで、複数スレッドによる内部共有構造体へのアクセスを制御します。Oracle 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 (重大ではない)
C_GetInfo() は、cryptoki ライブラリに関する開発元情報とバージョン情報を取得します。C_GetInfo() の構文は次のとおりです。
C_GetInfo(CK_INFO_PTR pInfo);
C_GetInfo() は次の値を返します。
cryptokiVersion = 2, 11
manufacturerID = Oracle Corporation.
CKR_FUNCTION_FAILED、CKR_GENERAL_ERROR、CKR_HOST_MEMORY、CKR_OK に加え、C_GetInfo() は次の戻り値を使用します。
CKR_ARGUMENTS_BAD
CKR_CRYPTOKI_NOT_INITIALIZED
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
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
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
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
Oracle Solaris 暗号化フレームワークでは、標準の PKCS #11 関数のほかに、次の 2 つの簡易関数が提供されています。
SUNW_C_GetMechSession() は、簡易関数です。この関数はまず、Oracle 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() を複数回呼び出したとしても、特に問題は生じません。
SUNW_C_KeyToObject() は、秘密鍵オブジェクトを作成します。呼び出し元のプログラムは、使用すべきメカニズムと未処理の鍵データを指定する必要があります。SUNW_C_KeyToObject() は内部的に、指定されたメカニズムに対する鍵の種類を決定します。C_CreateObject() によって汎用的な鍵オブジェクトが作成されます。続いて SUNW_C_KeyToObject() は、 C_GetSessionInfo() と C_GetMechanismInfo() を呼び出してスロットとメカニズムの情報を取得します。そして、C_SetAttributeValue() によって、鍵オブジェクトの属性フラグがメカニズムの種類に従って設定されます。