存取安全中繼資料和驗證套件

本頁說明如何從 assuredoss-metadata Cloud Storage 值區存取安全性中繼資料。如要瞭解安全性中繼資料,請參閱「安全性中繼資料欄位」。

本頁面僅適用於 Assured OSS 進階層級。如要瞭解免費方案,請參閱「在 Assured OSS 免費方案中驗證簽章」。

事前準備

設定驗證

擷取中繼資料

您可以使用 gcloudcurl 指令下載中繼資料。使用下列資訊建構這兩者的網址:

  • 語言: javapythonjavascript。值必須為小寫。
  • Package_ID:Java 為 groupId:artifactId,Python 為 packageName,JavaScript 則為 @org-name/package-name@username/package-namepackage-name。值必須為小寫。
  • 版本:套件版本。

網址必須採用下列格式:

gcloud

gs://assuredoss-metadata/language/package_id/version/metadata.json

網址必須為小寫。

Python 網址範例:gs://assuredoss-metadata/python/blessed/1.20.0/metadata.json

Java 網址範例:gs://assuredoss-metadata/java/org.apache.logging.log4j:log4j-core/2.17.1/metadata.json

JavaScript 網址範例:gs://assuredoss-metadata/javascript/@stoplight/spectral-core/0.0.0/metadata.json

curl

https://storage.googleapis.com/assuredoss-metadata/language/package_id/version/metadata.json

網址必須為小寫。

Python 網址範例:https://storage.googleapis.com/assuredoss-metadata/python/blessed/1.20.0/metadata.json

Java 網址範例:https://storage.googleapis.com/assuredoss-metadata/java/org.apache.logging.log4j:log4j-core/2.17.1/metadata.json

JavaScript 網址範例:https://storage.googleapis.com/assuredoss-metadata/javascript/@stoplight/spectral-core/0.0.0/metadata.json

  1. 下載中繼資料:

gcloud

gcloud storage cp "gs://assuredoss-metadata/language/package_id/version/metadata.json" outputFolderLocation

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -L https://storage.googleapis.com/assuredoss-metadata/language/package_id/version/metadata.json -o metadata.json

現在可以驗證簽章。以下提供兩種方案供您選擇:

使用 aoss-verifier 工具驗證下載套件的簽章

使用 aoss-verifier 工具驗證套件中繼資料。

使用這項工具前,請先安裝 Go

  1. 安裝 aoss-verifier 工具。

  2. 匯出「$(go env GOPATH)/bin」。

  3. 請執行 aoss-verifier verify-metadata 指令。

    aoss-verifier verify-metadata \
       --metadata_type TYPE \
       --language LANGUAGE \
       --package_id PACKAGE_ID \
       --version VERSION \
       [--disable_certificate_verification] \
       [--temp_downloads_path TEMP_DOWNLOADS_DIR_PATH] \
       [--disable_deletes]
    

    更改下列內容:

    • TYPE:可能的值為 premiuminfo
    • LANGUAGE:套件語言。 值必須為小寫。
    • PACKAGE_ID:如果是 Java,格式為 groupId:artifactId。如果是 Python,格式為 packageName。值必須為小寫。
    • VERSION:套件版本。

    --disable_certificate_verification 是選填的標記,如果使用,系統會略過透過憑證鏈結將分葉憑證與根憑證相符的程序。

    --temp_downloads_path 是選用標記,可設定要下載檔案的路徑 (請替換 TEMP_DOWNLOADS_DIR_PATH)。如果未設定標記,檔案會下載至目前目錄中的 tmp_downloads 資料夾。

    --disable_deletes 是選用旗標,可保留下載的檔案。根據預設,這項工具會清除所有已下載的檔案。

詳情請參閱 README

手動驗證下載套件的簽章

您只能驗證由 Assured OSS 安全建構的二進位檔的構件簽章,無法驗證透過 Proxy 由 Assured OSS 提供的二進位檔。

