Schlüssel nach Status abrufen

Wenn Sie den Status bestimmter Schlüssel in Ihrer Key Protect -Instanz filtern, können Sie Schlüssel abrufen, die sich in den von Ihnen angegebenen Status befinden.

Sie können beispielsweise Schlüssel in Ihrer Key Protect Instanz haben, die sich in den aktiven, ausgesetzten und zerstörten Status befinden. Sie möchten jedoch nur die Schlüssel im aktiven Status abrufen, wenn Sie eine Liste mit Schlüsseln durchsehen.

Weitere Informationen zu Schlüsselstatus finden Sie in Schlüsselstatus und -übergänge.

Nachdem Sie Ihre Schlüssel erstellt oder Ihre vorhandenen in den Service importiert haben, haben Sie zwei Möglichkeiten, Ihre Schlüssel anzuzeigen. Die erste Option, Schlüssel über die Ressourcenliste anzeigen, funktioniert für alle Schlüssel mit Ausnahme derjenigen, denen Sie differenzierten Zugriff auf zugewiesen haben. Informationen zum Anzeigen von Schlüsseln mit differenziertem Zugriff finden Sie unter Schlüssel mit differenziertem Zugriff anzeigen (IAM).

Liste mit Schlüsseln abrufen

Für eine übergeordnete Ansicht können Sie die Schlüssel durchsuchen, die in Ihrer bereitgestellten Instanz von Key Protect verwaltet werden, indem Sie einen GET-Aufruf an den folgenden Endpunkt absetzen.

https://<region>.kms.cloud.ibm.com/api/v2/keys

1. Rufen Sie Ihre Authentifizierungsnachweise ab, um mit den Schlüsseln im Service zu arbeiten.

2. Zeigen Sie allgemeine Merkmale zu Ihren Schlüsseln an, indem Sie den folgenden Befehl curl ausführen.

   $ curl -X GET \
       "https://<region>.kms.cloud.ibm.com/api/v2/keys" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: Bearer <IAM_token>" \
       -H "bluemix-instance: <instance_ID>" \
       -H "x-kms-key-ring: <key_ring_ID>" \
       -H "correlation-id: <correlation_ID>"
   

   Ersetzen Sie die Variablen in der Beispielanforderung gemäß den Informationen in Tabelle 1. Weitere Informationen zu optionalen Parametern, die beim Anzeigen von Schlüsselobjektgruppen verfügbar sind, einschließlich der Möglichkeit, Ihre Schlüssel zu durchsuchen, finden Sie im API-Dokumentation zur Methode List keys.

Eine erfolgreiche Anforderung GET api/v2/keys gibt eine Gruppe von Schlüsseln zurück, die in Ihrer Key Protect-Serviceinstanz verfügbar sind.

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key+json",
        "collectionTotal": 2
    },
    "resources": [
        {
            "id": "02fd6835-6001-4482-a892-13bd2085f75d",
            "type": "application/vnd.ibm.kms.key+json",
            "name": "Root-key",
            "state": 1,
            "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
            "createdBy": "...",
            "creationDate": "2020-03-11T16:30:06Z",
            "lastUpdateDate": "2020-03-11T16:30:06Z",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "Deprecated"
            },
            "extractable": false,
            "imported": true,
            "algorithmMode": "Deprecated",
            "algorithmBitSize": 256,
            "dualAuthDelete": {
                "enabled": false
            }
        },
        {
            "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "type": "application/vnd.ibm.kms.key+json",
            "name": "Standard-key",
            "state": 1,
            "expirationDate": "2020-03-14T03:50:12Z",
            "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:30372f20-d9f1-40b3-b486-a709e1932c9c:key:2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "createdBy": "...",
            "creationDate": "2020-03-12T03:50:12Z",
            "lastUpdateDate": "2020-03-12T03:50:12Z",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "Deprecated"
            },
            "extractable": true,
            "imported": false,
            "algorithmMode": "Deprecated",
            "algorithmBitSize": 256,
            "dualAuthDelete": {
                "enabled": false
            }
        }
    ]
}

Standardmäßig gibt die Anforderung GET api/v2/keys die ersten 200 Schlüssel zurück. Sie können diese Begrenzung jedoch mithilfe des Parameters limit bei der Abfrage anpassen. Weitere Informationen zu limit und offset finden Sie unter Untergruppe von Schlüsseln abrufen.

