Dela via

Konfigurera kundhanterade nycklar för datakryptering i Azure AI Search

  • Artikel

Azure AI Search krypterar automatiskt vilande data med tjänsthanterade nycklar. Om du behöver mer skydd kan du komplettera standardkryptering med ett annat krypteringslager med hjälp av nycklar som du skapar och hanterar i Azure Key Vault.

Den här artikeln beskriver hur du konfigurerar kundhanterad nyckel (CMK) eller BYOK-kryptering (bring-your-own-key).

Kommentar

Om ett index är CMK-krypterat är det endast tillgängligt om söktjänsten har åtkomst till nyckeln. Om åtkomsten återkallas är indexet oanvändbart och tjänsten kan inte skalas förrän indexet har tagits bort eller åtkomsten till nyckeln har återställts.

CMK-krypterade objekt

CMK-kryptering utförs på enskilda objekt. Om du behöver CMK i söktjänsten anger du en tvingande princip.

CMK-kryptering används när ett objekt skapas. Du kan inte kryptera objekt som redan finns. CMK-kryptering sker när ett objekt sparas på disk, antingen data i vila för långsiktig lagring eller tillfälliga data för kortsiktig lagring. Med CMK ser disken aldrig okrypterade data.

Objekt som kan krypteras är index, synonymlistor, indexerare, datakällor och kompetensuppsättningar. Kryptering är beräkningsmässigt dyrt att dekryptera så endast känsligt innehåll krypteras.

Kryptering utförs över följande innehåll:

  • Allt innehåll i index och synonymlistor.

  • Känsligt innehåll i indexerare, datakällor, kompetensuppsättningar och vektoriserare. Det här innehållet består bara av de fält som lagrar anslutningssträng, beskrivningar, identiteter, nycklar och användarindata. Kompetensuppsättningar har till exempel Azure AI-tjänstnycklar och vissa färdigheter accepterar användarindata, till exempel anpassade entiteter. I båda fallen krypteras nycklar och användarindata till kunskaper. Alla referenser till externa resurser (till exempel Azure-datakällor eller Azure OpenAI-modeller) krypteras också.

Fullständig dubbelkryptering

När du introducerar CMK-kryptering krypterar du innehåll två gånger. För de objekt och fält som anges i föregående avsnitt krypteras innehållet först med din CMK, och för det andra med den Microsoft-hanterade nyckeln. Innehållet krypteras dubbelt på datadiskar för långsiktig lagring och på tillfälliga diskar som används för kortsiktig lagring.

Om du aktiverar CMK-kryptering ökar indexstorleken och försämrar frågeprestandan. Baserat på observationer hittills kan du förvänta dig en ökning med 30–60 procent i frågetider, även om den faktiska prestandan varierar beroende på indexdefinitionen och typerna av frågor. Eftersom prestandan minskar rekommenderar vi att du bara aktiverar den här funktionen på objekt som verkligen kräver den.

Även om dubbel kryptering nu är tillgänglig i alla regioner distribuerades stödet i två faser:

  • Den första distributionen var den 1 augusti 2020 och inkluderade de fem regioner som anges nedan. tjänsten Search som skapats i följande regioner stöds CMK för datadiskar, men inte temporära diskar:

    • Västra USA 2
    • USA, östra
    • USA, södra centrala
    • US Gov, Virginia
    • US Gov, Arizona

  • Den andra distributionen den 13 maj 2021 lade till kryptering för tillfälliga diskar och utökad CMK-kryptering till alla regioner som stöds.

    Om du använder CMK från en tjänst som skapades under den första distributionen och du också vill ha CMK-kryptering över tillfälliga diskar måste du skapa en ny söktjänst i valfri region och distribuera om innehållet. Information om hur du fastställer datumet då tjänsten skapades finns i Så här kontrollerar du datumet då tjänsten skapades.

Förutsättningar

Begränsningar

  • Inget stöd för Azure Key Vault Managed Hardware Security Model (HSM).

  • Inget stöd för flera prenumerationer. Azure Key Vault och Azure AI Search måste finnas i samma prenumeration.

