Delen via

Gebruik versleuteling aan clientzijde met Always Encrypted voor Azure Cosmos DB

  • Artikel

VAN TOEPASSING OP: NoSQL

Belangrijk

Er is een belangrijke wijziging geïntroduceerd in de versie 1.0 van onze versleutelingspakketten. Als u gegevensversleutelingssleutels en containers met versleuteling hebt gemaakt met eerdere versies, moet u uw databases en containers opnieuw maken nadat u uw clientcode naar 1.0-pakketten hebt gemigreerd.

Always Encrypted is een functie die is ontworpen om gevoelige gegevens te beschermen, zoals creditcardnummers of nationale/regionale identificatienummers (bijvoorbeeld amerikaanse burgerservicenummers), opgeslagen in Azure Cosmos DB. Met Always Encrypted kunnen clients gevoelige gegevens in clienttoepassingen versleutelen en nooit de versleutelingssleutels aan de database onthullen.

Always Encrypted biedt versleutelingsmogelijkheden aan de clientzijde naar Azure Cosmos DB. Het versleutelen van uw gegevensclient kan vereist zijn in de volgende scenario's:

  • Gevoelige gegevens beveiligen met specifieke vertrouwelijkheidskenmerken: Met Always Encrypted kunnen clients gevoelige gegevens in hun toepassingen versleutelen en nooit de gegevens of versleutelingssleutels voor tekst zonder opmaak zichtbaar maken voor de Azure Cosmos DB-service.
  • Toegangsbeheer per eigenschap implementeren: omdat de versleuteling wordt beheerd met sleutels die u bezit en beheert vanuit Azure Key Vault, kunt u toegangsbeleid toepassen om te bepalen tot welke gevoelige eigenschappen elke client toegang heeft.

Concepten

Always Encrypted voor Azure Cosmos DB introduceert enkele nieuwe concepten die betrokken zijn bij de configuratie van uw versleuteling aan de clientzijde.

Versleutelingssleutels

Gegevensversleutelingssleutels

Wanneer u Always Encrypted gebruikt, worden gegevens versleuteld met DEK (Data Encryption Keys) die vooruit moeten worden gemaakt. Deze DEK's worden opgeslagen in de Azure Cosmos DB-service en worden gedefinieerd op databaseniveau, zodat een DEK kan worden gedeeld in meerdere containers. Het maken van de DEK's wordt uitgevoerd aan de clientzijde met behulp van de Azure Cosmos DB SDK.

U kunt:

  • Maak één DEK per eigenschap om te versleutelen of
  • Gebruik dezelfde DEK om meerdere eigenschappen te versleutelen.

Door klant beheerde sleutels

Voordat DEK's worden opgeslagen in Azure Cosmos DB, worden ze verpakt door een door de klant beheerde sleutel (CMK). Door het verpakken en uitpakken van DEK's te beheren, beheren CMK's effectief de toegang tot de gegevens die zijn versleuteld met de bijbehorende DEK's. CMK-opslag is ontworpen als uitbreidbaar, met een standaard implementatie waarin wordt verwacht dat ze worden opgeslagen in Azure Key Vault.

Versleutelingssleutels

Versleutelingsbeleid

Net als bij een indexeringsbeleid is een versleutelingsbeleid een specificatie op containerniveau waarin wordt beschreven hoe JSON-eigenschappen moeten worden versleuteld. Dit beleid moet worden opgegeven wanneer de container wordt gemaakt en onveranderbaar is. In de huidige release kunt u het versleutelingsbeleid niet bijwerken.

Voor elke eigenschap die u wilt versleutelen, definieert het versleutelingsbeleid het volgende:

  • Het pad van de eigenschap in de vorm van /property. Alleen paden op het hoogste niveau worden momenteel ondersteund, geneste paden zoals /path/to/property worden niet ondersteund.
  • De id van de DEK die moet worden gebruikt bij het versleutelen en ontsleutelen van de eigenschap.
  • Een versleutelingstype. Het kan willekeurig of deterministisch zijn.
  • Het versleutelingsalgoritmen dat moet worden gebruikt bij het versleutelen van de eigenschap. Het opgegeven algoritme kan het algoritme overschrijven dat is gedefinieerd bij het maken van de sleutel als deze compatibel zijn.

