Online signature API. Terms used in this document. The API in brief. Version 0.20,

Transcription

1 Online signature API Version 0.20, Terms used in this document Onnistuu.fi, the website Client, online page or other system using the API provided by Onnistuu.fi. End user, using the clients online page or other system. Document, the file, in PDF format, to be signed. Signature, the document signing performed using Onnistuu.fi, relating to the client, end user and document. The API in brief 1. Client collects the information required for signing. The required information consists of the required company registration codes and/or personal identification codes (i.e. social security numbers), and possible invitation parameters like addresses. 2. Client generates the document to be signed. 3. Client transmits the needed information about the signatures, invitations and document to Onnistuu.fi and transfers the end user to the Onnistuu.fi site, if there are signatures that should be collected immediately. 4. Onnistuu.fi collects the document from the clients server. 5. Onnistuu.fi collects the immediately required electronic signatures from the end user. 6. Onnistuu.fi transfers the end user back to the clients site and transmits information of the new, signed document version and the signatures collected. 7. If signature invitations need to be sent via or SMS message, they are sent. See more on this in section 3.3.

2 API access point Provided client information The client will receive the following information Name Type Example Client / customer identifier Encryption key Unique UUIDv4 string 256 bits encoded as a base64 string 3e c48-90defde5dbba5e9e Dw0coe6YCFdFZkHuALwsZjMd2PQuOC m2qfazkhc6qlc= The client identifier is public and is transmitted publicly on each API usage. The encryption key is secret and must never be revealed to end users or their browsers. The encryption key is used in its binary form, decoded from the base64 representation. Encryption The encryption used is Rijndael, CBC mode. Specifics of the encryption used: (Defaults in bold) Rijndael CBC mode A block size of 256 or 128 bits. An encryption key size of 256 bits. An initialization vector size of 256 or 128 bits. (depending on block size) Null or PKCS#5 padding. An initialization vector is generated for each API usage. The encrypted data and initialization vector are both transmitted. For AES compatibility, use block size 128, iv size 128 and PKCS#5 padding. Changing these options is discussed below in a section called Encryption options. With the AES compatible settings, you can test the encryption with these commands: openssl enc -aes-256-cbc -a -A -K <key-as-hex> -iv <iv-as-hex> -in plain.txt -out data.b64 openssl enc -aes-256-cbc -d -a -A -K <key-as-hex> -iv <iv-as-hex> -in data.b64 -out plain.txt

3 Detailed API phase documentation 1. Required information The client collects the required identification information for collecting the signatures. For private end users, this means their personal identification number (social security number), and for companies their company registration code. 2. Document requirements The document should be in the Adobe PDF format and under 2 megabytes in size. 3. Transmitting information and moving the end user The signature information and end user are transferred to Onnistuu.fi using a POSTrequest to the API access point Most information is kept secret by using the encryption that has been discussed earlier in this document. Required POST request fields (public) customer return_failure data iv The clients client / customer identifier as provided by Onnistuu.fi URL to return to in case of failure. Error codes are defined later in this document. The protected data fields, encrypted as discussed below. The initialization vector used for the encryption. Required protected data fields (encrypted) stamp return_success document requirements An identifier string generated by the client for this document / signing process URL to return a possible end user to, with the return data. The end user returning to this URL does not indicate success, the return data must be checked. URL from which Onnistuu.fi can fetch the document to be signed with a GET request. An array of requirements. The types and options are discussed below. Further optional fields are discussed later on.

