diff --git a/payment-encryption.md b/payment-encryption.md index 32c5382..aa47a1b 100644 --- a/payment-encryption.md +++ b/payment-encryption.md @@ -1,87 +1,44 @@ -# Objective - -* Provide a standard way for encryption of sensitive information -* Provide Data Integrity for encrypted payload -* Use existing standards for algorithms and message structure - # Asymmetric Encryption +## Unofficial Draft 07 May 2018 -## **Parties involved in encryption** - -### Data Receiver (Bob) - -Bob is intending to receive sensitive information. Bob shares his public key with Alice. - -### Data Provider (Alice) - -Alice uses public key provided by Bob to encrypt sensitive data. - -### Attacker (Eve) - -Eve tries to get information about communication between Bob and Alice and misuse the information for her benefit. - -## **Public Key Definition** - -**Algorithm**: RSA -**Key Length**: 2048 bits - -The public key shared by Bob would be in [certificate format (X.509)](https://en.wikipedia.org/wiki/X.509). The file should be in [PEM format](https://tools.ietf.org/html/rfc7468) (E.g. '*.pem') - -## **Encryption of Data & Data Integrity** - -A random AES 256 bit key would be generated and used as CEK (Content Encryption Key). CEK would be used to encrypt payload with algorithm of AES-256-GCM. This would generate IV and Authentication Tag. Authentication Tag is like MAC(Message Authentication Code) and provides data integrity. After encryption of data CEK would be encrypted using RSA_OAEP_256 algorithm. - -* Data Encryption: - * Algorithm : AES-256-GCM - * Key length : 256 bits - -* Key Encryption: - * Algorithm : RSA_OAEP_256 - * Key Length : 2048 bits - +### Latest editor's draft: https://w3c.github.io/TBD +### Editors: + Ian Jacobs + +### Participate: + [https://github.com/w3c/webpayments-crypto/blob/master/payment-encryption.md GitHub w3c/webpayments-crypto] + [https://github.com/w3c/webpayments-crypto/issues File a bug] -## **Message Structure** + [https://github.com/w3c/webpayments-methods-tokenization/commits/gh-pages Commit history] -JWT already is well recognized in the industry for encryption of JSON. -In general it has message structure as + [https://github.com/w3c/webpayments-methods-tokenization/pulls/ Pull requests] -**(header).(encrypted key).(iv).(cipher text).(integrity value)** +This document is licensed under a [https://creativecommons.org/licenses/by/3.0/ Creative Commons Attribution 3.0 License]. + -### Header -Following headers would be generated as outcome of encryption. +## Abstract +This specification provides a standard way for encryption of sensitive information to provide data integrity for encrypted payload using existing standards for algorithms and message structure. -{ "enc":"A256GCM", - "alg":"RSA-OAEP-256" -} -This would be base64 encoded. +## Status of This Document +This document is draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organisation. +The working group maintains [https://github.com/w3c/webpayments-crypto/issues a list of all bug reports that the group has not yet addressed]. Pull requests with proposed specification text for outstanding issues are strongly encouraged. -### Encrypted Key +## 1. Introduction +''This section is non-normative.'' -Encrypted Key will be random generated CEK encrypted with RSA public key. +Information security has grown to be a colossal factor, especially with modern communication networks, leaving loopholes that could be leveraged to devastating effects. To tighten communication security, Asymmetric encryption is commonly used. Encryption is the process of locking up information using cryptography. Asymmetric cryptography, also known as public key cryptography, uses public and private keys to encrypt and decrypt data. The keys are simply large numbers that have been paired together but are not identical (asymmetric). One key in the pair can be shared with everyone; it is called the public key. The other key in the pair is kept secret; it is called the private key. Either of the keys can be used to encrypt a message; the opposite key from the one used to encrypt the message is used for decryption. +This document describes how asymmetric encryption can be used to achieve the security goals. -* Key Encryption: - * Algorithm : RSA_OAEP_256 - * Key Length : 2048 bits - -### Initialization Vector - -The initialization vector that is used in encryption will be shared for decryption of cipher text. - -### Cipher text - -This is payload encrypted by use of AES 256 bits key and AES-GCM algorithm. - -### Integrity value - -This would be generated as part of AES-GCM algorithm. Also known as Authentication tag. This allows Bob to know if anyone has altered the message. - -## Message Sample: - -eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.CucrNRoLT0kkBS0MxlGq9_HsPwX_ggJ8p-kB72tA_3Rt-WkH3YQt6KOYci7YuPkFjRLFPj__i1EmXXwpqTF1FUF9posbsamSGGIRQiFRfS0qopTTGEk_aWK0ngxe5T3O8Y8m7MsZnwTdlO945u13Q2brWnsHa2yY_NyRdXXNo2FmkSurvR7DGR8A00UYlCweQOius0u2YQ8Gy93OrvZAQm7qBwFG8Lf9rDadCUdZPeDIM1iUKBwaylOYS_xkISVKJhdnw59RQGl-iumKx4DX3h0PY2LREK8cI7ZoRbhpCWZkQHe2U6stIljteZ94URMVWzda5wkYL8yCqalbvtYbJA.QSfbdD74z2tn7xXr.9zNqMmvYDh9fVwjVGPzQGM9KveFxZP-HXlf8u4Vo3lasp-gjMNDZmz9enfgTemz6xQvOi05Q2fvAP2AurtORPei3st3tPZZBYUbl4d4WWuRLsEJsqzRyT7WRfqSramV8IhDUXG0TKxg1hg_008g-bOnbjjvFWqiDkoHeAnA5mid6R-JysFbkgJJohngQN53pNNrV0eQYBaCS7dkvdcKn97vUE806OYPRpzwDKw.nrAvFnyvf4PgQfPJ8RDmYA - -## Sample Code using Nimbus (Connect2id) +## 2. Examples of usage +The following parties are involved in encryption: +* Data Receiver (Bob): Bob is intending to receive sensitive information. Bob shares his public key with Alice. +* Data Provider (Alice): Alice uses public key provided by Bob to encrypt sensitive data. +* Attacker (Eve): Eve tries to get information about communication between Bob and Alice and misuse the information for her benefit. +In order for Bob to receive sensitive data from Alice using asymmetric encryption, he first needs to generate a public key and private key pair. The public key can be known to everyone. Bob shares his public key with Alice and keeps his private key secret. Alice then can use Bob’s public key to encrypt sensitive data. Bob can use the private key to decrypt the encrypted data. Attackers such as Eve can’t decrypt the encrypted data as long as Bob keeps his private key secret. +### 2.1 Key generation Example +This sample shows how how to generate a new key pair using a given security provider. ``` java // Key generation KeyPairGenerator keyGenerator = null; @@ -95,15 +52,11 @@ keyGenerator.initialize(2048); KeyPair kp = keyGenerator.genKeyPair(); RSAPublicKey publicKey = (RSAPublicKey) kp.getPublic(); RSAPrivateKey privateKey = (RSAPrivateKey) kp.getPrivate(); - - - - ``` -Encryption using AES-256-GCM and RSA_OAEP_256 - -```java +### 2.2 Encryption Example +This sample shows how to encrypt a JSON Web Token (JWT) claim set using a specified public key. +``` java JWTClaimsSet claimsSet = new JWTClaimsSet(); claimsSet.setCustomClaim("cardNumber", "5413339000001513"); claimsSet.setCustomClaim("expiryMonth", "12"); @@ -136,12 +89,10 @@ try { String jwtString = jwt.serialize(); System.out.println(jwtString); - ``` - -Decryption using RSA private key. - -```java +### 2.3 Decryption Example +This sample shows how to decrypt an encrypted JSON Web Token (JWT) claim set using a specified public key. +``` java // Parse back jwt = EncryptedJWT.parse(jwtString); @@ -149,15 +100,50 @@ jwt = EncryptedJWT.parse(jwtString); RSADecrypter decrypter = new RSADecrypter(privateKey); jwt.decrypt(decrypter); String decryptedJson = jwt.serialize(); - ``` +## 3. Assumptions +* This specification is designed to address these primary use case +** The sensitive data is in JSON format +## 4. Public Key Definition +Algorithm: RSA Key Length: 2048 bits +The public key shared by data receiver would be in [https://en.wikipedia.org/wiki/X.509 certificate format (X.509)]. The file should be in [https://tools.ietf.org/html/rfc7468 PEM format] (E.g. '*.pem') +## 5. Message Structure +JWT already is well recognized in the industry for encryption of JSON. In general it has message structure as +**(header).(encrypted key).(iv).(cipher text).(integrity value)** + +### 5.1 Header +Following headers would be generated as outcome of encryption. +{ "enc":"A256GCM", + "alg":"RSA-OAEP-256" +} +This would be base64 encoded. + +### 5.2 Encrypted Key +Encrypted Key will be random generated CEK encrypted with RSA public key. + +* Key Encryption: + * Algorithm : RSA_OAEP_256 + * Key Length : 2048 bits + +### 5.3 Initialization Vector +The initialization vector that is used in encryption will be shared for decryption of cipher text. + +### 5.4 Cipher Text +This is payload encrypted by use of AES 256 bits key and AES-GCM algorithm. + +### 5.5 Integrity Value +This would be generated as part of AES-GCM algorithm. Also known as Authentication tag. This allows Bob to know if anyone has altered the message. + +### 5.6 Message Example + +eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.CucrNRoLT0kkBS0MxlGq9_HsPwX_ggJ8p-kB72tA_3Rt-WkH3YQt6KOYci7YuPkFjRLFPj__i1EmXXwpqTF1FUF9posbsamSGGIRQiFRfS0qopTTGEk_aWK0ngxe5T3O8Y8m7MsZnwTdlO945u13Q2brWnsHa2yY_NyRdXXNo2FmkSurvR7DGR8A00UYlCweQOius0u2YQ8Gy93OrvZAQm7qBwFG8Lf9rDadCUdZPeDIM1iUKBwaylOYS_xkISVKJhdnw59RQGl-iumKx4DX3h0PY2LREK8cI7ZoRbhpCWZkQHe2U6stIljteZ94URMVWzda5wkYL8yCqalbvtYbJA.QSfbdD74z2tn7xXr.9zNqMmvYDh9fVwjVGPzQGM9KveFxZP-HXlf8u4Vo3lasp-gjMNDZmz9enfgTemz6xQvOi05Q2fvAP2AurtORPei3st3tPZZBYUbl4d4WWuRLsEJsqzRyT7WRfqSramV8IhDUXG0TKxg1hg_008g-bOnbjjvFWqiDkoHeAnA5mid6R-JysFbkgJJohngQN53pNNrV0eQYBaCS7dkvdcKn97vUE806OYPRpzwDKw.nrAvFnyvf4PgQfPJ8RDmYA -# References +## A. References * X.509 certificate format: https://en.wikipedia.org/wiki/X.509 * JWT RFC - https://tools.ietf.org/html/rfc7519