Gerandomiseerde versus deterministische versleuteling

De Azure Cosmos DB-service ziet nooit de tekst zonder opmaak van eigenschappen die zijn versleuteld met Always Encrypted. Het biedt echter nog steeds ondersteuning voor bepaalde querymogelijkheden voor de versleutelde gegevens, afhankelijk van het versleutelingstype dat voor een eigenschap wordt gebruikt. Always Encrypted ondersteunt de volgende twee typen versleuteling:

  • Deterministische versleuteling: deze genereert altijd dezelfde versleutelde waarde voor een bepaalde waarde voor tekst zonder opmaak en versleutelingsconfiguratie. Met behulp van deterministische versleuteling kunnen query's gelijkheidsfilters uitvoeren op versleutelde eigenschappen. Het kan echter toestaan dat aanvallers informatie over versleutelde waarden raden door patronen in de versleutelde eigenschap te onderzoeken. Dit geldt met name als er een kleine set mogelijke versleutelde waarden is, zoals Waar/Onwaar of Noord/Zuid/Oost/West-regio.

  • Gerandomiseerde versleuteling: er wordt een methode gebruikt waarmee gegevens op een minder voorspelbare manier worden versleuteld. Gerandomiseerde versleuteling is veiliger, maar voorkomt dat query's filteren op versleutelde eigenschappen.

Zie Het genereren van de initialisatievector (IV) voor meer informatie over deterministische en willekeurige versleuteling in Always Encrypted.

Azure Key Vault instellen

De eerste stap om aan de slag te gaan met Always Encrypted is het maken van uw CMK's in Azure Key Vault:

  1. Maak een nieuw Azure Key Vault-exemplaar of blader naar een bestaand exemplaar.
  2. Maak een nieuwe sleutel in de sectie Sleutels .
  3. Zodra de sleutel is gemaakt, bladert u naar de huidige versie en kopieert u de volledige sleutel-id:
    https://<my-key-vault>.vault.azure.net/keys/<key>/<version>. Als u de sleutelversie aan het einde van de sleutel-id weglaat, wordt de meest recente versie van de sleutel gebruikt.

Vervolgens moet u configureren hoe de Azure Cosmos DB SDK toegang krijgt tot uw Azure Key Vault-exemplaar. Deze verificatie wordt uitgevoerd via een Microsoft Entra-identiteit. Waarschijnlijk gebruikt u de identiteit van een Microsoft Entra-toepassing of een beheerde identiteit als proxy tussen uw clientcode en uw Azure Key Vault-exemplaar, hoewel elk type identiteit kan worden gebruikt. Gebruik de volgende stappen om uw Microsoft Entra-identiteit als proxy te gebruiken:

  1. Blader vanuit uw Azure Key Vault-exemplaar naar de sectie Toegangsbeleid en voeg een nieuw beleid toe:

    1. Selecteer In Sleutelmachtigingen Ophalen, Weergeven, Sleutel uitpakken, Sleutel verpakken, Verifiëren en Ondertekenen.
    2. Zoek in Select Principal naar uw Microsoft Entra-identiteit.

Uw CMK beschermen tegen onbedoelde verwijdering

Om ervoor te zorgen dat u geen toegang verliest tot uw versleutelde gegevens nadat uw CMK per ongeluk is verwijderd, is het raadzaam om twee eigenschappen in te stellen op uw Azure Key Vault-exemplaar: Voorlopig verwijderen en Beveiliging opschonen.

Als u een nieuw Azure Key Vault-exemplaar maakt, schakelt u deze eigenschappen in tijdens het maken:

