Menu Docs
Página inicial do Docs
/ /
Backend do Django MongoDB
Página inicial do Docs
/
Bibliotecas do cliente
/
Python
/
Backend do Django MongoDB
Página inicial do Docs
/
Bibliotecas do cliente
/
Python
/
Backend do Django MongoDB

Tutorial: Queryable Encryption com backend do Django MongoDB

Visão geral

Neste tutorial, você pode aprender como usar a Queryable Encryption (QE) em um aplicação Django.

O recurso de Queryable Encryption do MongoDB ajuda a proteger dados confidenciais, criptografando-os automaticamente e, ao mesmo tempo, permitindo que seu aplicação interaja com os dados criptografados. Neste tutorial, você pode aprender como usar a Queryable Encryption com o Django MongoDB Backend ativando a criptografia nas configurações do aplicação e escolhendo campos de modelo para criptografia.

Pré-requisitos

Antes de iniciar este tutorial, conclua as seguintes tarefas de pré-requisito:

  • Crie uma conta MongoDB Atlas e configure um cluster. Certifique-se de que seu cluster seja executado no MongoDB Server versão 7.0 ou posterior. Para saber mais, consulte o guia Introduçãoao MongoDB .

  • Baixe a biblioteca compartilhada de criptografia automática. Para visualizar as instruções, consulte o guia Instalar e configurar um componente de análise de query. Estas instruções mostram como navegar até o Centro de Download do MongoDB e preencher o formulário necessário para baixar a biblioteca.

  • Instale o Python 3.10 ou posterior.

Tutorial

Neste tutorial, você cria um aplicação Queryable Encryption que usa o backend do Django MongoDB . O aplicação lida com os registros médicas com segurança: ele criptografa, descriptografa e consulta informações médicas confidenciais.

Dica

Aplicativo completo

Para visualizar o aplicação de amostra completo para este tutorial, consulte a pasta django_qe no GitHub.

Configurar seu projeto

Siga as etapas desta seção para instalar as dependências do projeto , configurar seu ambiente e criar a estrutura do aplicação .

1

Instale o Django MongoDB Backend com as dependências do QE.

Selecione a aba correspondente ao seu sistema operacional e execute os seguintes comandos para ativar um ambiente virtual, instalar o Django MongoDB Backend e instalar as dependências do Queryable Encryption :

python -m venv venv
source venv/bin/activate
pip install 'django-mongodb-backend[encryption]'
python -m venv venv
. venv\Scripts\activate
pip install 'django-mongodb-backend[encryption]'

O comando pip install 'django-mongodb-backend[encryption]' instala o Django MongoDB Backend, a versão mais recente do PyMongo e as dependências necessárias do Python.

Observação

Disponível em v6.0.1

A Queryable Encryption requer Django MongoDB Backend v6.0.1 ou posterior. O comando anterior instala a versão necessária.

2

Crie seu diretório de projeto .

A partir do seu shell, execute o seguinte comando para criar um novo projeto Django denominado django_qe com base em um modelo personalizado:

django-admin startproject django_qe --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip

Este comando cria um diretório de projeto django_qe e adiciona o andaime do arquivo inicial.

3

Crie seus arquivos de aplicação .

A partir do seu diretório django_qe, execute o seguinte comando para criar um aplicação denominado medical_records:

python manage.py startapp medical_records

Este comando cria um diretório de aplicação medical_records em seu projeto e adiciona arquivos de aplicativo padrão, incluindo arquivos para seus modelos e configurações.

4

Inclua seu aplicativo em seu projeto.

Navegue até o arquivo settings.py no seu diretório django_qe e edite sua configuração do INSTALLED_APPS para se assemelhar ao seguinte código:

INSTALLED_APPS = [
    'medical_records.apps.MedicalRecordsConfig',
    'django_qe.apps.MongoAdminConfig',
    'django_qe.apps.MongoAuthConfig',
    'django_qe.apps.MongoContentTypesConfig',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django_mongodb_backend',
]

Esta configuração garante que seu aplicativo medical_records esteja habilitado em seu projeto.

Conectar e habilitar criptografia

Após configurar seu projeto, siga as etapas nesta seção para se conectar ao MongoDB e criar modelos que armazenam dados criptografados.

1

Conecte-se ao MongoDB.

No diretório django_qe, navegue até o arquivo settings.py. Substitua a configuração DATABASES pelo seguinte código:

DATABASES = {
    'default': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': '<connection string>',
        'NAME': 'db',
    },
}

