Universign Guide 8.12.1 SNAPSHOT
Universign Guide 8.12.1 SNAPSHOT
Universign Guide 8.12.1 SNAPSHOT
Any total or partial reproduction of this document, without prior express au-
thorisation from Universign, would constitute an infringement punishable under
French law.
Universign
5-7 rue du Faubourg Poissonnière
F-75009 Paris
France
Tel: +33 1 44 08 73 00
Fax: +33 1 43 56 50 42
https://www.universign.com
1 Introduction 4
2 General Information 5
2.1 Signature modes . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.1 Document signature (server side) . . . . . . . . . . . . . 5
2.1.2 Contract signature (client side) . . . . . . . . . . . . . . . 5
2.1.3 Contract signature (client side) with signer registration . . 5
2.2 Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.3 Authentication and confidentiality . . . . . . . . . . . . . . . . . 8
2.4 Signature format and standard . . . . . . . . . . . . . . . . . . . 8
2.5 Services pre-configuration . . . . . . . . . . . . . . . . . . . . . 8
2.6 Documents retention policy and documents retrieval . . . . . . . . 9
4 Data objects 12
4.1 SignOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2 TransactionRequest . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3 TransactionSigner . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.4 RegistrationRequest . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.5 TransactionDocument . . . . . . . . . . . . . . . . . . . . . . . . 19
4.6 SignatureField . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.7 SEPAData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.8 SEPAThirdParty . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.9 TransactionResponse . . . . . . . . . . . . . . . . . . . . . . . . 22
4.10 TransactionInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.11 SignerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.12 InitiatorInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.13 CertificateInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.14 TransactionFilter . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.15 StandaloneRegistrationRequest . . . . . . . . . . . . . . . . . . . 26
SIGNATURE-GUIDE VERSION: 8.12.1-SNAPSHOT
1 Introduction
This document explains general functionalities of the U NIVERSIGN Signature Ser-
vice and how to integrate it with existing applications.
This document is structured as follows:
• section 3 is a guide to the API used to configure and use the service;
While great care has been taken to make integration as simple as possible, the
reader is assumed to be familiar with programming concepts in the language used
for integration.
2 General Information
2.1 Signature modes
The U NIVERSIGN signature service proposes three modes of signature.
• one or more signers, who are invited one after another to sign the documents
using a user-friendly web interface.
The creation of the transaction, the retrieval of the signed documents and the
retrieval of information on the status of a transaction are made through the U NI -
VERSIGN Web Service API by the requester. The requester also chooses which
certificate types are allowed for the signers to use.
The selection of the private key to use, the approval of the terms of the docu-
ments and the launching of signature process are made by the signer. Each signer
reaches the signature web interface via an URL containing a unique id. Each
signer receives his URL by mail, except possibly the first if the requester chooses
to.
Those interactions are depicted with a very simple example on figure 1.
This mode has an extension which is described in the following section.
a certified signature. In order to register his identity, a user should send his ID
documents to Universign RA, this can be done in two ways:
• French ID card.
• French Passport.
• Residence Permit.
• Check his identity information by indicating his birth date and confirming it
and his phone number. The birth date may was already indicated when the
transaction was requested with setting the birthDate key of the
TransactionSigner data object.
• Provide his ID documents. If they were sent when requesting the trans-
action, then they will be displayed and locked so that the user cannot edit
them.
2.2 Protocol
In order to allow integration from many different platforms and languages, U NI -
VERSIGN has chosen to provide a Web Services type API, under the form of
XML-RPC (Remote Procedure Call). XML-RPC protocol allows the consistent
transmission of parameters from any platform and has built-in support in many
languages. For language with no support of this protocol, or if you wish to re-
implement an XML-RPC library, the XML-RPC language specification is avail-
able at http://www.xmlrpc.com/.
The following conventions are in use with the U NIVERSIGN signature service:
• In the API, all parameters which are not XML-RPC predefined types are
XML-RPC structs (e.g. hashtables or maps or dictionaries depending on
your programming language). All keys in XML-RPC structs are case sen-
sitive.
• In the API, all methods for which the return value is not specified return the
integer 0.
The signature field needs to be activated and personnalized in size and content
to be used. The content can be a composition of images and texts.
An URL for status push in the client signature mode. A GET HTTP request will
be performed on this optional property each time a signature step is com-
pleted (i.e. each time a signer succeeds, fails or cancels its signature).Three
parameters are set to the request:
Elements for the web interface personnalization : a logo and a company name
that will be displayed on the signature web page.
• requester.cancelTransaction(String transactionId)
Cancel a transaction in progress with this id.
• TransactionResponse requester.requestRegistration(
StandaloneRegistrationRequest request)
Requests the standalone registration of the signer. Sends the signer identity
to be certified and returns an URL where the signer should be redirected
to. The registration process is similar to the transaction one but without
documents to sign.
• requester.requestTwoStepsRegistration(
StandaloneRegistrationRequest request)
Since 8.4
Requests a two steps standalone registration of the signer. This service
should be called by an operator after a face-to-face meeting with the signer.
It sends the signer’s identity to be certified including his identity documents.
Once the identity documents are validated by Universign, an email will be
sent to the signer with an URL where he can review his identity information
and agree to the Universign Services Subscription Form. This registration
process is similar to the transaction one but without documents to sign.
4 Data objects
In this section are presented the structure of the data objects used in the API.
All data structures are XML-RPC structs (i.e. dictionaries). The first column
contains the key and a letter which can be:
The second column is the type of the corresponding value. The third column
contains additional information about the parameter such as the optionality, details
about the data format. . .
4.1 SignOptions
The SignOptions data structure contains options for a document signature and
allows to specify a signature profile to use.
patternName [O] string The name of the pattern for the signature field.
4.2 TransactionRequest
The TransactionRequest data structure contains informations and options for a
Signature transaction creation.
finalDocCCeMails [O] String[] This option allows to send a copy of the final signed
documents to a list of email addresses. This copy is
send as cc for every final signed documents email ad-
dressed to a signer. For this option to be taken into ac-
count, the option finalDocSent must be sent to True.
twoStepsRegistration [O] boolean This option allows registration of signers via a two
steps registration process. When activated, the Regis-
trationRequest bean becomes mandatory for each of the
unregistered TransactionSigners, the certicateType
must be set to advanced, the phoneNumber and the
birthDate must be set.
Default value is False.
4.3 TransactionSigner
A TransactionSigner describes and contains options for a document signer.
4.4 RegistrationRequest
The RegistrationRequest data structure contains information for the signer
registration.
4.5 TransactionDocument
The TransactionDocument data structure contains information about a transac-
tion document.
content [O] byte[] The raw content of the PDF document. You can
provide the document using the url field, other-
wise this field is mandatory.
url [O] string The URL to download the PDF document. Note
that this field is mandatory if the content is not
set.
fileName string The file name of this document.
signatureFields [O] DocSignatureField[] A description of a visible PDF signature field.
checkBoxTexts [O] String[] Texts of the agreement checkboxes. The last one
should be the text of the checkbox related to sig-
nature fields labels agreement.
This attribute should not be used with docu-
ments of the type "pdf-for-presentation". Since
agreement for "pdf-for-presentation" is not cus-
tomisable.
metaData [O] Struct This structure can only contain simple types like
integer, string or date.
title [O] String A title to be used for display purpose.
SEPAData [O] SEPAData A structure containing data to create a SEPA
mandate PDF.
4.6 SignatureField
The SignatureField data structure describes the content of a PDF visible signa-
ture field. A default Pattern of signature is provided by Universign. This pattern
is customizable (see 2.5).
4.7 SEPAData
The SEPAData data structure contains information needed to create a SEPA man-
date PDF.
4.8 SEPAThirdParty
The SEPAThirdParty data structure is used to define information on both the
debtor and the creditor of a SEPA mandate.
4.9 TransactionResponse
The TransactionResponse data structure is the response sent after a request
for a transaction. This structure is used as a return value only, and will never be
instantiated by users.
4.10 TransactionInfo
The TransactionInfo data structure describes the status of a transaction. This
structure is used as a return value only, and will never be instantiated by users.
signerInfos SignerInfo A list of bean containing information about the signers and
their progression in the signature process.
currentSigner int The index of current signer if the status of transaction is ready
or who ended the transactions for other status.
creationDate date The creation date or last relaunch date of this transaction.
description String The description of the Transaction.
initiatorInfo InitiatorInfo A bean containing information about the requester of a trans-
action.
eachField Boolean whether the transaction was requested with requesting hand-
written signature for each signature field or not.
customerId String This id can be specified when creating the transaction request
and is used as additional information to identify the transac-
tion.
transactionId String This id is generated when creating the transaction request and
is the unique identifier of this transaction.
4.11 SignerInfo
The SignerInfo data structure describes the status of a signer. This structure is
used as a return value only, and will never be instantiated by users.
4.12 InitiatorInfo
The InitiatorInfo data structure describes the requester of a transaction. This structure is used
as a return value only, and will never be instantiated by users.
4.13 CertificateInfo
The CertificateInfo struct contains information about a certificate. This structure is used as a
return value only, and will never be instantiated by users.
4.14 TransactionFilter
Warning: this object has an experimental structure. While it is considered production qual-
ity, it is subject to change in future versions.
The TransactionFilter struct is a filter on transactions.
4.15 StandaloneRegistrationRequest
The StandaloneRegistrationRequest data structure contains the information about the signer
to register and allows to specify a signature profile to use.
Error codes
73002 An error occurred when signing the PDF document.
73004 An error occurred when retrieving a stored private key.
73010 The login and/or password are invalid.
73011 & 73013 The requesting user doesn’t have a valid signing account or its signing account
is inactive.
73014 When retrieving the document, the transaction id is missing or wrong.
73020 Malformed request. Typically, an invalid value has been set, the TransactionRequest
misses some mandatory elements or has some incompatible elements. The message at-
tached to the RPC fault contain more accurate information.
73025 The used transaction id or custom id is invalid.
73027 Requesting an action on a transaction which status doesn’t allow this action (e.g requesting
the documents of an unfinished transaction).
73040 Internal server error.
73070 The requested document is being retrieved asynchronously from archival, it may take few
hours. A further request will return the document.
References
[1] Draft ETSI TS 102 778, PDF Advanced Electronic Signatures (PAdES), v0.0.17. Technical
Specification, May 2009.
[2] HTTP Authentication: Basic and Digest Access Authentication
http://www.ietf.org/rfc/rfc2617.txt
[3] Document Management - Portable Document Format - Part 1: PDF 1.7
http://www.adobe.com/devnet/acrobat/pdfs/PDF32000_2008.pdf