Proof Specification 

Overview 

The Identity Proof file is a reference provided to integrators for auditing purposes. The service produces this file at the end of the proofing session, and it contains the following:

• The evidence provided by the user, including images
• Detailed verifications results performed during the proofing session
• The final identity resulting from the different verifications performed during the proofing session

Proof Zip File 

To retrieve the proof file, use the following REST API entry point:

Shell
1curl -X GET \
2  https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/proof \
3  -H 'apikey: [GIPS-RS_APIKEY_VALUE]' -o proof.tar.gz

GET Proof request is forbidden if the status of transaction is PROCESSING, GIPS will return HTTP 403 to the Relying Service.

This request closes the proofing session and returns a ZIP file embedded in a MIME envelope.

Note: Extract the zip file from the multipart enveloppe and then unzip the extracted file, then you will get the following structure:

The root folder is named after the identity ID and the timestamp of the proof generation:

For example gips-db676411-0329-4b13-ab7c-ee0adb6bb944_20171127144001086.

Below is the list of files contained in this folder.

Main Proof File 

The main proof file proof.json references all the data inside the proof and controls its integrity and origin. It contains the following:

• General information about the proof itself and the service that generated it

• Hash of other files contained in the proof

• The signature of the proof file

The content of this file corresponds to Proof structure.

Proof 

Note:

• Datetime format: yyyy-MM-ddThh-mm-ss[.SSSSSSS], the last part is optional and represents the fraction-of-seconds from 0 to 7 digits. (Example: 2020-08-05T17:56:14, 2020-08-05T17:56:14.33, 2020-08-05T17:56:14.331.)

• See https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_LOCAL_DATE_TIME.

Hashes 

Media 

Signature 

All hashes are calculated based on the SHA-256 algorithm. The compact IETF JWS with RS256 (RSA signature with SHA-256) is used for the signature.

The signature contains the following three parts separated by a dot ".":

• The header contains only the algorithm (in our case RS256)

• The payload is a base64 of the data to sign (a minimized JSON of the proof content)

• The signature

Note: The client application needs the public key or certificate to verify the proof signature.

There are many ways to verify signature. Example https://jwt.io/

For more details about IETF JWS, see https://tools.ietf.org/html/rfc7515.

Example Payload 

Note: In the JWS payload the JSON is minimized.

Below is an example of a proof.json file

JSON
1{
2  "version": "1.0",
3  "proofId": "********",
4  "identityId": "********",
5  "tenantId": "CUSTOM_NAME",
6  "tenantRole": "RELYING_SERVICE",
7  "transactionId": "********",
8  "startDateTime": "2017-09-29T04:42:48.111",
9  "endDateTime": "2017-09-29T04:59:57.575",
10  "componentVersion": "1.0.0",
11  "hashes": {
12    "identityDetails": "********",
13    "verificationAndEvaluationDetails": "********",
14    "images": [
15      {
16        "id": "b35f7954",
17        "path": "images/b35f7954.jpg",
18        "hash": "********"
19      },
20      {
21        "id": "7e435d21",
22        "path": "images/7e435d21.jpg",
23        "hash": "********"
24      }
25    ],
26    "videos": [
27      {
28        "id": "ad3ea472",
29        "path": "videos/ad3ea472.mp4",
30        "hash": "********"
31      },
32      {
33        "id": "2ceef228",
34        "path": "videos/2ceef228.webm",
35        "hash": "********"
36      }
37    ],
38    "additionalFiles": [
39      {
40        "id": "3786ff22",
41        "path": "additionalFiles/3786ff22.jpg",
42        "hash": "********"
43      },
44      {
45        "id": "a1262c99",
46        "path": "additionalFiles/a1262c99.jpg",
47        "hash": "********"
48      }
49    ]
50  },
51  "signature": "eyJhbGciOiJSUzI1NiJ9. InZlcnNpb24iOiIxLjAiLCJwcm9vZklkIjoiKioqKioqKioiLCJpZGVudGl0eUlkIjoiKioqKioqKioiLCJ0ZW5hbnRJZCI6IkNVU1RPTV9OQU1FIiwidHJhbnNhY3Rpb25JZCI6IioqKioqKioqIiwic3RhcnREYXRlVGltZSI6IjIwMTctMDktMjlUMDQ6NDI6NDguMTExIiwiZW5kRGF0ZVRpbWUiOiIyMDE3LTA5LTI5VDA0OjU5OjU3LjU3NSIsImNvbXBvbmVudFZlcnNpb24iOiIxLjAuMCIsImhhc2hzIjp7ImlkZW50aXR5RGV0YWlscyI6IioqKioqKioqIiwgICAgICAgICJ2ZXJpZmljYXRpb25BbmRFdmFsdWF0aW9uRGV0YWlscyI6IioqKioqKioqIiwiaW1hZ2VzIjpbe2lkOiAiMTIzNCIscGF0aDoiaW1hZ2VzLzEyMzQuanBnIixoYXNoOiIqKioqKioqKiJ9LHtpZDoiNDU2NyIscGF0aDoiaW1hZ2VzLzQ1NjcuanBnIiwgICAgICAgICAgICAgICAgaGFzaDoiKioqKioqKioifV0sInJlc3VtZURhdGEiOiIqKioqKioqKiJ9.IRMQENi4nJyp4er2LmZq3ivwoAjqa1uUkSBKFIX7ATndFF5ivnt+m8uApHO4kfIFOrW7w2Ezmlg3QdmaXlS9DhN0nUk/hGI3amEjkKd0BWYCB8vfUbUv0XGjQip78AI4z1PrFRNidm7+jPDm5Iq0SZnjKjCNS5Q15fokXZc8u0A="
52}

Identity Details File 