Substitua o espaço reservado <connection string> pela string de conexão que se conecta ao seu cluster.

Este código configura seu aplicação Django para se conectar ao MongoDB e acessar um banco de dados denominado db por padrão. Esta configuração se aplica aos seus modelos não criptografados.

2

Configure a Queryable Encryption.

No seu arquivo settings.py, você pode especificar a chave do encrypted na sua configuração do DATABASES para habilitar a Queryable Encryption e configurar seu fornecedor de Sistema de Gerenciamento de Chaves (KMS). O Django MongoDB Backend oferece suporte aos provedores AWS, Azure, GCP, KMIP e KMS locais.

Aviso

Armazenamento local da chave mestra do cliente

Se você armazenar sua chave mestra do cliente (CMK) localmente, não use este aplicação em produção. Sem um KMS remoto, você corre o risco de acesso não autorizado à chave de criptografia ou de perda da chave necessária para descriptografar seus dados.

Dica

Sistemas de gerenciamento de chaves

Para saber mais sobre o KMS, veja o verbete Key Management na Wikipedia.

Selecione a guia correspondente ao seu KMS e modifique sua configuração DATABASES para se assemelhar ao exemplo a seguir :

DATABASES = {
    'default': {
        # ... Your default configuration
    },
    'encrypted': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': '<connection string>',
        'NAME': 'medical_records',
        # ...
        'OPTIONS': {
            'auto_encryption_opts': AutoEncryptionOpts(
                key_vault_namespace='medical_records.__keyVault',
                kms_providers={
                    'local': {
                        # Generated by os.urandom(96)
                        'key': (
                            b'-\xc3\x0c\xe3\x93\xc3\x8b\xc0\xf8\x12\xc5#b'
                            b'\x19\xf3\xbc\xccR\xc8\xedI\xda\\ \xfb\x9cB'
                            b'\x7f\xab5\xe7\xb5\xc9x\xb8\xd4d\xba\xdc\x9c'
                            b'\x9a\xdb9J]\xe6\xce\x104p\x079q.=\xeb\x9dK*'
                            b'\x97\xea\xf8\x1e\xc3\xd49K\x18\x81\xc3\x1a"'
                            b'\xdc\x00U\xc4u"X\xe7xy\xa5\xb2\x0e\xbc\xd6+-'
                            b'\x80\x03\xef\xc2\xc4\x9bU'
                        )
                    },
                },
                crypt_shared_lib_path='<Automatic Encryption Shared Library path>',
                crypt_shared_lib_required=True,
            )
        },
    },
}

Substitua os seguintes valores de espaço reservado:

  • <connection string>: A mesma string de conexão que você especificou na chave default

  • <Automatic Encryption Shared Library path>: O caminho completo para sua Biblioteca compartilhada de criptografia automática

DATABASES = {
    'default': {
        # ... Your default configuration
    },
    'encrypted': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': '<connection string>',
        'NAME': 'medical_records',
        # ...
        'OPTIONS': {
            'auto_encryption_opts': AutoEncryptionOpts(
                key_vault_namespace='medical_records.__keyVault',
                kms_providers={
                    'aws': {
                        'accessKeyId': '<AWS Access Key ID>',
                        'secretAccessKey': '<AWS Secret Access Key>',
                    },
                },
                crypt_shared_lib_path='<Automatic Encryption Shared Library path>',
                crypt_shared_lib_required=True,
            )
        },
        'KMS_CREDENTIALS': {
            'aws': {
                'key': '<AWS Key ARN>', 
                'region': '<AWS Key Region>', 
            },
        },
    },
}

Substitua os seguintes valores de espaço reservado:

  • <connection string>: A mesma string de conexão que você especificou na chave default

  • <AWS Access Key ID>: IDda chave de acesso do Amazon Web Services

  • <AWS Secret Access Key>: Sua chave de acesso secreto Amazon Web Services

  • <Automatic Encryption Shared Library path>: O caminho completo para sua Biblioteca compartilhada de criptografia automática

  • <AWS Key ARN>: O nome do recurso da Amazon para o cliente AWS .

  • <AWS Key Region>: Sua região do AWS, como 'us-east-1'

