Richiamo delle chiavi per stato

Filtrando lo stato delle specifiche chiavi nella tua istanza Key Protect, puoi recuperare le chiavi che si trovano negli stati specificati.

Ad esempio, potresti avere delle chiavi nella tua istanza Key Protect che si trovano nello stato attivo, sospeso e distrutto, ma vuoi richiamare le chiavi nello stato attivo solo quando guardi un elenco di chiavi.

Per ulteriori informazioni sugli stati chiave, vedi Stati chiave e transizioni.

Dopo aver creato o importato le tue chiavi esistenti nel servizio, hai due opzioni per visualizzare le tue chiavi. La prima opzione, Visualizza le chiavi attraverso l'elenco delle risorse, funziona per tutte le chiavi, tranne quelle con accesso a grana fine. Per informazioni sulla visualizzazione delle chiavi con accesso a livello fine, vedere Visualizzazione delle chiavi di accesso a livello fine IAM.

Recupero di un elenco di chiavi

Per una vista di alto livello, puoi sfogliare le chiavi che sono gestite nella tua istanza fornita di Key Protect effettuando una chiamata GET al seguente endpoint.

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

1. Richiama le tue credenziali di autenticazione per lavorare con le chiavi nel servizio.

2. Visualizza le caratteristiche generali relative alle tue chiavi immettendo il seguente comando curl.

   $ 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>"
   

   Sostituire le variabili nella richiesta di esempio in base alle informazioni riportate nella Tabella 1. Per ulteriori informazioni sui parametri facoltativi disponibili quando visualizzi le raccolte di chiavi, inclusa la possibilità di ricercare le tue chiavi, consulta la documentazione API relativa al metodo List keys.

Una richiesta GET api/v2/keys con esito positivo restituisce una raccolta di chiavi disponibili nella tua istanza del servizio Key Protect.

{
    "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
            }
        }
    ]
}

Per impostazione predefinita, GET api/v2/keys restituisce le prime 200 chiavi ma puoi regolare questo limite utilizzando il parametro limit al momento della query. Per ulteriori informazioni sui parametri limit e offset, vedi Richiamo di un sottoinsieme di chiavi.

Non vedi l'elenco completo di chiavi? Potrebbe essere necessario consultare le pagine limit e offset oppure rivolgersi all'amministratore per assicurarsi di disporre del livello di accesso corretto alle chiavi nella propria istanza. Per ulteriori informazioni, vedi Impossibile visualizzare o elencare le chiavi.

Richiamo di un sottoinsieme di chiavi

Specificando i parametri limit e offset nel momento della query, puoi richiamare un sottoinsieme delle tue chiavi, a partire dal valore di offset che specifichi.

Ad esempio, potresti avere un totale di 3000 chiavi memorizzate nella tua istanza di Key Protect, ma desideri recuperare le chiavi da 200 a 300 quando effettui una richiesta GET /keys.

Puoi utilizzare la seguente richiesta di esempio per richiamare una diverso insieme di chiavi.

$ 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>"

Sostituisci le variabili limit e offset nella tua richiesta in base alla seguente tabella.

L'offset è la posizione di una determinata chiave in un dataset. Il valore di offset è a base zero, il che significa che la decima chiave di crittografia in un dataset è all'offset 9.

Richiamo delle chiavi per stato

Specificando il parametro state al momento della query, è possibile recuperare le chiavi che si trovano negli stati specificati.

Ad esempio, potresti avere chiavi nella tua istanza Key Protect che sono nello stato attivo, sospeso e distrutto, ma vuoi richiamare le chiavi solo nello stato attivo quando fai una richiesta GET /keys.

Il parametro della query di stato accetta un elenco di numeri interi da 0 a 5 delimitati da virgole senza spazi o virgole finali. Per ulteriori informazioni sugli stati chiave, vedi Stati chiave e transizioni.

Puoi utilizzare la seguente richiesta di esempio per richiamare una diverso insieme di chiavi.

$ 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>"

Sostituisci la variabile state nella tua richiesta in base alla tabella seguente.

Per ulteriori informazioni sull'utilizzo, consulta i seguenti esempi su come impostare il parametro di query state.

Richiamo delle chiavi per valore estraibile

Specificando il parametro extractable al momento della query, puoi recuperare le chiavi il cui materiale può lasciare il servizio.

Ad esempio, potresti avere sia chiavi standard che root nella tua istanza Key Protect, ma vuoi richiamare solo le chiavi con il materiale della chiave estraibile quando fai una richiesta GET /keys.

Il parametro di query estraibile assume un valore booleano.

Puoi utilizzare la seguente richiesta di esempio per richiamare una diverso insieme di chiavi.

$ 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>"

Sostituisci la variabile extractable nella tua richiesta in base alla tabella seguente.

Per ulteriori informazioni sull'utilizzo, consulta i seguenti esempi su come impostare il parametro di query extractable.

Ordinamento di un elenco di chiavi

Utilizzando il parametro sort nella stringa di interrogazione si ordina l'elenco di chiavi restituite in base a una o più proprietà chiave. Per ordinare una proprietà in ordine decrescente, anteporre il termine con "-". Per ordinare su più proprietà chiave, utilizzare una virgola per separare ciascuna proprietà. La prima proprietà dell'elenco separato da virgole viene valutata prima della successiva.

$ 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>"