如要手動驗證簽章,可以使用各種工具。下列步驟會使用 gcloud CLI、OpenSSL (3.0.1 以上版本) 和 jq (1.7.1 以上版本) 在 Linux 上驗證簽章。

  1. 下載中繼資料檔案。 如「安全性中繼資料欄位」所述,中繼資料檔案包含 buildInfo 欄位內的 SBOM 欄位。SBOM 包含建構的構件 (例如 JAR 或 EGG 檔案),以及代表簽章的註解。這個構件可讓您判斷 SPDX ID。

    舉例來說,如果構件名稱為 artifact_name,則 spdx_idSPDXRef-Package-artifact_name。如要驗證名為 gradio-3.30.0-py3-none-any.whl 的套件,請使用 spdx_id SPDXRef-Package-gradio-3.30.0-py3-none-any.whl

  2. 從中繼資料檔案擷取 SHA-256 摘要:

    cat METADATA_FILENAME | jq -rj '.buildInfo' | jq -rj '.sbom' | jq -rj '.packages' | jq '.[] | select(.SPDXID=="SPDX_ID")' | jq -rj '.annotations[0].comment' | jq -rj '.digest[0].digest' | cut -d ' ' -f1 > expectedDigest.txt
    

    更改下列內容:

    • METADATA_FILENAME:安全中繼資料檔案的名稱。

    • SPDX_ID:SPDX ID。

  3. 計算構件摘要:

    sha256sum ARTIFACT_FILE | cut -d ' ' -f1 > actualDigest.txt
    

    ARTIFACT_FILE 替換為構件檔案名稱。

  4. 檢查兩者是否有任何差異:

    diff actualDigest.txt expectedDigest.txt
    

    如果沒有差異,就不會輸出任何內容。

  5. 將欄位的摘要擷取至 .bin 檔案:

    cat METADATA_FILENAME | jq -rj '.buildInfo' | jq -rj '.sbom' | jq -rj '.packages' | jq '.[] | select(.SPDXID=="SPDX_ID")' | jq -rj '.annotations[0].comment' | jq -rj '.digest[0].digest' | cut -d ':' -f2 | xxd -r -p > digest.bin
    
  6. 將摘要的簽章擷取至 .sig 檔案:

    cat METADATA_FILENAME | jq -rj '.buildInfo' | jq -rj '.sbom' | jq -rj '.packages' | jq '.[] | select(.SPDXID=="SPDX_ID")' | jq -rj '.annotations[0].comment' | jq -rj '.signature[0].signature' | xxd -r -p > sig.sig
    
  7. 從公開憑證中將公開金鑰擷取至 .pem 檔案:

    cat METADATA_FILENAME | jq -rj '.buildInfo' | jq -rj '.sbom' | jq -rj '.packages' | jq '.[] | select(.SPDXID=="SPDX_ID")' | jq -rj '.annotations[0].comment' | jq -rj '.certInfo.cert' | openssl x509 -pubkey -noout  > pubKey.pem
    
  8. 使用擷取的公開金鑰驗證摘要的簽章:

    openssl pkeyutl -in digest.bin -inkey pubKey.pem -pubin -verify -sigfile sig.sig
    

    如果成功,這項指令會傳回 Signature Verified Successfully。 現在可以驗證憑證。

  9. 將公開憑證擷取至 .pem 檔案:

    cat METADATA_FILENAME | jq -rj '.buildInfo' | jq -rj '.sbom' | jq -rj '.packages' | jq '.[] | select(.SPDXID=="SPDX_ID")' | jq -rj '.annotations[0].comment' | jq -rj '.certInfo.cert' > cert.pem
    
  10. 下載根憑證 (下列指令中的 ca.crt):

    curl -o ca.crt https://privateca-content-6333d504-0000-2df7-afd6-30fd38154590.storage.googleapis.com/a2c725a592f1d586f1f8/ca.crt
    
  11. 使用擷取的憑證和根憑證驗證憑證:

    openssl verify -verbose -CAfile ca.crt cert.pem
    

    如果成功,這項指令會傳回 cert.pem: OK

驗證安全中繼資料欄位的簽章

您可以獨立驗證安全性中繼資料檔案中下列欄位的簽章:

  • buildInfo
  • vexInfo
  • healthInfo (如有)

欄位中的資料會使用 SHA-256 雜湊處理,然後使用 ECDSAP256_DER 演算法簽署雜湊。中繼資料內提供憑證和憑證鏈結,方便您驗證簽章。使用下列根憑證驗證憑證鏈結:

https://privateca-content-6333d504-0000-2df7-afd6-30fd38154590.storage.googleapis.com/a2c725a592f1d586f1f8/ca.crt

您可以手動驗證簽章,也可以使用 Assured OSS 驗證工具驗證簽章。

下列步驟說明如何手動驗證 metadata.json 檔案中 buildInfo 欄位的簽章。您可以按照類似的步驟驗證 vexInfo 欄位或 healthInfo 欄位的簽章。

您可以使用各種工具驗證簽名。下列範例使用 gcloud CLI、OpenSSL (3.0.1 以上版本) 和 jq (1.7.1 以上版本) 在 Linux 系統上驗證簽章。

  1. 產生欄位的 SHA-256 摘要:

    cat metadata.json | jq -rj '.buildInfo' | sha256sum | cut -d ' ' -f1 > actualDigest.txt
    
  2. metadata.json 檔案中擷取欄位的摘要:

    cat metadata.json | jq -rj '.buildInfoSignature.digest[0].digest' | cut -d ':' -f2 > expectedDigest.txt
    
  3. 檢查這兩個摘要是否有任何差異:

    diff actualDigest.txt expectedDigest.txt
    

    如果沒有差異,就不會輸出任何內容,這是最理想的情況。現在可以驗證簽章。

  4. 將欄位的摘要擷取至 .bin 檔案:

    cat metadata.json | jq -rj '.buildInfoSignature.digest[0].digest' | cut -d ':' -f2 | xxd -r -p > digest.bin
    
  5. 將摘要的簽章擷取至 .sig 檔案:

    cat metadata.json | jq -rj '.buildInfoSignature.signature[0].signature' | xxd -r -p > sig.sig
    
  6. 從公開憑證中將公開金鑰擷取至 .pem 檔案:

    cat metadata.json | jq -rj '.buildInfoSignature.certInfo.cert' | openssl x509 -pubkey -noout  > pubKey.pem
    
  7. 使用擷取的公開金鑰驗證摘要的簽章:

    openssl pkeyutl -in digest.bin -inkey pubKey.pem -pubin -verify -sigfile sig.sig
    

    如果驗證成功,這項指令會傳回 Signature Verified Successfully。現在可以驗證憑證。

  8. 將公開憑證擷取至 .pem 檔案:

    cat metadata.json | jq -rj '.buildInfoSignature.certInfo.cert' > cert.pem
    
  9. 下載根憑證,在下列指令中名為 ca.crt

    curl -o ca.crt https://privateca-content-6333d504-0000-2df7-afd6-30fd38154590.storage.googleapis.com/a2c725a592f1d586f1f8/ca.crt
    
  10. 使用擷取的憑證和根憑證驗證憑證:

    openssl verify -verbose -CAfile ca.crt cert.pem
    

    如果成功,指令會傳回 cert.pem: OK