`signature` session

There are two main modes of signature session and Relying Party must choose carefully between them. They look like the ones used in case of the authentication session, but there are important differences.

Signature by document number. This is the main and common usage scenario. Document number can be obtained from result of certificatechoice session or previous authentication session result. Signatures utilizing any of the *AdES signature schemes that include the certificate as part of signature must use this method. Otherwise, the signature may be given by the person specified, but not using the key pair corresponding to the certificate chosen by Relying Party.
Signature by person’s identifier. This method should only be used if it is acceptable that the end user gives the signature using any of the Smart-ID devices in their possession.

signature session creation requests accept QSCD (Qualified Signature Creation Device) as a certificate level parameter. This is a shortcut marking a certificate of QUALIFIED level which is also QSCD-capable. ADVANCED certificates cannot be QSCD-capable.

The signature protocol RAW_DIGEST_SIGNATURE must be used for signing.

Dynamic link based `signature` session

Signing endpoints
Method	URL
`POST`	`BASE/v3/signature/dynamic-link/etsi/:id-etsi-qcs-SemanticsId-Natural`
`POST`	`BASE/v3/signature/dynamic-link/document/:documentnumber`

This method is the main entry point to signature logic for the dynamic link based flows.

Error conditions

HTTP error code 403 - Relying Party has no permission to issue the request. This may happen when:
- Relying Party has no permission to invoke operations on accounts with ADVANCED certificates.
- Relying Party has no permission to use requested capability.
HTTP error code 404 - object described in URL was not found, essentially meaning that the user does not have an account in Smart-ID system.

Request parameters

Dynamic link based `signature` request parameters
Parameter	Type	Mandatory	Description
`relyingPartyUUID`	string	+	UUID of Relying Party.
`relyingPartyName`	string	+	RP friendly name, one of those configured for particular RP. Limited to 32 bytes in UTF-8 encoding.
`certificateLevel`	string		Level of certificate requested. `ADVANCED`/`QUALIFIED`/`QSCD`, `QUALIFIED`.
`signatureProtocol`	string	+	Signature protocol. Describes the `signatureProtocolParameters` object. Currently, the only allowed value is: `RAW_DIGEST_SIGNATURE` - scheme where user-provided digest is signed directly (similarly to RP-API v1 and v2). For more details see section `RAW_DIGEST_SIGNATURE`.
`signatureProtocolParameters`	object	+	An object describing the parameters for the signature algorithm. Its structure depends on the `signatureProtocol` used. See `RAW_DIGEST_SIGNATURE` parameters table.
`allowedInteractionsOrder`	array of objects	+	See section available interactions.
`nonce`	string		Random string, up to 30 characters. If present, must have at least 1 character.
`requestProperties`	object		A request properties object. Currently, only one property is supported: `shareMdClientIpAddress` - Whether the RP API server should share user mobile device IP address with the RP. By default it is set to `false`. The RP must have proper privilege to use this property. See section IP sharing for details.
`capabilities`	array		Used only when agreed with Smart-ID provider. When omitted request capabilities are derived from `certificateLevel` parameter.

Dynamic link based signature request example

{
  "relyingPartyUUID": "1f1bfa89-4f8b-420a-a98e-fb3a161a30bc",
  "relyingPartyName": "DEMO",
  "certificateLevel": "QUALIFIED",
  "signatureProtocol": "RAW_DIGEST_SIGNATURE",
  "signatureProtocolParameters": {
    "digest": "ZHNmYmhkZmdoZGcgZmRmMTM0NTM...",
    "signatureAlgorithm": "sha512WithRSAEncryption"
  },
  "nonce": "d8XkbEnA0WsE0PvBZZoxGnPI4ml9qk",
  "allowedInteractionsOrder": [
    {
      "type": "confirmationMessage",
      "displayText200": "Longer description of the transaction context"
    },
    {
      "type": "displayTextAndPIN",
      "displayText60": "Short description of the transaction context"
    }
  ],
  "requestProperties": {
    "shareMdClientIpAddress": false
  }
}

Response structure

Dynamic link based `signature` session creation response parameters
Parameter	Type	Mandatory	Description
`sessionID`	string	+	A string that can be used to request the operation result.
`sessionToken`	string	+	Unique random value that will be used to connect this signature attempt between the relevant parties (RP, RP-API, mobile app).
`sessionSecret`	string	+	Base64-encoded random key value that should be kept in secret and should be shared only between the RP backend and RP-API server.

Dynamic link based signature session creation response

