Utilizzare il tuo OVHcloud Key Management Service (KMS)

Crittografa o firma i tuoi dati con l'API REST regionale del Key Management Service (KMS) OVHcloud

Obiettivo

L'obiettivo di questa guida è presentare le diverse fasi per interagire con il KMS OVHcloud allo scopo di crittografare o firmare i tuoi dati.

Prerequisiti

Disporre di un account cliente OVHcloud.
Aver ordinato un KMS OVHcloud.
Aver configurato un metodo di autenticazione per il piano dati OKMS (token di accesso personale, account di servizio o certificato di accesso).

Procedura

Comunicare con il KMS

La comunicazione con il KMS per le azioni di crittografia e di firma avviene tramite le API.

Poiché il KMS è regionalizzato, l'accesso all'API avviene direttamente nella sua regione: https://my-region.okms.ovh.net.

Ad esempio, per un KMS creato nella regione eu-west-rbx: https://eu-west-rbx.okms.ovh.net

È possibile comunicare con il KMS utilizzando:

L'interfaccia utente Swagger
La CLI OKMS: https://github.com/ovh/okms-cli
L'SDK Golang: https://pkg.go.dev/github.com/ovh/okms-sdk-go

Autenticati tramite un token di accesso personale, un account di servizio o un certificato di accesso. Per l'utilizzo dell'API REST, si consiglia un token di accesso personale (PAT) o un account di servizio. I certificati di accesso sono obbligatori per le integrazioni KMIP.

Per testare le chiamate API in modo interattivo, utilizza l'interfaccia Swagger OKMS all'indirizzo https://<region>.okms.ovh.net/swagger/.

Creare una chiave di crittografia tramite API

La creazione di una chiave può essere effettuata tramite la oppure tramite le API specifiche del KMS OVHcloud. Non c'è alcuna differenza sul risultato in base al metodo di creazione.

Info

Le route seguenti utilizzano l'identificativo del tuo dominio OKMS. Viene restituito dalla seguente chiamata API:

GET/okms/resource

È visibile anche, insieme all'endpoint regionale, nella scheda Informazioni generali del .

Nel caso delle API specifiche del KMS OVHcloud, la creazione di una chiave avviene tramite la seguente API:

Metodo	Percorso	Descrizione
POST	/api/{okmsId}/v1/servicekey	Creare o importare una CMK

L'API prevede i seguenti valori:

Campo	Valore	Descrizione
name	string	Nome della chiave
context	string	Dato di identificazione supplementare che permette di verificare l'autenticità della chiave
type	oct, RSA, EC	Tipo della chiave: sequenza di byte (oct) per chiavi simmetriche, RSA (RSA), Elliptic Curve (EC)
size	Integer	Dimensione della chiave - vedi tabella di corrispondenza qui sotto
operations	Array	Utilizzo della chiave - vedi tabella di corrispondenza qui sotto
curve	P-256, P-384, P-521	(facoltativo) Curva crittografica per le chiavi di tipo EC
extractable	boolean	(facoltativo) Indica se il materiale di chiave potrà essere esportato - consulta la sezione Attributi di sensibilità delle chiavi di servizio qui sotto

Esempio di creazione di una chiave simmetrica:

{
  "name": "My first AES key",
  "context": "project A",
  "type": "oct",
  "size": 256,
  "operations": [
    "encrypt",
    "decrypt"
  ]
}

Esempio di creazione di una chiave asimmetrica:

{
  "name": "My first RSA key",
  "context": "project A",
  "type": "RSA",
  "size": 4096,
  "operations": [
    "sign",
    "verify"
  ]
}

Esempio di creazione di una chiave EC:

{
  "name": "My first EC key",
  "context": "project A",
  "type": "EC",
  "operations": [
    "sign",
    "verify"
  ],
  "curve": "P-256"
}

Le dimensioni e le operazioni possibili in base al tipo di chiave sono le seguenti:

oct:
- dimensione: 128, 192, 256
- operazioni:
  - encrypt, decrypt
  - wrapKey, unwrapKey
RSA:
- dimensione: 2048, 3072, 4096
- operazioni:
  - sign, verify
  - wrapKey, unwrapKey
EC:
- dimensione: non specificare
- curve: P-256, P-384, P-521
- operazioni: sign, verify

Info

Per le chiavi RSA, wrapKey / unwrapKey sono mutuamente esclusive con sign / verify.

Importare una chiave di crittografia

Al momento della creazione di una chiave, è possibile importare una chiave esistente in chiaro in formato JWK.

Warning

L'importazione di materiale di chiave in chiaro non è consigliata per le chiavi che devono rimanere affidabili. Preferisci il BYOK sicuro con incapsulamento RSA asimmetrico.

A tale scopo, puoi aggiungere un campo supplementare keys nel corpo della richiesta:

