Attestierer mit der REST API erstellen

Auf dieser Seite wird erläutert, wie Sie mithilfe der REST API einen benutzerdefinierten Attestierer in der Binärautorisierung erstellen.

Alternativ können Sie diese Schritte auch mit der Google Cloud CLI oder der Google Cloud Console ausführen. Diese Aufgabe ist Teil der Einrichtung der Binärautorisierung.

Cloud Build-Nutzer: Sie können stattdessen den Attestierer built-by-cloud-build verwenden, um nur von Cloud Build erstellte Images bereitzustellen.

Überblick

Ein Attestierer ist eine Google Cloud-Ressource, mit der die Binärautorisierung eine Attestierung prüft. Weitere Informationen zu Attestierungen finden Sie in der Übersicht über die Binärautorisierung.

So erstellen Sie einen Attestierer:

Erstellen Sie einen Hinweis in Artefaktanalyse, um darin vertrauenswürdige Metadaten zu speichern, die für den Attestierungsvorgang verwendet werden.
Richten Sie ein PKIX-Schlüsselpaar ein, mit dem die Identität des Attestierers geprüft werden kann. Asymmetrische Schlüsselpaare, die vom Cloud Key Management Service (Cloud KMS) generiert werden, haben ein PKIX-kompatibles Format. Sie können anstelle von PKIX-Schlüsseln auch PGP-Schlüsselpaare verwenden.
Erstellen Sie den Attestierer in der Binärautorisierung und verknüpfen Sie den Hinweis mit dem öffentlichen Schlüssel, den Sie erstellt haben.

In einer Einzelprojekteinrichtung erstellen Sie den Attestierer im selben Google Cloud-Projekt, in dem Sie die Richtlinie für die Binärautorisierung konfigurieren. Bei einer Einrichtung mit mehreren Projekten haben Sie höchstwahrscheinlich ein Bereitstellerprojekt, in dem Ihre Richtlinie konfiguriert ist, sowie ein separates Attestiererprojekt, in dem Ihre Attestierer gespeichert sind.

Hinweise

Standardprojekt festlegen

Legen Sie das Google Cloud-Standardprojekt fest, falls Sie dies noch nicht getan haben:

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

Umgebung einrichten

Richten Sie Umgebungsvariablen zum Speichern Ihrer Projektnamen und -nummern ein:

DEPLOYER_PROJECT_ID=${PROJECT_ID}
DEPLOYER_PROJECT_NUMBER="$(
    gcloud projects describe "${DEPLOYER_PROJECT_ID}" \
      --format="value(projectNumber)"
)"
ATTESTOR_PROJECT_ID=${PROJECT_ID}
ATTESTOR_PROJECT_NUMBER="$(
    gcloud projects describe "${ATTESTOR_PROJECT_ID}" \
    --format="value(projectNumber)"
)"

Wenn Ihr Attestiererprojekt mit Ihrem Bereitstellerprojekt identisch ist, verwenden Sie für beide Variablen dieselbe Projekt-ID.

Außerdem müssen Sie die Dienstkontonamen für die Projekte abrufen:

DEPLOYER_SERVICE_ACCOUNT="service-${DEPLOYER_PROJECT_NUMBER}@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
ATTESTOR_SERVICE_ACCOUNT="service-${ATTESTOR_PROJECT_NUMBER}@gcp-sa-binaryauthorization.iam.gserviceaccount.com"

Artefaktanalyse-Hinweis erstellen

Die Binärautorisierung verwendet Artefaktanalyse, um vertrauenswürdige Metadaten zu speichern, die für den Autorisierungsvorgang verwendet werden. Für jeden von Ihnen erstellten Attestierer muss ein Artefaktanalyse-Hinweis angelegt werden. Jede Attestierung wird als Vorkommen dieses Hinweises gespeichert.

So erstellen Sie einen Artefaktanalyse-Hinweis:

