erdtman / cleartext-jose Goto Github PK

As we'd discussed, the presence of __cleartext_header_parameters is based me not realizing that there was an error in one of the signing examples in the spec that I reviewed. (The error was that the header parameters and the signature were both at the top level - rather than the header parameters being in the Cleartext Signature structure.)

This obviously needs to be corrected before we can publish.

It's not clear whether the signature object and its signature
are being put into the unnormalized or normalized JSON.
Either should be a legal implementation, right? We should say so.

In the JWE variant alg may be specified at the top level as well as inside an recipients object.

I would prefer that alg either only exists at the top level or in the recipients objects rather than giving local definitions precedence. Crypto should be strict :-)

My current implementation follows this idea but the code is quite simple anyway.

If preference order rather is to be honored, how should a non-referred alg be treated?

We should rename draft-erdtman-cleartext-jws-00 to draft-erdtman-jose-cleartext-jws-00 and draft-erdtman-cleartext-jwe-00 to draft-erdtman-jose-cleartext-jwe-00 so that the specs appear in the list of JOSE WG drafts at https://datatracker.ietf.org/wg/jose/documents/ when they are submitted. This both requires changing the text string names in the "rfc" element in the beginning of the specs and renaming the files in Git.

My bad for not doing this right the first time!

Just to verify that we are on the same page, here is a genuine sample:

{
  "now": "2018-04-16T11:23:06Z",
  "escapeMe": "\u20ac$\u000F\u000aA'\u0042\u0022\u005c\\\"\/",
  "numbers": [1e+30,4.5,6],
  "__cleartext_signature": {
    "crit": ["myString","https://example.com/extension"],
    "signers": [{
      "alg": "ES256",
      "jwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "censDzcMEkgiePz6DXB7cDuwFemshAFR90UNVQFCg8Q",
        "y": "xq8rze6ewG0-eVcSF72J77gKiD0IHnzpwHaU7t6nVeY"
      },
      "myString": "some data",
      "https://example.com/extension": {
        "life-is-great": true
      },
      "signature": "rJUW8xr6_UgyqA_JIc519PLSM0q9kO4D-bLyBeBu-0z8wn46wEaUJCq5vvElPbgHuO7ACKQmrSm74k_FZrZBCw"
    },{
      "alg": "ES512",
      "jwk": {
        "kty": "EC",
        "crv": "P-384",
        "x": "GLfdsvEwphRzS_twup7UFPVOk7_CKgHZ7dt_fJ2QHPBdJa1c5pfJcRIWTfT0lpg9",
        "y": "ovA5_QXmFbj9U4pjZ1AX_ZdVyIRZUBWW9cuZda_tupKfWQfmcQHzDmHGHbxl9Xxl"
      },
      "myString": "other data",
      "https://example.com/extension": {
        "life-is-great": true
      },
      "signature": "T6MMaUABjJ10Q63IVbnIylmuA1QYAS1iLfkgxBPczJSLMPHz8TQ8z4xA-Lc0T7VU83XhnybMLRfEsu5QmXqtkQo3obqcGRJm0ucOb1ixlN8NRUy15w_IcW111-wX1oxY"
    }]
  }
}

Rules:

• The "crit" extension must only exist on the global/outer level
• The arguments themselves must only exist in the local/inner level

That is, the "crit act as a declarator for all the signatures.

I believe my implementation does something worth mentioning in the draft: A conforming implementation SHOULD NOT accept Signature Objects holding unknown extensions.

If we're going to create a Cleartext JWE specification that does something different than the JWE JSON Serialization, we need a very good reason for doing so. Furthermore, this reason needs to be put in the Introduction section of the Cleartext JWE specification, so that's available for public scrutiny and review.

I know that I was told once why we though we wanted to be different than the JWE JSON Serialization but I don't remember. We need to write this down.

My default position on this is that unless the answer involves using ES6 canonicalization in places where JOSE currently uses base64url encoding, we're on pretty weak grounds advocating a different encryption representation.

