Codelab do SDK de criptografia de comandos

1. Visão geral

Este codelab orienta você no uso do SDK de criptografia de comandos para se comunicar com segurança com um modelo disponibilizado em um ambiente de execução confiável (TEE) no Google Cloud.

O que você vai aprender

  • Como estabelecer um canal criptograficamente verificado e criptografado entre um cliente e um servidor de inferência remota.
  • Como verificar a identidade do servidor (hash de software, modelo de hardware, configuração de inicialização) usando o TLS atestado.
  • Garantindo a soberania de dados mantendo os comandos criptografados até que cheguem ao enclave verificado.
  • Como usar o SDK de criptografia de comandos para interagir com o vLLM em execução no Confidential Space.

O que é necessário

  • um projeto do Google Cloud com faturamento ativado
  • SDK Google Cloud (gcloud) instalado e autenticado.
  • ambiente Python 3.10 ou mais recente
  • um token do Hugging Face para fazer o download de modelos Gemma
  • familiaridade com firewalls de VPC e cota de endereço IP externo
  • A criação do SDK localmente exige a compilação da extensão C _ekm.c. Essa etapa falha se os cabeçalhos C do Python não estiverem instalados. Instale o python3-dev para resolver esse problema (por exemplo, sudo apt-get install python3-dev para Debian/Ubuntu).

2. Como configurar recursos do Cloud

Antes de começar, ative as APIs necessárias e configure seu ambiente.

1. Ativar as APIs necessárias:

gcloud services enable compute.googleapis.com \
    confidentialcomputing.googleapis.com \
    logging.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

2. Configurar Docker:

gcloud auth configure-docker gcr.io

3. Definir o token do Hugging Face:

export HF_TOKEN="your_token"

4. Clonar o repositório:

git clone https://github.com/google/prompt-encryption-sdk && cd prompt-encryption-sdk

3. Cenário

Vamos usar:

  • Cliente:seu ambiente Python local ou uma VM padrão.
  • Servidor:uma instância do vLLM que disponibiliza um modelo de código aberto (por exemplo, Gemma) dentro de um Confidential Space (TDX/SEV-SNP).
  • SDK:a biblioteca Python prompt_encryption_sdk.

4. Etapa 0: configuração do servidor

Antes que o cliente possa verificar qualquer coisa, precisamos de um servidor em execução no Confidential Space. Um script bash fornecido processa o provisionamento.

./codelabs/setup.sh --project-id <PROJECT_ID>

O script setup.sh faz o seguinte:

  1. Ativa as APIs necessárias (Compute, Computação confidencial, Geração de registros, Artifact Registry, Cloud Build).
  2. Cria e envia a imagem Docker (encapsulando o vLLM com o middleware TLS atestado).
  3. Provisiona uma conta de serviço com as permissões necessárias.
  4. Cria a VM confidencial (instância A3 com GPU H100 e TDX ativado).
  5. Configura a rede e o balanceamento de carga (balanceador de carga de rede de passagem).
  6. Salva as saídas (hash de imagem e IP do balanceador de carga) em arquivos locais.

5. Etapa 1: executar o cliente atestado

Agora que o servidor está em execução com segurança, estabeleça uma conexão atestada.

python3 -m venv venv
source venv/bin/activate
pip install -r examples/requirements.txt
pip install -e .
./codelabs/run_client.sh <PROJECT_ID>

O script run_client.sh lê os detalhes da implantação e executa uma solicitação do Python usando o ConfidentialSDKClient. Se a atestação falhar, uma AttestationError será gerada e o comando nunca será enviado.

6. Etapa 2: limpeza

Para evitar cobranças, limpe os recursos quando terminar.

./codelabs/cleanup.sh --project-id <PROJECT_ID>

7. Configurações avançadas

O que acontece durante http.post?

  1. TCP/TLS:conexão padrão estabelecida.
  2. Interceptação de handshake:o SDK pausa antes de enviar o corpo.
  3. RPC AttestConnection:o SDK envia um nonce ao servidor.
  4. Geração de cotação:o servidor solicita uma cotação de hardware TEE.
  5. Validação:o SDK verifica a assinatura e a política da cotação.
  6. Vincular: o SDK verifica se o "material de chave exportado" do canal corresponde à sessão vinculada na cotação.
  7. Transmissão de dados:o corpo é enviado somente se todas as verificações forem aprovadas.

8. Solução de problemas

  • Falha na atestação:verifique se o image_hash na política corresponde ao contêiner.
  • Conexão recusada:verifique se o servidor está acessível e se a porta 8000 está aberta.
  • Tempo limite:a geração de cotações de TEE pode levar tempo. Verifique se os tempos limite são suficientes.

9. Parabéns

Você concluiu o codelab do SDK de criptografia de comandos. Você aprendeu a estabelecer um canal criptograficamente verificado e criptografado entre o cliente e um servidor de inferência baseado em TEE.

A seguir

  • Confira as configurações avançadas de AttestationPolicy.
  • Integre o SDK aos aplicativos de produção atuais.
  • Saiba mais sobre o Confidential Space e os modelos de hardware TEE.

Leitura adicional