Aller au contenu
Avanet

Automatiser S/MIME de Sophos Email avec l’API

Sophos Email

La Sophos Email Management API pilote tout le cycle de vie des certificats S/MIME. L’ordre sûr est le suivant : lire l’inventaire, créer ou importer exactement une AC interne du tenant, créer d’abord la configuration désactivée, provisionner les AC de confiance et les certificats externes, activer S/MIME, provisionner les certificats internes, puis tester le flux de messagerie. Cet article distingue délibérément l’AC interne du tenant, les AC externes de confiance, les certificats d’utilisateurs internes et les certificats de destinataires externes. Leurs chemins diffèrent et ces objets ne sont pas interchangeables.

Pour l’architecture, la policy et les tests dans l’interface, consultez le guide S/MIME avec interface graphique. L’introduction à Sophos Email Management API explique le contrat général ; OAuth2, la résolution du tenant et l’hôte régional sont traités dans le futur runbook authentification API et tenant routing.

Avertissement critique : DELETE /smime/config/{deleteToken} supprime tous les certificats S/MIME et toutes les clés privées du tenant et met smimeEnabled à false. Ce n’est ni une rotation de certificat ni un dépannage ordinaire. L’API ne documente aucun export de clé privée. Sans sources PKCS#12 autorisées conservées séparément, les clés et le déchiffrement des contenus historiques peuvent être perdus définitivement.

Prérequis et base de requête sûre

Réutilisez uniquement SOPHOS_ACCESS_TOKEN (bearer token temporaire), SOPHOS_TENANT_ID (UUID cible) et SOPHOS_API_HOST (hôte régional complet) déjà validés. La spécification contrôlée est Email Management API v1.4.0 ; vérifiez la version actuelle avant toute implémentation. Tous les chemins sont relatifs à /email/v1 et exigent Authorization: Bearer ***, X-Tenant-ID et, pour JSON, Content-Type: application/json :

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

N’inscrivez jamais token, deleteToken, mot de passe ou contenu PKCS#12, ni clé privée dans les arguments, le code, les logs ordinaires ou les tickets. Utilisez un coffre approuvé, des fichiers de mode 600 et nettoyez les temporaires. Remplacez ops@example.net et alice@example.net par des adresses autorisées.

Avant toute écriture, exécutez ces lectures et ne consignez que le statut HTTP, requestId/correlationId des erreurs et le résultat du schéma :

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

Un 404 sur les deux premières signifie que l’objet n’existe pas encore. Les listes renvoient items et pages ; encodez pages.nextKey pour l’URL dans pageFromKey jusqu’à l’absence de nextKey.

Provisionner l’AC interne du tenant

L’AC interne signe les certificats créés par Sophos pour les utilisateurs internes. Il y en a exactement une par tenant. Sa création ou son import crée si nécessaire une configuration S/MIME désactivée, sans activer S/MIME. Une seconde tentative renvoie 409 ; l’API vérifiée ne possède aucun chemin séparé permettant de supprimer ou remplacer seulement cette AC.

Option A : faire créer l’AC par Sophos

POST /smime/ca/internal exige organizationName, locality, country et email. country contient exactement deux majuscules ISO 3166-1. organizationUnit est facultatif, tout comme certExpiryDate (YYYY-MM-DD) ou certValidityPeriod (1 à 20 ans). La valeur par défaut est 20 ans ; si les deux sont fournis, la durée la plus courte s’applique.

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

Le succès correspond à 201. Conservez le fingerprint SHA-256 de 64 caractères, issuer, validFrom, expiresAt et origin, sans journaliser inutilement toute la réponse.

Option B : importer une AC et sa clé

POST /smime/ca/internal/certificate attend un bundle certificat-clé PKCS#12 encodé en Base64, pas du PEM :

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

Après encodage, pkcs12 doit compter 1200 à 24000 caractères et password 3 à 50. Le responsable PKI vérifie certificat, clé privée, chaîne, usage et mot de passe. Base64 n’assure aucune protection de la clé. Retirez les retours à la ligne et ne placez jamais du PEM dans pkcs12.

Dans les deux cas, vérifiez que GET /smime/ca/internal renvoie le même fingerprint, que GET /smime/ca/internal/certificate télécharge le certificat public PEM en application/octet-stream et que son empreinte correspond à l’inventaire. Ce PEM ne contient pas de clé privée récupérable.

N’activer la configuration du tenant qu’ensuite

GET /smime/config renvoie smimeEnabled, extractCertificate, jusqu’à cinq certExpiryNotificationEmailAddresses et le deleteToken de huit caractères, à traiter comme un secret destructif.

Si la configuration manque, créez-la avec POST /smime/config. smimeEnabled est obligatoire et extractCertificate vaut false par défaut :

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

Pour une configuration existante, utilisez PATCH /smime/config : au moins un champ, champs omis inchangés, null ou [] pour effacer toutes les adresses et déduplication automatique. Écrivez d’abord smimeEnabled: false, provisionnez et inventoriez les AC de confiance et certificats externes pilotes, puis seulement envoyez {"smimeEnabled":true}. Sans AC interne, l’API renvoie 409. Confirmez par GET, provisionnez les certificats internes pilotes et testez signature et chiffrement. extractCertificate: true autorise seulement l’extraction entrante ; les prérequis de vérification de signature dans la policy Secure Message du guide graphique restent applicables.

Gérer les AC externes de confiance

Elles servent à vérifier les messages signés ; ce ne sont ni l’AC interne ni des certificats d’utilisateur. Avant l’import, contrôlez dans Sophos Fusion (anciennement Sophos Central) si l’émetteur bénéficie déjà de la confiance globale et vérifiez son SHA-256 par un canal indépendant.

  • GET /smime/cas/external : filtres commonName, certValidBefore, certValidAfter, certExpiryBefore, certExpiryAfter, certFingerprint, issuerCN, pageFromKey, pageSize (défaut 50).
  • POST /smime/cas/external/certificate : texte PEM dans certificate, 300 à 32000 caractères, en-tête et pied compris.
  • GET /smime/cas/external/certificate/{fingerprint} : télécharge ce PEM exact.
  • DELETE /smime/cas/external?certFingerprint=... : supprime précisément cette confiance.
{
  "certificate": "-----BEGIN CERTIFICATE-----\n<BASE64_CERTIFICATE>\n-----END CERTIFICATE-----"
}

Un doublon renvoie 409. Avant DELETE, une lecture filtrée exacte doit retourner un seul objet attendu ; après 200 et deleted: true, le même filtre doit être vide. Testez ensuite une signature avec la chaîne restante.

Gérer les certificats des destinataires externes

Ce sont les certificats publics des partenaires ; ils ne contiennent aucune clé privée du tenant. POST /smime/users/external/certificate accepte le PEM dans certificate (300 à 32000 caractères), déduit l’identité du certificat et active S/MIME pour cet utilisateur :

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

Pour DSA/EC, confirmVerificationOnlyCert: true confirme l’usage volontaire limité à signature/vérification, sans chiffrement/déchiffrement. Une identité possède au plus deux certificats (422 au suivant) ; un doublon renvoie 409.

GET /smime/users/external?email=partner@example.net filtre l’adresse exacte et accepte aussi emailStartsWith, dates, empreinte, émetteur et pagination. GET /smime/users/external/certificate/{fingerprint} télécharge le PEM. DELETE /smime/users/external?email=...&certFingerprint=... supprime uniquement la paire exacte, paramètres encodés pour l’URL ; le dernier certificat retire implicitement l’utilisateur de la liste. Après import, vérifiez email, fingerprint, émetteur et validité, puis faites déchiffrer un message pilote par le partenaire prévu.

Créer ou importer les certificats internes

L’utilisateur doit exister comme identité correspondante du tenant. Create ou upload active S/MIME pour lui. Ne normalisez pas les adresses : réutilisez l’email exact renvoyé par GET.

Pour créer, envoyez POST /smime/users/internal :

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

Seul email est obligatoire. certExpiryDate/certValidityPeriod suit les mêmes règles de 1 à 20 ans que l’AC. L’AC interne et S/MIME configuré/activé sont requis.

