42
[email protected] elevenpaths.com Web Services Reference SealSign BSS (Biometric Signature Services) ElevenPaths, radical and disruptive innovation in security solutions

Web Services Reference SealSign BSS

Embed Size (px)

Citation preview

Page 1: Web Services Reference SealSign BSS

[email protected]

elevenpaths.com

Web Services Reference SealSign BSS

(Biometric Signature Services)

ElevenPaths, radical and disruptive innovation in security solutions

Page 2: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 2 of 42

Table of content

1 Introduction ................................................................................................................ 5

2 SealSign BSS's Web Service Interfaces ......................................................................... 6

2.1 Common classes ....................................................................................................................... 6

2.1.1 BiometricSignatureVerification .................................................................................................. 6

2.1.2 BiometricSignatureParameters .................................................................................................. 7

2.1.3 BiometricImageParameters ........................................................................................................ 7

2.1.4 BiometricVerificationParameters ............................................................................................... 8

2.1.5 BiometricSignatureReference .................................................................................................... 8

2.2 Common Enumerations ............................................................................................................ 9

2.2.1 BiometricSignatureType ............................................................................................................. 9

2.2.2 BiometricSignatureFlags ........................................................................................................... 10

2.2.3 BiometricVerificationFlags ....................................................................................................... 10

2.2.4 BiometricVerificationResult...................................................................................................... 11

2.2.5 BiometricVerificationStatus ..................................................................................................... 11

3 SOAP 1.1 Biometric Signature Verification Service ...................................................... 12

3.1 Methods .................................................................................................................................. 12

3.1.1 Verify ........................................................................................................................................ 12

3.1.2 GetInfo ...................................................................................................................................... 13

3.1.3 GetInfoFromBiometricState ..................................................................................................... 14

4 SOAP 1.2 Biometric Signature Verification Service ...................................................... 15

4.1 Classes..................................................................................................................................... 15

4.1.1 BiometricVerificationRequest .................................................................................................. 15

4.1.2 BiometricVerificationResponse ................................................................................................ 16

4.1.3 BiometricGetInfoRequest ......................................................................................................... 16

4.1.4 BiometricGetInfoFromBiometricStateRequest ........................................................................ 16

4.1.5 BiometricGetInfoResponse ...................................................................................................... 17

4.2 Methods .................................................................................................................................. 17

4.2.1 Verify ........................................................................................................................................ 17

4.2.2 GetInfo ...................................................................................................................................... 17

4.2.3 GetInfoFromBiometricState ..................................................................................................... 18

5 Distributed Signature on Client Equipment ................................................................. 19

5.1 Architecture of the Distributed Signature .............................................................................. 19

5.2 Client signature component (SealSignBSSPanel) .................................................................... 20

5.3 Offline Distributed Signature .................................................................................................. 20

Page 3: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 3 of 42

6 Backend Distributed Signature Service SOAP 1.1 ........................................................ 21

6.1 Classes..................................................................................................................................... 21

6.1.1 BiometricSignatureBeginResponseBasic .................................................................................. 21

6.1.2 OfflineBiometricSignature ........................................................................................................ 22

6.1.3 OfflineBiometricSignatureProvider .......................................................................................... 22

6.2 Methods .................................................................................................................................. 23

6.2.1 BeginSignature ......................................................................................................................... 23

6.2.2 BeginSignatureProvider ............................................................................................................ 24

6.2.3 EndSignature ............................................................................................................................ 25

6.2.4 EndSignatureProvider ............................................................................................................... 25

6.2.5 SyncOfflineSignatures............................................................................................................... 26

6.2.6 SyncOfflineSignaturesProvider ................................................................................................. 26

6.2.7 HeartBeat ................................................................................................................................. 27

7 SOAP 1.2 Backend Distributed Signature Service ........................................................ 28

7.1 Classes..................................................................................................................................... 28

7.1.1 BiometricSignatureBeginRequest ............................................................................................. 28

7.1.2 BiometricSignatureBeginProviderRequest ............................................................................... 29

7.1.3 BiometricSignatureBeginResponse .......................................................................................... 30

7.1.4 BiometricSignatureEndRequest................................................................................................ 30

7.1.5 BiometricSignatureEndProviderRequest .................................................................................. 30

7.1.6 BiometricSignatureEndResponse ............................................................................................. 31

7.1.7 BiometricSignatureSyncOfflineRequest ................................................................................... 31

7.1.8 BiometricSignaturesSyncOfflineRequest .................................................................................. 32

7.2 Methods .................................................................................................................................. 32

7.2.1 BeginSignature ......................................................................................................................... 32

7.2.2 BeginSignatureProvider ............................................................................................................ 33

7.2.3 EndSignature ............................................................................................................................ 33

7.2.4 EndSignatureProvider ............................................................................................................... 34

7.2.5 SyncOfflineSignatures............................................................................................................... 34

7.2.6 SyncOfflineSignaturesProvider ................................................................................................. 34

7.2.7 HeartBeat ................................................................................................................................. 35

8 Document Providers .................................................................................................. 36

8.1 IDocumentProvider Interface ................................................................................................. 36

8.2 Registro de Proveedores de Documentos .............................................................................. 36

9 Bindings WCF of SealSign ........................................................................................... 37

9.1 Types of WCF Bindings in SealSign ......................................................................................... 37

9.1.1 BasicHttpBinding (Soap 1.1) ..................................................................................................... 37

9.1.2 WSHttpBinding (Soap 1.2) ........................................................................................................ 37

9.2 Setup of the WCF Bindings in SealSign without SSL ............................................................... 38

9.3 Setup of the WCF Bindings in SealSign with SSL ..................................................................... 38

Page 4: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 4 of 42

9.4 Calling of the SealSign and WCF Bindings Services................................................................. 38

9.4.1 Call of the SealSign services with the WCF Binding by default ................................................. 38

9.4.2 Call of the SealSign services with a specific WCF Binding ........................................................ 38

9.4.3 Typical call for SealSign Services .............................................................................................. 39

10 Resources ................................................................................................................. 41

Page 5: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 5 of 42

1 Introduction

SealSign Biometric Services (BSS) is a product developed entirely by Smart Access S.L. and the Carlos III University of Madrid, designed to facilitate the integration of the biometric handwritten signature with corporate applications.

There are various problems when it comes to the use of electronic signatures which hinder the adoption of such in certain scenarios. These problems range from users' lack of knowledge and reluctance to use a digital certificate to the impossibility of the use of secure storage devices, such as smart cards, in certain mobile handsets.

To resolve said scenarios where the use of digital certificates is not easily adaptable, SealSign BSS provides the necessary technology to use the handwritten signature by means of the capture, extraction and recognition of biometric patterns which ensure the authenticity of the signature.

SealSign BSS's handwritten signature capture process allows capture both with PCs (using a digitising tablet) and touch screens as used on many current mobile devices such as iPad, iPhone, Windows or devices with Android Operating Systems.

SealSign BSS displays its functions through Web Services based on Windows Communication Framework (WCF) technology. These services can be accessed and the applications therein implemented through most of the technology on the market.

For examples of the most common integration use cases, you may consult the various application integration guides from SealSign BSS, available for each one of the supported development technologies.

Page 6: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 6 of 42

2 SealSign BSS's Web Service Interfaces

Given the diversity of technology available on the market and with the objective of being accessible from the majority of corporate applications, SealSign BSS's web services are accessible through two interfaces:

Interface based on the SOAP 1.1 (BasicHttpBinding) specification.

Interface based on the SOAP 1.2 and WS-Addressing (WsHttpBinding) specification.

According to the technology and the capability of the client application, it will be possible to use one or other of the interfaces.

The SOAP 1.1 interface displays the following Web Services:

Biometric signature service (BiometricSignatureServiceBasic.svc): provides the capabilities of distributed signature and signature verification.

The SOAP 1.2 interface displays the following Web Services:

