# Manage API Keys source: https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md To integrate with Mastercard Checkout Solutions, you need the following keys: | Key | Purpose | Description | |---------------------------------|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **API Signing Key (OAuth key)** | Authenticate API calls | * API Signing Key is a 2048-bit or 4096-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 whose 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 password protected. * To get started, you can access the default API Signing Key from Mastercard Checkout Solutions onboarding application on Mastercard Connect. * Follow these steps to [create the API Signing Key](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md) on Mastercard Connect. Tip: Learn 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 first 48 characters (before the exclamation mark) of the consumer key represent the Client ID. The last 48 characters (after the exclamation mark) of the consumer key represent 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 or 4096-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/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md) 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/). | ## Mastercard Public Keys Mastercard {#mastercard-public-keys-mastercard} Mastercard generates two keys for the following purposes. | Name | Purpose | Description | |------------------------------|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Payload Verification Key** | Authenticate the source of payload. | Alongside encrypting the payload with your public \[Payload\] Encryption Key (detailed in the previous table), Mastercard signs it using the private part of this Payload Verification Key. During payload signature verification Integrator uses the corresponding public part to verify if the payload has come from Mastercard. You can identify the correct verification key through the header of the JWS signature containing a KID that corresponds to a public key on the **payloadVerification** URL. These keys can be stored in your cache for up to 10 days to ensure that the current and future keys are available during key rotation. | | **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/mastercard-checkout-solutions/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 | * Payload Verification Key: * FPAN Encryption Key: | | Production | * Payload Verification Key: * 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. Note: You must work with your [Mastercard representative](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/support/index.md#get-help) for required keys and certificates to receive notifications from Outbound API endpoints. Refer to [API Reference](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/index.md) section for more details. ## 1. Add Signing Key {#1-add-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. Two options are available when adding your API Signing Key: * [Option 1: Adding keys using the browser keystore](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md#option-1-adding-keys-using-the-browser-keystore) * [Option 2: Using a Certificate Signing Request](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-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 **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/mastercard-checkout-solutions/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 a 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. During key generation, you will give the P12 keystore a ***filename, password*** and ***alias*** (friendly name). 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 generates 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 of 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, upload it using the Add Key button. ![Signing Key-CSR](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/upload_signing_keys.png "Upload CSR key") You need to add the key alias you used in your key generation step. ### Commands {#commands} Generate the CSR in Base-64 PEM format. Open the CSR file using a simple text editor--- it should look like the samples below. #### Examples using OpenSSL {#examples-using-openssl} Use the following commands to create or check the required files. * 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 Widgets 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 * 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. * 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` ` ` ```
* 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. Add Payload Encryption Key {#2-add-payload-encryption-key} Payload Encryption involves 2048-bit or 4096-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 **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 (KID). 5. Browse and select the encryption certificate and click **Add Key**. 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. ![Add encryption key](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/add_payload_encryption_key.png "Add Encryption Key") ### Create a private key and public certificate {#create-a-private-key-and-public-certificate} Use the following SSL 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 FQDN (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 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 the expiration date should be within 59 days to 3 years. ## 3. Manage Keys {#3-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. ![Image](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/img/key-management-functions5.png "Key Management Functions") | Operation | Description | |----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Renew** | * Key renewal is available for both API Signing keys and Encryption keys. * For Signing key, it will bring up a "Renew Key" dialog - you can either enter a Keystore Password or upload an existing CSR file. * For encryption key, "Upload Certificate" functionality can be used to renew the key. Although you can renew an existing certificate, we recommend adding new keys. * Rotating keys is a recommended security practice. Note: * Before making API calls with a newly-added or renewed signing key, remember to update the OAuth header with the private key to avoid authentication issues. * After renewing an existing encryption key with a new one, Mastercard recommends you retain the old private encryption key until you see the new Key ID (KID) in the JWS header of the payload sent by Mastercard. | | **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 to you download the binary and text version of the key, respectively. | | **Enable Key** | * You can use this function to enable or disable encryption keys. * When an encryption key is created or uploaded for the first time, it is marked as "Enabled". * At a time, you can only create and enable one encryption key. * When an encryption key is enabled, the rest of the keys will be disabled. If you want to use a different encryption key, you must enable that key. * The enabled key should be used to perform checkout transactions. | | **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 and Encryption 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/mastercard-checkout-solutions/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.