Pour importer une clé, envoyez POST /smime/users/internal/certificate :

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

email, pkcs12 et password sont obligatoires, avec 1200–24000 caractères Base64 et 3–50 caractères de mot de passe. DSA/EC exige confirmSigningOnlyCert: true et ne permet alors que signature/vérification. Les AC du bundle sont aussi enregistrées comme AC de confiance : validez toute la chaîne et relisez /smime/cas/external. Deux certificats maximum par utilisateur ; doublon 409, troisième 422.

GET /smime/users/internal?email=alice@example.net renvoie l’utilisateur exact et ses certificats ; il accepte aussi userName, emailStartsWith, filtres date/empreinte/émetteur et pagination. GET /smime/users/internal/certificate/{fingerprint} télécharge le PEM avec les AC importées dans le bundle, mais sans clé privée. DELETE /smime/users/internal?email=...&certFingerprint=... supprime la paire exacte ; le dernier certificat retire l’utilisateur de la liste S/MIME. Après 201, vérifiez adresse, empreinte, émetteur et expiration, puis testez signature sortante et déchiffrement entrant.

Ne lancer la réinitialisation destructive que pour une reconstruction approuvée

Approbation obligatoire : l’AC interne, les AC de confiance, les certificats internes et externes et toutes les clés privées enregistrées sont supprimés ; smimeEnabled devient false. Cela ne répare pas un seul objet.

Avant l’action : (1) inventoriez toutes les pages de GET /smime/config, /smime/ca/internal, /smime/cas/external, /smime/users/internal et /smime/users/external ; (2) confirmez pour chaque clé récupérable une source PKCS#12 autorisée et un mot de passe testé—PEM n’est pas une sauvegarde de clé ; (3) documentez policy, fenêtre, owner, partenaires, interruption et ordre complet ; (4) prenez le deleteToken actuel directement dans GET ; (5) faites vérifier tenant, inventaire, conséquence et association du token par une seconde personne autorisée.

Alors seulement, appelez exactement DELETE /smime/config/{deleteToken}. Un mauvais token renvoie 409, une configuration absente 404. Après timeout, 5xx ou résultat inconnu, ne répétez pas à l’aveugle : relisez d’abord configuration et inventaires. Le succès exige 200 et deleted: true ; la configuration doit ensuite manquer ou être reconstruite avec smimeEnabled: false. Ordre de reconstruction : AC interne, configuration désactivée, confiance, utilisateurs, activation finale.

Validation et dépannage

Validez deux niveaux : état API, par GET exact avec email, SHA-256 de 64 hexadécimaux, issuer, validFrom, expiresAt, origin, fin de pagination et configuration ; et effet messagerie, en signant en sortie, vérifiant en entrée, chiffrant vers le pilote externe et déchiffrant pour l’interne sous une petite policy Secure Message. Consignez Message-ID, UTC et résultat, jamais clés ni payloads complets.

  • 400 : champs JSON, en-tête/pied PEM, Base64 sans retours, mot de passe PKCS#12, longueurs, date et email ; traitez chaque errors.
  • 401/403 : token, permission minimale et affectation tenant ; ne devinez pas la région.
  • 404 : hôte régional, chemin exact, paire email/empreinte et inventaire.
  • 409 : AC/certificat déjà présent, AC manquante à l’activation ou mauvais deleteToken ; lisez l’état avant de réécrire.
  • 422 : déjà deux certificats ; ne supprimez pas une empreinte inconnue.
  • Liste inattendue : parcourez pages.nextKey, encodez pageFromKey et utilisez le filtre exact.
  • Message en échec malgré GET correct : vérifiez activation, portée/ordre de policy, validité, identité, chaîne et usage ; terminez le test avec le guide graphique.

Pour l’escalade, méthode, chemin sans queries sensibles, statut HTTP, UTC, requestId/correlationId, tenant ID, type d’objet et métadonnées anonymisées suffisent. Excluez bearer token, deleteToken, mots de passe, PKCS#12, clés privées et listes personnelles complètes.