跳到主要內容

金鑰對聲明

「金鑰對聲明」是一項強大的功能，允許您的應用程式請求使用者的錢包產生一個新的加密金鑰對。這對於建立新的、特定於應用程式的帳戶或身份特別有用，這些帳戶或身份由使用者的錢包安全管理，但專門用於與您的服務互動。

您可以將管理使用者憑證的責任轉移到使用者的 DID 錢包，從而增強安全性與使用者控制權。

使用案例

  • 特定應用程式帳戶： 當使用者註冊時，您可以請求一個新的金鑰對，以便在您的應用程式中為他們建立一個專用帳戶。這個新帳戶的 DID 與使用者的主要 DID 是不同的。
  • 會話或裝置金鑰： 產生用於特定會話或裝置的臨時金鑰對，透過限制金鑰的範圍和生命週期來增強安全性。
  • 身份遷移： 透過指定 migrateFrom 屬性，簡化使用者從舊帳戶遷移到新帳戶的過程。

運作方式

當您請求 keyPair 聲明時，DID 錢包將會向使用者顯示您提供的描述。如果使用者批准，錢包將根據您設定的參數（targetType）產生一個新的金鑰對。預設情況下，錢包也會在區塊鏈上宣告這個新的 DID。然後，錢包會透過安全的 DID Connect 通道將新的金鑰對（公鑰、私鑰和地址）回傳給您的應用程式。

參數

keyPair 聲明接受以下參數：

NameTypeDescription
descriptionstring必需。 顯示給使用者的訊息，解釋為什麼需要新的金鑰對。
monikerstring必需。 新帳戶的人類可讀名稱，將在使用者的錢包中可見。必須符合正規表示式 ^[a-zA-Z0-9][-a-zA-Z0-9_]{2,128}$。
declareboolean可選。如果為 true（預設值），新的 DID 將在鏈上宣告。設定為 false 以產生鏈下金鑰對。
migrateFromstring可選。要從中遷移的 DID 地址。錢包可以使用此資訊將新帳戶連結到舊帳戶。
targetTypeobject可選。一個物件，指定要產生的金鑰對的加密屬性。

targetType 物件

您可以使用 targetType 物件自訂產生的金鑰對類型：

KeyTypeDefaultDescription
rolestringaccountDID 的角色，例如 account、application、blocklet。
keystringed25519加密金鑰演算法，例如 ed25519、secp256k1。
hashstringsha3用於產生地址的雜湊演算法，例如 sha3、sha2、keccak。
encodingstringbase58地址的編碼方式，例如 base58、base16。

範例：請求新帳戶

這是一個如何為使用者請求新金鑰對的範例，該金鑰對可用作他們在您應用程式中的帳戶。

Requesting a new key pair

javascript
const claims = {
  keyPair: {
    description: '為我們超棒的應用程式建立一個新帳戶',
    moniker: 'my-app-account',
    targetType: {
      role: 'account',
    },
  },
};

// 在您的處理常式中
const { authInfo } = await authenticator.sign({
  claims,
  // ... 其他情境屬性
});

範例：為 Blocklet 產生金鑰對

如果您正在建置一個 Blocklet，您可能需要一個具有特定角色的金鑰對。您也可以選擇不立即在鏈上宣告它，並從現有的 DID 進行遷移。

Requesting a key pair for a blocklet

javascript
const claims = {
  keyPair: {
    description: '產生金鑰對以管理您的新 Blocklet',
    moniker: 'my-blocklet-key',
    declare: false, // 產生金鑰對，但不廣播宣告交易
    migrateFrom: 'z3CtKiQt2QnLXaZfEfBYvJHTZoPXJggnHEYx4', // 要從中遷移的 DID
    targetType: {
      role: 'blocklet',
      key: 'ed25519',
      hash: 'sha3',
    },
  },
};

// 在您的處理常式中
const { authInfo } = await authenticator.sign({
  claims,
  // ... 其他情境屬性
});

錢包回應

如果使用者批准請求，您的應用程式的 onAuth 回呼函式將在 claims 陣列中收到新產生的金鑰對。單一 keyPair 聲明的回應將如下所示：

Wallet Response Example

json
{
  "type": "keyPair",
  "sk": "...", // 新金鑰對的私鑰
  "pk": "...", // 新金鑰對的公鑰
  "address": "...", // 新金鑰對的 DID 地址
  "moniker": "my-app-account",
  "meta": {}
}

您的應用程式應安全地處理收到的私鑰（sk），因為它授予對新建立的 DID 的完全控制權。

現在您已經了解如何請求新的金鑰對，您可能會對為其他目的派生金鑰感興趣。

下一步：加密金鑰聲明

了解如何請求錢包使用提供的鹽值從其主金鑰派生出一個秘密加密金鑰。

閱讀更多