Key Vault-tips

Om du inte har använt Azure Key Vault tidigare läser du den här snabbstarten och lär dig mer om grundläggande uppgifter: Ange och hämta en hemlighet från Azure Key Vault med hjälp av PowerShell.

Här följer några tips för att använda Key Vault:

  • Använd så många nyckelvalv som du behöver. Hanterade nycklar kan finnas i olika nyckelvalv. En söktjänst kan ha flera krypterade objekt, var och en krypterad med en annan kundhanterad krypteringsnyckel, lagrad i olika nyckelvalv.

  • Använd samma klientorganisation så att du kan hämta din hanterade nyckel genom att ansluta via ett system eller en användarhanterad identitet. Det här beteendet kräver att båda tjänsterna delar samma klientorganisation. Mer information om hur du skapar en klient finns i Konfigurera en ny klientorganisation.

  • Aktivera rensningsskydd och mjuk borttagning. På grund av krypteringens natur med kundhanterade nycklar kan ingen hämta dina data om din Azure Key Vault-nyckel tas bort. För att förhindra dataförlust som orsakas av oavsiktliga key vault-nyckelborttagningar måste skydd mot mjuk borttagning och rensning vara aktiverat i nyckelvalvet. Mjuk borttagning är aktiverat som standard, så du får bara problem om du inaktiverar det avsiktligt. Rensningsskydd är inte aktiverat som standard, men det krävs för kundhanterad nyckelkryptering i Azure AI Search.

  • Aktivera loggning på nyckelvalvet så att du kan övervaka nyckelanvändningen.

  • Aktivera autorotering av nycklar eller följ strikta procedurer under rutinmässig rotation av nyckelvalvsnycklar och programhemligheter och registrering. Uppdatera alltid allt krypterat innehåll för att använda nya hemligheter och nycklar innan du tar bort de gamla. Om du missar det här steget kan innehållet inte dekrypteras.

Steg 1: Skapa en nyckel i Key Vault

Hoppa över nyckelgenerering om du redan har en nyckel i Azure Key Vault som du vill använda, men samla in nyckelidentifieraren. Du behöver den här informationen när du skapar ett krypterat objekt.

Innan du lägger till nyckeln kontrollerar du att du har tilldelat dig rollen Key Vault Crypto Officer .

Azure AI Search-kryptering stöder RSA-nycklar i storlekarna 2048, 3072 och 4096. Mer information om nyckeltyper som stöds finns i Om nycklar.

  1. Logga in på Azure Portal och öppna översiktssidan för nyckelvalvet.

  2. Välj Objektnycklar> till vänster och välj sedan Generera/importera.

  3. I fönstret Skapa en nyckel går du till listan med alternativ och väljer Generera för att skapa en ny nyckel.

  4. Ange ett namn för din nyckel och godkänn standardinställningarna för andra nyckelegenskaper.

  5. Du kan också ange en princip för nyckelrotation för att aktivera automatisk rotation.

  6. Välj Skapa för att starta distributionen.

  7. Välj nyckeln, välj den aktuella versionen och anteckna sedan nyckelidentifieraren. Den består av nyckelvärdet Uri, nyckelnamnet och nyckelversionen. Du behöver identifieraren för att definiera ett krypterat index i Azure AI Search.

    Skapa en ny nyckel för nyckelvalv

Steg 2: Skapa ett säkerhetsobjekt

Du har flera alternativ för att konfigurera Azure AI Search-åtkomst till krypteringsnyckeln vid körning. Den enklaste metoden är att hämta nyckeln med hjälp av söktjänstens hanterade identitet. Du kan använda antingen en system- eller användarhanterad identitet. På så sätt kan du utelämna stegen för programregistrering och programhemligheter. Du kan också skapa och registrera ett Microsoft Entra-program och låta söktjänsten ange program-ID:t på begäranden.

