Este documento explica como usar certificados de e-mail S/MIME com a API Gmail.
A API Gmail oferece acesso programático para gerenciar certificados de e-mail S/MIME de usuários em um domínio do Google Workspace.
Um administrador precisa ativar o S/MIME hospedado para o domínio para que os certificados funcionem.
O padrão S/MIME oferece uma especificação para criptografia de chave pública e assinatura de dados MIME. Quando você configura certificados S/MIME para uma conta de usuário, o Gmail os usa das seguintes maneiras:
Assinar e-mails enviados com o certificado do usuário e a chave privada.
Descriptografar e-mails recebidos com a chave privada do usuário.
Criptografe o e-mail de saída com o certificado e a chave pública do destinatário.
Verifique o e-mail recebido com o certificado do remetente e a chave pública.
É possível gerar certificados S/MIME individuais e fazer upload deles usando a API Gmail. Cada certificado S/MIME é para um alias específico de uma conta de e-mail de usuário. Os aliases incluem o endereço de e-mail principal e os endereços personalizados de envio como. A API marca um único certificado S/MIME como padrão para cada alias.
Para mais informações sobre aliases, consulte Gerenciar aliases e assinaturas com a API Gmail.
Autorizar o acesso à API
Para autorizar o acesso à API Gmail, use um dos seguintes métodos:
Use uma conta de serviço com delegação de autoridade em todo o domínio. Para uma explicação desses termos, consulte Saiba mais sobre autenticação e autorização. Para ativar essa opção, consulte Criar credenciais de acesso.
Use um fluxo do OAuth 2.0 padrão que exige o consentimento do usuário para receber um token de acesso do OAuth 2.0. Para mais informações, consulte Saiba mais sobre autenticação e autorização.
Para usar essa opção, o administrador do domínio precisa marcar a caixa de seleção Ativar a criptografia S/MIME para enviar e receber e-mails no Google Admin Console. Para mais informações, consulte Ativar o S/MIME hospedado no Admin Console.
Escopos de autorização
A API Gmail usa os mesmos escopos do OAuth que os métodos Gmail sendAs:
gmail.settings.basic: obrigatório para atualizar o S/MIMESendAsprincipal.gmail.settings.sharing: necessário para atualizar o S/MIME de personalizado.
Configurar chaves S/MIME
O recurso
settings.sendAs.smimeInfo
oferece vários métodos para gerenciar certificados S/MIME. Cada certificado está associado a um alias de envio como de um usuário.
Para determinar os aliases de envio como de um usuário, use o método
settings.sendAs.list
no recurso
settings.sendAs.
Fazer upload de uma chave S/MIME
Use o método
settings.sendAs.smimeInfo.insert
no recurso settings.sendAs.smimeInfo para fazer upload de uma nova chave S/MIME
para um alias pertencente a um usuário. Identifique o alias de destino usando os seguintes parâmetros de caminho:
userId: o endereço de e-mail do usuário. Use o valor especialmepara indicar o usuário autenticado.sendAsEmail: o alias para o qual você está enviando a chave. Esse endereço de e-mail aparece no cabeçalhoFrom:das mensagens enviadas usando esse alias.
Forneça o certificado S/MIME e a chave privada no campo
pkcs12
no formato PKCS #12. Não defina outros campos na solicitação. O campo
pkcs12 contém a chave S/MIME do usuário e a cadeia de
certificados de assinatura. A API realiza validações padrão nesse campo antes de aceitá-lo, verificando o seguinte:
- O assunto corresponde ao endereço de e-mail especificado.
- As expirações são válidas.
- A autoridade de certificação (CA) emissora está na lista de confiança do Google.
- Os certificados atendem às restrições técnicas do Gmail.
Se a chave estiver criptografada, forneça a senha no campo
encryptedKeyPassword. Uma chamada de método settings.sendAs.smimeInfo.insert bem-sucedida retorna o recurso settings.sendAs.smimeInfo id usado para se referir à chave no futuro.
Listar as chaves S/MIME de um usuário
Use o método
settings.sendAs.smimeInfo.list
no recurso settings.sendAs.smimeInfo para retornar a lista de chaves
S/MIME do usuário e do alias especificados. Identifique o alias de destino usando os seguintes parâmetros de caminho:
userId: o endereço de e-mail do usuário. Use o valor especialmepara indicar o usuário autenticado.sendAsEmail: o alias para listar as chaves. Esse endereço de e-mail aparece no cabeçalhoFrom:das mensagens enviadas com esse alias.
Recuperar as chaves S/MIME de um alias
Use o método
settings.sendAs.smimeInfo.get
no recurso settings.sendAs.smimeInfo para retornar as chaves S/MIME
específicas de um alias "Enviar como" de um usuário. Identifique o alias de destino usando os seguintes parâmetros de caminho:
userId: o endereço de e-mail do usuário. Use o valor especialmepara indicar o usuário autenticado.sendAsEmail: o alias para o qual você está recuperando as chaves. Esse endereço de e-mail aparece no cabeçalhoFrom:das mensagens enviadas usando esse alias.
Excluir uma chave S/MIME
Use o método
settings.sendAs.smimeInfo.delete
no recurso settings.sendAs.smimeInfo para excluir a chave
S/MIME especificada de um alias. Identifique o alias de destino usando os seguintes parâmetros de caminho:
userId: o endereço de e-mail do usuário. Use o valor especialmepara indicar o usuário autenticado.sendAsEmail: o alias de onde você está excluindo a chave. Esse endereço de e-mail aparece no cabeçalhoFrom:das mensagens enviadas usando esse alias.id: o ID imutável dosmimeInfo.
Uma chave excluída não fica mais visível nem pode ser usada. Não é possível descriptografar e-mails S/MIME recebidos que foram criptografados usando a chave pública correspondente. Antes de excluir uma chave, revogue-a com a autoridade emissora (CA).
Definir a chave S/MIME padrão para um alias
Use o método
settings.sendAs.smimeInfo.setDefault
no recurso settings.sendAs.smimeInfo para marcar a chave S/MIME
especificada como padrão para o alias especificado. Identifique o alias de destino usando os seguintes parâmetros de caminho:
userId: o endereço de e-mail do usuário. Use o valor especialmepara indicar o usuário autenticado.sendAsEmail: o alias para definir a chave padrão. Esse endereço de e-mail aparece no cabeçalhoFrom:das mensagens enviadas usando esse alias.id: o ID imutável dosmimeInfo.
Apenas uma chave S/MIME é o padrão para um alias de envio como de um usuário. Chamar o método
settings.sendAs.smimeInfo.setDefault cancela o padrão anterior.
Quando um usuário recebe mensagens S/MIME assinadas com uma determinada chave, o Gmail associa a chave à data de validade not_before mais distante no futuro como padrão ao criptografar e-mails enviados ao usuário associado. Para garantir que os usuários do Gmail com quem o usuário já se comunicou usem a nova chave padrão, verifique se a nova chave padrão tem uma data not_before posterior à chave padrão anterior ou revogue a chave padrão anterior.
Amostras de código
Os exemplos de código a seguir mostram como usar a API Gmail para gerenciar certificados S/MIME de uma organização com vários usuários:
Criar um recurso smimeInfo para um certificado S/MIME
Este exemplo de código mostra como ler um certificado de um arquivo, codificá-lo em uma
string Base64URL e atribuí-lo ao campo
pkcs12
no recurso settings.sendAs.smimeInfo:
Java
Python
Fazer upload de um certificado S/MIME
Para fazer upload de um certificado, chame o método
settings.sendAs.smimeInfo.insert
e forneça o recurso settings.sendAs.smimeInfo no corpo da
solicitação:
Java
Python
Gerenciar certificados de vários usuários
Estes exemplos de código mostram como gerenciar certificados para vários usuários em uma organização em uma única chamada em lote:
Inserir certificados de um arquivo CSV
Confira a seguir um exemplo de arquivo CSV que lista IDs de usuários e o caminho para o certificado de cada usuário:
$ cat certificates.csv
user1@example.com,/path/to/user1_cert.p12,cert_password_1
user2@example.com,/path/to/user2_cert.p12,cert_password_2
user3@example.com,/path/to/user3_cert.p12,cert_password_3
Java
Use os exemplos
CreateSmimeInfo
e InsertSmimeInfo
para fazer upload dos certificados dos usuários especificados em um arquivo CSV:
Python
Use os exemplos
create_smime_info
e insert_smime_info
para fazer upload dos certificados dos usuários especificados em um arquivo CSV:
Gerenciamento de certificados
Este exemplo combina vários métodos do recurso settings.sendAs.smimeInfo
para mostrar como gerenciar certificados da sua organização. Ela lista os certificados do usuário. Se o certificado padrão estiver expirado ou não estiver definido, ele
vai fazer upload do certificado encontrado no arquivo especificado. Em seguida, ele define como padrão o certificado com a data de validade mais distante.
Em seguida, essa função processa um arquivo CSV, semelhante ao exemplo anterior Inserir certificados de um arquivo CSV.
Java
Python
Temas relacionados
- Gerenciar aliases e assinaturas com a API Gmail
- Escolher os escopos da API Gmail
- Ativar o S/MIME hospedado para criptografia de mensagens