Saltar para o conteudo
Avanet

Automatizar S/MIME do Sophos Email através da API

Sophos Email

A Sophos Email Management API permite controlar todo o ciclo de vida dos certificados S/MIME. A sequência segura é: ler o inventário, criar ou carregar exatamente uma CA interna do tenant, criar inicialmente a configuração desativada, disponibilizar CAs fidedignas e certificados externos, ativar S/MIME, disponibilizar certificados internos e testar o fluxo de correio. Este artigo distingue deliberadamente a CA interna do tenant, as CAs externas fidedignas, os certificados de utilizadores internos e os certificados de destinatários externos. Utilizam caminhos diferentes e não são intercambiáveis.

Para arquitetura, policy e testes na interface, consulte o guia gráfico de S/MIME. A introdução à Sophos Email Management API explica o contrato geral; OAuth2, resolução do tenant e host regional são tratados no runbook planeado de autenticação da API e tenant routing.

Aviso crítico: DELETE /smime/config/{deleteToken} elimina todos os certificados S/MIME e todas as chaves privadas do tenant e define smimeEnabled como false. Não é rotação de certificado nem troubleshooting normal. A API não documenta exportação de chaves privadas. Sem fontes PKCS#12 autorizadas e guardadas separadamente, podem perder-se definitivamente chaves e a capacidade de desencriptar conteúdo histórico.

Pré-requisitos e base segura

Utilize apenas SOPHOS_ACCESS_TOKEN (bearer token temporário), SOPHOS_TENANT_ID (UUID alvo) e SOPHOS_API_HOST (host regional completo) previamente validados. A especificação revista é Email Management API v1.4.0; confirme a versão atual antes de implementar. Todos os caminhos são relativos a /email/v1 e requerem Authorization: Bearer ***, X-Tenant-ID e, para JSON, Content-Type: application/json:

EMAIL_API_HOST="${SOPHOS_API_HOST%/}/email/v1"

Não coloque token, deleteToken, palavra-passe ou conteúdo PKCS#12 nem chaves privadas em argumentos, código, logs ou tickets. Utilize um secret store aprovado, ficheiros com modo 600 e elimine temporários. Substitua ops@example.net e alice@example.net por endereços autorizados.

Antes de escrever, execute estes reads e registe apenas estado HTTP, requestId/correlationId de erros e resultado do esquema:

GET /smime/config
GET /smime/ca/internal
GET /smime/users/internal?pageSize=1

Um 404 nos dois primeiros indica objeto inexistente. As listas devolvem items e pages; passe pages.nextKey, codificado para URL, como pageFromKey até deixar de existir nextKey.

Disponibilizar a CA interna do tenant

A CA interna assina certificados gerados pela Sophos para utilizadores internos. Existe exatamente uma por tenant. Criar ou carregar cria, se necessário, uma configuração S/MIME desativada, mas não ativa S/MIME. Uma segunda tentativa devolve 409; a API revista não tem um caminho separado para eliminar ou substituir apenas esta CA.

Opção A: criar a CA na Sophos

POST /smime/ca/internal exige organizationName, locality, country e email. country contém exatamente duas maiúsculas ISO 3166-1. organizationUnit é opcional, bem como certExpiryDate (YYYY-MM-DD) ou certValidityPeriod (1–20 anos). O padrão é 20 anos; se ambos forem enviados, aplica-se o prazo menor.

{
  "organizationName": "Example Operations GmbH",
  "organizationUnit": "Messaging",
  "locality": "Zurich",
  "country": "CH",
  "email": "ops@example.net",
  "certValidityPeriod": 10
}

Sucesso é 201. Guarde fingerprint SHA-256 de 64 caracteres, issuer, validFrom, expiresAt e origin sem registar a resposta completa.

Opção B: carregar CA com chave

POST /smime/ca/internal/certificate espera um bundle certificado-chave PKCS#12 codificado em Base64, não PEM:

{
  "pkcs12": "<BASE64_PKCS12>",
  "password": "<PKCS12_PASSWORD>"
}

Após Base64, pkcs12 deve ter 1200–24000 caracteres e password, 3–50. O responsável PKI valida certificado, chave privada, cadeia, finalidade e palavra-passe. Base64 não protege a chave. Remova quebras de linha e nunca coloque PEM em pkcs12.