Servicio de firma biométrica (BiometricSignatureService.svc): provides the capabilities of distributed signature and signature verification.

The services will be accessible in the SealSignBSSService virtual directory. For example: http://localhost/sealsignbssservice/ biometricsignatureservice.svc.

2.1 Common classes

The following classes are used as parameters in the Web services regardless of the interface they publish:

2.1.1 BiometricSignatureVerification The Verify method returns an object of this class after the signature verification process of a document. The BiometricSignatureVerification class is defined as follows:

public class BiometricSignatureVerification

{

public BiometricVerificationResult result;

public BiometricSignatureReference[] signatures;

public SignatureVerification dssResult;

}

Members

result: Indicates the general result of the signature process, possible values are:

o SignatureFound: At least one biometric signature was found in the document

o SignatureNotFound: No biometric signature was found in the document

signatures: Array with the validation information for each of the signatures found in the document.

dssResult: If support electronic signatures are found in the document, this will contain a SignatureVerification class object with the result of the validation of the electronic signatures.

Page 7: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 7 of 42

For a complete description of the SignatureVerification type refer to the SealSign DSS's Web Services Reference guide.

2.1.2 BiometricSignatureParameters The BiometricSignatureParameters class is defined as follows:

public class BiometricSignatureParameters

{

public BiometricImageParameters imageParameters;

public BiometricImageParameters[] advancedImageParameters;

public string documentPassword;

}

Members

imageParameters: BiometricImageParameters class object which allows the customisation of some parameters which govern the inclusion of the biometric signature image in the document. If a null is specified in this member, the default settings made at server level will be applied. For more information see the description of the BiometricImageParameters class in the following section.

advancedImageParameters: Array of BiometricImageParameters objects which allows the advanced customisation of some parameters which govern the inclusion of the biometric signature image in the document. If previous attribute (imageParameters) is defined, the content of advancedImageParameters will not be applied. You can add as many elements as needed.

documentPassword: Makes it possible to specify the password for documents that have been password protected and which will be used to open the folder to be signed.

2.1.3 BiometricImageParameters The BiometricImageParameters class allows the customisation of some parameters which govern the inclusion of the biometric signature image in a document. This class is defined as follows:

public class BiometricImageParameters

{

public string attachmentName;

public bool signatureVisible;

public string imageTokenText;

public int offsetX;

public int offsetY;

public bool autoSize;

public int height;

public int width;

public int rotate;

public bool onAllPages;

public int onPage;

public bool onLastPage;

public int pageOffset;

}

Members

attachmentName: Name of the embedded attachment where signature image must be printed or null (PDF only).

Page 8: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 8 of 42

signatureVisible: Boolean which indicates if the signature image will be visible in the document resulting from the signature operation.

imageTokenText: Only PDF documents. By providing this token string, the platform will include the biometric signature image over all occurrences of the PDF chunk of text in the document. So, it won’t be necessary to specify the positions in the parameters. This is especially useful when working with complex documents. Size and rotation will be obtained from the imageParameters attribute.

offsetX: Allows the user to indicate the value of the X coordinate in pixels, taken from the bottom left-hand corner of the page where the signature image appears.

offsetY: Allows the user to indicate the value of the Y coordinate in pixels, taken from the bottom left-hand corner of the page where the signature image appears.

autoSize: Boolean which allows the user to indicate if the signature image will be resized automatically or if the parameters height and width will be used.

height: The height of the signature image in pixels.

width: The width of the signature image in pixels.

rotate: Allows the user to indicate the angle of rotation of the signature image. Its possible values are 0, 90, 180 or 270.

onAllPages: Indicates if the signature image should be included on all pages of the document.

onPage: Indicates the page number where the signature image will be included.

onLastPage: Boolean that indicates whether the graph will be displayed on the last page of the signed document.

pageOffset: Whole number that indicates the positive or negative displacement of the signature, in page numbers, with regard to the current position.

2.1.4 BiometricVerificationParameters The BiometricVerificationParameters class represents those parameters which are necessary for the validation of the signature and which are not included within the signature itself.

public class BiometricVerificationParameters

{

public string documentPassword;

}

Members

documentPassword: Makes it possible to specify the password for documents that have been password protected and which will be used to open the folder to be verified.

2.1.5 BiometricSignatureReference Each object in this class represents the information that describes a biometric signature. The BiometricSignatureReference class is defined as follows:

public class BiometricSignatureReference

{

public string version;

public string signatureID;

public string signatureAccount;

public string signatureUserName;

Page 9: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 9 of 42

public double score;

public BiometricVerificationStatus signatureStatus;

public SignatureProfile signatureProfile;

public BiometricSignatureType signatureType;

public DateTime signingTime;

public TimestampReference timestamp;

}

Members

version: Version number of the signature format used.

signatureID: Value of the ID field provided by the calling application during the signature process.

signatureAccount: Value of the Account field provided by the calling application during the signature process.

signatureUserName: Name of the user the signature belongs to.

score: Score obtained during the process of comparing the document signature and the signature being validated.

signatureStatus: Status of the signature after the verification process. For more information on the possible values see the description of the BiometricVerificationStatus enumerated type.

signatureProfile: Indicates the profile of the biometric signature.

signingTime: Specifies the date and time that the signature was made.

timestamps: Array of TimestampReference type objects with the information corresponding to the timestamps included in this signature. If the signature does not contain timestamps this member will report a null value. For a complete description of the TimestampReference type please refere to the SealSign DSS's Web Services Reference guide.

2.2 Common Enumerations

The following enumerated types are used as parameters in the Web services regardless of the interface they publish:

2.2.1 BiometricSignatureType Indicates the different signature storage formats supported by SealSign BSS.

public enum BiometricSignatureType

{

Default = 0,

Signature = 1

}

Values

Default: Use the default signature storage format (Signature).

Signature: The signature is stored contained within the document.

Page 10: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 10 of 42

2.2.2 BiometricSignatureFlags The BiometricSignatureFlags enumerated type is used both in document signing operations and in the verification of such.

public enum BiometricSignatureFlags

{

None = 0,

Default = 1,

VerifyIdentity = 2,

IncludeTimestamp = 4,

BiometricImageAsWidgetBackground = 8,

IncludeHashWatermark = 16,

IncludeAttachments = 32,

ExcludeDocumentMetadata = 64,

IncludeIdWatermark = 128,

IncludeAccountWatermark = 256,

XMLBiometricSignatureDetached = 512

}

Values

None: Do not specify any signature flag.

Default: Use the default values for the signature. The default values will be composed based on the options ticked in the administration tool.

VerifyIdentity: The biometric signature must be verified to check the identity of the person signing.

IncludeTimestamp: Include the timestamp information in the signature.

BiometricImageAsWidgetBackground: Include the biometric signature image as the background image for the signature visualisation widget.

IncludeHashWatermark: Include the document's hash as a watermark in the signature visualisation widget.

IncludeAttachments: Include the portfolio's attachments in the signature.

ExcludeDocumentMetadata: It does not include the metadata field of the signature (Id and Account).

IncludeIdWatermark: Includes the field Id of the signature as a watermark.

IncludeAccountWatermark: Includes the Account of the signature as a watermark.

XMLBiometricSignatureDetached: Saves the biometric XML signature separately.

2.2.3 BiometricVerificationFlags Allows the user to configure the type of signature verification that SealSign BSS will perform.

public enum BiometricVerificationFlags

{

None = 0,

Default = 1,

IncludeDSSInfo = 2

}

Values

None: Do not specify any verification flag.

Page 11: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 11 of 42

Default: Use the default values for the verification. The default values will be composed based on the options ticked in the administration tool.

IncludeDSSInfo: The verification information for the support electronic signatures found in the document will be returned.

2.2.4 BiometricVerificationResult Indicates the general result of the validation process of a SealSign BSS biometric signature.

public enum BiometricVerificationResult

