- Request/response protocol
- Service authentication [Auth]
- Users management [User]
- Certificates management [Cert]
- Auditory management [Audit]
- Simple signatures [Sign]
- Document signatures [Signature]
- TimeStamp operations [TSP]
- Verification operations [Verify]
- External PKI integration [PKI]
- Common objects definition
1. Request/response protocol
It is possible to connect to IvSign's API through REST and SOAP protocols. Both protocols have the same methods and the same in and out object structure.
The methods are organized in categories. Some of them, such as the signature engine, may require a validation or a license in order to be used.
Consult with your project manager to obtain the URL and the credentials needed for a demo of the product in our demo environments.
1.1. REST service
REST service uses JSON notation for in and out of the service.
It is required a POST request to each operation URL with the request data.
The Auth category operations will return a session token. It will be needed on each operation and must be sent on the Authentication headline.
In order to access to each REST method it is needed to create the URL using the following example:
https://ENVIRONMENT/Keyman/rest/v3/CATEGORY/ACTION
For instance, to do a Login action in Auth category:
https://demo.ivsign.net/Keyman/rest/v3/auth/login
1.2. SOAP service
SOAP service uses WCF Microsoft services, allowing a quick implementation through .NET resources.
The Auth category operations will return a session token. It will be needed on each operation and must be sent as a parameter.
The URL service will depend on the environment it is wanted to access, using the following format:
https://ENVIRONMENT/Keyman/KeymanServiceV3.svc
Once the service is referenced, the operations described below in this document will be available. The name of each method will be the union between the category and the action.
For instance, to do a Login action in Auth category the .NET method would be:
AuthLoginResponse AuthLogin(AuthLoginRequest request);
2. Service authentication [Auth]
2.1. Obtaining session token [Auth/Login]
In order to obtain a session token, it is needed a request to Auth/Login operation using the following parameters:
| Auth/Login - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| string | Yes | Integration module identifier | |
| string | Yes | Authentication method (pass, win, federated) | |
| string | No | User identifier | |
| string | No | User password | |
| Auth/Login - Response | ||
|---|---|---|
| Parameter | Type | Value |
| string | Session token | |
| User | IvSign user object | |
The 'module' parameter identifies the IvSign integration application. It is an alphanumerical string used for auditory records and reports. The integrator may name the integration at wish, though it is recommend to use always the same name.
The 'authmethod' parameter specifies which authentication method will be used. The most commons is 'pass', which allows user/password authentication. For other authentication methods, consult with your project manager.
Request and response example:
| JSON request |
|---|
| { "module" : "testapi", "authmethod" : "pass", "login" : "miuser" "pass" : "mipass", } |
| JSON response |
|---|
| { "token":"KV2BxG3kj5YvgQ3N1AOP7Oj7BNSUQot/T087Z+RdZReo=", "user": { "userid":"miuser", "orgaid":"MiOrg", "email":"miuser@ivsign.net", "name":"Nombre", "lastname":"Apellidos", "disabled":false, "createdate":"2017-10-11T15:25:44", "lastlogin":"2017-10-16T09:18:25", "previouslogin":"2017-10-16T09:15:43" } } |
In this case, the token is: KV2BxG3kj5YvgQ3N1AOP7Oj7BNSUQot/T087Z+RdZReo=
3. Users management [User]
3.1. Creating users [User/Add]
A user's creation is done through User/Add method, it is needed to have admin privileges to use this method.
| User/Add - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| User | IvSign user object | ||
| string | Yes | IvSign user ID | |
| string | Yes | User email | |
| string | No | User password (if it is not specified, it will be generated randomly) | |
| string | No | Name | |
| string | No | Last name | |
| string | No | Phone number | |
| string | No | Identifier | |
| boolean | No | True allows to create a user without sending a confirmation email, however it requires a password | |
| User/Add - Response | ||
|---|---|---|
| Parameter | Type | Value |
| User | IvSign user object | |
Request and response example:
| JSON request |
|---|
| { "user": { "userid": "miuser", "pass": "123456", "email": "miuser@ivsign.net", "name": "Nombre", "lastname": "Apellidos", "phone": "600600600" "ident": "12345678Z", "disabled": false, }, "disablenotify": false } |
| JSON response |
|---|
| { "error": null, "user": { "userid": "miuser", "pass": "123456", "email": "miuser@ivsign.net", "name": "Nombre", "lastname": "Apellidos", "phone": "600600600" "ident": "12345678Z", "orgaid": "MiOrg", "disabled": false, "createdate": "2017-10-11T15:25:44", "authprovider": "db", } } |
3.2. Getting user data [User/Get]
Obtaining a user data is done through User/Get method. The method returns a specific user.
| User/Get - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| User | IvSign user object | ||
| string | No | IvSign user ID | |
| string | No | User email | |
| string | No | Name | |
| string | No | Last name | |
| string | No | Identifier | |
| User/Get - Response | ||
|---|---|---|
| Parameter | Type | Value |
| User | IvSign user object | |
Request and response example:
| JSON request |
|---|
| { "user": { "userid": "miuser" } } |
| JSON response |
|---|
| { "error": null, "user": { "userid":"miuser", "orgaid":"MiOrg", "email":"miuser@ivsign.net", "name":"Nombre", "lastname":"Apellidos", "disabled":false, "createdate":"2017-10-11T15:25:44", "lastlogin":"2017-10-16T09:18:25", "previouslogin":"2017-10-16T09:15:43" } } |
3.3. Setting user data [User/Set]
Setting user data is done through User/Set method. This method allows to modify user personal data and its access password.
Setting other users data and passwords requires having admin privileges, and the user objective must belong to the same organizations as the agent user.
The no null established values will be used to modify the designed user indicated on user.userid field.
| User/Set - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| User | IvSign user object | ||
| string | Yes | IvSign user ID | |
| string | No | User language, used on the emails and the panel | |
| string | No | User email | |
| string | No | New IvSign user password | |
| string | No | Name | |
| string | No | Last name | |
| string | No | Identifier, is unique in all the platform | |
| string | No | Phone number | |
| bool | No | True, the user is disabled | |
| User/Set - Response | ||
|---|---|---|
| Parameter | Type | Value |
| User | IvSign user object | |
Request and response example:
| JSON request |
|---|
| { "user": { "userid": "miuser", "email": "miuser@ivsign.net", "name": "Nombre", "lastname": "Apellidos", "ident": "12345678Z", "disabled": false, "pass": "123456", "lang": "es", "phone": "000000000" } } |
| JSON response |
|---|
| { "error": null, "user": { "userid": "miuser", "email": "miuser@ivsign.net", "name": "Nombre", "lastname": "Apellidos", "phone": "000000000" "ident": "12345678Z", "orgaid": "MiOrg", "disabled": false, "createdate": "2013-09-21T17:00:00", "authprovider": "db", } } |
3.4. Deleting users [User/Del]
Deleting users is done through User/Del method. Only users without certificate can be deleted. The agent user needs to have admin privileges to delete certificates. The user agent only can delete users of its own organization.
| User/Del - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| User | IvSign user object | ||
| string | Yes | IvSign user ID | |
| User/Del - Response | ||
|---|---|---|
| Parameter | Type | Value |
| bool | Deleting result | |
Request and response example:
| JSON request |
|---|
| { "user": { "userid": "user1" } } |
| JSON response |
|---|
| { "error": null, "result" : true } |
3.5. Listing users [User/List]
Listing users is done through the User/List method. The method list users depending on some filter parameters. Admin privileges are needed.
| User/List - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| User | IvSign user object | ||
| string | No | User filter | |
| string | No | Organization filter | |
| string | No | Email filter | |
| string | No | Name filter | |
| string | No | Last name filter | |
| string | No | Identifier filter | |
| bool | No | Enabled state filter | |
| string | No | Phone number filter | |
| User/List - Response | ||
|---|---|---|
| Parameter | Type | Value |
| User[] | IvSign user object | |
Request and response example:
| JSON request |
|---|
| { "user": { "orgaid": "miorga" } } |
| JSON response |
|---|
| { "error": null, "userlist" : [ { "userid": "miuser", "orgaid": "miorga", "email": "miuser@ivsign.net", "name": "Nombre", "lastname": "Apellidos", "ident": "12345678Z", "phone": "600600600" "disabled": false, "createdate": "2017-10-11T15:25:44", "lastlogin": "2017-10-16T09:18:25", "previouslogin": "2017-10-16T09:15:43", "authprovider": "db", }, { "userid": "miuser2", "orgaid": "miorga", "email": "miuser2@ivsign.net", "name": "Nombre2", "lastname": "Apellidos", "ident": "12312312K", "phone": "631242422" "disabled": true, "createdate": "2017-10-11T15:25:44", "lastlogin": "2017-10-16T09:18:25", "previouslogin": "2017-10-16T09:15:43", "authprovider": "db", }, ] } |
4. Certificates management [Cert]
4.1. Getting certificate data [Cert/Get]
Getting certificate data is done through the Cert/Get method.
| Cert/Get - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| Cert | IvSign certificate object | ||
| string | Yes | IvSign certificate ID | |
| Cert/Get - Response | ||
|---|---|---|
| Parameter | Type | Value |
| Cert | IvSign certificate object | |
Request and response example:
| JSON request |
|---|
| { "cert": { "certid":"8C41B4F2CC92" } } |
| JSON response |
|---|
| { "error": null, "cert": { "certid": "8A05B4C5CC92", "name": "testcert", "orgaid": "TestOrg", "userid": "testuser", "descr": "descr cert", "custom1": null, "custom2": null, "custom3": null, "disabled": false, "createdate": "2018-02-02T11:32:03", "subject":"CN=test1, OU=User, O=Test S.L., L=Valencia, C=ES", "subjectcn":"test1", "issuer":"CN=Test User CA, OU=Sistemas, O=Test S.L., C=ES", "issuercn":"Test User CA", "validfrom": "2016-02-15T17:15:16", "validto": "2019-02-14T17:15:16", "serial":"054C3E61E13981", "keysize": "2048", "delegated": false, "delegid": 0, "oper": "operuser", "linked": null, "revoked": null, "expired": null, "sha1sum": "6D8174240C8120A934C11804F555F213DE99AACC", } } |
4.2. Setting certificates [Cert/Set]
Setting certificate data is done through Cert/Set method. The method updates certain certificate parameters.
| Cert/Set - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| Cert | IvSign certificate object | ||
| string | Yes | IvSign certificate ID | |
| bool | No | Certificate enabled status | |
| string | No | Certificate name | |
| string | No | Certificate description | |
| string | No | Custom field 1 | |
| string | No | Custom field 2 | |
| string | No | Custom field 3 | |
| Cert/Set - Response | ||
|---|---|---|
| Parameter | Type | Value |
| Cert | IvSign certificate object | |
| JSON request |
|---|
| { "cert": { "certid":"8C41B4F2CC92", "name":"DOC serie318d" } } |
| JSON response |
|---|
| { "error": null, "cert": { "certid": "8A05B4C5CC92", "name": "DOC serie318d", "orgaid": "TestOrg", "userid": "testuser", "descr": "descr cert", "custom1": null, "custom2": null, "custom3": null, "disabled": false, "createdate": "2018-02-02T11:32:03", "subject":"CN=test1, OU=User, O=Test S.L., L=Valencia, C=ES", "subjectcn":"test1", "issuer":"CN=Test User CA, OU=Sistemas, O=Test S.L., C=ES", "issuercn":"Test User CA", "validfrom": "2016-02-15T17:15:16", "validto": "2019-02-14T17:15:16", "serial":"054C3E61E13981", "keysize": "2048", "delegated": false, "delegid": 0, "oper": "operuser", "linked": null, "revoked": null, "expired": null, "sha1sum": "6D8174240C8120A934C11804F555F213DE99AACC", } } |
4.3. Deleting certificate [Cert/Del]
Deleting certificate is done through Cert/Del method.
| Cert/Del - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| Cert | IvSign certificate object | ||
| string | Yes | IvSign certificate ID | |
| Cert/Del - Response | ||
|---|---|---|
| Parameter | Type | Value |
| bool | Deleting result | |
Request and response example:
| JSON request |
|---|
| { "cert": { "certid": "8A05B4C5CC92" } } |
| JSON response |
|---|
| { "error": null, "result" : true } |
4.4. Listing available certificates [Cert/ListAvailable]
Listing available certificates is done through Cert/ListAvailable method. This method list only available certificates on the request time.
| Cert/ListAvailable - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| Caller | IvSign caller object | ||
| string | No | Client application | |
| string | No | Client host | |
| Cert | IvSign certificate object | ||
| bool | No | Linked certificate filter | |
| bool | No | Revoked certificate filter | |
| bool | No | Expired certificate filter | |
| string | No | Userid filter | |
| string | No | Orgaid filter | |
| Cert/ListAvailable - Response | ||
|---|---|---|
| Parameter | Type | Value |
| Cert[] | IvSign certificate object | |
Request and response example:
| JSON request |
|---|
| { "caller": { "app": "string", "host": "string", }, "cert": { "userid":"miuser" } } |
| JSON response |
|---|
| { "certlist" : [ { "certid":"100000000001", "name":"testcert1", "userid":"miuser", "orgaid":"MiOrg", "serial":"054C3E61E13981", "subject":"CN=test1, OU=User, O=Test S.L., L=Valencia, C=ES", "subjectcn":"test1", "issuer":"CN=Test User CA, OU=Sistemas, O=Test S.L., C=ES", "issuercn":"Test User CA", "signalg":"sha256RSA", "createdate":"2017-09-13T18:45:18", "validfrom":"2017-04-03T09:48:18", "validto":"2022-04-02T09:48:18", "keysize":"2048" }, { "certid":"100000000002", "name":"testcert2", "userid":"miuser", "orgaid":"MiOrg", "serial":"054C6E61F02951", "subject":"CN=test2, OU=User, O=Test S.L., L=Valencia, C=ES", "subjectcn":"test2", "issuer":"CN=Test User CA, OU=Sistemas, O=Test S.L., C=ES", "issuercn":"Test User CA", "signalg":"sha256RSA", "createdate":"2017-09-13T18:45:22", "validfrom":"2017-04-03T09:48:22", "validto":"2022-04-02T09:48:22", "keysize":"2048" } ] } |
4.5. Verifying certificate pin [Cert/PinCheck]
Verifying certificate pin is done through Cert/PinCheck method.
| Cert/PinCheck - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| Cert | IvSign certificate object | ||
| string | Yes | IvSign certificate ID | |
| string | Yes | Certificate pin | |
| Cert/PinCheck - Response | ||
|---|---|---|
| Parameter | Type | Value |
| bool | Verify result | |
Request and response example:
| JSON request |
|---|
| { "cert": { "certid": "8C41B4F2CC92", "pin": "123#@Abc" } } |
| JSON response |
|---|
| { "result": true } |
4.6. Setting certificate pin [Cert/PinSet]
Setting certificate pin is done through Cert/PinSet method.
| Cert/PinSet - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| Cert | IvSign certificate object | ||
| string | Yes | IvSign certificate ID | |
| string | Yes | New certificate pin | |
| string | Yes | Current certificate pin | |
| Cert/Set - Response | ||
|---|---|---|
| Parameter | Type | Value |
| bool | Request result | |
| JSON request |
|---|
| { "cert": { "certid":"8C41B4F2CC92", "pin":"##pinactual##" "newpin":"##nuevopin##" } } |
| JSON response |
|---|
| { "error": null, "result": true } |
4.7. Importing certificate with private key [Cert/ImportPFX]
Importing certificates using its private key, pfx or p12 files, is done through Cert/ImportPFX method. The method imports the certificate to the agent user, unless there is set a userid.
| Cert/ImportPFX - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| Cert | Yes | IvSign certificate object | |
| string | Yes | Certificate personal name | |
| string | No | IvSign user ID (only for admin privileges) | |
| string | No | Certificate description | |
| string | No | Certificate pin | |
| string | No | Custom field 1 | |
| string | No | Custom field 2 | |
| string | No | Custom field 3 | |
| byte[] | Yes | PFX/P12 certificate | |
| string | Yes | PFX/P12 password | |
| Cert/ImportPFX - Response | ||
|---|---|---|
| Parameter | Type | Value |
| Cert | IvSign certificate object | |
Request and response example:
| JSON request |
|---|
| { "cert": { "userid": "testuser", "name": "testcert", "descr": "descr cert", "newpin": "PinAcceso" }, "pfxdata": "MIIhJgIBAz.....", "pfxpass": "ContraseñaAcceso" } |
| JSON response |
|---|
| { "error": null, "cert": { "certid": "8A05B4C5CC92", "name": "testcert", "orgaid": "TestOrg", "userid": "testuser", "descr": "descr cert", "custom1": null, "custom2": null, "custom3": null, "disabled": false, "createdate": "2018-02-02T11:32:03", "subject":"CN=test1, OU=User, O=Test S.L., L=Valencia, C=ES", "subjectcn":"test1", "issuer":"CN=Test User CA, OU=Sistemas, O=Test S.L., C=ES", "issuercn":"Test User CA", "validfrom": "2016-02-15T17:15:16", "validto": "2019-02-14T17:15:16", "serial":"054C3E61E13981", "keysize": "2048", "delegated": false, "delegid": 0, "oper": "operuser", "linked": null, "revoked": null, "expired": null, "sha1sum": "6D8174240C8120A934C11804F555F213DE99AACC", } } |
5. Auditory management [Audit]
5.1. Listing certificate records [Audit/List]
Listing auditory records is done through Audit/List method.
The method shows auditory records using as filters the request parameters.
| Audit/List - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| DateTime | Yes | UTC start search date | |
| DateTime | Yes | UTC end search date | |
| String | No | User's userid for looking up at the auditory. All the direct actions performed for the user and the indirect actions performed on the user | |
| Audit | No | Search filters: userid, oper, category, action, success, certid, serial, module | |
| Page | No | Pagination request | |
| Audit/List - Response | ||
|---|---|---|
| Parameter | Type | Value |
| Audit[] | Auditory records | |
| Page | Pagination information | |
Request and response example:
| JSON request |
|---|
| { "startdate": "2018-04-01T00:00:00.000Z", "enddate": "2018-04-30T23:59:59.999Z", "auditlist": [ { "auditid": 639312, "date": "2018-04-30T07:57:29.896350Z", "ip": "392.289.251.229", "host": "PC001", "certid": "3B64347CD364", "serial": "22B2BB15ED62F5CEA3", "certidorig": null, "orgaid": "TEST", "category": "Sign", "action": "RSA", "actiondata": "sha1", "success": true, "info": "SignHash ok. certname='CERT42' subjectcn='Usuario Pruebas' issuercn='Test' host='PC001' app='XolidoSign.exe' remoteuser='test'", "app": "XolidoSign.exe", "oper": "testuser", "userid": "testuser", "impersonator": null, "location": null, "module": "KeyController", "modver": "6.3", "data": " "certsha1sum": "2F492835717273481823478234AF947723DD21FE" } ], "page": { "id": 2, "itemspage": 25 } } |
| JSON response |
|---|
| { "auditlist": [ { "auditid": 18777, "date": "2018-05-14T15:19:51.776444Z", "ip": "62.58.25.108", "host": "62.58.25.108", "certid": null, "serial": null, "certidorig": null, "orgaid": "FooOrg", "category": "PKI", "action": "Petition", "actiondata": null, "success": true, "info": "pki='statuspre' fields='\"codpro\":\"qwer123\",\"num_perfil\":\"34\"", "app": null, "oper": "fooorgadm", "userid": "fooorgadm", "impersonator": null, "location": null, "module": "deloitte", "modver": null, "data": "pki='statuspre' fields='\"codpro\":\"qwer123\",\"num_perfil\":\"34\"", "certsha1sum": null }, ... ], "page": { "id": 3, "itemspage": 3, "numpages": 31, "totalitems": 91 }, "error": { "code": "K0000", "message": "OK" } } |
6. Simple signatures [Sign]
6.1. Hash signatures [Sign/Hash] ✍
Hash signature is done through Sign/Hash method.
To perform the signature the certificate ID and its pin are needed.
| Sign/Hash - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| Cert | IvSign certificate object | ||
| string | Yes | IvSign certificate ID | |
| string | Yes | Certificate pin | |
| Hash | IvSign hash object | ||
| string | Yes | Hash algorithm | |
| byte[] | Yes | Hash to sign | |
| Caller | IvSign caller object | ||
| string | No | Client application | |
| string | No | Client host | |
| Sign/Hash - Response | ||
|---|---|---|
| Parameter | Type | Value |
| byte[] | Hash RSA signature | |
Request and response example:
| JSON request |
|---|
| { "cert": { "certid": "100000000001", "pin": "PinAcceso" }, "hash": { "algorithm": "SHA512", "digest": "6D6FNdb2iUk+WBm9YKo+X9y6lA5tERq2+1w08k+GSWvzcm4r9..." }, "caller": { "host": "devhost", "app": "apitest" } } |
| JSON response |
|---|
| { "data": "IdzQHKgw0J+IT2/XO3VY7s760s8rVkj5YvgQ3N1AOP7Oj7BNSUQot/T087Z..." } |
7. Document signatures [Signature]
7.1. PDF document signature [Signature/Pades]
PDF signature document is done through Signature/Pades method.
To perform the signature the certificate ID and its pin are needed. Optionally there are additional parameters to personalize the signature.
| Signature/Pades - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| Cert | Yes | IvSign certificate object | |
| string | Yes | IvSign certificate ID | |
| string | Yes | Certificate pin | |
| binary | Yes | PDF document to sign | |
| string | Yes | Signature profile: "basic" o "enhanced" | |
| string | No | Signature algorithm ("SHA1", "SHA256", "SHA512", "MD5"), default algorithm SHA1 | |
| string | No | Signature extensions, separated by coma: "t"=Include TimeStamp into the signature, "timestamp"=Add a TimeStamp to the signature (Long Term Validation), "epes"=Include signature policy | |
| SignPadesParams | No | Complementary parameters | |
| TimestampServerInfo | No | TimeStamp server, if not specified there will be used the default one | |
| PDFSignParams | No | PDF specific properties | |
| Biometry | No | Biometric signature data | |
| Signature/Pades - Response | ||
|---|---|---|
| Parameter | Type | Value |
| byte[] | Signed document | |
Request and response example:
| JSON request |
|---|
| { "cert": { "certid": "1234567890AB", "pin": "123456" }, "doc": "JVBERi0xLjQKJcfsj6I...", "profile": "basic", "extensions": "t,timestamp", "parameters": { "tstampserver": { "url": "http://usuario:password@servidor.sellado", "includecertificates": true, "hashalgorithm": "sha1" }, "pdfparameters": { "pwd": "claveEnTextoPlano", "signvisible": true, "signbackgroundconfig": { "signback": "/9j/4RjhRXhpZgAATU0...", "signbackautostretch": true, "transparencymask": { "red": 255, "green": 255, "blue": 255, "tolerance": 10 } }, "widgetprops": { "autopos": false, "offsetx": 0, "offsety": 0, "autosize": false, "width": 150, "height": 150, "rotate": 270, "showonpages": "first,last,3,5-8", "widgetpageoffset": 0, "hidetext": false, "sizeheader": 5.5, "sizedatetime": 4, "sizetitlesection": 5, "sizetextsection": 4.5, } } } } |
| JSON response |
|---|
| { "data": "JVBERi0xLjsjkdl....." } |
| JSON error response |
|---|
| { "error": { "code": "K0004", "message": "Insufficient parameters (profile)" } } |
7.2. XML document signature [Signature/Xades]
| Signature/Xades - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| Cert | Yes | IvSign certificate object | |
| string | Yes | IvSign certificate ID | |
| string | Yes | Certificate pin | |
| binary | Yes | PDF document to sign | |
| string | Yes | Signature profile: "bes"=basic, "t"=Include TimeStamp into the signature, "c"=Add references to the signature for future Verifications, "x"=Add TimeStamp to the references, "xl"=Current revocation information for long term Verifications | |
| string | No | Signature algorithm ("SHA1", "SHA256", "SHA512", "MD5"). Default algorithm SHA1. | |
| string | No | Signature format "enveloped"=The original XML is included into the signature, "enveloping"=A new XML is generated during the signature process and the original signature is included in an XML node | |
| SignXadesParams | No | Complementary parameters | |
| TimestampServerInfo | No | TimeStamp server, if not specified there will be used the default one | |
| Signature/Xades - Response | ||
|---|---|---|
| Parameter | Type | Value |
| byte[] | Signed document | |
Request and response example:
| JSON request |
|---|
| { "cert": { "certid": "123456789AB", "pin": "1234" }, "doc": "PD94bWwgdm...", "profile": "t", "envelop": "enveloped", "parameters": { "tstampserver": { "url": "http://usuario:password@servidor.sellado", "includecertificates": true, "hashalgorithm": "sha1" } } } |
| JSON response |
|---|
| { "error": null, "data": "77u/PD94bWwg..." } |
| JSON error response |
|---|
| { "error": { "code": "K0004", "message": "Insufficient parameters (profile)" } } |
7.3. Generic document signature [Signature/Cades]
| Signature/Cades - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| Cert | Yes | IvSign certificate object | |
| string | Yes | IvSign certificate ID | |
| string | Yes | Certificate pin | |
| binary | Yes | Document to sign | |
| string | Yes | Signature profile: "bes"=basic, "t"=Include TimeStamp into the signature, "c"=Add references to the signature for future Verifications | |
| string | No | Signature algorithm ("SHA1", "SHA256", "SHA512", "MD5"). Default algorithm SHA1. | |
| string | No | Signature format "enveloping"=The original document is included into the signature, "detached"=The original document is not included into the signature | |
| SignCadesParams | No | Complementary parameters | |
| TimestampServerInfo | No | TimeStamp server, if not specified there will be used the default one | |
| Signature/Cades - Response | ||
|---|---|---|
| Parameter | Type | Value |
| byte[] | Signed document | |
Request and response example:
| JSON request |
|---|
| { "cert": { "certid": "123456789AB", "pin": "1234" }, "doc": "PD94bWwgdm...", "profile": "t", "envelop": "enveloping", "parameters": { "tstampserver": { "url": "http://usuario:password@servidor.sellado", "includecertificates": true, "hashalgorithm": "sha1" } } } |
| JSON response |
|---|
| { "error": null, "data": "77u/PD94bWwg..." } |
| JSON error response |
|---|
| { "error": { "code": "K0004", "message": "Insufficient parameters (profile)" } } |
8. TimeStamp operations [TSP]
8.1. TimeStamp [TSP/Sign]
TimeStamp is done through TSP/Sign method.
To sign a digest and an algorithm are needed. Optionally a sign TSU and a parameter that indicates if it is needed to include the certificates into the signature.
| TSP/Sign - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| byte[] | Yes | Digest to sign | |
| string | Yes | Signature algorithm | |
| string[] | No | TSU server list, it will be used the if not specified there will be used the default one | |
| bool | No | True by default, signing certificates are not included | |
| TSP/Sign - Response | ||
|---|---|---|
| Parameter | Type | Value |
| string | Time certificate authority | |
| byte[] | TimeStamp | |
8.2. TimeStamp Verification [TSP/Verify]
TimeStamp Response is done through TSP/Verify method.
To verify TSR is needed. Optionally, the original digest and the signing certificate can be included.
If the original digest is included, the method will compare it with the TSR digest and will return true or false on the valid_digest parameter according to the result.
Otherwise, valid_digest will be null.
If the signing certificate is included, the method will compare it with the TSR certificate and will return true or false on the valid_cert parameter according to the result.
Note: In case signing certificate is not included into the TSP, it will be needed to be provided.
The valid parameter will be true if all the non null valids are true.
| Verify/TSP - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| byte[] | Yes | TimeStamp to verify | |
| byte[] | Yes | Signed data hash | |
| byte[] | No | Signed certificate, in case it is not included into the TSR | |
| Verify/TSP - Response | ||
|---|---|---|
| Parameter | Type | Value |
| bool | True if all the non null valids are true | |
| bool | TSR validation | |
| bool | Digest validation | |
| bool | Certificate validation | |
| DateTime | TimeStamp UTC date time | |
| string | Signing authority | |
| string | Signing algorithm | |
9. Verification operations [Verify]
9.1. IvSign certificate Verifications [Verify/Cert]
IvSign certificate validation is done through Verify/Cert method.
IvSign certificate ID is needed to perform the Verification.
| Verify/Cert - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| Cert | IvSign certificate object | ||
| string | Yes | IvSign certificate ID | |
| DateTime | No | Request date time moment | |
| Verify/Cert - Response | ||
|---|---|---|
| Parameter | Type | Value |
| Certinfo | IvSign certificate information object | |
| bool | True if the certificate has expired, false otherwise | |
| bool | True if the certificate is not trusted, false otherwise | |
| bool | True if the certificate has been revoked, false if ti is not, null otherwise | |
| bool | True if the certificate intermediate CA signature is not valid, false in case it is valid, null if it was not possible to verify it | |
| bool | True if all the not null Verifications are true, false otherwise | |
9.2. External certificate Verification [Verify/CER]
External certificate Verification is done through Verify/CER method.
It is needed the certificate as a binary DER certificate in order to verify it.
| Verify/Cer - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| byte[] | Yes | Certificate in DER format | |
| DateTime | No | Request date time moment | |
| Verify/Cer - Response | ||
|---|---|---|
| Parameter | Type | Value |
| Certinfo | IvSign certificate information object | |
| bool | True if the certificate has expired, false otherwise | |
| bool | True if the certificate is not trusted, false otherwise | |
| bool | True si el certificado está revocado, False si el certificado no está revocado, Nulo si no hemos podido comprobar el valor | |
| bool | True if the certificate intermediate CA signature is not valid, false in case it is valid, null if it was not possible to verify it | |
| bool | True if all the not null Verifications are true, false otherwise | |
9.3. TimeStamp Verification [Verify/TSP]
TimeStamp Response is done through Verify/TSP method.
To verify TSR is needed. Optionally, the original digest and the signing certificate can be included.
If the original digest is included, the method will compare it with the TSR digest and will return true or false on the valid_digest parameter according to the result.
Otherwise, valid_digest will be null.
If the signing certificate is included, the method will compare it with the TSR certificate and will return true or false on the valid_cert parameter according to the result.
Note: In case signing certificate is not included into the TSP, it will be needed to be provided.
The valid parameter will be true if all the non null valids are true.
| Verify/TSP - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| byte[] | Yes | TimeStamp to verify | |
| byte[] | Yes | Signed data hash | |
| byte[] | No | Signed certificate, in case it is not included into the TSR | |
| Verify/TSP - Response | ||
|---|---|---|
| Parameter | Type | Value |
| bool | True if all the non null valids are true | |
| bool | TSR validation | |
| bool | Digest validation | |
| bool | Certificate validation | |
| DateTime | TimeStamp UTC date time | |
| string | Signing authority | |
| string | Signing algorithm | |
9.4. Signed PDF document Verification [Verify/Pades]
| Verify/Pades - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| byte[] | Yes | PDF document | |
| string | No | Document password | |
| string | No | Verification options | |
| Verify/Pades - Response | ||
|---|---|---|
| Parameter | Type | Value |
| Error | Error code, null means no error | |
| bool | Verification result, if the signature was not manipulated, the certificate is trustable and it is not expired nor revoked, the answer will be true | |
| SignatureData[] | Validated signatures information (signature array) | |
| JSON error response |
|---|
| { "error": { "code": "string", "message": "string" }, "valid": true, "certificatevalidation": { "certinfo": { "serial": "string", "validfrom": "2018-04-09T10:50:39.435Z", "validto": "2018-04-09T10:50:39.435Z", "issuercn": "string", "subject": "string", "subjectcn": "string", "subjectcountry": "string", "signalg": "string", "keyusage": [ "string" ], "enhancedkeyusage": [ "string" ], "caname": "string", "type": "string", "userinfo": {} } } |
10. External PKI integration [PKI]
10.1. Certificate request [PKI/Petition]
Requesting certificates with associated PKI is done through PKI/Petition method.
Admin privileges are needed to use this method.
The authentication will be provided on the pkiauth parameter. It changes according to the specified PKI.
The parameter fields will contain a key value array (dictionary). Its parameters will changes according to the specified PKI.
| PKI/Petition - Request | |||
|---|---|---|---|
| Parameter | Type | Required | Value |
| string | Yes | PKI identifier | |
| string | Yes | Certificate pin | |
| KeyPair[] | Yes | Request parameters | |
| PKI/Petition - Response | ||
|---|---|---|
| Parameter | Type | Value |
| bool | Operation result | |
Request and response example:
| JSON request |
|---|
| { "pki": "status", "pkiauth": "sign|8981CEC30B43|pin", "fields": [ [ "nombre", "Juan" ], [ "dni", "12345678Z" ], ] } |
| JSON response |
|---|
| { "result": true } |
11. Common objects definition
A list with some of IvSign common objects is shown below.
11.1. User object
| User | |
|---|---|
| JSON | Value |
| { | |
| "userid": "miuser", | User ID |
| "extid": "idexterno", | External user ID |
| "orgaid": "MiOrg", | Organization to which one the user is associated |
| "email": "miuser@ivsign.net", | |
| "name": "Nombre", | Name |
| "lastname": "Apellidos", | Last name |
| "lastip": "127.0.0.1", | Last access IP |
| "ident": "12345678Z", | Alternative user identifier |
| "disabled": false, | Disabled flag |
| "createdate": "2017-10-11T15:25:44", | Creation date time |
| "lastlogin": "2017-10-16T09:18:25", | Last connection date time |
| "previouslogin": "2017-10-16T09:15:43", | Next to last connection date time |
| "authprovider": "db", | Authentication provider |
| "admin": false, | Administrator privileges, allows to administrate its organization |
| "superadmin": false, | Super administrator privileges, allows to administrate its organization and organizations below to its |
| "pass": "123456", | Password |
| "validation": "C6307E1B", | Recovering password validation code |
| "lang": "es", | User language |
| "valid": true, | Valid flag |
| "phone": "600600600" | Phone number |
| } | |
11.2. Cert object
| Cert | |
|---|---|
| JSON | Value |
| { | |
| "certid": "100000000001", | IvSign certificate ID |
| "name": "testcert1", | IvSign certificate name |
| "orgaid": "MiOrg", | Organization to which one the certificate is associated |
| "userid": "miuser", | User ID |
| "descr": "miuser", | IvSign certificate name |
| "custom1": "", | Custom field 1 |
| "custom2": "", | Custom field 2 |
| "custom3": "", | Custom field 3 |
| "disabled": false, | Disabled flag |
| "createdate": "2017-09-13T18:45:18", | Importation/creation on IvSign date time |
| "subject": "CN=test1, OU=User, O=Test S.L., L=Valencia, C=ES", | Certificate subject |
| "subjectcn": "test1", | Certificate common name |
| "issuer": "CN=Test User CA, OU=Sistemas, O=Test S.L., C=ES", | Issuer name |
| "issuercn": "Test User CA", | Issuer common name |
| "validfrom": "2017-04-03T09:48:18", | Certificate valid from date time |
| "validto": "2022-04-02T09:48:18", | Expiry date |
| "serial": "054C3E61E13981", | Serial number |
| "keysize": "2048", | Private key bit size |
| "certprovider": "dbsecure", | Certificate provider |
| "delegated": false, | Delegation flag |
| "delegid": null, | IvSign delegation ID |
| "oper": "useradm", | Operator |
| "linked": false, | External certificate link flag |
| "pin": "123456", | Access pin |
| "newpin": null, | Access new pin (for modifying or initializing) |
| "revoked": false, | Revoked flag |
| "expired": false, | Expired flag |
| "fingerprintsha1": "C4FF20C05A66FC57EF1B50882A78AB2852AFC474", | Certificate fingerprint |
| "providerdata": null | External provider information |
11.3. Certinfo object
| Certinfo | |
|---|---|
| JSON | Value |
| { | |
| "serial": "00BBAAA0CD3482BFCD", | IvSign certificate ID |
| "validfrom": "2016-10-27T14:47:24", | Issue date |
| "validto": "2018-10-27T14:47:24", | Expiry date |
| "issuer": "CN=AC Camerfirma Certificados Camerales, C=ES, L=Madrid", | Issuer name |
| "issuercn": "AC Camerfirma Certificados Camerales", | Issuer common name |
| "subject": "C=ES, OU=TEST, CN=12345678K TEST USER", | Certificate subject |
| "subjectcn": "CN=12345678K TEST USER", | Certificate common name |
| "subjectcountry": "ES", | Certificate country |
| "signalg": "sha256RSA", | Hash algorithm |
| "keyusage": [ | Allowed usages list |
| "Digital Signature", | |
| "Non Repudiation", | |
| "Key Encipherment" | |
| ], | |
| "enhancedkeyusage": [ | Allowed extensions list |
| "1.3.6.1.5.5.7.3.2 TLS Web Client Autentication", | |
| "1.3.6.1.5.5.7.3.4 E-mail Protection" | |
| ], | |
| "caname": "Camerfirma", | PSC issuer identifier |
| "type": "PRAP", | Certificate type: NP: Natural person BNP: Natural person belonging to organization GR: General representative APGR: Artificial person general representative (previous law) AP: Artificial person (previous law) SAPGR: State administrations procedures general representative SR: Special representative EB: Electronic bill ES: Electronic stamp TSU: Time stamp UT: Unidentified type |
| "userinfo": { | Certificate user information |
| "name": "Juan", | |
| "lastname": "Apellidos", | |
| "ident": "12345678J", | |
| "email": "usuario@correo.ext", | |
| "birthdate": null | |
| }, | |
| "orgainfo": { | Organization information |
| "ident": "B12345678", | |
| "name": "EMPRESA SOLUCIONES S.L." | |
| }, | |
| "qualified": true, | Qualified certificate flag |
| "qualifiedclassification": 0 | Qualification classification: 0: Natural person 1: Artificial person 2: Components (web site) |
| } | |
11.4. Audit object
| Audit | |
|---|---|
| JSON | Value |
| { | |
| "auditid": 0, | Auditory ID |
| "date": "2018-05-15T13:47:45.045Z", | Operation date |
| "ip": "string", | Operation client user IP |
| "host": "string", | Operation client user host name or IP |
| "certid": "string", | Used IvSign certificate ID (if applicable) |
| "certsha1sum": "string" | Used certificate digest SHA1 sum (fingerprint) |
| "serial": "string", | Used IvSign certificate ID (if applicable) |
| "certidorig": "string", | Original IvSign certificate ID, if it is a delegation |
| "orgaid": "string", | Auditory record associated organization |
| "category": "string", | Operation category |
| "action": "string", | Performed action |
| "actiondata": "string", | Operation entry data |
| "success": true, | Operation success flag |
| "app": "string", | Application used |
| "oper": "string", | Userid action operator performer |
| "userid": "string", | Userid on witch the action is performed |
| "location": "string", | Signature URL (if applicable) |
| "module": "string", | Operation module |
| "modver": "string", | Module version |
| "data": "string", | Operation additional data |
| "info": "string", | Additional information |
| } | |
11.5. Page object
Page object is returned in all listing methods, in order to paginate the response data.
Is is needed to indicate the items per page number and the number of pages (itemspage) and the page to show (id) on the request.
The server will calculate the total number of pages (numpages) and the total number of elements (totalitems).
| Page | |
|---|---|
| JSON | Value |
| { | |
| "id": 0, | Page ID |
| "itemspage": 0, | Number of elements per page |
| "numpages": 0, | Total number of pages |
| "totalitems": 0 | Total number of elements |
| } | |
11.6. PDFSignParams object
| PDFSignParams | |
|---|---|
| JSON | Value |
| { | |
| "pwd": "1234", | PDF password |
| "signvisible": true, | Enables or disables visible signature |
| "widgetprops": { | Visible signature box configuration |
| "autopos": "false", | Enables or disables visible signature box auto position |
| "offsetx": 0, | Visible signature box X axis position |
| "offsety": 0, | Visible signature box Y axis position |
| "autosize": false, | Enables or disables visible signature box auto size |
| "width": 150, | Visible signature box width |
| "height": 150, | Visible signature box height |
| "rotate": 270, | Visible signature box rotation degrees |
| "showonpages": "all", | Specifies on what pages the visible signature is shown, option list, separated by coma: all = all the pages, first = first page, last = last page, x = specific page, y-z = page range, examples: "first,last,3,5,10-20,32-50" |
| "hidetext": false, | Enables or disables the certificate data box |
| "sizeheader": 5.5, | Certificate data box heather font size |
| "sizedatetime": 4, | Certificate data box date font size |
| "sizetitlesection": 5, | Certificate data box section heather font size |
| "sizetextsection": 4.5, | Certificate data box content font size |
| }, | |
| "signbackgroundconfig": { | Visible signature image properties |
| "signback": "/9j/4RjhRXhpZgAATU0...", | Visible signature image bytes, JPG format |
| "signbackautostretch": "true", | Enables or disables automatic background color adjust |
| "transparencymask": { | Transparency JPG image mask |
| "red": 255, | Red channel |
| "green": 255, | Green channel |
| "blue": 255, | Blue channel |
| } | |
| } | |
| } | |
11.7. Biometry object
| Biometry | |
|---|---|
| JSON | Value |
| { | |
| "data": "MIIMFDA...", | Biometric data |
| "cer": "MIIHyDCC...", | Biometry certificate public data |
| } | |
11.8. TimestampServerInfo object
| TimestampServerInfo | |
|---|---|
| JSON | Value |
| { | |
| "url": "https://freetsa.org/tsr", | TimeStamp server URL |
| "includecertificates": true, | Include stamp server certificate into the TSR |
| "hashalgorithm": "sha1" | Hash algorithm (server must support it) |
| } | |