If you take a sharp look at the JWS variant, "signature" is technically only a label and thus does not motivate IANA registration.

However, deprecating "signature" would be going too far.

How about:
For maximum interoperability it is RECOMMENDED using "signature" to denote the presence of an enveloped signature sub object.

BTW, this further motivates the idea supporting multiple signatures in the same way as JWE deals with multiple encryption objects: #1 That is, defining a unified signature container sub object. Please pardon my obsession with unification.

It seems that I haven't read JWA down to the letter.
If I understand things right ES256 is dedicated to to ECSDSA with P-256 and SHA256 making this example of ours incorrect:
https://tools.ietf.org/id/draft-erdtman-jose-cleartext-jws-00.html#multipleglobalalg
I have created an alternative test key called P-256-2 and associated sample to cope with that.

Please change all the occurrences of   to  . (And if there are other such uses of numeric character representations where symbolic forms are available, please make them symbolic as well.)

Please change EUR in "EUR$\u000f\nA'B\"\\\\\"/" to \u20AC and change the comment EUR denotes the Euro symbol to \u20AC represents the Euro symbol.

xref needed here once we publish the initial versions

The current Cleartext JWS I-D shows an example with data-to-be-signed:

"iss":"joe",
"exp":1300819380,
"http://example.com/is_root":true

My current test vectors do not. I can update the whole bunch to use the above. OK?

For encryption I have used:

Hello encrypted world!

OK?

The current scheme was partially derived from the JSON Serialized JWS.

Single signature:

  "signature": {
     Complete signature
   }

Multiple signatures:

  "signatures": [{
     Complete signature
  }...]

Although working this scheme has limitations wrt to crit and the proposed excl extension [1] making an alternative solution worth considering:

Single signature:

  "signature": {
     Global
     Signature specific
   }

Multiple signatures:

  "signature": {
    Global
    "multiple": [{
        Signature specific
    }...]
   }

Constraints:
Optional crit and excl specifiers MUST be in the Global section only.
Properties specified by crit MUST be in the Signature specific section(s) only.
Properties specified by excl MUST be in the Application level only only.

Advantages/features:

• A more logical and stringent crit feature
• excl would always refer to the application level object (where it makes sense)
• A Global alg would force all signatures to use that
• Analogous to JWE as shown by the following sample using both a shared alg and a crit extension:

{
  "aMutiplySignedProperty": "This is it!",
  "signature": {
    "alg": "ES256",
    "crit": ["who"],
    "multiple": [{
      "who": "Jane Doe",
      "val": "ZGJjHfoBPAfk3OC3DSoJwW4Rtkwl-oS--I1h8ogq3oEx8ncJ0R_BOfX9mxlX9K-zW4e1d46CikhNWyi2wKnsKw"
    },{
      "who": "John Doe",
      "val": "LZB2awEHZbK48Zgnm-zLlyLmFMArP2vMvjN_RfUhF72iQPDT4Gee-n8S0kDTdXsZfCs5mCoBU_rFLdS-lddBbS"
    }]
  }
}

1] The excl property

Optional array holding the names of one or more properties featured on the same level as the signature property, that MUST be excluded from the signature process.

Note that the excl property itself, MUST also be excluded from the signature process.

Property names that are to be excluded from the signature process MUST NOT be duplicated or try to override signature.

A conforming implementation MUST reject signatures listing properties that are not found as well as empty excl objects. Verifiers are RECOMMENDED introducing additional constraints like only accepting predefined properties. Sample:

{
  "mySignedData": "something",
  "myUnsignedData": "something else",
  "signature": {
    "alg": "ES256",
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "2zlYOKuQmOswt_xo_XhizgABDn8w2qUlte5ALXYpTWM",
      "y": "wcezP2ejoD6hwPrWNYPTPSteTmWKxMR8V04ryixmXLA"
    },
    "excl": ["myUnsignedData"],
    "val": "mjmbl9GjkGFwCgdvnx6zM_X0cYrxFm2EEdJ6s_DB3caiRfIj5hE5F4d_2dNkyE4ZqVrKUUKnE27oN2pW0IVlSw"
  }
}