{

SignatureFound = 0,

SignatureNotFound = 1

}

Values

SignatureFound: At least one biometric signature was found.

SignatureNotFound: No biometric signature was found.

2.2.5 BiometricVerificationStatus Specifies the status of a signature after verification of such according to the following values:

public enum BiometricVerificationStatus

{

Match = 0,

NoMatch = 1,

SignatureCorrupted = 2,

Failure = 3,

Unknown = 4,

}

Values

Match: The biometric signature corresponds to the specified user.

NoMatch: The biometric signature does not correspond to the specified user.

SignatureCorrupted: The current signature is not valid, either because the signature has been modified or because the document has been modified.

Failure: An error occurred during the verification process.

Unknown: An unknown error occurred during the verification process.

Page 12: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 12 of 42

3 SOAP 1.1 Biometric Signature Verification Service

SealSign BSS's BiometricSignatureServiceBasic.svc service displays the methods necessary for the validation of biometric signatures through a SOAP 1.1 (basic HttpBinding) web service.

The signature verification service displays the Verify, GetInfoFromBiometricState and GetInfo methods which allow the user to verify and obtain the information for each of the signatures included in a document.

The following sections contain a description of both the interface for this method and the classes and types related to such.

3.1 Methods

3.1.1 Verify Performs the verification of the signature(s) contained in the document against a signature captured using one of the supported devices. This method is responsible for receiving both the document to be validated and the various settings to be used in the validation process, returning all the verification information corresponding to the elements that constitute the signature in said process.

Syntax

public BiometricSignatureVerification Verify(

SignatureProfile signatureProfile,

BiometricSignatureType biometricSignatureType,

string id,

string account,

BiometricVerificationFlags biometricOptions,

BiometricVerificationParameters biometricParameters,

byte[] biometricState,

byte[] detachedSignature,

byte[] document

);

Entry Parameters

signatureProfile: Indicates the profile of the biometric signature to be generated. Its value must be one of the possible PDF or Office signature profiles (for XPS documents).

biometricSignatureType: Type of biometric signature to be validated. For more information see the description of the BiometricSignatureType enumerated type.

id: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

account: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

biometricOptions: Receives one or more values of the BiometricVerificationFlags type which specify the different verification options for the signature. For more information see the description of the BiometricVerificationFlags enumerated type.

biometricParameters: BiometricVerificationParameters type object which adds certain parameters necessary for the validation of some types of signatures. This parameter is reserved for future use, the value should currently be reported as null.

Page 13: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 13 of 42

biometricState: Byte array with the biometric signature data which is used to validate the document. This byte array is obtained by capturing a biometric signature through the client components of the different platforms supported by SealSign BSS.

detachedSignature: Where a detached signature is to be used, the byte array representing the detached signature in question is passed in via this parameter. Otherwise, a value of null should be passed in.

document: Byte array with the content of the document to be verified.

Return

Returns a BiometricSignatureVerification class object with all the validation information obtained in the signature verification process or an exception in the event that some type of error occurs.

Comments

The signatureProfile parameter is used to see the type of validation that will be performed based on the type of document. When the exact profile of the signature is unknown, at least the high level profiles must be indicated (SignatureProfile.PDF o SignatureProfile.Office) which will inform the validator as to whether the document type is PDF or XPS.

3.1.2 GetInfo Returns all the information corresponding to the signature(s) included in a document. Unlike the Verify method, this method does not perform the validation of the signatures against a captured signature but rather simply enumerates the information contained in the document.

Syntax

public BiometricSignatureVerification GetInfo(

SignatureProfile signatureProfile,

byte[] document

);

Entry Parameters

signatureProfile: Indicates the profile of the biometric signature to be validated. Its value must be one of the possible PDF or Office signature profiles (for XPS documents).

document: Byte array with the content of the document to be verified.

Return

Returns a BiometricSignatureVerification class object with all the validation information obtained in the signature information obtaining process or an exception in the event that some type of error occurs.

Comments

The signatureProfile parameter is used to see the type of validation that will be performed based on the type of document. When the exact profile of the signature is unknown, at least the high level profiles must be indicated (SignatureProfile.PDF o SignatureProfile.Office) which will inform the validator as to whether the document type is PDF or XPS.

Page 14: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 14 of 42

3.1.3 GetInfoFromBiometricState Returns all the information corresponding to the signature(s) included in biometric state returned by the client component.

Syntax

BiometricSignatureVerification GetInfoFromBiometricState(

SignatureProfile signatureProfile,

Guid instance,

byte[] biometricState,

byte[] document

);

Entry Parameters

signatureProfile: Indicates the profile of the biometric signature to be validated. Its value must be one of the possible PDF or Office signature profiles (for XPS documents).

instance: Transaction identifier for the signature returned by the client component.

biometricState: Byte array for the distributed signature status returned by the client component.

document: Byte array with the content of the document to be verified.

Return

Returns a BiometricSignatureVerification class object with all the validation information obtained in the signature information obtaining process or an exception in the event that some type of error occurs.

Comments

The signatureProfile parameter is used to see the type of validation that will be performed based on the type of document. When the exact profile of the signature is unknown, at least the high level profiles must be indicated (SignatureProfile.PDF o SignatureProfile.Office) which will inform the validator as to whether the document type is PDF or XPS.

Page 15: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 15 of 42

4 SOAP 1.2 Biometric Signature Verification Service

SealSign BSS's BiometricSignatureServiceBasic.svc service displays the methods necessary for the validation of biometric signatures through a SOAP 1.2 (basic HttpBinding) web service.

The signature verification service displays the Verify, GetInfoFromBiometricState and GetInfo methods which allow the user to verify and obtain the information for each of the signatures included in a document.

4.1 Classes

4.1.1 BiometricVerificationRequest Entry parameter for the Verify method.

public class BiometricVerificationRequest

{

public SignatureProfile signatureProfile;

public BiometricSignatureType biometricSignatureType;

public string id;

public string account;

public BiometricVerificationFlags biometricOptions;

public BiometricVerificationParameters biometricParameters;

public byte[] biometricState;

public byte[] detachedSignature;

public Stream document;

}

Attributes

signatureProfile: Indicates the profile of the biometric signature to be validated. Its value must be one of the possible PDF or Office signature profiles (for XPS documents).

biometricSignatureType: Type of biometric signature to be validated. For more information see the description of the BiometricSignatureType enumerated type.

id: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

account: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

biometricOptions: Receives one or more values of the BiometricVerificationFlags type which specify the different verification options for the signature. For more information see the description of the BiometricVerificationFlags enumerated type.

biometricParameters: BiometricVerificationParameters type object which adds certain parameters necessary for the validation of certain types of signature. This parameter is reserved for future use, the value should currently be reported as null.

biometricState: Byte array with the biometric signature data which is used to validate the document. This byte array is obtained by capturing a biometric signature through the client components of the different platforms supported by SealSign BSS.

detachedSignature: In the case of a detached signature, the corresponding byte array will be sent to said detached signature. For non-detached signatures a null value will be sent.

document: Stream with the content of the document to be verified.

Page 16: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 16 of 42

4.1.2 BiometricVerificationResponse Exit parameter for the Verify method.

public class BiometricVerificationResponse

{

public BiometricSignatureVerification signatureVerification;

}

Attributes

signatureVerification: BiometricSignatureVerification class object with all the validation information obtained in the signature verification process.

4.1.3 BiometricGetInfoRequest Entry parameter for the GetInfo method.

public class BiometricGetInfoRequest

{

public SignatureProfile signatureProfile;

public Stream document;

}

Attributes

signatureProfile: Indicates the profile of the biometric signature to be validated. Its value must be one of the possible PDF or Office signature profiles (for XPS documents).

document: Stream with the content of the document to be verified.

4.1.4 BiometricGetInfoFromBiometricStateRequest Entry parameter for the GetInfoFromBiometricState method.

public class BiometricGetInfoFromBiometricStateRequest

