HASH SIGNING API (CSC)

Yes, our interface offers the option of signing several hash values in one step, i.e. with one signature authorization.

You can obtain the maximum possible number of hash values by calling the credentials/info method.

Yes. With the DOCUMENT SIGNING API, primesign takes care of the correct creation of the PDF signature, the visual preparation of the signature (stamp) and the addition of all required LTV information. Additionally, primesign can also add a qualified timestamp on request.

More information under DOCUMENT SIGNING API.

• Ensure that the service name and the primesign logo are displayed without distortion/pixelation etc.
• Dynamically retrieve information such as logo, name, oauth2 URL, methods, from the /info endpoint.
• Ensure that a cancel ("Cancel" button in the primesign user interface) is handled correctly .
• Do not integrate primesign in an iFrame .
• Revoke the access token (from the service authorization) after signing using the API method /oauth2/revoke.
• primesign recommends compliance with OAuth2 best practices, e.g. the use of PKCE.
• Get an overview of the acceptance criteria for our acceptance test. These can be found in section 5.2 of the Getting Started Guide.

Make sure to encode the hash value correctly before passing it to the API methods oauth2/authorize and /signatures/signHash.

In accordance with the CSC specification, the hash value must be Base64 URL encoded when submitted to the oauth2/authorize endpoint.

For the API method /signatures/signHash, however, the hash value must be Base64-encoded.

primesign only creates ECC keys for the signature keys.

You can obtain the supported signature algorithm via the /credentials/info interface and receive the algorithm in the response under key/algo. Make sure to always use one of the supported signature algorithms for the signAlgo parameter in the API method /signatures/signHash.

primesign recommends the transfer of a transaction parameter defined by you (hereinafter referred to as clientTransactionId).

The clientTransactionId should be included in both /oauth2/authorize requests. The clientTransactionId simplifies the tracking of a signature transaction in the log file, for example for support requests, and is included in the transaction report in the invoice. The clientTransactionId is transmitted in JSON format in the clientData parameter, see Getting Started Guide.

The following characters are permitted: a-z A-Z 0-9 _ @ : + . -

Maximum length of the clientTransactionId: 200 characters

If an invalid clientTransactionId is transmitted, it is ignored and not used. No error is returned as this is an optional parameter.

The base URLs for primesign are:

Test system: https://qs.primesign-test.com
Production system: https://qs.prime-sign.com

By default, primesign creates a confidential client for your application.

• Confidential clients are applications that can authenticate themselves securely to the primesign IDENTITY PROVIDER.
• Confidential clients receive a clientId and a client secret that they can store securely. This requires a backend application.

primesign also creates public clients for applications without the option of securely storing the client secret.

• primesign creates public clients exclusively for client-side applications such as mobile app, web apps or native desktop applications without a backend server.
• Public clients receive a clientId but no client secret.
• Public clients must use the OAuth2 Authorization Code Flow. The use of PKCE is mandatory.
• Applications should use the system browser for OAuth authorization.

For testing signature creation with persistent primesign signing certificates, test accounts are necessary for the integrator. Each test account requires a registration code (VOUCHER CODE). A limited number of registration codes are provided by primesign for free. Inform developer@prime-sign.com how many test accounts are required.

To register a test account, visit the primesign OnBoarding Service (https://onboarding.primesign-test.com). Fill in the registration data and make sure to use a valid e-mail address and mobile phone number. For identification you can either use your eID (e.g. ID Austria/Handy-Signatur) or
use the test system of our video identification partner. When video identification is used, skip the actual video call by entering the magic TAN “123456”. After successful identification, we issue test certificates from our test hierarchy (no qualified certificates!). Only ECC keys are issued.

On request, primesign also issues accountIds for primesign ENTERPRISE ACCOUNTs within the test environment (no costs apply in the test environment).

For signature creation with a primesign account, a password and SMS-TAN is required. However, within the test environment primesign can mark specific  accounts to work with our magic TAN „123456“.

This is especially useful during development, when multiple developers share one test account and for integration tests, to allow for periodic automated testing. Contact developer@prime-sign.com to configure one of your existing test accounts to work with magic-TAN.

These test accounts with magic TAN are only available in the primesign test environment.

primesign forbids load tests with services provided by primesign (includes both test and production environment). Exceptions only with prior approval from primesign.

primesign offers the option of using the parameter amr_hint to control which signature means are available in the primesign login dialog.

This parameter is transferred in the first oauth/authorize request in JSON format in the clientData parameter. Example: /oauth2/authorize?scope=service&clientData=%7B "amr_hint"%3A "eid"%7D...

The amr_hint "eid" only shows the login via eID and hides the option to log in with e-mail and password.

The amr_hint "pwd" only shows the login with e-mail and password and hides the option to sign with an existing eID.

Users use their existing eID (e.g. German Identity Card, ID Austria) to sign without prior registration at primesign. The signature only needs to be authorized by entering the eID access data.

Users sign with qualified certificates issued immediately and „on-the-fly“ based on current data from a valid eID. The issued certificate can only be used once for this signature.

In order to use "Sign with eID", an account_token containing an accountId registered with primesign must be transmitted to primesign. This accountId is used for billing and must be issued once.

Please contact developer@prime-sign.com for the issue of an accountId.

The account_token is a JSON Web Token (JWT) that contains the accountId.

For using account_token consider:

• An account_token must be passed in the service authorization call, when calling oauth2/authorize for the first time. The transfer of an account_token in the credential authorization is optional.
• The account_token is a JWT consisting of header, payload and signature. The accountId is added as "sub" attribute in the JWT. See section 8.3.1 of the CSC API specification for the format of the account_token.
• The JWT payload also includes the issuing time of the JWT. account_token are valid for 2 minutes (2 minutes from the issuing time given in "iat").
• The JWT signature required to generate the account_token SHALL be calculated with the HMAC function, using the SHA256 hash of the client secret.
• Public clients (e.g. desktop apps) do not have client secrets. Therefore, public clients must send unsigned account_tokens. primesign accepts unsigned account_tokens only from public clients. Confidential clients have to send signed account_tokens.

Official test identities can be used to use ID-Austria.

To use the German Identity Card in the test system, the following requirements must be met:

• Download AusweisApp
• Card reader or smartphone (with NFC) to read the ID card
  
• The internal card simulator can be used instead of a physical German Identity Card

To activate the internal card simulator:

1. Download AusweisApp
2. Activate developer options: In the menu select "Help" and "Version information". Click ten times on the version information. A new "Developer options" tab will then appear in the Settings area.
3. Activate the internal card simulator: Switch to settings in the meu and activate "Internal card simulator" in the developer options
   

In our support area you get answers to frequently asked questions when using an eID.