Mapping between claims and response data elements

[adrianhopebailie]

The specification should define a mapping, or a way to define mappings in payment method specs, that map data elements from the payment response to claims in the JWT

[ianbjacobs]

I think this is a duplicate of https://github.com/w3c/webpayments-crypto/issues/10. Please confirm.

Ian

[adrianhopebailie]

Not really. I think #10 is somewhat redundant because the algorithms are already defined in the various JWT, JWE specs.

This concerns mapping response data to claims because JWT's contain claims, not just a raw JSON object.

The example suggests that each data element in the response will be stored as a claim. Another approach would be a single claim that contains the whole response as a single JSON encoded object.

Different payment method specs could define their own approach to this OR we could register a standard claim identifier(s) (there is a registry for these) which maybe favours the latter approach.

[adrianhopebailie]

PROPOSAL

As suggested above I believe we should move away from using individual claims for each data element as this places additional requirements on payment method specs to define mappings between data elements and claims.

Rather, I propose that we define a single claim that can be used by all payment methods to hold their response data as a JSON string. This can be called payment_response and registered in IANA's JWT claims registry.

Payment methods that wish to map specific data to claims (perhaps because they are using an existing, claims based system or well-known claims) can still do so but for payment methods that don't have this requirement they can simply define the schema of the response object.

Here is an example of definitions that might appear in an 'encrypted-card' spec.

The request is similar to 'basic-card' but includes an element for the website to specify the key to use for encryption (Note, the specifics of key exchange are still TBD).

dictionary EncryptedCardRequest {
  sequence<DOMString> supportedNetworks;
  sequence<BasicCardType> supportedTypes;
  required DOMString keyProviderURL;
};

The response provides display data and an element that holds the JWE

dictionary EncryptedCardResponse {
  DOMString displayMaskedCard;
  DOMString displayLast4;
  required DOMString displayExpiryMonth;
  required DOMString displayExpiryYear;
  required DOMString displayNetwork;
  required DOMString encryptedCard;
};

When the JWE is decrypted there will be a custom claim called payment_response which will be a JSON object that follows the following schema:

dictionary EncryptedCard {
  required DOMString       cardNumber;
  DOMString       cardholderName;
  DOMString       cardSecurityCode;
  DOMString       expiryMonth;
  DOMString       expiryYear;
  PaymentAddress? billingAddress;
};

[ianbjacobs]

@adrianhopebailie, in general I support the idea, which I understand to be: provide a convenience for naming a single blob but also allow payment methods to map data to specific claims.

If I understand, the payment_response is encrypted. But that name suggests it is the entire response, rather than just the encrypted portion. Could we change it to encrypted_payment_response?

In terms of spec edits, it seems that:

• the encryption spec would need to speak about this in the section "5. How to Use this Specification within a Payment Method Specification". It may also be that section 3.3 (Plaintext encryption) goes away in favor of section 5.
• the current Tokenized Card Payment specification would then say that the encryptedDetails value is encrypted data (per the encryption spec) where the encrypted_payment_response claim data has the form EncryptedTokenizedCard.

Is that how you imagine this being organized?

[adrianhopebailie]

I don't think it needs to be called encrypted_payment_response because all claims are encrypted. That would mean we need a new claim if we want to just sign the data?

Also, there is a trend toward small claim names so maybe pr or epr if you insist 😄

[stpeter]

Mappings are good. :-)

The usual practice for JWT claims is to define atomic entities (e.g., phone_number, given_name). This enables re-use (in fact, we might want to re-use some of the OAuth fields). Might other specs want to reuse cardNumber and cardSecurityCode and such?

[ianbjacobs]

Today I updated the spec to prepare for AHB's proposal: https://rawgit.com/w3c/webpayments-crypto/gh-pages/#howtouse

Once we have some agreement that this is the way to go (with the preferred name like "epr") then: a) We can add that specific name to the proposal, and b) We need to decide whether Tokenized Card Payment should use that feature and update accordingly. (And I think it should. :)

Ian