{

public SignatureProfile signatureProfile;

public Guid instance;

public byte[] biometricState;

public Stream document;

}

Attributes

signatureProfile: Indicates the profile of the biometric signature to be validated. Its value must be one of the possible PDF or Office signature profiles (for XPS documents).

instance: Transaction identifier for the signature returned by the client component.

biometricState: Byte array for the distributed signature status returned by the client component.

document: Stream with the content of the document to be verified.

Page 17: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 17 of 42

4.1.5 BiometricGetInfoResponse Exit parameter for the GetInfo method.

public class BiometricGetInfoResponse

{

public BiometricSignatureVerification signatureVerification;

}

Attributes

signatureVerification: BiometricSignatureVerification class object with all the validation information obtained in the signature verification process.

4.2 Methods

4.2.1 Verify Performs the verification of the signature(s) contained in a document against a signature captured using one of the supported devices. This method is responsible for receiving both the document to be validated and the various settings to be used in the validation process, returning all the verification information corresponding to the elements that constitute the signature in said process.

Syntax

public BiometricVerificationResponse Verify(

BiometricVerificationRequest request

);

Entry Parameters

request: BiometricVerificationRequest class object.

Return

Returns a BiometricSignatureVerification class object with all the validation information obtained in the signature verification process or an exception in the event that some type of error occurs.

Comments

The signatureProfile parameter is used to see the type of validation that will be performed based on the type of document. When the exact profile of the signature is unknown, at least the high level profiles must be indicated (SignatureProfile.PDF o SignatureProfile.Office) which will inform the validator as to whether the document type is PDF or XPS.

4.2.2 GetInfo Returns all the information corresponding to the signature(s) included in a document. Unlike the Verify method, this method does not perform the validation of the signatures against a captured signature but rather simply enumerates the information contained in the document.

Syntax

public BiometricGetInfoResponse GetInfo(

BiometricGetInfoRequest request

);

Page 18: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 18 of 42

Entry Parameters

request: BiometricGetInfoRequest class object.

Return

Returns a BiometricGetInfoResponse class object with all the validation information obtained in the signature information obtaining process or an exception in the event that some type of error occurs.

Comments

The signatureProfile parameter is used to see the type of validation that will be performed based on the type of document. When the exact profile of the signature is unknown, at least the high level profiles must be indicated (SignatureProfile.PDF o SignatureProfile.Office) which will inform the validator as to whether the document type is PDF or XPS.

4.2.3 GetInfoFromBiometricState Returns all the information corresponding to the signature(s) included in biometric state returned by the client component.

Syntax

BiometricGetInfoResponse GetInfoFromBiometricState(

BiometricGetInfoFromBiometricStateRequest request

)

Entry Parameters

request: BiometricGetInfoFromBiometricStateRequest class object.

Return

Returns a BiometricGetInfoResponse class object with all the validation information obtained in the signature information obtaining process or an exception in the event that some type of error occurs.

Comments

The signatureProfile parameter is used to see the type of validation that will be performed based on the type of document. When the exact profile of the signature is unknown, at least the high level profiles must be indicated (SignatureProfile.PDF o SignatureProfile.Office) which will inform the validator as to whether the document type is PDF or XPS.

Page 19: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 19 of 42

5 Distributed Signature on Client Equipment

Given that the biometric signature requires the existence of a handwritten signature capture device, it could be considered that the whole process must take place using the client's equipment. This architecture based solely on client equipment has several problems such as the processing capacity and diversity of said equipment.

One of the advantages that SealSign BSS provides is the distributed signature, which allows the scenario in question to be resolved in a flexible, simple manner. The distributed signature consists of performing the whole signature process on the server side except for the capturing of the biometric signature parameters which is produced on the client side, where the capture device is located. The obtaining of external elements is thus unified and optimised and the amount of information exchanged is drastically reduced.

This process is carried out securely in SealSign BSS in order to ensure the safety of the data on two levels: application level decoding the exchanged information and at the infrastructure level, allowing the use of underlying communications technology (SSL, authentication, etc.).

An additional advantage of this model is the simplicity of the client side which allows the simple integration of a multitude of different technologies, such as different operating systems (Windows, Linux, etc.) and different devices (PCs, mobiles, tablets, etc.).

This section shows how to integrate these functions with different kinds of applications and technology.

5.1 Architecture of the Distributed Signature

The distributed signature functionality with SealSign BSS is provided principally by three components and is equivalent to that of SealSign DSS's distributed electronic signature.

Entidades Externas SealSign BSS Server Aplicación Cliente

Clientes Windows SealSignBSSPanel

Backend BiometricSignatureServiceService

DocumentProvider

MOSS DocumentProvider

Entidades Certificadoras

SAP

Clientes IOS SealSignBSSPanelView

Clientes Android SealSignBSSPanel

Page 20: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 20 of 42

1. SealSign BSS's backend service (BiometricSignatureServiceBasic.svc or BiometricSignature Service.svc for SOAP 1.1 environments): This service is responsible for orchestrating the communication between the client and the repository where the original document is located, as well as carry out the signing process on the requested document.

2. Specific client signature component for each platform: This component is responsible for composing the handwritten signature biometric data that will be incorporated into the document which is being signed. The SealSign BSS platform includes versions of the component for .NET, Java, Android and iOS applications.

5.2 Client signature component (SealSignBSSPanel)

In SealSign BSS the handling of biometric signatures on client equipment must be carried out through the client signature component (SealSignBSSPanel), which is responsible for checking the hash received, decoding it and preparing it securely to be returned to the distributed signature service layer.

5.3 Offline Distributed Signature

In some scenarios it’s not possible to reach the server platform due to lack of connectivity. For those cases offline distributed signature functionality is provided. The process will be initiated in the device side, obtaining a temporal signature instance which will be synchronized once the connectivity with the server part is reestablished. That instance is associated uniquely to the document, the same manner than in the normal process, and only can be interpreted by the server side thanks to asymmetric and symmetric cryptographic algorithms, ensuring the integrity of the transaction.

When synchronizing the signature instance with the server side, document and signature integrity will be checked, completing the process only it the result is successful.

Page 21: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 21 of 42

6 Backend Distributed Signature Service SOAP 1.1

SealSign BSS's BiometricSignatureServiceBasic.svc service displays the methods necessary for the implementation of distributed signatures through a SOAP 1.1 (basicHttpBinding) web service.

The methods displayed are as follows:

BeginSignature: Informs the service of the beginning of a distributed signature. The server processes the document up to the generation of the summary which is returned to the client within the signature context to be encoded.

EndSignature: The client updates the signature on the server with the summary of the encoded document.

BeginSignatureProvider: Indicates to the service the start of a signature distributed through document provider. The server obtains the document and the parameters from the signature through a call to a provider document, from there, it processes the document until a summary is generated which is returned to the client in the context of the signature to be encrypted.

EndSignatureProvider: The client updates the signature on the server with the summary of the encrypted document and the server calls a provider document to store the final document.

SyncOfflineSignatures: It allows for performing the synchronization of one or various signatures captured separately into a document.

SyncOfflineSignaturesProvider: It allows for performing the synchronization of one or various signatures captured offline into a document. The document is obtained and stored using a document provider.

HeartBeat: Method that makes it possible to verify the health status of the service.

The following sections contain a description of both the interface for each of these methods and the classes and types related to such.

6.1 Classes

6.1.1 BiometricSignatureBeginResponseBasic Type returned by the BeginSignature method.

public class BiometricSignatureBeginResponseBasic

{

public Guid instance;

public byte[] biometricState;

}

Attributes

instance: Distributed signature transaction identifier necessary to complete the operation.

biometricState: Byte array containing the distributed signature context. The AsyncStateManager class must be used to process the context.

Page 22: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 22 of 42

6.1.2 OfflineBiometricSignature Type used by the multiple signature offline synchronization

public class OfflineBiometricSignature

