JSON Web Encryption (JWE)
The implementation of JWE with RDX facilitates the secure transmission of API requests from VCAS to the issuer/partner, protecting sensitive and non-sensitive data provided through the challenge process.
JSON Web Encryption
JSON Web Encryption (JWE) is an open message encryption format which can be used as a method of securely passing the RDX message during transaction processing. This is a standard naming convention format used by Cardinal to identify the JWE certificate rotation information. Specific information regarding JWE implementation is covered in RFC-7516.
VCAS encrypts the RDX payload message and formats it according to the JWE specification. The encrypted RDX payload message is then sent to the issuer’s server where the issuer processes the JWE and decrypts the message for further processing. Note that the client RDX response will not be encrypted.
Supported JWE Formats
Currently VCAS only supports certain JWE algorithms for both key management and content encryption.
The key management algorithm is used for key exchange between Cardinal and the issuer and for wrapping the content encryption key during message encryption for JWE.
Key Management Algorithm | JWE Algorithm (alg) Value |
---|---|
RSAES OAEP using SHA-256 and MGF1 | RSA-OAEP-256 |
The content encryption algorithm is used for ephemeral key generation and content encryption of the RDX payload/message.
Content Encryption Algorithm | JWE Algorithm (enc) Value |
---|---|
AES GCM using 256-bit key | A256GCM |
JWE Sample Request
This screenshot below shows a sample of the encrypted payload similar to what issuers receive from VCAS:
Encrypted Payload
eyJraWQiOiJSRFhNRVRFU1QtUEtFLUFDUy1DQy0yMDQ4U0hBMi1ERVYiLCJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ.EOx5dinhHNb8YcFnI7qFXofquFVMAQqjo7gH_FNJAPwvYeQcBMIIT3ivlx3EcQL7B0tgGMHfNY_pBgdvVB3yp6ULYeWn-r3TXMnTQ-BTPQn1SfCV-XrSlajs4npvjHTtE75GO3pk3p3At6UbwUKC36O8tDHIejJi1Ffc_DBJJuCl50c1ymq1mmwu3_mLrkrhDZkv5-Y7Ypchpl6zpl2P9n74JqKB0lqTy79mInw6ep5RMdS87tAfpacKHsHRal6CcEfGwzW-CjnnDtWPwCoiE17vGR6lX7Jaaxg-zoAR2w5MMNdy0SOq9z5axaNwPqXbWA5vgx0hdRFhcXWp6idvTA.zzyUpS2qJBGn6IKI.nEkGBa8H7T9k40AyD8FtjdvZ89xtkBx8DzQ2wsPcUaexJknXTzqWOaXgApJbLON7g7Vc2br7czxL9U-f24KPG73tHyiWc5pcddpTQb_wpK1zGd3QJzkjkaCxkW_8PXI5VqRGZTVLQ_eGHl7y3YIAR_hdBsFigjZYns5osAoUN5udTZoaV6Te2VssyBrC5epPmfRnM2iOs1BZaP4zqDmwDDNPZUu1_bmPQ3AR4hJGY6xjzXCCjH-2iQ-WpWcpzAMxx-jDl7z4g7aR4KrlamCQx-zi8RoyNBmxtTJWSv7P6bJYM_Ukz-aC2VoyWmCYEI1YQ6wcovzrl-cMXRAzYYQFV_rdOg9RvXjKeGSE4UgMW5wWyzyBbRTRRBvlXsPih9E59g8we5WFJU03QRMWcIzb3XUr1gCW7qA5xhsuG-qJk-8jCwoEoRCmFi3wQipZbpEBW_ycVTeFrJudajx6XErS34Dr2FC1x5sfqiv6-IwiXWTWE8XKUylwPDQ94cIHs5IvtK9JisvYQtIXIFdxbg68nwlJM7wKltZBga-o8JEENkR_gbFhIUVNcfJSfHFYYkrj__NrtodnQL85sbefPdUPzuaZk64U97cdRRRxQ8IrOhaQHwm4W6alLpMW6675wrTHevh4eCw793ftDiQ-sfL4-LyJ7TqeVahNYnwp3c2zzU_NQsPcp9Ofz4FuE6-ohdSD8hpcJxZUcnhFn1d0X3DmN2EQE7xB4WFj8Tcbvh4jedHp5pN9B7vE0EgnRC75ZMazcDxBYXJFMubesLXSOnBgBwKNqchoJXldtJwjSKan4U9QPn4IqwNZJVNDN3KXskH-GBwPskTQuODPw9z38NVy5h9cytsFOPX4eqBLP0hgxaIu-zVjEs1iyiVCJ0gyfGdtwDLdFV0CLAcrRtWvzudc1ez5VpQ9asnlN0M6B9yv1ss-RN23hyebhz6CGDg0h6K-udUdS6Zg8Qku6D4EJoYOjju5o_MpkYO3yUBict8Tx_HnNjisCZYUDb1_ytvweyupCjdn_8cS6r4QayA1kggjtu0d5JzYwFbwcYUdVDuvHmVl4PgDDw-OdJ8FYX8coOl2W_zQV6bmKIVO4nBL8n1Oq63ugDFks2r_YzseWMJ5Nfj7QZUEWKIXGEiB6IljfULoaYXNtdfwOvRKtY_Xz6UnpgNr8qQ0U8MYXD565wOurybcm6MoVBksfVWkq2SWKtDH-CAzdbuGOUzDDCZIwjTtfdXNKS7gJu8JPxvF0gztqsCLNeKmEqezEKgcZlKqWSp6wEyFeMr07GzOzJE8ehBbDkvwUZNYppm7Jklw79LlwrFwyrTgzRHO3tTJFHZrFZYIvuT4hMwiZS9Ec-z74pg2TUnC9_xSXQTUvuVXanyY_qQHiCxn6HsvqKxmXLzCQ4cbhKWkKdHP7kqTwmzdry0-UZ_5QLGP7zn50Cm3mpccHwYkvPCiu_9Uhpz4pN2LV4-fyXDQBh2RloCwznMVPLngDbeeCQuFNRmgunkZ3OuUj_HJuLA37egolRG9PYXztZxeemnRiTGi7F05HDMCpdMTiuTiV7EZaL6-Ivq8ADrdYLeV0nAyJcihlgLQjauMbbXQdzv644vvzqFn_knAnC4WHAb1lEtwEXZMqVcCFHRiC8Pc6eSTKHR69MOsbaYPiKlcRrMMMDOkp3Yq7Z_4wLCWj4qSUqcXqESynOayS17ENs5AzKb7nsEMWX4xWLvIY76z3cC7kbr-ExBk6A3M3rKsHWCVQJL8nFHbV551wtMbyjan61SLnuASntKNqmxh5JfMqwxSOEr4YZMhlzuLxdDUE66A5xxdhEuItRE0Zr1GutkoLVkc4anqD3OU9LYCJUItOA7rLDzQebX2bnloA13tzjYHSz_aRaqZogwWR-itzBSbdO4rGewuzvv10W9n3ldyrAfFGW75OKyX6SjDym6mm_TYMvJVpg2dHRLHED9ShqSsAe76R2V2pHHg65rPCp-MNIl4bFCLgRVT8CwtVRqnXRNbd37h0dPscGt6eU6kr7emUJdTTbeO.YOf0HEccaA7Wiw4PuWJlGQ
Decrypted Payload
{
"kid": "RDXMETEST-PKE-ACS-CC-2048SHA2-DEV",
"alg": "RSA-OAEP",
"enc": "A256GCM"
}
{
"ProcessorId": "5723ae630063ac1a9c3ab079",
"IssuerId": "5723ae630063ac1a9c3ab083",
"TransactionId": "00ec043e-40b5-4ce4-95c2-9e83b644f412",
"DSTransactionId": "00ec043e-40b5-4ce4-95c2-9e83b644f987",
"ThreeDSRequestorAuthenticationInd": "01",
"StepupRequestId": "878f4751-4140-4881-9e4a-003e83524f22",
"DeviceLocale": "en-US",
"DeviceUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36",
"MessageVersion": "2.2.0",
"RDXMessageVersion": "2.2.3",
"MessageCategory": "01",
"MerchantInfo": {
"AcquirerId": "1337",
"AcquirerCountryCode": "840",
"MerchantId": "876543210",
"MerchantName": "Ranier Expeditions",
"MerchantURL": "https://www.requestor.com",
"MerchantCategoryCode": "0123",
"MerchantCountryCode": "840",
"MerchantAppRedirectURL": "merchantScheme://appName?transID=b2385523-a66c-4907-ac3c-91848e8c0067"
},
"PaymentInfo": {
"CardNumber": "redacted",
"CardExpiryMonth": "08",
"CardExpiryYear": "28",
"CardHolderName": "Jane Doe"
},
"TransactionInfo": {
"TransactionCurrency": "840",
"Channel": "02"
}
}
JWE Certificate Creation (New Implementations)
During the implementation process, VCAS will request the initial certificate from the issuer. Issuers should work with their VCAS Implementations Manager to coordinate the details of the new JWE certificate creation.
Following creation of the certificate, the issuer should export and send only the public key in certificate format to CardinalCommerce.
Key-Pair Generation (New Implementations)
The issuer will generate a key-pair based on the key management algorithm chosen above, using openssl, key tool or a similar tool. The public key/certificate will be encoded with several pieces of information as shown below. The key/certificate will then be exported as a certificate and sent to Cardinal’s key management team to be imported into the VCAS system. Cardinal follows NIST recommendations for key-wrapping of two years.
Shown below is an example of the certificate that the issuer sends to VCAS:
-----BEGIN CERTIFICATE-----
MIIJojCCB4qgAwIBAgITFQACoT1f6hJJ+g1QuwAAAAKhPTANBgkqhkiG9w0BAQsF
ADBoMRMwEQYKCZImiZPyLGQBGRYDY29tMRMwEQYKCZImiZPyLGQBGRYDY
GAYKCZImiZPyLGQBGRYKZ2xvYmFsdGVzdDEgMB4GA1UEAxMXQU5aIEdsb2Jh
c3QgQ0EgMDEgdjMwHhcNMjIxMDE5MDMzMDIxWhcNMjMxMDE5MDMzMDIxW
mvpuGfZHkPbUC/91IQLe/Kerp/IBgz6TuOriTuKn8xJwpypwH0iqK6cBlm9WWgW
vizZa0LnAoCz2xYeUc9ebH+0Fl2+4ZEc3pWEJxc8UdEA6ZmtxhInY56gANpxyRp9
ByDr2JzzcweEEBmq6ShFjZyb5njUYixjYPDspL2QRh5D/6D1Ybmbk0nBGhdYAjxe
sis+rCjA3yotZSjsm39QZMxYulHayIHK7f4hQrZcqwEf3OioDwqqCfo89+NIunD0lpk
pKmCCxCqEZZVrr55XXP6JqXk/XCIo/YcwrteLaryqUSWPxaSrFWceLw6mSA9kRC
/xdmYkkehzc7R2rFIXlI1pQwpwIDAQABo4ID5jCCA+IwRAYJKoZIhvcNAQkPBDcwl
NTAOBggqhkiG9w0DAgICAIAwDgYIKoZIhvcNAwQCAgCAMAcGBSsOAwIHMAoG
SIb3DQMHMCcGCSsGAQQBgjcVCgQaMBgwCgYIKwYBBQUHAwEwCgYIKwYBBQ
cDySVyZ3hZLIX3SAt2asO+meYp0McT5tSEC95Oksgm6/sdwErFbiiRnt2ytlgO8Nko
T9HwMWWJOqn6/dJfwrdBfiawwPdznkEP10olExj9ggX814fnVN6nwm2d2YzieMXp
-----END CERTIFICATE-----
Key Exchange Process (New Implementations)
Implementation: During onboarding, issuers are required to generate and exchange a new key-pair using their own internal conventions. Unique key-pairs must be generated for both Staging (UAT) and Production environments.
The key-pair generated must only be used for the JWE integration and for no other purposes.
- Issuer generates key-pair in their system using their conventions (not defined by Cardinal)
- One key-pair for each environment – STAG (UAT) & PROD
- Key rotation frequency
a. NIST – Two-year recommendation - Issuer generates a certificate
- Key generation
- RSA encryption: RSA 2048, 3072 or 4096
- 4096 is the preferred format
- These parameters on the certificate need to be completed with the appropriate information:
- "key usage", "o", "ou"
- o = organization
- ou = organization unit
- Contact email in certificate for easy tracking when expiring
- Specify a two-year expiration date
- "key usage", "o", "ou"
- Certificate must be X.509 type using one of the following extensions:
- .pem
- .cer
- .crt
- .p7b
- Key generation
- Issuer or CA does not need to sign this certificate
- Issuer provides email and contact information for their key team / renewal
- Issuer exports and sends only the public key to Cardinal
- Issuer sends email with public certificate/key to their VCAS representative
- VCAS representative submits internal request to the certificate management team for review
- VCAS representative provides client with alias name. Alias name is part of encrypted message. Client will need to ensure acceptance of VCAS alias name; alias names must match what is provided by VCAS; alias names are unique per environment; STAG, PROD
- Issuer sends follow-up email with the SHA256 checksum value of the certificate for validation of authenticity.
Note: VCAS uses a standard naming convention when creating a new public certificate. Issuers should follow this naming convention to ensure compatibility with VCAS certificates. The VCAS alias name will be provided to the issuer during the implementation process.
Additional JWE Information
The Common name is driven by the client creating the certificate.
Key ID is a value that appears after the issuer decrypts the RDX payload, which is a Cardinal/VCAS assigned naming convention. This can be supplied by your VCAS representative. The format for the Key ID is shown below:
[Reason/Entity]-[Use Case For Cert]-[MPI/ACS]-[Cert Owning Entity]-[Bit Length/Algorithm]-[Environment]
Sample: 1234dadc1234b704c1f23dc4-PKE-ACS-Client-2048SHA2-STAG
After receiving the RDX request, the issuer will decrypt the payload and process the RDX request.
For both new certificate generation and certificate renewals, VCAS will communicate with the client via email to the address provided during the client onboarding process. Clients should configure their email accounts to recognize and trust emails from [email protected]
JWE Certificate Expiration and Renewal
For certificate renewals, the VCAS PKI team will send a renewal notification email from [email protected] at least 60 days prior to expiration. The renewal notification from VCAS will provide keys details of the expiring certificate, including the common name, serial number, alias, and expiration date.
Once the client issues the replacement certificate, they should forward it to [email protected]. VCAS will then start the change control process to rotate the certificate. The client should support both certificates until receiving an email from VCAS confirming that the new certificate has been installed.
Cardinal follows NIST recommendations on key rotation frequency requiring key-wrapping rotation every two years. For key rotation, Issuers are required to perform a key generation process and send the new public certificate to VCAS. The VCAS certificate team will send the issuer a renewal notification 60 days prior to key expiration. If VCAS does not receive a response, VCAS will engage the support team to provide an alternate issuer contact.
Contact your VCAS account representative for additional information.
Updated 5 days ago