Wird nicht die vollständige Liste der Schlüssel angezeigt? Sie müssen möglicherweise die Parameter limit und offset verwenden oder zusammen mit dem Administrator sicherstellen, dass Ihnen die richtige Zugriffsebene für Schlüssel in Ihrer Instanz zugewiesen ist. Weitere Informationen hierzu finden Sie unter Schlüssel können nicht angezeigt oder aufgelistet werden.

Untergruppe von Schlüsseln abrufen

Durch die Angabe der Parameter limit und offset bei der Abfrage können Sie eine Untergruppe Ihrer Schlüssel abrufen, die mit dem Wert beginnt, den Sie für offset angeben.

Beispiel: In Ihrer Key Protect-Instanz sind insgesamt 3000 Schlüssel gespeichert und beim Absetzen einer Anforderung GET /keys sollen nur die Schlüssel 200 - 300 abgerufen werden.

Sie können die folgende Beispielanforderung verwenden, um eine andere Gruppe von Schlüsseln abzurufen.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?offset=<offset>&limit=<limit>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Ersetzen Sie die Variablen limit und offset in der Anforderung, wie in der folgenden Tabelle beschrieben.

Mit dem Wert für 'offset' wird die relative Position eines bestimmten Schlüssels im Dataset angegeben. Der Wert für offset wird mit der Basis null angegeben, d. h., dass sich der zehnte Verschlüsselungsschlüssel in einem Dataset an der Position 9 befindet.

Schlüssel nach Status abrufen

Durch die Angabe des Parameters state in der Abfrage können Sie Schlüssel abrufen, die die Statuswerte aufweisen, die Sie angeben.

Beispiel: Ihre Key Protect-Instanz enthält Schlüssel, die sich im Status 'Aktiv', 'Ausgesetzt' bzw. 'Gelöscht' befinden, und es sollen nur die Schlüssel mit dem Status 'Aktiv' abgerufen werden, wenn Sie eine Anforderung GET /keys absetzen.

Die Abfrageparameter 'state' akzeptiert eine Liste ganzzahliger Werte von 0 bis 5, die durch Kommas getrennt und ohne Leerzeichen oder abschließendes Komma angegeben werden. Weitere Informationen zu Schlüsselstatus finden Sie in Schlüsselstatus und -übergänge.

Sie können die folgende Beispielanforderung verwenden, um eine andere Gruppe von Schlüsseln abzurufen.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?state=<state_integers>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Ersetzen Sie die Variable für den Parameter state in Ihrer Anforderung anhand der Angaben in der folgenden Tabelle.

Hinweise zur Verwendung können Sie den folgenden Beispielen für das Festlegen des Abfrageparameters state entnehmen.

Schlüssel nach Extractable-Wert abrufen

Wenn Sie den Parameter extractable zur Abfragezeit angeben, können Sie Schlüssel abrufen, deren Material den Service verlassen kann.

Sie können z. B. sowohl Standard-als auch Rootschlüssel in Ihrer Key Protect -Instanz haben, aber Sie möchten nur Schlüssel mit extrahierbarem Schlüsselmaterial abrufen, wenn Sie eine Anforderung GET /keys erstellen.

Der Parameter für die extrahierbare Abfrage verwendet einen booleschen Wert.

Sie können die folgende Beispielanforderung verwenden, um eine andere Gruppe von Schlüsseln abzurufen.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?extractable=<extractable>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Ersetzen Sie die Variable für den Parameter extractable in Ihrer Anforderung anhand der Angaben in der folgenden Tabelle.

Hinweise zur Verwendung können Sie den folgenden Beispielen für das Festlegen des Abfrageparameters extractable entnehmen.

Sortieren einer Liste von Schlüsseln

Mit dem Parameter sort in der Abfragezeichenfolge wird die Liste der Schlüssel, die zurückgegeben werden, basierend auf einer oder mehreren Schlüsseleigenschaften sortiert. Um nach einer Eigenschaft in absteigender Reihenfolge zu sortieren, stellen Sie dem Begriff "-" voran. Verwenden Sie zum Sortieren nach mehreren Schlüsseleigenschaften ein Komma, um die einzelnen Eigenschaften voneinander zu trennen. Die erste Eigenschaft in der durch Kommas getrennten Liste wird vor der nächsten ausgewertet.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?sort=<sort-value>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"