{

public BiometricSignatureType biometricSignatureType;

public string id;

public string account;

public BiometricSignatureFlags biometricOptions;

public BiometricSignatureParameters biometricParameters;

public SignatureFlags options;

public SignatureParameters parameters;

public Guid instance;

public byte[] offlineBiometricState;

}

Attributes

biometricSignatureType: Type of biometric signature to be validated. For more information see the description of the BiometricSignatureType enumerated type.

id: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

account: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

biometricOptions: Receives one or more values of the BiometricVerificationFlags type which specify the different verification options for the signature. For more information see the description of the BiometricVerificationFlags enumerated type.

biometricParameters: BiometricSignatureParameters type object which adds certain parameters necessary for the inclusion of the biometric signature.

options: Receives one or various SignatureFlags type values which allow the configuration of certain behaviour parameters in the document signing process. For more information on the values supported refer to the description of the SignatureFlags enumerated type in SealSign DSS's Web Services Reference guide.

parameters: SignatureParameters type object which adds certain extra parameters necessary to carry out some types of signatures. This value may be null in the event that the configuration of the parameters displayed is not necessary. For more information refer to the description of the SignatureParameters enumerated type in SealSign DSS's Web Services Reference guide.

instance: Transaction identifier for the signature returned by the client component.

offlineBiometricState: Byte array for the distributed signature returned by the client component.

6.1.3 OfflineBiometricSignatureProvider Type used for the synchronization request of various offline signatures using document provider.

public class OfflineBiometricSignature

{

public string id;

public string account;

public string uri;

public string providerParameter;

public Guid instance;

public byte[] offlineBiometricState;

}

Page 23: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 23 of 42

Attributes

id: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

account: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

uri: URI Identifier for the document in the repository.

providerParameter: Text chain that allows for transferring information between the client and the provider of documents to customize their behavior.

instance: Transaction identifier for the signature returned by the client component.

offlineBiometricState: Byte array for the distributed signature returned by the client component.

6.2 Methods

6.2.1 BeginSignature Begins a distributed signature process.

Syntax

public BiometricSignatureBeginResponseBasic BeginSignature(

SignatureProfile signatureProfile,

BiometricSignatureType biometricSignatureType,

string id,

string account,

BiometricSignatureFlags biometricOptions,

BiometricSignatureParameters biometricParameters,

SignatureFlags options,

SignatureParameters parameters,

byte[] detachedSignature,

byte[] signingDocument

);

Entry Parameters

signatureProfile: Indicates the profile of the biometric signature to be validated. Its value must be one of the possible PDF or Office signature profiles (for XPS documents).

biometricSignatureType: Type of biometric signature to be validated. For more information see the description of the BiometricSignatureType enumerated type.

id: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

account: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

biometricOptions: Receives one or more values of the BiometricVerificationFlags type which specify the different verification options for the signature. For more information see the description of the BiometricVerificationFlags enumerated type.

biometricParameters: BiometricSignatureParameters type object which adds certain parameters necessary for the inclusion of the biometric signature.

options: Receives one or various SignatureFlags type values which allow the configuration of certain behaviour parameters in the document signing process. For more information on the

Page 24: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 24 of 42

values supported refer to the description of the SignatureFlags enumerated type in SealSign DSS's Web Services Reference guide.

parameters: SignatureParameters type object which adds certain extra parameters necessary to carry out some types of signatures. This value may be null in the event that the configuration of the parameters displayed is not necessary. For more information refer to the description of the SignatureParameters enumerated type in SealSign DSS's Web Services Reference guide.

detachedSignature: In case of a countersignature with previous signature/s detached, this parameter will receive the array with the previous signatures.

signingDocument: Byte array with the content of the document to be signed.

Return

Returns a BiometricSignatureBeginResponseBasic class object with the signature transaction identifier and a byte array with the distributed signature context to be handled on the client device using the AsynStateManager class.

Comments

When indicating a signature profile in the signatureProfile field, bear in mind that only documents in PDF and XPS format are supported, therefore only PDF or Office values will be accepted.

The options and parameters parameters refer to the desired settings for the support electronic signature. refer to the administration guide for more information on the support electronic signature.

6.2.2 BeginSignatureProvider Starts a distributed signature process with document provider.

Syntax

BiometricSignatureBeginResponseBasic BeginSignatureProvider(

string id,

string account,

string uri,

string providerParameter,

byte[] document

);

Entry Parameters

id: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

account: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

uri: URI Identifier for the document in the repository.

providerParameter: Text chain that allows for transferring information between the client and the provider of documents to customize their behavior.

document: Optional parameter with the array of bytes from the document to be signed.

Page 25: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 25 of 42

Return

Returns a BiometricSignatureBeginResponseBasic class object with the signature transaction identifier and a byte array with the distributed signature context to be handled on the client device using the AsynStateManager class.

Comments

The array of bytes from the document to be signed is optional. If this occurs, this will be used along with the setups of the signature returned by the document provider. Otherwise, it is the document provider itself, associated to the uri, which should access the appropriate document repository to return the array of document bytes.

6.2.3 EndSignature Completes a distributed signature process.

Syntax

public byte[] EndSignature(

Guid instance,

byte[]biometricState

);

Entry Parameters

instance: Transaction identifier for the signature returned by the BeginSignature method.

biometricState: Byte array for the distributed signature status after this has been processed by the SealSignBSSPanel component.

Return

Returns a byte array with the document signed according to the signature parameters specified in the call to the function or an exception in the event that some type of error occurs.

6.2.4 EndSignatureProvider Starts a distributed signature process with document provider.

Syntax

public byte[] EndSignatureProvider(

Guid instance,

byte[] biometricState,

string uri,

string providerParameter,

bool returnSignedDocument

);

Entry Parameters

instance: Transaction identifier for the signature returned by the BeginSignature or BeginSignatureProvider method.

biometricState: Byte array for the distributed signature status after this has been processed by the SealSignBSSPanel component.

uri: URI Identifier for the document in the repository.

Page 26: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 26 of 42

providerParameter: Text chain that allows for transferring information between the client and the provider of documents to customize their behavior.

returnSignedDocument: Boolean that indicates whether the method should return the signed document.

Return

If the parameter returnSignedDocument is true, it returns an array of bytes with the signed document or otherwise a null.

Comments

The method will always call the document provider associated to the uri in order for the resulting document to be stored. If additionally it required the signed document to arrive to the calling application, then the parameter returnSignedDocument can be set to true.

6.2.5 SyncOfflineSignatures Synchronizes multiple temporary offline signatures with the server platform to obtain the final document.

Syntax

byte[] SyncOfflineSignatures(

SignatureProfile signatureProfile,

OfflineBiometricSignature[] offlineSignatures,

byte[] detachedSignature,

byte[] signingDocument

);

Entry Parameters

signatureProfile: Indicates the profile of the biometric signature to be validated. Its value must be one of the possible PDF or Office signature profiles (for XPS documents).

offlineSignatures: Array of OfflineBiometricSignature objects containing the data for each offline signature.

detachedSignature: In case of a countersignature with previous signature/s detached, this parameter will receive the array with the previous signatures.

signingDocument: Byte array with the content of the document to be signed.

Return

Returns a byte array with the document signed according to the signature parameters specified in the call to the function or an exception in the event that some type of error occurs.

6.2.6 SyncOfflineSignaturesProvider Synchronize multiple signatures made without a connection by using a document provider to obtain the signature document and setups.

Syntax

byte[] SyncOfflineSignaturesProvider( OfflineBiometricSignatureProvider[] offlineSignatures,

Page 27: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 27 of 42

byte[] signingDocument,

bool returnSignedDocument

);

Entry Parameters

offlineSignatures: Array of OfflineBiometricSignature objects containing the data for each offline signature.

signingDocument: Byte array with the content of the document to be signed.

returnSignedDocument: Boolean that indicates whether the method should return the signed document.