{
  "name": "My imported key",
  "keys": [
    {
      "kid": "string",
      "use": "string",
      "key_ops": [
        "string"
      ],
      "alg": "string",
      "kty": "oct",
      "n": "string",
      "e": "string",
      "k": "string",
      "crv": "string",
      "x": "string",
      "y": "string",
      "d": "string",
      "dp": "string",
      "dq": "string",
      "p": "string",
      "q": "string",
      "qi": "string"
    }
  ]
}

La chiave deve essere in formato JSON Web Key (JWK). Il valore dei campi contenuti nella tabella segue la documentazione della RFC 7518.

Gestire le chiavi di crittografia

Per gestire le chiavi di crittografia, sono disponibili diverse API:

Metodo	Percorso	Descrizione
GET	/api/{okmsId}/v1/servicekey	Elenca le chiavi di crittografia disponibili
DELETE	/api/{okmsId}/v1/servicekey/{keyId}	Elimina una chiave di crittografia
POST	/api/{okmsId}/v1/servicekey/{keyId}/activate	Attiva una chiave di crittografia
POST	/api/{okmsId}/v1/servicekey/{keyId}/deactivate	Disattiva una chiave di crittografia

La disattivazione di una chiave di crittografia implica che questa non sarà più utilizzabile, benché la chiave resti presente nel KMS.

L'eliminazione di una chiave di crittografia è possibile solo su una chiave precedentemente disattivata.

Warning

L'eliminazione di una chiave di crittografia è definitiva. Tutti i dati crittografati con essa saranno definitivamente inaccessibili.

Attributi di sensibilità delle chiavi di servizio

Quando crei o recuperi una chiave di servizio, gli indicatori di sensibilità ed estraibilità vengono restituiti nell'oggetto attributes della risposta GET (insieme ad altri metadati come state). Solo extractable è impostabile dall'utente (alla creazione o tramite PATCH). Gli altri indicatori sono impostati dal KMS. Impostare extractable su true fissa definitivamente never_extractable su false.

Attributo	Impostabile dall'utente?	Descrizione
`extractable`	Sì (creazione / PATCH)	Se `true`, il materiale di chiave può essere esportato (in chiaro o incapsulato, a seconda della classe di chiave). Predefinito: `false` — tranne le chiavi solo pubbliche, il cui valore predefinito è `true`.
`never_extractable`	No	`true` se la chiave non è mai stata estraibile dalla creazione nel KMS. Le chiavi importate con BYOK o tramite importazione in chiaro hanno `never_extractable` impostato su `false`, perché il materiale esisteva al di fuori del KMS prima dell'importazione. Attivare l'estrazione cancella anche questo indicatore in modo permanente.
`sensitive`	No	`true` quando la chiave può essere estratta solo dopo essere stata incapsulata (il che richiede anche che `extractable` sia `true`). Le chiavi segrete e private (materiale AES/`oct` e RSA/EC privato) sono sempre considerate sensibili.
`always_sensitive`	No	`true` se la chiave è sempre stata sensibile dalla creazione.

Esempio di risposta GET (campi abbreviati):

{
  "id": "<key-id>",
  "name": "aes-to-export",
  "type": "oct",
  "attributes": {
    "state": "active",
    "extractable": true,
    "never_extractable": false,
    "sensitive": true,
    "always_sensitive": true
  }
}

Per estrarre una chiave in modo sicuro, imposta extractable su true solo per l'operazione di esportazione, esportala con incapsulamento RSA, poi riportalo su false. Consulta Esportare una chiave incapsulata.

Crittografare un dato con il KMS

Crittografia sul KMS

Il KMS OVHcloud dispone di un'API di crittografia dedicata per la crittografia di piccoli volumi di dati (meno di 4 kB).

Si tratta del metodo più semplice, ma che non offre le migliori prestazioni.

Metodo	Percorso	Descrizione
POST	/api/{okmsId}/v1/servicekey/{keyId}/encrypt	Crittografia di dati con una CMK

L'API prevede i seguenti valori:

Campo	Valore	Descrizione
plaintext	string	Dato da crittografare
context	string	Dato di identificazione supplementare che permette di verificare l'autenticità del dato

Esempio di crittografia

{
  "plaintext": "My secret data",
  "context": "Project A"
}

L'API restituisce poi il dato crittografato in un campo ciphertext:

{
  "ciphertext": "Encrypted data",
}

La decrittografia del dato avviene in modo inverso tramite l'API:

Metodo	Percorso	Descrizione
POST	/api/{okmsId}/v1/servicekey/{keyId}/decrypt	Decrittografia di dati con una CMK

L'API prevede i seguenti valori:

Campo	Valore	Descrizione
ciphertext	string	Dato da decrittografare
context	string	Dato di identificazione supplementare che permette di verificare l'autenticità del dato

Il campo context deve avere lo stesso valore di quello indicato durante la crittografia.

Crittografia con una Data Key (DK)

