本頁面由 Cloud Translation API 翻譯而成。

私密/公開金鑰組

私密/公開金鑰組可讓代理程式與使用者的裝置建立彼此專屬的對話雜湊訊息。代理程式和「訊息」應用程式會使用私密/公開金鑰組，以計算共用密鑰並安全地對訊息內容進行雜湊處理，讓「已驗證簡訊」與 Google 無法讀取內容。

建立代理程式後，您必須建立代理程式的金鑰組，並使用已驗證簡訊更新代理程式的公開金鑰。代理程式執行後，您必須先取得使用者的公開金鑰，才能將已驗證訊息傳送給他們。

使用者公開金鑰

當您準備好傳送已驗證郵件時，您必須先取得支援簡訊驗證的收件者公開金鑰，才能建立並儲存訊息雜湊。您最多可在單一 API 呼叫中取得 10,000 個公開金鑰。

有時候，訊息應用程式會輪替公開金鑰，因此您在傳送任何訊息前，都必須取得使用者的公開金鑰，即使您先前已傳送已驗證訊息給使用者。如果您建立含有已過時公開金鑰的訊息雜湊，「訊息」應用程式就會根據目前的公開金鑰產生雜湊，最後產生雜湊不相符。如果已驗證簡訊無法比對訊息雜湊，您的訊息會顯示為未驗證。

當您儲存雜湊時，已驗證簡訊範例和 SDK 可取得已驗證簡訊使用者的公開金鑰。如果您選擇不使用範例和 SDK，以下程式碼就會取得一或多個使用者的公開金鑰。如需格式設定和值選項，請參閱 enabledUserKeys.batchGet。

如果已驗證簡訊的使用者電話號碼未啟用，已驗證簡訊就不會傳回該電話號碼的任何公開金鑰。

curl -X POST "https://verifiedsms.googleapis.com/v1/enabledUserKeys:batchGet" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/verified-sms" \
  -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY verifiedsms`" \
  -d "{
    'phoneNumbers': [
      'PHONE_NUMBER',
      'PHONE_NUMBER',
      'PHONE_NUMBER',
    ]
  }"

代理程式私密/公開金鑰組

代理程式在訊息雜湊處理期間，會使用私密金鑰和使用者公開金鑰對訊息內容進行模糊處理，「訊息」應用程式會使用使用者的私密金鑰和代理程式的公開金鑰。要讓已驗證簡訊代理程式正常運作，代理程式必須建立金鑰組，並將目前的公開金鑰與已驗證簡訊共用，讓訊息應用程式能夠存取。

建立代理程式的金鑰組

如要為代理程式建立金鑰組，請在終端機中執行下列指令。

openssl ecparam -name secp384r1 -genkey -outform PEM -noout -out verified-sms-AGENT_NAME-private-key-P-384.pem
openssl pkcs8 -topk8 -nocrypt -in verified-sms-AGENT_NAME-private-key-P-384.pem -outform DER -out verified-sms-AGENT_NAME-private-key-P-384-pkcs8.der
openssl ec -in verified-sms-AGENT_NAME-private-key-P-384.pem -pubout -outform DER -out verified-sms-AGENT_NAME-public-key-P-384.der

指令會產生三個檔案：

verified-sms-AGENT_NAME-private-key-P-384.pem 是 PEM 格式的私密金鑰，雖然未使用，但非常重要。
verified-sms-AGENT_NAME-private-key-P-384-pkcs8.der 是 SDK 用來建立訊息雜湊的私密金鑰。請勿將金鑰與已驗證簡訊分享。
verified-sms-AGENT_NAME-public-key-P-384.der 是訊息應用程式使用的公開金鑰，可為代理程式的訊息建立訊息雜湊。建立代理程式時，此為必要項目。

將私密金鑰檔案儲存在安全的地方，但可用於基礎架構。請勿分享你的私密金鑰。

現在您已為代理程式建立金鑰，現在需使用已驗證簡訊更新代理程式的公開金鑰。

更新代理程式的公開金鑰

您隨時可以變更代理程式的私人/公開金鑰組。無論是要遵守安全性規定，還是推出遭駭的金鑰組，更新代理程式的金鑰就跟建立新的金鑰組一樣，並使用已驗證簡訊更新代理程式的公開金鑰一樣簡單。

建議每週更新金鑰一次，這樣前三週的所有雜湊值仍會保持有效，以免發生延遲傳送的情況。

下列處理程序和程式碼會更新代理程式的公開金鑰。如需格式設定和值選項，請參閱 agents.updateKey。

開發人員控制台

Base-44 編碼代理程式的公開金鑰，並記下值。
開啟 Business Communications Developer Console，然後使用已驗證簡訊的 Google 帳戶登入。
按一下你的代理程式。
在左側導覽面板中，按一下 [代理程式資訊]。
在「Agent public key」(代理程式公開金鑰) 部分，輸入您的 Base64 編碼公開金鑰。
按一下「儲存」。

cURL

curl -X PATCH "https://verifiedsms.googleapis.com/v1/agents/AGENT_ID/key" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/verified-sms" \
  -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY verifiedsms`" \
  -d "{
    'name': 'AGENT_ID',
    'publicKey': 'BASE64-ENCODED_PUBLIC_KEY'
  }"

Java

在終端機中設定必要的環境變數。

export VERIFIED_SMS_PUBLIC_KEY_PATH="PATH_TO_PUBLIC_KEY.DER"
export VERIFIED_SMS_PRIVATE_KEY_PATH="PATH_TO_PRIVATE_KEY_PKCS8.DER"
export VERIFIED_SMS_SERVICE_ACCOUNT_PATH="PATH_TO_SERVICE_ACCOUNT_KEY.JSON"

請根據下列範例編輯並執行程式碼。

String agentId = getEnvVariable("VERIFIED_SMS_AGENT_ID");
String publicKeyPath = getEnvVariable("VERIFIED_SMS_PUBLIC_KEY_PATH");
String serviceAccountJson = getEnvVariable("VERIFIED_SMS_SERVICE_ACCOUNT_PATH");

LOGGER.info("Reading credentials/creating client ... ");
VerifiedSmsServiceClient verifiedSmsServiceClient =
        new VerifiedSmsServiceClient.Builder()
        .setServiceAccountKeyStream(new FileInputStream(serviceAccountJson))
        .build();

LOGGER.info("Reading public key... ");
byte[] publicKeyBytes = Files.readAllBytes(Paths.get(publicKeyPath));

LOGGER.info("Updating agent's public key in asynchronous way...");
CountDownLatch latch = new CountDownLatch(1);
verifiedSmsServiceClient.updateKey(
        agentId,
        publicKeyBytes,
        new VerifiedSmsCompletionCallback() {
            @Override
            public void onSuccess() {
                LOGGER.info("Updating key completed.");
                latch.countDown();
            }

            @Override
            public void onFailure(Throwable t) {
                LOGGER.warning("  Updating key failed: " + t);
                latch.countDown();
            }
        });

latch.await(); // Wait for callback to be completed.

LOGGER.info("Shutting down the service...");
verifiedSmsServiceClient.shutdown();

這段程式碼是關於已驗證簡訊範例和 SDK 的一部分。

Python

在終端機中設定必要的環境變數。

export VERIFIED_SMS_PUBLIC_KEY_PATH="PATH_TO_PUBLIC_KEY.DER"
export VERIFIED_SMS_PRIVATE_KEY_PATH="PATH_TO_PRIVATE_KEY_PKCS8.DER"
export VERIFIED_SMS_SERVICE_ACCOUNT_PATH="PATH_TO_SERVICE_ACCOUNT_KEY.JSON"

請根據下列範例編輯並執行程式碼。

import os
from verified_sms_client_library.verified_sms_service_client import VerifiedSmsServiceClient

