Back-up en herstel

Een connector is meer dan software: hij houdt de overeenkomsten van je organisatie bij, en het bewijs van alles wat er onder die overeenkomsten is gebeurd. Een back-up beschermt dat. Maar een bewijsketen is ook verankerd bij een onafhankelijke partij, en die merkt het als je terug in de tijd gaat. Lees daarom ook wat een herstel betekent.

Wat je bewaart

De PostgreSQL-database. Daar staat bijna alles in, van control plane, data plane en gebouwservice samen:

de identiteit van de connector, het DID-document en de ondertekende historie ervan (did:webvh);
je lidmaatschapsbewijs, catalogus, producten, voorwaarden, overeenkomsten, leveringen en abonnementen;
je systemen en koppelingen, mét de sleutels waarmee de data plane je systemen aanroept, versleuteld met BL_DATA_KEY;
de instellingen, waaronder de koppeling met je identity provider met het client-secret, ook versleuteld;
de apps en API-sleutels (alleen als hash);
het bewijslog, de bewijsbladen van de data plane, de ankers en de ontvangstbewijzen van de notaris;
de berichten die nog verstuurd moeten worden (de outbox);
de foto’s en gebouwgegevens van de gebouwservice, in het schema building;
met BL_KEY_SOURCE=db ook de private sleutels (alleen in development en tck).

Gebruik bij voorkeur doorlopend archiveren van PostgreSQL (WAL-archivering, point-in-time recovery), zodat je kunt terugzetten tot vlak voor een storing. Waarom dat ertoe doet, staat hieronder.

De sleutels, als ze buiten de database staan.

Met file of env: identity, dataplane, did-update en did-update-next, en de sleutel waarvan de hash in BL_DID_NEXT_KEY_HASH staat. Die laatste staat bewust niet op de server; bewaar hem offline, want zonder hem kan je connector zijn DID-document niet meer bijwerken.
Met pkcs11 of vault staan de sleutels in je HSM of KMS. Een niet-exporteerbare sleutel kun je niet als bestand bewaren: gebruik de back-up of replicatie van de HSM of KMS zelf.

Raak je de identiteitssleutel kwijt, dan kan je connector niet meer namens je organisatie tekenen.

De sleutel van de geheimen, BL_DATA_KEY, apart van de database. Zonder die sleutel zijn de sleutels van je systemen en het client-secret van je identity provider in een back-up niet terug te halen: je moet ze dan opnieuw invoeren. Bewaar hem dus, maar niet naast de back-up van de database, want samen geven ze die geheimen prijs. Neem je een nieuwe sleutel (zie een andere sleutel nemen), bewaar de oude dan tot er geen back-up meer is die hem nodig heeft. Zet je een back-up terug, start de connector dan met de sleutel van toen, of met de nieuwe als BL_DATA_KEY en die van toen als BL_DATA_KEY_PREVIOUS.

Met een omhulde sleutel (bl-wrap:v1:…, met een KMS of HSM) is BL_DATA_KEY zonder de KMS niets waard. Bewaar dan twee dingen: de omhulde waarde, en de sleutel bl-data in de KMS, via de back-up of replicatie van de KMS zelf. Ben je die sleutel kwijt, dan opent geen back-up de geheimen meer, en voer je ze opnieuw in. In Vault blijft een oude versie van bl-data openen zolang je min_decryption_version niet ophoogt, en op een HSM blijft een oude sleutel bruikbaar zolang je hem niet verwijdert. Houd ze tot er geen back-up van de configuratie meer is die ze nodig heeft. De omhulde waarde mag naast de back-up van de database staan: alleen wie ook de KMS mag gebruiken, opent hem.

De configuratie: de BL_*-variabelen en de geheimen die erin staan, zoals BL_SESSION_KEY, BL_DATA_KEY (leesbaar of omhuld), het wachtwoord van de database en het token voor Vault.

Behandel de back-up als vertrouwelijk. De geheimen erin zijn versleuteld, maar hij bevat alles over je overeenkomsten, leveringen en bewijs. Draait de connector zonder BL_DATA_KEY (alleen in development en tck), dan staat de sleutel van de geheimen in de database zelf, en is alles in de back-up leesbaar.

Wat je niet hoeft te bewaren

Redis. Daar staan alleen sessies (ook die van bl login), de inlogstatus, tellers en een paar vlaggen voor de status. Zonder Redis log je opnieuw in.
De logs. Ze helpen bij het zoeken naar problemen, maar bewijzen niets; dat doen de bewijsbladen in de database. Bewaar ze zo lang je ze nodig hebt.
De images. Die haal je opnieuw op, in dezelfde versie als de database.

Wat een herstel betekent

Terugzetten maakt de database gelijk aan het moment van de back-up. Alles wat er daarna gebeurde, is bij jou weg. Bij je tegenpartijen niet: zij hebben hun kant van elke overeenkomst, elk bericht en elk verzoek, met jouw handtekeningen erop.

De bewijsketen. Je connector verankert de kop van zijn bewijslog elke minuut bij de notaris van de Trust Authority. De notaris houdt per deelnemer één doorlopende keten bij, en accepteert alleen een anker dat voortbouwt op het vorige. Zet je een back-up terug van vóór het laatste anker, dan schrijft je connector nieuwe vastleggingen op plaatsen in de keten die al verankerd zijn, met een andere inhoud. De notaris weigert dan elk nieuw anker, en anchoring staat in /healthz en in de beheeromgeving op degraded. Dat blijft zo, ook na een herstart; de connector lost het niet vanzelf op.

Herstel je tot ná het laatste anker, met point-in-time recovery tot vlak voor de storing, dan bouwt de keten gewoon voort en loopt verankeren door.

De DID-historie. Elke versie van je DID-document staat in een ondertekende historie, en de Trust Authority bevestigt elke versie als getuige. Ze bevestigt alleen een historie die voortzet wat ze eerder bevestigde. Het DID-document verandert zelden: bij een andere sleutel of een ander adres. Maak na zo’n wijziging direct een nieuwe back-up. Een back-up van vóór de wijziging leidt na herstel tot een tweede historie, die de Trust Authority weigert.

Lopende processen. Overeenkomsten, leveringen en aanwijzingen van na de back-up kent je connector niet meer, terwijl je tegenpartijen ze wel kennen. Berichten die nog in de outbox stonden, gaan niet meer weg. Controleer na een herstel onder Aanvragen en Gebouwen wat er loopt, en stem af met je tegenpartijen.

TechnischEen herstel oefenen

Oefen een herstel in je acceptatieomgeving, met een eigen Trust Authority. Zet de back-up terug in een nieuwe database, start dezelfde versie van de connector met dezelfde sleutels en dezelfde DID (BL_DID, of zonder die instelling hetzelfde BL_INTERNAL_URL), en controleer /healthz: database, evidence en anchoring horen ok te zijn. Onder Bewijs kun je de bewijsketen laten narekenen.