TLS Offload-bibliotheek voor Azure Managed HSM

Artikel
08/07/2024

Azure Managed HSM biedt een TLS-offloadbibliotheek die compatibel is met PKCS#11 versie 2.40. Azure Managed HSM biedt geen ondersteuning voor alle functies die worden vermeld in de PKCS#11-specificatie; In plaats daarvan ondersteunt de TLS Offload-bibliotheek een beperkt aantal mechanismen en interfacefuncties voor SSL/TLS Offload met alleen F5 (BigIP) en Nginx, voornamelijk om TLS-servercertificaatsleutels te genereren en digitale handtekeningen te genereren tijdens TLS-handshakes.

Zie Azure Managed HSM TLS Offload Library GitHub voor meer informatie.

De TLS-offloadbibliotheek maakt intern gebruik van de Azure Key Vault REST API om te communiceren met Azure Managed HSM.

Aan de slag

PKCS#11 kenmerken

Voor een juiste integratie met PKCS#11 is het genereren van sleutels (via C_GenerateKeyPair) en het vinden van sleutelobjecten (via C_FindObjectsInit/C_FindObjects) een oplossing vereist voor het opslaan van PKCS#11-kenmerken in het Azure Key Vault-sleutelobject. De TLS-offloadbibliotheek converteert deze benodigde PKCS#11-kenmerken naar Azure Key Vault-tags.

Deze kenmerktags hebben een speciaal voorvoegsel:

p11_pri_{P11 Kenmerknaam} - Kenmerken van persoonlijke sleutel
p11_pub_{P11 Kenmerknaam} - Kenmerken van openbare sleutel

Met de TLS-offloadbibliotheek worden de kenmerken voor Sleutelbewerkingen en Levensduur van Azure Key Vault correct ingesteld, zodat de service deze beperkingen op de gegenereerde sleutels correct kan afdwingen. Deze kenmerken worden ook opgeslagen als tags zoals andere PKCS#11-kenmerken ter ondersteuning van querymogelijkheden.

Toepassingen die gebruikmaken van de TLS-offloadbibliotheek gebruiken een of meer PKCS#11-kenmerken om de sleutelobjecten te zoeken en te gebruiken.

Waarschuwing

Sleutels die worden gegenereerd door de TLS-offloadbibliotheek en de bijbehorende tags zijn toegankelijk via de REST API van Azure Key Vault. Als u deze P11-kenmerktags bewerkt met behulp van azure Key Vault REST API, kunnen de TLS-offloadbibliotheektoepassingen worden verbroken.

Sleutelgeneratie

De TLS-offloadbibliotheek bevat een hulpprogramma voor het maken van sleutels, mhsm_p11_create_key. Als u het hulpprogramma zonder opdrachtregelargumenten uitvoert, wordt het juiste gebruik van het hulpprogramma weergegeven.

Voor het hulpprogramma voor het maken van sleutels is een service-principal vereist, die is toegewezen aan de rol Beheerde HSM Crypto User op het bereik '/keys'.

Het hulpprogramma voor het maken van sleutels leest de referenties van de service-principal uit de omgevingsvariabelen MHSM_CLIENT_ID en MHSM_CLIENT_SECRET:

MHSM_CLIENT_ID: moet worden ingesteld op de toepassings-id van de service-principal (client)
MHSM_CLIENT_SECRET : moet worden ingesteld op het wachtwoord van de service-principal (clientgeheim)

Voor beheerde identiteiten zijn de bovenstaande omgevingsvariabelen niet nodig.

Gebruik het --identity argument om beheerde identiteit in te schakelen met het hulpprogramma mhsm_p11_create_key.
De client_id door de gebruiker toegewezen beheerde identiteit moet worden geciteerd in het MHSM-configuratiebestand (mhsm-pkcs11.conf). Als de door de client_id gebruiker toegewezen beheerde identiteit niet is opgegeven, wordt deze als door het systeem toegewezen beheerde identiteit gezien.

Het hulpprogramma voor het maken van sleutels genereert willekeurig een naam voor de sleutel op het moment van het maken. De volledige Azure Key Vault-sleutel-id en de sleutelnaam worden voor uw gemak afgedrukt naar de console.