4 Protected data representation The protected data fields are presented as JSON, for example: { } "stamp": " ", "return_success": " "document": " "requirements": [ {"type": "person", "identifier": " N"} ] This JSON string is encrypted with Rijndael 256 CBC with the key delivered to the client, using a unique initialization vector generated by the client for each request. POST request The clients customer id, the encrypted data (base64-encoded), the initialization vector (base64-encoded) and error condition return address are transmitted to Onnistuu.fi as a POST request, for example: <form method="post" action=" <input type="hidden" name="return_failure" value=" /> <input type="hidden" name="customer" value="90e07b0a-1ee6-4da0-92cc-bcea0d2af4e7" /> <input type="hidden" name="data" value="5gttb8nufmjty5nxz9m5f7thtxg5ujwlnnntpq5osdmuvoum8jyk3vr7t87 zcbej8yqsxi840pr2f6plp07/fsyis6wqqtdqcweizsx08dokdbhlaqblgqjfplytu Tmrzcm3KAeOJm12BFhn79NZQfy5HBCxb0rn+MAVEZzb9JAz3jH5iyX5ITXTHhfagX4 Bjyc44rObJ4Xjj1WK0oYX20mnr/M0ARDzm29mSbKVEF/Q7fxOMr2yp6ODij3vcPnGi qyv0eqvyjw4xjfbh4l0x7vnan9pfbgwg6m2kreuryykhnseo5jm8rqsvlph1p2vsht W1DND/npwDFxozI6QlaT31BlPZwJbwTxjkK5lBaXBUQNQx0Mwu7G1AVL8W+otS1Uin d5xwovl/xlmyuiwmgq8yv/7r75vpejmq/oja0adnhq/1huvo1mggj0yeb8wt1tx3/7 TLQLY+MDsTP27gA==" /> <input type="hidden" name="iv" value="zrde/ +5twpwPD6nrrUo9E/2oJqYHFpsAtUoSTMX0Pn4=" /> <input type="submit" value="sign" /> </form> Encryption options The encryption used can be modified with POST parameters: <form...> <input type="hidden" name="cipher" value="rijndael-128" /> <input type="hidden" name="padding" value="pkcs5" />... </form> These options will also be used for responses to this request. When left undefined, the options default to rijndael-256 and null.

