DevPortalPagoPA

Table of contents

E-service with “keychain” functionality: Trial Keychain

The “Certification - API Trial Keychain” e-service published in the catalog offers a service through which it is possible to see the keychain function in action: this is a service that does not add any particular business logic to the sent response, but at the same time provides immediate evidence about the additional information the provider implementing the function sends to the user.
add here use cases to clarify its use
Invocation of the e-service
Let's see the e-service in action. After subscribing to the service, we can immediately generate the toucher and then invoke the APIs.
The first call we will make is as follows:
GET /keychain-mock/signature
Header:
1Content-Type: application/json
2Authorization: Bearer {{bearerToken}}
3x-correlation-id: {{myUniqueCorrelationId}}
4
Header:
1x-payload-signature: {{signature}}
2x-payload-signature-kid: {{kid}}
3x-payload-signature-algorythm: SHA256withRSA
4
Payload:
1application/json
2{
3    "message": "response generated successfully"
4}
5
As can be seen from the obtained output, the provider sends a response that includes not only the body of the response but also additional headers calculated based on the public key connected to the keychain.
Remember this is only one of the methods with which the information can be sent.
Specifically, the method for sending the information and it quantity is the responsibility of the provider.
The user that receives the added headers can verify the integrity of the response.
An example is provided below of the steps that can be taken for the verification.
Recovery of the public key connected to the keychain
By means of the value contained in the header x-payload-signature-kid, it is possible to recover the public key.
For this purpose, it is possible to invoke the APIs provided by interoperability and specifically
1GET /keys/:kid
2
Setting the parameter :kid with the value obtained in the header.
The API will respond with the associated public key.
Verification of the signature
Thanks to the recovered pubic key and the remaining headers, it is possible to proceed with the verification.
For the verification, it is necessary to recover the value associated with x-payload-signatures and apply the algorithm indicated in x-payload-signature-algorithm to the signature.
An excerpt of code is provided below for illustrative purposes
1
2# Upload the public key
3
4public_key = load_pem_public_key(public_key_pem)
5
6# Verify the signature
7
8try:
9    public_key.verify(
10        signature,
11        payload,
12        padding.PKCS1v15(),
13        hashes.SHA256()
14    )
15    print("Valid signature!")
16except Exception as e:
17    print("Invalid signature:", e)
18
If the algorithm is executed correctly, the integrity verification is correct.
The e-service presents an additional API that permit sending feedback to the provider following verification of the signature.
For this purpose, the user can send details by making the following request:
POST /keychain-mock/verify
Header:
1Content-Type: application/json
2Authorization: Bearer {{bearerToken}}
3x-correlation-id: {{myUniqueCorrelationId}}
4x-payload-signature: {{signature}}
5
Payload:
1application/json
2{
3    "message": "Check Successful"
4}
5
Payload:
1application/json
2{
3    "status": "OK",
4    "message": "X-Payload-Signature verified"
5}
6
In this way, the provider recognizes that the call flow was completed correctly.

Need help?

Open a ticket using the dedicated feature inside your Reserved Area

Tell us what you think

To report problems or give feedback, you can open a report on GitHub