Schermopname van de eigenschappen voor voorlopig verwijderen en opschonen van een nieuw Azure Key Vault-exemplaar.

Als u een bestaand Exemplaar van Azure Key Vault gebruikt, kunt u controleren of deze eigenschappen zijn ingeschakeld door de sectie Eigenschappen in Azure Portal te bekijken. Als een van deze eigenschappen niet is ingeschakeld, raadpleegt u de secties 'Voorlopig verwijderen inschakelen' en 'Beveiliging tegen opschonen inschakelen' in een van de volgende artikelen:

De SDK initialiseren

Notitie

Always Encrypted voor Azure Cosmos DB wordt momenteel ondersteund:

  • In .NET met het pakket Microsoft.Azure.Cosmos.Encryption.
  • In Java met het pakket azure.cosmos.encryption.

Als u Always Encrypted wilt gebruiken, moet een exemplaar van een KeyResolver exemplaar worden gekoppeld aan uw Azure Cosmos DB SDK-exemplaar. Deze klasse, gedefinieerd in de Azure.Security.KeyVault.Keys.Cryptography naamruimte, wordt gebruikt om te communiceren met het sleutelarchief dat als host fungeert voor uw CMK's.

De volgende codefragmenten gebruiken de DefaultAzureCredential klasse om de Microsoft Entra-identiteit op te halen die moet worden gebruikt bij het openen van uw Azure Key Vault-exemplaar. Hier vindt u voorbeelden van het maken van TokenCredential verschillende soorten klassen.

Notitie

U hebt het extra Azure.Identity-pakket nodig om toegang te krijgen tot de TokenCredential klassen.

var tokenCredential = new DefaultAzureCredential();
var keyResolver = new KeyResolver(tokenCredential);
var client = new CosmosClient("<connection-string>")
    .WithEncryption(keyResolver, KeyEncryptionKeyResolverName.AzureKeyVault);

Een gegevensversleutelingssleutel maken

Voordat gegevens in een container kunnen worden versleuteld, moet er een gegevensversleutelingssleutel worden gemaakt in de bovenliggende database.

Het maken van een nieuwe sleutel voor gegevensversleuteling wordt uitgevoerd door de methode aan te roepen en door CreateClientEncryptionKeyAsync te geven:

  • Een tekenreeks-id waarmee de sleutel in de database uniek wordt geïdentificeerd.
  • Het versleutelingsalgoritmen dat is bedoeld voor gebruik met de sleutel. Er wordt momenteel slechts één algoritme ondersteund.
  • De sleutel-id van de CMK die is opgeslagen in Azure Key Vault. Deze parameter wordt doorgegeven in een algemeen EncryptionKeyWrapMetadata object waarbij:
    • Hiermee type definieert u het type sleutel-resolver (bijvoorbeeld Azure Key Vault).
    • De name naam kan elke gewenste beschrijvende naam zijn.
    • Dit value moet de sleutel-id zijn.

    Belangrijk

    Zodra de sleutel is gemaakt, bladert u naar de huidige versie en kopieert u de volledige sleutel-id: https://<my-key-vault>.vault.azure.net/keys/<key>/<version>. Als u de sleutelversie aan het einde van de sleutel-id weglaat, wordt de meest recente versie van de sleutel gebruikt.

    • Het algorithm definieert welk algoritme moet worden gebruikt om de sleutelversleutelingssleutel te verpakken met de door de klant beheerde sleutel.
var database = client.GetDatabase("my-database");
await database.CreateClientEncryptionKeyAsync(
    "my-key",
    DataEncryptionAlgorithm.AeadAes256CbcHmacSha256,
    new EncryptionKeyWrapMetadata(
        KeyEncryptionKeyResolverName.AzureKeyVault,
        "akvKey",
        "https://<my-key-vault>.vault.azure.net/keys/<key>/<version>",
        EncryptionAlgorithm.RsaOaep.ToString()));

Een container maken met versleutelingsbeleid