5 3.1 Handling of failed signature situations By default, if an immediately required signature addition fails, Onnistuu.fi presents a page for selecting a new signing method. If the client wants the end user to return to their system after such failures, they can define the parameter return_after_failures in the request:... <input type="hidden" name="return_after_failures" value="1" />... Be aware, that in this case the end user is returned to the URI given in return_success. The return data will only include information about the signatures that were successful. 3.2 Defining an identification method in the request If only one signing is to be done, the identification method can be defined in the request, in which case Onnistuu.fi will directly forward the end user to the service:... <input type="hidden" name="auth_service" value="tupas-nordea" />... A list of available identification methods can be obtained with a GET request: 1ee6-4da0-92cc-bcea0d2af4e7/ It is returned as JSON: [{"name": "Osuuspankki", "value": "tupas-osuuspankki", "img": " {"name": "Nordea", "value": "tupas-nordea", "img": "

6 3.3 Sending signature invitations with the API request The request can contain requirements of the type " ". These requirements will cause invitations to be sent after the immediate signings. The client organization administrator will be sent notifications of new signatures. {... "requirements": [{"type": " ", "identifier": " D", " ": Return request for invitation requirements After each signing, Onnistuu.fi can send a return GET request to the client, if requested. (Note that this needs to be defined for each requirement) {... "requirements": [{"type": " ", "identifier": " D", " ": "[email protected]", "return_request_on_sign": "1"}]} The GET request is made to the return_success URL defined in the original API request SMS invitations A mobile phone number (MSISDN) can also be defined in the requirement, and will receive an SMS message with an invitation link and the confirmation hash. {... "requirements": [{"type": " ", "identifier": " D", " ": "[email protected]", "sms": " "}]} When using an SMS message, the invitation parts can be separated, such that the url is sent through and the hash in an SMS message. {... "requirements": [{..., "sms": " ", "separate_invite_parts":"1"}]} It is also possible to send a custom SMS message: {... "requirements": [{..., "sms": " ", "customized_sms": "You have received an invitation to sign contract ABC123 -ExampleCompany"}]} When sending a custom SMS message, the normal invitation SMS is not sent by default. There is an option to send both the custom SMS and the invitation SMS: {... "requirements": [{..., "sms": " ", "customized_sms": "You have received an invitation to sign contract ABC123 -ExampleCompany", "customized_sms_both":"1"}]}

7 3.3.3 Inviter details The request can also define inviter details to be shown in the invitation s and during the signing process. Onnistuu.fi doesn't cache the possibly defined logo image or css file, both of which should be served through HTTPS to avoid browser warnings. The given inviter address will be sent notifications on new signatures, is shown as the invitation sender, and will receive the possible comments from signers. Depending on the address' DNS settings this may affect delivery of invitations. {... "requirements": [{"type": " ", "identifier": " D", " ": xample.org/signature_logo.jpg","inviter_css":" nnistuu.css"}]} Disabling signer capabilities Each requirement can define certain signer capabilities to be disabled. This will only affect the user interface. The capabilities that can be disabled are 'download', 'comment' and 'remove'. { "requirements": [{"type":" ", "identifier": " D", " ": "[email protected]", "disable_capabilities": ["download", "comment", "remove"]}]} Invitation signing order requirements Ordering requirements can be defined for the invitations, and the invitations will be sent accordingly: type identifier order require_order [email protected] [email protected] F [email protected] 3 0 Here, the invitations with order numbers 1 and 2 will be sent at the time of the API request, and invitation 3 only after the first two signatures have been collected. The 'order' and 'require_order' fields should be integers in json. {... "requirements": [{..., "order":1, "require_order":1}]}

8 3.3.6 Disabling the 'all signed' for a signer The 'all signed' that notifies signers of the completion of the document signing process can be disabled. {..., "requirements": [ { "type": " ", "identifier": " D", " ": "[email protected]", "no_all_signed_mail": "1" } ]} Disabling the invitation for a signer The invitation itself can be disabled, if you wish to deliver the invitation yourself. The invitation details necessary are given in the api return data. The invitation will still be visible for the user if they log into onnistuu.fi and have the correct verified address. {..., "requirements": [ { "type": " ", "identifier": " D", " ": "[email protected]", "no_invitation_mail": "1" } ]} Disabling the signature added s for the inviter By default, the first organization contact of an inviting organization is sent an for each collected signature. This can be disabled: {..., "requirements": [ { "type": " ", "identifier": " D", " ": "[email protected]", "no_signature_added_mail": "1" } ]}

9 3.3.9 Requiring organization signatures The signature to be collected can be required to be made as an organization. If the signer has signing rights in an organization registered at Onnistuu.fi, they can use that validated information. Otherwise they will be asked for the name of the organization and their position giving the right to sign. This information is not checked for validity by Onnistuu.fi. {..., "requirements": [ { "type": " ", "identifier": " D", " ": "[email protected]", "sign_as_organization": "1" } ]} 3.4 Document category The request can define a category for the document. The category is identified by name and must already exist at Onnistuu.fi. Categories are organization specific. { } "stamp": " ", "return_success": " "document": " "category": "Example category", "requirements": [ {"type": "person", "identifier": " N"} ] 4. Document availability requirement The document to be signed needs to be available at the clients server for Onnistuu.fi, using a GET request. 5. Signature methods The end user signs the document in the Onnistuu.fi service.

10 6. Return data Onnistuu.fi returns the end user and return data as a redirected GET request. The return data consists of the new document version URI and information on the made signings. The data is delivered encrypted with Rijndael 256 CBC, using the clients encryption key and an initialization vector generated by Onnistuu.fi. The client decrypts the information using their key and the given initialization vector. data=5gttb8nufmjty5nxz9m5f7thtxg5ujwlnnntpq5osdmuvoum8jyk3vr7t87zc Bej8yQsxI840pr2f6plp07/FsyiS6wqQtDqcweIzsX08DOKdbHlaQBLgqjFpLYtuTm rzcm3kaeojm12bfhn79nzqfy5hbcxb0rn+mavezzb9jaz3jh5iyx5itxthhfagx4bj yc44robj4xjj1wk0oyx20mnr/m0ardzm29msbkvef/q7fxomr2yp6odij3vcpngiqy v0eqvyjw4xjfbh4l0x7vnan9pfbgwg6m2kreuryykhnseo5jm8rqsvlph1p2vshtw1 DND/npwDFxozI6QlaT31BlPZwJbwTxjkK5lBaXBUQNQx0Mwu7G1AVL8W+otS1Uind5 XWOvl/xLmyUIwmgq8yv/7R75VpEJMq/OJa0adNHq/1HuVo1MgGj0yEb8Wt1tx3/7TL QLY+MDsTP27gA== &iv=tuswcc8jsrjlexzzthir0lr3fc0qjsxsjvvnz2umzwe= The decrypted return data is presented as JSON: {"stamp": " ", "document": " 1621dc4ac8e6db32be3a7a/", "cancel": " c6ccbba5ae1d170b313f8/", "signatures": [{"type": "person", "identifier": " N", "name": "John Smith", "timestamp": " :23:34", "uuid": "544b78a2-e db9159d"}, {"type": "company", "identifier": " ", "name": "Example Oy", "timestamp": " :24:45", "uuid": "7aa3dd3d-b adb-e788e "}]} The return data fields are described in more detail on the next page. Note that the response information should not be made directly available to end users at any point Return information without a redirection When the api is used only for invitations, the client can request the return data to be served by Onnistuu.fi as JSON instead of redirecting to the return_success url with GET parameters. return_success is still required and will be used in return_request_on_sign cases. (3.3.1.) {"stamp": " ",..., "return_success": " "return_success_json":"1"} causes the response {"data":"...", "iv":"..."}

11 Return data fields stamp document cancel signatures invitations The API process identifier, as defined by the client system in the request. An URL for retrieval of the new document PDF file with a GET request. The document is embedded with the signature information. An URL for canceling the signing process with a GET request. Can only be used if there are still signatures missing. Returns a JSON true/false. The immediately collected signatures as an array. In the return_request_on_sign case, only includes the signature the request is being made for. The signature invitations created as described in section 3.3. If your system has existing authentication for the invited end users, you can provide them with links and keys to their invitations. Signature data fields type identifier name timestamp uuid Either "person" or "company". Should be used for determining how to process the identifier field. Either a PIN/SSN for a person or a company registration code for a company. The name of the signing entity. In the case of persons, provided by the bank on each authentication. An ISO 8601 date and time for when the signature was processed. An UUIDv4 identifier for the signature, for verifying the document and signatures at a later date. Invitation data fields url key The address the invitation was sent to, as defined in the request. The invitation url the end user will use to add the document to their signing cart. A string the end user will be asked to enter to add the document.

12 Document verification The documents can be verified in the client system with a GET request to Onnistuu.fi: df43e7ed272e/ or optionally df43e7ed272e/sha1/a584099c99c103a57b2364b0d904c5f0c3971f09/ where the customer field is the clients customer id, the document field a documents UUID id and the optional sha1 field a hex encoded SHA1 hash of the document file. Onnistuu.fi will return JSON: {"document":"b c-477a-abd8-df43e7ed272e","signatures": [{"uuid":"a34a664e-57f4-45e4-b33b-9d4b b","name":"demo Nordea","timestamp":" :38:14"},{"uuid":"4a981a1c-2d b-59d641b3c4c5","name":"Testaaja Teemu, Testiyritys Oy","timestamp":" :39:53"}]} where the document field confirms the existence of the document and the signatures list the added signatures. The signer names and timestamps are only shown if the given SHA1 hash corresponds to a version of the document containing the signature. The beginning of the document verification URI shown on top of each document page can be defined with the field "document_check_url" in the JSON request: {"stamp": " ",..., "document_check_url": " If the verification address beginning is not specified, the Onnistuu.fi default verification service URI is used.

13 Error situations In the case of errors, Onnistuu.fi returns the end user to the given error page with an error message: onnistuu_error=60&onnistuu_message=could%20not%20fetch%20document Error codes 10 Invalid client customer id 20 The request could not be decrypted 21 The requested cipher is invalid 22 The requested padding is invalid 30 The success return address is invalid 40 The document retrieval address is invalid 50 The signature requirements are erroneous 60 The document could not be retrieved from the client system 70 The document file is too large 80 The document is not a valid PDF file 90 The requested identification service provider is invalid 100 return_failure address is invalid 110 Request was not POST 111 Request POST data was empty 120 An internal error occurred at Onnistuu.fi 140 Document check address invalid 150 Document category invalid 210 User cancelled signing before selecting an identity provider 220 User cancelled signing at an identity provider 230 User cancelled signing, last error was possible ssn mismatch