Richten Sie Umgebungsvariablen zum Speichern der Hinweis-ID und einer für Menschen lesbare Beschreibung ein:
```
NOTE_ID=NOTE_ID
NOTE_URI="projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}"
DESCRIPTION=DESCRIPTION
```
Ersetzen Sie Folgendes:
- NOTE_ID ist der interne Name des Hinweises in alphanumerischen Zeichen ohne Leerzeichen (z. B. test-attestor-note).
- NOTE_URI ist der voll qualifizierte Pfad zur Hinweisressource.
- DESCRIPTION ist ein für Menschen lesbarer Anzeigename für den Hinweis (z. B. Test Attestor Note).

Erstellen Sie in einem Texteditor eine JSON-Datei in /tmp/note_payload.json, die den Artefaktanalyse-Hinweis beschreibt:

cat > /tmp/note_payload.json << EOM
{
  "name": "${NOTE_URI}",
  "attestation": {
    "hint": {
      "human_readable_name": "${DESCRIPTION}"
    }
  }
}
EOM

Erstellen Sie den Hinweis, indem Sie eine HTTP-Anfrage an die Artifact Analysis REST API senden:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/note_payload.json  \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/?noteId=${NOTE_ID}"

Um zu prüfen, ob der Hinweis erstellt wurde, führen Sie folgenden Befehl aus:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/"

Berechtigungen für den Hinweis festlegen

Sie müssen auch Berechtigungen für den von Ihnen erstellten Artefaktanalyse-Hinweis festlegen, damit er für das Dienstkonto des Attestiererprojekts zugänglich ist. Aktualisieren Sie dazu die IAM-Richtlinie für den Hinweis und weisen Sie dem Konto die Rolle containeranalysis.notes.occurrences.viewer zu.

So legen Sie die Berechtigungen fest:

Erstellen Sie eine JSON-Datei mit den Informationen, die zum Festlegen der IAM-Richtlinie für Ihren Hinweis erforderlich sind:

cat > /tmp/iam_request.json << EOM
{
  'resource': '${NOTE_URI}',
  'policy': {
    'bindings': [
      {
        'role': 'roles/containeranalysis.notes.occurrences.viewer',
        'members': [
          'serviceAccount:${ATTESTOR_SERVICE_ACCOUNT}'
        ]
      }
    ]
  }
}
EOM

Fügen Sie der IAM-Richtlinie für den von Ihnen erstellten Hinweis das Dienstkonto und die angeforderten Zugriffsrollen hinzu:
```
curl -X POST  \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/iam_request.json \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}:setIamPolicy"
```
Wenn Sie der Richtlinie mithilfe der obigen Methode eine Rolle hinzufügen, werden alle vorhandenen Rollen für den Hinweis ersetzt. Wenn Sie vorhandene Rollen beibehalten möchten, nehmen Sie diese beim Festlegen der Richtlinie explizit in die JSON-Daten auf.

Kryptografische Schlüssel einrichten

Mit der Binärautorisierung können Sie mithilfe von PKIX-Schlüsseln die Identität des Signaturgebers, der eine Attestierung erstellt hat, sicher prüfen. Dies gewährleistet, dass nur bestätigte Nutzer ein Container-Image autorisieren können. Alternativ zu PKIX haben Sie auch die Möglichkeit, PGP-Schlüssel zu verwenden.

PKIX-Schlüsselpaar erstellen

Mit der Binärautorisierung können Sie zur Bestätigung einer Attestierung asymmetrische PKIX-Schlüsselpaare verwenden. Das Schlüsselpaar besteht aus einem privaten Schlüssel, mit dem der Signaturgeber Attestierungen digital signiert, und einem öffentlichen Schlüssel, den Sie dem Attestierer hinzufügen. Später prüft der Erzwinger der Binärautorisierung anhand des öffentlichen Schlüssels im Attestierer, ob die Attestierung vom Signaturgeber erstellt wurde.

In diesem Leitfaden wird der empfohlene Elliptic Curve Digital Signing Algorithm (ECDSA) verwendet, um ein PKIX-Schlüsselpaar zu erstellen. Sie können zum Signieren auch RSA- oder PGP-Schlüssel verwenden. Weitere Informationen zu Signieralgorithmen finden Sie unter Schlüsselzwecke und Algorithmen.