Geef het versleutelingsbeleid op containerniveau op bij het maken van de container.

var path1 = new ClientEncryptionIncludedPath
{
    Path = "/property1",
    ClientEncryptionKeyId = "my-key",
    EncryptionType = EncryptionType.Deterministic.ToString(),
    EncryptionAlgorithm = DataEncryptionAlgorithm.AeadAes256CbcHmacSha256
};
var path2 = new ClientEncryptionIncludedPath
{
    Path = "/property2",
    ClientEncryptionKeyId = "my-key",
    EncryptionType = EncryptionType.Randomized.ToString(),
    EncryptionAlgorithm = DataEncryptionAlgorithm.AeadAes256CbcHmacSha256
};
await database.DefineContainer("my-container", "/partition-key")
    .WithClientEncryptionPolicy()
    .WithIncludedPath(path1)
    .WithIncludedPath(path2)
    .Attach()
    .CreateAsync();

Versleutelde gegevens lezen en schrijven

Hoe gegevens worden versleuteld

Wanneer een document naar Azure Cosmos DB wordt geschreven, zoekt de SDK het versleutelingsbeleid op om erachter te komen welke eigenschappen moeten worden versleuteld en hoe. Het resultaat van de versleuteling is een base 64-tekenreeks.

Versleuteling van complexe typen:

  • Wanneer de eigenschap die moet worden versleuteld een JSON-matrix is, wordt elke vermelding van de matrix versleuteld.

  • Wanneer de eigenschap die moet worden versleuteld een JSON-object is, worden alleen de bladwaarden van het object versleuteld. De namen van tussenliggende subeigenschappen blijven in tekst zonder opmaak.

Versleutelde items lezen

Er is geen expliciete actie vereist voor het ontsleutelen van versleutelde eigenschappen bij het uitgeven van puntleesbewerkingen (het ophalen van één item op basis van de id en partitiesleutel), query's of het lezen van de wijzigingenfeed. Dit komt doordat:

  • De SDK zoekt het versleutelingsbeleid op om erachter te komen welke eigenschappen moeten worden ontsleuteld.
  • Het resultaat van de versleuteling sluit het oorspronkelijke JSON-type van de waarde in.

Houd er rekening mee dat de resolutie van versleutelde eigenschappen en de daaropvolgende ontsleuteling alleen zijn gebaseerd op de resultaten die worden geretourneerd door uw aanvragen. Als deze bijvoorbeeld property1 is versleuteld maar wordt geprojecteerd in property2 (SELECT property1 AS property2 FROM c), wordt deze niet geïdentificeerd als een versleutelde eigenschap wanneer deze wordt ontvangen door de SDK.

Query's filteren op versleutelde eigenschappen

Bij het schrijven van query's die filteren op versleutelde eigenschappen, moet een specifieke methode worden gebruikt om de waarde van de queryparameter door te geven. Deze methode gebruikt de volgende argumenten:

  • De naam van de queryparameter.
  • De waarde die in de query moet worden gebruikt.
  • Het pad van de versleutelde eigenschap (zoals gedefinieerd in het versleutelingsbeleid).

Belangrijk

Versleutelde eigenschappen kunnen alleen worden gebruikt in gelijkheidsfilters (WHERE c.property = @Value). Elk ander gebruik retourneert onvoorspelbare en verkeerde queryresultaten. Deze beperking wordt beter afgedwongen in volgende versies van de SDK.

var queryDefinition = container.CreateQueryDefinition(
    "SELECT * FROM c where c.property1 = @Property1");
await queryDefinition.AddParameterAsync(
    "@Property1",
    1234,
    "/property1");

Documenten lezen wanneer alleen een subset van eigenschappen kan worden ontsleuteld

