Naar de inhoud
Avanet

Sophos Email S/MIME automatiseren via de API

Sophos Email

Met de Sophos Email Management API beheert u de volledige levenscyclus van S/MIME-certificaten. De veilige volgorde is: inventaris lezen, exact één interne tenant-CA maken of uploaden, de tenantconfiguratie eerst uitgeschakeld aanmaken, vertrouwde CA’s en externe certificaten plaatsen, S/MIME inschakelen, interne certificaten plaatsen en daarna de mailflow testen. Dit artikel houdt de interne tenant-CA, vertrouwde externe CA’s, interne gebruikerscertificaten en certificaten van externe ontvangers bewust uit elkaar. Ze gebruiken andere paden en zijn niet uitwisselbaar.

Zie voor architectuur, policy en UI-tests de S/MIME GUI-handleiding. De inleiding tot Sophos Email Management API beschrijft het algemene contract; OAuth2, tenantbepaling en regionale host staan in het geplande runbook over API-authenticatie en tenant routing.

Kritieke waarschuwing: DELETE /smime/config/{deleteToken} verwijdert alle S/MIME-certificaten en privésleutels van de tenant en zet smimeEnabled op false. Dit is geen certificaatrotatie of normale probleemoplossing. De API documenteert geen export van privésleutels. Zonder apart bewaarde, geautoriseerde PKCS#12-bronnen kunnen sleutels en de mogelijkheid historische inhoud te ontsleutelen definitief verloren gaan.

Vereisten en veilige requestbasis

Gebruik alleen de reeds gevalideerde SOPHOS_ACCESS_TOKEN (tijdelijk bearer token), SOPHOS_TENANT_ID (UUID van de doeltenant) en SOPHOS_API_HOST (volledige regionale host). De gecontroleerde specificatie is Email Management API v1.4.0; controleer vóór implementatie de actuele versie. Alle paden zijn relatief aan /email/v1 en vereisen Authorization: Bearer ***, X-Tenant-ID en voor JSON Content-Type: application/json:

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

Plaats tokens, deleteToken, PKCS#12-wachtwoorden of -inhoud en privésleutels niet in argumenten, code, gewone logs of tickets. Gebruik een goedgekeurde secret store, bestanden met modus 600 en ruim tijdelijke bestanden op. Vervang ops@example.net en alice@example.net door goedgekeurde adressen.

Voer vóór de eerste write deze reads uit en registreer alleen HTTP-status, requestId/correlationId bij fouten en het schemaresultaat:

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

Een 404 bij de eerste twee betekent dat het object nog niet bestaat. Lijsten geven items en pages; geef pages.nextKey URL-gecodeerd als pageFromKey door totdat er geen nextKey meer is.

Interne tenant-CA plaatsen

De interne CA ondertekent certificaten die Sophos voor interne gebruikers maakt. Per tenant is exact één CA mogelijk. Maken en uploaden creëren zo nodig automatisch een uitgeschakelde S/MIME-configuratie, maar schakelen S/MIME niet in. Een tweede poging geeft 409; de gecontroleerde API heeft geen apart pad om alleen deze CA te verwijderen of vervangen.

Optie A: CA door Sophos laten maken

POST /smime/ca/internal vereist organizationName, locality, country en email. country is exact twee ISO 3166-1-hoofdletters. organizationUnit is optioneel, evenals certExpiryDate (YYYY-MM-DD) of certValidityPeriod (1–20 jaar). Standaard is 20 jaar; bij beide velden geldt de kortste termijn.

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

Succes is 201. Bewaar de 64 tekens lange SHA-256-fingerprint, issuer, validFrom, expiresAt en origin zonder onnodig de hele response te loggen.

Optie B: bestaande CA met sleutel uploaden

POST /smime/ca/internal/certificate verwacht een Base64-gecodeerde PKCS#12-certificaat-sleutelbundle, geen PEM:

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

Na Base64 moet pkcs12 1200–24000 tekens en password 3–50 tekens bevatten. De PKI-owner controleert certificaat, privésleutel, keten, doel en wachtwoord. Base64 beschermt de sleutel niet. Verwijder regeleinden en plaats nooit PEM in pkcs12.

