HASH SIGNING API (CSC)

Ja. Unsere Schnittstelle bietet die Möglichkeit mehrere Hashwerte in einem Schritt, d.h. mit einer Signaturfreigabe, zu unterzeichnen.

Die maximal mögliche Anzahl an Hash-Werten erhalten Sie durch Aufruf der credentials/info Methode.

Ja. Bei der DOCUMENT SIGNING API übernimmt primesign die korrekte Erstellung der PDF-Signatur, die visuelle Aufbereitung der Signatur  (Stempel), sowie das Einbringen von LTV-Informationen. Auf Wunsch ist auch die zusätzliche Einbringung eines qualifizierten Timestamps möglich.

Mehr Informationen unter DOCUMENT SIGNING API. 

• Sicherstellen, dass der Service Name sowie das Logo von primesign ohne Verzerrungen/Pixelierung usw. angezeigt werden.
• Dynamisches Beziehen von Informationen wie Logo, Namen, oauth2 URL, Methoden, aus dem /info Endpunkt.
• Sicherstellen, dass ein Abbruch ("Abbrechen"-Schaltfläche in der primesign Benutzeroberfläche) richtig behandelt wird.
• primesign nicht in einem iFrame integrieren.
• Widerrufen des Access Token (von der Service Authorization) nach der Signatur mithilfe der API-Methode /oauth2/revoke.
• primesign empfiehlt die Einhaltung der OAuth2-Best Practices, z. B. die Verwendung von PKCE.
• Machen Sie sich einen Überblick über die Akzeptanzkriterien unseres Abnahmetest. Diese finden Sie im Abschnitt 5.2 im Getting Started Guide.

Achten Sie darauf, den Hashwert korrekt zu kodieren, bevor Sie ihn an die API-Methoden oauth2/authorize und /signatures/signHash übermitteln.

In Übereinstimmung mit der CSC-Spezifikation muss der Hashwert Base64-URL-kodiert sein, wenn er an den oauth2/authorize Endpunkt übermittelt wird.

Bei der API-Methode /signatures/signHash hingegen muss der Hashwert Base64-kodiert sein.

primesign erzeugt für die Signaturschlüssel ausschließlich ECC-Schlüssel.

Den konkret unterstützten Signaturalgorithmus beziehen Sie über die Schnittstelle /credentials/info und erhalten den Algorithmus in der Response unter key/algo. Stellen Sie sicher, dass Sie immer einen der unterstützten Signaturalgorithmen für den Parameter signAlgo in der API-Methode /signatures/signHash verwenden. 

primesign empfiehlt die Übergabe eines von Ihnen definierten Transaktionsparameter (nachfolglich clientTransactionId genannt). 

Die clientTransactionId soll in beiden /oauth2/authorize Requests mitgegeben werden. Die clientTransactionId vereinfacht die Nachverfolgung einer Signaturtransaktion im Logfile beispielsweise bei Supportanfragen und wird im Transaktionsbericht bei der Rechnungsstellung inkludiert. Die clientTransactionId wird im JSON-Format im Parameter clientData übermittelt, siehe Getting Started Guide.

Folgende Zeichen sind erlaubt: a-z A-Z 0-9 _ @ : + . –

Maximale Länge der clientTransactionId: 200 Zeichen

Wird eine ungültige clientTransactionId mitgegeben, wird diese ignoriert und nicht herangezogen. Es wird kein Fehler retourniert, da es sich hier um einen optionalen Parameter handelt.

Die Basis-URLs für primesign lauten:

Testsystem: https://qs.primesign-test.com
Produktionsystem: https://qs.prime-sign.com

Standardmäßig erstellt primesign einen Confidential Client für Ihre Anwendung. 

• Confidential Clients sind Anwendungen, die sich sicher am primesign IDENTITY PROVIDER authentifizieren können.
• Confidential Clients erhalten eine clientId und ein client secret, die sie sicher speichern können. Dazu ist eine Backend-Applikation erforderlich.

Für Anwendungen ohne Möglichkeit zur sicheren Speicherung des client secrets erstellt primesign auch Public Clients.

• primesign erstellt Public Clients ausschließlich für Clientseitige Anwendungen wie mobile Apps und Web Apps oder native Desktop Anwendungen ohne Backend-Server.
• Public Clients erhalten eine clientId aber kein client secret.
• Public Clients müssen zwingend den OAuth2 Authorization Code Flow verwenden. Die Nutzung von PKCE ist verpflichtend.
• Anwendungen sollen den System Browser für die OAuth Authorisierung nutzen. 

Zum Testen der Signaturerstellung mit einem primesign Signaturzertifikan sind Testkonten für den Integrator erforderlich. Jedes Testkonto erfordert einen Registrierungscode (VOUCHER CODE). Eine begrenzte Anzahl von Registrierungscodes wird von primesign kostenlos zur Verfügung gestellt. Teilen Sie developer@prime-sign.com mit, wie viele Testkonten benötigt werden

Um ein Testkonto zu registrieren, besuchen Sie den primesign OnBoarding Service (https://onboarding.primesign-test.com). Füllen Sie die Registrierungsdaten aus und achten Sie darauf, dass Sie eine gültige E-Mail-Adresse und Handynummer verwenden. Zur Identifikation können Sie entweder Ihre eID (z.B. ID Austria/Handy-Signatur) verwenden oder das Testsystem unseres Video-Identifikationspartners verwenden. Bei der Videoidentifikation überspringen Sie die Videoidentifikation durch Eingabe der magischen TAN "123456". Nach erfolgreicher Identifikation stellen wir Testzertifikate aus unserer Testhierarchie aus (keine qualifizierten Zertifikate!). Es werden nur ECC-Schlüssel ausgestellt.

Auf Anfrage stellt primesign auch AccountIds für primesign ENTERPRISE ACCOUNTs innerhalb der Testumgebung aus (in der Testumgebung fallen keine Kosten an).

Für die Erstellung einer Signatur ist ein Passwort und eine SMS-TAN erforderlich. In unserer Testumgebung können jedoch bestimmte Accounts freigeschaltet werden, um eine Signatur mit unserem Magic-TAN "123456" freizugeben.

Dies ist besonders während der Entwicklung nützlich, wenn sich mehrere Entwickler einen Testaccount teilen, oder aber für Integrationstests um periodische automatische Tests zu ermöglichen. Kontaktieren Sie developer@prime-sign.com, um einen Ihrer bestehenden Testaccounts mit dem Magic-TAN auszustatten.

Diese Funktion ist nur in der primesign Testumgebung verfügbar.

primesign verbietet Lasttests mit von primesign bereitgestellten Diensten (umfasst sowohl Test- als auch Produktions-Umgebung). Ausnahmen nur mit vorheriger Genehmigung durch primesign.

primesign bietet die Möglichkeit über den Parameter amr_hint zu steuern, welche Signaturmittel im primesign Anmeldedialog zur Verfügung stehen.

Dieser Parameter wird im ersten Request oauth/authorize im JSON-Format im Parameter clientData übergeben. Beispiel: /oauth2/authorize?scope=service&clientData=%7B"amr_hint"%3A"eid"%7D…

Der amr_hint "eid" zeigt alleinig den Login mittels eID an und verbirgt die Option sich mit E-Mail und Passwort anzumelden.

Der amr_hint "pwd" zeigt alleinig den Login mit E-Mail und Passwort an und verbirgt die Option mit einer bestehenden eID zu signieren.

AnwenderInnen nutzen Ihre bestehende eID (z.B. deutscher Personalausweis, ID Austria) zur Signatur. Die Signatur muss dabei lediglich durch Eingabe der eID Zugangsdaten autorisiert werden.

Im Hintergrund stellt primesign „on-the-fly“ ein qualifiziertes primesign Signaturzertifikat auf Basis der eID aus. Das ausgestellte Zertifikat ist nur einmalig für diese Signatur nutzbar.

Um "Signieren mit eID" nutzen zu können, muss an primesign ein account_token, welcher eine bei primesign registrierte accountId beinhaltet, übermittelt werden. Diese accountId wird für die Verrechnung herangezogen und muss einmalig ausgestellt werden.

Wenden Sie sich an developer@prime-sign.com für die Ausstellung einer AccountId .

Der account_token ist ein JSON Web Token (JWT), der die accountId enthält.

Für die Verwendung von account_token zu beachten:

• Ein account_token muss im ersten Request oauth2/authorize übergeben werden (Service Scope). Die Übergabe eines account_token in der Credential Autorisierung ist optional.
• Der account_token ist ein JWT, welcher aus Header, Payload und Signatur besteht. Die accountId wird im "sub"-Attribut vom JWT übergeben. Siehe Abschnitt 8.3.1 der CSC API Spezifikation für das Format des account_token.
• Der JWT-Payload enthält auch die Ausstellungszeit des JWT. Ein account_token ist für 2 Minuten gültig (2 Minuten ab dem in "iat" angegebenen Ausstellungszeitpunkt).
• Die JWT-Signatur, die benötigt wird, um den account_token zu generieren, basiert auf einem Shared-Secret (clientSecret). Die Signatur MUSS mit der HMAC-Funktion, unter Verwendung des SHA256-Hashs des Client Secrets, berechnet werden
• Public Clients (z.B. Desktop Anwendungen) verfügen über kein Client Secret. Aus diesem Grund werden ausschließlich bei Public Clients auch unsignierte account_tokens akzeptiert. 
  

Zur Nutzung der ID-Austria können offizielle Testidentitäten genutzt werden. 

Zur Nutzung des deutschen Personalausweis im Testsystem sind folgende Voraussetzungen zu erfüllen:

• AusweisApp
• Kartenleser oder Smartphone (mit NFC)
  zum Auslesen des Ausweises
  
• Statt einem physischen deutschen Personalausweis kann der internen Kartensimulator verwendet werden

Um den internen Kartensimulator zu aktivieren:

1. Download AusweisApp
2. Entwickleroptionen aktivieren: Im Menü „Hilfe“ den Punkt  „Versionsinformationen“ auswählen. Zehnmal auf den Inhalt der Versionsinformationen klicken. Danach befindet sich im Bereich Einstellungen nun ein neuer Kartenreiter „Entwickleroptionen“.
3. Kartensimulator aktivieren: In den Entwickleroptionen „Interner Kartensimulator“ aktivieren
   

Unter Support erhalten Sie Hilfe bei der Nutzung Ihrer eID.