# Exchange Signing Certificate
source: https://developer.mastercard.com/account-to-account-commerce-for-dsp/tutorial/key-exchange-process/step3/index.md
### Exchange Signing Certificate {#exchange-signing-certificate}
This guide covers the details on how to generate the CSR for the signing certificate and get it signed by Mastercard Key Management from the Key Management Portal in MC Connect.
### Participant digital signing certificate {#participant-digital-signing-certificate}
The process for signing and validating messages is as follows:
1. Mastercard digitally signs the messages before transmitting them to a participant.
2. Participants use Mastercard's certificate to validate the signature.
3. Participants must digitally sign the messages before transmitting them to Mastercard.
4. Mastercard uses the respective participant's certificate to validate the signature.
### Participant digital signing certificate {#participant-digital-signing-certificate-1}
A participant must generate and provide the signing certificate request in the Mastercard Key Management portal.
The following steps describe how it is done:
| Steps | Description |
|--------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1. Obtain the signing certificate. | Create a signing certificate CSR as mentioned in the section below. |
| 2. Onboard the signing certificate on the Zapp platform. | Mastercard signs the CSR and returns the certificate to the participant. Account to Account Commerce will then use the corresponding certificate to validate the signature of the incoming message received from the participant. |
| 3. Obtain the public certificate for validating Zapp digital signatures. | The KMS team exchanges Zapp's public signing certificate with the participant during the participant's onboarding process to Account to Account Commerce or upon renewal of the certificate. |
| 4. Sign and verify messages. | Account to Account Commerce uses JWS for message signing; refer to [Signing a JWS Message](https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/tutorials-and-guides/jws-guide/signing-jws-message/index.md). |
| 5. Identify which API endpoints require signing. | API endpoints that require digital signing in the request message will contain the X-JWS-Signature HTTP header in the request specification. See the API's corresponding OpenAPI specification. API endpoints that require digital signature validation will contain the X-JWS-Signature HTTP header in the response message. See the API's corresponding OpenAPI specification. |
### Distinguished name templates for signing certificates {#distinguished-name-templates-for-signing-certificates}
The table below explains what DN attributes are needed to generate the Signing certificate and the fields to be selected in the Key Management Portal while requesting the Signed Signing keys from Mastercard.
A separate set of keys is required for each environment a participant connects to: Mastercard Test Facility (MTF) and Production.
#### MTF Environment {#mtf-environment}
|----------------------------|----------------------------|--------------------------------------|
| **Mastercard Application** | Zapp Platform ||
| **Environment** | MTF ||
| **Certificate Profile** | Signing ||
| **DN Requirements** | **Common Name (CN)** | \[Customer name\] |
| **DN Requirements** | **Organization (O)** | \[Registered customer name\] |
| **DN Requirements** | **Organization Unit (OU)** | Zapp MTF signing |
| **DN Requirements** | **Country ( C )** | Must be a valid 2-character ISO code |
#### Production Environment {#production-environment}
|----------------------------|----------------------------|--------------------------------------|
| **Mastercard Application** | Zapp Platform ||
| **Environment** | Production ||
| **Certificate Profile** | Signing ||
| **DN Requirements** | **Common Name (CN)** | \[Customer name\] |
| **DN Requirements** | **Organization (O)** | \[Registered customer name\] |
| **DN Requirements** | **Organization Unit (OU)** | Zapp Production signing |
| **DN Requirements** | **Country ( C )** | Must be a valid 2-character ISO code |
### Download signed certificates {#download-signed-certificates}
When a CSR is signed, participants are notified via the contact information provided in KMP. A security officer may download the signed certificate from KMP.
### Digital signature certificate requirements {#digital-signature-certificate-requirements}
To implement signing for messages sent to Account to Account Commerce and verify signed messages from Account to Account Commerce, the participant must do the following:
* Exchange X509 certificates with Mastercard at the time of onboarding.
* Support more than one active certificate at a time to support the certificate rotation process.
* Use RSA signing private key(s) with a length of 2048 bits.
Note: It is recommended for participants to store signing private key in a FIPS 140-2 compliant 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 (JSON Web Token) JWS specification RFC 7515](https://tools.ietf.org/html/rfc7515) standard for message signing.
The following rules apply:
* 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 unencoded payload.
* The kid claim in the Object Signing and Encryption (JOSE) header must include the Subject Key Identifier (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 the RS256 (RSASSA-PKCS1-v1_5 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 a JSON payload or any other arbitrary data. It is transmitted as detached content and is 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 "kid" 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-----
-----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 used, 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'.
For information on how to sign and verify JWS messages, refer to the following topics:
[Signing a JWS message](https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/tutorials-and-guides/jws-guide/signing-jws-message/index.md)
[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)