Return

If the parameter returnSignedDocument is true, it returns an array of bytes with the signed document or otherwise a null.

6.2.7 HeartBeat This method allows for verifying the web service status.

Syntax

public void HeartBeat();

Comments

It performs the necessary verification to verify whether the web service is operating correctly, otherwise it returns an exception.

Page 28: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 28 of 42

7 SOAP 1.2 Backend Distributed Signature Service

SealSign BSS's BiometricSignatureService.svc service displays the methods necessary for the generation of distributed signatures on documents through a SOAP 1.2 (basic HttpBinding) service.

The methods displayed are as follows:

BeginSignature: Informs the service of the beginning of a distributed signature. The server processes the document up to the generation of the summary that is returned to the client within the signature context to be encoded

EndSignature: The client updates the signature on the server with the summary of the encoded document.

BeginSignatureProvider: Indicates to the service the start of a signature distributed through document provider. The server obtains the document and the parameters from the signature through a call to a provider document, from there, it processes the document until a summary is generated which is returned to the client in the context of the signature to be encrypted.

EndSignatureProvider: The client updates the signature on the server with the summary of the encrypted document and the server calls a provider document to store the final document.

SyncOfflineSignatures: It allows for performing the synchronization of one or various signatures captured separately into a document.

SyncOfflineSignaturesProvider: It allows for performing the synchronization of one or various signatures captured offline into a document. The document is obtained and stored using a document provider.

HeartBeat: Method that makes it possible to verify the health status of the service.

The following sections contain a description of both the interface for each of these methods and the classes and types related to such.

7.1 Classes

7.1.1 BiometricSignatureBeginRequest Entry parameter for the BeginSignature method.

public class BiometricSignatureBeginRequest

{

public SignatureProfile signatureProfile;

public BiometricSignatureType biometricSignatureType;

public string id;

public string account;

public BiometricSignatureFlags biometricOptions;

public BiometricSignatureParameters biometricParameters;

public SignatureFlags options;

public SignatureParameters parameters;

public byte[] detachedSignature;

public Stream signingDocument;

}

Attributes

signatureProfile: Indicates the profile of the biometric signature to be validated. Its value must be one of the possible PDF or Office signature profiles (for XPS documents).

Page 29: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 29 of 42

biometricSignatureType: Type of biometric signature to be validated. For more information see the description of the BiometricSignatureType enumerated type.

id: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

account: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

biometricOptions: Receives one or more values of the BiometricVerificationFlags type which specify the different verification options for the signature. For more information see the description of the BiometricVerificationFlags enumerated type.

biometricParameters: BiometricSignatureParameters type object which adds certain parameters necessary for the inclusion of the biometric signature.

options: Receives one or various SignatureFlags type values which allow the configuration of certain behaviour parameters in the document signing process. For more information on the values supported refer to the description of the SignatureFlags enumerated type in SealSign DSS's Web Services Reference guide.

parameters: SignatureParameters type object which adds certain extra parameters necessary to carry out certain types of signature. This value may be null if the configuration of the parameters displayed is not necessary. For more information refer to the description of the SignatureParameters class in SealSign DSS's Web Services Reference guide.

detachedSignature: In case of a countersignature with previous signature/s detached, this parameter will receive the array with the previous signatures.

signingDocument: Byte array with the content of the document to be signed.

7.1.2 BiometricSignatureBeginProviderRequest Input parameter of the BeginSignatureProvider method.

public class BiometricSignatureBeginProviderRequest

{

public string id;

public string account;

public string uri;

public string providerParameter;

public bool signingDocumentSpecified;

public Stream signingDocument;

}

Attributes

id: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

account: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

uri: URI Identifier for the document in the repository.

providerParameter: Text chain that allows for transferring information between the client and the provider of documents to customize their behavior.

signingDocumentSpecified: Boolean that indicates if the signingDocument has been loaded to the document to be signed.

signingDocument: Byte array with the content of the document to be signed.

Page 30: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 30 of 42

7.1.3 BiometricSignatureBeginResponse Exit parameter for the BeginSignature and BeginSignatureProvider method.

public class BiometricSignatureBeginResponse

{

public Guid instance;

public byte[] biometricState;

}

Attributes

instance: Distributed signature transaction identifier necessary to complete the operation.

biometricState: Byte array containing the distributed signature context

7.1.4 BiometricSignatureEndRequest Entry parameter for the EndSignature method.

public class BiometricSignatureEndRequest

{

public Guid instance;

public byte[] biometricState;

}

Attributes

instance: Distributed signature transaction identifier necessary to complete the operation.

biometricState: Array of bytes that contain the context of the previously distributed signature through the SealSignBSSPanel panel.

7.1.5 BiometricSignatureEndProviderRequest Output parameter of the EndSignatureProvider methods.

public class BiometricSignatureEndRequest

{

public Guid instance;

public byte[] biometricState;

public string uri;

public string providerParameter;

public bool returnSignedDocument;

}

Attributes

instance: Distributed signature transaction identifier necessary to complete the operation.

biometricState: Array of bytes that contain the context of the previously distributed signature through the SealSignBSSPanel panel.

uri: URI Identifier for the document in the repository.

providerParameter: Text chain that allows for transferring information between the client and the provider of documents to customize their behavior.

returnSignedDocument: Boolean that indicates whether the method should return the signed document.

Page 31: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 31 of 42

7.1.6 BiometricSignatureEndResponse Output parameter for the EndSignature and EndSignatureProvider method.

public class BiometricSignatureEndResponse

{

public Stream signedDocument;

}

Attributes

signedDocument: Stream contanining the final document including the biometric signature.

7.1.7 BiometricSignatureSyncOfflineRequest Entry parameter for the SyncOfflineSignature method.

public class BiometricSignatureSyncOfflineRequest

{

public SignatureProfile signatureProfile;

public BiometricSignatureType biometricSignatureType;

public string id;

public string account;

public BiometricSignatureFlags biometricOptions;

public BiometricSignatureParameters biometricParameters;

public SignatureFlags options;

public SignatureParameters parameters;

public byte[] detachedSignature;

public Stream signingDocument;

public Guid instance;

public byte[] offlineBiometricState;

}

Attributes

signatureProfile: Indicates the profile of the biometric signature to be validated. Its value must be one of the possible PDF or Office signature profiles (for XPS documents).

biometricSignatureType: Type of biometric signature to be validated. For more information see the description of the BiometricSignatureType enumerated type.

id: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

account: Field which will be added to the biometric signature. The value of this field will be specified by the calling application.

biometricOptions: Receives one or more values of the BiometricVerificationFlags type which specify the different verification options for the signature. For more information see the description of the BiometricVerificationFlags enumerated type.

biometricParameters: BiometricSignatureParameters type object which adds certain parameters necessary for the inclusion of the biometric signature.

options: Receives one or various SignatureFlags type values which allow the configuration of certain behaviour parameters in the document signing process. For more information on the values supported refer to the description of the SignatureFlags enumerated type in SealSign DSS's Web Services Reference guide.

parameters: SignatureParameters type object which adds certain extra parameters necessary to carry out certain types of signature. This value may be null if the configuration of the parameters

Page 32: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 32 of 42

displayed is not necessary. For more information refer to the description of the SignatureParameters class in SealSign DSS's Web Services Reference guide.

detachedSignature: In case of a countersignature with previous signature/s detached, this parameter will receive the array with the previous signatures.

signingDocument: Byte array with the content of the document to be signed.

instance: Transaction identifier for the signature returned by the client panel.

offlineBiometricState: Byte array for the distributed signature status returned by the client panel.

7.1.8 BiometricSignaturesSyncOfflineRequest Entry parameter for the SyncOfflineSignatures method.

public class BiometricSignaturesSyncOfflineRequest

{

public SignatureProfile signatureProfile;

public OfflineBiometricSignature[] offlineSignatures;

public byte[] detachedSignature;

public Stream signingDocument;

}