Die in Cloud KMS erstellten und gespeicherten asymmetrischen Schlüsselpaare sind mit dem PKIX-Format konform. Informationen zum Erstellen eines Cloud KMS-Schlüssels für die Binärautorisierung finden Sie unter Asymmetrische Schlüssel erstellen. Achten Sie darauf, dass beim Erstellen des Schlüssels als Schlüsselzweck Asymmetrisches Signieren ausgewählt wird.

PKIX (Cloud KMS)

So erstellen Sie das Schlüsselpaar in Cloud KMS:

Führen Sie die folgenden Befehle aus, um Umgebungsvariablen einzurichten, die zum Erstellen des Schlüsselpaars erforderlich sind:
```
KMS_KEY_PROJECT_ID=KMS_KEY_PROJECT_ID
KMS_KEY_LOCATION=KMS_KEY_LOCATION
KMS_KEYRING_NAME=KMS_KEYRING_NAME
KMS_KEY_NAME=KMS_KEY_NAME
KMS_KEY_VERSION=KMS_KEY_VERSION
KMS_KEY_PURPOSE=asymmetric-signing
KMS_KEY_ALGORITHM=KMS_KEY_ALGORITHM
KMS_PROTECTION_LEVEL=KMS_PROTECTION_LEVEL
```
Ersetzen Sie Folgendes:
- KMS_KEY_PROJECT_ID: die ID des Projekts, in dem die Schlüssel gespeichert sind.
- KMS_KEY_LOCATION: der Speicherort des Schlüssels
- KMS_KEYRING_NAME: der Name des Schlüsselbunds
- KMS_KEY_NAME: der Name des Schlüssels
- KMS_KEY_VERSION: die Schlüsselversion
- KMS_KEY_ALGORITHM: der Algorithmus; ec-sign-p256-sha256 wird empfohlen
- KMS_PROTECTION_LEVEL: das Schutzniveau, z. B. software.

Führen Sie den folgenden Befehl aus, um das Schlüsselbund zu erstellen:

gcloud kms keyrings create ${KMS_KEYRING_NAME} \
    --location ${KMS_KEY_LOCATION}

Führen Sie den folgenden Befehl aus, um den Schlüssel zu erstellen:

gcloud kms keys create ${KMS_KEY_NAME} \
    --location ${KMS_KEY_LOCATION} \
    --keyring ${KMS_KEYRING_NAME}  \
    --purpose ${KMS_KEY_PURPOSE} \
    --default-algorithm ${KMS_KEY_ALGORITHM} \
    --protection-level ${KMS_PROTECTION_LEVEL}

PKIX (lokaler Schlüssel)

So erstellen Sie ein neues lokales asymmetrisches PKIX-Schlüsselpaar und speichern es in einer Datei:

Erstellen Sie den Domainschlüssel:

PRIVATE_KEY_FILE="/tmp/ec_private.pem"
openssl ecparam -genkey -name prime256v1 -noout -out ${PRIVATE_KEY_FILE}

Da diese Datei einen öffentlichen und einen privaten Schlüssel enthält, müssen Sie den öffentlichen Schlüssel in eine eigene Datei extrahieren, damit Sie ihn dem Attestierer hinzufügen können:
```
PUBLIC_KEY_FILE="/tmp/ec_public.pem"
openssl ec -in ${PRIVATE_KEY_FILE} -pubout -out ${PUBLIC_KEY_FILE}
```

Attestierer erstellen

Im nächsten Schritt erstellen Sie den Attestierer in der Binärautorisierung mit dem verknüpften Artefaktanalyse-Hinweis. Außerdem müssen Sie den kryptografischen öffentlichen Schlüssel hinzufügen.

So erstellen Sie den Attestierer:

Richten Sie eine Umgebungsvariable zum Speichern des Namens des Attestierers wie in der Binärautorisierung definiert ein:
```
ATTESTOR_NAME=ATTESTOR_NAME
```
Dabei ist ATTESTOR_NAME der Name des Attestierers, den Sie erstellen möchten (z. B. build-secure oder prod-qa).

Erstellen Sie den Attestierer und hängen Sie den öffentlichen Sicherheitsschlüssel an:

PKIX (Cloud KMS)

Richten Sie zusätzliche Umgebungsvariablen ein, um Informationen über das Cloud KMS-Schlüsselpaar für den Aufruf der API für die Binärautorisierung zu speichern.