MHSM_CLIENT_ID="<service-principal-application-id>" \
MHSM_CLIENT_SECRET="<service-principal-password>" \
mhsm_p11_create_key --RSA 4K --label tlsKey

Key is generated successfully. \
Managed HSM Key ID: https://myhsm.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f

Het --label argument voor het maken van sleutels geeft de gewenste CKA_LABEL op voor de gegenereerde persoonlijke en openbare sleutels. Deze kenmerken zijn doorgaans vereist voor het configureren van ondersteunde TLS-offloadoplossingen (bijvoorbeeld de nginx SSL-configuratie-instelling 'ssl_certificate_key').

U hebt de sleutelnaam nodig voor eventuele wijzigingen in roltoewijzingen via de Azure CLI.

Toegangsbeheer

De TLS-offloadbibliotheek vertaalt de C_FindObjectsInit naar een Azure Key Vault REST API-aanroep, die werkt op het bereik /keys. De MHSM-service vereist de leesmachtiging voor dit bereik voor de TLS-offloadbibliotheekgebruiker om de zoekbewerking te autoriseren voor de sleutels die zijn gemaakt via het hulpprogramma voor het maken van sleutels.

Zie voor meer informatie over lokale RBAC van Azure Managed HSM:

In de volgende sectie worden verschillende methoden beschreven voor het implementeren van toegangsbeheer voor de service-principal van de TLS-offloadbibliotheek en beheerde identiteit.

TLS Offload-service-principal

De TLS Offload-service-principal wordt gebruikt door de toepassing die gebruikmaakt van TLS Offload Library voor toegangssleutels en moet minimaal de volgende machtiging hebben via roltoewijzingen:

KeyRead-machtiging voor alle sleutels in de beheerde HSM
KeySign-machtiging voor de sleutels die nodig zijn voor TLS-offloading

Beheerder

De gebruiker met beheerdersrechten maakt een aangepaste roldefinitie en roltoewijzingen. Daarom moet de beheerdergebruiker worden toegewezen aan een van de volgende ingebouwde rollen op het bereik '/':

Crypto Officer van beheerde HSM
Beleidsbeheerder van beheerde HSM
Beheerder van beheerde HSM

Service-principal voor het genereren van sleutels

De service-principal voor het genereren van sleutels wordt gebruikt met het hulpprogramma voor het maken van sleutels (mhsm_p11_create_key) om TLS-offloadsleutels te genereren. Deze service-principal moet worden toegewezen aan de rol Beheerde HSM Crypto User op het bereik '/keys'.

Azure-CLI

Azure CLI kan worden gebruikt om taken uit te voeren, zoals roltoewijzing.

Permissieve benadering

De permissieve benadering is eenvoudiger en geschikt wanneer de Azure Managed HSM uitsluitend wordt gebruikt voor TLS-offloading.

Wijs de cryptogebruikersrol toe aan de TLS Offload-service-principal op het bereik '/keys'. Hiermee krijgt de TLS Offload-service-principal de machtiging om sleutels te genereren en deze te vinden voor TLS-offloading.

az keyvault role assignment create --hsm-name ContosoMHSM \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys

Geef voor beheerde identiteiten de volgende opdrachtargumenten op:

az keyvault role assignment create --hsm-name ContosoMHSM \
      --role "Managed HSM Crypto User"  \
       --assignee-object-id <object_id>  \
       --assignee-principal-type MSI \
       --scope /keys

Gedetailleerde benadering

De gedetailleerde benadering implementeert fijnmazig toegangsbeheer. Hiervoor zijn twee service-principals (TLS Offload-service-principal en service-principal voor sleutelgeneratie) en een beheerder vereist.

Het doel is om de machtigingen van de TLS Offload-service-principal te beperken ter ondersteuning van het minimum dat vereist is voor TLS-offload. De gebruiker moet de machtiging Lezen hebben voor andere sleutels om de functie C_FindObject* van de bibliotheek te ondersteunen.

Leesrol TLS-offloadbibliotheekgebruiker

De eerste stap bij het implementeren van de gedetailleerde benadering is het maken van een aangepaste rol. Deze bewerking hoeft slechts eenmaal te worden uitgevoerd.