Nas duas opções, confirme: GET /smime/ca/internal devolve o mesmo fingerprint; GET /smime/ca/internal/certificate descarrega o certificado público PEM como application/octet-stream; o fingerprint corresponde ao inventário. O PEM não contém chave privada recuperável.

Ativar a configuração apenas depois

GET /smime/config devolve smimeEnabled, extractCertificate, até cinco certExpiryNotificationEmailAddresses e o deleteToken de oito caracteres, que deve ser tratado como segredo destrutivo.

Se faltar configuração, crie-a com POST /smime/config. smimeEnabled é obrigatório e extractCertificate tem valor padrão false:

{
  "smimeEnabled": false,
  "extractCertificate": false,
  "certExpiryNotificationEmailAddresses": ["ops@example.net"]
}

Para configuração existente use PATCH /smime/config: pelo menos um campo, campos omitidos inalterados, null ou [] apaga todos os endereços e duplicados são removidos. Escreva primeiro smimeEnabled: false, disponibilize e inventarie CAs fidedignas e certificados externos piloto e só depois envie {"smimeEnabled":true}. Sem CA interna, a API devolve 409. Confirme com GET, disponibilize os certificados internos piloto e teste assinatura e encriptação. extractCertificate: true só permite extração de mensagens recebidas; os pré-requisitos de verificação da assinatura na policy Secure Message do guia gráfico continuam necessários.

Gerir CAs externas fidedignas

Estas CAs verificam mensagens assinadas; não são a CA interna nem certificados de utilizador. Antes do upload, verifique no Sophos Fusion (anteriormente Sophos Central) se o emissor já é globalmente fidedigno e confirme SHA-256 por canal independente.

  • GET /smime/cas/external: filtros commonName, certValidBefore, certValidAfter, certExpiryBefore, certExpiryAfter, certFingerprint, issuerCN, pageFromKey, pageSize (padrão 50).
  • POST /smime/cas/external/certificate: PEM no campo certificate, 300–32000 caracteres incluindo cabeçalho e rodapé.
  • GET /smime/cas/external/certificate/{fingerprint}: descarrega esse PEM.
  • DELETE /smime/cas/external?certFingerprint=...: elimina exatamente essa confiança.
{
  "certificate": "-----BEGIN CERTIFICATE-----\n<BASE64_CERTIFICATE>\n-----END CERTIFICATE-----"
}

Um duplicado devolve 409. Antes de DELETE, um list read exato deve devolver uma única entrada esperada; depois de 200 e deleted: true, o filtro deve ficar vazio. Teste então uma assinatura com a cadeia restante.

Gerir certificados de destinatários externos

São certificados públicos de parceiros e não contêm chaves privadas do tenant. POST /smime/users/external/certificate recebe PEM em certificate (300–32000 caracteres), obtém a identidade do certificado e ativa S/MIME para esse utilizador:

{
  "certificate": "-----BEGIN CERTIFICATE-----\n<BASE64_CERTIFICATE>\n-----END CERTIFICATE-----",
  "confirmVerificationOnlyCert": false
}

Para DSA/EC, confirmVerificationOnlyCert: true confirma conscientemente a limitação a assinar/verificar, sem encriptar/desencriptar. Há no máximo dois certificados por identidade (422 no seguinte); um duplicado devolve 409.

GET /smime/users/external?email=partner@example.net filtra pelo endereço exato e também suporta emailStartsWith, datas, fingerprint, emissor e paginação. GET /smime/users/external/certificate/{fingerprint} descarrega PEM. DELETE /smime/users/external?email=...&certFingerprint=... elimina apenas o par exato, com parâmetros URL-encoded; o último certificado remove implicitamente o utilizador da lista. Após upload, confirme email, fingerprint, emissor e validade e faça o parceiro piloto desencriptar uma mensagem.

Criar ou carregar certificados internos

O utilizador deve existir como identidade correspondente do tenant. Create ou upload ativa S/MIME para ele. Não normalize endereços: reutilize o email exato do GET.

Para criar, use POST /smime/users/internal:

{
  "email": "alice@example.net",
  "certValidityPeriod": 3
}

Só email é obrigatório. certExpiryDate/certValidityPeriod segue as regras de 1–20 anos da CA. São necessárias a CA interna e S/MIME configurado/ativado.

Para carregar uma chave, use POST /smime/users/internal/certificate:

{
  "email": "alice@example.net",
  "pkcs12": "<BASE64_PKCS12>",
  "password": "<PKCS12_PASSWORD>",
  "confirmSigningOnlyCert": false
}

email, pkcs12 e password são obrigatórios, com 1200–24000 caracteres Base64 e 3–50 de palavra-passe. DSA/EC exige confirmSigningOnlyCert: true e fica limitado a assinatura/verificação. CAs no bundle são guardadas como CAs fidedignas: valide a cadeia e verifique /smime/cas/external. Máximo dois certificados por utilizador; duplicado 409, terceiro 422.

GET /smime/users/internal?email=alice@example.net devolve o utilizador e certificados exatos e aceita userName, emailStartsWith, filtros de data/fingerprint/emissor e paginação. GET /smime/users/internal/certificate/{fingerprint} descarrega PEM incluindo CAs carregadas no bundle, mas sem chave privada. DELETE /smime/users/internal?email=...&certFingerprint=... elimina o par exato; o último remove o utilizador da lista S/MIME. Após 201, confirme endereço, fingerprint, emissor e expiração e teste assinatura de saída e desencriptação de entrada.

Executar a reposição destrutiva apenas como reconstrução aprovada

Aprovação obrigatória: elimina CA interna, CAs fidedignas, certificados internos e externos e todas as chaves privadas guardadas; smimeEnabled passa a false. Não repara um objeto isolado.

Antes: (1) inventarie todas as páginas de GET /smime/config, /smime/ca/internal, /smime/cas/external, /smime/users/internal, /smime/users/external; (2) para cada chave recuperável confirme fonte PKCS#12 autorizada e palavra-passe testada—PEM não é backup de chave; (3) documente policy, janela, owner, parceiros, interrupção e ordem completa; (4) obtenha o deleteToken atual diretamente do GET; (5) peça a outra pessoa autorizada que confira tenant, inventário, consequência e associação do token.

Só então invoque exatamente DELETE /smime/config/{deleteToken}. Token errado devolve 409; configuração ausente, 404. Em caso de timeout, 5xx ou resultado desconhecido, não repita às cegas: releia primeiro configuração e inventários. Sucesso exige 200 e deleted: true; depois a configuração deve estar ausente ou ser reconstruída com smimeEnabled: false. Ordem: CA interna, configuração desativada, confiança, utilizadores e ativação final.

Validação e troubleshooting

Valide dois níveis: estado API, com GET exato de email, SHA-256 de 64 hexadecimais, issuer, validFrom, expiresAt, origin, fim da paginação e configuração; e efeito nas mensagens, assinando saída, verificando entrada, encriptando para o piloto externo e desencriptando para o interno sob pequena policy Secure Message. Registe Message-ID, UTC e resultado, nunca chaves ou payloads completos.

  • 400: campos JSON, cabeçalho/rodapé PEM, Base64 sem quebras, password PKCS#12, comprimentos, data e email; processe cada errors.
  • 401/403: token, permissão mínima e atribuição do tenant; não adivinhe região.
  • 404: host regional, caminho exato, par email/fingerprint e inventário.
  • 409: CA/certificado já existe, CA ausente ao ativar ou deleteToken errado; leia o estado antes de repetir.
  • 422: já existem dois certificados; não elimine fingerprint desconhecido.
  • Lista inesperada: percorra pages.nextKey, codifique pageFromKey e use filtro exato.
  • Mensagem falha apesar de GET correto: verifique ativação, scope/ordem da policy, validade, identidade, cadeia e key usage; conclua o teste com o guia gráfico.

Para escalamento bastam método, caminho sem queries sensíveis, HTTP, UTC, requestId/correlationId, tenant ID, tipo de objeto e metadados anonimizados. Exclua bearer token, deleteToken, palavras-passe, PKCS#12, chaves privadas e listas pessoais completas.