Informazioni di riferimento sulle API proxy EKM per la gestione delle chiavi esterne del modulo di protezione hardware gestito

Questo articolo illustra l'API proxy EKM, ovvero l'interfaccia tra il modulo di protezione hardware gestito e un proxy EKM gestito dal cliente in una configurazione di gestione delle chiavi esterna . La versione dell'API coperta è 0.1-preview.

Informazioni generali

La gestione delle chiavi esterne del modulo di protezione hardware gestito consente ai clienti di archiviare chiavi di crittografia delle chiavi (KEK) in un modulo di protezione hardware gestito dal cliente all'esterno dell'infrastruttura Microsoft. Quando Azure servizi devono eseguire il wrapping o annullare il wrapping di una chiave di crittografia dei dati, il modulo di protezione hardware gestito delega l'operazione di crittografia a un proxy EKM eseguito dal cliente usando questa API.

L'API proxy non fornisce funzionalità per la creazione, l'eliminazione o la modifica di chiavi all'interno del sistema di gestione delle chiavi esterne. Le chiavi devono esistere nel modulo di protezione hardware esterno prima di associarle a un riferimento alla chiave del modulo di protezione hardware gestito. Sono supportate le operazioni seguenti:

Operation	Description
Ottenere informazioni sul proxy	Restituisce i dettagli del proxy e la versione più elevata dell'API supportata. Usato anche per verificare e monitorare la raggiungibilità del proxy.
Ottenere i metadati della chiave	Restituisce il tipo di chiave, le dimensioni e le operazioni supportate per una chiave esterna.
Eseguire il wrapping della chiave	Esegue il wrapping di una chiave crittografica usando l'algoritmo specificato.
Annulla il wrapping della chiave	Annulla il wrapping di una chiave di cui è stato eseguito il wrapping in precedenza.

Tipo di trasporto e contenuto

Tutte le richieste e le risposte devono usare JSON su HTTPS con Content-Type: application/json. Il proxy deve supportare HTTP 1.1 e TLS 1.3 con i pacchetti di crittografia seguenti:

TLS_AES_256_GCM_SHA384
TLS_AES_128_GCM_SHA256

Authentication

Mutual TLS (mTLS) autentica entrambe le parti:

Proxy del modulo di protezione hardware gestito →: HSM gestito presenta un certificato client X.509. Il proxy deve applicare mTLS rifiutando le richieste senza un certificato client valido. I clienti devono essere in grado di configurare sia il nome comune soggetto (CN) che la CA radice usata per autenticare le richieste del modulo di protezione hardware gestito.
Proxy → modulo di protezione hardware gestito: Il certificato server del proxy deve essere rilasciato dalla CA configurata nel modulo di protezione hardware gestito durante l'installazione di EKM. Il nome comune del certificato server deve corrispondere al nome di dominio completo dell'endpoint proxy o a un carattere jolly per tale dominio. Ad esempio, se l'endpoint è server.ekmproxy.example.com, il cn deve essere server.ekmproxy.example.com o *.ekmproxy.example.com.

Formato URI

Tutte le chiamate API usano il modello URI seguente:

https://{server}/[path-prefix]/{api-specific-paths}?api-version={client-api-version}

path-prefix è facoltativo e impostato in HSM gestito durante la configurazione della connessione EKM. Consente l'uso multi-cliente o l'isolamento di più pool di moduli di protezione hardware gestiti che condividono lo stesso proxy.

Vincoli:

Prefisso percorso: massimo 64 caratteri; lettere (a-z, A-Z), numeri (0-9), barre () e trattini (/-) solo.
Identificatore di chiave esterna: massimo 64 caratteri; lettere (a-z, A-Z), numeri (0-9) e trattini (-) solo.

Un singolo proxy EKM può gestire più pool di moduli di protezione hardware gestiti. Usare il prefisso del percorso per instradare le richieste da pool diversi a spazi dei nomi isolati nello stesso proxy.

Ora di risposta

Il proxy deve rispondere a tutte le chiamate API entro 250 millisecondi. Il modulo di protezione hardware gestito raggiunge il timeout delle richieste che superano questa soglia.

Contesto della richiesta

Ogni corpo della richiesta include un request_context oggetto che correla i log del modulo di protezione hardware gestito con i log del proxy EKM. Registrare queste informazioni nei log proxy in ogni richiesta.

