Egna skript

För en plattform som katalogen inte täcker skriver ni skriptet själva och laddar upp det som en anpassad agent. Det körs bara på målservern, aldrig på appliancen, och det kan inte anropa ett API från appliancen.

Ladda upp en anpassad agent

Bara en Owner kan slå på anpassade agenter och ladda upp dem.

Packa agent.yml och skriptet (.sh, .ps1 eller .py) i en zip-fil. Utgå från exemplet för Linux. För Windows-servrar, se Windows-servrar.
Öppna Agenter › Katalog och slå på Tillåt anpassade agenter under Anpassade agenter.
Välj filen under Zip-fil med agenten och klicka på Ladda upp och godkänn.
Tillåt anpassade agenter på servern (skriptpolicy).
Använd agenten i en installationsplan. I installationsplanens steg Sammanfattning klickar ni på Lägg till agent under Agentkedja för …, väljer er agent under Kompatibla agenter och väljer åtgärden. Vilken tjänst ni väljer på servern står i Servrar som sslbrain inte känner till.

Licensen avgör antalet anpassade agenter: Free 1, Basic 3, Professional och Enterprise obegränsat. En ny version av en agent tar inte en plats till.

Stänger ni av Tillåt anpassade agenter går det inte att ladda upp nya. De godkända fortsätter att köra.

Serviceagentens skriptpolicy

Serviceagenten kör inte anpassade agenter förrän dess skriptpolicy är 31. Standard är 15. Appliancen kan inte ändra det. Sätt värdet på Windows-servern på ett av två sätt:

Vid installationen med MSI-egenskapen SCRIPTPOLICY=31 (MSI-egenskaper).
Med Group Policy: ScriptPolicy (REG_DWORD, 31) under HKLM\SOFTWARE\Policies\sslbrain. Det går före värdet från installationen. Starta om tjänsten sslbrainagent om det ska gälla direkt.

Värdet är summan av det agenten får köra:

Värde	Får köra
1	FairSSL-paket som läser
2	FairSSL-paket som skriver
4	Community-paket som läser
8	Community-paket som skriver
16	Anpassade agenter

Värdena 4 och 8 finns i skriptpolicyn, men katalogen har i dag inga community-paket. Alla paket i katalogen är skrivna, granskade och signerade av FairSSL. Ett förslag från en användare blir ett paket först när FairSSL har granskat det, låst koden och gett ut det under FairSSL:s signatur.

Sidan Policy och revision › Skriptpolicy på appliancen avgör inte vad agenterna kör (policy).

agent.yml

Appliancen avvisar agenten om något av fälten saknas eller inte stämmer:

Fält	Värde
`agent.name`	Ett namn som inget paket från FairSSL och inget inbyggt paket använder
`agent.tier`	`custom`
`agent.channel`	`push-ssh`. Namnet är det som appliancen kräver
`actions.<namn>`	Åtgärden, till exempel `deploy`
`script`	En `.sh`-, `.ps1`- eller `.py`-fil i zip-filen
`runtime.location`	`target`
`runtime.interpreter`	`bash`
`runtime.delivery.mode`	`stdin` eller `scp-tmp`
`category`	`write` för en åtgärd som ändrar något, `read` för en som bara läser
`timeout`	Sekunder som åtgärden får köra
`cert_format`	`pem` eller `pfx_base64` (variabler)
`parameters`	Egna fält som fylls i i installationsplanen

Zip-filen får vara högst 1 MB, ha 64 filer, 512 kB per fil och 4 MB uppackad. Tillåtna filtyper är yml, yaml, sh, ps1, py, json, md och txt. Dolda filer, symboliska länkar, binära filer, absoluta sökvägar och .. avvisas.

Windows-servrar

På Windows-servrar installerar sslbrain bara certifikat genom serviceagenten. Den direkta anslutningen från appliancen till Windows används bara för att hitta servrar och installera serviceagenten, inte för certifikat. Därför visar manualen inget eget PowerShell-skript för certifikat.

Använd i stället de signerade Windows-agenterna i katalogen, som serviceagenten kör, till exempel IIS, Exchange, SQL Server och installation i Windows certifikatarkiv (Integrationer). För en Windows-tjänst som inget paket känner till använder ni mallen Custom Windows Certificate Deployment i katalogen. Den lägger certifikatet i Windows certifikatarkiv eller i en fil. Så installeras serviceagenten: Windows-servrar.