Controleer bij beide opties: GET /smime/ca/internal levert dezelfde fingerprint; GET /smime/ca/internal/certificate downloadt het openbare PEM-certificaat als application/octet-stream; de fingerprint klopt met de inventaris. PEM bevat geen herstelbare CA-privésleutel.

Tenantconfiguratie pas daarna inschakelen

GET /smime/config levert smimeEnabled, extractCertificate, maximaal vijf certExpiryNotificationEmailAddresses en de acht tekens lange deleteToken. Behandel die als destructief geheim.

Maak een ontbrekende configuratie met POST /smime/config; smimeEnabled is verplicht en extractCertificate is standaard false:

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

Gebruik voor een bestaande configuratie PATCH /smime/config: minimaal één veld, weggelaten velden blijven gelijk, null of [] wist alle adressen en duplicaten worden verwijderd. Schrijf eerst smimeEnabled: false, plaats en inventariseer vertrouwde CA’s en externe pilotcertificaten en stuur pas dan {"smimeEnabled":true}. Zonder interne CA volgt 409. Bevestig met GET, plaats interne pilotcertificaten en test ondertekening en versleuteling. extractCertificate: true staat alleen extractie uit inkomende berichten toe; de vereisten voor handtekeningverificatie in de Secure Message policy uit de GUI-handleiding blijven gelden.

Vertrouwde externe CA’s beheren

Deze CA’s verifiëren ondertekende berichten; het zijn niet de interne CA of gebruikerscertificaten. Controleer voor upload in Sophos Fusion (voorheen Sophos Central) of de issuer al wereldwijd vertrouwd is en verifieer SHA-256 via een onafhankelijk kanaal.

  • GET /smime/cas/external: filters commonName, certValidBefore, certValidAfter, certExpiryBefore, certExpiryAfter, certFingerprint, issuerCN, pageFromKey, pageSize (standaard 50).
  • POST /smime/cas/external/certificate: PEM in certificate, 300–32000 tekens inclusief header en footer.
  • GET /smime/cas/external/certificate/{fingerprint}: downloadt exact die PEM.
  • DELETE /smime/cas/external?certFingerprint=...: verwijdert exact die trust entry.
{
  "certificate": "-----BEGIN CERTIFICATE-----\n<BASE64_CERTIFICATE>\n-----END CERTIFICATE-----"
}

Een duplicaat geeft 409. Vóór DELETE moet een exacte list read één verwacht item opleveren; na 200 en deleted: true moet het filter leeg zijn. Test daarna een handtekening via de resterende keten.

Certificaten van externe ontvangers beheren

Dit zijn openbare partnercertificaten zonder tenant-privésleutel. POST /smime/users/external/certificate neemt PEM in certificate (300–32000 tekens), leidt de identiteit uit het certificaat af en schakelt S/MIME voor die gebruiker in:

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

Voor DSA/EC bevestigt confirmVerificationOnlyCert: true bewust dat alleen ondertekenen/verifiëren mogelijk is, niet versleutelen/ontsleutelen. Maximaal twee certificaten per identiteit (422 bij het volgende); duplicaat geeft 409.

GET /smime/users/external?email=partner@example.net filtert op het exacte adres en ondersteunt ook emailStartsWith, datum-, fingerprint- en issuerfilters en paginatie. GET /smime/users/external/certificate/{fingerprint} downloadt PEM. DELETE /smime/users/external?email=...&certFingerprint=... verwijdert alleen het exacte, URL-gecodeerde paar; bij het laatste certificaat verdwijnt de gebruiker uit de lijst. Controleer na upload email, fingerprint, issuer en geldigheid en laat de bedoelde pilotpartner een testbericht ontsleutelen.

Interne gebruikerscertificaten maken of uploaden

De gebruiker moet als overeenkomende tenantidentiteit bestaan. Create of upload schakelt S/MIME voor de gebruiker in. Normaliseer adressen niet: hergebruik de exacte email uit GET.

Gebruik voor create POST /smime/users/internal:

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

Alleen email is verplicht. Voor certExpiryDate/certValidityPeriod gelden dezelfde regels van 1–20 jaar als voor de CA. Interne CA en geconfigureerde/ingeschakelde S/MIME zijn vereist.

