Close
Data-Encryption
JWE Encryption

JSON Web Encryption (JWE) & JSON Web Signature (JWS)

JSON Web Encryption (JWE) represents encrypted content based on the JSON data structure. The cryptographic algorithms and identifiers for use with this specification are described in the JSON web algorithms (JWA) and IANA registries. The Related Digital Signatures and Message Authentication Code (MAC) capabilities are described separately in the JSON Web Signature (JWS) specification. To maximize security, JWE is being implemented for asymmetric encryption of sent requests.

The steps below are followed:

  1. Encrypt the request body, using a public key.
    1. Algorithm: RSA_OAEP
    2. Encryption method: A256CBC_HS512
    3. Public key (RSA .pem), this key is generated by NovoPayment and shared with the customer (NovoPayment is the owner of the private key)
  2. Sign the request body (encrypted text) by using a private key.
    1. Algorithm: RS512
    2. Private key (RSA .pem), this key is generated by the client. The client must generate a public key which must be shared with NovoPayment for signature verification on the request.

Note [important]: The JWE & JWS are enabled within the QA and Production environments. In sandbox environment, the client can consume the APIs without performing the JWE & JWS steps.

JWE keys generation and example of its use

This section describes the different steps to generate the JSON Web Encryption (JWE) keys. By using the “Open SSL” tool, please do the steps below.

Private Key generation

Command

{
$ openssl genpkey -algorithm RSA -out jwe_private_key.pem -pkeyopt rsa_keygen_bits:2048
}

Result

Result

Public Key generation

Command

{
$ openssl rsa -pubout -in jwe_private_key.pem -out jwe_public_key.pem
}

Result

Result

Usage

Below, the steps to perform in order to generate a JSON Web Encryption message.

jwe_public_key.pem content:

{
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA/L8BImxMGutiFyB2oY1l
29rQmGQrPxRl64h0ouzIHbj7Zm/r7flqeZG9dY19i1wWeeAG5wl15T3wvUPlV/xr
wv3MdEr3bmSQHipeXnm7UTB+LkSoIYmnqR9GEzQVJs42dmy4hYp1fLLBRh0blJnY
zfetkDWXiPhUuSv4kU+4/A7fMSFWDQpXC+Xae5i0Kd7TDwm2SVf31F6cyMTCY6Gk
SVmiBEZJEElKf2cPPVYlcRVsq+AtaC/dPU3wRVDoJtuwqG4jhSpi5yI7IajfsmiO
HKptQCsCIXYT5rsALDUgaeegVBCaidYNie5Ncl2Aie/5d69y5weliZzeFYmI8MIQ
5QIDAQAB
-----END PUBLIC KEY-----
}

