Dela via

TLS-avlastningsbibliotek med hanterad HSM i Azure

  • Artikel

Azure Managed HSM erbjuder ett TLS-avlastningsbibliotek som är kompatibelt med PKCS#11 version 2.40. Azure Managed HSM stöder inte alla funktioner som anges i PKCS#11-specifikationen. I stället stöder TLS-avlastningsbiblioteket en begränsad uppsättning mekanismer och gränssnittsfunktioner för SSL/TLS-avlastning med F5 (BigIP) och endast Nginx, främst för att generera TLS-servercertifikatnycklar och generera digitala signaturer under TLS-handskakningar.

Mer information finns i GitHub för Azure Managed HSM TLS Offload Library.

TLS Offload Library använder Azure Key Vault REST API internt för att interagera med Azure Managed HSM.

Kom igång

PKCS#11-attribut

För att kunna integreras korrekt med PKCS#11 krävs en lösning för att lagra PKCS#11-attribut på Azure Key Vault-nyckelobjektet för att generera nycklar (via C_GenerateKeyPair) och hitta nyckelobjekt (via C_FindObjectsInit/C_FindObjects). TLS-avlastningsbiblioteket konverterar dessa nödvändiga PKCS#11-attribut till Azure Key Vault-taggar.

Dessa "attributtaggar" har ett särskilt prefix:

  • p11_pri_{P11 Attributnamn} – Attribut för privat nyckel
  • p11_pub_{P11 Attributnamn} – Attribut för offentlig nyckel

TLS-avlastningsbiblioteket ställer in azure Key Vault-nyckelåtgärder och nyckellivslängdsattribut så att tjänsten kan tillämpa dessa begränsningar på de genererade nycklarna korrekt. Dessa attribut lagras också som taggar som andra PKCS#11-attribut för att stödja frågefunktioner.

Program som använder TLS-avlastningsbiblioteket använder ett eller flera PKCS#11-attribut för att hitta och använda nyckelobjekten.

Varning

Nycklar som genereras av TLS-avlastningsbiblioteket och deras taggar är tillgängliga via Azure Key Vault REST API. Om du manipulerar dessa P11-attributtaggar med hjälp av Azure Key Vault REST API kan programmet TLS Offload Library brytas.

Nyckelgenerering

TLS-avlastningsbiblioteket innehåller ett verktyg för att skapa nycklar mhsm_p11_create_key. Körning av verktyget utan kommandoradsargument visar korrekt användning av verktyget.

Verktyget för nyckelskapande kräver ett huvudnamn för tjänsten som tilldelas rollen "Hanterad HSM-kryptografianvändare" i omfånget "/keys".

Verktyget för att skapa nycklar läser autentiseringsuppgifterna för tjänstens huvudnamn från miljövariablerna MHSM_CLIENT_ID och MHSM_CLIENT_SECRET:

  • MHSM_CLIENT_ID – måste anges till program-ID för tjänstens huvudnamn (klient)
  • MHSM_CLIENT_SECRET – måste anges till lösenordet för tjänstens huvudnamn (klienthemlighet)

För hanterade identiteter behövs inte miljövariablerna ovan.

  • --identity Använd argumentet för att aktivera hanterad identitet med verktyget mhsm_p11_create_key.
  • Den client_id användartilldelade hanterade identiteten ska anges i MHSM-konfigurationsfilen (mhsm-pkcs11.conf). Om en användartilldelad hanterad identitet inte tillhandahålls betraktas den client_id som systemtilldelad hanterad identitet.

Verktyget för att skapa nycklar genererar slumpmässigt ett namn för nyckeln när den skapas. Det fullständiga Nyckel-ID:t för Azure Key Vault och nyckelnamnet skrivs ut till konsolen för att underlätta för dig.

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

Argumentet --label för verktyget för att skapa nycklar anger önskad CKA_LABEL för de privata och offentliga nycklar som genereras. Dessa attribut krävs vanligtvis för att konfigurera TLS-avlastningslösningar som stöds (till exempel NGINX SSL-konfigurationsinställningen "ssl_certificate_key").

Du behöver nyckelnamnet för eventuella rolltilldelningsändringar via Azure CLI.

Åtkomstkontroll

TLS-avlastningsbiblioteket översätter C_FindObjectsInit till ett REST API-anrop för Azure Key Vault som körs i omfånget /keys. MHSM-tjänsten kräver läsbehörighet i det här omfånget för TLS-avlastningsbiblioteksanvändaren för att auktorisera sökåtgärden för nycklarna som skapats via verktyget för att skapa nyckeln.

Mer information om lokal RBAC för Azure Managed HSM finns i:

I följande avsnitt beskrivs olika metoder för att implementera åtkomstkontroll för tjänstenS huvudnamn för TLS-avlastningsbibliotek och hanterad identitet.