The identityDetails.json contains the final result of the identity, with the same content as if a GET /{API URL}/identities/{id} was performed on the API with a Relying Service role.

Note: Refer to the API explorer section for details about the structure and content.

Verification and Evaluation Details File 

The following section provides details on the content of the verificationAndEvaluationDetails.json file.

This file contains a list of VerificationAndEvaluationDetails elements that give details about the performed verifications on different evidences and how they contributed to the identity.
Each evidence or consent found in IdentityDetails file corresponds to one VerificationAndEvaluationDetails element.

VerificationAndEvaluationDetails 

Note on Deleted Evidence

In case an evidence is deleted, the verificationAndEvaluationDetails file will contain two processing steps:

• One when evidence was added with all information including personal details except images since has been deleted after

• One when evidence was deleted with processingDetails, evidenceDetails and evaluationDetails but evidenceDetails will only contain Id, type, family (to know what has been deleted). Scope verificationDetails will be empty since no verification were performed on delete operation.

Note:

• Datetime format: yyyy-MM-ddThh-mm-ss[.SSSSSSS], the last part is optional and represents the fraction-of-seconds from 0 to 7 digits. (Example: 2020-08-05T17:56:14, 2020-08-05T17:56:14.33, 2020-08-05T17:56:14.331.)

• See https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_LOCALDATE_TIME.

AdditionalFile 

Additional file attached to the identity

AdjudicationDecisionDetail 

Free form field to express the reason of adjudication decision

AdjudicationDetails 

Contains details about the adjudication verification

AdjudicationEligibility 

Contains information about the evidence eligibility for adjudication

AttributesReferenceAndConsistency 

Details on attribute matching and consistency checks for the evidence

PortraitMatchingReference 

CaptureImage 

ConsentsDetails 

Consent 

ContactDetails 

Crop 

Data 

DeviceInfo 

EmailElement 

Error 

EvaluationDetails 

Contains all information related to evaluation of the Evidence and Identity

EvidenceDetails 

Contains details on the submitted evidence

HolderInformation 

IndicatorsMitigation 

List of indicators that mitigate invalidating indicators

LoaAndUpgradePath 

Details how LOA can be improved (See REST API)

Metadata 

Key-value structure that contains additional information depending on use case.

OTPElement 

ParticipantType 

Enumeration of participant types

ParticipantState 

Enumeration of participant states

PhoneElement 

ProofEvidence 

Result of the submitted evidence evaluation

RestDetails 

Contains information on the used REST endpoint during the proofing session, including the URL, method, returned errors, and HTTP code.
Only URLs that have an impact on the identity payload are registered in this structure. Consultation requests (GET) are not registered in the proof file.

SdkInfo 

SDK information from nativeSDK

StatusAndScoring 

Contains details on evidence evaluation result like status and scoring

Username 

Name used to contact the user

ValidityPeriod 

Period during which the information is considered valid.

VerificationDetails 

Contains details on the verifications performed on the submitted evidence

VerificationService 

EvidenceFamily 

Enumeration of evidence families

Source 

Enumeration of image sources

Progress 

Enumeration of VerificationAndEvaluationDetails progress status

ISOCountries31661Alpha3 

ABW,AFG,AGO,AIA,ALA,ALB,AND,ARE,ARG,ARM,ASM,ATA,ATF,ATG,AUS,AUT,AZE,BDI,BEL,BEN,BES,BFA,BGD,BGR,BHR,BHS,BIH,BLM,BLR,BLZ,BMU,BOL,BRA,BRB,BRN,BTN,BVT,BWA,CAF,CAN,CCK,CHE,CHL,CHN,CIV,CMR,COD,COG,COK,COL,COM,CPV,CRI,CUB,CUW,CXR,CYM,CYP,CZE,DEU,DJI,DMA,DNK,DOM,DZA,ECU,EGY,ERI,ESH,ESP,EST,ETH,FIN,FJI,FLK,FRA,FRO,FSM,GAB,GBD,GBR,GEO,GGY,GHA,GIB,GIN,GLP,GMB,GNB,GNQ,GRC,GRD,GRL,GTM,GUF,GUM,GUY,HKG,HMD,HND,HRV,HTI,HUN,IDN,IMN,IND,IOT,IRL,IRN,IRQ,ISL,ISR,ITA,JAM,JEY,JOR,JPN,KAZ,KEN,KGZ,KHM,KIR,KNA,KOR,KWT,LAO,LBN,LBR,LBY,LCA,LIE,LKA,LSO,LTU,LUX,LVA,MAC,MAF,MAR,MCO,MDA,MDG,MDV,MEX,MHL,MKD,MLI,MLT,MMR,MNE,MNG,MNP,MOZ,MRT,MSR,MTQ,MUS,MWI,MYS,MYT,NAM,NCL,NER,NFK,NGA,NIC,NIU,NLD,NOR,NPL,NRU,NZL,OMN,PAK,PAN,PCN,PER,PHL,PLW,PNG,POL,PRI,PRK,PRT,PRY,PSE,PYF,QAT,REU,RKS,ROU,RUS,RWA,SAU,SDN,SEN,SGP,SGS,SHN,SJM,SLB,SLE,SLV,SMR,SOM,SPM,SRB,SSD,STP,SUR,SVK,SVN,SWE,SWZ,SXM,SYC,SYR,TCA,TCD,TGO,THA,TJK,TKL,TKM,TLS,TON,TTO,TUN,TUR,TUV,TWN,TZA,UGA,UKR,UMI,UNA,UNK,UNO,URY,USA,UZB,VAT,VCT,VEN,VGB,VIR,VNM,VUT,WLF,WSM,XOM,XXA,XXB,XXC,XXX,YEM,ZAF,ZMB,ZWE,ABR |