De beheerder (met beheerde HSM Crypto Officer of beheerde HSM-beheerder of de rol Beheerder van het beheerde HSM-beleid) maakt een aangepaste roldefinitie voor gebruikersleesrol voor TLS-bibliotheek:

az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{ \
"roleName": "TLS Library User Read Role", \
"description": "Grant Read access to keys", \
"actions": [], \
"notActions": [], \
"dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \
"notDataActions": [] \
}'

Sleutels genereren

Sleutels kunnen worden gegenereerd met behulp van de service-principal voor het genereren van sleutels met het hulpprogramma voor het maken van sleutels (mhsm_p11_create_key).

Toestemming

De beheerder wijst de volgende rollen toe aan de TLS Offload-service-principal.

De rol Tls Library User Read Role toewijzen in het bereik '/keys'
Wijs de rol Beheerde HSM Crypto User toe bij het bereik /keys/{key name}.

In het volgende voorbeeld is de sleutelnaam 'p11-6a2155dc40c94367a0f97ab452dc216f'.

az keyvault role assignment create --hsm-name ContosoMHSM  \
--role "TLS Library User Read Role"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys

az keyvault role assignment create --hsm-name ContosoMHSM  \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f

Verbinding opslaan in cache

Om de prestaties van sign-aanroepen naar de beheerde HSM-service te verbeteren, slaat TLS-offloadbibliotheek de TLS-verbindingen op in de cache van de beheerde HSM-serviceservers. Tls Offload-bibliotheek slaat standaard maximaal 20 TLS-verbindingen in de cache op. Caching van verbindingen kan worden beheerd via het MHSM-configuratiebestand (mhsm-pkcs11.conf).

"ConnectionCache": {
        "Disable": false, 
        "MaxConnections": 20
}

Uitschakelen

Als deze waarde waar is, wordt caching van verbindingen uitgeschakeld. Deze functie is standaard ingeschakeld.

MaxConnections

Hiermee geeft u het maximum aantal verbindingen met de cache op. De maximale verbindingslimiet moet worden geconfigureerd op basis van het aantal gelijktijdige PKCS11-sessies dat door de toepassing wordt gebruikt. Toepassingen maken doorgaans een groep PKCS11-sessies en gebruiken ze uit een groep threads om gelijktijdig ondertekeningsaanvragen te genereren. De MaxConnections moeten overeenkomen met het aantal gelijktijdige ondertekeningsaanvragen dat door de toepassingen wordt gegenereerd.

De ondertekeningsaanvraag per seconde (RPS) is afhankelijk van het aantal gelijktijdige aanvragen en het aantal verbindingen dat in de cache is opgeslagen. Als u een hoger getal of zelfs de standaardlimiet opgeeft, wordt de ondertekenings-RPS niet verbeterd als het aantal gelijktijdige PKCS11-ondertekeningsaanvragen lager is dan deze limiet. Het maximum aantal gelijktijdige verbindingen voor het bereiken van de burstmodus van standard B1 HSM-pool is ongeveer 30, afhankelijk van het exemplaartype. U moet echter met verschillende getallen proberen om het optimale aantal gelijktijdige verbindingen te bepalen.

Raadpleeg de documentatie van uw toepassing of neem contact op met de leverancier van uw toepassing voor meer informatie over hoe de toepassing gebruikmaakt van de PKCS11-bibliotheek.

De TLS-offloadbibliotheek gebruiken

Sleutels genereren

Voor het hulpprogramma voor het maken van sleutels is een service-principal vereist, die is toegewezen aan de rol Beheerde HSM Crypto User op het bereik '/keys'.

Het hulpprogramma voor het maken van sleutels leest de referenties van de service-principal uit de omgevingsvariabelen MHSM_CLIENT_ID en MHSM_CLIENT_SECRET.

MHSM_CLIENT_ID: moet worden ingesteld op de toepassings-id van de service-principal (client)
MHSM_CLIENT_SECRET : moet worden ingesteld op het wachtwoord van de service-principal (clientgeheim)

MHSM_CLIENT_ID="<service-principal-application-id>" \
MHSM_CLIENT_SECRET="<service-principal-password>" \
mhsm_p11_create_key --RSA 4K --label tlsKey

Key is generated successfully.
Managed HSM Key ID: https://myhsm.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f

De sleutelnaam is vereist als u van plan bent om gedetailleerde toegang tot sleutels te implementeren.

Sleutelloze TLS implementeren

Er zijn twee benaderingen voor het genereren van een sleutel en het gebruik van de sleutel voor de sleutel minder TLS: een eenvoudigere, meer permissieve benadering en een gedetailleerde benadering, die betere beveiliging biedt. De benaderingen verschillen in implementatie-inspanningen en het afdwingen van beveiliging.

Eenvoudigere benadering

Een service-principal maken voor de TLS-offloadbibliotheek (bijvoorbeeld TLSOffload ServicePrincipal)

Wijs de rol Beheerde HSM Crypto User toe aan de TLS Offload-service-principal op het bereik '/keys'.

az keyvault role assignment create --hsm-name ContosoMHSM \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys

Genereer een sleutel met het vereiste label volgens de stappen in Het genereren van sleutels met behulp van de TLS-offloadbibliotheek.
De TLS-server configureren voor het gebruik van de beheerde HSM TLS-offloadbibliotheek als de PKCS#11-interfacebibliotheek
Configureer de TLS-server (bijvoorbeeld de nginx SSL-configuratie-instelling 'ssl_certificate_key') met het sleutellabel en de referenties van de TLS Offload-service-principal

Gedetailleerde benadering

Maak een beheerdergebruiker (bijvoorbeeld TLSOffloadAdminUser) met de volgende rol:
- De rol 'Managed HSM Crypto Officer' in het bereik '/'
Maak een service-principal voor sleutelgeneratie (bijvoorbeeld TLSOffloadKeyGenServicePrincipal) voor het genereren van TLS-offloadsleutels en wijs de volgende rol toe:
- De rol Beheerde HSM Crypto User in het bereik '/keys'.
Een service-principal maken voor tls-offloading (bijvoorbeeld TLSOffload ServicePrincipal)

De gebruiker met beheerdersrechten maakt de volgende aangepaste roldefinitie:

az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{ \
"roleName": "TLS Library User Read Role", \
"description": "Grant Read access to keys", \ 
"actions": [], \
"notActions": [], \
"dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \
"notDataActions": []
}'

Genereer een sleutel met het vereiste label na 'Sleutels genereren met behulp van de TLS-offloadbibliotheek'. Gebruik de service-principal voor sleutelgeneratie (bijvoorbeeld TLSOffloadKeyGenServicePrincipal) tijdens het genereren van sleutels. Noteer het sleutellabel en de sleutelnaam. Bijvoorbeeld:
- Sleutellabel: tlsKey
- Sleutelnaam: p11-6a2155dc40c94367a0f97ab452dc216f

Gebruiker met beheerdersrechten wijst de volgende rollen toe aan de TLS Offload-service-principal

Rol tls-bibliotheekgebruiker lezen in het bereik /sleutels
De rol Beheerde HSM Crypto User in het bereik "/keys/{key name}"

az keyvault role assignment create --hsm-name ContosoMHSM  \
--role " TLS Library User Read Role"  \
--assignee TLSOffloadServicePrincipal @contoso.com  \
--scope /keys

az keyvault role assignment create --hsm-name ContosoMHSM  \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f

De TLS-server configureren voor het gebruik van de Azure Managed HSM TLS-offloadbibliotheek als de PKCS#11-interfacebibliotheek
Configureer de TLS-server (bijvoorbeeld de nginx SSL-configuratie-instelling 'ssl_certificate_key') met het sleutellabel en de referenties van de TLS Offload-service-principal

Delen via

TLS Offload-bibliotheek voor Azure Managed HSM

Aan de slag

PKCS#11 kenmerken

Sleutelgeneratie

Toegangsbeheer

TLS Offload-service-principal

Beheerder

Service-principal voor het genereren van sleutels

Azure-CLI

Permissieve benadering

Gedetailleerde benadering

Leesrol TLS-offloadbibliotheekgebruiker

Sleutels genereren

Toestemming

Verbinding opslaan in cache

De TLS-offloadbibliotheek gebruiken

Sleutels genereren

Sleutelloze TLS implementeren

Eenvoudigere benadering

Gedetailleerde benadering

Volgende stappen

Feedback

Aanvullende resources