このガイドでは、SSL.comでドキュメント署名証明書の注文を登録する方法を説明します。 電子署名者 サービスを提供し、Cloud Signature Consortium（CSC）APIを使用して、ドキュメントハッシュとPDFファイルにデジタル署名します。 このガイドはどちらでも使用できます curl or Postman。 Postmanユーザーがインストールすることをお勧めします デスクトップアプリ 例を見て作業するために。 このガイドの例は、SSL.com の実稼働環境と、eSigner および eSealing のテスト環境の両方に適用できます。 運用モードとテスト モードのコマンドの違いについては、次のセクションで説明します。
これらの指示に従うには、次のものが必要です。
- 検証済みのドキュメント署名証明書の注文。 読んでください このハウツー 注文と検証の詳細については。
- A 顧客ID （別名 アプリケーションID。 参照してください このハウツー この資格情報を生成する手順については）。
SSL.com 文書署名証明書を注文する
実稼働環境で証明書を注文する方法
実稼働ドキュメント署名証明書を注文する方法については、このガイド記事を参照してください。 コードおよびドキュメント署名証明書の注文プロセス
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 に登録できます。
- 。 あなたは 注文 SSL.comアカウントでタブを押して、注文を見つけます。
- 注文のをクリックします 細部 リンクをクリックします。
- を作成して4桁のPINを確認し、[ PINを作成する
eSigner PINをリセットする必要がある場合は、以下をお読みください。 このハウツー.
- QRコードが表示されます。
次にページをリロードすると、QRコードは表示されなくなります。 eSigner QRコードを表示またはリセットする必要がある場合は、以下をお読みください。 このハウツー.
- コードをスキャンして、モバイルデバイスの2要素認証アプリに入れます。 or オート。 アプリは、署名時に使用するワンタイムパスワード（OTP）を提供します。 各OTPは30秒間有効です。
オプション: OV ドキュメント署名証明書をシール証明書に変換します。
注： このセクションはシーリングを希望するユーザーのみを対象としています。。ドキュメントの署名を自動化し、ワンタイム パスワード (OTP) によるプロンプトを表示しないようにするには、ユーザーは組織検証 (OV) ドキュメント署名証明書を SSL.com アカウントのシール証明書に自己変換します。 個人検証 (IV) 文書署名証明書は封印用に変換できないことに注意してください。。シーリング変換の手順については、以下で詳しく説明します。
- 注文 SSL.com アカウントのトップメニューにあります。
- 証明書を見つけて、 ダウンロード/詳細 リンクをクリックします。
- 2FA の削除
PostmanをインストールしてAPIコレクションをインポートする
このセクションの手順は、Postmanユーザーのみを対象としています。 CSC APIでcURLを使用している場合は、次のセクションに進むことができます。
- ダウンロードして解凍します CSC APIPostmanコレクション & ドキュメント署名APIPostmanコレクション （参照してください https://www.postman.com/sslcom オンラインSSL.comAPIコレクションの場合）。
- ダウンロードしてインストール PostmanRESTクライアント.
- Postmanを起動してから、新しいPostmanアカウントを作成するか、既存のアカウントにサインインします。
- インポート
- ファイルをアップロードする ボタンをクリックして、解凍したAPIコレクションファイルに移動します（
csc-api-prod.postman_collection.json&document-signing-api-prod.postman_collection.json）、それらを開きます。
- インポート
- 使用するAPIリクエストは、 コレクション Postmanウィンドウの左側にあるタブ。
アクセストークンを取得する
次のステップは、SSL.comからアクセストークンを取得することです。 あなたはあなたが必要になります 顧客ID SSL.comアカウントのユーザー名とパスワードだけでなく、利用可能です。 アクセストークンは、発行後XNUMX時間有効です。
以下のクリック可能なタブを使用して、PostmanまたはcURLの手順を選択します。
- CSCAPIコレクションからAPIリクエストを選択します。
- 現在地に最も近い 承認 タブを選択 OAuth 2.0 タイプ メニュー。
![[承認]タブ](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%201000%20416'%3E%3C/svg%3E)
- フォームに次の情報を入力します。
- ヘッダープレフィックス：
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
終了したら、をクリックします 新しいアクセストークンを取得する
- ヘッダープレフィックス：
- ログインフォームが表示されます。 SSL.comのユーザー名とパスワードを入力し、[ メンバーログイン
- 新しいアクセストークンがPostmanに表示されます。 アクセストークンのテキストを選択してクリップボードにコピーし、を閉じます アクセストークンの管理 ダイアログボックス。 アクセストークンをテキストエディタに貼り付けて、簡単にアクセスできるようにします。 各アクセストークンはXNUMX時間後に期限切れになります。
トークンを保存してPostmanリクエストで再利用することもできますが、トークンをコピーして各リクエストに直接貼り付けるのが最も信頼できることがわかりました。
![[承認]タブ](https://ee2cc1f8.rocketcdn.me/wp-content/uploads/2021/02/esigner-csc-api-14.png)
- 次のコマンドを使用して、アクセストークンを要求します。 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" : "パスワード", "ユーザー名" : "あなたのユーザー名", "パスワード" : "あなたのパスワード" }' - アクセストークンと更新トークンを含むJSONオブジェクトを受け取る必要があります。 アクセストークンの値をコピーして、APIリクエストに貼り付けます。 これらの例では、更新トークンは必要ありません。
ハッシュに署名する
アクセストークンを取得したので、APIリクエストの作成と署名の作成を開始できます。 このセクションでは、Postman CSCコレクションで利用可能なXNUMXつのリクエストについて説明し、ドキュメントハッシュからデジタル署名を作成します。
- PDF ライブラリは、ハッシュ入力用に PDF を操作し、後で PDF ドキュメントに PKCS#7 を埋め込むために必要です。 (例: Java の ApachePDFBox)。
- eSigner API (例: Java の BouncyCastle) から受け取った生の署名から PKCS#7 を作成するための暗号ライブラリ。
CSC情報の取得（オプション）
- あなたが使用することができます CSC情報 SSL.comのクラウド署名サービスに関する情報の取得をリクエストします。 コレクション内の他のリクエストとは異なり、このリクエストにはアクセストークンは必要ありません。 リクエストを送信するには、 CSC情報 CSC API コレクションをクリックし、 送信
- クラウド署名サービスに関する情報は、PostmanのJSONオブジェクトに表示されます レスポンス フィールド。
- 次のコマンドを使用して、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 "{}" - サービスに関する詳細が記載されたJSONオブジェクトを受け取ります。
CSC資格情報リスト
CSC資格情報リスト requestは、後のAPIリクエストで使用する資格情報を取得します。
- 選択 CSC資格情報リスト をクリックして 承認 タブには何も表示されないことに注意してください。
![[承認]タブ](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%201000%20335'%3E%3C/svg%3E)
- 選択する ベアラートークン タイプ メニューで、アクセストークンをに貼り付けます Next フィールドをクリックし、 送信
- ユーザーに関連付けられた資格情報IDのリストを持つJSONオブジェクトがに表示されます レスポンス フィールド。 リストにはおそらくXNUMXつの値が含まれます。 資格情報IDをコピーしてテキストエディタに貼り付け、後のリクエストで使用できるようにします。
![[承認]タブ](https://ee2cc1f8.rocketcdn.me/wp-content/uploads/2021/02/esigner-csc-api-19.png)
- 次のコマンドを入力します。 (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 "}' - ユーザーに関連付けられた資格情報IDのリストを含むJSONオブジェクトを受け取る必要があります。 リストにはおそらくXNUMXつの値が含まれます。 資格情報IDをコピーしてテキストエディタに貼り付け、後のリクエストで使用できるようにします。
CSC資格情報情報（オプション）
CSC資格情報 requestは、資格情報IDに関連付けられた証明書およびその他の情報を返し、署名には必要ありません。
- このリクエストを使用するには、 CSC資格情報 コレクションから、をクリックします 承認 タブには何も表示されないことに注意してください。
![[認証]タブ](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%201000%20357'%3E%3C/svg%3E)
- 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
- 現在地に最も近い ボディ タブをクリックし、資格情報IDをの値として貼り付けます
credentialID.
- 送信
- 署名証明書チェーンとその他の情報を含むJSONオブジェクトがに表示されます レスポンス フィールド。
![[認証]タブ](https://ee2cc1f8.rocketcdn.me/wp-content/uploads/2021/02/esigner-csc-api-23.png)
- 次のコマンドを入力します。 サンドボックス環境にいる場合は、次を使用します。
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}' - 署名証明書チェーンとその他の情報を含むJSONオブジェクトを受け取る必要があります。
資格情報の承認
資格情報の承認 リクエストは、ハッシュに署名するための承認を取得します。
- 選択することから始めます 資格情報の承認 コレクションからクリックして 承認 タブには何も表示されないことに注意してください。
![[承認]タブ](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%201000%20287'%3E%3C/svg%3E)
- 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
- 現在地に最も近い ボディ タブ。 資格情報IDをとして貼り付けます
credentialIDとして署名したいドキュメントの値とハッシュhash値。 認証アプリからOTPを取得して入力し、の値として入力しますOTP次に、 送信 ボタン。 注：証明書のシールにはOTPは必要ありません。
- 署名アクティベーションデータ（SAD）を含むJSONオブジェクトがに表示されます レスポンス フィールド。 この値をコピーしてテキストエディタに貼り付け、ハッシュ署名要求で使用します。
![[承認]タブ](https://ee2cc1f8.rocketcdn.me/wp-content/uploads/2021/02/esigner-csc-api-28.png)
- 次のコマンドを使用します。 交換
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 "} ' - 署名アクティベーションデータ（SAD）を含むJSONオブジェクトを受け取る必要があります。 この値をコピーしてテキストエディタに貼り付け、ハッシュ署名要求で使用します。
サインハッシュ
これで、ドキュメントハッシュに署名する準備が整いました。
- 選択 サインハッシュ コレクションから、を選択します 承認 タブには何も表示されないことに注意してください。
- 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
- 現在地に最も近い ボディ タブ。 資格情報IDをとして貼り付けます
credentialID値、署名アクティベーションデータとしてSAD値、および署名するドキュメントのハッシュhash値をクリックし、 送信
- 署名付きのJSONオブジェクトがに表示されます レスポンス フィールド。
![[承認]タブ](https://ee2cc1f8.rocketcdn.me/wp-content/uploads/2021/02/esigner-csc-api-32.png)
- 次のコマンドを入力します。 交換
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"} ' - 署名を含むJSONオブジェクトを受け取るはずです。
PDFに署名する
ドキュメントハッシュに署名するだけでなく、PDFファイルをアップロードして署名することもできます。
PDFに署名するときは、XNUMXつのPOSTリクエストを処理します。
- PDFドキュメントをアップロードする
- PDFドキュメントに署名する
上記で取得した資格情報は、 CSC資格情報リスト リクエスト。 おそらく、新しいものを取得する必要もあります アクセストークン.
PDFドキュメントをアップロードする
- 現在地に最も近い PDFドキュメントをアップロードする リクエストしてクリックします 承認 タブには何も表示されないことに注意してください。
![[承認]タブ](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%201000%20309'%3E%3C/svg%3E)
- 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
- 現在地に最も近い ヘッダ タブをクリックして、資格情報IDを 値 コラム。
![[ヘッダー]タブ](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20853%20313'%3E%3C/svg%3E)
- 現在地に最も近い ボディ タブをクリックします × の隣に
hello.pdfこのプレースホルダーファイル名を削除します。
- ファイルを選ぶ ボタンをクリックして、アップロードするファイルに移動します。
- 送信
- を選択してコピーします
id次のリクエストで使用する応答の値。
![[承認]タブ](https://ee2cc1f8.rocketcdn.me/wp-content/uploads/2021/02/esigner-csc-api-36.png)
![[ヘッダー]タブ](https://ee2cc1f8.rocketcdn.me/wp-content/uploads/2021/02/esigner-csc-api-38.png)
- 次のコマンドを使用します。 交換
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 "
- 次の値を持つJSONオブジェクトを受け取ります
id。 この値をコピーして、次のリクエストで使用します。
注：表示される署名については、次のHTTPリクエストヘッダー（/ v1 / pdf / upload）を参照してください。
|
クレデンシャルID |
キーに割り当てられた一意の資格情報ID–必須 |
|
署名-理由 |
署名の外観と署名辞書に追加する署名理由を追加–オプション（例：このドキュメントを承認する） |
|
署名-場所 |
署名辞書に署名場所を追加–オプション（テキサス州ヒューストンなど） |
|
連絡先情報 |
署名辞書に連絡先情報を追加する–オプション（電話番号など） |
|
署名-フィールド-位置 |
視覚的な署名が表示される署名フィールドの位置。 フォーマットは 「x、y、幅、高さ」 –オプション |
|
ページ番号 |
署名を描画するページ番号–オプション |
|
手書き署名 |
手署名のBase64エンコードPNG画像–オプション |
PDFドキュメントに署名する
これで、PDFに署名できます。
- 現在地に最も近い PDFドキュメントをアップロードする リクエストしてクリックします 承認 タブには何も表示されないことに注意してください。
- 選択する ベアラートークン タイプ メニューをクリックし、アクセストークンをに貼り付けます Next フィールド。
- [本文]タブを選択し、
id前の手順の値と認証アプリのOTPをクリックして、 送信
- PDFデータは以下に表示されます レスポンス フィールド。 選択 ファイルに保存 応答を保存 メニューをクリックし、ファイルに名前を付けます。
- ファイルをAcrobatで開き、ファイルが署名されていることを確認します。
- 次のコマンドを入力します。 交換
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 - cURLは署名されたファイルをダウンロードし、指定したファイル名で保存します。
- PDFをAcrobatまたはAcrobatReaderで開き、署名が有効であることを確認します。