DATABASES = {
    'default': {
        # ... Your default configuration
    },
    'encrypted': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': '<connection string>',
        'NAME': 'medical_records',
        # ...
        'OPTIONS': {
            'auto_encryption_opts': AutoEncryptionOpts(
                key_vault_namespace='medical_records.__keyVault',
                kms_providers={
                    'azure': {
                        'tenantId': '<Azure Tenant ID>',
                        'clientId': '<Azure Client ID>',
                        'clientSecret': '<Azure Client Secret>',
                    },
                },
                crypt_shared_lib_path='<Automatic Encryption Shared Library path>',
                crypt_shared_lib_required=True,
            )
        },
        'KMS_CREDENTIALS': {
            'azure': {
                'keyVaultEndpoint': '<Azure Key Vault Endpoint>',
                'keyName': '<Azure Key Name>',
                # Optional: 'keyVersion': '<Azure Key Version>',
            },
        },
    },
}

Substitua os seguintes valores de espaço reservado:

  • <connection string>: A mesma string de conexão que você especificou na chave default

  • <Azure Tenant ID>: Seu ID de locatário do Azure Active Directory

  • <Azure Client ID>: Seu ID de cliente do aplicação Azure

  • <Azure Client Secret>: Seu segredo do cliente do aplicação Azure

  • <Automatic Encryption Shared Library path>: O caminho completo para sua Biblioteca compartilhada de criptografia automática

  • <Azure Key Vault Endpoint>: Seu URL de ponto de extremidade do Azure Key Vault .

  • <Azure Key Name>: o nome da sua chave no Azure Key Vault

  • <Azure Key Version>: (Opcional) A versão da chave para usar

DATABASES = {
    'default': {
        # ... Your default configuration
    },
    'encrypted': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': '<connection string>',
        'NAME': 'medical_records',
        # ...
        'OPTIONS': {
            'auto_encryption_opts': AutoEncryptionOpts(
                key_vault_namespace='medical_records.__keyVault',
                kms_providers={
                    'gcp': {
                        'email': '<GCP Service Account Email>',
                        'privateKey': '<GCP Service Account Private Key>',
                    },
                },
                crypt_shared_lib_path='<Automatic Encryption Shared Library path>',
                crypt_shared_lib_required=True,
            )
        },
        'KMS_CREDENTIALS': {
            'gcp': {
                'projectId': '<GCP Project ID>',
                'location': '<GCP Key Ring Location>',
                'keyRing': '<GCP Key Ring Name>',
                'keyName': '<GCP Key Name>',
            },
        },
    },
}

Substitua os seguintes valores de espaço reservado:

  • <connection string>: A mesma string de conexão que você especificou na chave default

  • <GCP Service Account Email>: O e-mail da sua conta de serviço do Google Cloud

  • <GCP Service Account Private Key>: Chave privada da sua conta de serviço do Google Cloud

  • <Automatic Encryption Shared Library path>: O caminho completo para sua Biblioteca compartilhada de criptografia automática

  • <GCP Project ID>: Seu ID do projeto no Google Cloud

  • <GCP Key Ring Location>: A localização do seu chaveiro, como 'global'

  • <GCP Key Ring Name>: O nome do seu chaveiro

  • <GCP Key Name>: O nome da sua chave

DATABASES = {
    'default': {
        # ... Your default configuration
    },
    'encrypted': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': '<connection string>',
        'NAME': 'medical_records',
        # ...
        'OPTIONS': {
            'auto_encryption_opts': AutoEncryptionOpts(
                key_vault_namespace='medical_records.__keyVault',
                kms_providers={
                    'kmip': {
                        'endpoint': '<KMIP Server Endpoint>',
                    },
                },
                crypt_shared_lib_path='<Automatic Encryption Shared Library path>',
                crypt_shared_lib_required=True,
            )
        },
        'KMS_CREDENTIALS': {
            'kmip': {
                # Optional: 'keyId': '<KMIP Key Identifier>',
            },
        },
    },
}

Substitua os seguintes valores de espaço reservado:

  • <connection string>: A mesma string de conexão que você especificou na chave default.

  • <KMIP Server Endpoint>: o endpoint do servidor KMIP com a porta, como 'example.com:443'.

  • <Automatic Encryption Shared Library path>: O caminho completo para sua Biblioteca compartilhada de criptografia automática.

  • <KMIP Key Identifier>: (Opcional) O identificador exclusivo KMIP para um objeto gerenciado de dados secretos KMIP de 96bytes. Se você omitir esse valor, o Django MongoDB Backend criará um objeto aleatório de 96bytes.

Este código se conecta ao banco de dados medical_records criptografado , armazena suas chaves de dados na coleção medical_records.__keyVault e configura seu provedor de KMS.

3

Direcionar operações para o banco de dados criptografado.

No seu diretório medical_records, crie um arquivo denominado routers.py e cole o seguinte código nele:

class EncryptedRouter:
    def allow_migrate(self, db, app_label, model_name=None, **hints):
        # Create medical_records models only in the encrypted database.
        if app_label == "medical_records":
            return db == "encrypted"
        # Don't create collections for other apps in the encrypted db.
        if db == "encrypted":
            return False
        return None
    def db_for_read(self, model, **hints):
        # All reads and writes for medical_records models go to the encrypted db.
        if model._meta.app_label == "medical_records":
            return "encrypted"
        return None
    db_for_write = db_for_read

Este arquivo roteia as operações de banco de dados em todos os modelos em seu aplicação medical_records para o banco de dados medical_records criptografado.

Em seguida, adicione seu roteador personalizado navegando até seu arquivo settings.py e substituindo a configuração DATABASE_ROUTERS pelo seguinte código:

DATABASE_ROUTERS = [
    'django_mongodb_backend.routers.MongoRouter',
    'medical_records.routers.EncryptedRouter',
]
4

Crie modelos que armazenam campos criptografados.

No seu diretório medical_records, navegue até o arquivo models.py e cole o seguinte código:

from django.db import models
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.fields import (
    EmbeddedModelField,
    EncryptedCharField,
    EncryptedEmbeddedModelField,
)
class Patient(models.Model):
    patient_name = models.CharField(max_length=255)
    patient_id = models.BigIntegerField()
    patient_record = EmbeddedModelField("PatientRecord")
    class Meta:
        db_table = "patients"
    def __str__(self):
        return f"{self.patient_name} ({self.patient_id})"
class PatientRecord(EmbeddedModel):
    ssn = EncryptedCharField(max_length=11, queries={"queryType": "equality"})
    billing = EncryptedEmbeddedModelField("Billing")
    bill_amount = models.DecimalField(max_digits=10, decimal_places=2)
class Billing(EmbeddedModel):
    cc_type = models.CharField(max_length=50)
    cc_number = models.CharField(max_length=20)

Este código cria um modelo Patient, que corresponde à coleção patients no seu banco de dados medical_records. Ele também cria dois modelos embarcados, PatientRecord e Billing, para representar campos aninhados na collection.

O código configura os seguintes campos criptografados:

  • patient_record.ssn: criptografado e configurado para queries de igualdade

  • patient_record.billing.cc_type: criptografado, mas não consultável

  • patient_record.billing.cc_number: criptografado, mas não consultável

Realizar operações criptografadas

Depois de configurar o aplicação e a conexão do banco de dados , siga as etapas nesta seção para inserir e consultar documentos criptografados.

1

Execute migrações no banco de dados criptografado .

Execute os seguintes comandos a partir do seu diretório django_qe para criar migrações para seus modelos e aplicá-las ao banco de dados:

python manage.py makemigrations medical_records
python manage.py migrate --database encrypted
2

Inicie uma concha Python.

Execute o seguinte comando para entrar na shell Python:

python manage.py shell

Em seguida, execute o seguinte comando no shell para importar os modelos necessários:

from medical_records.models import Patient, PatientRecord, Billing
3

Insira dados criptografados.

A partir da sua shell, execute os seguintes comandos para criar uma instância do Patient e inserir um documento criptografado correspondente no banco de dados:

billing = Billing(cc_type="Visa", cc_number="4111111111111111")
record = PatientRecord(ssn="987-65-4320", billing=billing, bill_amount=1500)
patient = Patient.objects.create(
   name="John Doe",
   patient_id=12345678,
   patient_record=record
)

Se você navegar até sua medical_records.patients coleção no MongoDB Atlas, poderá ver que os campos e do documento patient_record.ssn patient_record.billing estão criptografados.

4

Consultar dados criptografados.

Execute o seguinte comando para executar uma query de igualdade no campo patient_record.ssn criptografado :

Patient.objects.get(patient_record__ssn="987-65-4320")

Se bem-sucedido, o comando retorna os seguintes dados do pai:

<Patient: John Doe (12345678)>

Próximos passos

Parabéns por concluir o tutorial Queryable Encryption ! Agora você tem um aplicação Django de amostra que usa o Queryable Encryption para criptografar e descriptografar automaticamente os campos do documento . Seu aplicação criptografa dados confidenciais no lado do servidor e consulta os dados no lado do cliente .

Para saber mais sobre Queryable Encryption e Django MongoDB Backend, visite os seguintes recursos:

Voltar

Transações

Próximo

Migrar aplicativos Djogo

Nesta página