Hoppa till innehållet
Avanet

Automatisera Sophos Email S/MIME via API:t

Sophos Email

Sophos Email Management API kan styra hela livscykeln för S/MIME-certifikat. Den säkra ordningen är: läs inventeringen, skapa eller ladda upp exakt en intern tenant-CA, skapa först tenantkonfigurationen inaktiverad, lägg till betrodda CA:er och externa certifikat, aktivera S/MIME, lägg till interna certifikat och testa sedan e-postflödet. Artikeln skiljer avsiktligt mellan intern tenant-CA, betrodda externa CA:er, interna användarcertifikat och externa mottagarcertifikat. De använder olika sökvägar och är inte utbytbara.

För arkitektur, policy och UI-tester, se GUI-guiden för S/MIME. Introduktionen till Sophos Email Management API förklarar det allmänna kontraktet; OAuth2, tenantupplösning och regional värd behandlas i planerad runbook för API-autentisering och tenant routing.

Kritisk varning: DELETE /smime/config/{deleteToken} tar bort alla S/MIME-certifikat och privata nycklar i tenanten och sätter smimeEnabled till false. Det är inte certifikatrotation eller normal felsökning. API:t dokumenterar ingen export av privata nycklar. Utan separat bevarade, auktoriserade PKCS#12-källor kan nycklar och möjligheten att dekryptera historiskt innehåll gå förlorade permanent.

Förutsättningar och säker requestbas

Använd endast redan validerade SOPHOS_ACCESS_TOKEN (kortlivad bearer token), SOPHOS_TENANT_ID (måltenantens UUID) och SOPHOS_API_HOST (fullständig regional värd). Den granskade specifikationen är Email Management API v1.4.0; kontrollera aktuell version före implementering. Alla sökvägar är relativa till /email/v1 och kräver Authorization: Bearer ***, X-Tenant-ID och för JSON Content-Type: application/json:

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

Placera inte token, deleteToken, PKCS#12-lösenord eller -innehåll eller privata nycklar i argument, kod, vanliga loggar eller ärenden. Använd godkänd secret store, filer med läge 600 och rensa temporära filer. Ersätt ops@example.net och alice@example.net med godkända adresser.

Kör före första write följande reads och logga endast HTTP-status, requestId/correlationId vid fel samt schemaresultat:

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

404 från de två första betyder att objektet inte finns. Listor returnerar items och pages; skicka pages.nextKey URL-kodat som pageFromKey tills nextKey saknas.

Etablera den interna tenant-CA:n

Intern CA signerar certifikat som Sophos skapar för interna användare. En tenant kan ha exakt en. Både create och upload skapar vid behov en inaktiverad S/MIME-konfiguration men aktiverar inte S/MIME. Ett andra försök returnerar 409; det granskade API:t har ingen separat sökväg för att ta bort eller ersätta bara denna CA.

Alternativ A: låt Sophos skapa CA:n

POST /smime/ca/internal kräver organizationName, locality, country och email. country är exakt två versala ISO 3166-1-bokstäver. organizationUnit är valfritt, liksom certExpiryDate (YYYY-MM-DD) eller certValidityPeriod (1–20 år). Standard är 20 år; anges båda används den kortare perioden.

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

Framgång är 201. Bevara den 64 tecken långa SHA-256-fingerprint, issuer, validFrom, expiresAt och origin utan att logga hela svaret i onödan.

Alternativ B: ladda upp CA och nyckel

POST /smime/ca/internal/certificate förväntar en Base64-kodad PKCS#12-certifikat- och nyckelbundle, inte PEM:

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

Efter Base64 ska pkcs12 vara 1200–24000 tecken och password 3–50 tecken. PKI-ägaren validerar certifikat, privat nyckel, kedja, syfte och lösenord. Base64 skyddar inte nyckeln. Ta bort radbrytningar och placera aldrig PEM i pkcs12.

För båda alternativen: GET /smime/ca/internal ska returnera samma fingerprint; GET /smime/ca/internal/certificate hämtar offentligt PEM som application/octet-stream; fingerprint ska matcha inventeringen. PEM innehåller ingen återställningsbar privat CA-nyckel.

Aktivera tenantkonfigurationen först därefter

GET /smime/config returnerar smimeEnabled, extractCertificate, högst fem certExpiryNotificationEmailAddresses och den åtta tecken långa deleteToken. Behandla den som destruktiv hemlighet.

Skapa saknad konfiguration med POST /smime/config; smimeEnabled krävs och extractCertificate är normalt false:

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

För befintlig konfiguration används PATCH /smime/config: minst ett fält, utelämnade fält förblir oförändrade, null eller [] tömmer adresserna och dubbletter tas bort. Skriv först smimeEnabled: false, lägg till och inventera betrodda CA:er och externa pilotcertifikat och skicka först därefter {"smimeEnabled":true}. Utan intern CA returneras 409. Bekräfta med GET, lägg till interna pilotcertifikat och testa signering och kryptering. extractCertificate: true tillåter bara extraktion från inkommande meddelanden; kraven på signaturverifiering i Secure Message policy från GUI-guiden gäller fortfarande.

Hantera betrodda externa CA:er

De verifierar signerade meddelanden; de är varken intern CA eller användarcertifikat. Kontrollera före upload i Sophos Fusion (tidigare Sophos Central) om issuer redan är globalt betrodd och verifiera SHA-256 via oberoende kanal.

  • GET /smime/cas/external: filter commonName, certValidBefore, certValidAfter, certExpiryBefore, certExpiryAfter, certFingerprint, issuerCN, pageFromKey, pageSize (standard 50).
  • POST /smime/cas/external/certificate: PEM i certificate, 300–32000 tecken inklusive header och footer.
  • GET /smime/cas/external/certificate/{fingerprint}: hämtar exakt PEM.
  • DELETE /smime/cas/external?certFingerprint=...: tar bort exakt trust entry.
{
  "certificate": "-----BEGIN CERTIFICATE-----\n<BASE64_CERTIFICATE>\n-----END CERTIFICATE-----"
}