Eget skript på en Linux-server

Exemplet skriver certifikat och nyckel till filer och läser om en tjänst.

agent.yml:

agent:
  name: intranet-app-linux
  display_name: "Intranet-app"
  version: "1.0.0"
  tier: custom
  description: "Installerar certifikatet för intranätappen"
  channel: push-ssh

actions:
  deploy:
    description: "Skriv certifikat och nyckel och läs om tjänsten"
    script: deploy.sh
    runtime:
      location: target
      interpreter: bash
      delivery:
        mode: stdin
    category: write
    timeout: 120
    cert_format: pem

deploy.sh:

#!/usr/bin/env bash
set -euo pipefail
trap 'echo "{\"status\":\"error\",\"message\":\"deploy misslyckades\"}"; exit 1' ERR

SUDO=""
[ "${SSLBRAIN_ELEVATE:-}" = "sudo" ] && SUDO="sudo -n"
umask 077

$SUDO mkdir -p /etc/intranet-app/tls
printf '%s\n' "$CERT_PEM" | $SUDO tee /etc/intranet-app/tls/cert.pem >/dev/null
printf '%s\n' "$KEY_PEM"  | $SUDO tee /etc/intranet-app/tls/key.pem  >/dev/null
$SUDO systemctl reload intranet-app

echo '{"status":"success"}'

Vad skriptet får

I bash är värdena miljövariabler. I PowerShell är de variabler i sessionen, till exempel $PFX_BASE64.

Certifikatet levereras i den form som åtgärdens cert_format anger. Utan cert_format får en åtgärd som deklarerar CERT_PEM, KEY_PEM eller CHAIN_PEM certifikatet som PEM.

`cert_format`	Variabler
`pem`	`CERT_PEM`, `KEY_PEM`, och `CHAIN_PEM` när kedjan levereras separat
`pfx_base64`	`PFX_BASE64`, `PFX_PASSWORD`, `PFX_ENCRYPTION` och `CERT_PEM`

Skriptet får alltid:

Variabler	Innehåll
`HOSTNAME`, `HOST`, `SERVER_IP`, `SERVER_OS_TYPE`	Servern
`CREDENTIAL_USER`, `CREDENTIAL_SECRET`	Åtkomstuppgiften på servern, när den har en
`SSLBRAIN_ELEVATE`	`sudo`, när åtkomstuppgiften har Höj behörighet med sudo påslaget
`CERTIFICATE_CN`, `CERTIFICATE_SERIAL`, `CERTIFICATE_FINGERPRINT_SHA256`, `CERTIFICATE_NOT_AFTER`, `CERTIFICATE_ISSUER`, `NEW_THUMBPRINT`, `NEW_FRIENDLY_NAME`	Det certifikat som installeras
`OLD_THUMBPRINT`, `OLD_FRIENDLY_NAME`, `OLD_FINGERPRINT_SHA256`, `OLD_CERTIFICATE_SERIAL`	Det certifikat som ersätts
`ENDPOINT_NAME`, `ENDPOINT_AGENT_TYPE`, `DEPLOYMENT_MODE`	Tjänsten i installationsplanen
`CERT_PATH`, `KEY_PATH`, `CHAIN_PATH`, `RELOAD_COMMAND`, `INIT_SYSTEM`, `SOFTWARE_VERSION`	Det som discovery har hittat på tjänsten

En parameter med source: certificate.pem, certificate.key, certificate.chain, certificate.pfx_base64, certificate.pfx_password, certificate.thumbprint, certificate.previous_thumbprint eller certificate.fingerprint_sha256 får värdet under parameterns eget namn. I PowerShell binds det också till param() efter namn.

Resultat: skriptet skriver alltid ett JSON-objekt med status satt till success eller error och eventuellt message. Det sista objektet med status gäller. Åtgärden misslyckas vid error, även om exit-koden är 0, och vid en exit-kod som inte är 0.

Signering

Appliancen signerar en anpassad agent med sin egen nyckel när den laddas upp. Serviceagenterna får nyckeln när de registreras och kör bara anpassade agenter som är signerade med den.

Paket från FairSSL har ett manifest med SHA-384 för varje fil, signerat med ECDSA P-384 på en hårdvarunyckel hos FairSSL. Appliancen litar bara på FairSSL:s fasta nycklar för produktion.

Agenter › Katalog visar för varje version Signatur OK, Ogiltig signatur eller Ej signerad.