# Certificates and Keys source: https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/api-basics/certificates-keys/index.md ## Certificates and Keys for Account to Account Commerce {#certificates-and-keys-for-account-to-account-commerce} ### Introduction {#introduction} As part of the implementation for Account to Account Commerce, participants are required to exchange cryptographic keys on the Key Management Portal (KMP) app in Mastercard Connect. ### Account to Account Commerce Exchange Keys {#account-to-account-commerce-exchange-keys} Account to Account Commerce uses two sets of keys: * Account to Account Commerce server certificate / TLS * Digital signing certificates (non-repudiation certificates) * Encryption certificates Note: Please see Tutorials and Guides for information on [Key Exchange Process](https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/api-basics/key-exchange/index.md). ## Account to Account Commerce mutual TLS certificates {#account-to-account-commerce-mutual-tls-certificates} ### Overview of mutual authentication {#overview-of-mutual-authentication} A mutual TLS connection must be established for a participant to send or receive messages from Account to Account Commerce. Account to Account Commerce leverages mutual authentication to authenticate, or validate, a participant before messages are exchanged between the **Participant** and **Zapp Platform** , the platform that supports Mastercard. In the following sections, you will find references to "Zapp Platform" or "Zapp" within the Distinguished Name templates for certificates. The mutual authentication process involves an exchange of the following certificates: * Server certificate: Used to identify edge servers to client devices over TLS and to establish a secure connection during the TLS handshake. * Client certificate: Used to identify client devices to edge servers over TLS. This certificate must meet the X.509 standard, defining the format of public key certificates. Participants and Account to Account Commerce must perform X.509 certificate-based mutual authentication. All Account to Account Commerce payment services are hosted over a secure communication channel and it only supports TLS 1.2 or above for transport layer security. To establish the mutually authenticated TLS connection, the participant and Account to Account Commerce present their certificates to each other in a process, known as an SSL handshake, as described below: 1. The client requests access to a protected resource. 2. The server presents its certificate to the client. 3. The client verifies the server's certificate. 4. If successful, the client sends its certificate to the server. 5. The server verifies the client's credentials. 6. If successful, the server grants access to the protected resource requested by the client. ### Account to Account Commerce server and client certificates {#account-to-account-commerce-server-and-client-certificates} Account to Account Commerce maintains a gateway server certificate to establish trust upon mutual connection with a participant. Account to Account Commerce uses DigiCert as the Certificate Authority (CA) for its server certificate. Participants must ensure that they have registered the DigiCert Chain Certificate in their trust store. Download the DigiCert certificate bundle **"DigiCert Global G2 TLS RSA SHA256 2020 CA1"** from [DigiCert Root Certificates](https://www.digicert.com/kb/digicert-root-certificates.htm#roots:~:text=0C%3AF5%3ABD%3A06%3A2B%3A56%3A02%3AF4%3A7A%3AB8%3A50%3A2C%3A23%3ACC%3AF0%3A66). During a participant's onboarding process, and upon renewal of the certificate, Mastercard exchanges the Account to Account Commerce client certificate with the participant through KMS. Client certificates used in this process are signed by Mastercard. For more information please contact your Mastercard Customer Implementation team during this project. ### Participant server and client certificates {#participant-server-and-client-certificates} A participant's server certificate must be of 2048-bit of key length and is signed by an industry recognized trusted CA. When a certificate chain is signed by an intermediate CA then the intermediate CA certificate must be signed by an industry recognized trusted Root CA. Following are the Mastercard-approved CA: 1. DigiCert 2. Verizon 3. COMODO 4. GeoTrust 5. Go Daddy Client certificates used in this process are signed by Mastercard. Participants are required to submit CSRs in the Key Management Portal to be signed by Mastercard. Refer to [Key Exchange Process](https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/api-basics/key-exchange/index.md) for additional information on how to submit CSRs to Mastercard. ### Distinguished Name templates for client certificates {#distinguished-name-templates-for-client-certificates} A separate set of keys is required for each environment a participant connects to: MTF and Production. The following certificate distinguished name (DN) information must be provided to Mastercard KMS during the key exchange process when creating a CSR for a client certificate. No special characters are allowed in the Organization(O) field and OU is case sensitive. #### MTF environment {#mtf-environment} | | | | |----------------------------|----------------------------|--------------------------------------| | **Mastercard Application** | | Zapp Platform | | **Environment** | | MTF | | **Certificate Profile** | | Client | | **DN Requirements** | **Common Name (CN)** | \[Customer name\] | | **DN Requirements** | **Organization (O)** | \[Registered customer name\] | | **DN Requirements** | **Organization Unit (OU)** | Zapp MTF client | | **DN Requirements** | **Country (C)** | Must be a valid 2-character ISO code | #### Production environment {#production-environment} | | | | |----------------------------|----------------------------|--------------------------------------| | **Mastercard Application** | | Zapp Platform | | **Environment** | | Production | | **Certificate Profile** | | Client | | **DN Requirements** | **Common Name (CN)** | \[Customer name\] | | **DN Requirements** | **Organization (O)** | \[Registered customer name\] | | **DN Requirements** | **Organization Unit (OU)** | Zapp PRD client | | **DN Requirements** | **Country (C)** | Must be a valid 2-character ISO code | ## Account to Account Commerce digital signing certificates {#account-to-account-commerce-digital-signing-certificates} ### Overview of digital signatures {#overview-of-digital-signatures} Public key cryptography, or asymmetric cryptography, is a cryptographic system that uses a pair of related keys to encrypt and decrypt a message and protect it from unauthorized access or use. In an asymmetric key pair, one of the keys in this key pair is called the **public key** and may be made publicly available. The other is called the **private key** and is kept secret. A digital certificate is a data file containing one of the keys in a key pair required for a Public Key Infrastructure (PKI). A valid digital signature assures the recipient that the message was created by a known sender, that the sender cannot deny having sent the message, and that the message was not altered in transit. Digital signatures provide added assurances of the evidence to provenance, identity, and status of an electronic document as well as acknowledging informed consent and approval by a signatory. Account to Account Commerce makes use of public key cryptography to ensure that the messages it receives are exactly what the client (participant) has sent and to ensure that no other party has tampered with the message. Account to Account Commerce transactions that have financial implications must follow the digital signing and verification process. For example, digital signatures are required for payment requests, responses and payment notifications. The process for signing and validating messages is as follows: 1. Account to Account Commerce digitally signs the messages before transmitting them to a participant. 2. Participants use Account to Account Commerce certificate to validate the signature. 3. Participants must digitally sign the messages before transmitting to Account to Account Commerce 4. Account to Account Commerce uses the respective participant's certificate to validate the signature. The sections below describe the certificates used by Account to Account Commerce and a participant in the digital signing process. ### Account to Account Commerce digital signing certificate {#account-to-account-commerce-digital-signing-certificate} Account to Account Commerce digitally signs and verifies exchanged messages as follows: 1. The KMS team exchanges the certificate with the participant during the participant's onboarding process or upon renewal of the certificate. 2. The participant uses the certificate to validate the signature of the incoming message received from Account to Account Commerce. ### Participant digital signing certificate {#participant-digital-signing-certificate} A Participant must generate and provide Account to Account Commerce with a signing certificate before it can send messages. The following steps describe how it is done. | Steps | Description | |-------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1. Obtain the signing certificate | Signing certificates are obtained through the Mastercard KMS [Key Exchange Process](https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/api-basics/key-exchange/index.md). | | 2. Onboard the Signing Certificate on the Zapp Platform | 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. 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 [Message Signing and Verification](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 in [API Reference](https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/api-reference/index.md). 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 in [API Reference](https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/api-reference/index.md). | ### Distinguished Name templates for signing certificates {#distinguished-name-templates-for-signing-certificates} A separate set of keys is required for each environment a participant in onboarded to: MTF and Production. The following certificate DN information must be provided to Mastercard KMS during the key exchange process when creating a CSR for Account to Account Commerce signing certificates. No special characters are allowed in the Organization(O) field and OU is case sensitive. #### MTF environment {#mtf-environment-1} | | | | |----------------------------|----------------------------|--------------------------------------| | **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-1} | | | | |----------------------------|----------------------------|--------------------------------------| | **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 PRD signing | | **DN Requirements** | **Country (C)** | Must be a valid 2-character ISO code | ## Account to Account Commerce Digital Encryption Certificate {#account-to-account-commerce-digital-encryption-certificate} ### Overview of Digital Encryption {#overview-of-digital-encryption} Mastercard encrypts API messages that contain sensitive data such as payment card data, for example, CVC2 and PAN, or personally identifiable information (PII). A2A Platform uses symmetric encryption to ensure that encrypted data can only be decrypted and read by the intended recipient that holds the symmetric key used in the encryption process. The process for encrypting and decrypting messages is as follows: 1. The sender of a message containing sensitive data digitally encrypts the API payload using a single-use symmetric key. The symmetric key is also known as a Content Encryption Key (CEK). 2. The symmetric key is encrypted using the recipient's RSA public key, so that the dynamically generated CEK can be communicated securely to the receiver to be used in the decryption process. 3. The encrypted payload is digitally signed using asymmetric cryptography and sent to the recipient using the recipient's public key. 4. The recipient validates the message signature and decrypts the CEK. 5. Using the decrypted CEK, the recipient deciphers the encrypted data to obtain the message payload. ### Account to Account Commerce Encryption Certificate {#account-to-account-commerce-encryption-certificate} The process for encrypting and decrypting the message between Participant and A2A is as follows: 1. The KMS team exchanges the certificate with the Account to Account Commerce Participant during the Participant's onboarding process or upon renewal of the certificate. For more information on this process, see [Key Exchange Process](https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/api-basics/key-exchange/index.md). 2. The Participant uses the Account to Account Commerce encryption public key to encrypt the payload before sending to Account to Account Commerce platform. 3. Account to Account Commerce platform decrypts the message using the Account to Account Commerce private key. ### Participant Digital Encryption Certificate {#participant-digital-encryption-certificate} To decrypt messages received from Account to Account Commerce Platform, Participant must generate an encryption certificate and provide the public key. The process for encrypting and decrypting the message between Account to Account Commerce and Participant is as follows: 1. The Participant submits the CSR in KMP for encryption. For more information on this process, see [Key Exchange Process](https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/api-basics/key-exchange/index.md). 2. KMS signs the CSR and returns the certificate to the Participant. 3. Account to Account Commerce uses the corresponding certificate's public key to encrypt the message and sends to Participant. 4. The Participant uses the corresponding certificate's private key to decrypt the message. ### Distinguished Name templates for encryption certificates {#distinguished-name-templates-for-encryption-certificates} A separate set of keys is required for each environment a participant in onboarded to: MTF and Production. The following certificate DN information must be provided to Mastercard KMS during the key exchange process when creating a CSR for Account to Account Commerce encryption certificates. No special characters are allowed in the Organization(O) field and OU is case sensitive. #### MTF environment {#mtf-environment-2} | | | | |----------------------------|----------------------------|--------------------------------------| | **Mastercard Application** | | Zapp Platform | | **Environment** | | MTF | | **Certificate Profile** | | Encryption | | **DN Requirements** | **Common Name (CN)** | \[Customer name\] | | | **Organization (O)** | \[Registered customer name\] | | | **Organization Unit (OU)** | Zapp MTF encryption | | | **Country (C)** | Must be a valid 2-character ISO code | #### Production environment {#production-environment-2} | | | | |----------------------------|----------------------------|--------------------------------------| | **Mastercard Application** | | Zapp Platform | | **Environment** | | Production | | **Certificate Profile** | | Encryption | | **DN Requirements** | **Common Name (CN)** | \[Customer name\] | | | **Organization (O)** | \[Registered customer name\] | | | **Organization Unit (OU)** | Zapp PRD encryption | | | **Country (C)** | Must be a valid 2-character ISO code |