A API no modo sandbox (SAPI, na sigla em inglês) é baseada no projeto Sandbox2, que já está bem estabelecido. Esta página explica a arquitetura de design da SAPI e os principais conceitos.
Visão geral
A SAPI foi projetada para fornecer aos desenvolvedores ferramentas para preparar bibliotecas C/C++ para sandbox, bem como as APIs necessárias para comunicação com a versão em sandbox das bibliotecas C/C++.
Este diagrama mostra a arquitetura de uma biblioteca C/C++ em sandbox da SAPI:
A SAPI também fornece primitivos para sincronização de memória manual e automática (com base em atributos de ponteiro personalizados) (matrizes, estruturas) entre as bibliotecas da SAPI e o código do host.
Por fim, uma API Transactions de alto nível permite monitorar e reiniciar as bibliotecas SAPI se elas falharem (por exemplo, devido a violações de segurança, falhas ou esgotamento de recursos).
Sandbox2
O projeto de código aberto Sandbox2 é desenvolvido e mantido por engenheiros de segurança do Google e é a principal tecnologia de isolamento em sandbox usada pela SAPI. O Sandbox2 contém três componentes principais: a política de sandbox, o executor e o Sandboxee.
Política de sandbox
A política de sandbox define o ambiente de execução restrito para a biblioteca em sandbox. Isso é feito esclarecendo quais syscalls podem ser executados. A SAPI usa o mesmo mecanismo do Sandbox2. Consulte a seção "Política de sandbox" e a página "Como começar" do Sandbox2 para mais informações sobre como criar e definir uma política de sandbox.
A SAPI usa uma política padrão. Se preferir, use uma política de sandbox dedicada definindo-a em um arquivo de cabeçalho sandbox.h e transmitindo-a como um argumento na regra de build sapi_library.
Biblioteca em sandbox
Essa é a biblioteca C/C++ em sandbox que será executada no ambiente de sandbox restrito fornecido pelo Sandbox2. Por fim, a biblioteca em sandbox expõe a funcionalidade necessária que pode ser consumida pelo código do host.
A biblioteca em sandbox é criada com a regra de build sapi_library, em que é possível especificar uma política de sandbox personalizada que define o ambiente de execução restrito. Dependendo da biblioteca, talvez seja necessário escrever um wrapper ou um código de stub (consulte libcurl), mas não é necessário mudar o código-fonte da biblioteca C/C++ ao preparar a versão da SAPI.
Objeto SAPI e stub RPC
O objeto SAPI é um objeto C++ que expõe a API da biblioteca em sandbox. Ele encaminha chamadas do código do host para o stub RPC, que está incorporado à biblioteca SAPI junto com a biblioteca em sandbox.
Esses dois elementos são gerados automaticamente pelo sistema de build usando a regra de build sapi_library(). A SAPI é compatível com dois sistemas de build: o Bazel e o CMake do Google.
Código do host
O código do host implementa a lógica fornecida pela biblioteca SAPI. É o que consumiria a versão sem sandbox da biblioteca C/C++. Assim, o código do host chama funções exportadas pela biblioteca SAPI, transmitindo e recebendo dados do sandbox.
O código do host precisa ser adaptado para usar a biblioteca SAPI. Principalmente, não é possível chamar as funções da biblioteca porque ela fica em um processo isolado separado. Portanto, a SAPI oferece ferramentas que criam um objeto SAPI que faz proxy de chamadas para uma biblioteca SAPI.
Conceitos
Regras de build do Bazel
O projeto SAPI oferece duas regras de build do Bazel para criar um sandbox de uma biblioteca C/C++:
sapi_library(): cria todas as saídas necessárias para ter a biblioteca C/C++ em sandbox como um Sandboxee do Sandbox2. A saída da build pode ser usada como uma dependência para a regracc_binary()usada para criar o binário do código do host.sapi_interface(): gera automaticamente o cabeçalho que pode ser incluído no binário de código do host.
Para uma explicação mais completa das regras de build, consulte Regras de build.
Variáveis
A SAPI oferece vários tipos especiais, chamados de tipos de SAPI, que recomendamos usar no código do host. O principal motivo para a necessidade dos tipos de SAPI é o processo e, portanto, o isolamento de memória entre o código do host e a biblioteca em sandbox.
Para uma explicação mais completa sobre esse assunto e uma visão geral de alguns tipos de SAPI usados com frequência, consulte Variáveis.
Transações
Como explicado acima, qualquer chamada de API para uma biblioteca em sandbox é transmitida por uma camada RPC. Para processar uma falha nessa camada, é necessário implementar o tratamento de erros adequado. O módulo SAPI Transaction fornece o mecanismo necessário para garantir que todas as chamadas a uma biblioteca em sandbox sejam concluídas sem problemas no nível de RPC ou sejam retornadas com um erro relevante.
Para uma explicação mais completa sobre esse tópico, consulte Transações.
Primeiros passos
Leia a página Como começar para configurar seu primeiro projeto de API em sandbox.