SSL.com

eSigner CSCAPIを使用したリモートドキュメント署名

SSL.comサポートチーム

このガイドでは、SSL.comでドキュメント署名証明書の注文を登録する方法を説明します。 電子署名者 サービスを提供し、Cloud Signature Consortium（CSC）APIを使用して、ドキュメントハッシュとPDFファイルにデジタル署名します。 このガイドはどちらでも使用できます curl or Postman。 Postmanユーザーがインストールすることをお勧めします デスクトップアプリ 例を見て作業するために。 このガイドの例は、SSL.com の実稼働環境と、eSigner および eSealing のテスト環境の両方に適用できます。 運用モードとテスト モードのコマンドの違いについては、次のセクションで説明します。

これらの指示に従うには、次のものが必要です。

SSL.com 文書署名証明書を注文する

すでに発行された文書署名証明書をお持ちの場合は、このセクションをスキップできます。 この場合は、証明書を eSigner に登録する方法を説明する次のセクションに進んでください。

実稼働環境で証明書を注文する方法

実稼働ドキュメント署名証明書を注文する方法については、このガイド記事を参照してください。 コードおよびドキュメント署名証明書の注文プロセス

SSL.com のサンドボックスでテスト証明書を注文する方法

SSL.com は、リスクのない実験スペースとして、ライブ SSL.com ポータルと SWS API をミラーリングする専用のサンドボックス環境を提供します。この「実験室」設定により、ユーザーは中断や実費の発生を心配することなく、SSL.com のサービスを探索およびテストできます。 

記事、 テストと統合のためのSSL.comサンドボックスの使用, は、サンドボックス アカウントの確立、テスト注文の開始、およびサンドボックスと SWS API の統合のプロセスをナビゲートするのに役立ちます。

テスト証明書を作成したら、SSL.com サポート チームに連絡して検証してもらいます。これを行うには、画面の右下隅にあるオンライン チャット ボタンをクリックします。 SSL.com ウェブサイトまたは電子メールの送信先 support@ssl.com.

ページのトップへ

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