KMS_CRYPTO_KEY_URI="projects/${KMS_KEY_PROJECT_ID}/locations/${KMS_KEY_LOCATION}/keyRings/${KMS_KEYRING_NAME}/cryptoKeys/${KMS_KEY_NAME}"
KMS_CRYPTO_KEY_VERSION_URI="${KMS_CRYPTO_KEY_URI}/cryptoKeyVersions/${KMS_KEY_VERSION}"
KMS_KEY_ID="//cloudkms.googleapis.com/v1/${KMS_CRYPTO_KEY_VERSION_URI}"

Laden Sie die öffentliche Schlüsseldatei von Cloud KMS herunter und speichern Sie sie auf Ihrem lokalen System in einer Datei namens /tmp/kms_public_key.pem.

Erstellen Sie eine JSON-Datei, die die zum Erstellen des Attestierers erforderlichen Informationen enthält:

cat > /tmp/attestor.json << EOM
{
    "userOwnedDrydockNote": {
        "noteReference": "${NOTE_URI}",
        "publicKeys": {
            "id": "${KMS_KEY_ID}",
            "pkixPublicKey": {
                "signatureAlgorithm": "${KMS_KEY_ALGORITHM}",
                "publicKeyPem": $( \
                    python < /tmp/kms_public_key.pem \
                    -c 'import json, sys; print(json.dumps(sys.stdin.read()))' \
                )
            }
        }
    }
}
EOM

Erstellen Sie den Attestierer:

curl -X POST  \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/attestor.json \
"https://binaryauthorization.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/attestors?attestorId=${ATTESTOR_NAME}"

PKIX (lokaler Schlüssel)

Erstellen Sie eine JSON-Datei, die die zum Erstellen des Attestierers erforderlichen Informationen enthält:

cat > /tmp/attestor.json << EOM
{
   "userOwnedGrafeasNote": {
       "noteReference": "${NOTE_URI}",
       "publicKeys": {
           "pkixPublicKey": {
               "signatureAlgorithm": "ecdsa_p256_sha256",
               "publicKeyPem": $( \
                   python < ${PUBLIC_KEY_FILE} \
                   -c 'import json, sys; print(json.dumps(sys.stdin.read()))' \
               )
           }
       }
   }
}
EOM

Erstellen Sie den Attestierer:

curl -X POST  \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \
   --data-binary @/tmp/attestor.json \
"https://binaryauthorization.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/attestors?attestorId=${ATTESTOR_NAME}"

Fügen Sie dem Attestierer eine IAM-Rollenbindung für das Bereitstellerprojekt hinzu. Diese wird von der Binärautorisierung verwendet, wenn eine Richtlinie ausgewertet wird, um festzustellen, ob das Projekt Berechtigungen zum Zugriff auf den entsprechenden Attestierer hat.

Erstellen Sie eine JSON-Datei mit den Informationen, die zum Festlegen der IAM-Richtlinie für Ihren Attestierer erforderlich sind:

cat > /tmp/iam_request.json << EOM
{
  'resource': 'projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}',
  'policy': {
    'bindings': [
      {
        'role': 'roles/binaryauthorization.attestorsVerifier',
        'members': [
          'serviceAccount:${DEPLOYER_SERVICE_ACCOUNT}'
        ]
      }
    ]
  }
}
EOM

Fügen Sie der IAM-Richtlinie für den von Ihnen erstellten Hinweis das Dienstkonto und die angeforderten Zugriffsrollen hinzu:

curl -X POST  \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/iam_request.json \
    "https://binaryauthorization.googleapis.com/v1beta1/projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}:setIamPolicy"

Erstellung des Attestierers prüfen

Führen Sie den folgenden Befehl aus, um zu überprüfen, ob der Attestierer erstellt wurde:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    "https://binaryauthorization.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/attestors/"

Nächste Schritte

Attestierungen für Ihren Attestierer erstellen
Aktualisieren Sie Ihre Richtlinie für die Binärautorisierung so, dass Attestierungen über die Google Cloud Console, das Google Cloud CLI und die REST API erforderlich sind.