def main():
    # Read environment variables
    agent_id = os.environ['VERIFIED_SMS_AGENT_ID']
    public_key_path = os.environ['VERIFIED_SMS_PUBLIC_KEY_PATH']
    service_account_location = os.environ['VERIFIED_SMS_SERVICE_ACCOUNT_PATH']

    # Read the private key file
    with open(public_key_path, mode='rb') as file:
        print('Reading the agent\'s public key ...')
        public_key_as_bytes = file.read()

        print('Creating the Verified SMS Api Client ...')
        vsms_service_client = VerifiedSmsServiceClient(service_account_location=service_account_location)

        print('Updating agent\'s public key')
        vsms_service_client.update_key(agent_id, public_key_as_bytes)

這段程式碼是關於已驗證簡訊範例和 SDK 的一部分。

Node.js

在終端機中設定必要的環境變數。

export VERIFIED_SMS_PUBLIC_KEY_PATH="PATH_TO_PUBLIC_KEY.DER"
export VERIFIED_SMS_PRIVATE_KEY_PATH="PATH_TO_PRIVATE_KEY_PKCS8.DER"
export VERIFIED_SMS_SERVICE_ACCOUNT_PATH="PATH_TO_SERVICE_ACCOUNT_KEY.JSON"

請根據下列範例編輯並執行程式碼。

const fs = require('fs');
const verifiedSmsServiceClient = require('./lib/verified_sms_client_library/verfied_sms_service_client');

// Read environment variables to run sample
let agentId = process.env.VERIFIED_SMS_AGENT_ID;
let publicKeyPath = process.env.VERIFIED_SMS_PUBLIC_KEY_PATH;
let serviceAccountLocation = process.env.VERIFIED_SMS_SERVICE_ACCOUNT_PATH;

// Convert into types needed for client library
let serviceAccountAsJson = require(serviceAccountLocation);

console.log('Reading public key...');
let publicKeyAsBytes = fs.readFileSync(publicKeyPath);
let publicKey = publicKeyAsBytes.toString('base64');

function updateKey() {
    console.log('Initializing the Verified SMS Service Client...');
    verifiedSmsServiceClient.initWithServiceAccount(serviceAccountAsJson);
    let updateKeyPromise = verifiedSmsServiceClient.updateKey(agentId, publicKey);

    console.log('Updating agent\'s public key...');
    updateKeyPromise.then((response) => {
        console.log(response);
    })
    .catch((err) => {
      console.log(err);
    });
}

module.exports = updateKey;

這段程式碼是關於已驗證簡訊範例和 SDK 的一部分。

使用代理程式的公開金鑰進行 Base64 編碼

在某些情況下，例如在開發人員控制台中更新代理程式的公開金鑰時，您可能需要將公開金鑰表示為文字。如要產生金鑰的文字表示法，請在終端機中使用 base64 指令。

以下程式碼會產生代理程式公開金鑰的 Base64 編碼字串，如建立代理程式的金鑰組中所述。

base64 verified-sms-AGENT_NAME-public-key-P-384.der

取得代理程式的公開金鑰

如果您不確定某個公開金鑰是否已向已驗證簡訊註冊，您可以取得代理程式目前註冊的公開金鑰。如果代理程式使用的金鑰組與使用已驗證簡訊註冊的公開金鑰不符，則您建立及儲存的雜湊可能無效，且可能導致未經驗證的訊息。

註冊已驗證簡訊的金鑰可能與公開金鑰不符，原因如下：

您使用的是舊版公開/私密金鑰組。找出並使用與已驗證簡訊註冊的公開金鑰相符的金鑰組。
您已建立新的金鑰組，但未使用已驗證簡訊更新公開金鑰。更新公開金鑰。

當公開金鑰相符時，您就可以開始雜湊處理訊息。

以下程式碼會取得代理程式的公開金鑰。如需格式設定和值選項，請參閱 agents.getKey。

curl -X GET "https://verifiedsms.googleapis.com/v1/agents/AGENT_ID/key" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/verified-sms" \
  -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY verifiedsms`"

後續步驟

現在，您的代理程式可以擷取使用者公開金鑰，並已透過已驗證簡訊註冊公開金鑰，那麼您現在可以開始設定訊息雜湊功能。