Vi rekommenderar att du använder en hanterad identitet. Med en hanterad identitet kan söktjänsten autentisera till Azure Key Vault utan att lagra autentiseringsuppgifter (ApplicationID eller ApplicationSecret) i kod. Livscykeln för den här typen av hanterad identitet är kopplad till livscykeln för din söktjänst, som bara kan ha en systemtilldelad hanterad identitet. Mer information om hur hanterade identiteter fungerar finns i Vad är hanterade identiteter för Azure-resurser.

Aktivera den systemtilldelade hanterade identiteten för söktjänsten.

Skärmbild av aktivera systemtilldelad hanterad identitet.

Steg 3: Bevilja behörigheter

Azure Key Vault stöder auktorisering med hjälp av rollbaserade åtkomstkontroller. Vi rekommenderar den här metoden för åtkomstprinciper för Key Vault. Mer information finns i Ge åtkomst till Key Vault-nycklar, certifikat och hemligheter med hjälp av Azure-roller.

I det här steget tilldelar du rollen Key Vault Crypto Service Encryption User till din söktjänst. Om du testar lokalt tilldelar du även den här rollen till dig själv.

  1. Logga in på Azure Portal och hitta ditt nyckelvalv.

  2. Välj Åtkomstkontroll (IAM) och välj Lägg till rolltilldelning.

  3. Välj Key Vault Kryptotjänstkrypteringsanvändare och välj sedan Nästa.

  4. Välj hanterade identiteter, välj medlemmar och välj sedan söktjänstens hanterade identitet.

  5. Välj Granska + tilldela.

Vänta några minuter tills rolltilldelningen tas i drift.

Steg 4: Kryptera innehåll

Krypteringsnycklar läggs till när du skapar ett objekt. Om du vill lägga till en kundhanterad nyckel i ett index, synonymkarta, indexerare, datakälla eller kompetensuppsättning använder du Azure Portal, ett REST API för sökning eller ett Azure SDK för att skapa ett objekt som har kryptering aktiverat. Information om hur du lägger till kryptering med Hjälp av Azure SDK finns i Python-exemplet i den här artikeln.

  1. Anropa API:erna för att skapa för att ange egenskapen encryptionKey :

  2. Infoga encryptionKey-konstruktionen i objektdefinitionen. Den här egenskapen är en förstanivåegenskap på samma nivå som namn och beskrivning. Om du använder samma valv, nyckel och version kan du klistra in samma encryptionKey-konstruktion i varje objektdefinition.

    Det första exemplet visar en encryptionKey för en söktjänst som ansluter med hjälp av en hanterad identitet:

    {
  "encryptionKey": {
    "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
    "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
    "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>"
  }
}

    Det andra exemplet innehåller accessCredentials, som krävs om du har registrerat ett program i Microsoft Entra-ID:

    {
  "encryptionKey": {
    "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
    "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
    "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
    "accessCredentials": {
      "applicationId": "<YOUR-APPLICATION-ID>",
      "applicationSecret": "<YOUR-APPLICATION-SECRET>"
    }
  }
}

  3. Kontrollera att krypteringsnyckeln finns genom att utfärda en GET på objektet.

  4. Kontrollera att objektet fungerar genom att utföra en uppgift, till exempel fråga ett index som har krypterats.

När du har skapat det krypterade objektet i söktjänsten kan du använda det på samma sätt som andra objekt av dess typ. Krypteringen är transparent för användaren och utvecklaren.

Ingen av dessa nyckelvalvsdetaljer anses vara hemliga och kan enkelt hämtas genom att bläddra till relevant Azure Key Vault-sida i Azure Portal.

Viktigt!

Krypterat innehåll i Azure AI Search är konfigurerat för att använda en specifik Azure Key Vault-nyckel med en specifik version. Om du ändrar nyckeln eller versionen måste objektet uppdateras för att kunna använda det innan du tar bort den tidigare. Om du inte gör det blir objektet oanvändbart. Du kommer inte att kunna dekryptera innehållet om nyckeln går förlorad.

Steg 5: Testa kryptering

Kontrollera att krypteringen fungerar genom att återkalla krypteringsnyckeln, fråga indexet (det bör vara oanvändbart) och sedan återställa krypteringsnyckeln.