**Payload example (without encryption):**
```js
{
    "programId": "TDDOV",
    "type": "named",
    "expiration": "1825",
    "line1": "TEST IOOO",
    "line2": "debit",
    "cardHolder": {
        "accountNumber": "1601064713272000306529025205",
        "documentType": "CC",
        "documentNumber": "1999230927",
        "firstName": "TAE NOM DCBZA",
        "lastName": "TAE APE DCBZA",
        "maternalSurname": null,
        "birthDate": "1989-02-10",
        "city": "Alban Cundinamarca",
        "state": "Cundinamarca",
        "country": "Colombia",
        "nationality": "Colombiano",
        "gender": "M",
        "maritalStatus": "S",
        "email": "tae_qbtjj@mailinator.com",
        "address": "56 67 12 casa",
        "codeAddress": "11002",
        "birthPlace": "Colombia",
        "phone": "573995935597",
        "branchId": "1"
    }
}

JWE representation of the payload:

eyJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.yFjF3DbNPfQuZtXbVaPgFk
3AcltIC_9a39E2ppY5avbqJdrYwZwPZphoD2N5mGCeipwfu3-
KoKAGadZS8DDB8WCWVfR_Wf2Hc7IJJsNXnMs5gZRzfFBiBpYyX-MdQ0YREYMyac1oD0as70hvc32aOtmChfrQSdMBxQkWDSJNF7TGZ_ml74eJjB14Ef7QCrxyBMevWJu
I2GtlKE9X2dWHkE4VFvnS4GniQsJkqhpe_OYFi8Eo5UHxHY2vfH6tbKVxzGnMVJtZBtd8SVAVIlSSkcSqi
_ggeE3AI9LMoTtJaiuzVUepsxAKC82bTxg1hTcy1b15KwiSg8DXHb4bzMJFOA.piFFKMwWKztbWnnC
GRb7hA.YU_o8TsYilMm697Y4mTDt480fJ4Rvq_JBL4MwuKIjPrrkIah8BJIId_Lclf2LqTT873EDkXSFPP01l
33Yt3vwIGsymXB0qd9RehpfUI4N6F8kyPgZ0_yQnnC33DSw5JVwDsCzWFISk4CjHk4TwOV8BoxYWF0
siuCV7_OeFA9Y1ByW8YRFpkjWSXd9CpGYwhU5sBrb-7iMqDxjaev04ZJQbkBdWz2JwtD9D5myD0jzzxmNWf_3h9gTq6L49E_1B4t_FSJg4B7jKhujK95_k0LWy
Heplp45Tb0Qm9ISQa65a2nxuO52WZzGUsyTHxCnoq6s-Y1DY0wqF4q1sf4Tpzcnu70AiWHjuI_K0oEM6Fr6UoXDpj9DN-A9-4U-7OTaurDTIAQJbzQYhqLu2ZU3kTwXtlzZNX4TjNeWkHAlvzEHjjux8tPq2XATsOEqn6ruuzWykf2K3Q_B
CdRAszZXjyMUDbT1IIIjfzpYzaZ3JkrJJeeOIOiag2iwCpUyIBlxMY0_cNu7aZVSKRnIBB9jOwizFghA1ACr
V3pm1MTYIvJ3Ztvt5Pvp5lW-xY4ybMqPrtGTmD1J-m8qlg2Hv-Kn4ZGdavw0K9rvdYA2RkIwsQhphrhBBjsKKDLiTVQEV9Rr7Uc__z50jDDXhZlnKVxNs6p7UKQqMKB8Jk
Dp9J1suINqp3Ln95Eu90UUqGWtcih7qytSSzo7j5qElJAdMpPKI1XaWPieoIJEQHPnAb-fMNXyCFuo-SKwqYJKelkQGbL3Gu69ZHRtLCM2M3gmk-KWWAPn17A1JxgjPv-JT1LMqNigqDgXQTSvcgA_S-lwvZw1gTFv6hdOkeQPwXVDj-dxyVQW6t9c2YbwiSN8zu4F3B8KRdQgfexNrR9JrKRlJTD5VJkiFSftpaj0n00MbHN1YuejpUvsLZD8zZ6
H31ai-SFTGAhHF_5sVu8_tDAM9gJI3yBjYKIPFJT1SfQdqVfA9IhjbCJaZboF07s42vq8Q0H_YwEe2iF_NcnQHW
6yOwBfPh7OMhOocXzY1yNnAbnD1H9KqFjolvg4o80Ws_U6c38vC7kIYAUvdvv-wKayOyFISRa1nzOick5W1lG29FHCwtUSA.rzRGKI7CdSuw6cfjV4_TlTpWRpCZqjMmeI6--PO-Yh4

JSON Request with payload:

{
 "data": 
"eyJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.yFjF3DbNPfQuZtXbVaPgF
k3AcltIC_9a39E2ppY5avbqJdrYwZwPZphoD2N5mGCeipwfu3-
KoKAGadZS8DDB8WCWVfR_Wf2Hc7IJJsNXnMs5gZRzfFBiBpYyX-MdQ0YREYMyac1oD0as70hvc32aOtmChfrQSdMBxQkWDSJNF7TGZ_ml74eJjB14Ef7QCrxyBMevWJu
I2GtlKE9X2dWHkE4VFvnS4GniQsJkqhpe_OYFi8Eo5UHxHY2vfH6tbKVxzGnMVJtZBtd8SVAVIlSSkcSqi
_ggeE3AI9LMoTtJaiuzVUepsxAKC82bTxg1hTcy1b15KwiSg8DXHb4bzMJFOA.piFFKMwWKztbWnnC
GRb7hA.YU_o8TsYilMm697Y4mTDt480fJ4Rvq_JBL4MwuKIjPrrkIah8BJIId_Lclf2LqTT873EDkXSFPP01l
33Yt3vwIGsymXB0qd9RehpfUI4N6F8kyPgZ0_yQnnC33DSw5JVwDsCzWFISk4CjHk4TwOV8BoxYWF0
siuCV7_OeFA9Y1ByW8YRFpkjWSXd9CpGYwhU5sBrb-7iMqDxjaev04ZJQbkBdWz2JwtD9D5myD0jzzxmNWf_3h9gTq6L49E_1B4t_FSJg4B7jKhujK95_k0LWy
Heplp45Tb0Qm9ISQa65a2nxuO52WZzGUsyTHxCnoq6s-Y1DY0wqF4q1sf4Tpzcnu70AiWHjuI_K0oEM6Fr6UoXDpj9DN-A9-4U-7OTaurDTIAQJbzQYhqLu2ZU3kTwXtlzZNX4TjNeWkHAlvzEHjjux8tPq2XATsOEqn6ruuzWykf2K3Q_B
CdRAszZXjyMUDbT1IIIjfzpYzaZ3JkrJJeeOIOiag2iwCpUyIBlxMY0_cNu7aZVSKRnIBB9jOwizFghA1ACr
V3pm1MTYIvJ3Ztvt5Pvp5lW-xY4ybMqPrtGTmD1J-m8qlg2Hv-Kn4ZGdavw0K9rvdYA2RkIwsQhphrhBBjsKKDLiTVQEV9Rr7Uc__z50jDDXhZlnKVxNs6p7UKQqMKB8Jk
Dp9J1suINqp3Ln95Eu90UUqGWtcih7qytSSzo7j5qElJAdMpPKI1XaWPieoIJEQHPnAb-fMNXyCFuo-SKwqYJKelkQGbL3Gu69ZHRtLCM2M3gmk-KWWAPn17A1JxgjPv-JT1LMqNigqDgXQTSvcgA_S-lwvZw1gTFv6hdOkeQPwXVDj-dxyVQW6t9c2YbwiSN8zu4F3B8KRdQgfexNrR9JrKRlJTD5VJkiFSftpaj0n00MbHN1YuejpUvsLZD8zZ6
H31ai-SFTGAhHF_5sVu8_tDAM9gJI3yBjYKIPFJT1SfQdqVfA9IhjbCJaZboF07s42vq8Q0H_YwEe2iF_NcnQHW
6yOwBfPh7OMhOocXzY1yNnAbnD1H9KqFjolvg4o80Ws_U6c38vC7kIYAUvdvv-wKayOyFISRa1nzOick5W1lG29FHCwtUSA.rzRGKI7CdSuw6cfjV4_TlTpWRpCZqjMmeI6--PO-Yh4"
}

JWS keys generation and example of its use

This section describes the different steps to generate the JSON Web Signature (JWS) keys.

By using the “Open SSL” tool, please do the steps below.

Private Key generation

Command

openssl genpkey -algorithm RSA -out jws_private_key.pem -pkeyopt rsa_keygen_bits:2048

Result

Result

Public key generation

Command

$ openssl rsa -pubout -in jws_private_key.pem -out jws_public_key.pem

Result

Result

Usage

Below, the steps to perform in order to generate a JSON Web Signature.

jws_private_key.pem content:

{
-----BEGIN PUBLIC KEY-----
MIIEpAIBAAKCAQEAzCB/DNHYN7Bse6QpuVoOnri6N/QX10znFo3HyW5tzClHsZTF
vvkJ+NM7YCBsmYNtahrm9EiA2HEPFY3bPfhxv6r8ywLPF+h7lnYA2UQIIy8L8kFm
VgpM/DTL0TEyQpkjzEp+eXG54nkRZP4qoDSaEeITt/0ib50FPRR8hZ9e00KPjfbf
TRDaxDIbFF2/ZkUjqi6+cX2g5dzPYuf/qemtv9+YyZEluOiwHjbbqRGmKe46xsGi
tdZ3Bmtm1VRpzjkJJRiV9As4OaS9wxAx3dNHzrlg4cXPJ8b2XfkbxbqDIYK7QMd6
Ig0uK5eG6mxLr8MiKuaZJhfzI3/31XGu34lwbQIDAQABAoIBAFkdOrobBnzRbZrQ
wVJk6YsLdGinDJ12ulATV4wtxItj3iO9olLMIDlb5kkB/sdKJEM1OWyeFnnnacFs
K7GzO92ERVZPhJ+YZBP8skQnujG6AUoimQ2o85ELb4uFIb8HYiR2xR45swAXAKwJ
dgx4ymZSP2+MeDMn5riSsAYZ3Gj3loqS8DwkaIHTXuD9x0LgeQprmgrOpB7X3hob
RGUWSIf0TqaY5b0LHeXDyw4AV2SJu6frdBtrZb/u8dDtTHS4rpgnx7RFZDo+bfWM
2lz7AV4YcMN3PVoY40WQZW36Dsw0eCEHvLxsIqFNzDp6T7cmN4TfktanCxztUtut
KSfIwTUCgYEA+o0U+PDIhZPW8zIHwFaDOacAUpTLe54+cq+wQxhU7rl+AJyDfBwr
6u8OXPfJfhr3UHEkQoVeK9ErCVovhDJVL7iB80VeYbexII1OXf/MbniaNI/NdFlF
947mADijwYBK3s2cKQ4S8uj6ASDiUuOrBeC/itTPjbvFRCKPgD+RsLsCgYEA0JDz
120bdGeuI3g/SPjM4CvHotLWpMCChIRkPxfcVJmWtgIXS85aaOQE2We6nqRlutEZ
hgenxK2Cj9JIqoA5CWKCk4G4tPmqK5o2ryOL3rQ+TZjhQO1aZF5/siLSn1KA836U
H0PpNCbiAwP4kARCSJalE5zK71Lpy42W+FTPBPcCgYEAnc7KjNkrk2bAlkDGvRBA
asmS3HC3kU7kSlv6CuiCZjIS+NObxUoBJ2IWi9vN302gw9vfWL6jx7lg/+z7zKnf
GcV+o/jnL2kBeV1HJNF+s33msoB4iXXJKdmpaC5EhhYGEjsyxnEE4lZ3UMqjgk2/
ZF5ghlLvv3erEfUqqT5gxw0CgYEAhXH5UoDQ7C3aUX+CnmHyVAwu85MLGubBm6BJ
s8TEiKysrU+xMCOb3TjnkWK5GP/+xwU623LSeRi7TOIy9ESOOd75xP9e+wwzQSqu
imin+ZpBssx6c1xqVYXRFl0Jfj7/mswGYerFr0Shn2RPCXZwIpmgjWfowC/Avyic
y88XlgkCgYAA8Qm6nqZVNbSoeTbUmfJ4B+DO6RA/Mg+4UFRJZw1ySzhxwwiZwmUi
dMhkz3ggsdI/wUxBwMuQR3vB4vet0/KwbkFyoMUyyLSpe7YN+mvvg5s3LQGDX99c
DiGH4dpkDGRq1uMVINJGexSdn9n8HcA+QvhZkavbhd7b0UD8L5ZfIg==
-----END PRIVATE KEY-----
}

JWE payload from the previous chapter

eyJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.yFjF3DbNPfQuZtXbVaPgFk
3AcltIC_9a39E2ppY5avbqJdrYwZwPZphoD2N5mGCeipwfu3-
KoKAGadZS8DDB8WCWVfR_Wf2Hc7IJJsNXnMs5gZRzfFBiBpYyXMdQ0YREYMyac1oD0as70hvc32aOtmChfrQSdMBxQkWDSJNF7TGZ_ml74eJjB14Ef7QCrxyBMevWJu
I2GtlKE9X2dWHkE4VFvnS4GniQsJkqhpe_OYFi8Eo5UHxHY2vfH6tbKVxzGnMVJtZBtd8SVAVIlSSkcSqi
_ggeE3AI9LMoTtJaiuzVUepsxAKC82bTxg1hTcy1b15KwiSg8DXHb4bzMJFOA.piFFKMwWKztbWnnC
GRb7hA.YU_o8TsYilMm697Y4mTDt480fJ4Rvq_JBL4MwuKIjPrrkIah8BJIId_Lclf2LqTT873EDkXSFPP01l
33Yt3vwIGsymXB0qd9RehpfUI4N6F8kyPgZ0_yQnnC33DSw5JVwDsCzWFISk4CjHk4TwOV8BoxYWF0
siuCV7_OeFA9Y1ByW8YRFpkjWSXd9CpGYwhU5sBrb7iMqDxjaev04ZJQbkBdWz2JwtD9D5myD0jzzxmNWf_3h9gTq6L49E_1B4t_FSJg4B7jKhujK95_k0LWy
Heplp45Tb0Qm9ISQa65a2nxuO52WZzGUsyTHxCnoq6sY1DY0wqF4q1sf4Tpzcnu70AiWHjuI_K0oEM6Fr6UoXDpj9DN-A9-4U7OTaurDTIAQJbzQYhqLu2ZU3kTwXtlzZNX4TjNeWkHAlvzEHjjux8tPq2XATsOEqn6ruuzWykf2K3Q_B
CdRAszZXjyMUDbT1IIIjfzpYzaZ3JkrJJeeOIOiag2iwCpUyIBlxMY0_cNu7aZVSKRnIBB9jOwizFghA1ACr
V3pm1MTYIvJ3Ztvt5Pvp5lW-xY4ybMqPrtGTmD1J-m8qlg2HvKn4ZGdavw0K9rvdYA2RkIwsQhphrhBBjsKKDLiTVQEV9Rr7Uc__z50jDDXhZlnKVxNs6p7UKQqMKB8Jk
Dp9J1suINqp3Ln95Eu90UUqGWtcih7qytSSzo7j5qElJAdMpPKI1XaWPieoIJEQHPnAb-fMNXyCFuoSKwqYJKelkQGbL3Gu69ZHRtLCM2M3gmk-KWWAPn17A1JxgjPv-JT1LMqNigqDgXQTSvcgA_SlwvZw1gTFv6hdOkeQPwXVDjdxyVQW6t9c2YbwiSN8zu4F3B8KRdQgfexNrR9JrKRlJTD5VJkiFSftpaj0n00MbHN1YuejpUvsLZD8zZ6
H31aiSFTGAhHF_5sVu8_tDAM9gJI3yBjYKIPFJT1SfQdqVfA9IhjbCJaZboF07s42vq8Q0H_YwEe2iF_NcnQHW
6yOwBfPh7OMhOocXzY1yNnAbnD1H9KqFjolvg4o80Ws_U6c38vC7kIYAUvdvvwKayOyFISRa1nzOick5W1lG29FHCwtUSA.rzRGKI7CdSuw6cfjV4_TlTpWRpCZqjMmeI6--PO-Yh4

JWS token result:

eyJhbGciOiJSUzUxMiJ9..SPaZX8_Pr6ybddVZDd0qlekHTFSauwW7EHIYh9V3ZNcJx0mQ2OxSCW3xbY
rdobTIveSV2glvQrIAx0KNgPA_kFJfLQjBHT2S-6iTOpKQqQZb2vgtNX3zR8-_Ogq1WKA1VNLFixGh_YfW1BnbYDjpRQYyTdCkmvSUCcOW5bchyN2VCK4KCH0EFabNxdiOwDeYFoA
OIpbB1mUbQoWcX0GOaaQCaLGEtSmFp6jckZAdgUI2LSMX2ZpTTiSd1pOj_C22U5WN5oRlh_9oGTX
BIVQ0unYSPfCZfaJ-x2fR9X_6sWNIrt-bUpOpbNxrCKJlkzdVS-DnfNzsDNZU87Hooa5Zg

JWS token usage: Once the JWS is generated, please include it in the request by defining the “X-Token” HTTP Header as described in the format below

X-Token: JWS + <JWS token>