Tjänstens huvudnamn för TLS-avlastning

Tjänstens huvudnamn för TLS-avlastning används av programmet som använder TLS-avlastningsbiblioteket för att få åtkomst till nycklar och bör minst ha följande behörighet via rolltilldelningar:

  • KeyRead-behörighet till alla nycklar i den hanterade HSM:en
  • KeySign-behörighet till de nycklar som krävs för TLS-avlastning

Administratörsanvändare

Den Admin användaren skapar en anpassad rolldefinition och rolltilldelningar. Därför bör den Admin användaren tilldelas till någon av följande inbyggda roller i omfånget "/":

  • Managed HSM Crypto Officer
  • Hanterad HSM-principadministratör
  • Managed HSM-administratör

Tjänstens huvudnamn för nyckelgenerering

Huvudnamnet för nyckelgenereringstjänsten används med verktyget för nyckelskapande (mhsm_p11_create_key) för att generera TLS-avlastningsnycklar. Tjänstens huvudnamn ska tilldelas rollen "Managed HSM Crypto User" i omfånget "/keys".

Azure CLI

Azure CLI kan användas för att utföra uppgifter som rolltilldelning.

Tillåtande metod

Den tillåtande metoden är enklare och lämplig när Azure Managed HSM uteslutande används för TLS-avlastning.

Tilldela rollen Kryptografianvändare till tjänstens huvudnamn för TLS-avlastning i omfånget "/keys". Detta ger tjänstens huvudnamn för TLS-avlastning behörighet att generera nycklar och hitta dem för TLS-avlastning.

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

För Hanterade identiteter anger du kommandoargument på följande sätt:

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

Detaljerad metod

Den detaljerade metoden implementerar detaljerad åtkomstkontroll. Det kräver två tjänsthuvudnamn (TLS-avlastning av tjänstens huvudnamn och tjänstens huvudnamn för nyckelgenerering) och en Admin användare.

Målet är att begränsa TLS-avlastningstjänstens huvudnamns behörigheter för att stödja det minsta som krävs för TLS-avlastning. Användaren måste ha läsbehörighet för andra nycklar för att stödja bibliotekets C_FindObject*-funktion.

TLS-avlastningsroll för biblioteksanvändare

Det första steget i att implementera den detaljerade metoden är att skapa en anpassad roll. Den här åtgärden behöver bara utföras en gång.

Den Admin användaren (med managed HSM Crypto Officer eller managed HSM-administratör eller hanterad HSM-principadministratörsroll) skapar en anpassad rolldefinition för "TLS-biblioteksanvändarens läsroll":

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": [] \
}'

Generera nycklar

Nycklar kan genereras med nyckelgenereringstjänstens huvudnamn med verktyget för nyckelskapande (mhsm_p11_create_key).

Bevilja behörighet

Den Admin användaren tilldelar följande roller till tjänstens huvudnamn för TLS-avlastning.

  • Tilldela rollen "Läsroll för TLS-biblioteksanvändare" i omfånget "/keys"
  • Tilldela rollen "Managed HSM Crypto User" i omfånget "/keys/{key name}"

I följande exempel är nyckelnamnet "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

Cachelagring av anslutning

För att förbättra prestanda för signeringsanrop till Managed HSM-tjänsten cachelagrar TLS Offload Library sina TLS-anslutningar till managed HSM-tjänstservrarna. Som standard cachelagrar TLS-avlastningsbiblioteket upp till 20 TLS-anslutningar. Cachelagring av anslutningar kan styras via MHSM-konfigurationsfilen (mhsm-pkcs11.conf).

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

Inaktivera

Om det här värdet är sant inaktiveras cachelagring av anslutningar. Det är aktiverat som standard.

Maxconnections

Anger det maximala antalet anslutningar som ska cachelageras. Den maximala anslutningsgränsen ska konfigureras baserat på antalet samtidiga PKCS11-sessioner som används av programmet. Program skapar vanligtvis en pool med PKCS11-sessioner och använder dem från en pool med trådar för att generera signeringsbegäranden parallellt. MaxConnections ska matcha antalet samtidiga signeringsbegäranden som genereras av programmen.

Signeringsbegäran per sekund (RPS) är beroende av antalet samtidiga begäranden och antalet cachelagrade anslutningar. Om du anger ett högre antal eller ens standardgränsen förbättras inte signerings-RPS om antalet samtidiga PKCS11-signeringsbegäranden är lägre än den här gränsen. Det maximala antalet samtidiga anslutningar för att uppnå burst-läge för Standard B1 HSM-poolen är cirka 30 beroende på instanstypen. Men du bör prova med olika tal för att ta reda på det optimala antalet samtidiga anslutningar.