{
  "sessionID": "de305d54-75b4-431b-adb2-eb6b9e546014",
  "sessionToken": "hyBdQYUeQtvXEPqWC7K8a97L",
  "sessionSecret": "dztL7Ur49D/YYgUzYl4sMg=="
}

Notification based `signature` session

Signing endpoints
Method	URL
`POST`	`BASE/v3/signature/notification/etsi/:id-etsi-qcs-SemanticsId-Natural`
`POST`	`BASE/v3/signature/notification/document/:documentnumber`

This method is the main entry point to signature logic for the notification based flows.

In order to improve security and prevent phishing attacks, it is recommended to only allow notification based flows on devices and browsers that have successfully completed a dynamic link based flow. Setting up a unique device identifier is left to the RP to implement.

Error conditions

HTTP error code 403 - Relying Party has no permission to issue the request. This may happen when:
- Relying Party has no permission to invoke operations on accounts with ADVANCED certificates.
- Relying Party has no permission to use requested capability.
HTTP error code 404 - object described in URL was not found, essentially meaning that the user does not have an account in Smart-ID system.

Request parameters

Notification based `signature` request parameters
Parameter	Type	Mandatory	Description
`relyingPartyUUID`	string	+	UUID of Relying Party.
`relyingPartyName`	string	+	RP friendly name, one of those configured for particular RP. Limited to 32 bytes in UTF-8 encoding.
`certificateLevel`	string		Level of certificate requested. `ADVANCED`/`QUALIFIED`/`QSCD`, `QUALIFIED`.
`signatureProtocol`	string	+	Signature protocol. Describes the `signatureProtocolParameters` object. Currently, the only allowed value is: `RAW_DIGEST_SIGNATURE` - scheme where user-provided digest is signed directly (similarly to RP-API v1 and v2). For more details see section `RAW_DIGEST_SIGNATURE`.
`signatureProtocolParameters`	object	+	An object describing the parameters for the signature algorithm. Its structure depends on the `signatureProtocol` used. See `RAW_DIGEST_SIGNATURE` parameters table.
`nonce`	string		Random string, up to 30 characters. If present, must have at least 1 character.
`allowedInteractionsOrder`	object	+	See section available interactions.
`requestProperties`	object		A request properties object. Currently, only one property is supported: `shareMdClientIpAddress` - Whether the RP API server should share user mobile device IP address with the RP. By default it is set to `false`. The RP must have proper privilege to use this property. See section IP sharing for details.
`capabilities`	array		Used only when agreed with Smart-ID provider. When omitted request capabilities are derived from `certificateLevel` parameter.

Notification based signature request example

{
  "relyingPartyUUID": "1f1bfa89-4f8b-420a-a98e-fb3a161a30bc",
  "relyingPartyName": "DEMO",
  "certificateLevel": "QUALIFIED",
  "signatureProtocol": "RAW_DIGEST_SIGNATURE",
  "signatureProtocolParameters": {
    "digest": "ZHNmYmhkZmdoZGcgZmRmMTM0NTM...",
    "signatureAlgorithm": "sha512WithRSAEncryption"
  },
  "nonce": "d8XkbEnA0WsE0PvBZZoxGnPI4ml9qk",
  "allowedInteractionsOrder": [
    {
      "type": "confirmationMessage",
      "displayText200": "Longer description of the transaction context"
    },
    {
      "type": "displayTextAndPIN",
      "displayText60": "Short description of the transaction context"
    }
  ],
  "requestProperties": {
    "shareMdClientIpAddress": false
  }
}

Response structure

Notification based `signature` session creation response parameters
Parameter	Type	Mandatory	Description
`sessionID`	string	+	A string that can be used to request the operation result.
`vc`	string	+	Object describing the VC code to be displayed by RP. See section VC codes.
`vc.type`	string	+	Type of the VC code. Currently, the only allowed type is `alphaNumeric4`. Note that the type is "alphaNumeric4" to refer to the fact that in the future the 4-symbol code might also contain letters. For the time being, only numeric values are returned for technical reasons. This may change in the future, so RPs should make no assumptions about it containing numeric data only!
`vc.value`	string	+	Value of the VC code.

Notification based signature session creation response

{
  "sessionID": "ce305d54-45b4-a31b-2db2-fb6b9e546015",
  "vc": {
    "type": "alphaNumeric4",
    "value": "4927"
  }
}

signature session

Dynamic link based signature session

Error conditions

Request parameters

Response structure

Notification based signature session

Error conditions

Request parameters

Response structure

`signature` session

Dynamic link based `signature` session

Notification based `signature` session