CSC API の使用を開始する前に、SSL.com の eSigner クラウド署名サービスに登録する必要があります。検証された注文は、以下の手順に従って eSigner に登録できます。 

  1. 。 あなたは 注文 SSL.comアカウントでタブを押して、注文を見つけます。
    注文を探す
  2. 注文のをクリックします 細部 リンクをクリックします。
  3. を作成して4桁のPINを確認し、[ PINを作成する
    eSigner PINをリセットする必要がある場合は、以下をお読みください。 このハウツー.
  4. QRコードが表示されます。
    次にページをリロードすると、QRコードは表示されなくなります。 eSigner QRコードを表示またはリセットする必要がある場合は、以下をお読みください。 このハウツー.
  5. コードをスキャンして、モバイルデバイスの2要素認証アプリに入れます。 or オート。 アプリは、署名時に使用するワンタイムパスワード（OTP）を提供します。 各OTPは30秒間有効です。
ヒント： eSignerを使用して、組織で検証された（OV）署名証明書をチームメート間で共有できます。 読んでください eSignerドキュメントとEVコード署名証明書のチーム共有 手順を参照してください。
ページのトップへ

オプション: OV ドキュメント署名証明書をシール証明書に変換します。

注： このセクションはシーリングを希望するユーザーのみを対象としています。。ドキュメントの署名を自動化し、ワンタイム パスワード (OTP) によるプロンプトを表示しないようにするには、ユーザーは組織検証 (OV) ドキュメント署名証明書を SSL.com アカウントのシール証明書に自己変換します。 個人検証 (IV) 文書署名証明書は封印用に変換できないことに注意してください。。シーリング変換の手順については、以下で詳しく説明します。

  1. クリック 注文 SSL.com アカウントのトップメニューにあります。 
  2. 証明書を見つけて、 ダウンロード/詳細 リンクをクリックします。
  3. クリック 2FA の削除
ページのトップへ

PostmanをインストールしてAPIコレクションをインポートする

このセクションの手順は、Postmanユーザーのみを対象としています。 CSC APIでcURLを使用している場合は、次のセクションに進むことができます。

  1. ダウンロードして解凍します CSC APIPostmanコレクション および ドキュメント署名APIPostmanコレクション （参照してください https://www.postman.com/sslcom オンラインSSL.comAPIコレクションの場合）。
  2. ダウンロードしてインストール PostmanRESTクライアント.
  3. Postmanを起動してから、新しいPostmanアカウントを作成するか、既存のアカウントにサインインします。
  4. クリック インポート
  5. クリック ファイルをアップロードする ボタンをクリックして、解凍したAPIコレクションファイルに移動します（csc-api-prod.postman_collection.json および document-signing-api-prod.postman_collection.json）、それらを開きます。
  6. クリック インポート
  7. 使用するAPIリクエストは、 コレクション Postmanウィンドウの左側にあるタブ。
ページのトップへ

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

次のステップは、SSL.comからアクセストークンを取得することです。 あなたはあなたが必要になります 顧客ID SSL.comアカウントのユーザー名とパスワードだけでなく、利用可能です。 アクセストークンは、発行後XNUMX時間有効です。

以下のクリック可能なタブを使用して、PostmanまたはcURLの手順を選択します。

郵便配達員の指示cURLの説明
  1. CSCAPIコレクションからAPIリクエストを選択します。
  2. 現在地に最も近い 承認 タブを選択 OAuth 2.0 タイプ メニュー。
  3. フォームに次の情報を入力します。
    • ヘッダープレフィックス： Bearer
    • トークン名： SSLCOM CSC （または他の覚えやすい名前）
    • 助成金の種類： Authorization Code
    • コールバックURL： https://upload.esigner.com
    • ブラウザの使用を承認します。 チェックしません
    • 認証URL：  https://login.ssl.com/oauth2/authorize 実稼働環境用。 https://oauth-sandbox.ssl.com/oauth2/authorize サンドボックス環境向け。
    • アクセストークンのURL： https://login.ssl.com/oauth2/token 実稼働環境用。 https://oauth-sandbox.ssl.com/oauth2/token サンドボックス環境向け。 
    • クライアントID： [クライアントID]
    • クライアントシークレット： [あなたのクライアントの秘密]
    • 範囲： service
    • 状態： [空白のまま]
    • クライアント認証： Send as Basic Auth header

    終了したら、をクリックします 新しいアクセストークンを取得する

  4. ログインフォームが表示されます。 SSL.comのユーザー名とパスワードを入力し、[ メンバーログイン
  5. 新しいアクセストークンがPostmanに表示されます。 アクセストークンのテキストを選択してクリップボードにコピーし、を閉じます アクセストークンの管理 ダイアログボックス。 アクセストークンをテキストエディタに貼り付けて、簡単にアクセスできるようにします。 各アクセストークンはXNUMX時間後に期限切れになります。
    トークンを保存してPostmanリクエストで再利用することもできますが、トークンをコピーして各リクエストに直接貼り付けるのが最も信頼できることがわかりました。
  1. 次のコマンドを使用して、アクセストークンを要求します。 ALL-CAPSに表示されている値を実際の値に置き換えます。
    curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id" : "YOUR -CLIENT-ID", "client_secret" : "あなたのクライアント シークレット", "grant_type" : "パスワード", "ユーザー名" : "あなたのユーザー名", "パスワード" : "あなたのパスワード" }'
  2. アクセストークンと更新トークンを含むJSONオブジェクトを受け取る必要があります。 アクセストークンの値をコピーして、APIリクエストに貼り付けます。 これらの例では、更新トークンは必要ありません。
ページのトップへ

ハッシュに署名する

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

PDF ドキュメントのハッシュを計算するには、SHA 256 アルゴリズムを使用する必要があります。 
  1. PDF ライブラリは、ハッシュ入力用に PDF を操作し、後で PDF ドキュメントに PKCS#7 を埋め込むために必要です。 (例: Java の ApachePDFBox)。 
  2. eSigner API (例: Java の BouncyCastle) から受け取った生の署名から PKCS#7 を作成するための暗号ライブラリ。

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

郵便配達員の指示cURLの説明
  1. あなたが使用することができます CSC情報 SSL.comのクラウド署名サービスに関する情報の取得をリクエストします。 コレクション内の他のリクエストとは異なり、このリクエストにはアクセストークンは必要ありません。 リクエストを送信するには、 CSC情報 CSC API コレクションをクリックし、 送信
  2. クラウド署名サービスに関する情報は、PostmanのJSONオブジェクトに表示されます レスポンス フィールド。
  1. 次のコマンドを使用して、SSL.com の CSC API サービスに関する情報を取得します。 サンドボックス環境の場合は、使用します https://cs-try.ssl.com/csc/v0/info を代わりにお使いください。 
    curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Content-Type：application / json" \ --data-raw "{}"
  2. サービスに関する詳細が記載されたJSONオブジェクトを受け取ります。

CSC資格情報リスト

　 CSC資格情報リスト requestは、後のAPIリクエストで使用する資格情報を取得します。

郵便配達員の指示cURLの説明
  1. 選択 CSC資格情報リスト をクリックして 承認 タブには何も表示されないことに注意してください。
  2. 選択する ベアラートークン タイプ メニューで、アクセストークンをに貼り付けます Next フィールドをクリックし、 送信
  3. ユーザーに関連付けられた資格情報IDのリストを持つJSONオブジェクトがに表示されます レスポンス フィールド。 リストにはおそらくXNUMXつの値が含まれます。 資格情報IDをコピーしてテキストエディタに貼り付け、後のリクエストで使用できるようにします。
  1. 次のコマンドを入力します。 (MY-ACCESS-TOKEN を実際のアクセス トークンに置き換えます)。 サンドボックス環境の場合は、次を使用します。 https://cs-try.ssl.com/csc/v0/credentials/list 代わりに：
    curl --location --request POST "https://cs.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.ssl.com/csc/v0/credentials/list" \ --header "Content-Type：application / json" \ --header "認証：ベアラーMY- ACCESS-TOKEN "\ --data-raw '{" clientData "：" DS_ESEAL "}'
  2. ユーザーに関連付けられた資格情報IDのリストを含むJSONオブジェクトを受け取る必要があります。 リストにはおそらくXNUMXつの値が含まれます。 資格情報IDをコピーしてテキストエディタに貼り付け、後のリクエストで使用できるようにします。

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

　 CSC資格情報 requestは、資格情報IDに関連付けられた証明書およびその他の情報を返し、署名には必要ありません。

郵便配達員の指示cURLの説明
  1. このリクエストを使用するには、 CSC資格情報 コレクションから、をクリックします 承認 タブには何も表示されないことに注意してください。
  2. 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
  3. 現在地に最も近い ボディ タブをクリックし、資格情報IDをの値として貼り付けます credentialID.
  4. クリック 送信
  5. 署名証明書チェーンとその他の情報を含むJSONオブジェクトがに表示されます レスポンス フィールド。
  1. 次のコマンドを入力します。 サンドボックス環境にいる場合は、次を使用します。 https://cs-try.ssl.com/csc/v0/credentials/info  交換する MY-ACCESS-TOKEN および MY-CREDENTIAL-ID あなたの実際の情報で：
    curl --location --request POST "https://cs.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}'
  2. 署名証明書チェーンとその他の情報を含むJSONオブジェクトを受け取る必要があります。

資格情報の承認

　 資格情報の承認 リクエストは、ハッシュに署名するための承認を取得します。

郵便配達員の指示cURLの説明
  1. 選択することから始めます 資格情報の承認 コレクションからクリックして 承認 タブには何も表示されないことに注意してください。
  2. 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
  3. 現在地に最も近い ボディ タブ。 資格情報IDをとして貼り付けます credentialID として署名したいドキュメントの値とハッシュ hash 値。 認証アプリからOTPを取得して入力し、の値として入力します OTP次に、 送信 ボタン。 注：証明書のシールにはOTPは必要ありません。
  4. 署名アクティベーションデータ（SAD）を含むJSONオブジェクトがに表示されます レスポンス フィールド。 この値をコピーしてテキストエディタに貼り付け、ハッシュ署名要求で使用します。
  1. 次のコマンドを使用します。 交換 MY-ACCESS-TOKEN, MY-CREDENTIAL-ID, MY-HASH あなたの実際の情報で。 2FAアプリケーションからワンタイムパスワードを取得し、の値として使用します MY-OTP。 注：証明書のシールにはOTPは必要ありません。
    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type：application / json" \ --header "承認：Bearer MY- ACCESS-TOKEN "\ --data-raw '{" credentialID "：" MY-CREDENTIAL-ID "、" numSignatures "：1、" hash "：[" MY-HASH "]、" OTP "：" MY-OTP "} '
  2. 署名アクティベーションデータ（SAD）を含むJSONオブジェクトを受け取る必要があります。 この値をコピーしてテキストエディタに貼り付け、ハッシュ署名要求で使用します。

サインハッシュ

これで、ドキュメントハッシュに署名する準備が整いました。

郵便配達員の指示cURLの説明
  1. 選択 サインハッシュ コレクションから、を選択します 承認 タブには何も表示されないことに注意してください。
  2. 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
  3. 現在地に最も近い ボディ タブ。 資格情報IDをとして貼り付けます credentialID 値、署名アクティベーションデータとして SAD 値、および署名するドキュメントのハッシュ hash 値をクリックし、 送信
  4. 署名付きのJSONオブジェクトがに表示されます レスポンス フィールド。
  1. 次のコマンドを入力します。 交換 MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SAD, MY-HASH あなたの実際の情報で：
    curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type：application / json" \ --header "認証：Bearer MY- ACCESS-TOKEN "\ --data-raw '{" credentialID "：" MY-CREDENTIAL-ID "、" SAD "：" MY-SAD "、" hash "：[" MY-HASH "]、" signAlgo "： "1.2.840.113549.1.1.11"} '
  2. 署名を含むJSONオブジェクトを受け取るはずです。
ページのトップへ

PDFに署名する

ドキュメントハッシュに署名するだけでなく、PDFファイルをアップロードして署名することもできます。

PDFに署名するときは、XNUMXつのPOSTリクエストを処理します。

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

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

郵便配達員の指示cURLの説明
  1. 現在地に最も近い PDFドキュメントをアップロードする リクエストしてクリックします 承認 タブには何も表示されないことに注意してください。
  2. 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
  3. 現在地に最も近い ヘッダ タブをクリックして、資格情報IDを 値 コラム。
  4. 現在地に最も近い ボディ タブをクリックします × の隣に hello.pdf このプレースホルダーファイル名を削除します。
  5. クリック ファイルを選ぶ ボタンをクリックして、アップロードするファイルに移動します。
  6. クリック 送信
  7. を選択してコピーします id 次のリクエストで使用する応答の値。
  1. 次のコマンドを使用します。 交換 MY-CREDENTIAL-ID, MY-ACCESS-TOKEN, /PATH/TO/FILE.pdf あなたの実際の情報で：
    curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id：MY-CREDENTIAL-ID" \ --header "Authorization：Bearer MY- ACCESS-TOKEN "\ --header" Content-Type：application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
  2. 次の値を持つJSONオブジェクトを受け取ります id。 この値をコピーして、次のリクエストで使用します。

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

リクエストヘッダー

説明

クレデンシャルID

キーに割り当てられた一意の資格情報ID–必須

署名-理由

署名の外観と署名辞書に追加する署名理由を追加–オプション（例：このドキュメントを承認する）

署名-場所

署名辞書に署名場所を追加–オプション（テキサス州ヒューストンなど）

連絡先情報

署名辞書に連絡先情報を追加する–オプション（電話番号など）

署名-フィールド-位置

視覚的な署名が表示される署名フィールドの位置。 フォーマットは 「x、y、幅、高さ」 –オプション

ページ番号

署名を描画するページ番号–オプション

手書き署名

手署名のBase64エンコードPNG画像–オプション


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

これで、PDFに署名できます。

封印文書署名証明書を使用して署名する場合、OTP認証は必要ありません。 証明書に署名する封印文書を使用する場合は、次のガイドのすべてのOTPパラメータを無視してください。
郵便配達員の指示cURLの説明
  1. 現在地に最も近い PDFドキュメントをアップロードする リクエストしてクリックします 承認 タブには何も表示されないことに注意してください。
      
  2. 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
  3. [本文]タブを選択し、 id 前の手順の値と認証アプリのOTPをクリックして、 送信
  4. PDFデータは以下に表示されます レスポンス フィールド。 選択 ファイルに保存 応答を保存 メニューをクリックし、ファイルに名前を付けます。
  5. ファイルをAcrobatで開き、ファイルが署名されていることを確認します。
  1. 次のコマンドを入力します。 交換 MY-CREDENTIAL-ID, MY-FILE-ID, OUTPUT-FILENAME あなたの実際の情報で。 2FAアプリからワンタイムパスワード（OTP）を取得し、次のように入力します MY-OTP。 注：証明書のシールにはOTPは必要ありません。
    curl --location --request POST'https：//ds.ssl.com/v1/pdf/sign '\ --header'Content-Transfer-Encoding：application / json' \ --header'Content-Type：application / json '\ --header'認証：ベアラーMY-ACCESS-TOKEN '\ --data-raw' {"id"： "MY-FILE-ID"、 "otp"： "MY-OTP"} '\- -出力OUTPUT-FILENAME
  2. cURLは署名されたファイルをダウンロードし、指定したファイル名で保存します。
  3. PDFをAcrobatまたはAcrobatReaderで開き、署名が有効であることを確認します。

モバイル版を終了