Egne scripts

Til en platform, kataloget ikke dækker, skriver I selv scriptet og lægger det op som en custom agent. Det kører kun på målserveren, aldrig på appliancen, og det kan ikke kalde et API fra appliancen.

Læg en custom agent op

Kun en Owner kan slå custom agenter til og lægge dem op.

Pak agent.yml og scriptet (.sh, .ps1 eller .py) i en zip-fil. Tag udgangspunkt i eksemplet til Linux. Til Windows-servere, se Windows-servere.
Åbn Agenter › Katalog, og slå Tillad custom agenter til under Custom agenter.
Vælg filen under Zip-fil med agenten, og klik på Upload og godkend.
Tillad custom agenter på serveren (script-politik).
Brug agenten i en regel. I reglens trin Opsummering klikker I på Tilføj agent under Agentkæde for …, vælger jeres agent under Kompatible agenter og vælger handlingen. Hvilken tjeneste I vælger på serveren, står i Servere, sslbrain ikke kender.

Licensen bestemmer antallet af custom agenter: Free 1, Basic 3, Professional og Enterprise ubegrænset. En ny version af en agent tager ikke en plads mere.

Slår I Tillad custom agenter fra, kan der ikke lægges nye op. De godkendte kører videre.

Service-agentens script-politik

Service-agenten kører ikke custom agenter, før dens script-politik er 31. Standard er 15. Appliancen kan ikke ændre det. Sæt værdien på Windows-serveren på en af to måder:

Ved installationen med MSI-egenskaben SCRIPTPOLICY=31 (MSI-egenskaber).
Med Group Policy: ScriptPolicy (REG_DWORD, 31) under HKLM\SOFTWARE\Policies\sslbrain. Den går forud for værdien fra installationen. Genstart tjenesten sslbrainagent, hvis den skal gælde med det samme.

Værdien er summen af det, agenten må køre:

Værdi	Må køre
1	FairSSL-pakker, der læser
2	FairSSL-pakker, der skriver
4	Community-pakker, der læser
8	Community-pakker, der skriver
16	Custom agenter

Værdierne 4 og 8 findes i script-politikken, men kataloget har i dag ingen community-pakker. Alle pakker i kataloget er skrevet, gennemgået og signeret af FairSSL. Et forslag fra en bruger bliver kun en pakke, når FairSSL har gennemgået det, låst koden og udgivet det under FairSSL’s signatur.

Siden Politik og revision › Script-politik på appliancen bestemmer ikke, hvad agenterne kører (politik).

agent.yml

Appliancen afviser agenten, hvis et af felterne mangler eller ikke passer:

Felt	Værdi
`agent.name`	Et navn, som ingen pakke fra FairSSL eller indbygget pakke bruger
`agent.tier`	`custom`
`agent.channel`	`push-ssh`. Navnet er det, appliancen kræver
`actions.<navn>`	Handlingen, fx `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` for en handling, der ændrer noget, `read` for en, der kun læser
`timeout`	Sekunder, handlingen må køre
`cert_format`	`pem` eller `pfx_base64` (variabler)
`parameters`	Egne felter, der udfyldes i reglen

Zip-filen må højst fylde 1 MB, have 64 filer, 512 KB pr. fil og 4 MB udpakket. Tilladte filtyper er yml, yaml, sh, ps1, py, json, md og txt. Skjulte filer, symbolske links, binære filer, absolutte stier og .. afvises.

Windows-servere

På Windows-servere installerer sslbrain kun certifikater gennem service-agenten. Den direkte forbindelse fra appliancen til Windows bruges kun til at finde servere og installere service-agenten, ikke til certifikater. Derfor viser manualen ikke et eget PowerShell-script til certifikater.

Brug i stedet de signerede Windows-agenter i kataloget, som service-agenten kører, fx IIS, Exchange, SQL Server og installation i Windows’ certifikatlager (Integrationer). Til en Windows-tjeneste, som ingen pakke kender, bruger I skabelonen Custom Windows Certificate Deployment fra kataloget. Den lægger certifikatet i Windows’ certifikatlager eller i en fil. Sådan installeres service-agenten: Windows-servere.

Eget script på en Linux-server

Eksemplet skriver certifikat og nøgle til filer og genindlæser en tjeneste.

agent.yml:

agent:
  name: intranet-app-linux
  display_name: "Intranet-app"
  version: "1.0.0"
  tier: custom
  description: "Installerer certifikatet til intranet-appen"
  channel: push-ssh

actions:
  deploy:
    description: "Skriv certifikat og nøgle, og genindlæs tjenesten"
    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 fejlede\"}"; 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"}'

Hvad scriptet får

I bash er værdierne miljøvariabler. I PowerShell er de variabler i sessionen, fx $PFX_BASE64.

Certifikatet leveres i den form, handlingens cert_format angiver. Uden cert_format får en handling, der erklærer CERT_PEM, KEY_PEM eller CHAIN_PEM, certifikatet som PEM.

`cert_format`	Variabler
`pem`	`CERT_PEM`, `KEY_PEM`, og `CHAIN_PEM`, når kæden leveres for sig
`pfx_base64`	`PFX_BASE64`, `PFX_PASSWORD`, `PFX_ENCRYPTION` og `CERT_PEM`

Scriptet får altid:

Variabler	Indhold
`HOSTNAME`, `HOST`, `SERVER_IP`, `SERVER_OS_TYPE`	Serveren
`CREDENTIAL_USER`, `CREDENTIAL_SECRET`	Adgangen på serveren, når den har en
`SSLBRAIN_ELEVATE`	`sudo`, når adgangen har Løft rettigheder med sudo slået til
`CERTIFICATE_CN`, `CERTIFICATE_SERIAL`, `CERTIFICATE_FINGERPRINT_SHA256`, `CERTIFICATE_NOT_AFTER`, `CERTIFICATE_ISSUER`, `NEW_THUMBPRINT`, `NEW_FRIENDLY_NAME`	Det nye certifikat
`OLD_THUMBPRINT`, `OLD_FRIENDLY_NAME`, `OLD_FINGERPRINT_SHA256`, `OLD_CERTIFICATE_SERIAL`	Det certifikat, der erstattes
`ENDPOINT_NAME`, `ENDPOINT_AGENT_TYPE`, `DEPLOYMENT_MODE`	Tjenesten i reglen
`CERT_PATH`, `KEY_PATH`, `CHAIN_PATH`, `RELOAD_COMMAND`, `INIT_SYSTEM`, `SOFTWARE_VERSION`	Det, discovery har fundet på tjenesten

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ærdien under parameterens eget navn. I PowerShell bindes den også til param() efter navn.

Resultat: scriptet skriver altid et JSON-objekt med status sat til success eller error og eventuelt message. Det sidste objekt med status gælder. Handlingen fejler ved error, også hvis exit-koden er 0, og ved en exit-kode, der ikke er 0.

Signering

Appliancen signerer en custom agent med sin egen nøgle, når den lægges op. Service-agenterne får nøglen, når de registreres, og kører kun custom agenter, der er signeret med den.

Pakker fra FairSSL har et manifest med SHA-384 af hver fil, signeret med ECDSA P-384 på en hardware-nøgle hos FairSSL. Appliancen stoler kun på FairSSL’s faste nøgler til produktion.

Agenter › Katalog viser for hver version Signatur OK, Ugyldig signatur eller Ikke signeret.