The application for excl is enabling a party somewhere in the middle acquiring data in a signed object that can be "consumed" and letting the party sent the revised data to yet another party.

This needs to talk about doing this for each signer.

The example has both the __cleartext_header_parameters and __cleartext_signature members at the top level of the JSON structure. Should the __cleartext_signature member be inside the __cleartext_header_parameters object?

The "x5c" attribute departs from all other JOSE attributes by requiring the binary data to be Base64-encoded rather than using Base64Url.

Personally, I would consider changing this to make it "neater". There is no legacy to bother with either. Dealing with this in libraries combining the original JOSE standards as well as the CT counterparts must be a very small thing.

But I wait for your "verdict" :-)

<!— TBD Include non-ASCII Unicode characters in the example, such as a UK Pound symbol and/or a Euro currency symbol -->

Document encoding needs to be changed

I have a pretty large collection of test vectors for my current incarnation of the Cleartext schemes.
I would like to stick a set of keys throughout the mission even if signatures and encryptions would change every now and then.

The current set of asymmetric keys include an RSA 2048 bit key, a P-256 key, a P-384 key, and a P-521 key. I'm thinking of (re)naming them to:

• example.com:r2048
• example.com:p256
• example.com:p384
• example.com:p521

These names are also featured in P12 containers which are used for producing the test keys which are not only JWKs but certificate paths for "x5c" and "x5u" as well.

Would that be OK?

That a JKU points to an arbitrary JWK key set in my opinion creates major interoperability issues. I can't imagine that anybody out there actually tries out different keys in order to verify signatures or decrypt data.

In my [sort of] "reference implementation" I have addressed this problem by restricting key sets to a single element: https://cyberphone.github.io/doc/openkeystore/p256.jwks

Another possibility would be that a JKU also implies the presence of an in-line JWK for avoiding the trial-and-error scheme.

I started with "value" but then I after consulted Samuel ended up with "val" following the spirit of "alg", "jwk", "kid" etc.

Seen in retrospect we have now created a rather weird set of names where the revised JVS uses "val" for denoting signature value while JWE uses "ciphertext" to denote its counterpart.

I certainly do not advocate for using "signaturevalue", I only wanted to raise the issue.

A difference with the original JOSE standards is that header data is now visible and therefore will be exposed to more interest than before.

See #5

The need for mixing signed and unsigned data in a JSON object pops up every now and then. The primary use case assumes a 3+ party arrangement where an intermediary needs a signed object for handing over to another party as well as some data that only is supposed to be consumed/known by the intermediary.

There's no absolute need for this, but the ability signing the outermost part of an object including a possible object type identifier is IMO a valid argument.

My reference implementation now supports this (proposed) addition to Cleartext JWS:

{
  "mySignedData": "something",
  "myUnsignedData": "something else",
  "__cleartext_signature": {
    "alg": "ES256",
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "censDzcMEkgiePz6DXB7cDuwFemshAFR90UNVQFCg8Q",
      "y": "xq8rze6ewG0-eVcSF72J77gKiD0IHnzpwHaU7t6nVeY"
    },
    "excl": ["myUnsignedData"],
    "signature": "H0-njIUKslhe8JKUDmOwebTatyL5ZN9S2wd_gJ9wR0cUz2apvnTpyUFYD-A9llGRyx4XzWY_ge7oD3S0Pb7ArQ"
  }
}

Explanation: The property myUnsignedData is unsigned as declared by the "excl" (exclude) parameter. For the verifier the object is rather treated as:

