Comments
Description
Transcript
Crypto-API 仕様書 - IPA 独立行政法人 情報処理推進機構
13 情経第 770 号 電子政府情報セキュリティ基盤技術開発事業 Crypto-API の開発 Crypto-API 仕様書 平成 14 年 2 月 情報処理振興事業協会 セキュリティセンター 目次 1. 概要 ......................................................................................................................................................1 1.1. 1.2. 1.3. 1.4. 2. 背景.............................................................................. 目的.............................................................................. 仕様概要 .......................................................................... 環境条件 .......................................................................... 1 1 3 7 APP 側 API 仕様 ..................................................................................................................................8 2.1. 鍵対生成機能 ...................................................................... 8 2.1.1. 2.2. 鍵対生成手順 .......................................................................................................................9 署名生成機能 ..................................................................... 10 2.2.1. 署名生成オブジェクト .......................................................................................................10 2.2.2. 署名生成手順 ..................................................................................................................... 11 2.3. 署名検証機能 ..................................................................... 20 2.3.1. 署名検証オブジェクト .......................................................................................................20 2.3.2. 署名検証手順 .....................................................................................................................21 2.4. 親展機能 ......................................................................... 31 2.4.1. 親展オブジェクト ..............................................................................................................31 2.4.2. 親展手順 ............................................................................................................................32 2.5. 親展解除機能 ..................................................................... 44 2.5.1. 親展解除オブジェクト .......................................................................................................44 2.5.2. 親展解除手順 .....................................................................................................................45 2.6. 鍵管理機能 ....................................................................... 56 2.6.1. 利用者認証情報を用いた鍵管理媒体へのログイン認証手順 ..............................................57 2.6.2. 公開鍵暗号アルゴリズムの秘密鍵を管理(保管)する手順 ..............................................58 2.6.3. 公開鍵暗号アルゴリズムの秘密鍵を管理(取得)する手順 ..............................................58 2.6.4. 公開鍵暗号アルゴリズムの秘密鍵を管理(削除)する手順 ..............................................59 2.6.5. 鍵管理媒体上の秘密鍵を用いて署名を生成する手順.........................................................59 2.6.6. 鍵管理媒体上の秘密鍵を用いて親展解除を行う手順.........................................................59 2.6.7. 鍵管理媒体として HD を使用する場合の注意 ...................................................................59 2.6.8. 鍵管理媒体の後処理手順 ...................................................................................................59 2.7. 証明書管理機能 ................................................................... 60 2.7.1. 証明書管理 .........................................................................................................................60 2.7.2. 利用者認証情報を用いた証明書管理媒体へのログイン認証手順.......................................61 2.7.3. 証明書の管理(保管)手順 ................................................................................................62 2.7.4. 証明書の管理(取得)手順 ................................................................................................62 2.7.5. 証明書の管理(削除)手順 ................................................................................................63 2.7.6. 証明書管理媒体として HD を使用する場合の注意............................................................63 2.7.7. 証明書管理媒体の後処理手順 ............................................................................................63 2.7.8. 証明書申請・取得 ................................................................................................................64 2.7.9. 証明書項目取得..................................................................................................................81 i 2.7.10. 2.8. 証明書項目取得手順...........................................................................................................81 証明書検証機能 ................................................................... 89 2.8.1. 証明書検証オブジェクト ...................................................................................................89 2.8.2. 証明書検証手順..................................................................................................................90 2.9. 失効情報管理機能 ................................................................ 100 2.9.1. 失効情報管理オブジェクト ..............................................................................................100 2.9.2. 失効情報の保管手順.........................................................................................................101 2.9.3. 失効情報の取得手順.........................................................................................................101 2.9.4. 失効情報の削除手順.........................................................................................................102 2.9.5. 2.10. 失効情報の項目取得......................................................................................................... 110 SP 管理機能 ................................................................... 116 2.10.1. CSP の登録機能............................................................................................................... 116 2.10.2. CSP の削除機能............................................................................................................... 116 2.10.3. CSP の使用機能............................................................................................................... 116 2.11. 鍵オブジェクト................................................................ 117 2.11.1. 鍵オブジェクト................................................................................................................ 117 2.11.2. 署名や親展解除で使用する為の秘密鍵の鍵オブジェクト生成と設定.............................. 118 2.11.3. 署名検証や親展で使用する為の公開鍵の鍵オブジェクトの生成と設定 .......................... 118 2.11.4. メモリ上の秘密鍵、公開鍵の鍵オブジェクト生成と設定 ............................................... 118 2.12. 名前オブジェクト.............................................................. 122 3. APP 側 API で使用する型定義.........................................................................................................129 4. Crypto-API で使用する PKCS #11 のインタフェース.....................................................................152 5. SP 側 API 仕様 .................................................................................................................................191 5.1. 5.2. 鍵対生成 SP 機能 ................................................................. 191 署名生成 SP 機能 ................................................................. 192 5.2.1. 5.3. 署名検証 SP 機能 ................................................................. 200 5.3.1. 5.4. 親展解除 SP オブジェクト...............................................................................................220 鍵管理 SP 機能 ................................................................... 230 証明書管理 SP 機能 ............................................................... 231 証明書検証 SP 機能 ............................................................... 232 5.8.1. 5.9. 親展 SP オブジェクト......................................................................................................209 親展解除 SP 機能 ................................................................. 220 5.5.1. 5.6. 5.7. 5.8. 署名検証 SP オブジェクト...............................................................................................200 親展 SP 機能 ..................................................................... 209 5.4.1. 5.5. 署名生成 SP オブジェクト...............................................................................................192 証明書検証 SP オブジェクト ...........................................................................................232 失効情報管理 SP 機能 ............................................................. 241 5.9.1. 失効情報管理 SP オブジェクト .......................................................................................241 6. SP 側で使用する型定義....................................................................................................................248 7. 付録 ..................................................................................................................................................252 7.1. 7.2. Crypto−API 仕様設計の論点について............................................... 252 証明書検証 SP 機能における前提条件 ............................................... 254 ii 7.2.1. 証明書のパス構築における前提条件................................................................................254 7.2.2. 検証における前提条件 .....................................................................................................254 7.2.3. その他、環境などにおける前提条件................................................................................254 7.3. 7.4. 7.4.1. 共通鍵生成 SP 機能 .........................................................................................................257 7.4.2. 共通鍵暗号化 SP 機能......................................................................................................262 7.4.3. 共有鍵復号 SP 機能 .........................................................................................................271 7.5. 8. 定数値一覧 ...................................................................... 255 基本暗号 SP 機能 API 仕様 ......................................................... 257 基本暗号 SP 機能構造体 ........................................................... 280 7.5.1. 共通鍵生成 SP 機能 .........................................................................................................280 7.5.2. 共通鍵暗号化 SP 機能......................................................................................................283 7.5.3. 共通鍵復号 SP 機能 .........................................................................................................286 参考文献 ...........................................................................................................................................287 iii 1. 概要 本仕様書は、 「電子政府情報セキュリティ基盤技術開発事業」の一つである「Crypto-API の開発」 の成果であり、電子政府 PKI アプリケーション構築の為の PKI ライブラリの API(Crypto-API) の仕様について記述したものである。 1.1. 背景 政府は、2003 年度までに行政の効率化や国民負担の軽減を目標に行政手続きを電子化する電 子政府の基盤を構築することを目指している。 電子政府の構築は、デジタル経済・社会の一つのモデルであり、その中で実施される情報セキ ュリティ確保のための対策もまた、広く民間の範となるものとなり、それによって、我が国のネ ットワーク全体の安全性・信頼性を高め、更に、具体的に進みつつある同様な取り組みと連携し ていくことにより国際的な貢献につながることも期待される。このため、電子政府の構築に向け て、情報セキュリティ政策を重要なものとして位置づけ、積極的な貢献を行っていく必要がある。 電子政府や電子調達などの電子政府システムの多くは、PKI(公開鍵基盤)に基づいて構築 されようとしており、それらを支える電子政府認証基盤として、電子政府関連認証局の整備とと もに、電子政府システム構築のための利用者側認証システムの整備、特に利用者側認証システム の中核となる PKI ライブラリの整備が急務である。 1.2. 目的 本仕様書は、電子政府システムの開発・保守に適切な PKI ライブラリの標準仕様確立と、その 仕様を満たす PKI ライブラリ製品の早期実現促進に貢献し、電子政府システムの健全かつ円滑な 発展に役立てるためのものである。 電子政府対応の利用者側認証システムの中核となる PKI ライブラリとして、次の項目を満足する PKI ライブラリの機能及び標準 API 仕様を含む。 (1)標準 API(Application Programming Interface)仕様 マルチベンダーによる電子政府システム構築や、将来に亙る電子政府システムの保守及びリス ク管理のために、PKI ライブラリの API 仕様を標準化することによって、電子政府システムの PKI アプリケーション・プログラムを極力変更することなく PKI ライブラリを切り替え可能とする。 (2)相互運用性、保守性及びリスク管理のための汎用的機構及び機能 電子政府システムの相互運用性、保守性及びリスク管理を強化するために、次の要件を満たす PKI ライブラリの汎用的機構及び機能を確立する。 (a)暗号アルゴリズム独立機構 暗号アルゴリズム/暗号ライブラリを切替え可能とする機構である。 複数の暗号アルゴリズム(共通鍵暗号アルゴリズム、署名アルゴリズム(対応する公開鍵暗号ア 1 ルゴリズムを含む) )を使用可能とするとともに、電子政府システムの PKI アプリケーション・ プログラムを極力変更することなく、今後の暗号技術の発展に伴ったより良い暗号に容易に切り 替えられる仕組みを実現する。 (b)鍵・証明書の管理媒体独立機構 鍵・証明書の管理媒体として、現在、固定ディスク、IC カード、耐タンパー性を有する秘密 鍵管理装置(HSM)などが存在する。電子政府システムの PKI アプリケーション・プログラムを極 力変更することなく、認証ポリシーに応じて鍵・証明書の管理媒体(固定ディスク、IC カード 又は HSM)を容易に切り替えられる仕組みを実現する。 (c)汎用的な証明書検証機能と証明書検証仕様独立機構 電子政府システムでは、電子政府関連の複数の認証局(CA)に亙った、ブリッジ CA を介した相 互認証を軸とする汎用的な証明書検証機能が必要である。また、証明書検証仕様は個々の電子政 府アプリケーションに依存する性質を持つが、電子政府システムの PKI アプリケーション・プロ グラムを極力変更することなく、認証ポリシーに従った証明書検証仕様を実現する証明書検証機 能に容易に切り替えられる仕組みを実現する。 2 1.3. 仕様概要 本仕様は、電子政府 PKI アプリケーション構築の為の、PKI ライブラリ(Crypto-API)の API 仕 様である。 Crypto-API 仕様は、図 1.3-1に示すように、APP 側 API 仕様と、SP 側 API 仕様から構成され る。 電子政府PKIアプリケーション(官側、民側(法人代表者、個人等)) 公開 APP側API PKIライブラリ 公開 ■CSP切替可能 ■暗号アルゴリズム独立、 鍵・証明書管理媒体独立、 証明書検証仕様独立を実現 鍵対生成機能 鍵管理機能 署名生成機能 証明書管理機能 署名検証機能 証明書検証機能 親展機能 失効情報管理機能 親展解除機能 SP管理機能(CSP取得/ 解放) SP側API 鍵対生成CSP 鍵管理CSP 署名生成CSP 証明書管理CSP 署名検証CSP 証明書検証CSP 親展CSP 失効情報管理CSP (論理的単位であり、物理的単位は任意) 親展解除CSP CSP : Cryptographic Service Provider 秘密鍵保管媒体(HD, ICカード, HSM) 図 1.3-1Crypto-API 開発対象の全体像 3 (1)PKI ライブラリ機能 PKI ライブラリの機能概要について説明する。 ① 鍵対生成機能 公開鍵暗号の鍵生成アルゴリズムを用いて、公開鍵対(公開鍵と秘密鍵)を生成す る機能。 ② 署名生成機能 署名アルゴリズムを用いて、平文と公開鍵暗号アルゴリズムの秘密鍵から、署名を 生成する機能。署名に使用する秘密鍵は、計算機上の主記憶上の秘密鍵、または鍵 管理媒体上の秘密鍵を指定する。 ③ 署名検証機能 署名アルゴリズムを用いて、平文と公開鍵暗号アルゴリズムの公開鍵と署名から、 署名の正当性を検証する機能。 ④ 親展機能 公開鍵暗号アルゴリズム(RSA)と共通鍵暗号アルゴリズムを組み合わせて、平文を 暗号化する機能。 ⑤ 親展解除機能 公開鍵暗号アルゴリズム(RSA)と共通鍵暗号アルゴリズムを組み合わせて、暗号文 を復号する機能。秘密鍵は、計算機上の主記憶上の秘密鍵、または鍵管理媒体上の 秘密鍵を指定する。 ⑥ 鍵管理機能 鍵管理媒体(固定ディスク、IC カード又は HSM)を用いて、秘密鍵を管理(保管・ 取得・削除)する機能。 ⑦ 証明書管理機能 証明書管理媒体(固定ディスク、IC カード又は HSM)を用いて、証明書を管理(保 管・取得・削除)する機能。証明書内部の項目を取得する機能。自分の証明書を申 請・取得する機能を含む。 ⑧ 証明書検証機能 利用したい証明書の正当性を確認する機能。 ⑨ 失効情報管理機能 失効情報管理媒体(固定ディスク)を用いて、失効情報(CRL 及び ARL)を管理(保 管・取得・削除)する機能。失効情報内部の項目を取得する機能を含む。 ⑩ SP 管理機能 Cryptographic Service Provider のインスタンスを示す SP コンテキストを管理(取 得・解放)する機能。 4 ※共通鍵暗号アルゴリズムは「任意のブロック暗号アルゴリズム」を指す。 ※署名アルゴリズム及びそれに対応する公開鍵暗号アルゴリズムは、総務省・法務 省・経済産業省 告示第二号「電子署名及び認証業務に関する法律に基づく特定認 証業務の認定に係る指針」で指定された電子署名方式の中の、 「sha1WithRSAEncryption を含む2個以上の、署名アルゴリズム及びそれに対応 する公開鍵暗号アルゴリズム」を示す。ただし、親展機能及び親展解除機能の為 の鍵配送に用いる公開鍵暗号アルゴリズムについては、RSA に限定する。 (2)具備する機構 SP 管理機能を用いた独立機構について説明する。 ① 暗号アルゴリズム独立機構 暗号アルゴリズムを切替え可能とする機構。複数の暗号アルゴリズム(共通鍵暗号 アルゴリズム・署名アルゴリズム(対応する公開鍵暗号アルゴリズムを含む) )が使 用可能である。また、既存の電子政府システムの PKI アプリケーション・プログラ ムを変更する事なく、新たな暗号を容易に切り替えられる。 ② 鍵・証明書の管理媒体独立機構 鍵・証明書の管理媒体として、固定ディスク、IC カード、耐タンパー性を有する秘 密鍵管理装置(HSM)などが存在する。既存の電子政府システムの PKI アプリケーショ ン・プログラムを変更する事なく、認証ポリシーに応じて鍵・証明書の管理媒体(固 定ディスク、IC カード又は HSM)を容易に切り替えられる。 ③ 汎用的な証明書検証機能と証明書検証仕様独立機構 電子政府システムでは、電子政府関連の複数の認証局(CA)に亙った、ブリッジ CA を 介した相互認証を軸とする汎用的な証明書検証機能が必要である。 また、証明書検証仕様は個々の電子政府アプリケーションに依存する性質を持つが、 既存の電子政府システムの PKI アプリケーション・プログラムを極力変更する事な く、認証ポリシーに従った証明書検証仕様を実現する証明書検証機能に容易に切り 替えられる。 5 これらの独立機構は基本的アーキテクチャとして APP−SP 構造を取り入れた事により、 PKI アプリケーション・プログラムから複数のライブラリを柔軟に選択する事が可能と なった。また APP−SP 構造における API は、アプリケーション・プログラムが呼び出す APP(Application Program)側 API と、SP(Service Provider)群が提供する SP 側 API から成る。Crypto-API では、PKI アプリケーション・プログラムから APP 側 API を介し て適切なライブラリ CSP を呼び出し、ライブラリ CSP 群が提供する様々な機能を選択的 に利用する事が可能である。 ※Crypto-API では、SP を CSP(Cryptographic Service Provider)とも呼称する。 暗号アルゴリズム独立、鍵・証明書の管理媒体独立及び証明書検証仕様独立と各ライブ ラリ機能との関係を、図 1.3-2に示す。 鍵対生成機能 暗号アルゴリズム独立 署名生成機能 共通鍵暗号アルゴリズム 署名検証機能 署名アルゴリズム (任意のブロック暗号) (sha1WithRSAEncryptionを含む 2個以上の、政府告示の署名アル ゴリズム。 署名アルゴリズムに対応する 公開鍵暗号アルゴリズムを含む。) 親展機能 親展解除機能 鍵管理機能 鍵・証明書管理媒体独立 証明書管理機能 (固定ディスク、ICカード、HSM) 証明書検証機能 失効情報管理機能 証明書検証仕様独立 SP管理機能 (認証ポリシーに応じた 証明書検証仕様) [注1]当該親展機能及び親展解除機能に使用可能な公開鍵暗号アルゴリズムは、RSAに限定している。 他の各公開鍵暗号アルゴリズムに対応した親展機能及び親展解除機能が必要な場合は、各アルゴリズム 対応の同等機能を別途追加する必要がある。(ただし、署名用途専用のアルゴリズムはこの限りではない。) [注2] は直接的に有効となる関係、 は間接的に有効となる関係を示す。 図 1.3-2各ライブラリ機能と各独立機構との関係 6 1.4. 環境条件 (1)開発成果等の動作環境 開発成果である PKI ライブラリ(Crypto-API)の API 仕様については、プラットフォー ム(機種・OS)を特定しない。ただし、この API 仕様を用いて開発する PKI アプリケー ション・プログラムは、C言語で記述する事を想定している。 7 2. APP 側 API 仕様 2.1. 鍵対生成機能 鍵対生成機能は公開鍵暗号の鍵生成アルゴリズムを用いて、公開鍵対(公開鍵:Public-Key、秘 密鍵:Private-Key)を生成する機能。公開鍵対は公開鍵暗号アルゴリズムに規定されたフォー マットに従って生成する。 <公開鍵暗号アルゴリズム> RSA を含む2個以上の、政府告示の署名アルゴリズムに 対応する公開鍵暗号アルゴリズム。 本機能で生成した鍵対は証明書管理機能を用いて、証明書の取得を作成する為に使用する。 鍵対生成機能を実現する為の API 仕様として業界標準として普及している PKCS#11(Version2.01 以降)を採用する。 8 2.1.1. 鍵対生成手順 鍵対生成手順例を記載する。なお、Crypto-API で使用する PKCS#11 関数に関しては「4 Crypto-API で使用する PKCS #11 のインタフェース」を、詳細な関数仕様等は参考文献[1]、または使用する 鍵管理/証明書管理媒体の PKCS#11 ライブラリの仕様説明書を参照の事。 1 使用する PKCS#11 ライブラリの関数「C_GetFunctionList」のアドレスを取得 2 PKCS#11 ライブラリの関数リストを取得 C_GetFunctionList 3 PKCS#11 ライブラリの初期化 C_Initialize 4 スロット数の取得 C_GetSlotList 5 スロットリストの取得 C_GetSlotList 6 セッションオープン C_OpenSession 7 ログイン C_Login 8 鍵対の生成 C_GenerateKeyPair 9 「2.6.8鍵管理媒体の後処理手順」の手順で後処理を行う。 9 2.2. 署名生成機能 署名生成機能は、署名アルゴリズムを用いて、平文と公開鍵暗号アルゴリズムの秘密鍵から、署 名を生成する機能である。署名に使用する秘密鍵は、計算機の主記憶上の秘密鍵、または鍵管理 媒体上の秘密鍵を使用する。鍵管理媒体上の秘密鍵を用いる場合は、利用者認証情報(パスワー ド等)を用いた利用者の認証を行い、なりすましによる不正使用を防止する。署名は署名アルゴ リズムに規定されたフォーマットに従って生成する。 <署名アルゴリズム> sha1WithRSAEncryption を含む2個以上の、政府告示の署名アルゴリズム。 署名生成は署名生成オブジェクトの操作によって行う。なお、署名生成に使用する秘密鍵に関し ては、 「2.6 鍵管理機能」 、 「鍵オブジェクト」を参照の事。 2.2.1. 署名生成オブジェクト 関数名 ICASignatureObjectCreate ICASignatureObjectDestroy ICASignatureObjectRegisterCSP ICASignatureObjectSetAlgorithm ICASignatureObjectSetKey ICASignatureObjectSetMessage ICASignatureObjectAddMessage ICASignatureObjectGetSignature 概要 署名生成オブジェクトの生成 署名生成オブジェクトの破棄 署名生成 CSP の登録 署名アルゴリズム設定 秘密鍵の設定 署名対象の平文データの設定 署名対象の平文データの追加設定 署名データの取得 10 2.2.2. 署名生成手順 0 「2.11.2署名や親展解除で使用する為の秘密鍵の鍵オブジェクト生成と設定」の手順 で鍵管理媒体上の秘密鍵の鍵オブジェクトの生成、設定を行う。 または、 「2.11.4. メモリ上の秘密鍵、公開鍵の鍵オブジェクト生成と設定」の手 順で主記憶上の秘密鍵の鍵オブジェクトの生成、設定を行う。 1 署名生成オブジェクトの生成 ICASignatureObjectCreate 2 署名生成 CSP の登録 ICASignatureObjectRegisterCSP 3 署名アルゴリズム設定 ICASignatureObjectSetAlgorithm 4 秘密鍵の設定 ICASignatureObjectSetKey 5 署名対象の平文データの設定 ICASignatureObjectSetMessage 6 署名対象の平文データの追加設定(省略可、分割して平文データを設定する場合に使用 ) ICASignatureObjectAddMessage 7 署名データの取得 ICASignatureObjectGetSignature 8 署名生成オブジェクトの破棄 ICASignatureObjectDestroy 9 鍵オブジェクトの破壊 ICAKeyDestroy 10 鍵管理機能の解放 *0 は署名生成オブジェクトを用いるための準備フェーズ 11 ICASignatureObjectCreate () 署名生成オブジェクトの生成 【機能】 署名生成オブジェクトの生成を行う。 【形式】 ICASignatureObjectHandle ICAErrorCode ) ICASignatureObjectCreate ( *pErr 【引数】 pErr: 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :署名生成オブジェクトハンドル(0 以外) 異常終了 :0 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 12 ICASignatureObjectDestroy () 署名生成オブジェクトの破棄 【機能】 署名生成オブジェクトの破棄を行う。 【形式】 ICAReturnCode ICASignatureObjectDestroy ( ICASignatureObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 署名生成オブジェクトハンドル(IN) 破棄する署名生成オブジェクトハンドルを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 13 ICASignatureObjectRegisterCSP () 署名生成 CSP の登録 【機能】 署名生成 CSP の登録を行う。 【形式】 ICAReturnCode ICASignatureObjectRegisterCSP ( ICASignatureObjectHandle hObj, ICASignatureObjectCSP *pCSP, ICAErrorCode *pErr ) 【引数】 hObj: pCSP: pErr: 署名生成オブジェクトハンドル(IN) 署名生成オブジェクトハンドルを指定する。 署名生成 CSP の関数リスト(IN) 署名生成 CSP の関数リストを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 14 ICASignatureObjectSetAlgorithm () 署名アルゴリズム設定 【機能】 署名生成の設定を行う。 【形式】 ICAReturnCode ICASignatureObjectSetAlgorithm( ICASignatureObjectHandle hObj, ICAAlgorithmId *pAlg, ICAErrorCode *pErr ) 【引数】 hObj: pAlg: pErr: 署名生成オブジェクトハンドル(IN) 署名生成オブジェクトハンドルを指定する。 署名アルゴリズム(IN) 署名アルゴリズムを指定する。詳細は「3 APP 側 API で使用する型定義」 を参照の事。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM 意味 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 15 ICASignatureObjectSetKey () 秘密鍵の設定 【機能】 秘密鍵の設定を行う。 【形式】 ICAReturnCode ICASignatureObjectSetKey ( ICASignatureObjectHandle hObj, ICAKeyObjectHandle hKey, ICAErrorCode *pErr ) 【引数】 hObj: hKey: pErr: 署名生成オブジェクトハンドル(IN) 署名生成オブジェクトを指定する。 署名生成用の秘密鍵の鍵オブジェクト(IN) 署名生成用の秘密鍵の鍵オブジェクトを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 回復不能な致命的エラー発生 ICAE_FATAL_ERROR 16 ICASignatureObjectSetMessage () 署名対象の平文データの設定 【機能】 署名対象の平文データの設定を行う。 【形式】 ICAReturnCode ICASignatureObjectSetMessage ( ICASignatureObjectHandle hObj, ICAMessage *pMsg, ICAErrorCode *pErr ) 【引数】 hObj: pMsg: pErr: 署名生成オブジェクトハンドル(IN) 署名生成オブジェクトを指定する。 署名対象の平文データ(IN) 署名対象の平文を指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 回復不能な致命的エラー発生 平文データ不正 ICAE_FATAL_ERROR ICAE_INVALID_DATA 17 ICASignatureObjectAddMessage () 署名対象の平文データの追加設定 【機能】 署名対象の平文データの追加設定を行う。署名対象の平文データを分割して設定する 場合に使用する。 【形式】 ICAReturnCode ICASignatureObjectAddMessage ( ICASignatureObjectHandle hObj, ICAMessage *pMsg, ICAErrorCode *pErr ) 【引数】 hObj: pMsg: pErr: 署名生成オブジェクトハンドル(IN) 署名生成オブジェクトを指定する。 署名対象の平文データ(IN) 署名対象の平文を指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_DATA 意味 回復不能な致命的エラー発生 平文データ不正 18 ICASignatureObjectGetSignature () 署名データの取得 【機能】 署名データの取得を行う。 【形式】 ICAReturnCode ICASignatureObjectGetSignature ( ICASignatureObjectHandle hObj, ICASignature *pSig, ICAErrorCode *pErr ) 【引数】 hObj: pSig: pErr: 署名生成オブジェクトハンドル(IN) 署名生成オブジェクトを指定する。 署名データの格納領域(OUT) 署名データが格納されている領域を指すポインタが返される。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pSig には署名生成オブジェクトが内部に保持するポインタが返される。その為、この領域 はへの書込みは行わない事。 署名生成オブジェクトを破棄した後、この領域にはアクセス不可能となる。 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM ICAE_INVALID_KEY ICAE_INVALID_KEY_LENGTH ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_INVALID_KEY_OR_DATA ICAE_FAILURE_MALLOC ICAE_DEVICE_FAILURE ICAE_DEVICE_FAILURE_MALLOC ICAE_DEVICE_REMOVED ICAE_SESSION_INVALID_HANDLE ICAE_SESSION_CLOSED ICAE_SESSION_USER_NOT_LOGGED_IN ICAE_FUNCTION_FAILED ICAE_OTHER 意味 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 秘密鍵不正 秘密鍵の長さ不正 平文データ不正 平文データの長さ不正 暗号化失敗 メモリ確保に失敗 暗号トークンのエラー 暗号トークンにおけるメモリ確保の失敗 暗号トークンが除去 セッションハンドル不正 セッションはクローズ状態 暗号トークンに対して未ログイン 回復可能なエラー発生 その他のエラー発生 19 2.3. 署名検証機能 署名検証機能は、署名アルゴリズムを用いて、平文と公開鍵暗号アルゴリズムの公開鍵と署名か ら、署名の正当性を検証する機能である。署名アルゴリズムに規定されたフォーマットに従った 署名の入力機能を含む。 署名検証は署名検証オブジェクトを操作する事により行う。 2.3.1. 署名検証オブジェクト 関数名 ICAVerificationObjectCreate ICAVerificationObjectDestroy ICAVerificationObjectRegisterCSP ICAVerificationObjectSetAlgorithm ICAVerificationObjectSetKey ICAVerificationObjectSetMessage ICAVerificationObjectAddMessage ICAVerificationObjectSetSignature ICAVerificationObjectVerifySignature 概要 署名検証オブジェクトの生成 署名検証オブジェクトの破壊 署名検証 CSP の登録 署名アルゴリズムの設定 署名検証用の公開鍵の設定 署名検証の平文データの設定 署名検証の平文データの追加設定 署名データの設定 署名検証結果の取得 20 2.3.2. 署名検証手順 1 署名検証オブジェクトの生成 ICAVerificationObjectCreate 2 署名検証 CSP の登録 ICAVerificationObjectRegisterCSP 3 署名アルゴリズムの設定 ICAVerificationObjectSetAlgorithm 4 署名検証用の公開鍵の設定 ICAVerificationObjectSetKey 5 署名検証の平文データの設定 ICAVerificationObjectSetMessage 6 署名検証の平文データの追加設定(省略可、分割して平文データを設定する場合に使用 ) ICAVerificationObjectAddMessage 7 署名データの設定 ICAVerificationObjectSetSignature 8 署名検証結果の取得 ICAVerificationObjectVerifySignature 9 署名検証オブジェクトの破壊 ICAVerificationObjectDestroy 21 ICAVerificationObjectCreate () 署名検証オブジェクトの生成 【機能】 署名検証オブジェクトの生成を行う。 【形式】 ICAVerificationObjectHandle ICAErrorCode ) ICAVerificationObjectCreate ( *pErr 【引数】 pErr: 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :署名検証オブジェクトハンドル 異常終了 :0 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 22 ICAVerificationObjectDestroy () 署名検証オブジェクトの破棄 【機能】 署名検証オブジェクトの破棄を行う。 【形式】 ICAReturnCode ICAVerificationObjectDestroy ( ICAVerificationObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 署名検証オブジェクトハンドル(IN) 破棄する署名検証オブジェクトハンドルを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 23 ICAVerificationObjectRegisterCSP () 署名検証 CSP の登録 【機能】 署名検証 CSP の登録を行う。 【形式】 ICAReturnCode ICAVerificationObjectRegisterCSP ( ICAVerificationObjectHandle hObj, ICAVerificationObjectCSP *pCSP, ICAErrorCode *pErr ) 【引数】 hObj: pCSP: pErr: 署名検証オブジェクトハンドル(IN) 署名検証オブジェクトを指定する。 署名検証 CSP の関数リスト(IN) 署名検証 CSP の関数リストを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 24 ICAVerificationObjectSetAlgorithm () 署名アルゴリズム設定 【機能】 署名アルゴリズムの設定を行う。 【形式】 ICAReturnCode ICAVerificationObjectSetAlgorithm( ICAVerificationObjectHandle hObj, ICAAlgorithmId *pAlg, ICAErrorCode *pErr ) 【引数】 hObj: pAlg: pErr: 署名検証オブジェクトハンドル(IN) 署名検証オブジェクトハンドルを指定する。 署名アルゴリズム(IN) 詳細は「3 APP 側 API で使用する型定義」を参照の事。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM ICAE_INVALID_OTHER 意味 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 その他のパラメータ不正 25 ICAVerificationObjectSetKey () 署名検証用の公開鍵の設定 【機能】 署名検証用の公開鍵を設定する。 【形式】 ICAReturnCode ICAVerificationObjectSetKey ( ICAVerificationObjectHandle hObj, ICAKeyObjectHandle hKey, ICAErrorCode *pErr ) 【引数】 hObj: hKey: pErr: 署名検証オブジェクトハンドル(IN) 署名検証オブジェクトハンドルを指定する。 署名検証用の公開鍵の鍵オブジェクト(IN) 署名検証用の公開鍵の鍵オブジェクトを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_KEY_OR_DATA ICAE_INVALID_KEY_LENGTH 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 公開鍵または署名データ不正 公開鍵の長さ不正 26 ICAVerificationObjectSetMessage () 署名検証の平文データの設定 【機能】 署名検証を行う平文データの設定を行う。 【形式】 ICAReturnCode ICAVerificationObjectSetMessage ( ICAVerificationObjectHandle hObj, ICAMessage *pMsg, ICAErrorCode *pErr ) 【引数】 hObj: pMsg: pErr: 署名検証オブジェクトハンドル(IN) 署名検証オブジェクトハンドルを指定する。 署名検証対象の平文データ(IN) 署名検証を行う平文を指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_DATA 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 平文データ不正 27 ICAVerificationObjectAddMessage () 署名検証の平文データの追加設定 【機能】 署名検証を行う平文データの追加設定を行う。署名検証を行う平文データを分割して 設定する場合に使用する。 【形式】 ICAReturnCode ICAVerificationObjectAddMessage( ICAVerificationObjectHandle hObj, ICAMessage *pMsg, ICAErrorCode *pErr ) 【引数】 hObj: pMsg: pErr: 署名検証オブジェクトハンドル(IN) 署名検証オブジェクトハンドルを指定する。 署名検証対象の平文データ(IN) 署名対象の平文を指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_DATA 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 平文データ不正 28 ICAVerificationObjectSetSignature () 署名データの設定 【機能】 署名データの設定を行う。 【形式】 ICAReturnCode ICAVerificationObjectSetSignature( ICAVerificationObjectHandle hObj, ICASignature *pSig, ICAErrorCode *pErr ) 【引数】 hObj: pSig: pErr: 署名検証オブジェクトハンドル(IN) 署名検証オブジェクトハンドルを指定する。 署名データの格納領域(IN) 署名データの格納領域を指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER 意味 オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 29 ICAVerificationObjectVerifySignature () 署名検証結果の取得 【機能】 署名検証結果を取得する。 【形式】 ICAReturnCode ICAVerificationObjectVerifySignature( ICAVerificationObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 署名検証オブジェクトハンドル(IN) 署名検証オブジェクトハンドルを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 署名検証に成功した場合は戻り値に「ICAR_SUCCESS」 、それ以外は「ICAR_FAILURE」が返る。 署名対象の平文が改ざんされていた場合、エラーコードに「ICAE_INVALID_SIGNATURE」が返る。 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_INVALID_SIGNATURE ICAE_INVALID_SIGNATURE_LENGTH ICAE_INVALID_KEY_OR_DATA 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 アルゴリズム不正 復号文データ不正 復号文データの長さ不正 署名データ不正 署名データの長さ不正 復号失敗 30 2.4. 親展機能 親展機能は、アルゴリズム(共通鍵生成アルゴリズム、鍵配送アルゴリズム、共通鍵暗号アルゴ リズム)及び公開鍵暗号アルゴリズム(RSA)の公開鍵を組み合わせて、平文から親展文(暗号 文)を生成する機能である。共通鍵生成アルゴリズムに従って共通鍵(セッション鍵)を生成す る機能、鍵配送アルゴリズムに従って公開鍵でセッション鍵を暗号化する機能、共通鍵暗号アル ゴリズムに従ってセッション鍵で平文を暗号化する機能を含む。また、暗号文と暗号化されたセ ッション鍵を、親展文をフォーマットするのに必要な形式で出力する機能を含む。 <暗号アルゴリズム> セッション鍵の暗号アルゴリズム(共通鍵暗号アルゴリズム)は、任意の共通鍵ブロック暗号 アルゴリズム。公開鍵暗号アルゴリズムは、RSA。 親展は親展オブジェクトを操作する事により行う。 2.4.1. 親展オブジェクト 関数名 ICAEncryptionObjectCreate ICAEncryptionObjectDestroy ICAEncryptionObjectRegisterCSP ICAEncryptionObjectGenerateKey ICAEncryptionObjectSetKeyTransferAlgorithm ICAEncryptionObjectExportKey ICAEncryptionObjectSetAlgorithm ICAEncryptionObjectSetData ICAEncryptionObjectAddData ICAEncryptionObjectGetEncryptedData ICAEncryptionObjectGetEncryptedDataFinal 31 概要 親展オブジェクトの生成 親展オブジェクトの破壊 親展 CSP の登録 共通鍵の生成 鍵配送アルゴリズムの設定 暗号化した共通鍵の取得 共通鍵暗号アルゴリズムの設定 平文データを設定 平文データの追加設定 暗号文取得 最後の暗号文取得 2.4.2. 親展手順 1 親展オブジェクトの生成 ICAEncryptionObjectCreate 2 親展 CSP の登録 ICAEncryptionObjectRegisterCSP 3 共通鍵の生成 ICAEncryptionObjectGenerateKey 4 鍵配送アルゴリズムの設定 ICAEncryptionObjectSetKeyTransferAlgorithm 5 暗号化した共通鍵の取得 ICAEncryptionObjectExportKey 6 共通鍵暗号アルゴリズムの設定 ICAEncryptionObjectSetAlgorithm 7 平文の暗号化 ICAEncryptionObjectSetData 8 暗号文取得 ICAEncryptionObjectGetEncryptedData 9 分割暗号化の平文(省略可、分割して平文データを設定する場合に使用 ) ICAEncryptionObjectAddData 10 最後の暗号文取得 ICAEncryptionObjectGetEncryptedDataFinal 11 親展オブジェクトの破壊 ICAEncryptionObjectDestroy 32 ICAEncryptionObjectCreate() 親展オブジェクトの生成 【機能】 親展オブジェクトの生成を行う。 【形式】 ICAEncryptionObjectHandle ICAEncryptionObjectCreate( ICAErrorCode *pErr ) 【引数】 pErr: 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :親展オブジェクトハンドル 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 33 ICAEncryptionObjectDestroy() 親展オブジェクトの破棄 【機能】 親展オブジェクトの破棄を行う。 【形式】 ICAReturnCode ICAEncryptionObjectDestroy ( ICAEncryptionObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 親展オブジェクトハンドル(IN) 破棄する親展オブジェクトハンドルを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 34 ICAEncryptionObjectRegisterCSP() 親展 CSP の登録 【機能】 親展 CSP の登録を行う。 【形式】 ICAReturnCode ICAEncryptionObjectRegisterCSP ( ICAEncryptionObjectHandle hObj, ICAEncryptionObjectCSP *pCSP, ICAErrorCode *pErr ) 【引数】 hObj: pCSP: pErr: 親展オブジェクトハンドル(IN) 親展オブジェクトハンドルを指定する。 親展 CSP の関数リスト(IN) 親展 CSP の関数リストを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 35 ICAEncryptionObjectGenerateKey() 共通鍵の生成 【機能】 平文の暗号化を行う為の共通鍵を生成する。 【形式】 ICAReturnCode ICAEncryptionObjectGenerateKey( ICAEncryptionObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 親展オブジェクトハンドル(IN) 破壊する親展オブジェクトを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_FAILURE_KEYGEN 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 共通鍵生成に失敗 36 ICAEncryptionObjectSetKeyTransferAlgorithm () 鍵配送アルゴリズム設定 【機能】 鍵配送アルゴリズムの設定を行う。 【形式】 ICAReturnCode ICAEncryptionObjectSetKeyTransferAlgorithm( ICAEncryptionObjectHandle hObj, ICAAlgorithmId *pAlg, ICAErrorCode *pErr ) 【引数】 hObj: pAlg: pErr: 親展オブジェクトハンドル(IN) 親展オブジェクトハンドルを指定する。 鍵配送アルゴリズム(IN) 鍵配送アルゴリズムを指定する。詳細は「3 APP 側 API で使用する型定義」 を参照の事。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM 37 ICAEncryptionObjectExportKey () 暗号化した共通鍵の取得 【機能】 指定した公開鍵で暗号化した共通鍵を取得する。 【形式】 ICAReturnCode ICAEncryptionObjectExportkey( ICAEncryptionObjectHandle *pObj, ICAKeyObjectHandle hKey, ICAEncryptedKey *pEKey, ICAErrorCode *pErr ) 【引数】 hObj: hKey: pEKey: pErr: 親展オブジェクトハンドル(IN) 親展オブジェクトハンドルを指定する。 公開鍵オブジェクト(IN) 公開鍵オブジェクトを指定する。 暗号化した共通鍵(OUT) 暗号化した共通鍵が返される。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pEKey には親展オブジェクトが内部に保持するポインタが返される。その為、この領域は への書込みは行わない事。 親展オブジェクトを破棄した後、この領域にはアクセス不可能となる。 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM ICAE_INVALID_KEY ICAE_INVALID_KEY_LENGTH ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_INVALID_SEED ICAE_INVALID_KEY_OR_DATA 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 公開鍵不正 公開鍵の長さ不正 共通鍵データ不正 共通鍵データの長さ不正 乱数発生ルーチン初期値不正 暗号化失敗 38 ICAEncryptionObjectSetAlgorithm() 共通鍵暗号アルゴリズム設定 【機能】 共通鍵暗号アルゴリズムの設定を行う。 【形式】 ICAReturnCode ICAEncryptionObjectSetAlgorithm( ICAEncryptionObjectHandle hObj, ICAAlgorithmId *pAlg, ICAErrorCode *pErr ) 【引数】 hObj: pAlg: pErr: 親展オブジェクトハンドル(IN) 親展オブジェクトハンドルを指定する。 鍵配送アルゴリズム(IN) 鍵配送アルゴリズムを指定する。詳細は「3 APP 側 API で使用する型定義」 を参照の事。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM ICAE_INVALID_KEY ICAE_INVALID_KEY_LENGTH 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 共通鍵不正 共通鍵の長さ不正 39 ICAEncryptionObjectSetData() 平文データの設定 【機能】 平文データを設定する。 【形式】 ICAReturnCode ICAEncryptionObjectSetData( ICAEncryptionObjectHandle hObj, ICAMessage *pMsg, ICAErrorCode *pErr ) 【引数】 hObj: pMsg: pErr: 親展オブジェクトハンドル(IN) 親展オブジェクトハンドルを指定する。 平文データ(IN) 平文データを設定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_FAILURE_MALLOC 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 平文データ不正 平文データの長さ不正 メモリ確保に失敗 40 ICAEncryptionObjectAddData() 平文データの追加設定 【機能】 平文データを追加設定する。 【形式】 ICAReturnCode ICAEncryptionObjectAddData( ICAEncryptionObjectHandle hObj, ICAMessage *pMsg, ICAErrorCode *pErr ) 【引数】 hObj: pMsg: pErr: 親展オブジェクトハンドル(IN) 親展オブジェクトハンドルを指定する。 平文データ(IN) 平文データを設定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_FAILURE_MALLOC 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 平文データ不正 平文データの長さ不正 メモリ確保に失敗 41 ICAEncryptionObjectGetEncryptedData() 暗号文データの取得 【機能】 暗号文データを取得する。 【形式】 ICAReturnCode ICAEncryptionObjectGetEncryptedData( ICAEncryptionObjectHandle hObj, ICAEncryptedMessage *pEMsg, ICAErrorCode *pErr ) 【引数】 hObj: pEMsg: pErr: 親展オブジェクトハンドル(IN) 親展オブジェクトハンドルを指定する。 暗号文データ(OUT) 暗号文データが返される。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pEMsg には親展オブジェクトが内部に保持するポインタが返される。その為、この領域は への書込みは行わない事。 親展オブジェクトを破棄した後、この領域にはアクセス不可能となる。 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 42 ICAEncryptionObjectGetEncryptedDataFinal() 最後の暗号文データの取得 【機能】 最後の暗号文データを取得する。 【形式】 ICAReturnCode ICAEncryptionObjectGetEncryptedDataFinal( ICAEncryptionObjectHandle hObj, ICAEncryptedMessage *pEMsg, ICAErrorCode *pErr ) 【引数】 hObj: pEMsg: pErr: 親展オブジェクトハンドル(IN) 親展オブジェクトハンドルを指定する。 暗号文データ(OUT) 暗号文データが返される。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pEMsg には親展オブジェクトが内部に保持するポインタが返される。その為、この領域は への書込みは行わない事。 親展オブジェクトを破棄した後、この領域にはアクセス不可能となる。 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_FAILURE_MALLOC 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 平文データ不正 平文データの長さ不正 メモリ確保に失敗 43 2.5. 親展解除機能 親展解除機能は、アルゴリズム(鍵配送アルゴリズム、共通鍵暗号アルゴリズム)及び、公開鍵 暗号アルゴリズム(RSA)の秘密鍵を組み合わせて、暗号文から平文を取得する機能である。鍵 配送アルゴリズムに従って暗号化されたセッション鍵を秘密鍵で復号する機能、共通鍵暗号アル ゴリズムに従ってセッション鍵で暗号文を復号する機能を含む。鍵管理媒体上の秘密鍵を用いる 場合は、利用者認証情報(パスワード等)を用いた利用者の認証を行い、なりすましによる不正 使用を防止する。また、親展文のフォーマットに従った、暗号文と暗号化されたセッション鍵の 入力機能を含む。 <暗号アルゴリズム> セッション鍵の暗号アルゴリズム(共通鍵暗号アルゴリズム)は、任意の共通鍵ブロック暗号 アルゴリズム。公開鍵暗号アルゴリズムは、RSA。 親展解除は親展解除オブジェクトを操作する事により行う。なお、親展解除に使用する秘密鍵に 関しては、 「2.6 鍵管理機能」 、 「鍵オブジェクト」を参照の事。 2.5.1. 親展解除オブジェクト 関数名 ICADecryptionObjectCreate ICADecryptionObjectDestroy ICADecryptionObjectRegisterCSP ICADecryptionObjectSetKeyTransferAlgorithm ICADecryptionObjectImportKey ICADecryptionObjectSetAlgorithm ICADecryptionObjectSetEncryptedData ICADecryptionObjectAddEncryptedData ICADecryptionObjectGetData ICADecryptionObjectGetDataFinal 44 概要 親展解除オブジェクトの生成 親展解除オブジェクトの破壊 親展解除 CSP の登録 鍵配送アルゴリズムの設定 暗号化した共通鍵の設定 共通鍵暗号アルゴリズムの設定 暗号化されたデータの設定 暗号化されたデータの追加設定 平文取得 最後の平文取得 2.5.2. 親展解除手順 0 「2.11.2署名や親展解除で使用する為の秘密鍵の鍵オブジェクト生成と設定」の手 順で鍵管理媒体上の秘密鍵の鍵オブジェクトの生成、設定を行う。 または、 「2.11.4. メモリ上の秘密鍵、公開鍵の鍵オブジェクト生成と設定」の手 順で主記憶上の秘密鍵の鍵オブジェクトの生成、設定を行う。 1 親展解除オブジェクトの生成 ICADecryptionObjectCreate 2 親展解除 CSP の登録 ICADecryptionObjectRegisterCSP 3 鍵配送アルゴリズムの設定 ICADecryptionObjectSetKeyTransferAlgorithm 4 暗号化した共通鍵の設定 ICADecryptionObjectImportKey 5 共通鍵暗号アルゴリズムの設定 ICADecryptionObjectSetAlgorithm 6 暗号化されたデータの設定 ICADecryptionObjectSetEncryptedData 7 平文取得 ICADecryptionObjectGetData 8 暗号化されたデータの追加設定(省略可、分割して暗号文データを設定する場合に使用 ) ICADecryptionObjectAddEncryptedData 9 最後の平文取得 ICADecryptionObjectGetDataFinal 10 親展解除オブジェクトの破壊 ICADecryptionObjectDestroy *0 は親展解除オブジェクトを用いるための準備フェーズ 45 ICADecryptionObjectCreate() 親展解除オブジェクトの生成 【機能】 親展解除オブジェクトの生成を行う。 【形式】 ICADecryptionObjectHandle ICAErrorCode ) ICADecryptionObjectCreate ( *pErr 【引数】 pErr: 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :親展解除オブジェクト(0 以外) 異常終了 :0 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 46 ICADecryptionObjectDestroy() 親展解除オブジェクトの破棄 【機能】 親展解除オブジェクトの破棄を行う。 【形式】 ICAReturnCode ICADecryptionObjectDestroy ( ICADecryptionObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 親展解除オブジェクトハンドル(IN) 破棄する親展解除オブジェクトハンドルを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 47 ICADecryptionObjectRegisterCSP() 親展解除 CSP の登録 【機能】 親展解除 CSP の登録を行う。 【形式】 ICAReturnCode ICADecryptionObjectRegisterCSP ( ICADecryptionObjectHandle hObj, ICADecryptionObjectCSP *pCSP, ICAErrorCode *pErr ) 【引数】 hObj: pCSP: pErr: 親展解除オブジェクトハンドル(IN) 親展解除オブジェクトハンドルを指定する。 親展解除 CSP の関数リスト(IN) 親展解除 CSP の関数リストを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 48 ICADecryptionObjectSetKeyTransferAlgorithm () 鍵配送アルゴリズム設定 【機能】 鍵配送アルゴリズムの設定を行う。 【形式】 ICAReturnCode ICADecryptionObjectSetKeyTransferAlgorithm( ICADecryptionObjectHandle hObj, ICAAlgorithmId *pAlg, ICAErrorCode *pErr ) 【引数】 hObj: pAlg: pErr: 親展解除オブジェクトハンドル(IN) 親展解除オブジェクトハンドルを指定する。 鍵配送アルゴリズム(IN) 鍵配送アルゴリズムを指定する。詳細は「3 APP 側 API で使用する型定義」 を参照の事。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 49 ICADecryptionObjectImportKey () 暗号化された共通鍵の設定 【機能】 指定した秘密鍵で暗号化された共通鍵を復号し内部に保管する。 【形式】 ICAReturnCode ICADecryptionObjectImportKey( ICADecryptionObjectHandle hObj, ICAKeyObjectHandle hKey, ICAEncryptedKey *pEKey, ICAErrorCode *pErr ) 【引数】 hObj: hKey: pEKey: pErr: 親展解除オブジェクトハンドル(IN) 親展解除オブジェクトハンドルを指定する。 秘密鍵オブジェクト(IN) 秘密鍵オブジェクトを指定する。 暗号化された共通鍵(IN) 暗号化された共通鍵を設定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM ICAE_INVALID_KEY_HANDLE ICAE_INVALID_KEY ICAE_INVALID_KEY_LENGTH ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_INVALID_KEY_OR_DATA ICAE_FAILURE_MALLOC ICAE_DEVICE_FAILURE ICAE_DEVICE_FAILURE_MALLOC ICAE_DEVICE_REMOVED ICAE_SESSION_INVALID_HANDLE ICAE_SESSION_CLOSED ICAE_SESSION_USER_NOT_LOGGED_IN ICAE_FUNCTION_FAILED ICAE_OTHER (注) 「秘密鍵情報の不正」を含む 50 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 鍵オブジェクト不正 秘密鍵不正 (注) 秘密鍵の長さ不正 暗号文データ不正 暗号文データの長さ不正 復号失敗 メモリ確保に失敗 暗号トークンのエラー 暗号トークンにおけるメモリ確保の失敗 暗号トークンは取り除かれている セッションハンドル不正 セッションはクローズ状態 暗号トークンに対して未ログイン 回復可能なエラー発生 その他のエラー発生 ICADecryptionObjectSetAlgorithm() 共通鍵暗号アルゴリズム設定 【機能】 共通鍵暗号アルゴリズムの設定を行う。 【形式】 ICAReturnCode ICADecryptionObjectSetAlgorithm( ICADecryptionObjectHandle hObj, ICAAlgorithmId *pAlg, ICAErrorCode *pErr ) 【引数】 hObj: pAlg: pErr: 親展解除オブジェクトハンドル(IN) 親展解除オブジェクトハンドルを指定する。 鍵配送アルゴリズム(IN) 鍵配送アルゴリズムを指定する。詳細は「3 APP 側 API で使用する型定義」 を参照の事。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM ICAE_INVALID_KEY ICAE_INVALID_KEY_LENGTH 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 共通鍵不正 共通鍵の長さ不正 51 ICADecryptionObjectSetEncryptedData() 暗号文データの設定 【機能】 暗号文データを設定する。 【形式】 ICAReturnCode ICADecryptionObjectSetEncryptedData( ICADecryptionObjectHandle hObj, ICAEncryptedMessage *pEMsg, ICAErrorCode *pErr ) 【引数】 hObj: pEMsg: pErr: 親展解除オブジェクトハンドル(IN) 親展解除オブジェクトハンドルを指定する。 暗号文データ(IN) 暗号文データを設定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 暗号文データ不正 暗号文データの長さ不正 メモリ確保に失敗 ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_FAILURE_MALLOC 52 ICADecryptionObjectAddEncryptedData() 暗号文データの追加設定 【機能】 暗号文データを追加設定する。 【形式】 ICAReturnCode ICADecryptionObjectAddEncryptedData( ICADecryptionObjectHandle hObj, ICAEncryptedMessage *pEMsg, ICAErrorCode *pErr ) 【引数】 hObj: pEMsg: pErr: 親展解除オブジェクトハンドル(IN) 親展解除オブジェクトハンドルを指定する。 暗号文データ(IN) 暗号文データを設定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_INVALID_KEY_OR_DATA ICAE_FAILURE_MALLOC 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 暗号文データ不正 暗号文データの長さ不正 共通鍵または暗号文データ不正 メモリ確保に失敗 53 ICADecryptionObjectGetData() 平文データの取得 【機能】 平文データを取得する。 【形式】 ICAReturnCode ICADecryptionObjectGetData( ICADecryptionObjectHandle hObj, ICAMessage *pMsg, ICAErrorCode *pErr ) 【引数】 hObj: pMsg: pErr: 親展解除オブジェクトハンドル(IN) 親展解除オブジェクトハンドルを指定する。 平文データ(OUT) 平文データが返される。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pMsg には親展解除オブジェクトが内部に保持するポインタが返される。その為、この領域 はへの書込みは行わない事。 親展解除オブジェクトを破棄した後、この領域にはアクセス不可能となる。 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 54 ICADecryptionObjectGetDataFinal() 最後の平文データの取得 【機能】 最後の平文データを取得する。 【形式】 ICAReturnCode ICADecryptionObjectGetDataFinal( ICADecryptionObjectHandle hObj, ICAMessage *pMsg, ICAErrorCode *pErr ) 【引数】 hObj: pMsg: pErr: 親展解除オブジェクトハンドル(IN) 親展解除オブジェクトハンドルを指定する。 平文データ(OUT) 平文データが返される。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pMsg には親展解除オブジェクトが内部に保持するポインタが返される。その為、この領域 はへの書込みは行わない事。 親展解除オブジェクトを破棄した後、この領域にはアクセス不可能となる。 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_DATA_LENGTH ICAE_INVALID_KEY_OR_DATA ICAE_FAILURE_MALLOC 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 暗号文データの長さ不正 復号失敗 メモリ確保に失敗 55 2.6. 鍵管理機能 鍵管理機能は鍵管理媒体(固定ディスク、IC カード又は HSM)を用いて、公開鍵暗号アルゴリズ ムの秘密鍵を管理(保管、取得、削除)する機能。署名生成機能と組み合わせる事によって、鍵 管理媒体上の秘密鍵を用いて署名を生成する機能を含む。親展解除機能と組み合わせる事によっ て、鍵管理媒体上の秘密鍵を用いて親展解除を行う機能を含む。秘密鍵を用いる場合は、利用者 認証情報(パスワード等)を用いた利用者の認証を行い、なりすましによる不正使用を防止する。 さらに、HD の場合は、メッセージ認証コード等の暗号アルゴリズムを用いて、保管中の秘密鍵 の改ざん及び暴露から保護する。 <公開鍵暗号アルゴリズム> RSA を含む2個以上の、政府告示の署名アルゴリズムに対応する公開鍵暗号アルゴリズム。 <秘密鍵管理媒体> HD、IC カード、又は HSM (Hardware Security Module) 鍵管理機能を実現する為の API 仕様として、業界標準として普及している PKCS#11(Version2.01 以降)を採用する。 56 2.6.1. 利用者認証情報を用いた鍵管理媒体へのログイン認証手順 なりすましによる不正使用を防止の為、鍵管理媒体上の秘密鍵を用いる場合には利用者認証情報 (パスワード等)を用いた利用者の認証を行う必要がある。 ここでは鍵管理媒体の使用の為の認証手順例を記載する。なお、Crypto-API で使用する PKCS#11 関数に関しては「4Crypto-API で使用する PKCS #11 のインタフェース」を、詳細な関数仕様等 は参考文献[1]、または使用する鍵管理管理媒体の PKCS#11 ライブラリの仕様説明書を参照の事。 1 使用する PKCS#11 ライブラリの関数「C_GetFunctionList」のアドレスを取得 2 PKCS#11 ライブラリの関数リストを取得 C_GetFunctionList 3 PKCS#11 ライブラリを初期化 C_Initialize 4 スロット数の取得 C_GetSlotList 5 スロットリストの取得 C_GetSlotList 6 セッションオープン C_OpenSession 7 利用者認証情報による認証(ログイン) C_Login 57 2.6.2. 公開鍵暗号アルゴリズムの秘密鍵を管理(保管)する手順 公開鍵暗号アルゴリズムの秘密鍵の保管手順を記載する。 なお、Crypto-API で使用する PKCS#11 関数に関しては「4Crypto-API で使用する PKCS #11 のイ ンタフェース」を、詳細な関数仕様等は参考文献[1]、または使用する鍵管理管理媒体の PKCS#11 ライブラリの仕様説明書を参照の事。 1 「2.6.1利用者認証情報を用いた鍵管理媒体へのログイン認証手順」の手順で利用者認証 情報による認証を行う。 2 秘密鍵を鍵管理媒体に保管 C_CreateObject 2.6.3. 公開鍵暗号アルゴリズムの秘密鍵を管理(取得)する手順 公開鍵暗号アルゴリズムの秘密鍵を用いた処理(署名や親展解除)を行う為に必要な鍵情報 (PKCS#11 の秘密鍵の鍵オブジェクト)の取得手順を記載する。 なお、Crypto-API で使用する PKCS#11 関数に関しては「4Crypto-API で使用する PKCS #11 のイ ンタフェース」を、詳細な関数仕様等は参考文献[1]、または使用する鍵管理管理媒体の PKCS#11 ライブラリの仕様説明書を参照の事。 1 「2.6.1利用者認証情報を用いた鍵管理媒体へのログイン認証手順」の手順で利用者認証 情報による認証を行う。 2 秘密鍵の検索条件の設定 C_FindObjectsInit 3 秘密鍵の検索、PKCS#11 の秘密鍵の鍵オブジェクトの取得 C_FindObjects 4 検索終了 C_FindObjectsFinal 58 2.6.4. 公開鍵暗号アルゴリズムの秘密鍵を管理(削除)する手順 公開鍵暗号アルゴリズムの秘密鍵の削除手順を記載する。 なお、Crypto-API で使用する PKCS#11 関数に関しては「4Crypto-API で使用する PKCS #11 のイ ンタフェース」を、詳細な関数仕様等は参考文献[1]、または使用する鍵管理管理媒体の PKCS#11 ライブラリの仕様説明書を参照の事。 1 「2.6.3公開鍵暗号アルゴリズムの秘密鍵を管理(取得) 」の手順で PKCS#11 の秘密鍵の 鍵オブジェクトを取得する。 2 秘密鍵削除 C_DestroyObject 2.6.5. 鍵管理媒体上の秘密鍵を用いて署名を生成する手順 署名生成機能と組み合わせる事によって、鍵管理媒体上の秘密鍵を用いて署名を生成する手順は 「2.2署名生成機能」を参照の事。 2.6.6. 鍵管理媒体上の秘密鍵を用いて親展解除を行う手順 親展解除機能と組み合わせる事によって、鍵管理媒体上の秘密鍵を用いて親展解除を行う手順は 「2.5親展解除機能」を参照の事。 2.6.7. 鍵管理媒体として HD を使用する場合の注意 鍵管理媒体として HD を使用する場合は、メッセージ認証コード等の暗号アルゴリズムを用いて、 保管中の秘密鍵の改ざん及び暴露から保護する事。 2.6.8. 鍵管理媒体の後処理手順 利用者認証情報を用いた鍵管理媒体へのログイン認証をした場合の後処理例を記載する。 なお、Crypto-API で使用する PKCS#11 関数に関しては「4Crypto-API で使用する PKCS #11 のイ ンタフェース」を、詳細な関数仕様等は参考文献[1]、または使用する鍵管理管理媒体の PKCS#11 ライブラリの仕様説明書を参照の事。 1 トークンからのログアウト C_Logout 2 セッションの終結 C_CloseSession 3 PKCS#11 ライブラリの終了 C_Finalize 59 2.7. 証明書管理機能 証明書管理機能は、証明書管理媒体(固定ディスク、IC カード又は HSM)を用いて、証明書を管 理(保管、取得、削除)する機能、及び証明書内部の項目を取得する機能である。証明書には、 利用者(自分)の証明書、CA の証明書及び他人の証明書を含む。 さらに、信頼点に相当する証明書を含む。信頼点に相当する証明書を管理する場合は、利用者認 証情報(パスワード等)を用いた利用者の認証を行い、なりすましによる不正使用を防止する。 HD の場合は、メッセージ認証コード等の暗号アルゴリズムを用いて、保管中の信頼点となる証 明書を改ざん及び暴露から保護する。自分の証明書の申請及び取得機能も含む。 <証明書管理媒体> HD、IC カード、又は HSM(Hardware Security Module) 。 証明書内部の項目を取得する機能。自分の証明書を申請・取得する機能を含む。 証明書の管理機能は「2.7.1証明書管理」を参照の事。証明書内部の項目を取得する機能は「2.7.9 証明書項目取得」を参照の事。また、自分の証明書を申請・取得する機能は「2.7.8証明書申請・ 取得」を参照の事。 2.7.1. 証明書管理 証明書管理媒体(固定ディスク、IC カード又は HSM)を用いて、証明書を管理(保管、取得、削 除)する機能。 証明書管理媒体の管理を行う機能の実現をする為の API 仕様として、業界標準として普及してい る PKCS#11(Version2.01 以降)を採用する。 60 2.7.2. 利用者認証情報を用いた証明書管理媒体へのログイン認証手順 信頼点に相当する証明書を管理する場合は、なりすましによる不正使用を防止の為、利用者認証 情報(パスワード等)を用いた利用者の認証を行う事。 ここでは証明書管理媒体の認証手順例を記載する。なお、Crypto-API で使用する PKCS#11 関数 に関しては「4Crypto-API で使用する PKCS #11 のインタフェース」を、詳細な関数仕様等は参 考文献[1]、または使用する証明書管理管理媒体の PKCS#11 ライブラリの仕様説明書を参照の事。 1 使用する PKCS#11 ライブラリの関数「C_GetFunctionList」のアドレスを取得 2 PKCS#11 ライブラリの関数リストを取得 C_GetFunctionList 3 PKCS#11 ライブラリの初期化 C_Initialize 4 スロット数の取得 C_GetSlotList 5 スロットリストの取得 C_GetSlotList 6 セッションオープン C_OpenSession 7 利用者認証情報による認証(ログイン) C_Login 61 2.7.3. 証明書の管理(保管)手順 証明書の保管手順を記載する。 なお、Crypto-API で使用する PKCS#11 関数に関しては「4Crypto-API で使用する PKCS #11 のイ ンタフェース」を、詳細な関数仕様等は参考文献[1]、または使用する鍵管理管理媒体の PKCS#11 ライブラリの仕様説明書を参照の事。 1 「2.7.2利用者認証情報を用いた証明書管理媒体へのログイン認証手順」の手順で利用者 認証情報による認証を行う。 2 証明書を証明書管理媒体に保管 C_CreateObject 2.7.4. 証明書の管理(取得)手順 証明書の取得手順を記載する。 なお、Crypto-API で使用する PKCS#11 関数に関しては「4Crypto-API で使用する PKCS #11 のイ ンタフェース」を、詳細な関数仕様等は参考文献[1]、または使用する鍵管理管理媒体の PKCS#11 ライブラリの仕様説明書を参照の事。 1 「2.6.1利用者認証情報を用いた鍵管理媒体へのログイン認証手順」の手順で利用者認証 情報による認証を行う。 2 証明書の検索条件の設定 C_FindObjectsInit 3 証明書の検索、PKCS#11 の証明書オブジェクトの取得 C_FindObjects 4 検索終了 C_FindObjectsFinal 5 証明書の取得 C_GetAttributeValue 62 2.7.5. 証明書の管理(削除)手順 証明書の削除手順を記載する。 なお、Crypto-API で使用する PKCS#11 関数に関しては「4Crypto-API で使用する PKCS #11 のイ ンタフェース」を、詳細な関数仕様等は参考文献[1]、または使用する鍵管理管理媒体の PKCS#11 ライブラリの仕様説明書を参照の事。 1 「2.6.1利用者認証情報を用いた鍵管理媒体へのログイン認証手順」の手順で利用者認証 情報による認証を行う。 2 証明書の検索条件の設定 C_FindObjectsInit 3 証明書の検索、PKCS#11 の証明書オブジェクトの取得 C_FindObjects 4 検索終了 C_FindObjectsFinal 5 証明書削除 C_DestroyObject 2.7.6. 証明書管理媒体として HD を使用する場合の注意 証明書管理媒体として HD を使用する場合は、メッセージ認証コード等の暗号アルゴリズムを用 いて、保管中の秘密鍵の改ざん及び暴露から保護する事。 2.7.7. 証明書管理媒体の後処理手順 利用者認証情報を用いた証明書管理媒体へのログイン認証をした場合の後処理例を記載する。 なお、Crypto-API で使用する PKCS#11 関数に関しては「4Crypto-API で使用する PKCS #11 のイ ンタフェース」を、詳細な関数仕様等は参考文献[1]、または使用する鍵管理管理媒体の PKCS#11 ライブラリの仕様説明書を参照の事。 1 トークンからのログアウト C_Logout 2 セッションの終結 C_CloseSession 3 PKCS#11 ライブラリの終了 C_Finalize 63 2.7.8. 証明書申請・取得 自分の証明書の申請及び取得機能であり、証明書申請オブジェクトにより証明書申請機能を実現し、証明 書コンテナオブジェクトにより証明書取得機能を実現する。 2.7.8.1. 証明書申請オブジェクト 証明書申請オブジェクトは、証明書の申請を行うためのオブジェクトである。 関数名 ICACertRequestObjectCreate ICACertRequestObjectDestroy ICACertRequestObjectSetKeyPair ICACertRequestObjectSetSubjectName ICACertRequestObjectSetAlgorithmInfo ICACertRequestObjectSetChallengePassword ICACertRequestObjectAddEmailAddress ICACertRequestObjectAddUnstructuredAddress ICACertRequestObjectAddUnstructuredName ICACertRequestObjectGenMyCertRequest 64 機能 オブジェクトの生成 オブジェクトの破棄 鍵対の設定 証明書所有者の名前情報の設定 アルゴリズム情報の設定 証明書取り消し要求パスワードの設定 電子メールアドレスの追加 証明書発行要求者の住所の追加 証明書発行要求者の名前の追加 証明書発行要求の生成 ICACertRequestObjectCreate() オブジェクトの生成 【機能】 証明書申請オブジェクトの生成を行う。 【形式】 ICACertRequestObjectHandle ICACertRequestObjectCreate( ICAErrorCode *pErr ) 【引数】 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :証明書申請オブジェクト(0 以外) 異常終了 :0 【補足】 本関数を使用して生成した証明書申請オブジェクトは、使用後に必ず ICACertRequestObjectDestroy()を用いて破棄する必要がある。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 65 ICACertRequestObjectDestroy() オブジェクトの破棄 【機能】 証明書申請オブジェクトを破棄します。 【形式】 ICAReturnCode ICACertRequestObjectDestroy ( ICACertRequestObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj pErr 証明書申請オブジェクト(IN) 証明書申請オブジェクトを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 ICACertRequestObjectCreate()を用いて生成した証明書申請オブジェクトは、使用後 に必ず本関数を用いて破棄する必要がある。 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 66 ICACertRequestObjectSetKeyPair () 鍵対の設定 【機能】 証明書申請するための公開鍵アルゴリズムの鍵対を設定する。 【形式】 ICAReturnCode ICACertRequestObjectSetKeyPair( ICACertRequestObjectHandle hObj, ICAKeyObjectHandle hPriKey, ICAKeyObjectHandle hPubKey, ICAErrorCode *pErr ) 【引数】 hObj hPriKey hPubKey pErr 証明書申請オブジェクト(IN) 証明書申請オブジェクトを指定する。 秘密鍵の鍵オブジェクト(IN) 証明書申請するための秘密鍵の鍵オブジェクトを設定する。 公開鍵の鍵オブジェクト(IN) 証明書申請するための公開鍵の鍵オブジェクトを設定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_KEYHANDLE ICAE_INVALID_KEYLENGTH ICAE_INVALID_KEY ICAE_FAILURE_MALLOC 67 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 鍵タイプ不正 鍵長不正 鍵不正 メモリの確保に失敗 ICACertRequestObjectSetSubjectName() 証明書所有者の名前情報の設定 【機能】 証明書所有者の名前情報を設定する。 【形式】 ICAReturnCode ICACertRequestObjectSetSubjectName ( ICACertRequestObjectHandle hObj, ICANameObject *pSubjectNameObj, ICAErrorCode *pErr ) 【引数】 hObj 証明書申請オブジェクト(IN) 証明書申請オブジェクトを指定する。 pSubjectNameObj 証明書所有者の名前情報(IN) 証明書所有者の名前情報を設定する。 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 同一の証明書申請オブジェクトに本関数を複数回適用した場合、後から設定したもの が有効となる。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_DATA 証明書所有者の名前情報が不正 ICAE_FAILURE_MALLOC メモリの確保に失敗 68 ICACertRequestObjectSetAlgorithmInfo() アルゴリズム情報の設定 【機能】 アルゴリズム情報を設定する。 【形式】 ICAReturnCode ICACertRequestObjectSetAlgorithmInfo( ICACertRequestObjectHandle hObj, ICAAlgorithmId *pAlg, ICAErrorCode *pErr ) 【引数】 hObj pAlg pErr 証明書申請オブジェクト(IN) 証明書申請オブジェクトを指定する。 アルゴリズム情報(IN) アルゴリズム情報を設定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 同一の証明書申請オブジェクトに本関数を複数回適用した場合、後から設定したもの が有効となる。 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_FAILURE_MALLOC 69 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 アルゴリズム情報が不正 メモリの確保に失敗 ICACertRequestObjectGenMyCertRequest() 証明書発行要求の生成 【機能】 証明書発行要求(PKCS#10 形式)を生成する。 【形式】 ICAReturnCode ICACertRequestObjectGenMyCertRequest ( ICACertRequestObjectHandle hObj, ICAEncodedData **ppCertRequest, ICAErrorCode *pErr ) 【引数】 hObj 証明書申請オブジェクト(IN) 証明書申請オブジェクトを設定する。 ppCertRequest 証明書発行要求の格納領域(OUT) 証明書発行要求が返される。 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_FAILURE_MALLOC メモリの確保に失敗 70 ICACertRequestObjectSetChallengePassword 証明書取り消し要求パスワードの設定 【機能】 証明書取り消し要求パスワードを設定する。 【形式】 ICAReturnCode ICACertRequestObjectSetChallengePassword( ICACertRequestObjectHandle hObj, Int32 lStringType, ICAMessage *pChallengePassword, ICAErrorCode *pErr ) 【引数】 hObj オブジェクト(IN) 証明書申請オブジェクトを設定する。 lStringType 文字列タイプ(IN) 文字列のタイプを設定する。 pChallengePassword 証明書取り消し要求パスワード(IN) 証明書取り消し要求パスワードを設定する。 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 本関数で設定するパスワードは暗号化されずに証明書発行要求に含まれる。したがっ て、証明書取り消し要求パスワードを含む証明書発行要求を CA へ送る際には、暗号化 された通信路などの機密の確保された手段を用いる必要がある。 証明書取り消し要求パスワードに設定できる文字列の文字数の上限は規定しない。長 さ0の文字列も設定できる。 同一の ICAAttribute オブジェクトに本関数を複数回適用した場合、後から設定したも のが有効となる。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_DATA データ不正 ICAE_FAILURE_MALLOC メモリの確保に失敗 lStringType で設定できる主な文字列タイプを以下に示す。 ・ICA_PRINTABLE_STRING ・ICA_T61_STRING ・ICA_UNIVERSAL_STRING 71 ICACertRequestObjectAddEmailAddress () 電子メールアドレスの追加 【機能】 電子メールアドレスを追加する。 【形式】 ICAReturnCode ICACertRequestObjectAddEmailAddress( ICACertRequestObjectHandle hObj, ICAMessage *pEmailAddress, ICAErrorCode *pErr ) 【引数】 hObj 証明書申請オブジェクト(IN) 証明書申請オブジェクトを指定する。 pEmailAddress 電子メールアドレス(IN) 電子メールアドレスを設定する。 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 電子メールアドレスで使用できる文字列タイプは ICA_IA5_STRING のみ。 電子メールアドレスには1バイト以上の文字列を設定できる。文字数の上限は規定し ない。 電子メールアドレスは複数追加できる。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_DATA データ不正 ICAE_FAILURE_MALLOC メモリの確保に失敗 72 ICACertRequestObjectAddUnstructuredAddress () 証明書発行要求者の住所の追加 【機能】 証明書発行要求者の住所を追加する。 【形式】 ICAReturnCode ICACertRequestObjectAddUnstructuredAddress( ICACertRequestObjectHandle hObj, Int32 lStringType, ICAMessage *pUnstructuredAddress, ICAErrorCode *pErr ) 【引数】 hObj 証明書申請オブジェクト(IN) 証明書申請オブジェクトを指定する。 lStringType 文字列タイプ(IN) 文字列のタイプを設定する。 pUnstructuredAddress 証明書発行要求者の住所(IN) 証明書発行要求者の住所を設定する。 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 証明書発行要求者の住所には1バイト以上の文字列を設定できる。文字数の上限は規 定しない。 証明書発行要求者の住所は複数追加できる。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_DATA データ不正 ICAE_FAILURE_MALLOC メモリの確保に失敗 設定できるおもな文字列タイプを以下に示す。 ・ICA_PRINTABLE_STRING ・ICA_T61_STRING ・ICA_UNIVERSAL_STRING 73 ICACertRequestObject AddUnstructuredName() 証明書発行要求者の名前の追加 【機能】 証明書発行要求者の名前を追加する。 【形式】 ICAReturnCode ICAAttributeObjectAddUnstructuredName( ICACertRequestObjectHandle hObj, Int32 lStringType, ICAMessage *pUnstructuredName, ICAErrorCode *pErr ) 【引数】 hObj 証明書申請オブジェクト(IN) 証明書申請オブジェクトを指定する。 lStringType 文字列タイプ(IN) 文字列のタイプを設定する。 pUnstructuredName 証明書発行要求者の名前(IN) 証明書発行要求者の名前を設定する。 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 証明書発行要求者の名前には1バイト以上の文字列を設定できる。文字数の上限は規 定しない。 証明書発行要求者の名前は複数追加できる。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_DATA データ不正 ICAE_FAILURE_MALLOC メモリの確保に失敗 設定できる主な文字列タイプを以下に示す。 ・ICA_IA5_STRING ・ICA_UNIVERSAL_STRING 74 2.7.8.2. 証明書コンテナオブジェクト 証明書コンテナオブジェクトは、CA から発行された証明書コンテナデータをあらわし、コンテナデータか ら証明書を取得する機能を提供する。 関数名 ICACertContainerObjectCreate ICACertContainerObjectDestroy ICACertContainerObjectSetContainer ICACertContainerObjectGetCertFirst ICACertContainerObjectGetCertNext 機能 オブジェクトの生成 オブジェクトの破棄 コンテナデータの設定 最初の証明書の取得 2番目以降の証明書の取得 75 ICACertContainerObjectCreate() オブジェクトの生成 【機能】 証明書コンテナオブジェクトを生成する。 【形式】 ICACertContainerObjectHandle ICAErrorCode ) ICACertContainerObjectCreate( *pErr 【引数】 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICACertContainerObjectHandle(0 以外) 異常終了 : 0 【補足】 本関数を使用して生成した証明書コンテナオブジェクトは、使用後に必ず ICACertContainerObjectDestroy()を用いて破棄する必要がある。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 76 ICACertContainerObjectDestroy() オブジェクトの破棄 【機能】 証明書コンテナオブジェクトを破棄する。 【形式】 ICAReturnCode ICACertContainerObjectDestroy( ICACertContainerObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj pErr 証明書コンテナオブジェクト(IN) 証明書コンテナオブジェクトを設定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 ICACertContainerObjectCreate()を用いて生成した証明書コンテナオブジェクトは、 使用後に必ず本関数を用いて破棄する必要がある。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_MEMORY_FREE メモリの解放に失敗 77 ICACertContainerObjectSetContainer () コンテナデータの設定 【機能】 コンテナデータを設定する。 【形式】 ICAReturnCode ICACertContainerObjectSetContainer( ICACertContainerObjectHandle hObj, ICAEncodedData *pCertContainer, ICAErrorCode *pErr ) 【引数】 hObj 証明書コンテナオブジェクト(IN) 証明書コンテナオブジェクトを設定する。 pCertContainer コンテナデータ(IN) コンテナデータを設定する。 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_DATA コンテナデータが不正 ICAE_FAILURE_MALLOC メモリの確保に失敗 ICAE_MEMORY_FREE メモリの解放に失敗 78 ICACertContainerObjectGetCertFirst () 証明書の取得 【機能】 最初の証明書を取得する。 【形式】 ICAReturnCode ICACertCRLContainerObjectGetCertFirst( ICACertContainerObjectHandle hObj, ICACertObjectHandle *phCertObj, ICAErrorCode *pErr ) 【引数】 hObj 証明書コンテナオブジェクト(IN) 証明書コンテナオブジェクトを設定する。 phCertObj 証明書オブジェクト(OUT) 証明書オブジェクトが返される。 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 phCertObj には、関数内部で新規に生成された証明書オブジェクトが返される。この 証明書オブジェクトは保持していた証明書コンテナオブジェクトが破棄される際に同 時に破棄される。したがって、証明書コンテナオブジェクトを破棄した後、そこから 取得した証明書オブジェクトは使用できなくなる。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_DATA 証明書の格納領域が不正 ICAE_OTHER 取得できる証明書が存在しない ICAE_FAILURE_MALLOC メモリの確保に失敗 79 ICACertContainerObjectGetCertNext () 証明書の取得 【機能】 2番目以降の証明書を取得する。 【形式】 ICAReturnCode ICACertContainerObjectGetCertNext( ICACertContainerObjectHandle hObj, ICACertObjectHandle *phCertObj, ICAErrorCode *pErr ) 【引数】 hObj 証明書コンテナオブジェクト(IN) 証明書コンテナオブジェクトを設定する。 phCertObj 証明書オブジェクト(OUT) 証明書が返される。 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 phCertObj には、関数内部で新規に生成された証明書オブジェクトが返されます。こ の証明書オブジェクトは保持していた証明書コンテナオブジェクトが破棄される際に 同時に破棄される。したがって、証明書コンテナオブジェクトを破棄した後、そこか ら取得した証明書オブジェクトは使用できなくなる。 本関数は、ICACertCRLContainerObjectGetCertFirst()を実行した後に実行できる。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_DATA 証明書の格納領域が不正 ICAE_OTHER 取得できる証明書が存在しない ICAE_FAILURE_MALLOC メモリの確保に失敗 80 2.7.9. 証明書項目取得 証明書オブジェクトの操作を行うことにより、証明書の項目取得を行う。 証明書オブジェクト関数一覧 関数名 ICACertObjectCreate ICACertObjectDestroy ICACertObjectSetPdu ICACertObjectGetSubjectName ICACertObjectGetIssuerSerial ICACertObjectGetValidity ICACertObjectGetPubkeyObject 機能 オブジェクトの生成 オブジェクトの破棄 証明書の交換形式データの設定 証明書所有者の名前情報の取得 証明書 ID の取得 証明書有効期間の取得 公開鍵の鍵オブジェクトの取得 2.7.10. 証明書項目取得手順 1 証明書オブジェクトの生成 ICACertObjectCreate 2 証明書の交換形式データの設定 ICACertObjectSetPdu 3 項目の取得 ICACertObjectGetSubjectName ICACertObjectGetIssuerSerial ICACertObjectGetValidity ICACertObjectGetPubkeyObject ICANameObjectGetPduString 4 証明書オブジェクトの破棄 ICACertObjectDestroy 81 ICACertObjectCreate() 証明書オブジェクトの生成 【機能】 証明書オブジェクトを生成する。 【形式】 ICACertObjectHandle ICAErrorCode ) ICACertObjectCreate( *pErr 【引数】 pErr: 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :証明書オブジェクトハンドル(0 以外) 異常終了 :0 【補足】 本関数を使用して生成した証明書オブジェクトは、使用後に必ず ICACertObjectDestroy() を用いて破棄する必要がある。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 82 ICACertObjectDestroy() 証明書オブジェクトの破棄 【機能】 証明書オブジェクトを破棄する。 【形式】 ICAReturnCode ICACertObjectDestroy( ICACertObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 証明書オブジェクトハンドル(IN) 破棄する証明書オブジェクトを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 ICACertObjectCreate()を用いて生成した証明書オブジェクトは、使用後に必ず本関数を用 いて破棄する必要がある。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 83 ICACertObjectSetPdu() 証明書の交換形式データの設定 【機能】 証明書の交換形式データを設定する。 【形式】 ICAReturnCode ICACertObjectSetPdu( ICACertObjectHandle hObj, ICAEncodedData *pCertPdu, ICAErrorCode *pErr ) 【引数】 hObj: 証明書オブジェクトハンドル(IN) 証明書オブジェクトハンドルを指定する。 pCertPdu: 証明書の交換形式データ(IN) 証明書の交換形式データを設定する。 pErr: 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_DATA 証明書の交換形式データが不正 ICAE_FAILURE_MALLOC メモリの確保に失敗 84 ICACertObjectGetSubjectName () 証明書所有者の名前情報取得 【機能】 証明書所有者の名前情報を取得する。 【形式】 ICAReturnCode ICACertObjectGetSubjectName( ICACertObjectHandle hObj, ICANameObject **ppNameObj, ICAErrorCode *pErr ) 【引数】 hObj: ppNameObj: pErr: 証明書オブジェクトの格納領域(IN) 証明書オブジェクトを指定する。 証明書所有者の名前オブジェクトの格納領域(OUT) 証明書所有者の名前オブジェクトを返す。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 ppNameObj には、関数内部で新規に生成された名前オブジェクトが返される。 この関数で取得した名前オブジェクトは、明示的に破棄しなくても名前オブジェクトを保 持していた証明書オブジェクトが破棄される際に同時に破棄される。その為、証明書オブ ジェクトを破棄した後、取得した名前オブジェクトは使用不可となる。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_DATA 証明書所有者の名前情報の格納領域が不正 ICAE_FAILURE_MALLOC メモリの確保に失敗 85 ICACertObjectGetIssuerSerial() 証明書 ID の取得 【機能】 証明書 ID を取得する。 【形式】 ICAReturnCode ICACertObjectGetIssuerSerial( ICACertObjectHandle hObj, ICAIssuerSerial **ppIssuerSerial, ICAErrorCode *pErr ) 【引数】 hObj: ppIssuerSerial: pErr: 証明書オブジェクトの格納領域(IN) 証明書オブジェクトを指定する。 証明書 ID の格納領域(OUT) 証明書 ID が返される。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 ppIssuerSerial には、証明書オブジェクトが内部に保持する ICAIssuerSerial 構造体への ポインタが返される。その為、ppIssuerSerial に返された構造体メンバーの値を修正して はならない。 証明書オブジェクトを破棄した後、証明書オブジェクトから取得した構造体にはアクセス 不可能となる。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_DATA 証明書 ID の格納領域が不正 86 ICACertObjectGetValidity () 証明書の有効期間を取得 【機能】 証明書の有効期間をグリニッジ標準時で取得する。 【形式】 ICAReturnCode ICACertObjectGetValidity( ICACertObjectHandle hObj, ICAValidity **ppValidity, ICAErrorCode *pErr ) 【引数】 hObj: ppValidity: pErr: 証明書オブジェクトの格納領域(IN) 証明書オブジェクトを指定する。 有効期間の格納領域(OUT) 証明書有効期間が返される。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 ppValidity には、証明書オブジェクトが内部に保持する ICAValidity 構造体へのポインタ が返される。その為、ppValidity に返された構造体メンバーの値を修正してはならない。 証明書オブジェクトを破棄した後、証明書オブジェクトから取得した構造体にはアクセス 不可能となる。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_DATA 有効期間の格納領域が不正 87 ICACertObjectGetPubkeyObject() 公開鍵の鍵オブジェクトの取得 【機能】 証明書の公開鍵の鍵オブジェクトを取得する。 【形式】 ICAReturnCode ICACertObjectGetPubkeyObject( ICACertObjectHandle hObj, ICAKeyObject **ppPubkeyObject, ICAErrorCode *pErr ) 【引数】 hObj: ppPubkeyObject: pErr: 証明書オブジェクトの格納領域(IN) 証明書オブジェクトを指定する。 公開鍵の鍵オブジェクト(OUT) 公開鍵の鍵オブジェクトが返される。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 ppPubkeyObject には、公開鍵の鍵オブジェクトが返される。解放は ICAKeyObjectDestroy を呼んで解放する事。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_KEY 公開鍵情報の格納領域が不正 88 2.8. 証明書検証機能 以下のオブジェクトを使用して、検証対象の証明書を 証明書経路の構築と検証も含めて正当性を確認する。 2.8.1. 証明書検証オブジェクト 関数名 ICACertificateValidationObjectCreate ICACertificateValidationObjectDestroy ICACertificateValidationObjectRegisterCSP ICACertificateValidationObjectSetServerInfo ICACertificateValidationObjectAttachEnv ICACertificateValidationObjectDetachEnv ICACertificateValidationObjectValidateCertificate 89 概要 証明書検証オブジェクトの生成 証明書検証オブジェクトの破棄 証明書検証 CSP の登録 証明書検証に使用するサーバ情報の設定 証明書検証環境に対する認証 証明書検証環境に対する認証の解除 証明書の検証 2.8.2. 証明書検証手順 1 証明書検証オブジェクトの生成 ICACertificateValidationObjectCreate 2 証明書検証 CSP の登録 ICACertificateValidationObjectRegisterCSP 3 証明書検証に使用するサーバ情報の設定 ICACertificateValidationObjectSetServerInfo 4 証明書検証環境に対する認証 ICACertificateValidationObjectAttachEnv 5 証明書の検証 ICACertificateValidationObjectValidateCertificate 6 証明書検証環境に対する認証の解除 ICACertificateValidationObjectDetachEnv 7 証明書検証オブジェクトの破棄 ICACertificateValidationObjectDestroy 90 ICACertificateValidationObjectCreate () 証明書検証オブジェクトの生成 【機能】 証明書検証オブジェクトの生成を行う。 【形式】 ICACertificateValidationObjectHandle ICACertificateValidationObjectCreate ( ICAErrorCode *pErr ) 【引数】 pErr: 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :証明書検証オブジェクトハンドル(0 以外) 異常終了 :0 【補足】 当関数が返す証明書検証オブジェクトハンドルに対して書き込みを行わない事。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 91 ICACertificateValidationObjectDestroy () 証明書検証オブジェクトの破棄 【機能】 証明書検証オブジェクトの破棄を行う。 【形式】 ICAReturnCode ICACertificateValidationObjectDestroy ( ICACertificateValidationObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 証明書検証オブジェクトハンドル(IN) 破棄する証明書検証オブジェクトのハンドルを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 証明書検証オブジェクトは、必ず当 API を呼び出して破棄する事。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER 引数の指定に誤り 92 ICACertificateValidationObjectRegisterCSP () 証明書検証 CSP の登録 【機能】 証明書検証 CSP の登録を行う。 【形式】 ICAReturnCode ICACertificateValidationObjectRegisterCSP ( ICACertificateValidationObjectHandle hObj, ICACertificateValidationObjectCSP *pCSP, ICAErrorCode *pErr ) 【引数】 hObj: pCSP: pErr: 証明書検証オブジェクトハンドル(IN) 証明書検証オブジェクトのハンドルを指定する。 証明書検証 CSP のリスト(IN) 証明書検証 CSP の関数リストを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 93 ICACertificateValidationObjectSetServerInfo () 証明書検証に使用するサーバ情報の設定 【機能】 証明書検証に使用するサーバ情報の設定する。 【形式】 ICAReturnCode ICACertificateValidationObjectSetServerInfo ( ICACertificateValidationObjectHandle hObj, ICACertificateValidationServerInfo *pServerInfo, ICAErrorCode *pErr, ) 【引数】 hObj: pServerInfo: pErr: 証明書検証オブジェクトハンドル(IN) 証明書検証オブジェクトのハンドルを指定する。 証明書検証関連サーバ情報(IN) 証明書検証時に使用するリポジトリなどのサーバにアクセ スする為の情報を指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER 引数の指定に誤り ICAE_LDAP_SERVER_INCORRECT LDAP サーバ指定に誤り ICAE_OCSP_SERVER_INCORRECT OCSP サーバ指定に誤り 94 ICACertificateValidationObjectAttachEnv () 証明書検証環境に対する認証 【機能】 証明書検証環境に対して認証を行う。 【形式】 ICAReturnCode ICACertificateValidationObjectAttachEnv ( ICACertificateValidationObjectHandle hObj, ICAPINData *pPIN, ICAErrorCode *pErr ) 【引数】 hObj: pPIN: pErr: 証明書検証オブジェクトハンドル(IN) 証明書検証オブジェクトのハンドルを指定する。 認証情報(IN) パスワード等の認証情報を指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER 引数の指定に誤り ICAE_INVALID_PIN パスワード不正 ICAE_ENV_ACCESS_DENIED 環境認証エラー ICAE_ENV_ACCESS_FAILED 環境アクセスエラー ICAE_ENV_INVALID 環境構築エラー(環境が正しく構築されていな い) ICAE_DEVICE_REMOVED トークン除去 ICAE_DEVICE_FAILURE トークンエラー 95 ICACertificateValidationObjectDetachEnv () 証明書検証環境に対する認証の解除 【機能】 証明書検証環境に対して認証を解除する。 【形式】 ICAReturnCode ICACertificateValidationObjectDetachEnv ( ICACertificateValidationObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 証明書検証オブジェクトハンドル(IN) 証明書検証オブジェクトのハンドルを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER 引数の指定に誤り ICAE_ENV_ACCESS_FAILED 環境アクセスエラー ICAE_ENV_INVALID 環境構築エラー(環境が正しく構築されていな い) ICAE_DEVICE_REMOVED トークン除去 ICAE_DEVICE_FAILURE トークンエラー 96 ICACertificateValidationObjectValidateCertificate () 証明書の検証 【機能】 証明書を検証し検証結果を出力する。また、失効状態についてのチェックも行う。 【形式】 ICAReturnCode ICACertificateValidationObjectValidateCertificate ( ICACertificateValidationObjectHandle hObj, ICACertificateData *pTargetCert, ICACertificateList *pUpperCerts, ICACertificateList *pTrsutAnchors, ICACertificateValidationCondition *pCondition, ICACertificateValidationResult *pCertPath, ICAErrorCode *pErr ) 【引数】 hObj: pTargetCert: pUpperCerts: pTrsutAnchors: pCondition: pCertPath: pErr: 証明書検証オブジェクトハンドル(IN) 証明書検証オブジェクトのハンドルを指定する。 検証する証明書(オブジェクト)(IN) 検証する証明書(オブジェクト)を指定する。 上位の証明書(IN) 上位の証明書を指定する。 トラストアンカーの情報(IN) トラストアンカーの情報を指定する。 検証条件(IN) 証明書検証時の検証条件を指定する。 検証に成功した証明書経路(OUT) 証明書検証の結果、検証に成功した証明書経路が返される。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 97 【補足】 pCertPath に返る証明書経路の情報通知領域は証明書検証オブジェクトを破棄すると同時に破 棄される為、必要に応じてアプリケーション側で情報をコピーする事。 pCertPath に通知する証明書経路は、 (ICACertificateData 構造体のリストにおいて)リストの 先頭にトラストアンカーの証明書が設定され、次の要素以降は下位の証明書が順次設定される。 リストの末尾は検証対象の証明書が設定される。 戻り値、及び pCertPath への通知は以下の通り。 検証状態 戻り値 pCertPath 証明書経路を構築し、検証 ICAR_SUCCESS 検証に成功した証明書経路を通知する。 対象の証明書の検証まで 完了した。 証明書経路を構築し、検索 ICAR_FAILURE 検証に成功した(一部未完了)証明書経路を 対象の証明書の検証まで 通知する。 行ったが、一部未完了の検 証がある。 1 つも証明書経路を構築 ICAR_FAILURE 通知しない。 できなかった。 証明書経路を構築したが、 ICAR_FAILURE 通知しない。 検証対象の証明書の検証 までに至る証明書経路が 見つからなかった。 98 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER 引数の指定に誤り ICAE_ENV_ACCESS_FAILED 環境アクセスエラー ICAE_ENV_INVALID 環境構築エラー(環境が正しく構築されていな い) ICAE_DEVICE_REMOVED トークン除去 ICAE_DEVICE_FAILURE トークンエラー ICAE_CERT_VALIDITY_EXPIRED 証明書が有効期間外である ICAE_CERT_REVOKED 証明書が失効されている ICAE_CERT_DECODE_FAILURE 証明書データ形式不正 ICAE_CERT_VALIDITY_UNKNOWN 検証が一部未完了 ICAE_PATH_CONSTRUCTION_FAIL 証明書経路作成失敗 ICAE_PATH_VALIDATION_FAIL 検証が成功する証明書経路の作成失敗 ICAE_TRUSTANCHOR_NOT_FOUND 証明書経路作成に必要なトラストアンカー不明 ICAE_BASICCONST_PATHLEN_VIOLATION BasicConstraints 内のパス長制限に違反 ICAE_BASICCONST_CA_NOT_TRUE BasicConstraints 内の CA フラグの設定に違反 ICAE_CERTPOLICIES_MISMATCH 受け入れ可能なポリシーが存在しない ICAE_CERT_INVALID_POLICY 証明書経路内に一貫したポリシーが存在しない ICAE_POLICYMAP_INCORRECT PolicyMapping 内の情報不正 ICAE_NAMECONST_NAME_NOT_ACCEPTED NameConstraints 内の情報に違反 ICAE_KEYUSAGE_MISMATCH KeyUsage 内の情報に違反 ICAE_LDAP_COMMUNICATION_FAIL LDAP サーバへの通信エラー ICAE_OCSP_COMMUNICATION_FAIL OCSP サーバへの通信エラー ICAE_OCSP_ACCESS_DENIED OCSP サーバへの検証要求受け付け拒否 ICAE_OCSP_SERVER_INVALID OCSP サーバ不正 ICAE_OCSP_VALIDATION_FAILED OCSP サーバによる検証失敗 ICAE_OCSP_CERT_INVALID OCSP サーバにより無効な証明書と判定 ICAE_NETWORK_TIMEOUT 通信でタイムアウト発生 99 2.9. 失効情報管理機能 失効情報管理機能は、失効情報管理媒体(固定ディスク)を用いて、失効情報を管理(保管、取 得、削除)する機能、及び失効情報内部の項目を取得する機能である。 失効情報の管理は失効情報管理オブジェクトの操作によって行う。また、失効情報内部の項目の 取得は「2.9.5失効情報の項目取得」記載の関数によって行う。 2.9.1. 失効情報管理オブジェクト 関数名 ICACRLManagementObjectCreate ICACRLManagementObjectDestroy ICACRLManagementObjectRegisterCSP ICACRLManagementObjectSetCRL ICACRLManagementObjectGetCRLList ICACRLManagementObjectDeleteCRL ICACRLManagementObjectDeleteAllCRL 概要 失効情報管理オブジェクトの生成 失効情報管理オブジェクトの破棄 失効情報管理 CSP の登録 失効情報の保管 失効情報のリスト取得 失効情報の削除 失効情報の全削除 100 2.9.2. 失効情報の保管手順 1 失効情報管理オブジェクトの生成 ICACRLManagementObjectCreate 2 失効情報管理 CSP の登録 ICACRLManagementObjectRegisterCSP 3 失効情報の保管 ICACRLManagementObjectSetCRL 4 失効情報管理オブジェクトの破棄 ICACRLManagementObjectDestroy 2.9.3. 失効情報の取得手順 1 失効情報管理オブジェクトの生成 ICACRLManagementObjectCreate 2 失効情報管理 CSP の登録 ICACRLManagementObjectRegisterCSP 3 失効情報リストの取得 ICACRLManagementObjectGetCRLList 4 リストから CRL を取得 5 失効情報管理オブジェクトの破棄 ICACRLManagementObjectDestroy 101 2.9.4. 失効情報の削除手順 1 失効情報管理オブジェクトの生成 ICACRLManagementObjectCreate 2 失効情報管理 CSP の登録 ICACRLManagementObjectRegisterCSP 3 失効情報リストの取得 ICACRLManagementObjectGetCRLList 4 リストから CRL を取得 5 失効情報の削除 ICACRLManagementObjectDeleteCRL 6 失効情報管理オブジェクトの破棄 ICARevocateManageObjectDestroy 102 ICACRLManagementObjectCreate () 失効管理情報オブジェクトの生成 【機能】 失効管理情報オブジェクトの生成を行う。 【形式】 ICACRLManagementObjectHandle ICAErrorCode ) ICACRLManagementObjectCreate( *pErr 【引数】 pErr: 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :失効管理情報オブジェクトハンドル(0 以外) 異常終了 :0 【補足】 本関数を使用して生成した失効情報管理オブジェクトは、使用後に必ず ICACRLManagementObjectDestroy()を用いて破棄する必要がある。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 103 ICACRLManagementObjectDestroy () 失効情報管理オブジェクトの破棄 【機能】 失効情報管理オブジェクトの破棄を行う。 【形式】 ICAReturnCode ICACRLManagementObjectDestroy ( ICACRLManagementObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 失効情報管理オブジェクトハンドル(IN) 破棄する失効情報管理オブジェクトハンドルを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 ICACRLManagementObjectCreate()を用いて生成した失効情報管理オブジェクトは、使用後に 必ず本関数を用いて破棄する必要がある。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 104 ICACRLManagementObjectRegisterCSP () 失効情報管理 CSP の登録 【機能】 失効情報管理 CSP の登録を行う。 【形式】 ICAReturnCode ICACRLManagementObjectRegisterCSP( ICACRLManagementObjectHandle hObj, ICACRLManagementObjectCSP *pCSP, ICAErrorCode *pErr ) 【引数】 hObj: pCSP: pErr: 失効情報管理オブジェクトハンドル(IN) 失効情報管理オブジェクトハンドルを指定する。 失効情報管理 CSP の関数リスト(IN) 失効情報管理 CSP の関数リストを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_OTHER ICAE_FATAL_ERROR 意味 オブジェクトハンドル不正 回復不能な致命的エラー発生 105 ICACRLManagementObjectSetCRL () 失効情報の保管 【機能】 失効情報を保管する。 【形式】 ICAReturnCode ICACRLManagementObjectSetCRL ( ICACRLManagementObjectHandle hObj, ICACRLData *pCRL, ICAErrorCode *pErr ) 【引数】 hObj: pCRL: pErr: 失効情報管理オブジェクトハンドル(IN) 失効情報管理オブジェクトハンドルを指定する。 CRL (IN) 保管する失効情報を指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_DATA 失効情報が不正 ICAE_FAILURE_MALLOC メモリの確保に失敗 106 ICACRLManagementObjectGetCRLList() 失効情報の取得 【機能】 失効情報を取得する。 【形式】 ICAReturnCode ICACRLManagementObjectGetCRLList ( ICACRLManagementObjectHandle hObj, ICACRLList *pCRLList, ICAErrorCode *pErr ) 【引数】 hObj: 失効情報管理オブジェクトハンドル(IN) 失効情報管理オブジェクトハンドルを指定する。 pCRLList: 保存している CRL のリスト (OUT) 保存している CRL のリストが返される。 pErr: 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pCRLList に返る失効情報リストの格納領域は失効情報管理オブジェクトが破棄され るときに破棄されるため、必要に応じて情報をコピーすること。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_FAILURE_MALLOC メモリの確保に失敗 107 ICACRLManagementObjectDeleteCRL() 失効情報の削除 【機能】 失効情報を削除する。 【形式】 ICAReturnCode ICACRLManagementObjectDeleteCRL( ICACRLManagementObjectHandle hObj, ICACRLData *pCRLData, ICAErrorCode *pErr ) 【引数】 hObj: pCRLData: pErr: 失効情報管理オブジェクトハンドル(IN) 失効情報管理オブジェクトハンドルを指定する。 CRL (IN) 失効情報管理から削除する CRL を指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 108 ICACRLManagementObjectDeleteAllCRL () すべての失効情報の削除 【機能】 保存されているすべての失効情報を削除する。 【形式】 ICAReturnCode ICACRLManagementObjectDeleteAllCRL( ICACRLManagementObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 失効情報管理オブジェクトハンドル(IN) 失効情報管理オブジェクトハンドルを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER オブジェクトハンドル不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 109 2.9.5. 失効情報の項目取得 失効情報内部の項目を取得する機能は次の関数により実現する。 関数名 ICACRLManagementGetIssuer ICACRLManagementGetUpdates ICACRLManagementGetRevokedCertificateInit ICACRLManagementGetRevokedCertificateUpdate ICACRLManagementGetRevokedCertificateFinal 110 概要 Issuer(発行者名)を取得 有効期間を取得 失効した証明書の情報の取得開始 失効した証明書の情報の取得を継続 失効した証明書の情報の取得を終了 ICACRLManagementGetIssuer() Issuer の取得 【機能】 CRL から Issuer(発行者名)を取得する。 【形式】 ICACRLManagementGetIssuer( ICACRLData ICAEncodedData ICAErrorCode ) *pCRL, *pIssuer, *pErr 【引数】 pCRL: CRL (IN) CRL を指定する。 pIssuer: 発行者名 (OUT) CRL 中に格納されている Issuer(発行者名)が BER 符号化されて返される。 pErr: 異常終了時のエラーコード (OUT) エラーコードが返される。 【戻り値】 正常終了: 異常終了: ICAR_SUCCESS ICAR_FAILURE 【補足】 pIssuer へ結果を返すためのメモリ領域は、関数内部で確保される。ただし、関数の実行 後は、その領域やメモリの内容は保証されないので、結果を保存する場合は、利用者が 確保した領域に内容をコピーすること。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER CRL データの不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 111 ICACRLManagementGetUpdates() 有効期間の取得 【機能】 CRL の有効期間を取得する。 【形式】 ICACRLManagementGetUpdates( ICACRLData UInt8 UInt8 ICAErrorCode ) *pCRL, *pThisUpdate, *pNextUpdate, *pErr 【引数】 pCRL: CRL (IN) CRL を指定する。 pThisUpdate: 発行日時 (IN/OUT) CRL が発行された日時が文字列 “YYYYMMDDHHMMSSZ” の形で返される。 pNextUpdate: 次回発行日時 (IN/OUT) CRL の次回発行予定の日時が文字列 “YYYYMMDDHHMMSSZ” の形で返される。 CRL 中に情報がない場合は、長さ 0 の文字列が返される。 pErr: 異常終了時のエラーコード (OUT) エラーコードが返される。 【戻り値】 正常終了: 異常終了: ICAR_SUCCESS ICAR_FAILURE 【補足】 pThisUpdate, pNextUpdate には、16 バイト以上の領域を確保すること。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER CRL データの不正 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 112 ICACRLManagementGetRevokedCertificateInit() 失効証明書の取得の開始 【機能】 CRL から失効した証明書の情報の取得を開始する。 【形式】 ICACRLManagementGetRevokedCertificateInit( ICACRLData *pCRL, ICARevokedCertificate *pCertificate, ICAErrorCode *pErr ) 【引数】 pCRL: CRL (IN) CRL を指定する。 pCertificate: 証明書の情報 (OUT) CRL 中に格納されている失効した証明書リストから、先頭の証明書の情報が返 される。 証明書の情報がない場合は、ICARevokedCertificate 構造体中の pSerial メン バが NULL となって返される。 pErr: 異常終了時のエラーコード (OUT) エラーコードが返される。 【戻り値】 正常終了: 異常終了: ICAR_SUCCESS ICAR_FAILURE 【補足】 pCertificate へ結果を返すためのメモリ領域は関数内部で確保される。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER CRL データの不正 ICAE_FAILURE_MALLOC メモリの確保に失敗 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 113 ICACRLManagementGetRevokedCertificateUpdate() 失効証明書の取得の継続 【機能】 CRL から失効した証明書の情報の取得を継続する。 【形式】 ICACRLManagementGetRevokedCertificateUpdate( ICACRLData *pCRL, ICARevokedCertificate *pCertificate, ICAErrorCode *pErr ) 【引数】 pCRL: CRL (IN) CRL を指定します。 pCertificate: 証明書の情報 (IN/OUT) CRL 中に格納されている失効した証明書リストから、前回、 ICACRLManagementGetRevokedCertificateInit を実行した結果、もしくは、 ICACRLManagementGetRevokedCertificateUpdate を実行した結果取得された、 情報の次の情報が返される。 証明書の情報がない場合は、ICARevokedCertificate 構造体中の pSerial メン バが NULL となって返される。 pErr: 異常終了時のエラーコード (OUT) エラーコードが返されます。 【戻り値】 正常終了: 異常終了: ICAR_SUCCESS ICAR_FAILURE 【補足】 pCertificate へ結果を返すためのメモリ領域は関数内部で確保される。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER CRL データの不正 ICAE_FAILURE_MALLOC メモリの確保に失敗 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 114 ICACRLManagementGetRevokedCertificateFinal() 失効証明書の取得の終了 【機能】 CRL から失効した証明書の情報の取得を終了する。 【形式】 ICACRLManagementGetRevokedCertificateFinal( ICARevokedCertificate *pCertificate, ICAErrorCode *pErr ) 【引数】 pCertificate: 証明書の情報 (IN) ICACRLManagementGetRevokedCertificateInit または、 ICACRLManagementGetRevokedCertificateUpdate から取得された情報を指定す る。 pErr: 異常終了時のエラーコード (OUT) エラーコードが返されます。 【戻り値】 正常終了: 異常終了: ICAR_SUCCESS ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 115 2.10. SP 管理機能 Cryptographic Service Provider(CSP)とは、交換可能な PKI ライブラリの実体である。 Crypto-API では、複数の CSP を利用目的に応じて使用する事によって、暗号アルゴリズム独立、 鍵・証明書の管理媒体独立及び証明書検証仕様独立を実現する事を目指す。SP 管理機能は、CSP の登録・削除・使用機能を含む。 2.10.1. CSP の登録機能 CSP の登録機能は鍵対生成機能から失効情報管理機能までの各機能を実現する CSP を、アプリケ ーションが Crypto-API を経由し、利用できる状態にする機能である。 鍵対生成機能、鍵管理機能、証明書管理機能に関する登録機能は、PKCS#11 の C_GetFunctionList 関数を使い、各機能を実現する為の PKCS#11 関数のアドレスを取得保存する事により実現する。 署名生成機能、署名検証機能、親展機能、親展解除機能、証明書検証機能、失効情報管理機能に 関する CSP の登録機能は各機能の RegisterCSP 関数により実現する。 2.10.2. CSP の削除機能 CSP の削除機能は、アプリケーションが処理終了時に、各 CSP の後処理を行わせる為の機能であ る。具体的には Crypto-API や CSP が使用していたメモリの解放等を行う。 鍵対生成機能、鍵管理機能、証明書管理機能に関する削除機能は、アプリケーションが PKCS#11 用に確保していたメモリの解放を行う事で実現する。 署名生成機能、署名検証機能、親展機能、親展解除機能、証明書検証機能、失効情報管理機能に 関する CSP の削除機能は各機能の Destroy 関数により実現する。 2.10.3. CSP の使用機能 CSP の使用機能は、アプリケーションが Crypto-API を使用して実現する機能そのものを指す。 116 2.11. 鍵オブジェクト 各機能を実現する際、鍵もしくは鍵に関する情報の授受の為に鍵オブジェクトを設ける。 2.11.1. 鍵オブジェクト 鍵オブジェクトは公開鍵、秘密鍵、共通鍵等の鍵を表わす。 関数名 ICAKeyObjectCreate ICAKeyObjectDestroy ICAKeyObjectSetKeyFromPKCS11 概要 鍵オブジェクトの生成 鍵オブジェクトの破棄 鍵オブジェクトに鍵情報を設定 117 2.11.2. 署名や親展解除で使用する為の秘密鍵の鍵オブジェクト生成と設定 1 「2.6.3公開鍵暗号アルゴリズムの秘密鍵を管理(取得) 」の手順で鍵情報を取得する。 2 鍵オブジェクトを生成 ICAKeyObjectCreate 3 鍵オブジェクトに鍵情報を設定 ICAKeyObjectSetKeyFromPKCS11 2.11.3. 署名検証や親展で使用する為の公開鍵の鍵オブジェクトの生成と設定 公開鍵の鍵オブジェクトは証明書オブジェクトより「ICACertObjectGetPubkeyObject()」を使い 取得する。証明書オブジ ェ クトに関しては「2.7.9証明書項目取得」を参照の事 。 なお、 「ICACertObjectGetPubkeyObject()」で取得した鍵オブジェクトの解放はアプリケーションが 「ICAKeyObjctDestroy」を呼び出し行う事。 2.11.4. メモリ上の秘密鍵、公開鍵の鍵オブジェクト生成と設定 1 鍵オブジェクトを生成 ICAKeyObjectCreate 2 「3APP 側 API で使用する型定義」を参照し、鍵オブジェクトに値を設定する。 118 ICAKeyObjectCreate () 鍵オブジェクトの生成 【機能】 鍵オブジェクトの生成を行う。 【形式】 ICAKeyObjectHandle ICAKeyObjectCreate ( ICAErrorCode *pErr ) 【引数】 pErr: 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :鍵オブジェクトハンドル(0 以外) 異常終了 :0 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 119 ICAKeyObjectDestroy () 鍵オブジェクトの破棄 【機能】 鍵オブジェクトの破棄を行う。 【形式】 ICAReturnCode ICAKeyObjectDestroy ( ICAKeyObjectHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 鍵オブジェクトハンドル(IN) 破壊する鍵オブジェクトハンドルを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 120 ICAKeyObjectSetKeyFromPKCS11 () 鍵情報の設定 【機能】 鍵オブジェクトに鍵管理機能または証明書管理機能の鍵情報を設定する。 【形式】 ICAReturnCode ICAKeyObjectSetKeyFromPKCS11( ICAKeyObjectHandle hObj, CK_FUNCTION_LIST_PTR pFunctionList, CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, ICAErrorCode *pErr ) 【引数】 hObj: pFunctionList: hSession: hObject: pErr: 鍵オブジェクトハンドル(IN) 鍵オブジェクトハンドルを指定する。 鍵管理機能または証明書管理機能の関数リスト(IN) 鍵管理機能または証明書管理機能の関数リストを指定する。 鍵管理機能または証明書管理機能のセッションハンドル(IN) 鍵管理機能または証明書管理機能のセッションハンドルを指定 する。 鍵管理機能または証明書管理機能の鍵オブジェクト(IN) 鍵管理機能または証明書管理機能の鍵オブジェクトを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 121 2.12. 名前オブジェクト 名前オブジェクトは、証明書の発行者や所有者を識別する名前情報をあらわし、名前情報を扱う機能を提 供する。 名前オブジェクトに提供されている関数を以下の表に示します。 名前オブジェクトの関数一覧 関数名 ICANameObjectCreate ICANameObjectDestroy ICANameObjectGetDNString ICANameObjectSetDNString ICANameObjectGetPduString ICANameObjectSetPduString 機能 オブジェクトの生成 オブジェクトの破棄 DN 文字列の取得 DN 文字列の設定 名前情報の交換形式データ文字列の取得 名前情報の交換形式データ文字列の設定 122 ICANameObjectCreate () オブジェクト生成 【機能】 名前オブジェクトを生成する。 【形式】 ICANameObject * ICANameObjectCreate( ICAErrorCode *pErr ) 【引数】 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICANameObject をさすポインタ(0 以外) 異常終了 : 0 【補足】 本関数を使用して生成した名前オブジェクトは、使用後に必ず ICANameObjectDestroy()を用いて破棄する必要がある。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 123 ICANameObjectDestroy () オブジェクトの破棄 【機能】 名前オブジェクトを破棄する。 【形式】 ICAReturnCode ICANameObjectDestroy( ICANameObject *pObj, ICAErrorCode *pErr ) 【引数】 pObj pErr 名前オブジェクト(IN) 名前オブジェクトを指定する。 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 ICANameObjectCreate()で生成した名前オブジェクトは、使用後に本関数を用いて破棄 する必要がある。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_NAME_OBJECT 名前オブジェクトが不正 ICAE_MEMORY_FREE メモリの解放に失敗 124 ICANameObjectGetDNString () DN 文字列の取得 【機能】 名前オブジェクトから DN 文字列を取得します。 【形式】 ICAReturnCode ICANameObjectGetDNString( ICANameObject *pObj, Char **ppszDNString, ICAErrorCode *pErr ) 【引数】 pObj 名前オブジェクト(IN) 名前オブジェクトを指定する。 ppszDNString DN 文字列の格納領域(OUT) DN 文字列が返される。 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 ppszDNString には、名前オブジェクトが内部に保持する Char 型データへのポインタ が返される。したがって、ppszDNString に返された値を修正してはならない。また、 名前オブジェクトを破棄した後、名前オブジェクトから取得した値にはアクセスでき ない。 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_NAME_OBJECT ICAE_INVALID_DNSTRING ICAE_CALL_SEQUENCE ICAE_FAILURE_MALLOC ICAE_MEMORY_FREE 125 意味 ICAName オブジェクトが不正 DN 文字列の格納領域が不正 メソッドの呼び出し順序が不正 メモリの確保に失敗 メモリの解放に失敗 ICANameObjectSetDNString() DN 文字列の設定 【機能】 DN 文字列を設定します。 【形式】 ICAReturnCode ICANameObjectSetDNString( ICANameObject *pObj, Char *pszDNString, ICAErrorCode *pErr ) 【引数】 pObj 名前オブジェクト(IN) 名前オブジェクトを指定する。 pszDNString DN 文字列(IN) DN 文字列を設定する。 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_INVALID_NAME_OBJECT ICAE_INVALID_DNSTRING ICAE_FAILURE_MALLOC 126 意味 名前オブジェクトが不正 DN 文字列指定が不正 メモリの確保に失敗 ICANameObjectGetPduString () 名前情報の交換形式データ文字列の取得 【機能】 名前情報の交換形式データ文字列を取得します。 【形式】 ICAReturnCode ICANameObjectGetPduString( ICANameObject *pObj, Char **ppszPduString, ICAErrorCode *pErr ) 【引数】 pObj 名前オブジェクト(IN) 名前オブジェクトを指定する。 ppszPduString 交換形式データ文字列の格納領域(OUT) 名前情報の交換形式データ文字列が返される。 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 交換形式データ文字列は交換形式データを 16 進文字列で表わしたものである。 例)303e310b3009060355040 ppszPduString には、名前オブジェクトが内部に保持する Char 型データへのポインタ が返される。したがって、ppszPduString に返された値を修正してはならない。また、 名前オブジェクトを破棄した後、名前オブジェクトから取得した値にはアクセスでき ない。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_NAME_OBJECT 名前オブジェクトが不正 ICAE_INVALID_PDUSTRING DN 文字列指定が不正 ICAE_MEMORY_ALLOC 交換形式データ文字列の格納領域が不正 ICAE_CALL_SEQUENCE メソッドの呼び出し順序が不正 ICAE_MEMORY_FREE メモリの解放に失敗 127 ICANameObjectSetPduString () 名前情報の交換形式データ文字列の設定 【機能】 名前情報の交換形式データ文字列を設定します。 【形式】 ICAReturnCode ICANameObjectSetPduString( ICANameObject *pObj, Char *pszPduString, ICAErrorCode *pErr 【引数】 pObj 名前オブジェクト(IN) 名前オブジェクトを設定します。 pszPduString 交換形式データ文字列(IN) 名前情報の交換形式データ文字列を設定します。 pErr 異常終了時のエラーコード(OUT) エラーコードが返される。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 交換形式データ文字列は交換形式データを 16 進文字列で表わしたものである。 例)303e310b3009060355040 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_NAME_OBJEC 名前オブジェクトが不正 ICAE_INVALID_PDUSTRING 交換形式データ文字列が不正 ICAE_MEMORY_ALLOC 交換形式データ文字列の格納領域が不正 ICAE_MEMORY_FREE メモリの解放に失敗 128 3. APP 側 API で使用する型定義 ICASignatureObjectCSP 【機能】 署名生成 CSP の関数アドレスを表す。 【形式】 typedef struct { tICASignatureCSPInit tICASignatureCSPSetAlgorithm tICASignatureCSPSetKey tICASignatureCSPSetMessage tICASignatureCSPAddMessage tICASignatureCSPGetSignature tICASignatureCSPDestroy } ICASignatureObjectCSP; ICASignatureCSPInit; ICASignatureCSPSetAlgorithm; ICASignatureCSPSetKey; ICASignatureCSPSetMessage; ICASignatureCSPAddMessage; ICASignatureCSPGetSignature; ICASignatureCSPDestroy; 【メンバー】 ICASignatureCSPInit: ICASignatureCSPSetAlgorithm: ICASignatureCSPSetKey: ICASignatureCSPSetMessage: ICASignatureCSPAddMessage: 署名生成 CSP の初期化関数 署名生成 CSP の署名アルゴリズム設定関数 署名生成 CSP の秘密鍵設定関数 署名生成 CSP の署名対象データ設定関数 署名生成 CSP の署名対象データ追加設定関 数 署名生成 CSP の署名データ取得関数 署名生成 CSP の解放関数 ICASignatureCSPGetSignature: ICASignatureCSPDestroy: 129 ICAVerificationObjectCSP 【機能】 署名検証 CSP の関数アドレスを表す。 【形式】 typedef struct { tICAVerificationCSPInit tICAVerificationCSPSetAlgorithm tICAVerificationCSPSetKey tICAVerificationCSPSetMessage tICAVerificationCSPAddMessage tICAVerificationCSPSetSignature tICAVerificationCSPVerifySignature tICAVerificationCSPDestroy } ICAVerificationObjectCSP; ICAVerificationCSPInit; ICAVerificationCSPSetAlgorithm; ICAVerificationCSPSetKey; ICAVerificationCSPSetMessage; ICAVerificationCSPAddMessage; ICAVerificationCSPSetSignature; ICAVerificationCSPVerifySignature; ICAVerificationCSPDestroy; 【メンバー】 ICAVerificationCSPInit: ICAVerificationCSPSetAlgorithm: ICAVerificationCSPSetKey: ICAVerificationCSPSetMessage: ICAVerificationCSPAddMessage: ICAVerificationCSPSetSignature: ICAVerificationCSPVerifySignature: ICAVerificationCSPDestroy: 130 署名検証 CSP の初期化関数 署名検証 CSP のアルゴリズム設定関数 署名検証 CSP の署名検証用公開鍵設定関数 署名検証 CSP の署名検証対象データ設定関 数 署名検証 CSP の署名検証対象データ追加設 定関数 署名検証 CSP の署名データ設定関数 署名検証 CSP の署名検証結果取得関数 署名検証 CSP の解放関数 ICAEncryptionObjectCSP 【機能】 親展 CSP の関数アドレスを表す。 【形式】 typedef struct { tICAEncryptionCSPInit ICAEncryptionCSPInit; tICAEncryptionCSPGenerateKey ICAEncryptionCSPGenerateKey; tICAEncryptionCSPSetKeyTransferAlgorithm ICAEncryptionCSPSetKeyTransferAlgorithm; tICAEncryptionCSPExportKey ICAEncryptionCSPExportKey; tICAEncryptionCSPSetAlgorithm ICAEncryptionCSPSetAlgorithm; tICAEncryptionCSPSetData ICAEncryptionCSPSetData; tICAEncryptionCSPAddData ICAEncryptionCSPAddData; tICAEncryptionCSPGetEncryptedData ICAEncryptionCSPGetEncryptedData; tICAEncryptionCSPGetEncryptedDataFinal ICAEncryptionCSPGetEncryptedDataFinal; tICAEncryptionCSPDestroy ICAEncryptionCSPDestroy; } ICAEncryptionObjectCSP; 【メンバー】 ICAEncryptionCSPInit: 親展 CSP の初期化関数 ICAEncryptionCSPGenerateKey: 親展 CSP の共通鍵生成関数 ICAEncryptionCSPSetKeyTransferAlgorithm:親展 CSP の鍵配送アルゴリズムの設定関数 ICAEncryptionCSPExportKey: 親展 CSP の暗号化した共通鍵の取得関数 ICAEncryptionCSPSetAlgorithm: 親展 CSP の共通鍵暗号アルゴリズムの設定 関数 ICAEncryptionCSPSetData: 親展 CSP の親展対象データ設定関数 ICAEncryptionCSPAddData: 親展 CSP の親展対象データ追加設定関数 ICAEncryptionCSPGetEncryptedData: 親展 CSP の暗号文取得関数 ICAEncryptionCSPGetEncryptedDataFinal: 親展 CSP の最後の暗号文取得関数 ICAEncryptionCSPDestroy: 親展 CSP の解放関数 131 ICADecryptionObjectCSP 【機能】 親展解除 CSP の関数アドレスを表す。 【形式】 typedef struct { tICADecryptionCSPInit ICADecryptionCSPInit; tICADecryptionCSPSetKeyTransferAlgorithm ICADecryptionCSPSetKeyTransferAlgorithm; tICADecryptionCSPImportKey ICADecryptionCSPImportKey; tICADecryptionCSPSetAlgorithm ICADecryptionCSPSetAlgorithm; tICADecryptionCSPSetEncryptedData ICADecryptionCSPSetEncryptedData; tICADecryptionCSPAddEncryptedData ICADecryptionCSPAddEncryptedData; tICADecryptionCSPGetData ICADecryptionCSPGetData; tICADecryptionCSPGetDataFinal ICADecryptionCSPGetDataFinal; tICADecryptionCSPDestroy ICADecryptionCSPDestroy; } ICADecryptionObjectCSP; 【メンバー】 ICADecryptionCSPInit: 親展解除 CSP の初期化関数 ICADecryptionCSPSetKeyTransferAlgorithm:親展解除 CSP の鍵配送アルゴリズムの設定 関数 ICADecryptionCSPImportKey: 親展解除 CSP の暗号化した共通鍵の設定 関数 ICADecryptionCSPSetAlgorithm: 親展解除 CSP の共通鍵暗号アルゴリズムの 設定関数 ICADecryptionCSPSetEncryptedData: 親展解除 CSP の暗号化されたデータの設定 関数 ICADecryptionCSPAddEncryptedData: 新展解除 CSP の暗号化されたデータの追加 設定関数 ICADecryptionCSPGetData: 親展解除 CSP の復号データ取得関数 ICADecryptionCSPGetDataFinal: 親展解除 CSP の最後の復号データ取得関数 ICADecryptionCSPDestroy: 親展解除 CSP の解放関数 132 ICACertificateValidationObjectCSP 【機能】 証明書検証 CSP の関数アドレスを表す。 【形式】 typedef struct { tICACertValidationCSPInit ICACertificateValidationCSPInit; tICACertValidationCSPSetServerInfo ICACertificateValidationCSPSetServerInfo; tICACertValidationCSPAttachEnv ICACertificateValidationCSPAttachEnv; tICACertValidationCSPDetachEnv ICACertificateValidationCSPDetachEnv; tICACertValidationCSPValidateCertificate ICACertificateValidationCSPValidateCertificate; tICACertValidationCSPDestroy ICACertificateValidationCSPDestroy; CK_FUNCTION_LIST_PTR pCertManagementFunctionList; CK_FUNCTION_LIST_PTR pKeyManagementFunctionList; ICACRLManagementObjectCSP CRLManagementCSP; } ICACertificateValidationObjectCSP; 【メンバー】 ICACertificateValidationCSPInit: 証明書検証 CSP の初期化関数 ICACertificateValidationCSPSetServerInfo: 証明書検証に使用するサーバ情報の設定関 数 ICACertificateValidationCSPAttachEnv: 証明書検証環境に対する認証関数 ICACertificateValidationCSPDetachEnv: 証明書検証環境に対する認証の解除関数 ICACertificateValidationCSPValidateCertificate: 証明書の検証関数 ICACertificateValidationCSPDestroy: 証明書検証 SP オブジェクトの破棄関数 pCertManagementFunctionList: 証明書検証 CSP が内部で呼び出す証明書管 理 CSP の関数リスト pKeyManagementFunctionList: 証明書検証 CSP が内部で呼び出す鍵管理 CSP の関数リスト CRLManagementCSP: 証明書検証 CSP が内部で呼び出す失効情報 管理 CSP の関数リスト 133 ICACRLManagementObjectCSP 【機能】 失効情報管理 CSP の関数アドレスを表す。 【形式】 typedef struct { tICACRLManagementCSPInit tICACRLManagementCSPSetCRL tICACRLManagementCSPGetCRLList tICACRLManagementCSPDeleteCRL tICACRLManagementCSPDeleteAllCRL tICACRLManagementCSPDestroy } ICACRLManagementObjectCSP; ICACRLManagementCSPInit; ICACRLManagementCSPSetCRL; ICACRLManagementCSPGetCRLList; ICACRLManagementCSPDeleteCRL; ICACRLManagementCSPDeleteAllCRL; ICACRLManagementCSPDestroy; 【メンバー】 ICACRLManagementCSPInit: ICACRLManagementCSPSetCRL: ICACRLManagementCSPGetCRLList: ICACRLManagementCSPDeleteCRL: ICACRLManagementCSPDeleteAllCRL: ICACRLManagementCSPDestroy: 134 失効情報管理 CSP の初期化関数 失効情報管理 CSP の失効情報保管関数 失効情報管理 CSP の失効情報取得関数 失効情報管理 CSP の失効情報削除関数 失効情報管理 CSP の失効情報全削除関数 失効情報管理 CSP の解放関数 ICAErrorCode 【機能】 エラーコードを表す。 【形式】 typedef UInt32 ICAErrorCode; ICAReturenCode 【機能】 関数の戻り値を表す。 【形式】 typedef UInt32 ICAReturnCode; 【補足】 正常に処理が終了した場合は ICAR_SUCCESS が戻り値に設定される。 それ以外の場合は ICAR_FAILURE が戻り値に設定される。 ICAMessage 【機能】 署名対象データや親展対象データ等の平文を表す。 【形式】 typedef struct { Int32 Length; UInt8 *pData; } ICAMessage; 【メンバー】 Length: pData: オクテット列の長さ(バイト長) オクテット列へのポインタ 135 ICASignature 【機能】 署名データを表す。 【形式】 typedef struct { Int32 Length; UInt8 *pData; } ICASignature; 【メンバー】 pData: Length: 署名データへのポインタ 署名データの長さ(バイト長) ICAEncryptedMessage 【機能】 暗号文を表す。 【形式】 typedef struct { Int32 Length; UInt8 *pData; } ICAEncryptedMessage; 【メンバー】 pData: Length: 暗号文へのポインタ 暗号文の長さ(バイト長) ICAEncryptedKey 【機能】 暗号化された共通鍵を表す。 【形式】 typedef struct { Int32 Length; UInt8 *pData; } ICAEncryptedKey; 【メンバー】 pData: Length: 暗号化された共通鍵へのポインタ 暗号化された共通鍵の長さ(バイト長) 136 ICAEncodedData 【機能】 各種のデータを ASN.1 の BER/DER 形式で符号化したオクテット列を格納する構造体を 表す。 【形式】 typedef struct { Int32 Length; UInt8 *pData; } ICAEncodedData; 【メンバー】 Length: pData: オクテット列の長さ(バイト長) オクテット列へのポインタ ICAPINData 【機能】 パスワードを表す。 【形式】 typedef struct { Int32 Length; UInt8 *pData; } ICAPINData; 【メンバー】 Length: pData: パスワードの長さ(バイト長) パスワードへのポインタ 137 ICACertificateData 【機能】 証明書を BER 符号化したデータを表す。 【形式】 typedef ICAEncodedData ICACertificateData; ICACRLData 【機能】 CRL を BER 符号化したデータを表す。 【形式】 typedef ICAEncodedData ICACRLData; 【メンバー】 ICAAlgorithmId 【機能】 アルゴリズムを指定するために、AlgorithmIdentifier 形式の情報を DER 符号化したデー タを表す。 【形式】 typedef ICAEncodedData ICAAlgorithmId; 138 ICAKeyObject 【機能】 鍵オブジェクトのデータを表す構造体を表す。 【形式】 typedef struct { UInt32 KeyType; void *pKeyData; } ICAKeyObject; 【メンバー】 KeyType: pKeyData: 鍵のタイプを表す。 鍵のデータを指すポインタ。実際の内容は鍵のタイプに依存する。 【補足】 現在定義されている鍵のタイプは以下の通り。 値 内容 ICAKRSAPublic RSA 公開鍵を表す。 ICAKRSAPrivate RSA 秘密鍵を表す。 ICAKRSAKeyPair RSA 鍵対を表す。 ICAKRSAPrivateT 鍵管理媒体内の RSA 秘密鍵を表す。 ICAKECPublic 楕円暗号の公開鍵を表す。 ICAKECPrivate 楕円暗号の秘密鍵を表す。 ICAKECKeyPair 楕円暗号の鍵対を表す。 ICAKECPrivateT 鍵管理媒体内の楕円暗号の秘密鍵を表す。 ICAKeyObjectHandle 【機能】 鍵オブジェクトハンドルを表す。 【形式】 typedef ICAKeyObject *ICAKeyObjectHandle; 139 形式データ _ICAKeyObjectRSAPublicKey _ICAKeyObjectRSAPrivateKey _ICAKeyObjectRSAKeyPair _ICAKeyObjectOnPKCS11 _ICAKeyObjectECPublicKey _ICAKeyObjectECPrivateKey _ICAKeyObjectECKeyPair _ICAKeyObjectOnPKCS11 _ICAKeyObjectRSAPublicKey 【機能】 RSA の公開鍵(ASN.1 BER 符号形式)を表す。 【形式】 typedef ICAEncodedData _ICAKeyObjectRSAPublicKey; _ICAKeyObjectRSAPrivateKey 【機能】 RSA の秘密鍵(ASN.1 BER 符号形式)を表す。 【形式】 typedef ICAEncodedData _ICAKeyObjectRSAPrivateKey; _ICAKeyObjectRSAKeyPair 【機能】 RSA の鍵対を表す。 【形式】 typedef struct { _ICAKeyObjectRSAPublicKey PublicKey; _ICAKeyObjectRSAPrivateKey PrivateKey; } _ICAKeyObjectRSAKeyPair; 【メンバー】 Publickey: RSA の公開鍵(ASN.1 BER 符号形式)を表す。 PrivateKey: RSA の秘密鍵(ASN.1 BER 符号形式)を表す。 140 _ICAKeyObjectECPublicKey 【機能】 楕円暗号の楕円曲線ドメインパラメータを表す。 【形式】 ICAEncodedData ICAECParams; ICAInteger 【機能】 暗号の演算に用いられる整数を表す。 【形式】 typedef struct { Int32 Length; UInt8 *pData; } ICAInteger; 【メンバー】 pData: Length: 整数データ 整数データの長さ (バイト) 【補足】 pData には整数値を上位桁が先頭になるように符号化したデータを格納します。長さが k バイトであるデータ D1 ,..., Dk と整数 x は次の条件を満たします。 k x = å 2 8( k -i ) Di i =1 ICAECPoint 【機能】 楕円曲線上の点を表す。 【形式】 typedef struct { ICAInteger x; ICAInteger y; } ICAECPoint; 【メンバー】 x: y: 楕円曲線 Q のx座標 xQ 楕円曲線 Q のy座標 yQ 141 _ICAKeyObjectECPrivateKey 【機能】 楕円暗号の秘密鍵を表す構造体を表す。 【形式】 typedef struct { ICAECParams Parameters; ICAInteger PrivateKey; } _ICAKeyObjectECPrivateKey; 【メンバー】 PrivateKey: 秘密鍵の値。 Parameters: 楕円曲線ドメインパラメータ。 _ICAKeyObjectECKeyPair 【機能】 楕円暗号の鍵対を表す構造体を表す。 【形式】 typedef struct { _ICAKeyObjectECPublicKey PublicKey; _ICAKeyObjectECPrivateKey PrivateKey; } _ICAKeyObjectECKeyPair; 【メンバー】 PublicKey: 楕円暗号の公開鍵。 PrivateKey: 楕円暗号の秘密鍵。 _ICAKeyObjectOnPKCS11 【機能】 鍵管理媒体内の鍵を表す構造体を表す。 【形式】 typedef struct { CK_FUNCTION_LIST_PTR pFunctionList; CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hObject } _ICAKeyObjectOnPKCS11; 【メンバー】 pFunctionList: hSession: hObject: 鍵管理 CSP の関数リスト 鍵管理媒体上の鍵を検索するのに用いたセッションのハンドル 鍵管理媒体上の鍵か格納されているオブジェクトのハンドル 142 ICACertificateValidationServerInfo 【機能】 証明書検証関連サーバ情報を表す。 【形式】 typedef struct { ICACertificateValidationLDAPInfo ICACertificateValidationOCSPInfo } ICACertificateValidationServerInfo; *pLDAPInfo; *pOCSPInfo; 【メンバー】 pLDAPInfo: pOCSPInfo: 証明書検証で使用するディレクトリサーバ情報 証明書検証で使用する OCSP サーバ情報 【補足】 使用しないメンバーには NULL を設定する。 143 ICAServerInfo 【機能】 サーバ情報を表す。 【形式】 typedef struct { UInt8 UInt32 UInt32 } ICAServerInfo; *pHost; Port; TimeOut; 【メンバー】 pHost: Port: TimeOut: サーバのホスト名 サーバアクセス時のポート番号 サーバとの通信の最大応答待ち時間(秒) 144 ICACertificateList 【機能】 証明書のリスト情報を表す。 【形式】 typedef struct { UInt32 ICACertificateData } ICACertificateList; Length; *pCertificate; 【メンバー】 Length: pCertificate: 証明書のリスト数 証明書のリスト情報 145 ICACertificateValidationCondition 【機能】 証明書の検索・検証に関連する条件を表す。 【形式】 typedef struct { ICACertificatePolicyIdList Bool32 Bool32 Bool32 UInt32 } ICACertificateValidationCondition; *pCertPolicyIdList; bExplicitCertPolicy; bInhibitPolicyMapping; bInhibitAnyPolicy; MaxPathLength; 【メンバー】 pCertPolicyIdList: bExplicitCertPolicy: bInhibitPolicyMapping: bInhibitAnyPolicy: MaxPathLength: 証明書経路において許容するポリシーのリスト 証明書中に明示的なポリシーの設定を必須とするかどうかを指 定する。 必須: ICAB_TRUE 必須ではない: ICAB_FALSE 証明書経路本体においてポリシーマッピングを禁止するかどう かを指定する。 禁止する: ICAB_TRUE 禁止しない: ICAB_FALSE 証明書中の AnyPolicy の設定を禁止するかどうかを指定する。 禁止する: ICAB_TRUE 禁止しない: ICAB_FALSE 1 つの証明書経路における許容する最大長 146 ICACertificatePolicyIdList 【機能】 ポリシーID をリストで表す。 【形式】 typedef struct { UInt32 Length; ICAObjectId *pObjId; } ICACertificatePolicyIdList; 【メンバー】 Length: pObjId: ポリシーID のリスト数 ポリシーID のリスト情報 147 ICAObjectId 【機能】 オブジェクト識別子をリストで表す。 【形式】 typedef struct { UInt32 Int32 } ICAObjectId; Length; *pId; 【メンバー】 Length: pId: オブジェクト識別子の要素数 オブジェクト識別子へのポインタ 【補足】 例:オブジェクト識別子:{ 1 2 3 4}を表す。 ICAObjectId Int32 objid; oid[4]; oid[[0] = 1; oid[1] = 2; oid[2] = 3; oid[3] = 4; objId.pId = oid; objId.Length = 4; 148 ICACertificateValidationResult 【機能】 証明書検証の結果として作成された証明書経路を表す。リストの先頭にトラストアンカ ーの証明書が設定され、次の要素以降は順次下位の証明書が設定される。 【形式】 typedef ICACertificateList ICACertificateValidationResult; 149 ICACRLList 【機能】 CRL のリストを表す。 【形式】 typedef struct { UInt32 ICACRLData } ICACRLList; Length; *pCRL; 【メンバー】 Length: pCRL: CRL リストの長さ CRL を指すポインタ 150 ICARevokedCertificate 【機能】 失効した証明書の情報を表わす。 【形式】 typedef struct { ICAInteger UInt8 } ICARevokedCertificate; *pSerial; *pRevocationDate; 【メンバー】 pSerial: 証明書のシリアル番号 pRevocationDate: 失効日時 【補足】 pRevocationDate は “YYYYMMDDHHMMSSZ” と い う 形 式 の 文 字 列 で 表 現 す る 。 (e.g. “20020222202002Z” (2002 年 2 月 22 日 20 時 20 分 2 秒)) 151 4. Crypto-API で使用する PKCS #11 のインタフェース 鍵管理機能、証明書管理機能の一部(トラストアンカーの管理)、鍵対生成機能は、業界標準とし て普及している PKCS#11(Version2.01 以降)のインタフェースのサブセットを利用して構成され ている。本章では、これらの機能が使用する関数のインタフェースと引数に指定しなければなら ないデータについて説明する。データの型や引数に指定されるマクロ定数の意味は PKCS #11 を 参照の事。引数の説明で(Mandatory)と記されているデータは、本 API に準拠するライブラリに おいて、それぞれの機能を実現するために、最低限指定できることが保証されているデータであ る。それ以外のデータや、実装されていない事があると補足欄に記載されている関数を使用した 場合、利便性や機能は向上するが、ライブラリ間での互換性を失う可能性がある為、利用する際 は注意が必要となる。 152 C_Initialize() ライブラリの初期化 【機能】 PKCS #11 ライブラリを初期化する。 【形式】 CK_RV C_Initialize( CK_VOID_PTR ) pInitArgs 【引数】 pInitArgs: NULL_PTR を指定する。(Mandatory) 【補足】 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 153 C_Finalize() ライブラリの使用終了 【機能】 PKCS #11 ライブラリの使用を終了する。 【形式】 CK_RV C_Finalize( CK_VOID_PTR ) pReserved 【引数】 pReserved: NULL_PTR を指定する。(Mandatory) 【補足】 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 154 C_GetInfo() ライブラリ情報の取得 【機能】 PKCS #11 ライブラリの情報を取得する。 【形式】 CK_RV C_GetInfo( CK_INFO_PTR ) pInfo 【引数】 pInfo: 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 155 C_GetFunctionList() 関数リストの取得 【機能】 PKCS #11 ライブラリの関数リストを取得する。 【形式】 CK_RV C_GetFunctionList( CK_FUNCTION_LIST_PTR_PTR ) ppFunctionList 【引数】 ppFunctionList: 取得される関数リストへのポインタのポインタを指定する。 (Mandatory) 【補足】 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 156 C_GetSlotList() スロットリストの取得 【機能】 スロットのリストを取得する。 【形式】 CK_RV C_GetSlotList( CK_BBOOL CK_SLOT_ID_PTR CK_ULONG_PTR ) tokenPresent, pSlotList, pulCount 【引数】 tokenPresent: pSlotList: pulCount: TRUE または FALSE を指定する。(Mandatory) NULL_PTR またはリストを格納する為の領域へのポインタを指定 する。(Mandatory) 取得しようとする項目数や取得された項目数を格納する為の領 域へのポインタを指定する。(Mandatory) 【補足】 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 157 C_GetSlotInfo() スロット情報の取得 【機能】 スロットの情報を取得する。 【形式】 CK_RV C_GetSlotInfo( CK_SLOT_ID CK_SLOT_INFO_PTR ) slotID, pInfo 【引数】 slotID: pInfo: 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 158 C_GetTokenInfo() トークン情報の取得 【機能】 トークンの情報を取得する。 【形式】 CK_RV C_GetTokenInfo( CK_SLOT_ID CK_TOKEN_INFO_PTR ) slotID, pInfo 【引数】 slotID: pInfo: 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 159 C_WaitForSlotEvent() スロットイベント終了待機 【機能】 スロットイベントが終了するまで待機する。 【形式】 CK_RV C_WaitForSlotEvent( CK_FLAGS CK_SLOT_ID_PTR CK_VOID_PTR ) flags, pSlot, pReserved 【引数】 flags: pSlot: pReserved: 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 160 C_GetMechanismList() メカニズムリストの取得 【機能】 トークンがサポートしているメカニズムの種類を取得する。 【形式】 CK_RV C_GetMechanismList( CK_SLOT_ID CK_MECHANISM_TYPE_PTR CK_ULONG_PTR ) slotID, pMechanismList, pulCount 【引数】 slotID: pMechanismList: pulCount: 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 161 C_GetMechanismInfo() メカニズム情報の取得 【機能】 トークンでサポートされているメカニズムの情報を取得する。 【形式】 CK_RV C_GetMechanismInfo( CK_SLOT_ID CK_MECHANISM_TYPE CK_MECHANISM_INFO_PTR ) slotID, type, pInfo 【引数】 slotID: type: pInfo: 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 162 C_InitToken() トークンの初期化 【機能】 トークンを初期化する。 【形式】 CK_RV C_InitToken( CK_SLOT_ID CK_CHAR_PTR CK_ULONG CK_CHAR_PTR ) slotID, pPin, ulPinLen, pLabel 【引数】 slotID: pPin: ulPinLen: pLabel: 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 163 C_InitPIN() ユーザパスワードの初期化 【機能】 ユーザのパスワードを初期化する。 【形式】 CK_RV C_InitPIN( CK_SESSION_HANDLE CK_CHAR_PTR CK_ULONG ) hSession, pPin, ulPinLen 【引数】 hSession: pPin: ulPinLen: 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 164 C_SetPIN() ユーザパスワードの変更 【機能】 現在ログインしているユーザのパスワードを変更する。 【形式】 CK_RV C_SetPIN( CK_SESSION_HANDLE CK_CHAR_PTR CK_ULONG CK_CHAR_PTR CK_ULONG ) hSession, pOldPin, ulOldLen, pNewPin, ulNewLen 【引数】 hSession: pOldPin: ulOldLen: pNewPin: ulNewLen: 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 165 C_OpenSession() セッションのオープン 【機能】 セッションをオープンする。 【形式】 CK_RV C_OpenSession( CK_SLOT_ID CK_FLAGS CK_VOID_PTR CK_NOTIFY CK_SESSION_HANDLE_PTR ) slotID, flags, pApplication, Notify, phSession 【引数】 slotID: flags: pApplication: Notify: phSession: セッションをオープンしようとするトークンが存在するスロッ トの ID を指定する。(Mandatory) ‘CKF_RW_SESSION│CKF_SERIAL_SESSION’ を指定する。(Mandatory) ‘CKF_SERIAL_SESSION’ を指定する。(Optional) NULL_PTR を指定する。(Mandatory) NULL_PTR を指定する。(Mandatory) セッションハンドルを格納する為の領域へのポインタを指定す る。(Mandatory) 【補足】 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 166 C_CloseSession() セッションのクローズ 【機能】 セッションをクローズする。 【形式】 CK_RV C_CloseSession( CK_SESSION_HANDLE ) hSession 【引数】 hSession:クローズしようとするセッションのハンドルを指定する。(Mandatory) 【補足】 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 167 C_CloseAllSessions() 全セッションのクローズ 【機能】 すべてのセッションをクローズする。 【形式】 CK_RV C_CloseAllSessions( CK_SLOT_ID ) slotID 【引数】 slotID: 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 168 C_GetSessionInfo() セッション情報の取得 【機能】 セッションの情報を取得する。 【形式】 CK_RV C_GetSessionInfo( CK_SESSION_HANDLE CK_SESSION_INFO_PTR ) hSession, pInfo 【引数】 hSession: pInfo: 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 169 C_GetOperationState() 暗号演算の状態取得 【機能】 セッションの暗号演算の状態を取得する。 【形式】 CK_RV C_GetOperationState( CK_SESSION_HANDLE CK_BYTE_PTR CK_ULONG_PTR ) hSession, pOperationState, pulOperationStateLen 【引数】 hSession: 指定すべき必須の値はない。 pOperationState: 指定すべき必須の値はない。 pulOperationStateLen: 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 170 C_SetOperationState() 暗号演算の状態設定 【機能】 暗号演算の状態をセッションに設定する。 【形式】 CK_RV C_SetOperationState( CK_SESSION_HANDLE CK_BYTE_PTR CK_ULONG CK_OBJECT_HANDLE CK_OBJECT_HANDLE ) hSession, pOperationState, ulOperationStateLen, hEncryptionKey, hAuthenticationKey 【引数】 hSession: pOperationState: ulOperationStateLen: hEncryptionKey: hAuthenticationKey: 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 171 C_Login() ログイン 【機能】 トークンにログインする。 【形式】 CK_RV C_Login( CK_SESSION_HANDLE CK_USER_TYPE CK_CHAR_PTR CK_ULONG ) hSessioin, userType, pPin, ulPinLen 【引数】 hSession: userType: pPin: ulPinLen: ログインしようとするセッションのハンドルを指定する。(Mandatory) CKU_USER を指定する。(Mandatory) ログインする為のパスワードが格納されている領域へのポインタを指定す る。(Mandatory) ログインする為のパスワードの長さを指定する。(Mandatory) 【補足】 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 172 C_Logout() ログアウト 【機能】 トークンからログアウトする。 【形式】 CK_RV C_Logout( CK_SESSION_HANDLE ) hSession 【引数】 hSession: ログアウトしようとするセッションのハンドルを指定する。(Mandatory) 【補足】 本関数は、鍵管理機能、証明書管理機能、鍵対生成機能の一部である。 173 C_CreateObject() オブジェクトの生成 【機能】 オブジェクトを生成する。 【形式】 CK_RV C_CreateObject( CK_SESSION_HANDLE hSession, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount, CK_OBJECT_HANDLE_PTR phObject ) 【引数】 hSession: pTemplate: ulCount: phObject: オブジェクトを生成しようとするセッションのハンドルを指定する。 (Mandatory) オブジェクトの属性を指定する。(Mandatory) 属性の項目数を指定する。(Mandatory) 生成されたオブジェクトのハンドルを格納する領域へのポインタを指定す る。(Mandatory) 【補足】 pTemplate に指定する種別は以下の通り。 種別 値 CKA_CLASS CKO_CERTIFICATE CKA_TOKEN TRUE CKA_PRIVATE TRUE CKA_LABEL ラベル CKA_CERTIFICATE_TYPE CKC_X_509 CKA_SUBJECT DER 符号化された subject name CKA_VALUE BER 符号化された証明書 CKA_ID 公開鍵対の key identifier CKA_ISSUER DER 符号化された issuer name CKA_SERIAL_NUMBER DER 符号化された serial number 本関数は証明書管理機能の一部である。 174 指定区分 Mandatory Mandatory Mandatory Optional Mandatory Mandatory Mandatory Optional Optional Optional C_CopyObject() オブジェクトのコピー 【機能】 オブジェクトをコピーする。 【形式】 CK_RV C_CopyObject( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount, CK_OBJECT_HANDLE_PTR phNewObject ) 【引数】 hSession: hObject: pTemplate: ulCount: phNewObject: 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は証明書管理機能の一部である。 175 C_DestroyObject() オブジェクトの破棄 【機能】 オブジェクトを破棄する。 【形式】 CK_RV C_DestroyObject( CK_SESSION_HANDLE CK_OBJECT_HANDLE ) hSession, hObject 【引数】 hSession: オ ブ ジ ェ ク ト を 破 棄 し よ う と す る セ ッ シ ョ ン の ハ ン ド ル を 指 定 す る 。 (Mandatory) hObject: 破棄しようとするオブジェクトのハンドルを指定する。(Mandatory) 【補足】 本関数は証明書管理機能の一部である。 176 C_GetObjectSize() オブジェクトサイズの取得 【機能】 オブジェクトの大きさを取得する。 【形式】 CK_RV C_GetObjectSize( CK_SESSION_HANDLE CK_OBJECT_HANDLE CK_ULONG_PTR ) hSession, hObject, pulSize 【引数】 hSession: hObject: pulSize: 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は証明書管理機能の一部である。 177 C_GetAttributeValue() オブジェクト属性の取得 【機能】 オブジェクトの属性を取得する。 【形式】 CK_RV C_GetAttributeValue( CK_SESSION_HANDLE CK_OBJECT_HANDLE CK_ATTRIBUTE_PTR CK_ULONG ) hSession, hObject, pTemplate, ulCount 【引数】 hSession: hObject: pTemplate: ulCount: 属性を取得しようとするセッションのハンドルを指定する。(Mandatory) 属性を取得しようとするオブジェクトのハンドルを指定する。(Mandatory) 取得しようとする属性の種別が格納されており、属性の値を格納する為の 領域へのポインタを指定する。(Mandatory) 取得しようとする属性の項目数を指定する。(Mandatory) 【補足】 pTemplate に指定する種別は以下の通り。 種別 指定区分 CKA_VALUE Mandatory 本関数は証明書管理機能の一部である。 178 C_SetAttributeValue() オブジェクト属性の設定 【機能】 オブジェクトの属性を設定する。 【形式】 CK_RV C_SetAttributeValue( CK_SESSION_HANDLE CK_OBJECT_HANDLE CK_ATTRIBUTE_PTR CK_ULONG_PTR ) hSession, hObject, pTemplate, ulCount 【引数】 hSession: hObject: pTemplate: ulCount: 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は証明書管理機能の一部である。 179 C_FindObjectsInit() オブジェクト検索の初期化 【機能】 オブジェクトの検索条件を初期化する。 【形式】 CK_RV C_FindObjectsInit( CK_SESSION_HANDLE CK_ATTRIBUTE_PTR CK_ULONG ) hSession, pTemplate, ulCount 【引数】 hSession: pTemplate: ulCount: 検索を行なうセッションのハンドルを指定する。(Mandatory) 検索を行なうキーとして使用する属性を指定する。(Mandatory) NULL_PTR を指定する。(Mandatory) 属性の項目数を指定する。(Mandatory) pTemplate に NULL_PTR を指定した場合、0 を指定する。(Mandatory) 【補足】 pTemplate に指定する種別は以下の通り。 種別 指定区分 CKA_CLASS Optional CKA_TOKEN Optional CKA_PRIVATE Optional CKA_LABEL Optional CKA_KEY_TYPE Optional (Public-Key, Private-Key) CKA_ID Optional CKA_SUBJECT Optional CKA_SENSITIVE Optional (Private-Key) CKA_EXTRACTABLE Optional (Private-Key) CKA_ALWAYS_SENSITIVE Optional (Private-Key) CKA_NEVER_EXTRACTABLE Optional (Private-Key) CKA_SIGN Optional (Private-Key) CKA_ISSUER Optional (Certificate) CKA_SERIAL_NUMBER Optional (Certificate) CKA_VALUE Optional (Certificate) CKA_MODULUS Optional (RSA Public-Key, RSA Private-Key) CKA_MODULUS_BITS Optional (RSA Public-Key) CKA_PUBLIC_EXPONENT Optional (RSA Public-Key, Private-Key) CKA_ECDSA_PARAMS Optional (ECDSA Public-Key, ECDSA Private-Key) CKA_EC_POINT Optional (ECDSA Public-Key) 本関数は、鍵管理機能、証明書管理機能の一部である。 180 C_FindObjects() オブジェクト検索 【機能】 オブジェクトの検索を継続する。 【形式】 CK_RV C_FindObjects( CK_SESSION_HANDLE CK_OBJECT_HANDLE_PTR CK_ULONG CK_ULONG_PTR ) hSession, phObject, ulMaxObjectCount, pulObjectCount 【引数】 hSession: phObject: ulMaxObjectCount: pulObjectCount: オブジェクトの検索を行なうセッションのハンドルを指定する。 (Mandatory) オブジェクトを格納する為の領域へのポインタを指定する。 (Mandatory) phObject に格納で きるオブジ ェクトの 最大数を 指定する。 (Mandatory) 検索されたオブジェクトの数を格納する為の領域へのポインタ を指定する。(Mandatory) 【補足】 本関数は、鍵管理機能、証明書管理機能の一部である。 181 C_FindObjectsFinal() オブジェクト検索の終了 【機能】 オブジェクトの検索を終了する。 【形式】 CK_RV C_FindObjectsFinal( CK_SESSION_HANDLE ) hSession 【引数】 hSession: 検索を終了するセッションのハンドルを指定する。(Mandatory) 【補足】 本関数は、鍵管理機能、証明書管理機能の一部である。 182 C_SignInit() 署名生成の初期化 【機能】 署名生成演算を初期化する。 【形式】 CK_RV C_SignInit( CK_SESSION_HANDLE CK_MECHANISM_PTR CK_OBJECT_HANDLE ) hSession, pMechanism, hKey 【引数】 hSession: 署名生成を行なうセッションのハンドルを指定する。(Mandatory) pMechanism: 署名生成を行なう為のメカニズムを指定する。(Mandatory) hKey: 署名生成の為の鍵オブジェクトを指定する。(Mandatory) 【補足】 pMechanism に指定する種別は以下の通り。 種別 指定区分 CKM_RSA_PKCS Mandatory (RSA) CKM_MD5_RSA_PKCS Optional (RSA) CKM_SHA1_RSA_PKCS Optional (RSA) CKM_ECDSA Optional (ECDSA) CKM_ECDSA_SHA1 Mandatory (ECDSA) 本関数は、鍵管理機能の一部であり、署名生成機能から呼び出される。 183 C_Sign() 署名生成 【機能】 署名を生成する。 【形式】 CK_RV C_Sign( CK_SESSION_HANDLE CK_BYTE_PTR CK_ULONG CK_BYTE_PTR CK_ULONG_PTR ) hSession, pData, ulDataLen, pSignature, pulSignatureLen 【引数】 hSession: pData: ulDataLen: pSignature: pulSignatureLen: 署名生成を行なうセッションのハンドルを指定する。 (Mandatory) 署名されるデータが格納されている領域へのポインタを指定す る。(Mandatory) 署名されるデータの長さを指定する。(Mandatory) 署名結果を格納する為の領域へのポインタを指定する。 (Mandatory) 署名結果の長さを格納する為の領域へのポインタを指定する。 (Mandatory) 【補足】 ECDSA のみをサポートしているライブラリでは、本関数は実装されていない事がある。 本関数は、鍵管理機能の一部であり、署名生成機能から呼び出される。 184 C_SignUpdate() 署名生成の継続 【機能】 複数回に分けて署名を生成する。 【形式】 CK_RV C_SignUpdate( CK_SESSION_HANDLE CK_BYTE_PTR CK_ULONG ) hSession, pPart, ulPartLen 【引数】 hSession: pPart: ulPartLen: 署名生成を行なうセッションのハンドルを指定する。(Mandatory) 署名されるデータの一部が格納されている領域へのポインタを指定する。 (Mandatory) pPart で指定した署名されるデータの一部の長さを指定する。(Mandatory) 【補足】 RSA を利用した署名のみをサポートしているライブラリでは、本関数は実装されていない 事がある。 本関数は、鍵管理機能の一部であり、署名生成機能から呼び出される。 185 C_SignFinal() 署名生成の終了 【機能】 複数回に分けた署名の生成を終了する。 【形式】 CK_RV C_SignFinal( CK_SESSION_HANDLE CK_BYTE_PTR CK_ULONG_PTR ) hSession, pSignature, pulSignatureLen 【引数】 hSession: pSignature: pulSignatureLen: 署名生成を行なうセッションのハンドルを指定する。 (Mandatory) 署名結果を格納する為の領域へのポインタを指定する。 (Mandatory) 署名結果の長さを格納する為の領域へのポインタを指定する。 (Mandatory) 【補足】 RSA を利用した署名のみをサポートしているライブラリでは、本関数は実装されていない 事がある。 本関数は、鍵管理機能の一部であり、署名生成機能から呼び出される。 186 C_GenerateKeyPair() 公開鍵対の生成 【機能】 公開鍵対を生成し、新しい鍵オブジェクトを作成する。 【形式】 CK_RV C_GenerateKeyPair( CK_SESSION_HANDLE CK_MECHANISM_PTR CK_ATTRIBUTE_PTR CK_ULONG CK_ATTRIBUTE_PTR CK_ULONG CK_OBJECT_HANDLE_PTR CK_OBJECT_HANDLE_PTR ) hSession, pMechanism, pPublicKeyTemplate, ulPublicKeyAttributeCount, pPrivateKeyTemplate, ulPrivateKeyAttributeCount, phPublicKey, phPrivateKey 【引数】 hSession: pMechanism: pPublicKeyTemplate: ulPublicKeyAttributeCount: pPrivateKeyTemplate: ulPrivateKeyAttributeCount: phPublicKey: phPrivateKey: 公開鍵対を生成するセッションのハンドルを指定す る。(Mandatory) 公開鍵対生成の為のメカニズムを指定する。 (Mandatory) 生 成 さ れ る Public-Key の 属 性 を 指 定 す る 。 (Mandatory) Public-Key の属性の項目数を指定する。(Mandatory) 生 成 さ れ る Private-Key の 属 性 を 指 定 す る 。 (Mandatory) Private-Key の属性の項目数を指定する。(Mandatory) 生成される Public-Key のオブジェクトのハンドルを 格納する為の領域へのポインタを指定する。 (Mandatory) 生成される Private-Key のオブジェクトのハンドルを 格納する為の領域へのポインタを指定する。 (Mandatory) 【補足】 pMechanism に指定する種別は以下の通り。 種別 指定区分 CKM_RSA_PKCS_KEY_PAIR_GEN Mandatory (RSA) CKM_ECDSA_KEY_PAIR_GEN Mandatory (ECDSA) pPublicKeyTemplate に指定する種別は以下の通り。 共通: 種別 CKA_TOKEN CKA_PRIVATE CKA_LABEL CKA_ID CKA_SUBJECT CKA_VERIFY 値 TRUE TRUE ラベル key identifier DER 符号化された subject name TRUE 指定区分 Optional Optional Optional Optional Optional Optional 値 鍵長 (法の長さ) public exponent 指定区分 Mandatory Mandatory RSA: 種別 CKA_MODULUS_BITS CKA_PUBLIC_EXPONENT 187 ECDSA: 種別 CKA_ECDSA_PARAMS 値 DER 符号化された ecParameters pPrivateKeyTemplate に指定する種別は以下の通り。 種別 値 CKA_TOKEN TRUE CKA_PRIVATE TRUE CKA_LABEL ラベル CKA_ID key identifier CKA_SUBJECT DER 符号化された subject name CKA_SENSITIVE TRUE CKA_SIGN TRUE CKA_EXTRACTABLE FALSE 本関数は鍵対生成機能の一部である。 188 指定区分 Mandatory 指定区分 Mandatory Mandatory Optional Optional Optional Optional Mandatory Optional C_WrapKey() 鍵の暗号化 【機能】 Private-Key や Secrete-Key を暗号化して取得する。 【形式】 CK_RV C_WrapKey( CK_SESSION_HANDLE CK_MECHANISM_PTR CK_OBJECT_HANDLE CK_OBJECT_HANDLE CK_BYTE_PTR CK_ULONG_PTR ) hSession, pMechanism, hWrappingKey, hKey, pWrappedKey, pulWrappedKeyLen 【引数】 hSession: pMechanism: hWrappingKey: hKey: pWrappedKey: pulWrappedKeyLen: 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は鍵管理機能の一部である。 189 C_UnwrapKey() 暗号化された鍵の設定 【機能】 暗号化された Private-Key や Secret-Key を復号し、新しい鍵オブジェクトを作成する。 【形式】 CK_RV C_UnwrapKey( CK_SESSION_HANDLE CK_MECHANISM_PTR CK_OBJECT_HANDLE CK_BYTE_PTR CK_ULONG CK_ATTRIBUTE_PTR CK_ULONG CK_OBJECT_HANDLE_PTR ) hSession, pMechanism, hUnwrappingKey, pWrappedKey, ulWrappedKeyLen, pTemplate, ulAttributeCount, phKey 【引数】 hSession: pMechanism: hUnwrappingKey: pWrappedKey: ulWrappedKeyLen: pTemplate: ulAttributeCount: phKey: 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 指定すべき必須の値はない。 【補足】 本関数は実装されていない事がある。 本関数は鍵管理機能の一部である。 190 5. SP 側 API 仕様 5.1. 鍵対生成 SP 機能 鍵対生成 SP 機能は、公開鍵暗号の鍵生成アルゴリズムを用いて、公開鍵対(公開鍵:Public-Key、 秘密鍵:Private-Key)を生成する機能の実体である。公開鍵対は公開鍵暗号アルゴリズムに規 定されたフォーマットに従って生成する。 鍵 対 生 成 SP 機 能 を 実 現 す る API 仕 様 と し て は 、 業 界 標 準 と し て 普 及 し て い る PKCS#11(Version2.01 以降)を採用する。また、PKCS#11 を採用する為、鍵対生成機能と鍵対生成 SP 機能を実現する API 仕様は同一となる。 <公開鍵暗号アルゴリズム> RSA を含む2個以上の、政府告示の署名アルゴリズムに対応する公開鍵暗号アルゴリズム。 191 5.2. 署名生成 SP 機能 署名生成SP機能は、署名アルゴリズムを用いて、平文と公開鍵暗号アルゴリズムの秘密鍵から、 署名を生成する機能の実体である。署名に使用する秘密鍵は、計算機の主記憶上の秘密鍵、また は鍵管理媒体上の秘密鍵を使用する。鍵管理媒体上の秘密鍵を用いる場合は、利用者認証情報(パ スワード等)を用いた利用者の認証を行い、なりすましによる不正使用を防止する。署名は署名 アルゴリズムに規定されたフォーマットに従って生成する。 <署名アルゴリズム> sha1WithRSAEncryption を含む2個以上の、政府告示の署名アルゴリズム。 5.2.1. 署名生成 SP オブジェクト 関数名 ICASignatureCSPInit ICASignatureCSPDestroy ICASignatureCSPSetAlgorithm ICASignatureCSPSetKey ICASignatureCSPSetMessage ICASignatureCSPAddMessage ICASignatureCSPGetSignature 概要 署名生成 CSP 初期化 署名生成 CSP の解放 署名アルゴリズム設定 秘密鍵の設定 署名対象の平文データの設定 署名対象の平文データの追加設定 署名データの取得 192 ICASignatureCSPInit () 署名生成 CSP の初期化 【機能】 署名生成 CSP の初期化を行う。 【形式】 ICASignatureCSPHandle ICASignatureCSPInit ( ICAErrorCode *pErr ) 【引数】 pErr: 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :署名生成 SP オブジェクトハンドル(0 以外) 異常終了 :0 【補足】 アプリケーションが「ICASignatureObjectRegisterCSP」を呼び出した延長で呼び出さ れる。初期化の処理内容及び署名生成 SP オブジェクトの構造は、CSP に依存し、API 仕様としては規定しない。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 193 ICASignatureCSPDestroy () 署名生成 CSP の解放 【機能】 署名生成 CSP の解放処理を行う。 【形式】 ICAReturnCode ICASignatureCSPDestroy ( ICASignatureCSPHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 署名生成 SP オブジェクトハンドル(IN) 解放する署名生成 SP オブジェクトハンドルが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 アプリケーションが「ICASignatureObjectDestroy」を呼び出した延長で呼び出される。 解放処理の内容は CSP の構造に依存するが、 「ICASignatureCSPGetSignature」で返す、 署名データを格納した領域のメモリ解放は行う必要がある。 194 ICASignatureCSPSetAlgorithm () 署名アルゴリズム設定 【機能】 署名アルゴリズムの設定を行う。 【形式】 ICAReturnCode ICASignatureCSPSetAlgorithm( ICASignatureCSPHandle hObj, ICAAlgorithmId *pAlg, ICAErrorCode *pErr ) 【引数】 hObj: pAlg: pErr: 署名生成 SP オブジェクトハンドル(IN) 署名生成 SP オブジェクトハンドルが指定される。 署名アルゴリズム(IN) 署名アルゴリズムが指定される。詳細は「3 APP 側 API で使用する型定義」 を参照の事。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM 195 意味 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 ICASignatureCSPSetKey () 秘密鍵の設定 【機能】 秘密鍵の設定を行う。 【形式】 ICAReturnCode ICASignatureCSPSetKey ( ICASignatureCSPHandle hObj, ICAKeyObjectHandle hKey, ICAErrorCode *pErr ) 【引数】 hObj: hKey: pErr: 署名生成 SP オブジェクトハンドル(IN) 署名生成 SP オブジェクトハンドルが指定される。 署名生成用の秘密鍵の鍵オブジェクト(IN) 署名生成用の秘密鍵の鍵オブジェクトが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR 196 意味 回復不能な致命的エラー発生 ICASignatureCSPSetMessage () 署名対象の平文データの設定 【機能】 署名対象の平文データの設定を行う。 【形式】 ICAReturnCode ICASignatureCSPSetMessage ( ICASignatureCSPHandle hObj, ICAMessage *pMsg, ICAErrorCode *pErr ) 【引数】 hObj: pMsg: pErr: 署名生成 SP オブジェクトハンドル(IN) 署名生成 SP オブジェクトハンドルが指定される。 署名対象の平文データ(IN) 署名対象の平文が指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_DATA 197 意味 回復不能な致命的エラー発生 平文データ不正 ICASignatureCSPAddMessage () 署名対象の平文データの追加設定 【機能】 署名対象の平文データの追加設定を行う。署名対象の平文データを分割して設定する 場合に使用する。 【形式】 ICAReturnCode ICASignatureCSPAddMessage ( ICASignatureCSPHandle hObj, ICAMessage *pMsg, ICAErrorCode *pErr ) 【引数】 hObj: pMsg: pErr: 署名生成 SP オブジェクトハンドル(IN) 署名生成 SP オブジェクトハンドルが指定される。 署名対象の平文データ(IN) 署名対象の平文が指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_DATA 198 意味 回復不能な致命的エラー発生 平文データ不正 ICASignatureCSPGetSignature () 署名データの取得 【機能】 署名データの取得を行う。 【形式】 ICAReturnCode ICASignatureCSPGetSignature( ICASignatureCSPHandle hObj, ICASignature *pSig, ICAErrorCode *pErr ) 【引数】 hObj: 署名生成 SP オブジェクトハンドル(IN) 署名生成 SP オブジェクトハンドルが指定される。 署名データの格納領域(OUT) 署名データが格納されている領域を指すポインタを返す。 署名データが格納されている領域のメモリ確保は CSP で行う。 「ICASignatureCSPDestroy」が呼び出された際にメモリの解放を行う必要 がある。 異常終了時のエラーコード(OUT) エラーコードを返す。 pSig: pErr: 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_ALGORITHM アルゴリズム不正 ICAE_INVALID_ALGORITHM_PARAM アルゴリズムのパラメータ不正 ICAE_INVALID_KEY 秘密鍵不正 ICAE_INVALID_KEY_LENGTH 秘密鍵の長さ不正 ICAE_INVALID_DATA 平文データ不正 ICAE_INVALID_DATA_LENGTH 平文データの長さ不正 ICAE_INVALID_KEY_OR_DATA 暗号化失敗 ICAE_FAILURE_MALLOC メモリ確保に失敗 ICAE_DEVICE_FAILURE 暗号トークンのエラー ICAE_DEVICE_FAILURE_MALLOC 暗号トークンにおけるメモリ確保の失敗 ICAE_DEVICE_REMOVED 暗号トークンは取り除かれている ICAE_SESSION_INVALID_HANDLE セッションハンドル不正 ICAE_SESSION_CLOSED セッションはクローズ状態 ICAE_SESSION_USER_NOT_LOGGED_IN 暗号トークンに対して未ログイン ICAE_FUNCTION_FAILED 回復可能なエラー発生 ICAE_OTHER その他のエラー発生 199 5.3. 署名検証 SP 機能 署名検証SP機能は、署名アルゴリズムを用いて、平文と公開鍵暗号アルゴリズムの公開鍵と署 名から、署名の正当性を検証する機能の実体である。署名アルゴリズムに規定されたフォーマッ トに従った署名の入力機能を含む。 5.3.1. 署名検証 SP オブジェクト 関数名 ICAVerificationCSPInit ICAVerificationCSPDestroy ICAVerificationCSPSetAlgorithm ICAVerificationCSPSetKey ICAVerificationCSPSetMessage ICAVerificationCSPAddMessage ICAVerificationCSPSetSignature ICAVerificationCSPVerifySignature 概要 署名検証 CSP の初期化 署名検証 CSP の破棄 署名アルゴリズムの設定 署名検証用の公開鍵の設定 署名検証の平文データの設定 署名検証の平文データの追加設定 署名データの設定 署名検証結果の取得 200 ICAVerificationCSPInit() 署名検証 CSP の初期化 【機能】 署名検証 CSP の初期化を行う。 【形式】 ICAVerificationCSPHandle ICAVerificationCSPInit( ICAErrorCode *pErr ) 【引数】 pErr: 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :署名検証 SP オブジェクトハンドル 異常終了 :0 【補足】 アプリケーションが「ICAVerificationObjectRegisterCSP」を呼び出した延長で呼び 出される。初期化の処理内容及び署名検証 SP オブジェクトの構造は、CSP に依存し、 API 仕様としては規定しない。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 201 ICAVerificationCSPDestroy () 署名検証 CSP の解放 【機能】 署名検証 CSP の解放を行う。 【形式】 ICAReturnCode ICAVerificationCSPDestroy ( ICAVerificationCSPHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 署名検証 SP オブジェクトハンドル(IN) 解放する署名検証 SP オブジェクトハンドルが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 アプリケーションが「ICAVerificationObjectDestroy」を呼び出した延長で呼び出さ れる。解放処理の内容は CSP の構造に依存する。 202 ICAVerificationCSPSetAlgorithm () 署名アルゴリズム設定 【機能】 署名アルゴリズムの設定を行う。 【形式】 ICAReturnCode ICAVerificationCSPSetAlgorithm( ICAVerificationCSPHandle hObj, ICAAlgorithmId *pAlg, ICAErrorCode *pErr ) 【引数】 hObj: pAlg: pErr: 署名検証 SP オブジェクトハンドル(IN) 署名検証 SP オブジェクトハンドルが指定される。 署名アルゴリズム(IN) 署名アルゴリズムが指定される。詳細は「3 APP 側 API で使用する型定義」 を参照の事。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM 203 意味 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 ICAVerificationCSPSetKey () 署名検証用の公開鍵の設定 【機能】 署名検証用の公開鍵を設定する。 【形式】 ICAReturnCode ICAVerificationCSPSetKey ( ICAVerificationSPObjectHandle hObj, ICAKeyObjectHandle hKey, ICAErrorCode *pErr ) 【引数】 hObj: hKey: pErr: 署名検証 SP オブジェクトハンドル(IN) 署名検証 SP オブジェクトハンドルが指定される。 署名検証用の公開鍵の鍵オブジェクト(IN) 署名検証用の公開鍵の鍵オブジェクトが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR 204 意味 回復不能な致命的エラー発生 ICAVerificationCSPSetMessage () 署名検証の平文データの設定 【機能】 署名検証を行う平文データの設定を行う。 【形式】 ICAReturnCode ICAVerificationCSPSetMessage ( ICAVerificationCSPHandle hObj, ICAMessage *pMsg, ICAErrorCode *pErr ) 【引数】 hObj: pMsg: pErr: 署名検証 SP オブジェクトハンドル(IN) 署名検証 SP オブジェクトハンドルが指定される。 署名検証対象の平文データ(IN) 署名検証を行う平文が指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_DATA 205 意味 回復不能な致命的エラー発生 平文データ不正 ICAVerificationCSPAddMessage () 署名検証の平文データの追加設定 【機能】 署名検証を行う平文データの追加設定を行う。署名検証を行う平文データを分割して 設定する場合に使用する。 【形式】 ICAReturnCode ICAVerificationCSPAddMessage ( ICAVerificationCSPHandle hObj, ICAMessage *pMsg, ICAErrorCode *pErr ) 【引数】 hObj: pMsg: pErr: 署名検証 SP オブジェクトハンドル(IN) 署名検証 SP オブジェクトハンドルが指定される。 署名検証を行う平文データ(IN) 署名対象の平文が指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_DATA 206 意味 回復不能な致命的エラー発生 平文データ不正 ICAVerificationCSPSetSignature () 署名データの設定 【機能】 署名データの設定を行う。 【形式】 ICAReturnCode ICAVerificationCSPSetSignature ( ICAVerificationCSPHandle hObj, ICASignature *pSig, ICAErrorCode *pErr ) 【引数】 hObj: pSig: pErr: 署名検証 SP オブジェクトハンドル(IN) 署名検証 SP オブジェクトハンドルが指定される。 署名データの格納領域(IN) 署名データの格納領域が指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FATAL_ERROR 回復不能な致命的エラー発生 ICAE_INVALID_ALGORITHM アルゴリズム不正 ICAE_INVALID_ALGORITHM_PARAM アルゴリズムのパラメータ不正 ICAE_INVALID_KEY 公開鍵不正 ICAE_INVALID_KEY_LENGTH 公開鍵の長さ不正 ICAE_INVALID_DATA 署名データ不正 ICAE_INVALID_DATA_LENGTH 署名データの長さ不正 ICAE_INVALID_KEY_OR_DATA 公開鍵または署名データ不正 207 ICAVerificationCSPVerifySignature () 署名検証結果の取得 【機能】 署名検証結果を取得する。 【形式】 ICAReturnCode ICAVerificationCSPVerifySignature ( ICAVerificationCSPHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: 署名検証 SP オブジェクトハンドル(IN) 署名検証 SP オブジェクトハンドルが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 pErr: 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 署名検証に成功した場合は戻り値に「ICAR_SUCCESS」 、それ以外は「ICAR_FAILURE」が返る。 署名対象の平文が改ざんされていた場合、エラーコードに「ICAE_INVALID_SIGNATURE」が返る。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_VERIFY_SUCCESS 検証成功 ICAE_VERIFY_FAILURE ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_INVALID_SIGNATURE ICAE_INVALID_SIGNATURE_LENGTH ICAE_INVALID_KEY_OR_DATA 検証失敗 回復不能な致命的エラー発生 アルゴリズム不正 復号文データ不正 復号文データの長さ不正 署名データ不正 署名データの長さ不正 復号失敗 208 5.4. 親展 SP 機能 親展SP機能は、アルゴリズム(共通鍵生成アルゴリズム、鍵配送アルゴリズム、共通鍵暗号ア ルゴリズム)及び、公開鍵暗号アルゴリズム(RSA)の公開鍵を組み合わせ、平文から、親展文 (暗号文)を生成する機能の実体である。共通鍵生成アルゴリズムに従って、共通鍵(セッショ ン鍵)を生成する機能、鍵配送アルゴリズムに従って公開鍵でセッション鍵を暗号化する機能、 共通鍵暗号アルゴリズムに従ってセッション鍵で平文を暗号化する機能を含む。また、暗号文と 暗号化されたセッション鍵を、親展文をフォーマットするのに必要な形式で出力する機能を含む。 <暗号アルゴリズム> セッション鍵の暗号アルゴリズム(共通鍵暗号アルゴリズム)は、任意の共通鍵ブロック 暗号アルゴリズム。公開鍵暗号アルゴリズムは、RSA。 5.4.1. 親展 SP オブジェクト 関数名 ICAEncryptionCSPInit ICAEncryptionCSPDestroy ICAEncryptionCSPGenerateKey ICAEncryptionCSPSetKeyTransferAlgorithm ICAEncryptionCSPExportKey ICAEncryptionCSPSetAlgorithm ICAEncryptionCSPSetData ICAEncryptionCSPAddData ICAEncryptionCSPGetEncryptedData ICAEncryptionCSPGetEncryptedDataFinal 209 概要 親展 CSP の初期化 親展 CSP の解放 共通鍵の生成 鍵配送アルゴリズムの設定 暗号化した共通鍵の取得 共通鍵暗号アルゴリズムの設定 平文データ設定 平文データ追加設定 暗号文取得 最後の暗号文取得 ICAEncryptionCSPInit() 親展 CSP の初期化 【機能】 親展 CSP の初期化を行う。 【形式】 ICAEncryptionCSPHandle ICAErrorCode ) ICAEncryptionCSPInit( *pErr 【引数】 pErr: 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :親展 SP オブジェクトハンドル 異常終了 :0 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 210 ICAEncryptionCSPDestroy() 親展 CSP オブジェクトの解放 【機能】 親展 CSP オブジェクトの解放を行う。 【形式】 ICAReturnCode ICAEncryptionCSPDestroy( ICAEncryptionCSPHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 親展 SP オブジェクトハンドル(IN) 解放する親展 SP オブジェクトハンドルが指定される。 異常終了時のエラーコード エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 211 ICAEncryptionCSPGenerateKey() 共通鍵の生成 【機能】 平文の暗号化を行う為の共通鍵を生成する。 【形式】 ICAReturnCode ICAEncryptionCSPGenerateKey( ICAEncryptionCSPHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 親展 SP オブジェクトハンドル(IN) 親展 SP オブジェクトハンドルが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_FAILURE_KEYGEN 意味 回復不能な致命的エラー発生 共通鍵生成に失敗 212 ICAEncryptionCSPSetKeyTransferAlgorithm () 鍵配送アルゴリズム設定 【機能】 鍵配送アルゴリズムの設定を行う。 【形式】 ICAReturnCode ICAEncryptionCSPSetKeyTransferAlgorithm( ICAEncryptionCSPHandle hObj, ICAAlgorithmId *pAlg, ICAErrorCode *pErr ) 【引数】 hObj: pAlg: pErr: 親展 SP オブジェクトハンドル(IN) 親展 SP オブジェクトハンドルが指定される。 鍵配送アルゴリズム(IN) 鍵配送アルゴリズムが指定される。 詳細は「3 APP 側 API で使用する型定義」を参照の事。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM 213 意味 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 ICAEncryptionCSPExportKey () 暗号化した共通鍵の取得 【機能】 指定した公開鍵で暗号化した共通鍵を取得する。 【形式】 ICAReturnCode ICAEncryptionCSPExportKey( ICAEncryptionCSPHandle hObj, ICAKeyObjectHandle hKey, ICAEncryptedKey *pEncyptedKey, ICAErrorCode *pErr ) 【引数】 hObj: hKey: pEncyptedKey: pErr: 親展 SP オブジェクトハンドル(IN) 親展 SP オブジェクトハンドルが指定される。 公開鍵の鍵オブジェクト(IN) 公開鍵の鍵オブジェクトが指定される。 暗号化した共通鍵(OUT) 暗号化した共通鍵を返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 実際に暗号化された共通鍵を格納する領域は CSP が確保し、ICAEncryptionCSPDestroy が呼び出されたタイミングで解放すること。 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM ICAE_INVALID_KEY ICAE_INVALID_KEY_LENGTH ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_INVALID_SEED ICAE_INVALID_KEY_OR_DATA 214 意味 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 公開鍵不正 公開鍵の長さ不正 共通鍵データ不正 共通鍵データの長さ不正 乱数発生ルーチン初期値不正 暗号化失敗 ICAEncryptionCSPSetAlgorithm() 共通鍵暗号アルゴリズム設定 【機能】 共通鍵暗号アルゴリズムの設定を行う。 【形式】 ICAReturnCode ICAEncryptionCSPSetAlgorithm( ICAEncryptionCSPHandle hObj, ICAAlgorithmId *pAlg, ICAErrorCode *pErr ) 【引数】 hObj: pAlg: pErr: 親展 SP オブジェクトハンドル(IN) 親展 SP オブジェクトハンドルが指定される。 鍵配送アルゴリズム(IN) 鍵配送アルゴリズムが指定される。 詳細は「3 APP 側 API で使用する型定義」を参照の事。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM ICAE_INVALID_KEY ICAE_INVALID_KEY_LENGTH 意味 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 共通鍵不正 共通鍵の長さ不正 215 ICAEncryptionCSPSetData() 平文データの設定 【機能】 平文データを設定する。 【形式】 ICAReturnCode ICAEncryptionCSPSetData( ICAEncryptionCSPHandle hObj, ICAMessage *pData, ICAErrorCode *pErr ) 【引数】 hObj: pData: pErr: 親展 SP オブジェクトハンドル(IN) 親展 SP オブジェクトハンドルが指定される。 平文データ(IN) 平文データが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_FAILURE_MALLOC 意味 回復不能な致命的エラー発生 平文データ不正 平文データの長さ不正 メモリ確保に失敗 216 ICAEncryptionCSPAddData() 平文データの追加設定 【機能】 平文データを追加設定する。 【形式】 ICAReturnCode ICAEncryptionCSPAddData( ICAEncryptionCSPHandle hObj, ICAMessage *pData, ICAErrorCode *pErr ) 【引数】 hObj: pData: pErr: 親展 SP オブジェクトハンドル(IN) 親展 SP オブジェクトハンドルが指定される。 平文データ(IN) 平文データが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_FAILURE_MALLOC 意味 回復不能な致命的エラー発生 平文データ不正 平文データの長さ不正 メモリ確保に失敗 217 ICAEncryptionCSPGetEncryptedData() 暗号文データの取得 【機能】 暗号文データを取得する。 【形式】 ICAReturnCode ICAEncryptionCSPGetEncryptedData( ICAEncryptionCSPHandle hObj, ICAEncryptedMessage *pEncryptedData, ICAErrorCode *pErr ) 【引数】 hObj: pEncryptedData: pErr: 親展 SP オブジェクトハンドル(IN) 親展 SP オブジェクトハンドルが指定される。 暗号文データ(OUT) 暗号文データ格納されている領域を指すポインタを返す。 暗号化データが格納される領域のメモリ確保は CSP で行う。 「ICAEncryptionCSPDestroy」が呼ばれる際にメモリの解放を行 う必要がある。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 回復不能な致命的エラー発生 ICAE_FATAL_ERROR 218 ICAEncryptionCSPGetEncryptedDataFinal() 最後の暗号文データの取得 【機能】 最後の暗号文データを取得する。 【形式】 ICAReturnCode ICAEncryptionCSPGetEncryptedDataFinal( ICAEncryptionCSPtHandle hObj, ICAEncryptedMessage *pEncryptedData, ICAErrorCode *pErr ) 【引数】 hObj: pEncryptedData: pErr: 親展 SP オブジェクトハンドル(IN) 親展 SP オブジェクトハンドルが指定される。 暗号文データ(OUT) 暗号文データ格納されている領域を指すポインタを返す。 暗号化データが格納される領域のメモリ確保は CSP で行う。 「ICAEncryptionCSPDestroy」が呼ばれる際にメモリの解放を行 う必要がある。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 回復不能な致命的エラー発生 平文データ不正 平文データの長さ不正 メモリ確保に失敗 ICAE_FATAL_ERROR ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_FAILURE_MALLOC 219 5.5. 親展解除 SP 機能 親展解除SP機能は、アルゴリズム(鍵配送アルゴリズム、共通鍵暗号アルゴリズム)及び、公 開鍵暗号アルゴリズム(RSA)の秘密鍵、を組み合わせて暗号文から、平文を取得する機能の実 体である。鍵配送アルゴリズムに従って暗号化されたセッション鍵を秘密鍵で復号する機能、共 通鍵暗号アルゴリズムに従ってセッション鍵で暗号文を復号する機能を含む。鍵管理媒体上の秘 密鍵を用いる場合は、利用者認証情報(パスワード等)を用いた利用者の認証を行い、なりすま しによる不正使用を防止する。また、親展文のフォーマットに従った、暗号文と暗号化されたセ ッション鍵の入力機能を含む。 <暗号アルゴリズム> セッション鍵の暗号アルゴリズム(共通鍵暗号アルゴリズム)は、任意の共通鍵ブロック 暗号アルゴリズム。公開鍵暗号アルゴリズムは、RSA。 5.5.1. 親展解除 SP オブジェクト 関数名 ICADecryptionCSPInit ICADecryptionCSPDestroy ICADecryptionCSPSetKeyTransferAlgorithm ICADecryptionCSPImportKey ICADecryptionCSPSetAlgorithm ICADecryptionCSPSetEncryptedData ICADecryptionCSPAddEncryptedData ICADecryptionCSPGetData ICADecryptionCSPGetDataFinal 220 概要 親展解除 CSP の初期化 親展解除 CSP の解放 鍵配送アルゴリズムの設定 暗号化した共通鍵の設定 共通鍵暗号アルゴリズムの設定 暗号化されたデータの設定 暗号化されたデータの追加設定 平文取得 最後の平文取得 ICADecryptionCSPInit() 親展解除 CSP の初期化 【機能】 親展解除 CSP の初期化を行う。 【形式】 ICADecryptionCSPHandle ICAErrorCode ) ICADecryptionCSPInit( *pErr 【引数】 pErr: 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :親展解除 SP オブジェクトハンドル(0 以外) 異常終了 :0 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 221 ICADecryptionCSPDestroy() 親展解除 CSP の解放 【機能】 親展解除 CSP の解放を行う。 【形式】 ICAReturnCode ICADecryptionCSPDestroy ( ICADecryptionCSPHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 親展解除 SP オブジェクトハンドル(IN) 解放する親展解除 SP オブジェクトハンドルが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 222 ICADecryptionCSPSetKeyTransferAlgorithm () 鍵配送アルゴリズム設定 【機能】 鍵配送アルゴリズムの設定を行う。 【形式】 ICAReturnCode ICADecryptionCSPSetKeyTransferAlgorithm( ICADecryptionCSPHandle hObj, ICAAlgorithmId *pAlg, ICAErrorCode *pErr ) 【引数】 hObj: pAlg: pErr: 親展解除 SP オブジェクトハンドル(IN) 親展解除 SP オブジェクトハンドルが指定される。 鍵配送アルゴリズム(IN) 鍵配送アルゴリズムが指定される。 詳細は「3 APP 側 API で使用する型定義」を参照の事。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICA_REASON_FATAL_ERROR ICA_REASON_INVALID_ALGORITHM ICA_REASON_INVALID_ALGORITHM_PARAM 223 意味 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 ICADecryptionCSPImportKey () 暗号化された共通鍵の設定 【機能】 指定した秘密鍵で暗号化された共通鍵を復号し、内部に保管する。 【形式】 ICAReturnCode ICADecryptionCSPImportKey( ICADecryptionSPObjectHandle hObj, ICAKeyObjectHandle hKey, ICAEncryptedKey *pEncyptedKey, ICAErrorCode *pErr ) 【引数】 hObj: hKey: pEncyptedKey: pErr: 親展解除 SP オブジェクトハンドル(IN) 親展解除 SP オブジェクトハンドルが指定される。 秘密鍵オブジェクト(IN) 秘密鍵オブジェクトが指定される。 暗号化された共通鍵(IN) 暗号化された共通鍵が指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM ICAE_INVALID_KEY ICAE_INVALID_KEY_LENGTH ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_INVALID_KEY_OR_DATA ICAE_FAILURE_MALLOC ICAE_DEVICE_FAILURE ICAE_DEVICE_FAILURE_MALLOC ICAE_DEVICE_REMOVED ICAE_SESSION_INVALID_HANDLE ICAE_SESSION_CLOSED ICAE_SESSION_USER_NOT_LOGGED_IN ICAE_FUNCTION_FAILED ICAE_OTHER (注) 「秘密鍵情報の不正」を含む 224 意味 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 秘密鍵不正 (注) 秘密鍵の長さ不正 暗号文データ不正 暗号文データの長さ不正 復号失敗 メモリ確保に失敗 暗号トークンのエラー 暗号トークンにおけるメモリ確保の失敗 暗号トークンが除去 セッションハンドル不正 セッションはクローズ状態 暗号トークンに対して未ログイン 回復可能なエラー発生 その他のエラー発生 ICADecryptionCSPSetAlgorithm() 共通鍵暗号アルゴリズム設定 【機能】 共通鍵暗号アルゴリズムの設定を行う。 【形式】 ICAReturnCode ICADecryptionCSPSetAlgorithm( ICADecryptionCSPHandle hObj, ICAAlgorithmId *pAlg, ICAErrorCode *pErr ) 【引数】 hObj: pAlgorithm: pErr: 親展解除 SP オブジェクトハンドル(IN) 親展解除 SP オブジェクトハンドルが指定される。 共通鍵暗号アルゴリズム(IN) 共通鍵暗号アルゴリズムが指定される。 詳細は「3 APP 側 API で使用する型定義」を参照の事。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_ALGORITHM ICAE_INVALID_ALGORITHM_PARAM ICAE_INVALID_KEY ICAE_INVALID_KEY_LENGTH 意味 回復不能な致命的エラー発生 アルゴリズム不正 アルゴリズムのパラメータ不正 共通鍵不正 共通鍵の長さ不正 225 ICADecryptionCSPSetEncryptedData() 暗号文データの設定 【機能】 暗号文データを設定する。 【形式】 ICAReturnCode ICADecryptionCSPSetEncryptedData( ICADecryptionCSPHandle hObj, ICAEncryptedMassage *pEncryptedData, ICAErrorCode *pErr ) 【引数】 hObj: pEncryptedData: pErr: 親展解除 SP オブジェクトハンドル(IN) 親展解除 SP オブジェクトハンドルが指定される。 暗号文データ(IN) 暗号文データが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_FAILURE_MALLOC 226 意味 回復不能な致命的エラー発生 暗号文データ不正 暗号文データの長さ不正 メモリ確保に失敗 ICADecryptionCSPAddEncryptedData() 暗号文データの追加設定 【機能】 暗号文データを追加設定する。 【形式】 ICAReturnCode ICADecryptionCSPAddEncryptedData( ICADecryptionCSPHandle hObj, ICAEncryptedMessage *pEncryptedData, ICAErrorCode *pErr ) 【引数】 hObj: pEncryptedData: pErr: 親展解除 SP オブジェクトハンドル(IN) 親展解除 SP オブジェクトハンドルが指定される。 暗号文データ(IN) 暗号文データが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード ICAE_FATAL_ERROR ICAE_INVALID_DATA ICAE_INVALID_DATA_LENGTH ICAE_INVALID_KEY_OR_DATA ICAE_FAILURE_MALLOC 意味 回復不能な致命的エラー発生 暗号文データ不正 暗号文データの長さ不正 共通鍵または暗号文データ不正 メモリ確保に失敗 227 ICADecryptionCSPGetData() 平文データの取得 【機能】 平文データを取得する。 【形式】 ICAReturnCode ICADecryptionCSPGetData( ICADecryptionCSPtHandle hObj, ICAMMessage *pData, ICAErrorCode *pErr ) 【引数】 hObj: pData: pErr: 親展解除 SP オブジェクトハンドル(IN) 親展解除 SP オブジェクトハンドルが指定される。 平文データ(OUT) 平文データを返す。 平文データが格納される領域のメモリ確保は CSP で行う。 「ICAEncryptionCSPDestroy」が呼ばれる際にメモリの解放を行う必要があ る。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 回復不能な致命的エラー発生 ICAE_FATAL_ERROR 228 ICADecryptionCSPGetDataFinal() 最後の平文データの取得 【機能】 最後の平文データを取得する。 【形式】 ICAReturnCode ICADecryptionCSPGetDataFinal( ICADecryptionCSPtHandle hObj, ICAMessage *pData, ICAErrorCode *pErr ) 【引数】 hObj: pData: pErr: 親展解除 SP オブジェクトハンドル(IN) 親展解除 SP オブジェクトハンドルが指定される。 平文データ(OUT) 平文データを返す。 平文データが格納される領域のメモリ確保は CSP で行う。 「ICAEncryptionCSPDestroy」が呼ばれる際にメモリの解放を行う必要があ る。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 回復不能な致命的エラー発生 暗号文データの長さ不正 復号失敗 メモリ確保に失敗 ICAE_FATAL_ERROR ICAE_INVALID_DATA_LENGTH ICAE_INVALID_KEY_OR_DATA ICAE_FAILURE_MALLOC 229 5.6. 鍵管理 SP 機能 鍵管理 SP 機能は、鍵管理媒体(固定ディスク、IC カード又は HSM)を用いて、公開鍵暗号アル ゴリズムの秘密鍵を管理(保管、取得、削除)する機能の実体である。署名生成機能と組み合わ せる事によって、鍵管理媒体上の秘密鍵を用いて署名を生成する機能の実体を含む。親展解除機 能と組み合わせる事によって、鍵管理媒体上の秘密鍵を用いて親展解除を行う機能の実体を含む。 秘密鍵を用いる場合は、利用者認証情報(パスワード等)を用いた利用者の認証を行い、なりす ましによる不正使用を防止する。さらに、HD の場合は、メッセージ認証コード等の暗号アルゴ リズムを用いて、保管中の秘密鍵の改ざん及び暴露から保護する。 <公開鍵暗号アルゴリズム> RSA を含む2個以上の、政府告示の署名アルゴリズムに対応する公開鍵暗号アルゴリズム。 <秘密鍵管理媒体> HD、IC カード、又は HSM (Hardware Security Module) 鍵 管 理 SP 機 能 を 実 現 す る 為 の API 仕 様 と し て 、 業 界 標 準 と し て 普 及 し て い る PKCS#11(Version2.01 以降)を採用する。また、PKCS#11 を採用した為、鍵管理機能と鍵管理 SP 機能を実現する API 仕様は同一となる。 230 5.7. 証明書管理 SP 機能 証明書管理 SP 機能は、証明書管理媒体(固定ディスク、IC カード又は HSM)を用いて、証明書 を管理(保管、取得、削除)する機能、証明書内部の項目を取得する機能の実体である。証明書 には、利用者(自分)の証明書、CA の証明書及び他人の証明書を含む。さらに、信頼点に相当 する証明書を含む。信頼点に相当する証明書を管理する場合は、利用者認証情報(パスワード等) を用いた利用者の認証を行い、なりすましによる不正使用を防止する。さらに、HD の場合は、 メッセージ認証コード等の暗号アルゴリズムを用いて、保管中の信頼点となる証明書を改ざん及 び暴露から保護する。自分の証明書の申請及び取得機能も含む。 <証明書管理媒体> HD、IC カード、又は HSM(Hardware Security Module) 証明書管理 SP 機能の証明書管理媒体を用いて証明書を管理する機能を実現する API 仕様として は、業界標準として普及している PKCS#11(Version2.01 以降)を採用する。また、PKCS#11 を採 用した事から証明書管理機能と証明書管理 SP 機能を実現する API 仕様は同一となる。 証明書内部の項目を取得する機能、および自分の証明書の申請及び取得機能は APP に提供する API 自体を実体とする。 231 5.8. 証明書検証 SP 機能 証明書検証 SP 機能は、利用したい証明書の正当性を確認する機能の実体である。検証する証明 書、信頼点の証明書、検証の条件及び CA の証明書を用いて認証パスを構築し、失効情報を利用 して検証処理を行う。検証項目には、証明書の標準項目の検証、Standard Extension の検証が 含まれる。 5.8.1. 証明書検証 SP オブジェクト 関数名 ICACertificateValidationCSPInit ICACertificateValidationCSPDestroy ICACertificateValidationCSPSetServerInfo ICACertificateValidationCSPAttachEnv ICACertificateValidationCSPDetachEnv ICACertificateValidationCSPValidateCertificate 232 概要 証明書検証 CSP の初期化 証明書検証 CSP オブジェクトの破棄 証明書検証に使用するサーバ情報の設定 証明書検証環境に対する認証 証明書検証環境に対する認証の解除 証明書の検証 ICACertificateValidationCSPInit () 証明書検証 CSP の初期化 【機能】 証明書検証 CSP の初期化を行う。 【形式】 ICACertificateValidationCSPHandle ICACertificateValidationCSPInit ( ICACertificateValidationCSPSupportCSP *pCSP, ICAErrorCode *pErr ) 【引数】 pCSP: pErr: 証明書検証 CSP のリスト(IN) 証明書検証 CSP の関数リストが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :証明書検証 SP オブジェクトハンドル(0 以外) 異常終了 :0 【補足】 当関数が返す証明書検証 SP オブジェクトハンドルに対して書き込みを行わない事。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_FAILURE_MALLOC メモリの確保に失敗 233 ICACertificateValidationCSPDestroy () 証明書検証 SP オブジェクトの破棄 【機能】 証明書検証 SP オブジェクトの破棄を行う。 【形式】 ICAReturnCode ICACertificateValidationCSPDestroy ( ICACertificateValidationCSPHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 証明書検証 SP オブジェクトハンドル(IN) 破棄する証明書検証 SP オブジェクトのハンドルが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 証明書検証 SP オブジェクトは、必ず当 API を呼び出して破棄する事。 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER 引数の指定に誤り 234 ICACertificateValidationCSPSetServerInfo () 証明書検証に使用するサーバ情報の設定 【機能】 証明書検証に使用するサーバ情報の設定する。 【形式】 ICAReturnCode ICACertificateValidationCSPSetServerInfo ( ICACertificateValidationCSPHandle hObj, ICACertificateValidationServerInfo *pServerInfo, ICAErrorCode *pErr, ) 【引数】 hObj: pServerInfo: pErr: 証明書検証 SP オブジェクトハンドル(IN) 証明書検証 SP オブジェクトのハンドルが指定される。 証明書検証関連サーバ情報(IN) 証明書検証時に使用するリポジトリなどのサーバにアクセ スする為の情報が指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER 引数の指定に誤り ICAE_LDAP_SERVER_INCORRECT LDAP サーバ指定に誤り ICAE_OCSP_SERVER_INCORRECT OCSP サーバ指定に誤り 235 ICACertificateValidationCSPAttachEnv () 証明書検証環境に対する認証 【機能】 証明書検証環境に対して認証を行う。 【形式】 ICAReturnCode ICACertificateValidationCSPAttachEnv ( ICACertificateValidationCSPHandle hObj, ICAPINData *pPIN, ICAErrorCode *pErr ) 【引数】 hObj: pPIN: pErr: 証明書検証 SP オブジェクトハンドル(IN) 証明書検証 SP オブジェクトのハンドルが指定される。 認証情報(IN) パスワード等の認証情報が指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER 引数の指定に誤り ICAE_INVALID_PIN パスワード不正 ICAE_ENV_ACCESS_DENIED 環境認証エラー ICAE_ENV_ACCESS_FAILED 環境アクセスエラー ICAE_ENV_INVALID 環境構築エラー(環境が正しく構築されていない) ICAE_DEVICE_REMOVED トークン除去 ICAE_DEVICE_FAILURE トークンエラー 236 ICACertificateValidationCSPDetachEnv () 証明書検証環境に対する認証の解除 【機能】 証明書検証環境に対して認証を解除する。 【形式】 ICAReturnCode ICACertificateValidationCSPDetachEnv ( ICACertificateValidationCSPHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 証明書検証 SP オブジェクトハンドル(IN) 証明書検証 SP オブジェクトのハンドルが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 【補足】 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER 引数の指定に誤り ICAE_ENV_ACCESS_FAILED 環境アクセスエラー ICAE_ENV_INVALID 環境構築エラー(環境が正しく構築されていない) ICAE_DEVICE_REMOVED トークン除去 ICAE_DEVICE_FAILURE トークンエラー 237 ICACertificateValidationCSPValidateCertificate () 証明書の検証 【機能】 証明書を検証し検証結果を出力する。また、失効状態についてのチェックも行う。 【形式】 ICAReturnCode ICACertificateValidationCSPValidateCertificate ( ICACertificateValidationCSPHandle hObj, ICACertificateData *pTargetCert, ICACertificateList *pUpperCerts, ICACertificateList *pTrsutAnchors, ICACertificateValidationCondition *pCondition, ICACertificateValidationResult *pCertPath, ICAErrorCode *pErr ) 【引数】 hObj: pTargetCert: pUpperCerts: pTrsutAnchors: pCondition: pCertPath: pErr: 証明書検証 SP オブジェクトハンドル(IN) 証明書検証 SP オブジェクトのハンドルが指定される。 検証する証明書(オブジェクト)(IN) 検証する証明書(オブジェクト)が指定される。 上位の証明書(IN) 上位の証明書が指定される。 トラストアンカーの情報(IN) トラストアンカーの情報が指定される。 検証条件(IN) 証明書検証時の検証条件が指定される。 検証に成功した証明書経路(OUT) 証明書検証の結果、検証に成功した証明書経路を返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 238 【補足】 pCertPath に返る証明書経路の情報通知領域は証明書検証 SP オブジェクトを破棄すると同時に 破棄される為、必要に応じてアプリケーション側で情報をコピーする事。 pCertPath に通知する証明書経路は、 (ICACertificateData 構造体のリストにおいて)リストの 先頭にトラストアンカーの証明書が設定され、次の要素以降は下位の証明書が順次設定される。 リストの末尾は検証対象の証明書が設定される。 戻り値、及び pCertPath への通知は以下の通り。 検証状態 戻り値 pCertPath 証明書経路を構築し、検証 ICAR_SUCCESS 検証に成功した証明書経路を通知する。 対象の証明書の検証まで 完了した。 証明書経路を構築し、検索 ICAR_FAILURE 検証に成功した(一部未完了)証明書経路を 対象の証明書の検証まで 通知する。 行ったが、一部未完了の検 証がある。 1 つも証明書経路を構築 ICAR_FAILURE 通知しない。 できなかった。 証明書経路を構築したが、 ICAR_FAILURE 通知しない。 検証対象の証明書の検証 までに至る証明書経路が 見つからなかった。 239 pErr で返される主なエラー値は以下の通り。 エラーコード 意味 ICAE_INVALID_OTHER 引数の指定に誤り ICAE_ENV_ACCESS_FAILED 環境アクセスエラー ICAE_ENV_INVALID 環境構築エラー(環境が正しく構築されていな い) ICAE_DEVICE_REMOVED トークン除去 ICAE_DEVICE_FAILURE トークンエラー ICAE_CERT_VALIDITY_EXPIRED 証明書が有効期間外である ICAE_CERT_REVOKED 証明書が失効されている ICAE_CERT_DECODE_FAILURE 証明書データ形式不正 ICAE_CERT_VALIDITY_UNKNOWN 検証が一部未完了 ICAE_PATH_CONSTRUCTION_FAIL 証明書経路作成失敗 ICAE_PATH_VALIDATION_FAIL 検証が成功する証明書経路の作成失敗 ICAE_TRUSTANCHOR_NOT_FOUND 証明書経路作成に必要なトラストアンカー不明 ICAE_BASICCONST_PATHLEN_VIOLATION BasicConstraints 内のパス長制限に違反 ICAE_BASICCONST_CA_NOT_TRUE BasicConstraints 内の CA フラグの設定に違反 ICAE_CERTPOLICIES_MISMATCH 受け入れ可能なポリシーが存在しない ICAE_CERT_INVALID_POLICY 証明書経路内に一貫したポリシーが存在しない ICAE_POLICYMAP_INCORRECT PolicyMapping 内の情報不正 ICAE_NAMECONST_NAME_NOT_ACCEPTED NameConstraints 内の情報に違反 ICAE_KEYUSAGE_MISMATCH KeyUsage 内の情報に違反 ICAE_LDAP_COMMUNICATION_FAIL LDAP サーバへの通信エラー ICAE_OCSP_COMMUNICATION_FAIL OCSP サーバへの通信エラー ICAE_OCSP_ACCESS_DENIED OCSP サーバへの検証要求受け付け拒否 ICAE_OCSP_SERVER_INVALID OCSP サーバ不正 ICAE_OCSP_VALIDATION_FAILED OCSP サーバによる検証失敗 ICAE_OCSP_CERT_INVALID OCSP サーバにより無効な証明書と判定 ICAE_NETWORK_TIMEOUT 通信でタイムアウト発生 240 5.9. 失効情報管理 SP 機能 失効情報管理 SP 機能は、失効情報管理媒体(固定ディスク)を用いて、失効情報を管理(保管、 取得、削除)する機能、及び失効情報内部の項目を取得する機能の実体である。 失効情報管理媒体を用いて失効情報を管理する機能は失効情報管理 SP オブジェクトにより実現 する。失効情報内部の項目を取得する機能は APP に提供する API 自体を実体とする。 5.9.1. 失効情報管理 SP オブジェクト 関数名 ICACRLManagementCSPInit ICACRLManagementCSPDestroy ICACRLManagementCSPSetCRL ICACRLManagementCSPGetCRLList ICACRLManagementCSPDeleteCRL ICACRLManagementCSPDeleteAllCRL 概要 失効情報管理 CSP の初期化 失効情報管理 CSP の解放 失効情報の保管 失効情報の取得 失効情報の削除 失効情報の全削除 241 ICACRLManagementCSPInit () 失効管理情報 CSP の初期化 【機能】 失効管理情報 CSP の初期化を行う。 【形式】 ICACRLManagementCSPHandle ICAErrorCode ) ICACRLManagementCSPInit ( *pErr 【引数】 pErr: 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :失効情報管理 SP オブジェクトハンドル 異常終了 :0 242 ICACRLManagementCSPDestroy() 失効情報管理 CSP の解放 【機能】 失効情報管理 CSP の解放を行う。 【形式】 ICAReturnCode ICACRLManagementCSPDestroy( ICACRLManagementCSPHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 失効情報管理 SP オブジェクトハンドル(IN) 解放する失効情報管理 SP オブジェクトハンドルが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 243 ICACRLManagementCSPSetCRL () 失効情報の保管 【機能】 失効情報を保管する。 【形式】 ICAReturnCode ICACRLManagementCSPSetCRL( ICACRLManagementCSPHandle hObj, ICACRLData *pCRLData, ICAErrorCode *pErr ) 【引数】 hObj: pCRLData: pErr: 失効情報管理 SP オブジェクトハンドル(IN) 失効情報管理 SP オブジェクトハンドルが指定される。 CRL (IN) 保存したい CRL が指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 244 ICACRLManagementCSPGetCRLList () 保存されている失効情報リストの取得 【機能】 保存されている失効情報を取得する。 【形式】 ICAReturnCode ICACRLManagementCSPGetCRLList ( ICACRLManagementCSPHandle hObj, ICACRLList *pCRLList, ICAErrorCode *pErr ) 【引数】 hObj: pCRLList: pErr: 失効情報管理 SP オブジェクトハンドル(IN) 失効情報管理 SP オブジェクトハンドルが指定される。 CRL リスト(OUT) 保存されている CRL のリストのポインタを返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 245 ICACRLManagementCSPDeleteCRL () 失効情報の削除 【機能】 失効情報を削除する。 【形式】 ICAReturnCode ICACRLManagementCSPDeleteCRL( ICACRLManagementCSPHandle hObj, ICACRLData *pCRLData, ICAErrorCode *pErr ) 【引数】 hObj: pCRLData: pErr: 失効情報管理 SP オブジェクトハンドル(IN) 失効情報管理 SP オブジェクトハンドルが指定される。 CRL (IN) 削除対象の CRL が指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 246 ICACRLManagementCSPDeleteAllCRL () すべての失効情報の削除 【機能】 すべての失効情報を削除する。 【形式】 ICAReturnCode ICACRLManagementCSPDeleteAllCRL( ICACRLManagementCSPHandle hObj, ICAErrorCode *pErr ) 【引数】 hObj: pErr: 失効情報管理 SP オブジェクトハンドル(IN) 失効情報管理 SP オブジェクトハンドルが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 :ICAR_SUCCESS 異常終了 :ICAR_FAILURE 247 6. SP 側で使用する型定義 以下のものを除き、 「3APP 側 API で使用する型定義」を参照の事。また、これらの内容に関しては、CSP に 依存し規定しない。 ・ ・ ・ ・ ・ ・ 署名生成 SP オブジェクト 署名検証 SP オブジェクト 親展 SP オブジェクト 親展解除 SP オブジェクト 証明書検証 SP オブジェクト 失効管理 SP オブジェクト 248 ICASignatureCSPHandle 【機能】 署名生成 CSP 固有オブジェクトハンドル。 【形式】 typedef void *ICASignatureCSPHandle; ICAVerificationCSPHandle 【機能】 署名検証 CSP 固有オブジェクトハンドル。 【形式】 typedef void *ICAVerificationCSPHandle; 249 ICAEncryptionCSPHandle 【機能】 親展 CSP 固有オブジェクトハンドル。 【形式】 typedef void *ICAEncryptionCSPHandle; I CADecryptionCSPHandle 【機能】 親展解除 CSP 固有オブジェクトハンドル。 【形式】 typedef void * ICADecryptionCSPHandle; 250 ICACertificateValidationCSPHandle 【機能】 証明書検証 CSP 固有オブジェクトハンドル。 【形式】 typedef void* ICACertificateValidationCSPHandle; ICACRLManagementCSPHandle 【機能】 失効情報管理 CSP 固有オブジェクトハンドル。 【形式】 typedef void* ICACRLManagementCSPHandle; 251 7. 付録 7.1. Crypto−API 仕様設計の論点について Crypto-API 仕様設計のポイントとして、検討会等の設計過程で論点となった主な事項を以下 に示す。 (1) 証明書検証機能について 証明書検証機能については、一連の基礎的な機能(認証パス構築、認証パス検証及び証明書 有効性検証等)で構成することによって自由度/汎用性の高い API とすることを目指すか、PKI アプリケーション・プログラムの開発者にとってできるだけ簡便な自動化指向の API とすること を目指すかが論点となった。Crypto-API では、普及を睨んで簡便であることを重視して、後者 のアプローチを選択した。 ただし、簡便な証明書検証 API が成り立つためには、いくつかの前提が必要なので、電子政 府/GPKI というスコープでどういう前提条件を置けば証明書検証処理を自動的なものにできる かを検討・明確化しながら、PKI アプリケーション・プログラムの開発者にとって簡便な API 仕 様となるように証明書検証機能を設計した。 [一連の基礎的な機能で構成する場合の長所/短所] ① 長所:自由度/汎用性が高い。 ② 短所:証明書検証に関する専門的知識が必要となるので、PKI アプリケーション・プ ログラムの開発者が苦労しそうであり、普及しにくいであろう。 [簡便な自動化指向の API とする場合の長所/短所] ① 長所:一回の証明書検証要求を行えば、検証に必要な情報の収集、認証パス構築、 認証パス検証及び証明書有効性検証といった一連の処理を PKI ライブラリが自動的 に実施してくれ、最終検証結果を得られるので、PKI アプリケーション・プログラ ムの開発者は楽である。 特に、検証に必要な証明書、相互認証証明書対及び失効情報(失効リスト等)を自 動的に収集してくれる点が大きい。証明書検証に関する専門的知識は少なくて済む ので、普及しやすいであろう。 ② 短所:自由度/汎用性が低下する。また、自動化を進めるには前提条件を置く必要 がある。ただし、電子政府/GPKI の世界に対して合理的な前提条件を置くこと、そ してその分自由度が低下することは差し支えないと考えられる。また、証明書検証 仕様に関して今後種々の変更要求が発生したとしても、証明書検証仕様独立機構に 従って証明書検証 CSP を切り替えることによって殆ど対応可能と考えられる。 (証明書検証機能における前提条件については、Crypto-API 仕様書の付録を参照。 ) 252 (2) 鍵管理機能・証明書管理機能について 秘密鍵や証明書を管理するハードウェア・トークンのアクセスインタフェースの業界標準と して PKCS#11 仕様が普及・浸透している。Crypto-API の鍵管理機能・証明書検証機能として、 自由度/汎用性を重視してこの PKCS#11 仕様を踏襲するか、PKI アプリケーション・プログラム の開発者にとってできるだけ簡便な API とすることを目指すかが論点となった。Crypto-API で は、自由度/汎用性を重視して、前者のアプローチを選択した。また、電子政府/GPKI という スコープで不要と考えられる PKCS#11 仕様部分を除外してサブセット化した。 [PKCS#11 仕様を踏襲する場合の長所/短所] ① 長所:自由度/汎用性が高い。今後の PKI アプリケーションのニーズに対応して鍵 管理機能・証明書管理機能を見直す必要が殆どない。 ② 短所:基礎的な API であり、簡便な API の場合と比べて、PKI アプリケーション・プ ログラム開発者の負担が増える。 なお、今後の PKI アプリケーションのニーズに対応して問題向きの簡便な PKI ライ ブラリ機能を必要に応じて当 Crypto-API ライブラリ層の上に追加・提供して行くこ とによって、その負担を軽減することができる。 [簡便な API とする場合の長所/短所] ① 長所:PKI アプリケーション・プログラム開発者の負担が少ない。ただし、短所が顕 在化すれば API 変更が必要となり、必ずしも負担が少ないとは言えなくなる。 ② 短所:自由度/汎用性が低い。今後の PKI アプリケーションのニーズに対応して機 能を見直さなければならないリスクが大きい。(今まで要求に応じて複数の鍵管理 機能・証明書管理機能が作成されて来ている経験から、そう判断できる。 ) (3) 鍵用途について 最近の動向として鍵用途(Key Usage)を署名用、守秘用等に分けて複数の鍵を用途に応じて 使い分けられるようにするケースが増えつつあり、PKI ライブラリとしてもこれに対応すること が望まれる。 (なお、現行 GPKI の仕様では、例えば官職の鍵用途を署名用(ディジタル署名及び否認防止) に指定してはいるが、鍵をその一種類に限定している。 ) このように鍵用途が論点の一つになったが、Crypto-API という基礎的な PKI ライブラリ層で は、鍵オブジェクトによって鍵を選択することから(証明書又は証明書識別情報によって鍵を選 択するインタフェースではないことから) 、次の認識であることを確認した。 ① 鍵用途の管理機能は Crypto-API を使用するアプリケーション・プログラム(又は上位層 の PKI ライブラリ)の担当機能になること ② 証明書検証 CSP が提供する機能には、鍵用途を検証する機能も含められること ③ 上記①と②によって、鍵用途による鍵の使い分けが可能になること 253 7.2. 証明書検証 SP 機能における前提条件 証明書の検証は、関連する認証局の信用関係のモデルや使用する証明書のプロファイルなど、様々 な要因に依存する。そのため、多くの要因に対応するためには、証明書検証を行なう機能に対し て、要因に応じて動作を選択するための入力が必要となる。 しかし、動作を選択するための入力を証明書検証 SP 機能へのパラメタとした場合には、これらの 要因が利用側にまで透過となり、入力パラメタの複雑化による利用側への負担増加が生じるとと もに、証明書検証ライブラリの亜流が生じやすく、結果としてライブラリからの独立性が失われ ることが懸念される。 そのため、 Crypto-API の仕様策定においては、 用途を電子政府 PKI アプリケーションの構築とし、 一定の前提条件を設けることにより、仕様の共通化を行い、ライブラリからの独立性を重視した 設計を行なっている。 ここでは、証明書検証 SP 機能を策定した際に、想定した前提条件や方針について説明する。 7.2.1. 証明書のパス構築における前提条件 7.2.1.1. 信頼点(トラストアンカー)の種類 使用する信頼点の種類は全体で一つとしている。電子政府システムにおいては、信頼点の種類を、 証明書用、CRL 用、OCSP 用と区別する要件はあげられていないため、全体で一つの種類としてい る。 7.2.1.2. パス構築に必要な証明書の収集 パス構築に必要な中間認証局の証明書や相互認証証明書は、利用側からの入力を必須とせず、証 明書検証 SP の中で収集することを基本としている。証明書検証 SP の中にパス構築に必要な論理 を隠蔽することにより、利用側の独立性を持たせている。細かなカストマイズは API 以外の証明 書検証 SP の機能とするか、証明書検証 SP を切り替えることにより実現する方針である。 例えば、以下のケースでは、利用するシステムに応じて証明書検証 SP を切り替えることにより対 応をすることを想定している。 ・ 相互認証が存在する認証局の信頼関係のモデルにおいて、自己署名証明書をパスの中に含め るか否か。 ・ 証明書内の個別 extension を解釈するか否か。 7.2.2. 検証における前提条件 7.2.2.1. 検証日時の扱い 有効性の検証は、証明書検証 SP の検証時刻により行う。検証時刻を外部から与える場合には、長 期保存など別な技術も必要であり、将来課題としている。 7.2.2.2. 失効確認に必要な情報の収集 証明書の失効確認を行うための情報は、パス構築に必要な証明書の扱いと同様に、利用側からの 入力を必須とせず、証明書検証 SP の中で収集することを基本としている。細かなカストマイズは API 以外の証明書検証 SP とするか、 証明書検証 SP を切り替えることにより実現する方針である。 7.2.3. その他、環境などにおける前提条件 7.2.3.1. トークンの扱い 使用できるトークンは全体で一つとしている。同時に使用されるトークンは一つと考え、また、 トークンを特定するためのスロットなどの物理的な情報については、 SP に隠蔽することにより、 、 利用側の独立性を持たせている。 7.2.3.2. サーバ接続時の認証 CRL を格納するリポジトリや OCSP レスポンダは、anonymous でアクセスできるものとしている。 電子政府システムにおいては、これらのサーバは anonymous でアクセスできる仕様となっており、 認証については、将来課題としている。 254 7.3. 定数値一覧 Crypto-API で定義している定数値の一覧を記載する。 Bool32 には以下の値を定義している。 #define ICAB_FALSE 0 #define ICAB_TRUE (!ICAB_FALSE) ICAReturnCode には以下の値を定義している。 #define ICAR_SUCCESS 0 #define ICAR_FAILURE 1 ICAErrorCode には以下の値を定義している。 #define ICAE_OK #define ICAE_INVALID_DATA #define ICAE_INVALID_DATA_LENGTH #define ICAE_INVALID_KEY #define ICAE_INVALID_KEY_LENGTH #define ICAE_INVALID_KEY_HANDLE #define ICAE_INVALID_KEY_OR_DATA #define ICAE_INVALID_ALGORITHM #define ICAE_INVALID_ALGORITHM_PARAM #define ICAE_INVALID_SIGNATURE #define ICAE_INVALID_SIGNATURE_LENGTH #define ICAE_INVALID_OTHER #define ICAE_FAILURE_KEYGEN #define ICAE_FAILURE_MALLOC #define ICAE_DEVICE_FAILURE #define ICAE_DEVICE_REMOVED #define ICAE_DEVICE_FAILURE_MALLOC #define ICAE_SESSION_INVALID_HANDLE #define ICAE_SESSION_USER_NOT_LOGGED_IN #define ICAE_SESSION_CLOSED #define ICAE_CERT_REVOKED #define ICAE_CERT_VALIDITY_EXPIRED #define ICAE_PATH_CONSTRUCTION_FAIL #define ICAE_PATH_VALIDATION_FAIL #define ICAE_KEYUSAGE_MISMATCH #define ICAE_BASICCONST_CA_NOT_TRUE #define ICAE_BASICCONST_PATHLEN_VIOLATION #define ICAE_NAMECONST_NAME_NOT_ACCEPTED #define ICAE_CERTPOLICIES_MISMATCH #define ICAE_CERT_INVALID_POLICY #define ICAE_POLICYMAP_INCORRECT #define ICAE_CERT_DECODE_FAILURE #define ICAE_CERT_VALIDITY_UNKNOWN #define ICAE_TRUSTANCHOR_NOT_FOUND #define ICAE_ENV_ACCESS_DENIED #define ICAE_ENV_ACCESS_FAILED #define ICAE_ENV_INVALID #define ICAE_LDAP_COMMUNICATION_FAIL #define ICAE_LDAP_SERVER_INCORRECT #define ICAE_OCSP_COMMUNICATION_FAIL #define ICAE_OCSP_SERVER_INCORRECT 255 0x00000000 0x01000100 0x01000101 0x01000200 0x01000201 0x01000210 0x01000300 0x01000800 0x01000801 0x01002200 0x01002201 0x0100FF00 0x02000000 0x03000000 0x09000000 0x09000100 0x0900A100 0x0C001100 0x0C003100 0x0C005100 0x11001000 0x11002200 0x14001001 0x14001002 0x18001510 0x18001913 0x18001930 0x18003010 0x18003210 0x18003232 0x18003320 0x1F00FF01 0x20001000 0x20002000 0x20004100 0x20004200 0x20004300 0x20004400 0x20004500 0x20004600 0x20004700 #define #define #define #define #define #define #define #define ICAE_NETWORK_TIMEOUT ICAE_OCSP_ACCESS_DENIED ICAE_OCSP_SERVER_INVALID ICAE_OCSP_VALIDATION_FAILED ICAE_OCSP_CERT_INVALID ICAE_OTHER ICAE_FUNCTION_FAILED ICAE_FATAL_ERROR ICAKeyObject の KeyType には以下の値を定義している。 #define ICAKRSAPublic 0x00010001 #define ICAKRSAPrivate 0x00010002 #define ICAKRSAKeyPair 0x00010003 #define ICAKRSAPrivateT 0x00010006 #define ICAKECPublic 0x00020001 #define ICAKECPrivate 0x00020002 #define ICAKECKeyPair 0x00020003 #define ICAKECPrivateT 0x00020006 256 0x20004800 0x20008100 0x20008200 0x20008300 0x20008400 0xFF000000 0xFFFF0000 0xFFFFFFFF 7.4. 基本暗号 SP 機能 API 仕様 付録として、Crypto-API の仕様範囲外であるが、親展 SP 機能及び親展解除 SP 機能の内部で使 用する基本暗号 SP 機能(共通鍵暗号)の CSP の仕様を記述する。 テストプログラム Crypto-API 親展 CSP 親展解除 CSP 基本暗号 SP 機能 ・共通鍵生成 SP 機能 ・共通鍵暗号化 SP 機能 ・共通鍵復号 SP 機能 7.4.1. 共通鍵生成 SP 機能 共通鍵暗号アルゴリズムにおいて共通鍵の生成機能を提供する。 7.4.1.1. 共通鍵生成 SP オブジェクト 関数名 ICASymmetricKeyGenerationCSPInit ICASymmetricKeyGenerationCSPDestroy ICASymmetricKeyGenerationCSPSetAlgorithm ICASymmetricKeyGenerationCSPGetKey 257 機能 共通鍵生成 CSP の初期化 共通鍵生成 CSP の解放 共通鍵暗号の鍵生成アルゴリズムの設定 共通鍵の取得 ICASymmetricKeyGenerationCSPInit() CSP の初期化 【機能】 共通鍵生成 CSP の初期化を行う。 【形式】 ICAReturnCode ICASymmetricKeyGenerationCSPInit( ICASymmetricKeyGenerationSPObject **ppObj, ICAErrorCode *pErr ) 【引数】 ppObj: pErr: 共通鍵生成 SP オブジェクトの格納領域(OUT) 共通鍵生成 SP オブジェクトを返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 以後、オブジェクトに対するメソッド関数の実行に必要なメモリ領域は、オブジェクトに よって動的に確保される。 これらの領域を解放する為には、操作終了時に ICASymmetricKeyGenerationCSPDestroy()を 実行し、オブジェクトを破棄する必要がある。 258 ICASymmetricKeyGenerationCSPDestroy() CSP の解放 【機能】 共通鍵生成 CSP の解放を行う。同時に本オブジェクトに対する関数実行により確保され た領域も解放する。 【形式】 ICAReturnCode ICASymmetricKeyGenerationCSPDestroy( ICASymmetricKeyGenerationSPObject *pObj, ICAErrorCode *pErr ) 【引数】 pObj: pErr: 共通鍵生成 SP オブジェクト(IN) 共通鍵生成 SP オブジェクトが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 ICASymmetricKeyGenerationCSPInit()で生成したオブジェクトは、使用後に本関数を使用して 破棄する必要がある。本関数の実行により、オブジェクト内部で動的に確保された領域は、 すべて解放される。 オブジェクト内部の鍵データを保存する場合は、本関数の実行前にユーザ側でコピーしておく 必要がある。 259 ICASymmetricKeyGenerationCSPSetAlgorithm() アルゴリズムの設定 【機能】 共通鍵暗号の鍵生成アルゴリズムを設定する。 【形式】 ICAReturnCode ICASymmetricKeyGenerationCSPSetAlgorithm( ICASymmetricKeyGenerationSPObject *pObj, ICASymmetricKeyAlgorithm *pAlgorithm, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: 共通鍵生成 SP オブジェクト(IN) 共通鍵生成 SP オブジェクトが指定される。 pAlgorithm: 共通鍵暗号の鍵生成アルゴリズム(IN) 共通鍵暗号の鍵生成アルゴリズムの格納領域を設定する。 構造体の詳細は、 「7.5.2共通鍵暗号化」を参照の事。 pReason: 異常終了時のエラー理由(OUT) アルゴリズムの設定が異常終了した場合の理由を返す。 pErr: 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 pReason に返される主なエラー理由は以下の通り。 pReason の値 意味 ICAREASON_INVALID_ALGORITHM アルゴリズム不正 ICAREASON_INVALID_SEED 乱数発生ルーチン初期値不正 ICAREASON_FATAL_ERROR 回復不能な致命的エラー発生 260 ICASymmetricKeyGenerationCSPGetKey() 共通鍵の取得 【機能】 生成された共通鍵を取得する。 【形式】 ICAReturnCode ICASymmetricKeyGenerationCSPGetKey( ICASymmetricKeyGenerationSPObject *pObj, ICASymmetricKey *pSymmetricKey, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: pSymmetricKey: pReason: pErr: 共通鍵生成 SP オブジェクト(IN) 共通鍵生成 SP オブジェクトが指定される。 共通鍵の格納領域(OUT) 共通鍵の格納領域を設定する。 異常終了時のエラー理由(OUT) 共通鍵の取得が異常終了した場合の理由を返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 取得したデータ(ICASymmetricKey 型)の、オクテット列へのポインタには、共通鍵生成 SP オブジェクト内部のオクテット列格納領域へのポインタがセットされている。 取得したデータの内部領域には書き込み動作を行わない事。 pReason に返される主なエラー理由は以下の通り。 pReason の値 意味 ICAREASON_FAILURE_KEYGEN 共通鍵生成に失敗 ICAREASON_FATAL_ERROR 回復不能な致命的エラー発生 261 7.4.2. 共通鍵暗号化 SP 機能 共通鍵暗号を使用した暗号化機能を提供する。 7.4.2.1. 共通鍵暗号化 SP オブジェクト 関数名 機能 ICASymmetricKeyEncryptionCSPInit ICASymmetricKeyEncryptionCSPDestroy 共通鍵暗号 CSP の初期化 共通鍵暗号 CSP の解放 ICASymmetricKeyEncryptionCSPSetAlgorithm ICASymmetricKeyEncryptionCSPSetKey ICASymmetricKeyEncryptionCSPSetData ICASymmetricKeyEncryptionCSPAddData ICASymmetricKeyEncryptionCSPGetEncryptedData ICASymmetricKeyEncryptionCSPGetEncryptedDataFinal 共通鍵暗号アルゴリズムの設定 共通鍵の設定 平文データの設定 平文データの追加設定 暗号文データの取得 最後の暗号文データの取得 262 ICASymmetricKeyEncryptionCSPInit() CSP の初期化 【機能】 共通鍵暗号化 CSP の初期化を行う。 【形式】 ICAReturnCode ICASymmetricKeyEncryptionCSPInit( ICASymmetricKeyEncryptionSPObject **ppObj, ICAErrorCode *pErr ) 【引数】 ppObj: pErr: 共通鍵暗号化 SP オブジェクトの格納領域(OUT) 共通鍵生成 SP オブジェクトを返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 以後、オブジェクトに対するメソッド関数の実行に必要なメモリ領域は、オブジェクトによって 動的に確保される。 これらの領域を解放する為には、操作終了時に ICASymmetricKeyEncryptionCSPDestroy()を 実行し、オブジェクトを破棄する必要がある。 263 ICASymmetricKeyEncryptionCSPDestroy() CSP の解放 【機能】 共通鍵暗号化 CSP の解放を行う。同時に本オブジェクトに対する関数実行により確保さ れた領域も解放する。 【形式】 ICAReturnCode ICASymmetricKeyEncryptionCSPDestroy( ICASymmetricKeyEncryptionSPObject *pObj, ICAErrorCode *pErr ) 【引数】 pObj: pErr: 共通鍵暗号化 SP オブジェクト(IN) 共通鍵暗号化 SP オブジェクトが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 ICASymmetricKeyEncryptionCSPInit()で生成したオブジェクトは、使用後に本関数を使用して 破棄する必要がある。本関数の実行により、オブジェクト内部で動的に確保された領域は、 すべて解放される。 オブジェクト内部の鍵データを保存する場合は、本関数の実行前にユーザ側でコピーしておく 必要がある。 264 ICASymmetricKeyEncryptionCSPSetAlgorithm() アルゴリズムの設定 【機能】 共通鍵暗号アルゴリズムを設定する。 【形式】 ICAReturnCode ICASymmetricKeyEncryptionCSPSetAlgorithm ( ICASymmetricKeyEncryptionSPObject *pObj, ICASymmetricKeyAlgorithm *pAlgorithm, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: 共通鍵暗号化 SP オブジェクト(IN) 共通鍵暗号化 SP オブジェクトが指定される。 pAlgorithm: 共通鍵暗号アルゴリズム(IN) 共通鍵暗号アルゴリズムの格納領域を設定する。 構造体の詳細は、 「7.5.2共通鍵暗号化」を参照の事。 pReason: 異常終了時のエラー理由(OUT) アルゴリズムの設定が異常終了した場合の理由を返す。 pErr: 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 pReason に返されるエラー理由とその意味は以下の通り。 pReason の値 意味 ICAREASON_INVALID_ALGORITHM アルゴリズム不正 ICAREASON_INVALID_ALGORITHM_PARAM アルゴリズムのパラメータ不正 ICAREASON_FATAL_ERROR 回復不能な致命的エラー発生 265 ICASymmetricKeyEncryptionCSPSetKey() 共通鍵の設定 【機能】 暗号化に使用する共通鍵を設定する。 【形式】 ICAReturnCode ICASymmetricKeyEncryptionCSPSetKey( ICASymmetricKeyEncryptionSPObject *pObj, ICASymmetricKey *pSymmetricKey, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: pSymmetricKey: pReason: pErr: 共通鍵暗号化 SP オブジェクト(IN) 共通鍵暗号化 SP オブジェクトが指定される。 共通鍵(IN) 共通鍵を設定する。 異常終了時のエラー理由(OUT) 共通鍵の設定が異常終了した場合の理由を返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 pReason に返される主なエラー理由は以下の通り。 pReason の値 意味 ICAREASON_INVALID_KEY 共通鍵不正 ICAREASON_INVALID_KEY_LENGTH ICAREASON_FATAL_ERROR 共通鍵の長さ不正 回復不能な致命的エラー発生 266 ICASymmetricKeyEncryptionCSPSetData() 平文データの設定 【機能】 暗号化対象の平文データを設定する。 【形式】 ICAReturnCode ICASymmetricKeyEncryptionCSPSetData( ICASymmetricKeyEncryptionSPObject *pObj, ICAData *pData, ICADataOpt *pRandomSeedOpt, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: pData: pRandomSeedOpt: pReason: pErr: 共通鍵暗号化 SP オブジェクト(IN) 共通鍵暗号化 SP オブジェクトが指定される。 平文データ(IN) 暗号化する平文データを設定する。 予備(IN) ICADataOpt のメンバーopt に ICAOPT_ABSENT を必ず設定する事。 異常終了時のエラー理由(OUT) 共通鍵の設定が異常終了した場合の理由を返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 本メソッド関数を実行した際、分割暗号化の過程で共通鍵暗号化 SP オブジェクト内部に 保管されていた中間データは破棄される。 分割暗号化を行う場合、2回目以降のデータ入力には、ICASymmetricKeyEncryptionCSPAddData() を使用する事。 pReason に返される主なエラー理由は以下の通り。 pReason の値 意味 ICAREASON_INVALID_DATA 暗号化失敗(平文データ不正) ICAREASON_INVALID_DATA_LENGTH 平文データの長さ不正 ICAREASON_INVALID_SEED 予備パラメータの指定誤り ICAREASON_FAILURE_MALLOC メモリ確保に失敗 ICAREASON_FATAL_ERROR 回復不能な致命的エラー発生 267 ICASymmetricKeyEncryptionCSPAddData() 平文データの追加設定 【機能】 分割暗号化を行う場合、2回目以降の平文データを設定する。 【形式】 ICAReturnCode ICASymmetricKeyEncryptionCSPAddData( ICASymmetricKeyEncryptionSPObject *pObj, ICAData *pData, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: pData: pReason: pErr: 共通鍵暗号化 SP オブジェクト(IN) 共通鍵暗号化 SP オブジェクトが指定される。 平文データ(IN) 暗号化する平文データを設定する。 異常終了時のエラー理由(OUT) 共通鍵の設定が異常終了した場合の理由を返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 pReason に返される主なエラー理由は以下の通り。 pReason の値 意味 ICAREASON_INVALID_DATA 暗号化失敗(平文データ不正) ICAREASON_INVALID_DATA_LENGTH 平文データの長さ不正 ICAREASON_FAILURE_MALLOC メモリ確保に失敗 ICAREASON_FATAL_ERROR 回復不能な致命的エラー発生 268 ICASymmetricKeyEncryptionCSPGetEncryptedData() 暗号文データの取得 【機能】 暗号文データを取得する。 【形式】 ICAReturnCode ICASymmetricKeyEncryptionCSPGetEncryptedData ( ICASymmetricKeyEncryptionSPObject *pObj, ICAData *pEncryptedData, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: pEncryptedData: pReason: pErr: 共通鍵暗号化 SP オブジェクト(IN) 共通鍵暗号化 SP オブジェクトが指定される。 暗号文データの格納領域(OUT) 暗号文データを返す。 異常終了時のエラー理由(OUT) 暗号文データの取得が異常終了した場合の理由を返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 本関数では、ICASymmetricKeyEncryptionCSPSetData()/AddData()を用いて共通鍵暗号化 SP オブジェクトに設定されたデータに対し、適切な長さの部分に対する暗号化を行う。 オブジェクト内部のデータの長さが暗号化に適切でない(暗号化処理しきれない中途半端なデー タが残った)場合、それらのデータはオブジェクト内部の中間データとして自動的に保管される。 取得した暗号文データ(ICAData 型)の、オクテット列へのポインタには、共通鍵暗号化 SP オブジェクト内部のオクテット列格納領域へのポインタがセットされている。取得したデータの 内部領域には書き込み動作を行わない事。 pReason に返される主なエラー理由は以下の通り。 pReason の値 意味 ICAREASON_FATAL_ERROR 回復不能な致命的エラー発生 269 ICASymmetricKeyEncryptionCSPGetEncryptedDataFinal() 最後の暗号文データの取得 【機能】 残されている最後の暗号文データを取得する。 【形式】 ICAReturnCode ICASymmetricKeyEncryptionCSPGetEncryptedDataFinal( ICASymmetricKeyEncryptionSPObject *pObj, ICAData *pEncryptedData, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: pEncryptedData: pReason: pErr: 共通鍵暗号化 SP オブジェクト(IN) 共通鍵暗号化 SP オブジェクトが指定される。 暗号文データの格納領域(OUT) 暗号文データを返す。 異常終了時のエラー理由(OUT) 暗号文データの取得が異常終了した場合の理由を返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 本関数では、共通鍵暗号化 SP オブジェクトに設定されたデータのうち、残ったデータ全体に 対する暗号化を行う。オブジェクト内部のデータの長さが暗号化に適切でない場合、指定した 暗号アルゴリズムに対応したパディング処理を行った後、暗号化を行う。 取得した暗号文データ(ICAData 型)の、オクテット列へのポインタには、共通鍵暗号化 SP オブジェクト内部のオクテット列格納領域へのポインタがセットされている。取得したデータの 内部領域には書き込み動作を行わない事。 pReason に返される主なエラー理由は以下の通り。 pReason の値 意味 ICAREASON_INVALID_DATA ICAREASON_INVALID_DATA_LENGTH ICAREASON_FAILURE_MALLOC 暗号化失敗(平文データ不正) 平文データの長さ不正 メモリ確保に失敗 ICAREASON_FATAL_ERROR 回復不能な致命的エラー発生 270 7.4.3. 共有鍵復号 SP 機能 共通鍵暗号を使用した復号機能を提供する。 7.4.3.1. 共通鍵復号 SP オブジェクト 関数名 機能 ICASymmetricKeyDecryptionCSPInit 共通鍵復号 CSP の初期化 ICASymmetricKeyDecryptionCSPDestroy 共通鍵復号 CSP の解放 ICASymmetricKeyDecryptionCSPSetAlgorithm ICASymmetricKeyDecryptionCSPSetKey ICASymmetricKeyDecryptionCSPSetEncryptedData 共通鍵暗号アルゴリズムの設定 共通鍵の設定 暗号文データの設定 ICASymmetricKeyDecryptionCSPAddEncryptedData 暗号文データの追加設定 ICASymmetricKeyDecryptionCSPGetData ICASymmetricKeyDecryptionCSpGetDataFinal 平文データの取得 最後の平文データの取得 271 ICASymmetricKeyDecryptionCSPInit() CSP の初期化 【機能】 共通鍵復号 CSP の初期化を行う。 【形式】 ICAReturnCode ICASymmetricKeyDecryptionCSPInit( ICASymmetricKeyDecryptionSPObject **ppObj, ICAErrorCode *pErr ) 【引数】 ppObj: pErr: 共通鍵復号 SP オブジェクトの格納領域(OUT) 共通鍵復号 SP オブジェクトを返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 以後、オブジェクトに対するメソッド関数の実行に必要なメモリ領域は、オブジェクトによって 動的に確保される。 これらの領域を解放する為には、操作終了時に ICASymmetricKeyDecryptionCSPDestroy()を 実行し、オブジェクトを破棄する必要がある。 272 ICASymmetricKeyDecryptionCSPDestroy() CSP の解放 【機能】 共通鍵復号 CSP の解放を行う。同時に本オブジェクトに対する関数実行により確保され た領域も解放する。 【形式】 ICAReturnCode ICASymmetricKeyDecryptionCSPDestroy( ICASymmetricKeyDecryptionSPObject *pObj, ICAErrorCode *pErr ) 【引数】 pObj: pErr: 共通鍵復号 SP オブジェクト(IN) 共通鍵復号 SP オブジェクトが指定される。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 ICASymmetricKeyDecryptionCSPInit()で生成したオブジェクトは、使用後に本関数を使用して 破棄する必要がある。本関数の実行により、オブジェクト内部で動的に確保された領域は、 すべて解放される。 オブジェクト内部の鍵データを保存する場合は、本関数の実行前にユーザ側でコピーしておく 必要がある。 273 ICASymmetricKeyDecryptionCSPSetAlgorithm() アルゴリズムの設定 【機能】 共通鍵暗号アルゴリズムを設定する。 【形式】 ICAReturnCode ICASymmetricKeyDecryptionCSPSetAlgorithm ( ICASymmetricKeyDecryptionSPObject *pObj, ICASymmetricKeyAlgorithm *pAlgorithm, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: 共通鍵復号 SP オブジェクト(IN) 共通鍵復号 SP オブジェクトが指定される。 pAlgorithm: 共通鍵暗号アルゴリズム(IN) 共通鍵暗号アルゴリズムの格納領域を設定する。 構造体の詳細は、 「7.5.2共通鍵暗号化」を参照の事。 pReason: 異常終了時のエラー理由(OUT) アルゴリズムの設定が異常終了した場合の理由を返す。 pErr: 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 pReason に返されるエラー理由とその意味は以下の通り。 pReason の値 意味 ICAREASON_INVALID_ALGORITHM ICAREASON_INVALID_ALGORITHM_PARAM ICAREASON_FATAL_ERROR 274 アルゴリズム不正 アルゴリズムのパラメータ不正 回復不能な致命的エラー発生 ICASymmetricKeyDecryptionCSPSetKey() 共通鍵の設定 【機能】 暗号化に使用した共通鍵を設定する。 【形式】 ICAReturnCode ICASymmetricKeyDecryptionCSPSetKey( ICASymmetricKeyDecryptionSPObject *pObj, ICASymmetricKey *pSymmetricKey, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: pSymmetricKey: pReason: pErr: 共通鍵復号 SP オブジェクト(IN) 共通鍵復号 SP オブジェクトが指定される。 共通鍵(IN) 共通鍵を設定する。 異常終了時のエラー理由(OUT) 共通鍵の設定が異常終了した場合の理由を返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 pReason に返される主なエラー理由は以下の通り。 pReason の値 意味 ICAREASON_INVALID_KEY 共通鍵不正 ICAREASON_INVALID_KEY_LENGTH ICAREASON_FATAL_ERROR 共通鍵の長さ不正 回復不能な致命的エラー発生 275 ICASymmetricKeyDecryptionCSPSetEncryptedData() 暗号文データの設定 【機能】 暗号文データを設定する。 【形式】 ICAReturnCode ICASymmetricKeyDecryptionCSPSetEncryptedData( ICASymmetricKeyDecryptionSPObject *pObj, ICAData *pEncryptedData, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: pEncryptedData: pReason: pErr: 共通鍵復号 SP オブジェクト(IN) 共通鍵復号 SP オブジェクトが指定される。 暗号文データ(IN) 復号する暗号文データを設定する。 異常終了時のエラー理由(OUT) 暗号文データの設定が異常終了した場合の理由を返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 本メソッド関数を実行した際、分割復号の過程で共通鍵復号 SP オブジェクト内部に保管されて いた中間データは破棄される。分割復号を行う場合、2回目以降のデータ入力には、 ICASymmetricKeyDecryptionCSPAddEncryptedData()を使用する事。 pReason に返される主なエラー理由は以下の通り。 pReason の値 意味 ICAREASON_INVALID_DATA ICAREASON_INVALID_DATA_LENGTH 復号失敗(暗号文データ不正) 暗号文データの長さ不正 ICAREASON_FAILURE_MALLOC メモリ確保に失敗 ICAREASON_FATAL_ERROR 回復不能な致命的エラー発生 276 ICASymmetricKeyDecryptionCSPAddEncryptedData() 暗号文データの追加設定 【機能】 分割復号を行う場合、2回目以降の暗号文データを設定する。 【形式】 ICAReturnCode ICASymmetricKeyDecryptionCSPAddEncryptedData( ICASymmetricKeyDecryptionSPObject *pObj, ICAData *pEncryptedData, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: pEncryptedData: pReason: pErr: 共通鍵復号 SP オブジェクト(IN) 共通鍵復号 SP オブジェクトが指定される。 暗号文データ(IN) 復号する暗号文データを設定する。 異常終了時のエラー理由(OUT) 暗号文データの設定が異常終了した場合の理由を返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 pReason に返される主なエラー理由は以下の通り。 pReason の値 意味 ICAREASON_INVALID_DATA ICAREASON_INVALID_DATA_LENGTH 復号失敗(暗号文データ不正) 暗号文データの長さ不正 ICAREASON_INVALID_KEY_OR_DATA 復号失敗(共通鍵または暗号文データ不正) ICAREASON_FAILURE_MALLOC ICAREASON_FATAL_ERROR メモリ確保に失敗 回復不能な致命的エラー発生 277 ICASymmetricKeyDecryptionCSPGetData() 平文データの取得 【機能】 復号された平文データを取得する。 【形式】 ICAReturnCode ICASymmetricKeyDecryptionCSPGetData ( ICASymmetricKeyDecryptionSPObject *pObj, ICAData *pData, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: pData: pReason: pErr: 共通鍵復号 SP オブジェクト(IN) 共通鍵復号 SP オブジェクトが指定される。 平文データの格納領域(OUT) 復号された平文データを返す。 異常終了時のエラー理由(IN) 平文データの取得が異常終了した場合の理由を返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 本関数では、ICASymmetricKeyDecryptionCSPSetEncryptedData()/AddEncryptedData()を用いて 共通鍵復号 SP オブジェクトに設定された暗号文データに対し、適切な長さの部分に対する復号 を行う。 オブジェクト内部のデータの長さが復号に適切でない(復号処理しきれない中途半端なデータが 残った)場合、それらのデータは、オブジェクト内部の中間データとして自動的に保管される。 取得した平文データ(ICAData 型)のオクテット列へのポインタには、共通鍵復号 SP オブジェ クト内部のオクテット列格納領域へのポインタがセットされている。取得したデータの内部領域 には書き込み動作を行わない事。 pReason に返される主なエラー理由は以下の通り。 pReason の値 意味 ICAREASON_FATAL_ERROR 回復不能な致命的エラー発生 278 ICASymmetricKeyDecryptionCSPGetDataFinal() 最後の平文データの取得 【機能】 残されている、最後の平文データを取得する。 【形式】 ICAReturnCode ICASymmetricKeyDecryptionCSPGetDataFinal( ICASymmetricKeyDecryptionObject *pObj, ICAData *pData, ICAReason *pReason, ICAErrorCode *pErr ) 【引数】 pObj: pData: pReason: pErr: 共通鍵生成 SP オブジェクト(IN) 共通鍵生成 SP オブジェクトが指定される。 平文データの格納領域(OUT) 平文データを返す。 異常終了時のエラー理由(OUT) 暗号文データの取得が異常終了した場合の理由を返す。 異常終了時のエラーコード(OUT) エラーコードを返す。 【戻り値】 正常終了 : ICAR_SUCCESS 異常終了 : ICAR_FAILURE 【補足】 本関数では、共通鍵復号 SP オブジェクトに設定された暗号文データのうち、残ったデータ全体 の復号を行う。復号したデータにパディングデータが含まれる場合、指定した暗号アルゴリズム に対応してパディング部分を除去する。 取得した平文データ(ICAData 型)の、オクテット列へのポインタには、共通鍵復号 SP オブジ ェクト内部のオクテット列格納領域へのポインタがセットされている。取得したデータの内部領 域には書き込み動作を行わない事。 pReason に返される主なエラー理由は以下の通り。 pReason の値 意味 ICAREASON_INVALID_DATA_LENGTH ICAREASON_INVALID_KEY_OR_DATA ICAREASON_FAILURE_MALLOC 暗号文データの長さ不正 復号失敗(共通鍵または暗号文データ不正) メモリ確保に失敗 ICAREASON_FATAL_ERROR 回復不能な致命的エラー発生 279 7.5. 基本暗号 SP 機能構造体 7.5.1. 共通鍵生成 SP 機能 共通鍵生成 SP オブジェクト 構造体名 ICASymmetricKeyGenerationAlgorithm ICASymmetricKeyGenerationParam ICASymmetricKey 280 機能 共通鍵暗号の鍵生成アルゴリズムを表す。 共通鍵暗号の鍵生成アルゴリズムのパラ メータを表す。 共通鍵暗号アルゴリズムの鍵情報を表す。 ICASymmetricKeyGenerationAlgorithm 【機能】 共通鍵生成 SP オブジェクトに設定する共通鍵暗号の鍵生成アルゴリズムを表す。 【形式】 typedef struct ICASymmetricKeyGenerationAlgorithm { ICAType type ; Void *pParameter; } ICASymmetricKeyGenerationAlgorithm ; 【メンバー】 type: pParameter: アルゴリズムの種類 アルゴリズム種類に関連するパラメータへのポインタ(省略可) 【補足】 pParameter の値が NULL の場合は、パラメータが省略されている事を意味する。 type に指定可能な主な値は以下の通り。 値 意味 ICAALGORITHM_MISTY1_128_KEYGEN MISTY1 ICAALGORITHM_DES_EDE3_192_KEYGEN DES_EDE3 ICAALGORITHM_DES_64_KEYGEN DES ICAALGORITHM_RC2_40_KEYGEN RC2(注) (注) 鍵長及び有効鍵長が共に 40 ビットの鍵を生成する。 pParameter は Void*型として定義されているが、実際の型は type の値によって変化する。 現在の版においては、常に ICASymmetricKeyGenerationParam 型へのポインタの値をとる。 パラメータを省略する事は出来ない。 281 ICASymmetricKeyGenerationParam 【機能】 共通鍵を生成する際の共通鍵暗号アルゴリズムのパラメータを表す。 【形式】 typedef struct ICASymmetricKeyGenerationParam { ICADataOpt randomSeedOpt ; } ICASymmetricKeyGenerationParam ; 【メンバー】 randomSeedOpt: 鍵生成に使用する乱数発生ルーチンの初期値(省略可) 【補足】 乱数発生ルーチンの初期値には、任意の長さ(16 バイト以上を推奨)のオクテット列を指定 できる。値を省略した場合は、オブジェクト内部で初期値が自動生成されるが、乱数の精度は 低くなる。必ず初期値を指定する事。 ICASymmetricKey 【機能】 ICASymmetricKeyGeneration を用いて生成した共通鍵暗号アルゴリズムの鍵情報を表す。 【形式】 typedef struct ICASymmetricKey { ICAData key ; } ICASymmetricKey ; 【メンバー】 key: 共通鍵データ格納領域 282 7.5.2. 共通鍵暗号化 SP 機能 共通鍵暗号化 SP オブジェクト 構造体名 ICASymmetricKeyAlgorithm ICASymmetricKeyParamIV 機能 共通鍵暗号アルゴリズムを表す。 共通鍵暗号アルゴリズムの初期データ を表す。 「7.5.1共通鍵生成 SP 機能」の項を参照 の事。 ICASymmetricKey 283 ICASymmetricKeyAlgorithm 【機能】 ICASymmetricKeyEncryption オブジェクト及び ICASymmetricKeyDecryption オブジェク トに設定する共通鍵暗号アルゴリズムを表す。 【形式】 typedef struct ICASymmetricKeyAlgorithm { ICAType type; Void *pParameter; } ICASymmetricKeyAlgorithm ; 【メンバー】 type: pParameter: アルゴリズムの種類 アルゴリズム種類に関連するパラメータへのポインタ(省略可) 【補足】 pParameter の値が NULL の場合、パラメータが省略されている事を意味する。 type に指定可能な主な値は以下の通り。 値 ICAALGORITHM_MISTY1_128_CBC_PAD_PKCS (*) ICAALGORITHM_DES_EDE3_192_CBC_PAD_PKCS (*) ICAALGORITHM_DES_64_CBC_PAD_PKCS (*) ICAALGORITHM_RC2_40_CBC_PAD_PKCS (*) 意味 MISTY1 CBC モード PKCS パディング (注 1) DES_EDE3 CBC モード PKCS パディング (注 1) DES CBC モード PKCS パディング (注 1) RC2(注 2) CBC モード PKCS パディング (注 1) (注 1) 業界標準規格 PKCS #7 v1.5: Cryptographic Message Syntax Standard に規定された パディング方式を使用する。 pParameter は Void*型として定義されているが、実際の型は type の値によって変化する。 現版では、type の値が(*)印のアルゴリズムのいずれかの時は、pParameter は ICASymmetricKeyParamIV の値へのポインタの値を取る。この時、パラメータを省略する事は 出来ない。 また、 (*)印以外のアルゴリズムの時は、pParameter は省略する必要がある。 284 ICASymmetricKeyParamIV 【機能】 共通鍵暗号アルゴリズムのパラメータである、初期データを表す。 【形式】 typedef struct ICASymmetricKeyParamIV { ICAData iv; } ICASymmetricKeyParamIV; 【メンバー】 iv: 初期データ 285 7.5.3. 共通鍵復号 SP 機能 共通鍵復号 SP オブジェクト 構造体名 ICASymmetricKeyAlgorithm 機能 「7.4.2共通鍵暗号化 SP 機能」の項を参 照の事。 ICASymmetricKeyParamIV ICASymmetricKey 「7.5.1共通鍵生成 SP 機能」オブジェク トの項を参照の事。 286 8. 参考文献 [1]RSA Laboratories, "PKCS #11: Cryptographic Token Interface Standard," Version 2.01, December 1997 287