From 99764618c1d86805f2466b063f290a49934a09a2 Mon Sep 17 00:00:00 2001 From: Fi Quick <47183728+fiquick@users.noreply.github.com> Date: Thu, 13 Feb 2025 14:20:23 +0000 Subject: [PATCH] add cmek (#602) --- modules/ROOT/content-nav.adoc | 1 + modules/ROOT/pages/security/encryption.adoc | 117 +++++++++++--------- 2 files changed, 65 insertions(+), 53 deletions(-) diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 452f70ca4..3c6d5f7ce 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -81,6 +81,7 @@ Generic Start * Security ** xref:security/single-sign-on.adoc[Single sign-on] +** xref:security/encryption.adoc[Encryption] * xref:user-management.adoc[User management] diff --git a/modules/ROOT/pages/security/encryption.adoc b/modules/ROOT/pages/security/encryption.adoc index 79fdb2aa6..c71c59e12 100644 --- a/modules/ROOT/pages/security/encryption.adoc +++ b/modules/ROOT/pages/security/encryption.adoc @@ -4,19 +4,24 @@ All data stored in Neo4j Aura is encrypted using intra-cluster encryption between the various nodes comprising your instance and encrypted at rest using the underlying cloud provider's encryption mechanism. +Aura always requires encrypted connections and ensures that clients validate server certificates when establishing a connection. +This means that network traffic flowing to and from Neo4j Aura is always encrypted. + By default, each cloud provider encrypts all backup buckets (including the objects stored inside) using either link:https://cloud.google.com/storage/docs/encryption/default-keys[Google-managed encryption], link:https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html[AWS SSE-S3 encryption], or link:https://learn.microsoft.com/en-us/azure/storage/common/storage-service-encryption[Azure Storage encryption]. +To protect data at rest, Aura uses encrypted data storage capabilities offered by the cloud providers. +Whether customers choose to host in AWS, Azure, or GCP, each object store provides server-side encrypted buckets for data at rest encryption. +By default, AWS, Azure, and GCP encrypt all backup buckets (including the objects stored inside) with AWS SSE-S3 encryption, Azure Storage Encryption (SSE), or Google-managed encryption. +This ensures all your data stored in any one of these cloud providers uses 256-bit Advanced Encryption Standard (AES). + +In addition to Aura’s default encryption for data at rest, Customer Managed Keys enable security-conscious enterprises to manage encryption keys through their Cloud Service Provider's Key Management Services (KMS) on Aura, granting control over data protection and access management, including the ability to revoke access from Neo4j. +This allows adherence to strict security policies alongside Aura's default enterprise-grade security measures. + == Customer Managed Keys -label:AuraDB-Enterprise[] +label:AuraDB-Virtual-Dedicated-Cloud[] label:AuraDS-Enterprise[] -[NOTE] -==== -This feature has been released as a public GA for AuraDB Enterprise and AuraDS Enterprise for AWS managed keys. -GCP’s Cloud Key Management and Azure’s Key Vault are in development. -==== - A Customer Managed Key (CMK) gives you more control over key operations than the standard Neo4j encryption. These are created and managed using a supported cloud key management service (KMS). Externally, Customer Managed Keys are also known as Customer Managed Encryption Keys (CMEK). @@ -26,19 +31,13 @@ Customer Managed Keys are supported for v4.x and latest version instances. When using Customer Managed Keys, you give Aura permission to encrypt and decrypt using the key, but Aura has no access to the key’s material. Aura has no control over the availability of your externally managed key in the KMS. -If you lose keys that are managed outside of Aura, Aura can’t recover your data. [WARNING] ==== -The loss of a Customer Managed Key, through deletion, disabling, or expiration, renders all data encrypted with that key unrecoverable. -Neo4j cannot administer database instances when keys are disabled, deleted, or permissions revoked. +The loss of a Customer Managed Key makes all data encrypted with that key inaccessible. +Neo4j is unable to manage database instances if the key is disabled, deleted, expired, or if permissions are revoked. ==== -=== Delete a key - -If a Customer Managed Key is being used to encrypt one or more Aura instances in the console, it can't be deleted. -If you need to delete the key, first delete the Aura database instances encrypted with the key, then delete the key. - === Key rotation In your KMS platform, you can either configure automatic rotation for the Customer Managed Key, or you can perform a manual rotation. @@ -46,26 +45,39 @@ In your KMS platform, you can either configure automatic rotation for the Custom Although automatic rotation is not enforced by Aura, it is best practice to rotate keys regularly. Manual key rotation is **not** recommended. -=== Regions - -There is a limit of one key for AuraDB and one key for AuraDS per region. -Depending on the KMS, there may be a delay between disabling a key, and when it can no longer be used to encrypt and decrypt data. - === Import an existing database -You can upload a database to instances encrypted with Customer Managed Keys in Neo4j latest directly from the console or by using `neo4j-admin database upload`. +You can upload a database to instances encrypted with Customer Managed Keys in Neo4j 5 directly from the console or by using `neo4j-admin database upload`. If the database is larger than 4 GB, you have to use `neo4j-admin database upload`. Note that the `neo4j-admin push-to-cloud` command in Neo4j v4.4 and earlier is **not** supported for instances encrypted with Customer Managed Keys. -//For more information see the xref:auradb/importing/import-database.adoc#_neo4j_admin_database_upload[Neo4j Admin `database upload`] documentation. -//Link is not working +For more information see the link:https://neo4j.com/docs/aura/classic/auradb/importing/import-database/#_neo4j_admin_database_upload[Neo4j Admin `database upload`] documentation. === Clone an instance protected by CMK To clone an instance protected by a Customer Managed Key, the key must be valid and available to Aura. -The cloned instance, by default, uses the available Customer Managed Key for that region and product. +If the same CMK does not exist in the destination region and product, the cloned instance must be encrypted with an available CMK for that region and product. + +It is best practice to use the same Customer Managed Key as the instance it’s being cloned from. +You can override this to use another Customer Managed Key - but you can not use the Neo4j Managed Key. + +When cloning an instance that is encrypted with a Customer Managed Key, specific restrictions apply when using the API. +Below are the details and possible errors that you may encounter depending on the cloning method and key configurations. -You can override this behavior by selecting the Neo4j Managed Key when cloning the database. -If there is no valid CMK for the destination region and product, the Neo4j Managed Key is used to encrypt the cloned instance. +.Summary of cloning restrictions +|=== +| Cloning method | Destination key | Result + +| **Console & API** | Same CMK as source instance | Cloning allowed. +| **Console** | Different CMK than source instance | Cloning allowed. Warning message shown. +| **Console** | Neo4j Managed Key | Cloning blocked. Error message shown. +| **API** | Different CMK than source instance, or Neo4j Managed Key | Cloning blocked. Error message shown. +|=== + +=== Remove a CMK from Aura + +When using a Customer Managed Key within Aura to encrypt one or more Aura database instances, it cannot be removed from Aura. +If you no longer need to use this Customer Managed Key to encrypt Aura databases, first delete the Aura database instances that are encrypted with the key, then you can remove the key from Aura. +Keep in mind that this process only breaks the link between the key and Aura —- it does not delete the actual key from the Cloud KMS. == AWS keys @@ -74,7 +86,7 @@ If there is no valid CMK for the destination region and product, the Neo4j Manag . Create a key in the AWS KMS making sure the region matches your Aura database instance. Copy the generated ARN. You need it in the next step. -. Go to *security settings* in the Aura console, add a *Customer Managed Key* and copy the JSON code that is generated in the Aura console when you add a key. +. Go to *security settings* in the Aura Console, add a *Customer Managed Key* and copy the JSON code that is generated in the Aura Console when you add a key. . In the AWS KMS, edit the key policy to include the JSON code. === Edit the AWS key policy @@ -82,19 +94,19 @@ You need it in the next step. After you have initially created a key in the AWS KMS, you can edit the key policy. In the AWS key policy, "Statement" is an array that consists of one or more objects. Each object in the array describes a security identifier (SID). -The objects in the AWS code array are comma-separated, e.g. `{[{'a'}, {'b'}, {'c'}]}` +The objects in the AWS code array are comma-separated, for example `{[{'a'}, {'b'}, {'c'}]}`. -Add a comma after the curly brace in the final SID, and then paste the JSON code that was generated in the Aura console, e.g. `{[{'a'}, {'b'}, {'c'}, _add code here_ ]}` +Add a comma after the curly brace in the final SID, and then paste the JSON code that was generated in the Aura Console (for example `{[{'a'}, {'b'}, {'c'}, _add code here_ ]}`). === AWS regions -When creating a Customer Managed Key in the AWS KMS, you can create a single-region key in a single AWS region, or create a multi-region key that you can replicate into multiple AWS regions. -Aura only supports AWS Customer Managed Keys that reside in the same region as the instance. +Aura supports AWS Customer Managed Keys that reside in the same region as the instance. +When creating a Customer Managed Key in the AWS KMS, you can create a single-region key, or create a multi-region key. -[CAUTION] -==== -In Aura, you can use AWS single-region keys, multi-region keys or replica keys as long as the key resides in the same region as the Aura instace. -==== +Single-region keys reside in only one AWS region, which must be the same region as your Aura instance. + +Multi-region keys have a primary region, however these can be replicated to other regions that match the region of your Aura instance. +The replicas share the same key ID and different Amazon Resource Names (ARNs) with the primary key. === AWS automatic key rotation @@ -111,24 +123,28 @@ Move through the tabs to enable to following: * Purge protection * Azure role-based access control * Azure Disk Encryption for volume encryption -* Allow access from all networks +* When setting up the key vault, in Networking you can choose: +** *Allow public access from all networks* +** *Allow public access from specific virtual networks and IP addresses* (need to check *Allow trusted Microsoft services to bypass this firewall*) +** *Disable public access* (need to check *Allow trusted Microsoft services to bypass this firewall*) +** If you need to edit the public access setting after setting up the key vault, you will find public access options in Networking > Firewalls and Virtual Networks and below it is the Exception section the checkbox to Allow trusted Microsoft services to bypass this firewall. === Create a key -. When preparing to create a key, if needed grant a role assigment: +. When preparing to create a key, if needed grant a role assignment: .. Inside the key vault, go to *Access Control (IAM)* and *add role assignment*. .. In the *Role* tab, select *Key Vault Administrator*. .. In the *Member* tab, select *User, group, or service principal*. -.. *Select members* and select yourself or the relevant person, then *Review + Assign*. +.. From *Select members*, add yourself or the relevant person, then *Review + Assign*. . Create a key in the Azure Key Vault. . After the key is created, click into key version and copy the *Key Identifier*, you need it in the next step. -. Go to *security settings* in the Aura console and add a *Customer Managed Key*. -. Follow the instructions in the Aura console for the next sections. +. Go to *security settings* in the Aura Console and add a *Customer Managed Key*. +. Follow the instructions in the Aura Console for the next sections. === Create a service principal -In the Azure Entra ID tenant where your key is located, create a service principal linked to the Neo4j CMK Application with the *Neo4j CMK Application ID* displayed in the Aura console. +In the Azure Entra ID tenant where your key is located, create a service principal linked to the Neo4j CMK Application with the *Neo4j CMK Application ID* displayed in the Aura Console. One way to do this is by clicking the terminal icon at the top of the Azure portal, to open the Azure Cloud Shell. @@ -138,14 +154,14 @@ Using Azure CLI, the command is: ---- az ad sp create --id Neo4jCMKApplicationID ---- -For more information about the Azure CLI, see link:https://learn.microsoft.com/en-us/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create[az ad sp documentation]. +For more information about the Azure CLI, see link:https://learn.microsoft.com/en-us/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create[`az ad sp` documentation]. === Grant key permissions . To add role assignment to the Azure key, inside the key, go to *Access control (IAM)* and add *role assignment*. . In the *Role* tab, select *Key Vault Crypto Officer*. . In the *Member* tab, select *User, group, or service principal*. -. *Select members* and paste the *Neo4j CMK Application name* that is displayed in the Aura console. +. In *Select members*, paste the *Neo4j CMK Application name* that is displayed in the Aura Console. . The *Neo4j CMK Application* should appear, select this application then *Review + Assign*. == GCP keys @@ -160,23 +176,18 @@ For more information about the Azure CLI, see link:https://learn.microsoft.com/e === Create a key -. Create a key in the Google console. +. Create a key in the Google Console. You can use default settings for the options, but setting a key rotation period is recommended. . Select *Create* and you are brought to the key ring, with your key listed. . Click *More* (three dots) and *Copy resource name*, you need it in the next step. For more information, see link:https://cloud.google.com/kms/docs/getting-resource-ids[Google Cloud docs] -. Go to *security settings* in the Aura console and add a *Customer Managed Key*. +. Go to *security settings* in the Aura Console and add a *Customer Managed Key*. Paste the *resource name* into the *Encryption Key Resource Name* field. -. After you select *Add Key* in the Aura console, three *service accounts* are displayed in the Aura console. +. After you select *Add Key* in the Aura Console, three *service accounts* are displayed in the Aura Console. You will need these in the next steps. === Grant key permissions . Go to the Google Cloud console, click into the key and go to *Permissions* then *Grant Access*. -. In *Add principals* paste the three service accounts from the Aura console. -. In *Assign roles* assign both *Cloud KMS CryptoKey Encrypter/Decrypter* and *Cloud KMS Viewer* roles to all three service accounts. - - - - - +. In *Add principals* paste the three service accounts from the Aura Console. +. In *Assign roles* assign both *Cloud KMS CryptoKey Encrypter/Decrypter* and *Cloud KMS Viewer* roles to all three service accounts. \ No newline at end of file