Attributes

signatureProfile: Indicates the profile of the biometric signature to be validated. Its value must be one of the possible PDF or Office signature profiles (for XPS documents).

offlineSignatures: Array of objects OfflineBiometricSignature containing the data for each offline signature.

detachedSignature: In case of a countersignature with previous signature/s detached, this parameter will receive the array with the previous signatures.

signingDocument: Byte array with the content of the document to be signed.

7.2 Methods

7.2.1 BeginSignature Begins a distributed signature process.

Syntax

public BiometricSignatureBeginResponse BeginSignature(

BiometricSignatureBeginRequest request

);

Entry Parameters

request: Instance of the BiometricSignatureBeginRequest type with the data for the beginning of a signature transaction.

Page 33: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 33 of 42

Return

Returns a BiometricSignatureBeginResponse class object with the signature transaction identifier and a byte array with the distributed signature context to be handled on the client device through the AsynStateManager class.

7.2.2 BeginSignatureProvider Starts a distributed signature process with document provider.

Syntax

public BiometricSignatureBeginResponse BeginSignature(

BiometricSignatureBeginProviderRequest request

);

Entry Parameters

request: Instance of the BiometricSignatureBeginProviderRequest type with the data for the beginning of a signature transaction.

Return

Returns a BiometricSignatureBeginResponse class object with the signature transaction identifier and a byte array with the distributed signature context to be handled on the client device through the AsynStateManager class.

Comments

The array of bytes from the document to be signed is optional. If this occurs, this will be used along with the setups of the signature returned by the document provider. Otherwise, it is the document provider itself, associated to the uri, which should access the appropriate document repository to return the array of document bytes.

7.2.3 EndSignature Completes a distributed signature process.

Syntax

BiometricSignatureResponse EndSignature(

BiometricSignatureEndRequest request

);

Entry Parameters

request: Instance of the BiometricSignatureEndRequest type with the necessary data to complete the signature transaction.

Return

This method returns a BiometricSignatureResponse class object or an exception in the event that some type of error occurs.

Page 34: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 34 of 42

7.2.4 EndSignatureProvider Completes a distributed signature process through document provider.

Syntax

BiometricSignatureEndResponse EndSignature(

BiometricSignatureEndProviderRequest request

);

Entry Parameters

request: Instance of the BiometricSignatureEndProviderRequest type with the necessary data to complete the signature transaction.

Return

This method returns a BiometricSignatureEndResponse class object or an exception in the event that some type of error occurs.

Comments

The method will always call the document provider associated to the uri in order for the resulting document to be stored. If additionally it required the signed document to arrive to the calling application, then the parameter returnSignedDocument can be set to true.

7.2.5 SyncOfflineSignatures Synchronizes multiple temporary offline signatures with the server platform to obtain the final document.

Syntax

public BiometricSignatureEndResponse SyncOfflineSignatures(

BiometricSignaturesSyncOfflineRequest request

);

Entry Parameters

request: BiometricSignaturesSyncOfflineRequest type instance with the synchronization data from the transaction signature.

Return

This method returns a BiometricSignatureEndResponse class object or an exception in the event that some type of error occurs.

7.2.6 SyncOfflineSignaturesProvider Synchronize multiple signatures made without a connection by using a document provider to obtain the signature document and setups.

Syntax

BiometricSignatureEndResponse SyncOfflineSignaturesProvider(

BiometricSignaturesSyncOfflineProviderRequest request

);

Page 35: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 35 of 42

Entry Parameters

request: BiometricSignaturesSyncOfflineRequest type instance with the synchronization data from the transaction signature.

Return

This method returns a BiometricSignatureEndResponse class object or an exception in the event that some type of error occurs.

7.2.7 HeartBeat This method allows for verifying the web service status.

Syntax

public void HeartBeat();

Comments

It performs the necessary verification to verify whether the web service is operating correctly, otherwise it returns an exception.

Page 36: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 36 of 42

8 Document Providers

SealSign BSS's frontend service allows the user to integrate documents residing in various storage repositories with the biometric signature processes in a way which appears transparent to the client. Access to the repositories is resolved through a system of installable components or plug-ins which can be incorporated into the service in a simple manner.

These document providers can be developed by ElevenPaths or any other company to facilitate the integration of repositories. The components must be developed on .NET and must comply with the IDocumentProvider interface.

8.1 IDocumentProvider Interface

The document repository access interface has just two methods to obtain and store the document in the repository. The GetSigningDocument method, as well as Streaming the document, returns the necessary signature parameters:

using SealSignDSSTypes;

using SealSignBSSTypes;

interface IDocumentProvider

{

Stream GetSigningDocument(string uri,

string providerParameter,

out SignatureProfile signatureProfile,

out BiometricSignatureType biometricSignatureType,

out BiometricSignatureFlags biometricOptions,

out BiometricSignatureParameters biometricParameters,

out SignatureFlags options,

out SignatureParameters parameters,

out byte[] detachedSignature);

void SetSignedDocument(string uri,

string providerParameter,

Stream signedDocument);

}

The document is identified throughout the process by means of a URI identifier, which is made up of both a protocol identifier which allows SealSign BSS to decide on the associated plug-in, and the repository's specific document identifier (this may include additional access information). For example, the identifier “moss://http://server/lista/documento” indicates the provider associated with the “moss” protocol and the document within the repository accessible through “http://server/lista/documento”.

8.2 Registro de Proveedores de Documentos

In order to register a document provider on the system, it is sufficient to add to the <DocumentProviders> section of the documentproviders.config file of the SealSignDSSService web application, a code with the protocol identifier and the assembly statement implementing itSaid assembly may reside either in the default search path or in the GAC. For example: <DocumentProviders>

<add key="test" value="SealSignBiometricTestProvider, Version=1.0.0.0,

Culture=neutral, PublicKeyToken=7292d37ec3154539"/>

</DocumentProviders>

Page 37: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 37 of 42

9 Bindings WCF of SealSign

The setup of the WCF (Windows Communication Foundation) bindings are a fundamental part of the Windows architecture over which the SealSign platform is built and which are shared by all of the modules on this platform.

For more information regarding WCF visit https://msdn.microsoft.com/es-es/library/ms731082 (v=vs.90).aspx

9.1 Types of WCF Bindings in SealSign

The WCF bindings from the different SealSign modules can be found on the web application directories of each one of the modules, in a folder called bindings.config.

9.1.1 BasicHttpBinding (Soap 1.1)

BasicHttpBinding_IServiceSSLIntegrated: WCF Binding whose client server communication requires security through Windows integrated authentication and SSL.

BasicHttpBinding_IServiceNOSSLIntegrated: WCF Binding whose client server communication requires security through Windows integrated authentication without SSL.

BasicHttpBinding_IServiceSSLBasic: WCF Binding whose client server communication requires security through basic authentication and SSL.

BasicHttpBinding_IServiceNOSSLBasic: WCF Binding whose client server communication requires security through basic authentication without SSL.

BasicHttpBinding_IServiceSecNone: WCF Binding whose client server communication does not require any kind of security (anonymous).

BasicHttpBinding_IServiceSSLSecNone: WCF Binding whose client server communication does not require any kind of security (anonymous) and SSL.

9.1.2 WSHttpBinding (Soap 1.2)

WSHttpBinding_IServiceSSLIntegrated: WCF Binding whose client server communication requires security through Windows integrated authentication and SSL.

WSHttpBinding_IServiceNOSSLIntegrated: WCF Binding whose client server communication requires security through Windows integrated authentication without SSL.

WSHttpBinding_IServiceSSLBasic: WCF Binding whose client server communication requires security through basic authentication and SSL.

WSHttpBinding_IServiceNOSSLBasic: WCF Binding whose client server communication requires security through basic authentication without SSL.

WSHttpBinding_IServiceSecNone: WCF Binding whose client server communication does not require any kind of security (anonymous).