Name	TIPO	Description
`request_id`	Stringa	ID richiesta assegnato dal client HSM gestito di origine. Optional.
`correlation_id`	Stringa	ID di correlazione assegnato dal modulo di protezione hardware gestito, usato per collegare i log e i record di controllo tra sistemi.
`pool_name`	Stringa	Nome del pool del modulo di protezione hardware gestito per la correlazione dei log.

Esempio:

{
    "request_id": "6476b291-7c15-4d0b-aef9-03688390cb8e",
    "correlation_id": "aa9a3cb4-82b4-11f0-afc6-5ffd3bdade85",
    "pool_name": "mhsm-pool-name"
}

Risposta di errore

In caso di errore, il proxy deve restituire un codice di stato di errore HTTP standard e il corpo JSON seguente.

ProxyError

Name	TIPO	Description
`code`	Stringa	Codice di errore o nome.
`message`	Stringa	Messaggio di errore.

Codici di stato HTTP:

Codice di stato	Description
400	Parametro di richiesta non valido, ad esempio testo crittografato non valido o algoritmo non supportato.
401	Autenticazione non riuscita(ad esempio, certificato client mancante o mancata corrispondenza del soggetto CN).
403	Accesso negato (ad esempio, la chiave è disabilitata, scaduta o l'operazione non è supportata).
404	Chiave non trovata.
429	Troppe richieste. Il proxy non può elaborare il volume di richiesta corrente o la quota di utilizzo viene superata.
5xx	Errore del server.

Esempio:

{
    "code": "KeyDisabled",
    "message": "Operation WrapKey is not allowed on a disabled key"
}

Regole di codifica delle chiavi

Tutti i numeri interi e il materiale della chiave in questa API usano la codifica seguente:

Rappresenta il valore come sequenza di byte binario big-endian senza segno.
Codifica Base64url (RFC 7515) sequenza di byte.

I moduli testuali non devono essere codificati in base64url. Sono incluse stringhe decimali, stringhe esadecimale, campi PEM e JWK (k, n, ee così via). Solo i byte non elaborati sono input validi per il codificatore base64url.

Esempi:

Esponente RSA 65537 → byte 01 00 01 → base64url AQAB
Una chiave AES a 256 bit (byte non elaborati) → la stringa base64url corrispondente

Informazioni di riferimento sulle API

Le sezioni seguenti definiscono ogni endpoint che deve essere implementato da un proxy EKM conforme.

Ottenere informazioni sul proxy

Restituisce i dettagli del proxy e la versione più alta dell'API supportata dal proxy. Il modulo di protezione hardware gestito chiama questo endpoint durante la configurazione della connessione EKM per verificare la raggiungibilità e l'autenticazione. Il modulo di protezione hardware gestito usa anche questo endpoint come monitoraggio dell'integrità a circa 3 chiamate al minuto.

POST https://{server}/[path-prefix]/info?api-version=0.1-preview

Parametri URI

Name	In	Obbligatorio	Description
`path-prefix`	percorso	No	Prefisso di percorso facoltativo configurato durante l'installazione della connessione EKM.
`api-version`	stringa di query	Sì	Versione dell'API client.

Corpo della richiesta

Name	Obbligatorio	TIPO	Description
`request_context`	Sì	RequestContext	Vedere Contesto della richiesta.

Responses

Codice di stato	TIPO	Description
200 Va bene	Proxyinfo	Dettagli proxy.
Other	ProxyError	Risposta di errore.

ProxyInfo

Name	TIPO	Description
`api_version`	Stringa	Versione più recente dell'API supportata dal proxy.
`proxy_vendor`	Stringa	Nome del fornitore del proxy EKM.
`proxy_name`	Stringa	Nome e versione del prodotto proxy EKM.
`ekm_vendor`	Stringa	Nome del fornitore del sistema di gestione delle chiavi esterno.
`ekm_product`	Stringa	Nome e versione del prodotto del sistema di gestione delle chiavi esterne.

Example

Richiesta:

POST https://ekmproxy.example.com/path-prefix/info?api-version=0.1-preview

{
    "request_context": {
        "request_id": "6476b291-7c15-4d0b-aef9-03688390cb8e",
        "correlation_id": "aa9a3cb4-82b4-11f0-afc6-5ffd3bdade85",
        "pool_name": "mhsm-pool-name"
    }
}

Risposta:

{
    "api_version": "1.0",
    "proxy_vendor": "EKM Proxy Vendor",
    "proxy_name": "EKM Proxy Service v1.0",
    "ekm_vendor": "SoftHSM",
    "ekm_product": "SoftHSM v2.5.0"
}

Ottenere i metadati della chiave

Restituisce il tipo di chiave, le dimensioni e le operazioni supportate per una chiave esterna.

POST https://{server}/[path-prefix]/{key-name}/metadata?api-version=0.1-preview

Parametri URI

Name	In	Obbligatorio	Description
`path-prefix`	percorso	No	Prefisso di percorso facoltativo configurato durante l'installazione della connessione EKM.
`key-name`	percorso	Sì	Identificatore di chiave esterna.
`api-version`	stringa di query	Sì	Versione dell'API client.

Corpo della richiesta

Name	Obbligatorio	TIPO	Description
`request_context`	Sì	RequestContext	Vedere Contesto della richiesta.

Responses

Codice di stato	TIPO	Description
200 Va bene	KeyMetadata	Metadati della chiave esterna.
Other	ProxyError	Risposta di errore.

KeyMetadata

Name	TIPO	Description
`key_type`	Stringa	Tipo di chiave. Vedere Tipi e dimensioni delle chiavi.
`key_size`	integer (int32)	Dimensioni della chiave in bit. Vedere Tipi e dimensioni delle chiavi.
`key_ops`	string[]	Deve essere `["wrapKey", "unwrapKey"]`.
`n`	string (base64url)	Modulo RSA. Convertire l'intero nella rappresentazione binaria big-endian senza segno e quindi codifica base64url. Le forme testuali (decimali, esadecimali) non devono essere codificate. Obbligatorio per le chiavi RSA.
`e`	string (base64url)	Esponente pubblico RSA. Applicare la stessa codifica di `n`. Per esponente 65537: byte `01 00 01` → `AQAB`. Obbligatorio per le chiavi RSA.

Tipi e dimensioni delle chiavi

Tipo di chiave	Description	Dimensioni delle chiavi supportate (bit)
`oct`	Chiave AES	256
`RSA`	Chiave RSA	2048, 3072, 4096

Example

Richiesta:

POST https://ekmproxy.example.com/path-prefix/aes-key-1/metadata?api-version=0.1-preview

{
    "request_context": {
        "request_id": "6476b291-7c15-4d0b-aef9-03688390cb8e",
        "correlation_id": "aa9a3cb4-82b4-11f0-afc6-5ffd3bdade85",
        "pool_name": "mhsm-pool-name"
    }
}

Risposta:

{
    "key_type": "oct",
    "key_size": 256,
    "key_ops": ["wrapKey", "unwrapKey"]
}

Eseguire il wrapping della chiave

Esegue il wrapping di una chiave crittografica.

POST https://{server}/[path-prefix]/{key-name}/wrapkey?api-version=0.1-preview

Parametri URI

Name	In	Obbligatorio	Description
`path-prefix`	percorso	No	Prefisso di percorso facoltativo configurato durante l'installazione della connessione EKM.
`key-name`	percorso	Sì	Identificatore di chiave esterna.
`api-version`	stringa di query	Sì	Versione dell'API client.

Corpo della richiesta

Name	Obbligatorio	TIPO	Description
`request_context`	Sì	RequestContext	Vedere Contesto della richiesta.
`alg`	Sì	Stringa	Algoritmo di wrapping. Vedere Wrapping degli algoritmi.
`value`	Sì	string (base64url)	Tasto da incapsulare. Convertire la sequenza di byte non elaborati della chiave nella relativa rappresentazione binaria big-endian senza segno, quindi codifica base64url. I moduli testuali (hex, decimal, PEM, JWK) non devono essere codificati.

Wrapping degli algoritmi

Tipo di chiave	Algoritmi supportati
`oct`	`A256KW` — AES Key Wrap con una chiave a 256 bit `A256KWP` — AES Key Wrap with Padding using a 256-bit key (Ritorno a capo chiave AES con riempimento con una chiave a 256 bit)
`RSA`	`RSA-OAEP-256` — RSAES OAEP con SHA-256 e MGF1 con SHA-256 `RSA-OAEP` — RSAES OAEP con SHA-1 e MGF1 con SHA-1

Responses

Codice di stato	TIPO	Description
200 Va bene	WrapKeyOperationResult	Tasto di cui è stato eseguito il wrapping.
Other	ProxyError	Risposta di errore.

WrapKeyOperationResult

Name	TIPO	Description
`value`	string (base64url)	Tasto di cui è stato eseguito il wrapping. La sequenza di byte non elaborata prodotta dall'operazione di wrapping deve essere considerata unsigned big-endian, quindi codificata in base64url. I moduli testuali non devono essere codificati.

Example

Richiesta:

POST https://ekmproxy.example.com/path-prefix/aes-key-1/wrapkey?api-version=0.1-preview

{
    "request_context": {
        "request_id": "6476b291-7c15-4d0b-aef9-03688390cb8e",
        "correlation_id": "aa9a3cb4-82b4-11f0-afc6-5ffd3bdade85",
        "pool_name": "mhsm-pool-name"
    },
    "alg": "A256KWP",
    "value": "MTIzNDU2NzgxMjM0NTY3ODEyMzQ1Njc4MTIzNDU2Nzg"
}

Risposta:

{
    "value": "MTIzNDU2NzgxMjM0NTY3ODEyMzQ1Njc4MTIzNDU2NzgxMjM0NTY3OA"
}

Annulla il wrapping della chiave

Annulla il wrapping di una chiave di cui è stato eseguito il wrapping in precedenza.

POST https://{server}/[path-prefix]/{key-name}/unwrapkey?api-version=0.1-preview

Parametri URI

Name	In	Obbligatorio	Description
`path-prefix`	percorso	No	Prefisso di percorso facoltativo configurato durante l'installazione della connessione EKM.
`key-name`	percorso	Sì	Identificatore di chiave esterna.
`api-version`	stringa di query	Sì	Versione dell'API client.

Corpo della richiesta

Name	Obbligatorio	TIPO	Description
`request_context`	Sì	RequestContext	Vedere Contesto della richiesta.
`alg`	Sì	Stringa	Algoritmo di wrapping. Vedere Wrapping degli algoritmi.
`value`	Sì	string (base64url)	Chiave di cui è stato eseguito il wrapping. Deve essere una rappresentazione di byte con codifica Base64url della sequenza di byte con wrapping non elaborato, considerata come big-endian senza segno. I moduli testuali non devono essere codificati.

Responses

Codice di stato	TIPO	Description
200 Va bene	UnwrapKeyOperationResult	Chiave di cui è stato annullato il wrapping.
Other	ProxyError	Risposta di errore.

UnwrapKeyOperationResult

Name	TIPO	Description
`value`	string (base64url)	Chiave di cui è stato annullato il wrapping. La sequenza di byte non elaborati deve essere rappresentata come big-endian senza segno, quindi con codifica base64url. I moduli testuali non devono essere codificati.

Example

Richiesta:

POST https://ekmproxy.example.com/path-prefix/aes-key-1/unwrapkey?api-version=0.1-preview

{
    "request_context": {
        "request_id": "6476b291-7c15-4d0b-aef9-03688390cb8e",
        "correlation_id": "aa9a3cb4-82b4-11f0-afc6-5ffd3bdade85",
        "pool_name": "mhsm-pool-name"
    },
    "alg": "A256KWP",
    "value": "MTIzNDU2NzgxMjM0NTY3ODEyMzQ1Njc4MTIzNDU2NzgxMjM0NTY3OA"
}

Risposta:

{
    "value": "MTIzNDU2NzgxMjM0NTY3ODEyMzQ1Njc4MTIzNDU2Nzg"
}

Passaggi successivi

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-07-07

Informazioni di riferimento sulle API proxy EKM per la gestione delle chiavi esterne del modulo di protezione hardware gestito

Informazioni generali

Tipo di trasporto e contenuto

Authentication

Formato URI

Condivisione proxy

Ora di risposta

Contesto della richiesta

Risposta di errore

ProxyError

Regole di codifica delle chiavi

Informazioni di riferimento sulle API

Ottenere informazioni sul proxy

Parametri URI

Corpo della richiesta

Responses

ProxyInfo

Example

Ottenere i metadati della chiave

Parametri URI

Corpo della richiesta

Responses

KeyMetadata

Tipi e dimensioni delle chiavi

Example

Eseguire il wrapping della chiave

Parametri URI

Corpo della richiesta

Wrapping degli algoritmi

Responses

WrapKeyOperationResult

Example

Annulla il wrapping della chiave

Parametri URI

Corpo della richiesta

Responses

UnwrapKeyOperationResult

Example

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive