ScalarDL 認証ガイド

注記

このページは英語版のページが機械翻訳されたものです。英語版との間に矛盾または不一致がある場合は、英語版を正としてください。

このドキュメントでは、ScalarDL の認証メカニズムとその適切な使用方法について説明します。

ScalarDL での認証

認証は ScalarDL の重要な役割の1つであり、プロトコルを期待どおりに動作させることができます。 ScalarDL は、次の3つの状況で認証を使用します。

• クライアント認証（Ledger と Auditor 用）
  • Ledger と Auditor は、クライアントからのリクエストに添付されたクライアント生成の署名を使用してクライアントを認証します。
• Ledger 認証（Auditor 用）
  • Auditor は、アセットプルーフに添付された Ledger 生成の署名を使用して Ledger を認証します。
• Auditor 認証（Ledger 用）
  • Ledger は、クライアントのリクエストに添付された Auditor が生成した署名を使用して Auditor を認証します。

Ledger 認証と Auditor 認証は Auditor モードでのみ使用されることに注意してください。Auditor の詳細については、ScalarDL Auditor 入門および ScalarDL 実装を参照してください。

また、ここでは認証に使用されるバイト配列を指定するために signature という用語を使用していることに注意してください。

認証方法

ScalarDL は、電子署名と HMAC という2つの認証方法をサポートしています。 以下に説明するように、これらの方法には両方とも長所と短所がありますが、どちらの方法でもビザンチン故障検出機能が犠牲になることはありません。

電子署名

• 利点
  • クライアントのリクエスト、アセットレコード、およびアセットプルーフには否認防止特性があります。具体的には、クライアントのリクエストに添付された電子署名は、そのリクエストが生成する対応するアセットレコードとともに保存されるため、クライアントのリクエストと対応するレコードには否認防止の特性が備わります。つまり、リクエストに署名した秘密鍵の所有者がレコードを作成したことを保証できます。さらに、実行の結果としてクライアントに返されるアセットプルーフに添付された電子署名により、Ledger と Auditor がそれぞれ証明を作成したことが保証されます。クライアント（アプリケーション）がプルーフを保持しておけば、クライアントは必要に応じてプルーフを使用して結果を検証できます。
• 短所
  • 電子署名は非常に遅いです。上記の利点と引き換えに、無視できないパフォーマンスのオーバーヘッドが追加されます。

HMAC

• 利点
  • HMAC は電子署名よりもはるかに高速です。
• 短所
  • クライアントのリクエスト、アセットレコード、およびアセットプルーフには否認防止特性がありません。

どれを使用すればよいですか?

否認防止プロパティが必要ない場合は、常に HMAC を使用する必要があります。 技術的には、クライアント認証には電子署名を使用し、Ledger/Auditor 認証には HMAC を使用するなど、認証方法を混合することができます。ただし、混合方法は非常に混乱を招く可能性があるため、ScalarDL ではそのような使用を禁止しています。

パフォーマンスを向上させるために、Ledger と Auditor の認証に HMAC のみを使用するように ScalarDL を更新する予定であることに注意してください。同様に、Ledger と Auditor の認証をアセットプルーフへの署名方法から分離する予定です。上記の変更により、Ledger と Auditor の間で HMAC 認証を使用しながら、電子署名されたアセットプルーフを返すことができるようになります。

設定

このセクションでは、ScalarDL 認証を適切に使用するために設定する必要がある変数について説明します。各変数の詳細については、Javadoc を参照してください。

電子署名

• クライアント認証
  • クライアント側のプロパティ
    • scalar.dl.client.auditor.enabled (Auditor を使用する場合は true に設定します)
    • scalar.dl.client.authentication_method (digital-signatureに設定)
    • scalar.dl.client.entity.id (または非推奨の scalar.dl.client.cert_holder_id)
      • お客様を識別するために使用します。
    • scalar.dl.client.entity.identity.digital_signature.cert_pem または scalar.dl.client.entity.identity.digital_signature.cert_path (または scalar.dl.client.cert_pem または scalar.dl.client) .cert_path、これは非推奨です。)
      • クライアントが生成した署名を検証するために、Ledger と Auditor の証明書を登録するために使用されます。
      • 証明書の取得方法については、こちらを参照してください。
    • scalar.dl.client.entity.identity.digital_signature.cert_version (または非推奨の scalar.dl.client.cert_version)
    • scalar.dl.client.entity.identity.digital_signature.private_key_pem または scalar.dl.client.entity.identity.digital_signature.private_key_path (または scalar.dl.client.private_key_pem または scalar.dl.client) .private_key_path、これは非推奨です。)
      • リクエストの署名に使用されます。
      • 秘密鍵の取得方法については、こちらを参照してください。
  • Ledger 側のプロパティ
    • scalar.dl.ledger.authentication.method (digital-signatureに設定)
  • Auditor 側のプロパティ
    • scalar.dl.auditor.authentication.method (digital-signatureに設定)
• Ledger 認証
  • Ledger 側のプロパティ
    • scalar.dl.ledger.proof.enabled (true に設定)
      • Ledger 認証ではアセットプルーフの署名が使用されるため必須です。
    • scalar.dl.ledger.proof.private_key_pem または scalar.dl.ledger.proof.private_key_path
      • アセットプルーフに署名するために使用されます。
      • 秘密鍵の取得方法については、こちらを参照してください。
• Auditor 側のプロパティ
  • scalar.dl.auditor.ledger.cert_holder_id
  • scalar.dl.auditor.ledger.cert_version
    • アセットプルーフの署名を検証するために使用されます。
• Auditor の認証
  • Ledger 側のプロパティ
    • scalar.dl.ledger.auditor.cert_holder_id
      • クライアント要求に添付された Auditor が生成した署名を検証するために使用されます。
    • scalar.dl.ledger.auditor.cert_version
      • クライアント要求に添付された Auditor が生成した署名を検証するために使用されます。
  • Auditor 側のプロパティ
    • scalar.dl.auditor.cert_holder_id
      • クライアントライブラリを使用して Ledger サービスを直接呼び出すために使用されます。
    • scalar.dl.auditor.cert_version
      • クライアントライブラリを使用して Ledger サービスを直接呼び出すために使用されます。
    • scalar.dl.auditor.private_key_pem または scalar.dl.auditor.private_key_path
      • クライアントのリクエストと Auditor から Ledger へのリクエストに署名するために使用されます。
      • 秘密鍵の取得方法については、こちらを参照してください。

HMAC

• クライアント認証

  • クライアント側のプロパティ
    • scalar.dl.client.authentication_method (hmacに設定)
    • scalar.dl.client.entity.id ※お客様を識別するために使用します。
    • scalar.dl.client.entity.identity.hmac.secret_key
      • リクエストの署名に使用されます。
      • シークレットキーはランダムな長い値 (例: 32文字の長さの16進文字列) である必要があります。
    • scalar.dl.client.entity.identity.hmac.secret_key_version
  • Ledger 側のプロパティ
    • scalar.dl.ledger.authentication.method (hmacに設定)
  • Auditor 側のプロパティ
    • scalar.dl.auditor.authentication.method (hmacに設定)

• Ledger と Auditor の認証

  • Ledger 側のプロパティ
    • scalar.dl.ledger.proof.enabled (true に設定)
      • Ledger 認証ではアセットプルーフの署名が使用されるため必須です。
    • scalar.dl.ledger.servers.authentication.hmac.secret_key
      • Ledger と Auditor 間のメッセージとリクエストの署名と検証に使用されます。
      • シークレットキーはランダムな長い値 (例: 32文字の長さの16進文字列) である必要があります。
    • scalar.dl.ledger.authentication.hmac.cipher_key
      • クライアントのシークレットキーの暗号化および復号に使用されます。
      • 暗号キーは、予測できない長い値である必要があります。
  • Auditor 側のプロパティ
    • scalar.dl.auditor.servers.authentication.hmac.secret_key
      • Ledger と Auditor 間のメッセージとリクエストの署名と検証に使用されます。scalar.dl.ledger.servers.authentication.hmac.secret_key と同じキーである必要があります。
      • シークレットキーはランダムな長い値 (例: 32文字の長さの16進文字列) である必要があります。
    • scalar.dl.auditor.authentication.hmac.cipher_key
      • クライアントのシークレットキーの暗号化および復号に使用されます。
      • 暗号キーは、予測できない長い値である必要があります。

リクエストを実行する前に準備する

設定後、実行リクエストを発行する準備として次の作業を行う必要があります。

電子署名

• クライアントの証明書を Ledger (および有効な場合は Auditor) に登録します。
  • クライアントライブラリまたはコマンドラインツール (register-cert) を使用します。
• Auditor の証明書を Ledger に登録します。
  • Auditor が有効な場合にのみ必須です。
• Auditor に Ledger 証明書を登録します。
  • Auditor が有効な場合にのみ必須です。
• コントラクトを Ledger (および有効な場合は Auditor) に登録します。

HMAC

• クライアントのシークレットキーを Ledger (および有効な場合は Auditor) に登録します。
  • クライアントライブラリまたはコマンドラインツール (register-secret) を使用します。
• コントラクトを Ledger (および Auditor) に登録します。