En dubblett ger 409. Före DELETE ska exakt list read ge ett förväntat objekt; efter 200 och deleted: true ska filtret vara tomt. Testa sedan signatur via återstående kedja.

Hantera externa mottagarcertifikat

Detta är partnernas offentliga certifikat utan tenantens privata nyckel. POST /smime/users/external/certificate tar PEM i certificate (300–32000 tecken), härleder identiteten ur certifikatet och aktiverar S/MIME för användaren:

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

För DSA/EC bekräftar confirmVerificationOnlyCert: true medvetet att endast signering/verifiering fungerar, inte kryptering/dekryptering. Högst två certifikat per identitet (422 vid nästa); dubblett ger 409.

GET /smime/users/external?email=partner@example.net filtrerar exakt adress och stöder även emailStartsWith, datum-, fingerprint- och issuerfilter samt paginering. GET /smime/users/external/certificate/{fingerprint} hämtar PEM. DELETE /smime/users/external?email=...&certFingerprint=... tar bara bort exakt, URL-kodat par; sista certifikatet tar implicit bort användaren från listan. Kontrollera efter upload email, fingerprint, issuer och giltighet och låt avsedd pilotpartner dekryptera ett testmeddelande.

Skapa eller ladda upp interna användarcertifikat

Användaren måste finnas som matchande tenantidentitet. Create eller upload aktiverar S/MIME för användaren. Normalisera inte adresser; återanvänd exakt email från GET.

För create, använd POST /smime/users/internal:

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

Endast email krävs. certExpiryDate/certValidityPeriod följer samma regler på 1–20 år som CA:n. Intern CA och konfigurerad/aktiverad S/MIME krävs.

För upload, använd POST /smime/users/internal/certificate:

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

email, pkcs12, password krävs; gränserna är 1200–24000 Base64-tecken och 3–50 lösenordstecken. DSA/EC kräver confirmSigningOnlyCert: true och kan då endast signera/verifiera. CA:er i bundlen lagras som betrodda CA:er: validera kedjan och kontrollera /smime/cas/external. Högst två certifikat per användare; dubblett 409, tredje 422.

GET /smime/users/internal?email=alice@example.net returnerar exakt användare och certifikat och stöder userName, emailStartsWith, datum/fingerprint/issuer samt paginering. GET /smime/users/internal/certificate/{fingerprint} hämtar PEM inklusive CA:er som laddades upp i bundlen, men ingen privat nyckel. DELETE /smime/users/internal?email=...&certFingerprint=... tar bara bort paret; sista certifikatet tar bort användaren från S/MIME-listan. Kontrollera efter 201 adress, fingerprint, issuer och utgång och testa utgående signering samt inkommande dekryptering.

Destruktiv återställning endast som godkänd återuppbyggnad

Godkännande krävs: intern CA, betrodda CA:er, interna och externa certifikat samt alla lagrade privata nycklar tas bort; smimeEnabled blir false. Detta reparerar inte ett enskilt objekt.

Före åtgärden: (1) inventera alla sidor från GET /smime/config, /smime/ca/internal, /smime/cas/external, /smime/users/internal, /smime/users/external; (2) bekräfta auktoriserad PKCS#12-källa och testat lösenord för varje återställningsbar nyckel—PEM är ingen nyckelbackup; (3) dokumentera policy, fönster, owner, partner, avbrott och fullständig ordning; (4) hämta aktuell deleteToken direkt från GET; (5) låt en andra behörig person kontrollera tenant, inventering, konsekvens och tokenkoppling.

Anropa först därefter exakt DELETE /smime/config/{deleteToken}. Fel token ger 409, saknad konfiguration 404. Vid timeout, 5xx eller okänt resultat: försök inte blint igen; läs först konfiguration och inventeringar. Framgång kräver 200 och deleted: true; sedan ska konfigurationen saknas eller återbyggas med smimeEnabled: false. Ordning: intern CA, inaktiverad konfiguration, trust, användare, slutlig aktivering.

Validering och felsökning

Validera två nivåer: API-status, med exakt GET av email, 64 hextecken SHA-256, issuer, validFrom, expiresAt, origin, pagineringsslut och konfiguration; samt meddelandeeffekt, genom att signera utgående, verifiera inkommande, kryptera till extern pilot och dekryptera för intern pilot med liten Secure Message policy. Logga Message-ID, UTC och resultat, aldrig nycklar eller kompletta payloads.

  • 400: JSON-fält, PEM-header/footer, Base64 utan radbrytningar, PKCS#12-lösenord, längder, datum och email; behandla varje errors.
  • 401/403: token, minsta behörighet och tenanttilldelning; gissa inte region.
  • 404: regional värd, exakt sökväg, email/fingerprint-par och inventering.
  • 409: CA/certifikat finns, CA saknas vid aktivering eller fel deleteToken; läs status före ny write.
  • 422: två certifikat finns redan; ta inte bort okänd fingerprint.
  • Oväntad lista: följ pages.nextKey, koda pageFromKey och använd exakt filter.
  • Meddelande misslyckas trots korrekt GET: kontrollera aktivering, policy-scope/-ordning, giltighet, identitet, kedja och key usage; slutför testet med GUI-guiden.

För eskalering räcker metod, sökväg utan känsliga queries, HTTP, UTC, requestId/correlationId, tenant ID, objekttyp och anonymiserade metadata. Exkludera bearer token, deleteToken, lösenord, PKCS#12, privata nycklar och fullständiga personlistor.