Läs programdokumentationen eller kontakta programleverantören om du vill veta mer om hur programmet använder PKCS11-biblioteket.

Använda TLS-avlastningsbiblioteket

Generera nycklar

TLS-avlastningsbiblioteket innehåller ett verktyg för att skapa nycklar mhsm_p11_create_key. Körning av verktyget utan kommandoradsargument visar korrekt användning av verktyget.

Verktyget för nyckelskapande kräver ett huvudnamn för tjänsten som tilldelas rollen "Hanterad HSM-kryptografianvändare" i omfånget "/keys".

Verktyget för att skapa nycklar läser autentiseringsuppgifterna för tjänstens huvudnamn från miljövariablerna MHSM_CLIENT_ID och MHSM_CLIENT_SECRET.

  • MHSM_CLIENT_ID – måste anges till program-ID för tjänstens huvudnamn (klient)
  • MHSM_CLIENT_SECRET – måste anges till lösenordet för tjänstens huvudnamn (klienthemlighet)

Verktyget för att skapa nycklar genererar slumpmässigt ett namn för nyckeln när den skapas. Det fullständiga Nyckel-ID:t för Azure Key Vault och nyckelnamnet skrivs ut till konsolen för att underlätta för dig.

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

Argumentet --label för verktyget för att skapa nycklar anger önskad CKA_LABEL för de privata och offentliga nycklar som genereras. Dessa attribut krävs vanligtvis för att konfigurera TLS-avlastningslösningar som stöds (till exempel NGINX SSL-konfigurationsinställningen "ssl_certificate_key").

Nyckelnamnet krävs om du planerar att implementera detaljerad åtkomst till nycklar.

Implementera nyckellös TLS

Det finns två metoder för att generera en nyckel och använda nyckeln för TLS utan nyckel: en enklare, mer tillåtande metod och en detaljerad metod som ger bättre säkerhet. Metoderna skiljer sig åt när det gäller implementeringsarbete och tvingande säkerhet.

Enklare metod

  1. Skapa ett tjänsthuvudnamn för TLS-avlastningsbiblioteket (till exempel TLSOffload ServicePrincipal)
  2. Tilldela rollen "Managed HSM Crypto User" till tjänstens huvudnamn för TLS-avlastning i omfånget "/keys". 
    az keyvault role assignment create --hsm-name ContosoMHSM \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys
  3. Generera nyckel med obligatorisk etikett genom att följa stegen i Så här genererar du nycklar med hjälp av TLS-avlastningsbiblioteket.
  4. Konfigurera TLS-servern att använda Managed HSM TLS-avlastningsbiblioteket som PKCS#11-gränssnittsbiblioteket
  5. Konfigurera TLS-servern (till exempel konfigurationsinställningen nginx SSL "ssl_certificate_key") med nyckeletiketten och autentiseringsuppgifterna för TLS-avlastning av tjänstens huvudnamn

Detaljerad metod

  1. Skapa en Admin användare (till exempel TLSOffloadAdminUser) med följande roll:
    • "Managed HSM Crypto Officer"-rollen i omfånget "/"
  2. Skapa ett huvudnamn för nyckelgenereringstjänsten (till exempel TLSOffloadKeyGenServicePrincipal) för genereringen av TLS-avlastningsnyckeln och tilldela följande roll:
    • Rollen "Hanterad HSM-kryptografianvändare" i omfånget "/keys".
  3. Skapa ett tjänsthuvudnamn för TLS-avlastning (till exempel TLSOffload ServicePrincipal)
  4. Den Admin användaren skapar följande anpassade rolldefinition:
    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": []
}'
  5. Generera en nyckel med obligatorisk etikett efter "Så här genererar du nycklar med hjälp av TLS-avlastningsbiblioteket". Använd tjänstens huvudnamn för nyckelgenerering (till exempel TLSOffloadKeyGenServicePrincipal) när du genererar nycklar. Anteckna nyckeletiketten och nyckelnamnet. Exempel:
    • Nyckeletikett: tlsKey
    • Nyckelnamn: p11-6a2155dc40c94367a0f97ab452dc216f
  6. Admin Användaren tilldelar följande roller till tjänstens huvudnamn för TLS-avlastning
    • Rollen "Läsroll för TLS-biblioteksanvändare" i omfånget "/keys"
    • "Managed HSM Crypto User"-rollen i omfånget "/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
  7. Konfigurera TLS-servern att använda Azure Managed HSM TLS-avlastningsbiblioteket som PKCS#11-gränssnittsbiblioteket
  8. Konfigurera TLS-servern (till exempel konfigurationsinställningen nginx SSL "ssl_certificate_key") med nyckeletiketten och autentiseringsuppgifterna för TLS-avlastning av tjänstens huvudnamn

Nästa steg