# Message Signing and Verification
source: https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/api-basics/message-signing-verification/index.md

## Message Signing and Non-repudiation Overview {#message-signing-and-non-repudiation-overview}

Messages exchanged between Account to Account Commerce and participants are digitally signed to fulfill authentication and non-repudiation requirements.   

Requests with valid signatures created by participants are granted access to Account to Account Commerce services. Similarly, the participants must verify the signature before processing the messages received from Account to Account Commerce.   

The initiator of the message is also referred to as Signer and the recipient is referred to as Verifier throughout this page.
As there are cases where message signing is not needed for processing, not all messages are signed. The details are made explicit in the specifications of each API.   

## Digital Signature Certificate Requirements {#digital-signature-certificate-requirements}

Participants must meet specific requirements to implement signatures sent and to verify messages received from Account to Account Commerce.   

To meet the requirements, the participant **must** do the following:   

* Exchange X509 certificates with Mastercard at the time of onboarding  
* Support more than one active certificate at a point in time to support the certificate rotation process   
* Use RSA signing private key(s) with length 2048 bits  

Note: It is recommended for Participants to store the signing private key in a FIPS 140-2 complaint system e.g. Hardware Secure Module (HSM)   

## Digital Signature Specifications for JSON Messages {#digital-signature-specifications-for-json-messages}

### JSON message signing rules {#json-message-signing-rules}

Account to Account Commerce uses the [IETF JWS specification RFC 7515](https://tools.ietf.org/html/rfc7515) standard for message signing.

The following rules apply:   

* JSON Web Signature (JWS) is specified with detached content as defined in [RFC 7515 - Appendix F](https://tools.ietf.org/html/rfc7515#appendix-F) in the HTTP header `X-JWS-Signature` of the API request/response  
* HTTP body forms an un-encoded payload   
* The KID claim in JOSE (Javascript Object Signing and Encryption) header must include the SKI of the signer. The Verifier should have a mechanism to look up the signer public key from a trust store based on the KID value   
* The signer must sign the messages using PS256 (RSASSA-PSS using SHA-256) algorithm   

#### JWS logical values {#jws-logical-values}

A JWS represents the following logical values.

|   Component   |                                                                                    Description                                                                                    |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| JOSE Header   | Contains JWS Protected Header information for JWS such as `alg` used for signing. For JSON compact serialization, the JOSE header supports including only a JWS Protected Header. |
| JWS Payload   | This is the HTTP body. It can be either JSON payload or any arbitrary data. It is transmitted as detached content and not included as part of the `X-JWS-Signature`.              |
| JWS Signature | This is the digital signature over the JOSE Header and JWS Payload.                                                                                                               |

### KID (Key ID) {#kid-key-id}

The 'KID' (key ID) Header Parameter is a hint indicating which key was used to secure the JWS. This parameter allows originators to signal a change of key to recipients explicitly. The structure of the "" value is unspecified by the JWS specification, but its value must be a case-sensitive string.  

#### Obtaining the 'KID' {#obtaining-the-kid}

For an X509 certificate, the 'KID' is the "Subject Key Identifier" (SKI) content. To acquire this value, the following two steps need to be completed:  

**Step 1:** Obtain a copy of the client certificate containing the public key

* The public key will be available via the KMP portal as a .pem file
* Certificates in the .pem file will be visible from a text editor. Look for the following lines that identify the start and end of the certificate:   

-----BEGIN CERTIFICATE-----   

<br />


-----END CERTIFICATE-----   

* The .pem file may contain more than one certificate. If this is the case, we must identify and extract the client certificate
* To do so, extract the text, including the lines above, into a new text file and save it with a .pem extension
* We suggest naming the new file "client_sign_cert.pem"

**Step 2**: Extract the SKI from the client certificate

* We will use the OpenSSL utility to print out the certificate information. This data will contain the SKI
* To do this, run the following command on the client certificate file created in step 1

**openssl x509 -in client_sign_cert.pem -noout -text**

* This will display a field titled: "x509v3 Subject Key Identifier"
* Copy the above SKI value from this field
* The SKI will be in hexadecimal format. This needs to be converted to base64 format to obtain a case-sensitive string
* Any hexadecimal-to-base64 conversion utility can be utilized, but we suggest one that is integrated with your IDE
* Once you have converted the KID to a base64 string, you now have the value to be used as the 'KID'

## Next Steps {#next-steps}

For information on how to sign and verify JWS messages please see [Signing a message using JWS](https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/tutorials-and-guides/jws-guide/signing-jws-message/index.md) and [Verifying a JWS signed message](https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/tutorials-and-guides/jws-guide/verifying-jws-signed-message/index.md) for step-by-step instructions.