# Key Management source: https://developer.mastercard.com/issuer-enrollment/documentation/tutorials-and-guides/key-management-click2pay-tutorial/index.md To integrate with Mastercard Checkout Solutions, you will need the following keys: | Key | Purpose | Description | |---------------------------------|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **API Signing Key (OAuth key)** | Authenticate API calls | * API Signing Key is a 2048-bit private RSA key required to authenticate your API calls. * When you call Mastercard APIs you will need to include an OAuth1.0a Authentication header in your request. You use the private part of the API Signing Key to generate the OAuth header so that the Mastercard API server can authenticate your access to the APIs. * This private key is part of a public/private key pair generated by you (or your web browser) and the public key is certified by Mastercard. It is provided in a [PKCS #12](https://tools.ietf.org/html/rfc7292) format key store file, with a .p12 suffix, and is password protected. * To get started, you can access the default API Signing Key from the onboarding application on Mastercard Connect. Tip: See how [Mastercard authenticates your requests and provides access to the APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/) | | **Consumer Key** | Identifies the client application and is required to calculate the OAuth header. | * The API Signing Key and the Consumer Key are collectively referred to as the OAuth key. * [Consumer Key](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#the-consumer-key) is generated along with the API Signing Key. * The Consumer Key appears in the OAuth1.0a authorization header sent with each request. * Consumer Keys are 97 character identifiers for client applications consuming Mastercard APIs. * The last 48 characters (after the exclamation mark) of the consumer key forms the Key ID (KID). Note: The Key ID portion of the Consumer Key changes whenever the API Signing Key is modified. | | **Payload Encryption Key** | Payload encryption for payment credentials security | * Encryption involves 2048-bit RSA public/private key pairs. * Mastercard uses the public part of this encryption key to [encrypt response payloads containing payment card credentials](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/). * Merchants or PSPs will need the corresponding private part to decrypt these payloads. * Follow these steps to [upload Encryption Key](https://developer.mastercard.com/issuer-enrollment/documentation/tutorials-and-guides/key-management-click2pay-tutorial/index.md#3-add-payload-encryption-key) on Mastercard Connect. * Mastercard Checkout uses Field Level Encryption to provide end-to-end payload encryption to secure sensitive data like Personally Identifying Information (PII). Tip: To learn more about encryption schemes that Mastercard uses, refer to [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/). | ## Public Key Mastercard Provides {#public-key-mastercard-provides} | Name | Purpose | Description | |-------------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **FPAN Encryption Key** | Protect FPANs in transit. | During card enrollment, you must encrypt card objects and enrollmentData objects containing the FPANs before transmitting to Mastercard. You can encrypt them using this public key. Mastercard will then decrypt using the private part. During encryption, obtain the key from the fpanEncryption URL and include the corresponding KID in the header of your JWE object. This key can be stored in cache for up to 10 days to ensure the latest key is available during key rotation. View the [Card Encryption](https://developer.mastercard.com/issuer-enrollment/documentation/tutorials-and-guides/perform-encryption-tutorial/index.md) tutorial for details. | Fetch the most up-to-date public keys (in a JWK format) via the following Mastercard URLs. | Environment | URLs | |-------------|-----------------------------------------------------------------------------------| | Sandbox | FPAN Encryption Key: | | Production | FPAN Encryption Key: | Refer to [JSON Web Key RFC](https://tools.ietf.org/html/rfc7517) for a definition of the format of this JSON object. The Key ID Parameter (kid) shows the purpose of each key. ## 1. Add API Signing Key {#1-add-api-signing-key} The **Key Management** tab on the Mastercard Checkout Solutions onboarding application allows you to add and download API signing keys for use on both the Sandbox and Production environments. Tip: The API Signing Key (OAuth key) and Consumer Key are auto-generated in Sandbox (Mastercard Checkout Solutions - Sandbox). It is advisable to start with the auto-generated keys in the Sandbox before proceeding to adding your keys in the Production environment. After creating, you can test your API Signing Key using Insomnia. Detailed instructions are provided at [use-insomnia-rest-client-for-mastercard-apis](https://developer.mastercard.com/donations/tutorial/how-to-install-and-configure-insomnia-tool/). Two options are available when adding your API Signing Key: * [Option 1: Adding keys using the browser keystore](https://developer.mastercard.com/issuer-enrollment/documentation/tutorials-and-guides/key-management-click2pay-tutorial/index.md#option-1-adding-keys-using-the-browser-keystore) * [Option 2: Using a Certificate Signing Request](https://developer.mastercard.com/issuer-enrollment/documentation/tutorials-and-guides/key-management-click2pay-tutorial/index.md#option-2-using-a-certificate-signing-request) ### Option 1: Adding keys using the browser keystore {#option-1-adding-keys-using-the-browser-keystore} 1. Access the Mastercard Checkout Solutions onboarding application on Mastercard Connect. 2. Navigate to the **Key Management** tab. 3. Click **Add Key** in the API Signing Key (OAuth key) section. 4. Provide a Key Alias and Keystore Password and click **Add** . ![Signing Key](https://static.developer.mastercard.com/content/issuer-enrollment/img/create_apisigning_key1.png "Adding New Keys Using Keystore") * Your browser generates a key pair and a Certificate Signing Request (CSR). * The browser keystore secures the private key and then forwards the public key via CSR to Mastercard. * Mastercard signs this key and sends it back as an X509 certificate. * Upon receiving this certificate, your browser generates a PKCS#12 keystore. 5. Your browser automatically downloads this PKCS#12 keystore as a file suffixed with ".p12". * The P12 keystore you generate contains a public/private key secured with the passphrase (Keystore Password) you added. The public key is shared with Mastercard during the generation process and will be used to verify the OAuth signature provided on every API call. The OAuth signature must be created using the private key inside the P12 keystore. #### View the contents of the keystore: {#view-the-contents-of-the-keystore} During key generation, you will give the P12 keystore a ***filename, password*** and ***alias*** (friendly name). So for example: * Filename: `srctest-sandbox` * Password: `keystorepassword` * Private key alias (friendly name): `keyalias` To view the contents of the keystore, you can use the following commands, either in Java Keytool or OpenSSL. * OpenSSL * Javakeytool ```OpenSSL openssl pkcs12 -info -in srctest-sandbox.p12 -password pass:keystorepassword ``` ```Javakeytool keytool -storetype PKCS12 -list -keystore srctest-sandbox.p12 -storepass keystorepassword -v ``` Note: Always keep your private keys safe, ideally in a password-protected or hardware keystore. If you lose this file you should revoke the corresponding key and generate a new one. ### Option 2: Using a Certificate Signing Request {#option-2-using-a-certificate-signing-request} You can manually upload a Certificate Signing Request (CSR) generated in your system. A CSR is an encoded file that provides a standardized way to send a public key as well as some information that identifies your company and domain name. This method will keep your private key secure, at no time will Mastercard see it or be able to recover it. Note: Once you upload your CSR file, Mastercard sets a default 364 day expiry period for the API Signing certificate. Mastercard will sign your certificate and your validated public certificate and generate a Consumer Key. This validated public certificate is the one that Mastercard will use to check your OAuth headers on your API requests. Before you can add new keys, you will need to generate a CSR from your Certificate Authority server. When you generate a CSR, you will be asked for the following information: * Country (C): The two-letter code for the country where your organization is located. For example, `BR`. * State/County/Region (ST): The state/region where your organization is located. This shouldn't be abbreviated. For example, `Brazil`. * Locality Name (L): The city where your organization is located. This should not be abbreviated. For example, `Curitiba`. * Organizational Unit (OU): The division of your organization handling the certificate. For example, `IT`. * Common Name (CN): The fully qualified domain name (FQDN) of your server or the host where you intend to use the certificate.For example, `yourdomain.com`. This is a required field. * Email Address: An email address we can use to contact you, usually belonging to the certificate administrator or IT department. For example, `CA@yourdomain.com`. * Key type: Mastercard uses RSA. * Key size: The size is 2048 bits. When your CSR is ready, you'll need to upload it using the Add Key button. ![Signing Key-CSR](https://static.developer.mastercard.com/content/issuer-enrollment/img/upload_csr_signingkey1.png "Upload CSR key") You will need to add the key alias you used in your key generation step. ### Commands {#commands} The CSR itself should be generated in Base-64 PEM format. You can open the CSR file using a simple text editor and it will look like the samples below. #### Example using OpenSSL {#example-using-openssl} Use the following command to create a private key and public certificate. * OpenSSL $ ls cacert.pem cakey.pem readme.txt "\> ```OpenSSL $ openssl req -newkey rsa:2048 -x509 -keyout cakey.pem -out cacert.pem Generating a RSA private key .+++++ ..+++++ writing new private key to 'cakey.pem' Enter PEM pass phrase: Verifying - Enter PEM pass phrase: ### You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. {#if-you-enter-3939-the-field-will-be-left-blank} Country Name (2 letter code) [AU]: State or Province Name (full name) [Some-State]: Locality Name (eg, city) []: Organization Name (eg, company) [Internet Widgits Pty Ltd]: Organizational Unit Name (eg, section) []: Common Name (e.g. server FQDN or YOUR name) []: Email Address []: `$ ls cacert.pem cakey.pem readme.txt ` ```
In the above command : * `req` option means you are creating a Certificate Request (pkcs10). * `-newkey rsa:2048` means you are generating a new RSA key of 2048 bits in size. * `-x509` means you are outputting an x509 structure instead of a cert req. * `-keyout cakey.pem` is the private key. * `-out cacert.pem` is the public certificate. #### Use the following commands to create a PKCS12 file: {#use-the-following-commands-to-create-a-pkcs12-file} * OpenSSL ```OpenSSL openssl pkcs12 -export -in cacert.pem -inkey cakey.pem -out identity.p12 -name "keyalias" Enter pass phrase for cakey.pem: Enter Export Password: Verifying - Enter Export Password: ``` In the above command: * `-name` is the alias of the private key entry in keystore. * `Export Password` is the Keystore password provided to access the .p12 file. #### Use the following commands to create a CSR file: {#use-the-following-commands-to-create-a-csr-file} * OpenSSL $ ls cacert.pem cakey.pem certreq.csr "\> ```OpenSSL openssl req -out certreq.csr -key cakey.pem -new Enter pass phrase for cakey.pem: You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. Country Name (2 letter code) [AU]: State or Province Name (full name) [Some-State]: Locality Name (eg, city) []: Organization Name (eg, company) [Internet Widgits Pty Ltd]: Organizational Unit Name (eg, section) []: Common Name (e.g. server FQDN or YOUR name) []:ad Email Address []: Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: An optional company name []: `$ ls cacert.pem cakey.pem certreq.csr` ` ` ```
#### Use the following command to check the CSR: {#use-the-following-command-to-check-the-csr} * OpenSSL ```OpenSSL $ openssl req -in certreq.csr -noout -text ``` To learn more about the requirements your CSR must meet, refer to [Mastercard Requirements for CSRs](https://developer.mastercard.com/platform/documentation/security-and-authentication/csr-requirements/). ## 2. Manage Keys {#2-manage-keys} You can manage keys in the Portal using a number of available options. A drop-down menu is available next to the details of each key. ![Key Management](https://static.developer.mastercard.com/content/issuer-enrollment/documentation/img/key_management_2.png "Key Management Functions") | Operation | Description | |--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Renew** | Key renewal is available for API Signing key, where it will bring up a **Renew Key** dialog, where you can either enter a Keystore Password or upload an existing CSR file. Although you can renew an existing certificate, we recommend adding new keys. Rotating keys is a recommended security practice. | | **Download** | Download a certificate file containing the public keys in either PEM, DER or P12 format. Only default, auto-generated keys can be downloaded in P12 format, allowing you to download the private key along with the public key. PEM and DER formats enable you to download the binary and text versions of the key, respectively. | | **Revoke** | Revoke a particular key. Once you revoke a key, the key becomes inactive immediately and you can no longer use it to access the APIs. When revoking an API Signing Key, ensure there's another active key. |
### Key Renewal Notifications {#key-renewal-notifications} Once you create a key, Mastercard sets a default 364 day expiry period for the key. Email notifications are sent at regular intervals to Merchants and PSPs if a key is approaching its expiration date. Note: To avoid service interruption, renew your API Signing Key prior to the expiration date. ### Key Metadata {#key-metadata} In addition to the keys stored in the certificate file, you should keep a record of the following key metadata as these will be required to test or integrate with Mastercard. * **SRC Client ID**: This identifier is referred to as Client ID. It is found on the Dashboard. * **Key ID (KID)** : The key ID is provided when adding an encryption certificate. This Key ID is returned by the [POST /transaction/credentials](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#checkout) API call as `KID` in the response header. So you will use this identifier to distinguish which of your keys is required to decrypt the payload. * **Key Alias**: The key alias used when generating the private part of the API Signing key. * **Keystore Password**: The password used when generating the private key. ## 3. Add Payload Encryption Key {#3-add-payload-encryption-key} Payload Encryption involves 2048-bit RSA public/private key pairs. Upload the public certificate (PEM format) generated as a part of the key pair in your own system. The encryption key should be unique. Ensure the encryption certificate you upload corresponds to a private key that has not been used before in this project. Tip: The Encryption Key is auto-generated in Sandbox (Mastercard Checkout Solutions - Sandbox). It is advisable to start with the auto-generated keys in the Sandbox before proceeding to adding your keys in the Production environment. 1. Access the Mastercard Checkout Solutions onboarding application on Mastercard Connect. 2. Navigate to the **Key Management** tab. 3. Click **Add Key** in the Encryption Key section. 4. Provide the Key ID and ensure your Key ID is unique. You cannot use a previously used Key ID (Step 2). 5. Browse and select the encryption certificate and click **Add Key**. Learn how to create an encryption certificate. Note: You can add up to three encryption keys in a project where only one can be active/enabled at a time. If three encryption keys already exist, use "Revoke Key" to remove one of these existing encryption keys to add a new one. ![Upload encryption key](https://static.developer.mastercard.com/content/issuer-enrollment/documentation/img/add_encryption_key2.png "Upload Encryption Key") ### Create a private key and public certificate {#create-a-private-key-and-public-certificate}
Use the following command to create a private key and public certificate: * OpenSSL $ ls cacert.pem cakey.pem readme.txt "\> ```OpenSSL $ openssl req -newkey rsa:2048 -x509 -keyout cakey.pem -out cacert.pem -days 365 Generating a RSA private key .+++++ ..+++++ writing new private key to 'cakey.pem' Enter PEM pass phrase: Verifying - Enter PEM pass phrase: ### You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. {#if-you-enter-3939-the-field-will-be-left-blank} Country Name (2 letter code) [AU]: State or Province Name (full name) [Some-State]: Locality Name (eg, city) []: Organization Name (eg, company) [Internet Widgits Pty Ltd]: Organizational Unit Name (eg, section) []: Common Name (e.g. server FQDN or YOUR name) []: Email Address []: `$ ls cacert.pem cakey.pem readme.txt ` ```
The Common Name (CN) is a required field, which should be the FQND (Fully Qualified Domain Name) of the server or the host where you intend to use the certificate. In the above command : * `req` option means you are creating a Certificate Request (pkcs10). * `-newkey rsa:2048` means you are generating a new RSA key of 2048 bits in size. * `-x509` means you are outputting a x509 structure instead of a cert req. * `-keyout cakey.pem` is the private key. * `-out cacert.pem` is the public certificate. * `-days 365` is the number of days a certificate generated by -x509 is valid for. Ensure the key expiration time is included when creating your encryption key pair and is between 360 days and 3 years.