Per ottenere prestazioni migliori, è possibile generare una Data Key (DK) a partire da una chiave simmetrica (AES) per utilizzarla dalla tua applicazione. La chiave AES utilizzata deve essere stata generata con le operazioni wrapKey e unwrapKey.

La generazione di una DK avviene tramite la seguente API:

Metodo	Percorso	Descrizione
POST	/api/{okmsId}/v1/servicekey/{keyId}/datakey	Generare una DK derivata da una CMK

L'API prevede i seguenti valori:

Campo	Valore	Descrizione
name	string	Nome della chiave
size	Integer	Dimensione della chiave (64-4096)

Esempio di generazione di una Data Key:

{
  "name": "My Data Key",
  "size": 4096
}

L'API restituirà poi la Data Key:

{
  "key": "string",
  "plaintext": "string"
}

key: chiave crittografata codificata in base64. Questa informazione deve essere memorizzata con il dato crittografato e sarà utilizzata per la decrittografia da parte del KMS.
plaintext: chiave in chiaro codificata in base64. Questa informazione deve essere eliminata una volta effettuata la crittografia e non deve essere salvata.

L'utilizzo della Data Key avviene poi tramite algoritmi di crittografia come AES-GCM, che non è trattato in questa documentazione.

Al contrario, è possibile recuperare la versione decrittografata di una Data Key tramite la seguente API:

Metodo	Percorso	Descrizione
POST	/api/{okmsId}/v1/servicekey/{keyId}/datakey/decrypt	Decrittografia di una DK

L'API prevede i seguenti valori:

Campo	Valore	Descrizione
key	string	Data Key crittografata

E restituisce la Data Key decrittografata in un campo plaintext.

Firmare con il KMS

La firma di un file avviene tramite la chiave privata di una coppia di chiavi asimmetriche.

Algoritmi supportati

Il KMS OVHcloud supporta il seguente elenco di algoritmi di firma:

RSASSA-PKCS1 v1.5

Nome	Digital Signature Algorithm
RS256	RSASSA-PKCS1-v1_5 using SHA-256
RS384	RSASSA-PKCS1-v1_5 using SHA-384
RS512	RSASSA-PKCS1-v1_5 using SHA-512

Secondo la documentazione della RFC 7518.

ECDSA

Nome	Digital Signature Algorithm
ES256	ECDSA using P-256 and SHA-256
ES384	ECDSA using P-384 and SHA-384
ES512	ECDSA using P-521 and SHA-512

Secondo la documentazione della RFC 7518.

RSASSA-PSS

Nome	Digital Signature Algorithm
PS256	RSASSA-PSS using SHA-256 and MGF1 with SHA-256
PS384	RSASSA-PSS using SHA-384 and MGF1 with SHA-384
PS512	RSASSA-PSS using SHA-512 and MGF1 with SHA-512

Secondo la documentazione della RFC 7518.

Firma di un messaggio

Dato che la chiave privata non può essere estratta in chiaro dal KMS, la firma può avvenire solo direttamente presso il KMS.

Metodo	Percorso	Descrizione
POST	/api/{okmsId}/v1/servicekey/{keyId}/sign	Firma di un file

L'API prevede i seguenti valori:

Campo	Valore	Descrizione
message	string	Messaggio da firmare in formato base64
alg	string	Algoritmo di firma
isdigest	boolean	Indica se il messaggio è già sottoposto ad hash

Esempio di firma:

{
  "message": "SGVsbG8gV29ybGQ=",
  "alg": "RS256",
  "isdigest": false
}

L'API restituirà poi la firma del file:

{
  "signature": "EmUGXC6rsFTWtmFn77y6NS/U6IuhThApVKWTZdXjE7rDMonRPPxbjTo01HQN62J3Dxqyw=="
}

Verifica di un file

La verifica di un file può avvenire direttamente presso il KMS oppure utilizzando la chiave pubblica.

Presso il KMS, è possibile utilizzare la seguente API:

Metodo	Percorso	Descrizione
POST	/api/{okmsId}/v1/servicekey/{keyId}/verify	Verifica di una firma

L'API prevede i seguenti valori:

Campo	Valore	Descrizione
message	string	Messaggio da firmare
signature	string	Firma associata al messaggio
alg	string	Algoritmo di firma
isdigest	boolean	Indica se il messaggio è già sottoposto ad hash

Esempio di verifica

{
  "message": "SGVsbG8gV29ybGQ=",
  "signature": "EmUGXC6rsFTWtmFn77y6NS/U6IuhThApVKWTZdXjE7rDMonRPPxbjTo01HQN62J3Dxqyw==",
  "alg": "RS256",
  "isdigest": false
}

L'API restituirà poi il risultato della verifica:

{
  "result": true
}

Per saperne di più

Importare ed esportare chiavi su OVHcloud KMS con BYOK

Metodi di autenticazione OKMS

Come connettere un prodotto compatibile utilizzando il protocollo KMIP

Contatta la nostra Community di utenti.

Questa pagina ti è stata utile?