Page 38: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 38 of 42

9.2 Setup of the WCF Bindings in SealSign without SSL

In order to set up WCF on any of the SealSign modules so that these do not use SSL, simply make the following change on the Web.config of the module in question: ...

<services configSource="servicesnossl.config"/>

<!--<services configSource="servicesssl.config"/>-->

...

9.3 Setup of the WCF Bindings in SealSign with SSL

In order to set up WCF on any of the SealSign modules so that these use SSL, simply make the following change on the Web.config of the module in question: ...

<!--<services configSource="servicesnossl.config"/>-->

<services configSource="servicesssl.config"/>

...

For more information on how to set up IIS/SSL see https://support.microsoft.com/en-us/kb/299875 /es-es

9.4 Calling of the SealSign and WCF Bindings Services

In this section we will see how to call the SealSign services and how to specify what type of WCF Binding should be used during the calls. What is shown in this section is not client platform specific (.NET, Android, IOS, etc.)

SealSign uses HTTP-based WCF bindings, therefore the services are simply referenced through a service URL.

Some examples of SealSign service URLs are:

http://host/SealSignDSSService/SignatureService.svc

http://host/SealSignBSSService/BiometricSignatureService.svc

9.4.1 Call of the SealSign services with the WCF Binding by default

In order to call the SealSign services with the WCF Bindings by default, it is not necessary to add anything to the service URL, therefore, an example of the call URL to a SealSign service could be:

http://host/SealSignBSSService/BiometricSignatureService.svc

The default bindings of the services can be seen in the folders servicesnossl.config (services without SSL) or servicesssl.config (services with SSL)

9.4.2 Call of the SealSign services with a specific WCF Binding

In order to call the SealSign services with a specific WCF Binding, it is necessary to add to the service URL the WCF Binding through which you intend to access the service.

An example of each of the available WCF bindings is shown below:

Page 39: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 39 of 42

9.4.2.1 BasicHttpBinding (Soap 1.1)

BasicHttpBinding_IServiceSSLIntegrated: WCF Binding whose client server communication requires security through Windows integrated authentication and SSL. https://host/SealSignBSSService/BiometricSignatureService.svc/BSSLI

BasicHttpBinding_IServiceNOSSLIntegrated: WCF Binding whose client server communication requires security through Windows integrated authentication without SSL. http://host/SealSignBSSService/BiometricSignatureService.svc/BI

BasicHttpBinding_IServiceSSLBasic: WCF Binding whose client server communication requires security through basic authentication and SSL. https://host/SealSignBSSService/BiometricSignatureService.svc/BSSLB

BasicHttpBinding_IServiceNOSSLBasic: WCF Binding whose client server communication requires security through basic authentication without SSL. http://host/SealSignBSSService/BiometricSignatureService.svc/BB

BasicHttpBinding_IServiceSecNone: WCF Binding whose client server communication does not require any type of security (anonymous). http://host/SealSignBSSService/BiometricSignatureService.svc/B

BasicHttpBinding_IServiceSSLSecNone: WCF Binding whose client server communication does not require any kind of security (anonymous) and SSL. https://host/SealSignBSSService/BiometricSignatureService.svc/BSSL

9.4.2.2 WSHttpBinding (Soap 1.2)

WSHttpBinding_IServiceSSLIntegrated: WCF Binding whose client server communication requires security through integrated Windows authentication and SSL. https://host/SealSignBSSService/BiometricSignatureService.svc/WSSSLI

WSHttpBinding_IServiceNOSSLIntegrated: WCF Binding whose client server communication requires security through Windows integrated authentication without SSL. http://host/SealSignBSSService/BiometricSignatureService.svc/WSI

WSHttpBinding_IServiceSSLBasic: WCF Binding whose client server communication requires security through basic authentication and SSL. https://host/SealSignBSSService/BiometricSignatureService.svc/WSSSLB

WSHttpBinding_IServiceNOSSLBasic: WCF Binding whose client server communication requires security through basic authentication without SSL. http://host/SealSignBSSService/BiometricSignatureService.svc/WSB

WSHttpBinding_IServiceSecNone: WCF Binding whose client server communication does not require any type of security (anonymous). https://host/SealSignBSSService/BiometricSignatureService.svc/WSSSL

9.4.3 Typical call for SealSign Services

9.4.3.1 .NET

In .NET, the typical call method for a SealSign service is through BasicHttpBinding or WSHttpBinding and integrated Windows authentication, therefore, an example URL for the call would be:

https://host/SealSignBSSService/BiometricSignatureService.svc/BSSLI (BasicHttpBinding With SSL)

http://host/SealSignBSSService/BiometricSignatureService.svc/BI (BasicHttpBinding Without SSL)

https://host/SealSignBSSService/BiometricSignatureService.svc/WSSSLI (WSHttpBinding With SSL)

http://host/SealSignBSSService/BiometricSignatureService.svc/WSI (WSHttpBinding Without SSL)

Page 40: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 40 of 42

9.4.3.2 IOS

In IOS, the typical call method for a SealSign service is through BasicHttpBinding and basic authentication, therefore, an example URL for the call would be:

https://host/SealSignBSSService/BiometricSignatureServiceBasic.svc/BSSLB (With SSL)

http://host/SealSignBSSService/BiometricSignatureServiceBasic.svc/BB (Without SSL)

9.4.3.3 Android

In Android, the typical call method for a SealSign service is through BasicHttpBinding and basic authentication, therefore, an example URL for the call would be:

https://host/SealSignBSSService/BiometricSignatureServiceBasic.svc/BSSLB (With SSL)

http://host/SealSignBSSService/BiometricSignatureServiceBasic.svc/BB (Without SSL)

Page 41: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 41 of 42

10 Resources

For information about the different SealSign services available, please go to this address:

https://www.elevenpaths.com/technology/sealsign/index.html

Also, on the ElevenPaths blog you can find interesting articles and innovations regarding this product.

You can find more information about Eleven Paths products on YouTube, on Vimeo and on Slideshare.

Page 42: Web Services Reference SealSign BSS

Web Services Reference SealSign BSS (Biometric Signature Services)

V.3.2 – November 2016

2016 © Telefónica Digital España, S.L.U. All rights reserved. Page 42 of 42

The information disclosed in this document is the property of Telefónica Digital España, S.L.U. (“TDE”) and/or any other entity within Telefónica Group and/or its licensors. TDE and/or any Telefonica Group entity or TDE’S licensors reserve all patent, copyright and other proprietary rights to this document, including all design, manufacturing, reproduction, use and sales rights thereto, except to the extent said rights are expressly granted to others. The information in this document is subject to change at any time, without notice.

Neither the whole nor any part of the information contained herein may be copied, distributed, adapted or reproduced in any material form except with the prior written consent of TDE.

This document is intended only to assist the reader in the use of the product or service described in the document. In consideration of receipt of this document, the recipient agrees to use such information for its own use and not for other use.

TDE shall not be liable for any loss or damage arising out from the use of the any information in this document or any error or omission in such information or any incorrect use of the product or service. The use of the product or service described in this document are regulated in accordance with the terms and conditions accepted by the reader.

TDE and its trademarks (or any other trademarks owned by Telefonica Group) are registered service marks.

PUBLICATION:

November 2016

At ElevenPaths we have our own way of thinking when we talk about security. Led by Chema Alonso, we are a team of experts who are passionate about their work, who are eager to redefine the industry and have great experience and knowledge about the security sector.

Since June 2013, we have become a startup company within Telefónica aimed at working in an agile and dynamic way, transforming the concept of security and, consequently, staying a step ahead of our attackers.

Our head office is in Spain, but we can also be found in the UK, the USA, Brazil, Argentina and Colombia.

If you wish to know more about us, please contact us at:

elevenpaths.com Blog.elevenpaths.com @ElevenPaths Facebook.com/ElevenPaths YouTube.com/ElevenPaths