# API Basics
source: https://developer.mastercard.com/authentication-facilitator/documentation/api-basics/index.md
## Security Overview {#security-overview}
Two security layers are used for the protection of sensitive PCI/PII information. All communication between the Authentication Facilitator API and the Issuer's Server(s) are secured using mutually authenticated TLS. In addition, all PCI sensitive data (such as Account PAN) and all Account holder personally identifiable information (PII), such as PAR are encrypted for transport using a separate key. The encrypted data contains an additional timestamp to specify the encrypted data validity period. This prevents the same encrypted data from being replayed after the validity period expires.
All operations related to key management shall comply with the [Keys and Certificates](https://techdocs.mastercard.com/bundle/m_MDESQG/resource/mc_mdes_key_cert_qg.pdf).
## Mutual TLS Authentication {#mutual-tls-authentication}
Communication between Authentication Facilitator API and issuer web service are secured using mutually authenticated TLS.
During TLS handshake Mastercard presents an Internet X.509 Public Key Infrastructure certificate - the Mastercard Client Certificate - signed by Entrust public Certification Authority (CA). Therefore, to validate the Mastercard Client Certificate, the issuer must ensure its Internet appliance has an access to a trustore containing the Entrust Certificate Authority L1k certificate chain. The Entrust Certificate Authority L1k certificate chain can be downloaded from the [Entrust website](https://www.entrust.com/get-support/ssl-certificate-support/root-certificate-downloads/).
During TLS handshake, the issuer presents an Internet X.509 Public Key Infrastructure certificate - the Issuer Server Certificate. For Mastercard to validate the issuer's Server certificate, it must be signed by a CA. For the updated list of CAs, please contact your Mastercard representative.
Note: Self-signed server certificates are not allowed by Mastercard
During TLS handshake Mastercard and the issuer's server agree upon a TLS cipher suite to use for exchanging messages within the established TLS connection. The issuer must support a minimum of one Mastercard-supported TLS cipher suites. The Mastercard-preferred order of TLS cipher suites are as follows.
For TLSv1.1:
* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
* TLS_RSA_WITH_AES_256_CBC_SHA (weak)
For TLSv1.2 (recommended):
* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
* TLS_RSA_WITH_AES_256_CBC_SHA256 (weak)
* TLS_RSA_WITH_AES_256_CBC_SHA (weak)
## Encryption {#encryption}
The PCI/PII sensitive data is encrypted using a single use encryption key (SK), which is transported in a digital envelope encryptedKey within the TLS tunnel. The digital envelope is created with the encryption public key provided by the Issuer during onboarding. The encryption public key is known as the Mastercard Encryption Key within the project created by the Issuer on Mastercard developers.
An overview of the PCI/PII payload bulk data encryption process is provided in the figure below.
[The Issuer must use the PKCS #11 v2.20 standard](https://static.developer.mastercard.com/content/authentication-facilitator/uploads/pkcs-11v2-20.pdf)
SK is generated by a strong pseudorandom number generator built into the Harware Security Module (HSM). SK is wrapped with the encryption public key provided by the Issuer during onboarding - the Mastercard Encryption Key, in a RSA digital envelope computed using PKCS#11's C_WrapKey method (section 11.14), which is defined on page 178 of the PKCS #11 v2.20 standard.
The Issuer acting as a receiver of API encrypted payloads must support an unwrapping mechanism chosen amongst the following:
| Value of hash algorithm during Onboarding | Issuer must use |
|-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| None | the PKCS#1 v1.5 RSA mechanism (section 12.1.6) denoted CKM_RSA_PKCS, defined on page 197 of the [PKCS#11 v2.20 standard](https://static.developer.mastercard.com/content/authentication-facilitator/uploads/pkcs-11v2-20.pdf), for unwrapping SK in the encryptedKey received from Mastercard. In such cases, the 'oaepHashingAlgorithm field is not present in the EncryptedPayload object. |
| 'SHA256' or 'SHA512' | the PKCS#1 RSA OAEP mechanism (section 12.1.8) denoted CKM_RSA_PKCS_OAEP, defined on page 200 of the [PKCS#11 v2.20 standard](https://static.developer.mastercard.com/content/authentication-facilitator/uploads/pkcs-11v2-20.pdf), for unwrapping SK in the encryptedKey received from Mastercard. In such cases, the 'oaepHashingAlgorithm' field is present in the EncryptedPayload object with the value either 'SHA256' or 'SHA512' depending on the issuer choice during onboarding. |
Within the mechanism parameters table CK_RSA_PKCS_OAEP_PARAMS (section 12.1.7) defined on page 200 of the PKCS#11 v2.20 standard, the following two parameters are considered:
* CK_MECHANISM_TYPE indicates the message digest algorithm used to calculate the digest of the encoding parameter;
* CK_RSA_PKCS_MGF_TYPE indicates the Mask Generation Function (MGF) to use on the encoded block.
The Authentication Facilitator API fills in these parameters as follows:
| If during the onboarding Issuer has chosen.. | Then issuer must expect.... |
|----------------------------------------------|-----------------------------------------------------------------------|
| "oaepHashingAlgorithm" = "SHA256" | CK_MECHANISM_TYPE = CKM_SHA256 CK_RSA_PKCS_MGF_TYPE = CKG_MGF1_SHA256 |
| "oaepHashingAlgorithm" = "SHA512" | CK_MECHANISM_TYPE = CKM_SHA512 CK_RSA_PKCS_MGF_TYPE = CKG_MGF1_SHA512 |
Mastercard exposes:
* The digital envelope containing the one time key SK in encryptedKey.
* The bulk encrypted data encryptedData containing the sensitive data.The hashing algorithm used by the OAEP scheme, when chosen - oaepHashingAlgorithm.
* The hashing algorithm used by the OAEP scheme, when chosen - oaepHashingAlgorithm.
* The public key fingerprint publicKeyFingerprint of the Issuer Encryption Public Key used by the encryption scheme for the computation of the digital envelope.
* The initialization vector - iv - for the bulk encryption with AES in CBC block cipher mode.
## API Design Principles {#api-design-principles}
The Authentication Facilitator API consists in a single Remote Procedure Call (RPC) style stateless web service where the API endpoint represents an operation to be performed. All request and response payloads are sent in the JSON (JavaScript Object Notation) data-interchange format. The endpoint in the API specifies the HTTP Method used to access it. All strings in request and response objects are UTF-8 encoded. The API URI includes the major and minor version of API that it conforms to. This allows multiple concurrent versions of the API to be deployed simultaneously.
All APIs return an HTTP response code of 200 if the call was successfully received and accepted for processing. To ensure forward-compatibility, all API integrations must be resilient to new elements being added to requests. Any errors that subsequently occur during processing are returned in the response payload.
**To ensure forward-compatibility, all API client implementation must be resilient to new elements being added to outbound requests from the Authentication Service.**
### URL Scheme {#url-scheme}
The API URL follows the format:
scheme://host[:port]/contextRoot/api/majorVer/minorVer/apiName
| URL Element | Definition |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| scheme | https |
| host\[:port\] | Hostname and optionally port number for the environment as provided by issuer during onboarding e.g. [www.issuersite.com](https://www.issuersite.com). |
| contextRoot | Context root for the service as provided by Issuer during onboarding e.g. /root/directoy1/directory2/directory3 |
| api | authentication |
| majorVer | The major version of the APIs. This is not related to the version of this document. This version of the document corresponds to a major version of: 1 |
| minorVer | The minor version of the APIs. This version of the document corresponds to a minor version of: 0 |
| apiName | The URL endpoint as defined in the respective section for the API operation. |