{
  "mySignedData": "something",
  "__cleartext_signature": {
    "alg": "ES256",
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "censDzcMEkgiePz6DXB7cDuwFemshAFR90UNVQFCg8Q",
      "y": "xq8rze6ewG0-eVcSF72J77gKiD0IHnzpwHaU7t6nVeY"
    },
    "signature": "H0-njIUKslhe8JKUDmOwebTatyL5ZN9S2wd_gJ9wR0cUz2apvnTpyUFYD-A9llGRyx4XzWY_ge7oD3S0Pb7ArQ"
  }
}

That is, the "excl" header itself is also excluded from the normalization process.

A multi-signature sample:

{
  "mySignedData": "something",
  "myUnsignedData": "something else",
  "__cleartext_signature": {
    "excl": ["myUnsignedData"],
    "signers": [{
      "alg": "ES256",
      "jwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "censDzcMEkgiePz6DXB7cDuwFemshAFR90UNVQFCg8Q",
        "y": "xq8rze6ewG0-eVcSF72J77gKiD0IHnzpwHaU7t6nVeY"
      },
      "signature": "W91yxbjB59wEkxe2ieZILqYLMJYGp0lQTsfETaribEwPiI5FPnt46NIv03a30i_rcIZYU_xuLBxAd8u_gETZWw"
    },{
      "alg": "ES512",
      "jwk": {
        "kty": "EC",
        "crv": "P-384",
        "x": "GLfdsvEwphRzS_twup7UFPVOk7_CKgHZ7dt_fJ2QHPBdJa1c5pfJcRIWTfT0lpg9",
        "y": "ovA5_QXmFbj9U4pjZ1AX_ZdVyIRZUBWW9cuZda_tupKfWQfmcQHzDmHGHbxl9Xxl"
      },
      "signature": "xoxi4mCMKKL0NpA4QqrEOJAp9WK3o0AcRj2GZKoy3nt1hUtK5Wuid4NWKrCZ0rxgRCGjbTn7Y2MHuMk8Vx4nZ2lMK7OBQtKMMBf_zbm0WKSASfsoB_ucMvLvqfCA7tYY"
    }]
  }
}

Rules:

• "excl" MUST only be present at the global level
• A conforming implementation MUST NOT accept "excl" unless it is specifically configured for doing that

This needs to be more specific. Are you just talking about accepting input or doing ES6 serialization?

If these work items receive JOSE support it would (for marketing reasons) be a good idea reusing the names of the standards as well. JWS/X and JWE/X are possible names where 'X' denotes eXtended or whatever you want :-)

Adding a -CT suffix for Clear Text also sounds reasonable.

JWS/JWE defines a bunch of attributes that are IANA registered.
The attributes that are added in the JSON serialization variants are though not registered.
In the revised scheme all attributes would(?) be candidates for IANA registration.

Although not important a JWE property like ciphertext doesn't feel entirely right since it

• departs from current JSON naming standards like cipherText and cipher_text.
• departs from other registered JOSE attributes which are 1-4 characters

To aid JSON tool designers as well as supporting other usages of this scheme (it is already extensively used for hash-only constructs in Saturn), it might be an idea describing this part in a separate document.

When Direct Key Agreement or... (removed)
Should not be removed?

We need to choose consistent wording between "signature construct" and "signature object".

If you take the JOSE specifications literally, it seems that constructs like the following would be legal:

 "kid":" mykey",
 "jwk": {
   "kid": "mykey",
   "x5c": ["MI..........................................."]

In my [sort of] "reference implementation", a supplied JWK may only contain a public key, everything else is flagged as an error. JWE indeed says that a JWK contains a public key but doesn't say anything about possible additional properties except for "kid" which is supposed to be "matched". Non-matches => fail?

I do not propose improving the matching text, I rather want to remove things that only add "fuzz". I.e. JWK would when hosted in Cleartext JW*, be a profiled version of the JWK standard.

Add note to remove in final version

After "liberating" the Signature Object from the property dogma, I couldn't resist trying to sign arrays as well. It turned out to be easier than I had imagined. Here is an authentic printout that validates in my reference implementation:

["Hi there!",2003,{
  "alg": "ES256",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "censDzcMEkgiePz6DXB7cDuwFemshAFR90UNVQFCg8Q",
    "y": "xq8rze6ewG0-eVcSF72J77gKiD0IHnzpwHaU7t6nVeY"
  },
  "val": "gOIohCbkhQOftFjqHgqRuRG1qqROSzwTiW8C7FUAQzojtqtpVoOz7BOYYNRQ7e09EfDlejz7jHumAvlAlQ6txw"
}]