Använd Azure Portal för den här uppgiften.

  1. På sidan Azure Key Vault väljer du Objektnycklar>.

  2. Välj den nyckel som du nyss skapade och välj sedan Ta bort.

  3. På sidan Azure AI Search väljer du Sökhanteringsindex>.

  4. Välj ditt index och använd Sökutforskaren för att köra en fråga. Du bör få ett fel.

  5. Gå tillbaka till sidan Azure Key Vault-objektnycklar>.

  6. Välj Hantera borttagna nycklar.

  7. Välj din nyckel och välj sedan Återställ.

  8. Gå tillbaka till ditt index i Azure AI Search och kör frågan igen. Du bör se sökresultat. Om du inte ser några omedelbara resultat väntar du en minut och försöker igen.

Konfigurera en princip för att framtvinga CMK-efterlevnad

Azure-principer bidrar till att upprätthålla organisationens standarder och utvärdera efterlevnad i stor skala. Azure AI Search har en valfri inbyggd princip för cmk-tillämpning för hela tjänsten.

I det här avsnittet anger du principen som definierar en CMK-standard för söktjänsten. Sedan konfigurerar du söktjänsten för att tillämpa den här principen.

  1. Gå till den inbyggda principen i webbläsaren. Välj Tilldela

    Skärmbild av tilldelning av inbyggd CMK-princip.

  2. Konfigurera principomfånget. I avsnittet Parametrar avmarkerar du Visa endast parametrar... och anger Effekt till Neka.

    Under utvärderingen av begäran markeras en begäran som matchar en principdefinition för nekande som inkompatibel. Förutsatt att standarden för din tjänst är CMK-kryptering innebär "neka" att begäranden som inte anger CMK-kryptering inte är kompatibla.

    Skärmbild av ändring av den inbyggda CMK-principeffekten så att den nekas.

  3. Slutför skapandet av principen.

  4. Anropa API:et Services – Update för att aktivera CMK-principframtvingande på tjänstnivå.

PATCH https://management.azure.com/subscriptions/<your-subscription-Id>/resourceGroups/<your-resource-group-name>/providers/Microsoft.Search/searchServices/<your-search-service-name>?api-version=2023-11-01

{
    "properties": {
        "encryptionWithCmk": {
            "enforcement": "Enabled"
        }
    }
}

Rotera eller uppdatera krypteringsnycklar

Vi rekommenderar att du använder autorotationsfunktionerna i Azure Key Vault, men du kan också rotera nycklar manuellt.

När du ändrar en nyckel eller dess version måste alla objekt som använder nyckeln först uppdateras för att använda de nya värdena innan du tar bort de gamla värdena. Annars blir objektet oanvändbart eftersom det inte kan dekrypteras.

  1. Fastställ nyckeln som används av en index- eller synonymkarta.

  2. Skapa en ny nyckel i nyckelvalvet, men lämna den ursprungliga nyckeln tillgänglig.

  3. Uppdatera encryptionKey-egenskaperna på en index- eller synonymkarta för att använda de nya värdena. Endast objekt som ursprungligen skapades med den här egenskapen kan uppdateras för att använda ett annat värde.

  4. Inaktivera eller ta bort den tidigare nyckeln i nyckelvalvet. Övervaka åtkomsten till nyckeln för att kontrollera att den nya nyckeln används.

Av prestandaskäl cachelagrar söktjänsten nyckeln i upp till flera timmar. Om du inaktiverar eller tar bort nyckeln utan att ange en ny, fortsätter frågorna att fungera tillfälligt tills cacheminnet upphör att gälla. Men när söktjänsten inte längre kan dekryptera innehåll får du följande meddelande: "Åtkomst förbjuden. Den frågenyckel som används kan ha återkallats – försök igen."

Arbeta med krypterat innehåll

Med kundhanterad nyckelkryptering kan du märka svarstider för både indexering och frågor på grund av det extra krypterings-/dekrypteringsarbetet. Azure AI Search loggar inte krypteringsaktiviteten, men du kan övervaka nyckelåtkomst via nyckelvalvsloggning.

