Als je een PDF via Cleverbase ondertekent, is het werk in tweeën verdeeld:
| Cleverbase | Jij (de integrator) |
|---|---|
| Identificeert de ondertekenaar en bewaart zijn gekwalificeerde certificaat en sleutel. | Bereidt het document voor: velden, weergave, de gereserveerde ruimte voor de handtekening. |
| Autoriseert één handtekening per keer, met instemming van de ondertekenaar. | Berekent wat er ondertekend moet worden en stuurt ons de hash daarvan. |
| Ondertekent die hash met de gekwalificeerde sleutel van de ondertekenaar en geeft de handtekeningwaarde terug. | Zet de handtekeningwaarde in een CMS-structuur en die structuur in de PDF. |
| Valideert het resultaat en controleert hoe het eruitziet in de viewers die je gebruikers hebben. |
De dienst waarmee je praat is een Cloud Signature Consortium API, versie 1.0.4, met OAuth 2.0 voor de twee autorisaties die erbij horen. Het is met opzet een hash-ondertekenende API: Cleverbase ziet je document nooit, alleen een hash. Dat is goed voor de vertrouwelijkheid, en het is de reden dat het bouwen van het document aan jouw kant zit.
Wat die verdeling voor jou betekent
Omdat wij alleen een hash zien, is alles aan het document van jou: in welk veld de handtekening komt, hoe die eruitziet, of het formulier bewerkbaar blijft, hoeveel ruimte de handtekening krijgt, en of het bestand in elke viewer van je gebruikers nog een handtekening toont. Niets daarvan controleert de API, en een validator ziet het evenmin. Daarom gaat het grootste deel van deze documentatie over de PDF en niet over de drie API-aanroepen: de aanroepen zijn voor iedereen gelijk, het document is waar koppelingen verschillen, en waar ze misgaan.
Het betekent ook dat dezelfde drie aanroepen elke container bedienen. Deze documentatie werkt PAdES uit, een handtekening in een PDF, omdat daar de vragen vandaan komen. CAdES (een handtekening over een willekeurig bestand) en XAdES (XML) gebruiken dezelfde hash-ondertekenstap met een andere verpakking, en worden genoemd waar het verschil uitmaakt.
De referentie-implementatie
Cleverbase draait zelf een koppeling met precies deze flow, en de codevoorbeelden in deze documentatie zijn daaruit geknipt. De PDF-kant is een kleine Java-service op DSS 6.3 (endpoints voor prepare en complete); de CSC-kant is een Python-applicatie die de OAuth-rondgangen doet, de credential opvraagt en signHash aanroept. Waar een pagina zegt "onze implementatie doet X", verwijst dat naar die code, en is X een keuze die in productie gebruikt wordt en niet alleen een aanbeveling uit een specificatie.
Waar je verder gaat
De hosts en wat je nodig hebt voor de eerste aanroep staan in Omgevingen en vereisten. De stappen zelf zijn de handleidingen, te beginnen met De ondertekenflow; wat de ondertekenaar ondertussen doorloopt is De reis van de ondertekenaar.