Gebruik voor upload POST /smime/users/internal/certificate:

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

email, pkcs12 en password zijn verplicht; grenzen zijn 1200–24000 Base64-tekens en 3–50 wachtwoordtekens. DSA/EC vereist confirmSigningOnlyCert: true en is dan alleen voor ondertekenen/verifiëren. CA’s in de bundle worden als vertrouwde CA opgeslagen: valideer de keten en controleer /smime/cas/external. Maximaal twee certificaten per gebruiker; duplicaat 409, derde 422.

GET /smime/users/internal?email=alice@example.net geeft exacte gebruiker en certificaten en ondersteunt userName, emailStartsWith, datum/fingerprint/issuer en paginatie. GET /smime/users/internal/certificate/{fingerprint} downloadt PEM inclusief met de bundle geüploade CA’s, maar zonder privésleutel. DELETE /smime/users/internal?email=...&certFingerprint=... verwijdert alleen het paar; na het laatste certificaat verdwijnt de gebruiker uit de S/MIME-lijst. Controleer na 201 adres, fingerprint, issuer en vervaldatum en test uitgaand ondertekenen en inkomend ontsleutelen.

Destructieve reset alleen als goedgekeurde herbouw

Goedkeuring vereist: interne CA, vertrouwde CA’s, interne en externe certificaten en alle opgeslagen privésleutels worden verwijderd; smimeEnabled wordt false. Hiermee herstelt u geen afzonderlijk object.

Vooraf: (1) inventariseer alle pagina’s van GET /smime/config, /smime/ca/internal, /smime/cas/external, /smime/users/internal, /smime/users/external; (2) bevestig per herstelbare sleutel een geautoriseerde PKCS#12-bron en getest wachtwoord—PEM is geen sleutelbackup; (3) documenteer policy, venster, owner, partners, uitval en volledige herbouwvolgorde; (4) haal de actuele deleteToken direct uit GET; (5) laat tenant, inventaris, gevolg en tokenkoppeling door een tweede bevoegde persoon controleren.

Roep pas dan exact DELETE /smime/config/{deleteToken} aan. Verkeerde token geeft 409; ontbrekende configuratie 404. Bij timeout, 5xx of onbekend resultaat niet blind herhalen: lees eerst configuratie en inventarissen. Succes vereist 200 en deleted: true; daarna moet de configuratie ontbreken of met smimeEnabled: false worden herbouwd. Volgorde: interne CA, uitgeschakelde configuratie, trust, gebruikers, definitief inschakelen.

Validatie en troubleshooting

Valideer twee niveaus: API-status, met exacte GET van email, 64 hextekens SHA-256, issuer, validFrom, expiresAt, origin, pagina-einde en configuratie; en berichteffect, door uitgaand te ondertekenen, inkomend te verifiëren, voor de externe pilot te versleutelen en voor de interne pilot te ontsleutelen met een kleine Secure Message policy. Leg Message-ID, UTC en resultaat vast, nooit sleutels of volledige payloads.

  • 400: JSON-velden, PEM-header/footer, Base64 zonder regeleinden, PKCS#12-wachtwoord, lengtes, datum en email; verwerk elke errors.
  • 401/403: token, minimale rechten en tenanttoewijzing; raad de regio niet.
  • 404: regionale host, exact pad, email/fingerprint-paar en inventaris.
  • 409: CA/certificaat bestaat, CA ontbreekt bij inschakeling of verkeerde deleteToken; lees status vóór een nieuwe write.
  • 422: er zijn al twee certificaten; verwijder geen onbekende fingerprint.
  • Onverwachte lijst: volg pages.nextKey, encodeer pageFromKey en gebruik exact filter.
  • Bericht mislukt ondanks correcte GET: controleer inschakeling, policy-scope/-volgorde, geldigheid, identiteit, keten en key usage; rond de test af met de GUI-handleiding.

Voor escalatie volstaan methode, pad zonder gevoelige queries, HTTP-status, UTC, requestId/correlationId, tenant ID, objecttype en geanonimiseerde metadata. Sluit bearer token, deleteToken, wachtwoorden, PKCS#12, privésleutels en volledige persoonslijsten uit.