The current draft AFAICT still talks about MUST while we have discussed a default.

I don't know how to express this in a draft since defaults are usually applied when information is missing. Maybe you guys have an idea?

To me it still seems easier and better redefining Cleartext JWS as a Signature Object, behaving more less as any other derived data type. This at least what my "reference implementation" does, here featured in a payment provider system I've recently been involved in:

public class PSPRequest {

    static final String MERCHANT_ID  = "merchantId";
    static final String REFERENCE_ID = "referenceId";
    static final String CURRENCY     = "currency";
    static final String AMOUNT       = "amount";
    static final String CARD_DETAILS = "cardDetails";
    static final String TIME_STAMP   = "timeStamp";
    static final String SIGNATURE    = "signature";

    public static JSONObjectWriter encode(String merchantId,
                                          String referenceId,
                                          Currencies currency,
                                          BigDecimal amount,
                                          CardDetails cardDetails,
                                          ServerAsymKeySigner signer) throws IOException {
        return new JSONObjectWriter()
            .setString(MERCHANT_ID, merchantId)
            .setString(REFERENCE_ID, referenceId)
            .setString(CURRENCY, currency.toString())
            .setBigDecimal(AMOUNT, amount, currency.getDecimals())
            .setObject(CARD_DETAILS, cardDetails.writeObject())
            .setDateTime(TIME_STAMP, new GregorianCalendar(), true)
            .setSignature(SIGNATURE, signer);
    }

    String merchantId;
    String referenceId;
    Currencies currency;
    BigDecimal amount;
    GregorianCalendar timeStamp;
    CardDetails cardDetails;
    PublicKey publicKey;
    
    public PSPRequest(JSONObjectReader rd) throws IOException {
        merchantId = rd.getString(MERCHANT_ID);
        referenceId = rd.getString(REFERENCE_ID);
        currency = Currencies.valueOf(rd.getString(CURRENCY));
        amount = rd.getBigDecimal(AMOUNT, currency.getDecimals());
        cardDetails = new CardDetails(rd.getObject(CARD_DETAILS));
        timeStamp = rd.getDateTime(TIME_STAMP);
        publicKey = rd.getSignature(SIGNATURE, new JSONSignatureDecoder.Options()).getPublicKey();
        rd.checkForUnread();
     }
}

If any element is unknown, missing, or malformed, the PSPRequest object is rejected.

A schema based approach would presumably do the same.

It is hard describing JWE. I'm currently exploring different ways of doing that.

FWIW, I have played a bit with (sort of) EBNF, here in a very primitive way:

encryption object = 'enc', 'iv', 'tag', 'ciphertext', [ key encryption ], [ 'crit' ] ;
key encrytion     = multiple | ( single, [ encrypted_key ]) ;
public key data   = 'jku' | 'x5u' | 'jwk' | 'x5c' ;
multiple          = 'recipients', ":[", { single keywrap }, "]", optional ;
single keywrap    = single, encrypted key ;
encrypted key     = 'encrypted_key' ;
single            = key data, crit properties, optional ;
key data          = [ 'epk' ], [ public key data ] ;
optional          = [ 'alg' ], [ 'kid' ] ;
crit properties   = [ ? custom properties listed in the 'crit' array ? ] ;

Constraints for multiple:
'alg' or 'kid' properties MUST NOT be defined on both the Global level and inside of single keywrap.
crit properties MUST NOT be defined on the Global level.

Related: #1