In situaties waarin de client geen toegang heeft tot alle CMK die wordt gebruikt voor het versleutelen van eigenschappen, kan alleen een subset eigenschappen worden ontsleuteld wanneer gegevens worden teruggelezen. Als bijvoorbeeld property1 is versleuteld met sleutel1 en property2 is versleuteld met key2, kan een clienttoepassing die alleen toegang heeft tot key1 nog steeds gegevens lezen, maar niet property2. In dat geval moet u uw gegevens lezen via SQL-query's en de eigenschappen weg projecteren die de client niet kan ontsleutelen: SELECT c.property1, c.property3 FROM c.

CMK-draaiing

U kunt uw CMK 'draaien' (dat wil gezegd een nieuwe CMK gebruiken in plaats van de huidige) als u vermoedt dat de huidige CMK is aangetast. Het is ook een veelvoorkomende beveiligingspraktijk om de CMK regelmatig te roteren. Als u deze rotatie wilt uitvoeren, hoeft u alleen de sleutel-id op te geven van de nieuwe CMK die moet worden gebruikt om een specifieke DEK te verpakken. Houd er rekening mee dat deze bewerking geen invloed heeft op de versleuteling van uw gegevens, maar op de beveiliging van de DEK. De toegang tot de vorige CMK mag pas worden ingetrokken als de rotatie is voltooid.

await database.RewrapClientEncryptionKeyAsync(
    "my-key",
    new EncryptionKeyWrapMetadata(
        KeyEncryptionKeyResolverName.AzureKeyVault,
        "akvKey",
        "https://<my-key-vault>.vault.azure.net/keys/<new-key>/<version>",
        EncryptionAlgorithm.RsaOaep.ToString()));

DEK-draaiing

Het uitvoeren van een rotatie van een gegevensversleutelingssleutel wordt niet aangeboden als kant-en-klare functie. Dit komt doordat het bijwerken van een DEK een scan vereist van alle containers waarin deze sleutel wordt gebruikt en een herversleuteling van alle eigenschappen die met deze sleutel zijn versleuteld. Deze bewerking kan alleen op de client worden uitgevoerd omdat de Azure Cosmos DB-service de waarde voor tekst zonder opmaak van de DEK niet opslaat of ooit opent.

In de praktijk kan een DEK-rotatie worden uitgevoerd door een gegevensmigratie uit te voeren van de betrokken containers naar nieuwe containers. De nieuwe containers kunnen op dezelfde manier worden gemaakt als de oorspronkelijke containers. Om u te helpen bij een dergelijke gegevensmigratie, kunt u een zelfstandig hulpprogramma voor migratie vinden op GitHub.

Aanvullende versleutelde eigenschappen toevoegen

Het toevoegen van extra versleutelde eigenschappen aan een bestaand versleutelingsbeleid wordt om dezelfde redenen niet ondersteund als in de sectie hierboven. Voor deze bewerking is een volledige scan van de container vereist om ervoor te zorgen dat alle exemplaren van de eigenschappen correct zijn versleuteld. Dit is een bewerking die alleen kan worden uitgevoerd aan de clientzijde. Net als bij een DEK-rotatie kunnen extra versleutelde eigenschappen worden toegevoegd door een gegevensmigratie uit te voeren naar een nieuwe container met een geschikt versleutelingsbeleid.

Als u flexibiliteit hebt in de manier waarop nieuwe versleutelde eigenschappen kunnen worden toegevoegd vanuit het oogpunt van een schema, kunt u ook gebruikmaken van de schemaagnostische aard van Azure Cosmos DB. Als u een eigenschap gebruikt die in uw versleutelingsbeleid is gedefinieerd als een 'eigenschappenverzameling', kunt u hieronder meer eigenschappen toevoegen zonder beperking. Stel dat dit property1 is gedefinieerd in uw versleutelingsbeleid en dat u in eerste instantie in uw documenten schrijft property1.property2 . Als u in een later stadium moet toevoegen property3 als een versleutelde eigenschap, kunt u beginnen met schrijven property1.property3 in uw documenten en wordt de nieuwe eigenschap ook automatisch versleuteld. Voor deze aanpak is geen gegevensmigratie vereist.

Volgende stappen