1. OpenID Foundation Avatar OpenID Foundation
  2. WGs
  3. fapi
  4. Issues

Open Banking Europe JWS PROFILE for OpenBanking

Issue #297 resolved
Francis Pouatcha created an issue

This JWS profile consolidate the work done at ETSI (JADes) and the Internet Draft draft-cavage-http-signatures-10 and Signing HTTP Messages.

This issue will be used to collect details associated with referencing that work in the FAPI profiles for the purpose of addressing non repudiation.

Comments (17)

  1. Anders Rundgren

    Thanx Francis!

    For completeness I wanted to show the system used in Saturn based on the coming RFC 8587 JSON canonicalizaton scheme. Most notable differences include:

    • Headers are with URL as sole exception not used to carry signed information
    • Since the data is canonicalized before being signed, the entire JSON object can be embedded in other JSON objects, serialized in databases, or counter-signed without making the signature invalid
    • Due to canonicaliztion, all data can be provided in clear

    As a side-note I don’t see much of a disadvantage having the certificate included. This makes the signature possible to validate without having access to the registry.

    Saturn is not the only system using this: https://cyclonedx.org/use-cases/#authenticity.

    For “body-less” requests you obviously need another solution.

    Applied to the OBE sample:

    {
    "recipientUrl": "https://api.testbank.com/v1/payments/sepa-credit-transfers",
    "timeStamp": "2020-04-16T07:35:56Z",
    "requestId": "99391c7e-ad88-49ec-a2ad-99ddcb1f7721",
    "psuData": {
        "ipAddress": "192.168.8.78",
        "geoLocation": "GEO:52.506931,13.144558",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64; rv:54.0) Gecko/20100101 Firefox/54.0"
    },
    "instructedAmount": {
        "currency": "EUR",
        "amount": "123.50"
    },
    "debtorAccount": {
        "iban": "DE40100100103307118608"
    },
    "creditorName": "Merchant123",
    "creditorAccount": {
        "iban": "DE02100100109307118603"
    },
    "remittanceInformationUnstructured": "Ref Number Merchant",
    "signature": "eyJhbGciOiJFUzI1NiJ9..oB7hnILuIIWy0Mn-KjunBBlFTng3ZmAr-GklnIGfzoV3KNp1KXf3y34mx5A5vJ6w8F_H6IHfSJR8Wmyh2h1WPA"
}

    ‌

  7. Anders Rundgren

    @Dave Tonge Do you expect a consensus view from the FAPI WG? I would be interested in raising the B64 and serialization issues. B64 bodies are pretty much incompatible with just about everything out there while detached signatures make HTTP requests alien compared to signatures in other contexts.

    Using RFC 8785 together with JWS you can obtain universality. If you to that recommend that data to be signed should be in the request body rather than in HTTP headers things become really neat as you can see in https://bitbucket.org/openid/fapi/issues/297/open-banking-europe-jws-profile-for#comment-57807655.

    The ETSI/OBE work started (like JOSE) with the assumption that canonicalization either is impossible or plain stupid. There are (of course…) are a few things application developers must take in consideration but they are by no means difficult. Anybody can try out this scheme on-line: https://mobilepki.org/jws-jcs

    I got some great help from other persons who took care of JSON Number serialization including code in multiple languages.

  8. Anders Rundgren

    @Dave Tonge Is universality of a signature scheme important? Well, the JOSE/OBE/ETSI solution for digitally signed receipts would be:

    eyJhbGciOiJFUzI1NiJ9.eyJvdGhlclByb3BlcnRpZXMiOlsyMDAwLHRydWVdLCJzdGF0ZW1lbnQiOiJIZWxsbyBzaWduZWQgd29ybGQhIn0.6QTR5Vp4RxH3B8x0Corgdgsykuq3SNAPEb2zThi96H7kAVLumWKwir3N26DSZWlNae-hJoBB9cCr6IulzmBIlQ

    This solution may have to compete with systems using more developer-friendly signatures:

    {
    "@context": "https://webpki.github.io/saturn/v3",
    "@qualifier": "Receipt",
    "status": "AVAILABLE",
    "referenceId": "2020100900000003",
    "timeStamp": "2020-10-09T04:34:17+00:00",
    "commonName": "Planet Gas",
    "physicalAddress": ["171 Rue de Châteaugiron", "35000 Rennes", "France"],
    "phoneNumber": "02 99 50 63 93",
    "emailAddress": "support@planetgas.com",
    "amount": "33.25",
    "currency": "EUR",
    "barcode": {
        "type": "CODE_128",
        "value": "2020100900000003"
    },
    "lineItems": [{
        "description": ["Standard 95E/Pump 8"],
        "quantity": "24.6",
        "unit": "Litre",
        "price": "1.35"
    }],
    "paymentMethodName": "Bank Direct",
    "accountReference": "FR*0128",
    "payeeAuthorityUrl": "https://192.168.1.79:8442/webpay-payeebank/payees/973277",
    "providerData": {
        "commonName": "My Bank",
        "providerAuthorityUrl": "https://192.168.1.79:8442/webpay-payerbank/authority",
        "referenceId": "#0100345336",
        "payeeRequestId": "2020100900000003.1",
        "timeStamp": "2020-10-09T04:34:45+00:00"
    },
    "receiptSignature": {
        "algorithm": "ES256",
        "publicKey": {
            "kty": "EC",
            "crv": "P-256",
            "x": "yxkJV3w2WH5g_4IBSrdZ1EFmLojQIiYhhiwOd3YjooU",
            "y": "-8mDbeY6oEFpwktEPOQPlMo5BNW1AJoeTmQ4gmsADy4"
        },
        "value": "Cq-_aDsoJ34068yaau2eTD7-zychBJcs5dHVPjYagL17_XOA7MVEAzTUGwe4lpJ8oHK1yPaBBV-psRmyOQ-cXQ"
    }
}

    ‌

  9. Francis Pouatcha reporter

    I will drop my comment here again for completeness:
    Section 3 and 4 are written as a summary of extracts of RFC7515 and RFC7797. This can be confusing when text is not transfered untempered. Both section summarize into following requirements:

    • compact serialization
    • unencoded payload
    • detached payload

    ‌

    Section 5.3.2 deals with key management, representation and validation. This is too tight to PSD2/eiDAS legislation. OBE is correct as the document is written for the PSD2 legislation area, but it makes the document unusable for other markets.

    ‌

    RECOMMENDATION-24 is confusing

    As for the canonicalization of the content to be signed (headers, body), I understand why OBE relies on draft-cavage-http-signatures-10 and RFC3230 as they will otherwise have to reinvent the wheel.

    ‌

    My suggestion:

    • Suggest the draft of a legislation independent specification on how to sign FAPI messages. This spec shall abstracted from Key and Certificate specifics so as to allow each legislation to derive a profile fitting into its trust framework (e.g. OBE/ETSI JAdES for PSD2). 

    • This specification could be hosted by FAPI, based on the current OBE draft and driven by OBE and current FAPI members.

    ‌

  10. Francis Pouatcha reporter

    Abstract

    This document is an abstraction of the OBE document as can be factorized from the PSD2 legislation framework to allow for reuse by other legislations:

    Signature Mechanism

    The signature mechanism will be in charge of defining production rules for data to be signed. It is represented by the JOSE header field “sigD“.”mID”. This document provides a default signature mechanism.

    Trust Framework

    The trust framework is in charge of specifying how to represent, retrieve and legitimate public key material (resp. certificate) used to verify a signature. The trust framework can be represented by the header field “sigF“.(Note: This is not part of OBE. Might nevertheless be essential for cross legislation interoperability).

    Signature Production

    This document mandates the use of:

    • JWS Compact Serialization as defined in RFC 7515
    • JWS Unencoded Payload as defined in RFC 7797 (set b64 header to false)
    • JWS Detached Payload as defined in RFC 7515 Appendix F
    • JWS Detached Signature to be transported in HTTP Header field: x-jws-signature

    Signature Header

    Following JOSE header are mandated. by this profile.

    • “typ”: if present must be "JOSE"
    • “alg”: must be present and shall not carry the value "none" (as defined in section 3.6 of RFC 7518)
    • JOSE-Header for signature key: see bellow.
    • “sigF“: indicating the signature trust framework for resolution and validation of key material.

    • “crit” must be present and shall contain only

      • “b64”: with value set to false
      • “sigT”: indicating the claimed signing time encoded using RFC 3339 Internet time format for UTC without fractional seconds (e.g. "2019-11-19T17:28:15Z")
      • “sigD”: indicating signature data as defined in Signature Data.

    Signature Data

    Signature data are represented by the JOSE header field sigD that contains two fields:

    • “mID”: A URI which identifies the mechanism used to identify the Data to be Signed.

    • “pars”: Parameters of this mechanism or the list of http headers used to create the data to be signed. Indicated mechanism must also specify:

      • The canonicalization rules and digest method used to produce the cryptographic digest value of the http body of the request to be included in the signature data,

        • including the name of the http header field used to carry that digest,
        • including the representation of empty body content.

      • The canonicalization rules and string construction procedures for the production of http headers to include in the signature.

    Signature Key Representation

    The trust framework will specify how to represent, retrieve and legitimate public key material by indicating which of the JOSE header fields defined bellow is to be included in the signature header and how to use corresponding value to produce and validate the public key material.

    Signature key or certificate might be represented either by reference or by value:

    • If represented by value, trust framework will have to define how to legitimate the key,
    • If represented by reference, trust framework will define how to retrieve and legitimate the key.

    Key represented by reference:

    • Use JOSE header field "kid" to indicate the public key used to verify the request or
    • Use JOSE header field "jku" to indicate the url where to retrieve the public key used to verify the request.

    Key represented by value:

    • Use JOSE header field "jwk" to represent the key material used to sign the request.

    Certificate represented by reference:

    • Use JOSE header field "x5u" to indicate the url where to retrieve the X.509 signing certificate or certificate chain corresponding to the public key used to verify the request.
    • Use JOSE header field "x5t#S256" to indicate the SHA 256 digest of the X.509 signing certificate. Digest will be used to retrieve the X.509 signing certificate or certificate chain corresponding to the public key used to verify the request.

    Certificate represented by value:

    • Use JOSE header field "x5c" to indicate the X.509 public key certificate or certificate chain corresponding to the public key used to verify the request.

    Sample Signature Mechanism (from OBE PSD2)

    • JOSE header field “mID” must carry the value: “http://uri.etsi.org/19182/HttpHeaders“
    • Apply RFC 3230 to compute the digest of the HTTP body
    • Use the http header parameter "Digest" to represent the computed body digest
    • User draft-cavage-http-signatures-10 to construct string value of header parameters included in the signature (JOSE header field “pars“)
    • … many more as defined in the OBE document.

    Sample Signature Trust Framework (from ETSI TS 19182)

    ‌

    This suggestion could be part os the response to ETSI.

  11. Anders Rundgren

    @Francis Pouatcha I would drop all references to RFC 7797, RFC 7515 Appendix F matches the actual use.

    For the record it is worth mentioning that the ETSI approach will require an entirely different solution for in-line signatures like the weird ZIP arrangement discussed in another context.

  15. Anders Rundgren

    @Francis Pouatcha I probably used the wrong terminology. Anyway, this profile only applies to HTTP based signatures, anything else will require Base64Url-encoded data which I called in-line but probably better would be called self-contained like the digital customer receipt shown above.

    Regarding RFC 7797, I don’t think it was actually intended for detached mode. As the OBIE reported few libraries honor this extension for the obvious reason that nobody in their right mind would encode detached JWS data.

    @Dave Tonge I have nothing to add. RFC 8785 works great (if you stick to the specification….), and permits hashing of JSON enabling cool things like shown above. The ETSI/OBE folks haven’t reviewed this option.

  16. Francis Pouatcha reporter

    @Anders Rundgren Yes. OBE document applies only for HTTP Signature for banking API. This is the way open banking API are designed for the moment as in many markets there is a lot of influence of ISO20022 and ISO20015. Those are not JSON based.

    For a pure JSON based API, I would also go for RFC 8785 instead of RFC 3230.

  18. Log in to comment
Assignee
–
Type
bug
Priority
major
Status
resolved
Component
HTTP Signing
Milestone
–
Votes
0
Watchers
1
Jira: the preferred issue tracker for Bitbucket. Join the team!