eSignerCSCAPIを使用したリモートドキュメント署名のテストに関する統合ガイド

このガイドでは、SSL.comを使用してドキュメントハッシュとPDFファイルに署名する方法について説明します。 電子署名者 クラウド署名サービスとクラウド署名コンソーシアム（CSC）API。 すべてのAPIリクエストの例は次のように表示されます Postman、およびインストールすることをお勧めします Postmanデスクトップアプリ 例を実行したい場合は、コンピューター上で。 APIリクエストのcURLコマンドの例も含まれています。

テストオーダーを作成する

1. まず、サンドボックスでドキュメントの署名順序を作成する必要があります。 サンドボックスアカウントにサインインして、 ダッシュボード タブには何も表示されないことに注意してください。
   
2. 開発者ツール.
   
3. 選択 eSignerドキュメントの署名次に、 テスト注文を作成
   
4. ダイアログボックスが表示されます。 クリック OK
   
5. テスト注文を見つけて、をクリックします 細部 リンクをクリックします。
   
6. 登録者を編集 テスト注文の申請者と受信者の情報の入力を開始します。 この情報は有効な文書署名証明書の発行には使用されないため、必要に応じて架空の情報を入力できます。
   
7. テスト証明書の申請者情報を追加し、[ 次へ>>
   
8. 受信者情報を入力し、をクリックします 次へ>>
   
9. クリック スキップ ボタンをクリックして、テスト証明書の検証ドキュメントのアップロードをスキップします。
   
10. これで、テスト注文のステータスは次のようになります。 検証待ち。 次のSSL.comサポートチームに連絡してください。 Support@SSL.com テスト証明書を検証します。
    

eSignerに登録し、XNUMX要素認証を設定します

1. テスト注文がSSL.comサポートスタッフによって検証されたら、eSignerに登録できます。 に移動します 注文 SSL.comサンドボックスアカウントのタブをクリックして、テスト注文を見つけます。
   
2. 注文のをクリックします 細部 リンクをクリックします。
   
3. 4桁のPINを作成して確認し、[ PINを作成する
   
   eSigner PINをリセットする必要がある場合は、以下をお読みください。 このハウツー.
   
4. QRコードが表示されます。
   
   次にページをリロードすると、QRコードは表示されなくなります。 eSigner QRコードを表示またはリセットする必要がある場合は、以下をお読みください。 このハウツー.
   
5. コードをスキャンして、GoogleAuthenticatorやAuthyなどのモバイルデバイス上の2要素認証アプリに入れます。 アプリは、署名時に使用するワンタイムパスワード（OTP）を提供します。 各OTPは30秒間有効です。
   

インストールを開始する Postman CSCAPIコレクションをインポートします

1. ダウンロードして解凍します CSC APIPostmanコレクション （参照してください https://www.postman.com/sslcom/workspace/public/collection/3420801-f2df0995-1293-45da-8719-73467c9f0ca7?ctx=documentation 最新のAPIエンドポイントまたはコレクションのダウンロードの場合）。
   
2. ダウンロードしてインストール PostmanRESTクライアント.
   
3. Postmanを起動してから、新しいPostmanアカウントを作成するか、既存のアカウントにサインインします。
   
4. クリック インポート
   
5. クリック ファイルをアップロードする ボタンをクリックして、解凍したAPIコレクションファイルに移動します（CSC-API.postman_collection.json）、それを開きます。
   
6. クリック インポート
   
7. クリック コレクション Postmanのタブをクリックし、CSC APIコレクションを展開して、操作するXNUMXつのPOSTリクエストを表示します。
   • CSC情報
   • CSC資格情報リスト
   • CSC資格情報
   • 資格情報の承認
   • サインハッシュ

   

アクセストークンを取得する

1. 次のステップは、SSL.comからアクセストークンを取得することです。 アクセストークンをリクエストする前に、 顧客ID （別名 アプリケーションID。 参照してください このハウツー この資格情報を生成する手順については）。
2. 現在地に最も近い 承認 タブ、選択 OAuth 2.0 タイプ メニューをクリックし、 新しいアクセストークンを取得する
   
3. フォームに次の情報を入力します。
   • トークン名： SandBox CSC（またはその他の覚えやすい名前）
   • 助成金の種類： 承認コード
   • コールバックURL： [空白のまま]
   • ブラウザの使用を承認します。 チェック済み
   • 認証URL： https://oauth-sandbox.ssl.com/oauth2/authorize
   • アクセストークンのURL： https://oauth-sandbox.ssl.com/oauth2/token
   • クライアントID： [クライアントID]
   • クライアントシークレット： [あなたのクライアントの秘密]
   • 範囲： サービス
   • 状態： [空白のまま]
   • クライアント認証： 基本認証ヘッダーとして送信する

   終了したら、をクリックします リクエストトークン
   

4. ログインフォームがWebブラウザに表示されます。 SSL.comのユーザー名とパスワードを入力し、[ メンバーログイン
   
5. 新しいアクセストークンがPostmanに表示されます。 アクセストークンのテキストを選択してクリップボードにコピーし、を閉じます アクセストークンの管理 ダイアログボックス。 アクセストークンをテキストエディタに貼り付けて、簡単にアクセスできるようにします。 各アクセストークンはXNUMX時間後に期限切れになります。
   
   トークンを保存して再利用することもできます Postman リクエストがありますが、トークンをコピーして各リクエストに直接貼り付けるのが最も信頼できることがわかりました。
   

ハッシュに署名する

アクセストークンを取得したので、APIリクエストの作成と署名の作成を開始できます。 このセクションでは、で利用可能なXNUMXつのリクエストについて説明します。 郵便配達員CSCコレクション、ドキュメントハッシュからデジタル署名が作成されます。

CSC情報の取得（オプション）

1. あなたが使用することができます CSC情報 SSL.comのクラウド署名サービスに関する情報の取得をリクエストします。 コレクション内の他のリクエストとは異なり、このリクエストにはアクセストークンは必要ありません。 リクエストを送信するには、 CSC情報 CSC API コレクションをクリックし、 送信
   
2. クラウド署名サービスに関する情報は、PostmanのJSONオブジェクトに表示されます レスポンス フィールド。
   

cURLコマンド

curl --location --request POST "https://cs-try.ssl.com/csc/v0/info" \ --header "Content-Type：application / json" \ --data-raw "{}"

CSC資格情報リスト

1. 　 CSC資格情報リスト requestは、後のAPIリクエストで使用する資格情報を取得します。 選択する CSC資格情報リスト をクリックして 承認 タブには何も表示されないことに注意してください。
   
2. 選択する ベアラートークン タイプ メニューで、アクセストークンをに貼り付けます Next フィールドをクリックし、 送信
   
3. ユーザーに関連付けられた資格情報IDのリストを持つJSONオブジェクトがに表示されます レスポンス フィールド。 リストにはおそらくXNUMXつの値が含まれます。 資格情報IDをコピーしてテキストエディタに貼り付け、後のリクエストで使用できるようにします。
   

cURLコマンド

交換する MY-ACCESS-TOKEN 実際のアクセストークンを使用する場合：

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type：application / json" \ --header "認証：ベアラーMY-ACCESS-TOKEN "\ --data-raw" {} "

eseal証明書（組織情報のみを含むドキュメント署名証明書。無料のesigner.comアカウントに含まれています）を使用する場合は、「clientData」：「DS_ESEAL」を含めます（注：esealsにはOTP認証は必要ありません）。 「clientData」の他のオプションは、EVコード署名の場合は「EVCS」、IVまたはIV + OV文書署名の場合は「DS」（デフォルト）です。

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type：application / json" \ --header "認証：ベアラーMY-ACCESS-TOKEN "\ --data-raw" {\ "clientData \"：\ "DS_ESEAL \"} "

CSC資格情報情報（オプション）

1. 　 CSC資格情報 requestは、資格情報IDに関連付けられた証明書およびその他の情報を返し、署名には必要ありません。 このリクエストを使用するには、 CSC資格情報 コレクションから、をクリックします 承認 タブには何も表示されないことに注意してください。
   
2. 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
   
3. 現在地に最も近い ボディ タブをクリックし、資格情報IDをの値として貼り付けます credentialID.
   
4. クリック 送信
   
5. 署名証明書チェーンとその他の情報を含むJSONオブジェクトがに表示されます レスポンス フィールド。
   

cURLコマンド

交換する MY-ACCESS-TOKEN & MY-CREDENTIAL-ID あなたの実際の情報で：

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/info" \ --header "Content-Type：application / json" \ --header "認証：ベアラーMY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \"：\ "MY-CREDENTIAL-ID \"、\ "certificates \"：\ "chain \"、\ "certInfo \"：true、 \ "authInfo \"：true} "

資格情報の承認

1. 　 資格情報の承認 リクエストは、ハッシュに署名するための承認を取得します。 選択することから始めます 資格情報の承認 コレクションからクリックして 承認 タブには何も表示されないことに注意してください。
   
2. 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
   
3. 現在地に最も近い ボディ タブ。 資格情報IDをとして貼り付けます credentialID として署名したいドキュメントの値とハッシュ hash 値。 認証アプリからOTPを取得して入力し、の値として入力します OTP次に、 送信
   
4. 署名アクティベーションデータ（SAD）を含むJSONオブジェクトがに表示されます レスポンス フィールド。 この値をコピーしてテキストエディタに貼り付け、ハッシュ署名要求で使用します。
   

cURLコマンド

交換する MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-HASH, MY-OTP あなたの実際の情報で：

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type：application / json" \ --header "承認：ベアラーMY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \"：\ "MY-CREDENTIAL-ID \"、\ "numSignatures \"：1、\ "hash \"：[\ "MY-HASH \ "]、\" OTP \ "：\" MY-OTP \ ">"

サインハッシュ

1. これで、ドキュメントハッシュに署名する準備が整いました。 選択する サインハッシュ コレクションから、を選択します 承認 タブには何も表示されないことに注意してください。
   
2. 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
   
3. 現在地に最も近い ボディ タブ。 資格情報IDをとして貼り付けます credentialID 値、署名アクティベーションデータとして SAD 値、および署名するドキュメントのハッシュ hash 値をクリックし、 送信
   
4. 署名付きのJSONオブジェクトがに表示されます レスポンス フィールド。
   

cURLコマンド

交換する MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SAD, MY-HASH あなたの実際の情報で：

curl --location --request POST "https://cs-try.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type：application / json" \ --header "認証：ベアラーMY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \"：\ "MY-CREDENTIAL-ID \"、\ "SAD \"：\ "MY-SAD \"、\ "hash \"： [\ "MY-HASH \"]、\ "signAlgo \"：\ "1.2.840.113549.1.1.11 \"} "

PDFに署名する

ドキュメントハッシュに署名するだけでなく、PDFファイルをアップロードして署名することもできます。 をダウンロードしてインポートすることから始めます ドキュメント署名APIPostmanコレクション （参照してください https://www.postman.com/sslcom/workspace/public/collection/3454644-277d8427-f749-4a94-93bf-c3478b79b999?ctx=documentation 最新のAPIエンドポイントとコレクションのダウンロードの場合）、同じ インストール手順 上記のCSCAPIコレクションをフォローしました。

• PDFドキュメントをアップロードする
• PDFドキュメントに署名する

上記で取得した資格情報は、 CSC資格情報リスト リクエスト。 おそらく、新しいものを取得する必要もあります アクセストークン.

PDFドキュメントをアップロードする

1. 現在地に最も近い PDFドキュメントをアップロードする リクエストしてクリックします 承認 タブには何も表示されないことに注意してください。
   
2. 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
   
3. 現在地に最も近い ヘッダ タブをクリックして、資格情報IDを 値 コラム。
   
4. 現在地に最も近い ボディ タブをクリックします × の隣に hello.pdf このプレースホルダーファイル名を削除します。
   
5. クリック ファイルを選ぶ ボタンをクリックして、アップロードするファイルに移動します。
   
6. クリック 送信
   
7. を選択してコピーします id 次のリクエストで使用する応答の値。
   

cURLコマンド

交換する MY-CREDENTIAL-ID, MY-ACCESS-TOKEN, /PATH/TO/FILE.pdf あなたの実際の情報で：

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/upload" \ --header "Credential-Id：MY-CREDENTIAL-ID" \ --header "認証：ベアラーMY-ACCESS-TOKEN "\ --header" Content-Type：application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "

注：表示される署名については、次のHTTPリクエストヘッダー（/ v1 / pdf / upload）を参照してください。

PDFドキュメントに署名する

1. これで、PDFに署名できます。 を選択 PDFドキュメントをアップロードする リクエストしてクリックします 承認 タブには何も表示されないことに注意してください。
     
2. 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
   
3. [本文]タブを選択し、 id 前のステップの値。
   
4. 認証アプリからOTPを入力し、[ 送信
   
5. PDFデータは以下に表示されます レスポンス フィールド。 選択 ファイルに保存 応答を保存 メニューをクリックし、ファイルに名前を付けます。
   
6. ファイルをAcrobatで開き、ファイルが署名されていることを確認します。 （以下のスクリーンショットでは、SSL.comのRSA開発ルートがAcrobatで手動で信頼されていることに注意してください。）
   

cURLコマンド

交換する MY-CREDENTIAL-ID, MY-FILE-ID, MY-OTP あなたの実際の情報で：

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/sign" \ --header "Content-Transfer-Encoding：application / json" \ --header "Content-Type ：application / json "\ --header"認証：Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "id \"：\ "MY-FILE-ID \"、\ "otp \"：\ "MY-OTP \"} "

 本番環境で稼働する

公開するには、サブドメインから「-try」を削除する必要があります。 たとえば、ds-try.ssl.comを公開するには、「-try」を削除して、サブドメインがds.ssl.comになるようにします。