Vi rekommenderar att du aktiverar loggning som en del av key vault-konfigurationen.

  1. Skapa en log analytics-arbetsyta.

  2. Lägg till en diagnostikinställning i nyckelvalvet som använder arbetsytan för datakvarhållning.

  3. Välj granskning eller allLogs för kategorin, ge diagnostikinställningen ett namn och spara den.

Python-exempel på en krypteringsnyckelkonfiguration

Det här avsnittet visar Python-representationen av en encryptionKey i en objektdefinition. Samma definition gäller för index, datakällor, kunskapsuppsättningar, indexerare och synonymkartor. Om du vill prova det här exemplet på söktjänsten och nyckelvalvet laddar du ned notebook-filen från azure-search-python-samples.

Installera vissa paket.

! pip install python-dotenv
! pip install azure-core
! pip install azure-search-documents==11.5.1
! pip install azure-identity

Skapa ett index som har en krypteringsnyckel.

from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    SimpleField,
    SearchFieldDataType,
    SearchableField,
    SearchIndex,
    SearchResourceEncryptionKey
)
from azure.identity import DefaultAzureCredential

endpoint="<PUT YOUR AZURE SEARCH SERVICE ENDPOINT HERE>"
credential = DefaultAzureCredential()

index_name = "test-cmk-index"
index_client = SearchIndexClient(endpoint=endpoint, credential=credential)  
fields = [
        SimpleField(name="Id", type=SearchFieldDataType.String, key=True),
        SearchableField(name="Description", type=SearchFieldDataType.String)
    ]

scoring_profiles = []
suggester = []
encryption_key = SearchResourceEncryptionKey(
    key_name="<PUT YOUR KEY VAULT NAME HERE>",
    key_version="<PUT YOUR ALPHANUMERIC KEY VERSION HERE>",
    vault_uri="<PUT YOUR KEY VAULT ENDPOINT HERE>"
)

index = SearchIndex(name=index_name, fields=fields, encryption_key=encryption_key)
result = index_client.create_or_update_index(index)
print(f' {result.name} created')

Hämta indexdefinitionen för att verifiera att krypteringsnyckelkonfigurationen finns.

index_name = "test-cmk-index-qs"
index_client = SearchIndexClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)  

result = index_client.get_index(index_name)  
print(f"{result}")

Läs in indexet med några dokument. Allt fältinnehåll anses vara känsligt och krypteras på disk med hjälp av din kundhanterade nyckel.

from azure.search.documents import SearchClient

# Create a documents payload
documents = [
    {
    "@search.action": "upload",
    "Id": "1",
    "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities."
    },
    {
    "@search.action": "upload",
    "Id": "2",
    "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts."
    },
    {
    "@search.action": "upload",
    "Id": "3",
    "Description": "The hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services."
    },
    {
    "@search.action": "upload",
    "Id": "4",
    "Description": "The hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace."
    }
]

search_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, index_name=index_name, credential=credential)
try:
    result = search_client.upload_documents(documents=documents)
    print("Upload of new document succeeded: {}".format(result[0].succeeded))
except Exception as ex:
    print (ex.message)

    index_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)

Kör en fråga för att bekräfta att indexet fungerar.

from azure.search.documents import SearchClient

query = "historic"  

search_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential, index_name=index_name)
  
results = search_client.search(  
    query_type='simple',
    search_text=query, 
    select=["Id", "Description"],
    include_total_count=True
    )
  
for result in results:  
    print(f"Score: {result['@search.score']}")
    print(f"Id: {result['Id']}")
    print(f"Description: {result['Description']}")

Utdata från frågan bör ge resultat som liknar följande exempel.

Score: 0.6130029
Id: 4
Description: The hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.
Score: 0.26286605
Id: 1
Description: The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.

Eftersom krypterat innehåll dekrypteras före datauppdatering eller frågor visas inga visuella tecken på kryptering. Kontrollera att krypteringen fungerar genom att kontrollera resursloggarna.

Nästa steg

Om du inte är bekant med Azure-säkerhetsarkitekturen läser du dokumentationen för Azure Security och i synnerhet den här artikeln:

Vilande datakryptering