Merge pull request #290 from dajiaji/drop-support-for-recipient-from_jwk

Drop support for Recipient.from_jwk.

Author: dajiaji

README.md

@@ -26,7 +26,22 @@ $ pip install cwt
 
 And then, you can use it as follows:
 
-```py
+**COSE API**
+
+```pycon
+>>> from cwt import COSE, COSEKey
+>>> ctx = COSE.new()
+>>> mac_key = COSEKey.generate_symmetric_key(alg="HS256", kid="01")
+>>> encoded = ctx.encode_and_mac(b"Hello world!", mac_key, unprotected={"alg": "HS256"})
+>>> encoded.hex()
+'d18443a10105a1044230314c48656c6c6f20776f726c642158205d0b144add282ccaac32a02e0d5eec76928ccadf3623271eb48e9464e2ee03b2'
+>>> ctx.decode(encoded, mac_key)
+b'Hello world!'
+```
+
+**CWT API**
+
+```pycon
 >>> import cwt
 >>> from cwt import COSEKey
 >>> key = COSEKey.generate_symmetric_key(alg="HS256", kid="01")
@@ -37,7 +52,9 @@ And then, you can use it as follows:
 {1: 'coaps://as.example', 2: 'dajiaji', 7: b'123', 4: 1620088759, 5: 1620085159, 6: 1620085159}
 ```
 
-See [Documentation](https://python-cwt.readthedocs.io/en/stable/) for details.
+Various usage examples are shown in this README.
+
+See [Documentation](https://python-cwt.readthedocs.io/en/stable/) for the details of API specification.
 
 ## Index
 
@@ -89,10 +106,9 @@ pip install cwt
 
 ## COSE Usage Examples
 
-Followings are typical and basic examples which create various types of COSE messages, verify and decode them.
+Followings are typical and basic examples which encode various types of COSE messages and decode them.
 
-See [API Reference](https://python-cwt.readthedocs.io/en/stable/api.html#cwt.COSE) and
-[COSE Usage Examples on document](https://python-cwt.readthedocs.io/en/stable/cose_usage.html) for more details.
+See [API Reference](https://python-cwt.readthedocs.io/en/stable/api.html#cwt.COSE).
 
 ### COSE MAC0
 
@@ -167,6 +183,7 @@ mac_key = COSEKey.generate_symmetric_key(alg="HS512", kid="01")
 
 # The sender side:
 r = Recipient.new(unprotected={"alg": "direct", "kid": mac_key.kid})
+# r = Recipient.new(unprotected={1: -6, 4: mac_key.kid}) # is also acceptable.
 
 sender = COSE.new()
 encoded = sender.encode_and_mac(b"Hello world!", mac_key, recipients=[r])
@@ -192,12 +209,12 @@ r = Recipient.new(
         "alg": "direct+HKDF-SHA-256",
         "salt": "aabbccddeeffgghh",
     },
+    context={"alg": "HS256"},
 )
-mac_key = r.encode(shared_key.to_bytes(), context={"alg": "HS256"})
 sender = COSE.new(alg_auto_inclusion=True)
 encoded = sender.encode_and_mac(
     b"Hello world!",
-    mac_key,
+    shared_key,
     recipients=[r],
 )
 
@@ -213,19 +230,17 @@ The AES key wrap algorithm can be used to wrap a MAC key as follows:
 ```py
 from cwt import COSE, COSEKey, Recipient
 
+# The sender side:
+mac_key = COSEKey.generate_symmetric_key(alg="HS512")
 enc_key = COSEKey.from_jwk(
     {
         "kty": "oct",
         "kid": "01",
         "alg": "A128KW",
         "k": "hJtXIZ2uSN5kbQfbtTNWbg",  # A shared wrapping key
     }
-);
-
-# The sender side:
-mac_key = COSEKey.generate_symmetric_key(alg="HS512")
+)
 r = Recipient.new(unprotected={"alg": "A128KW"}, sender_key=enc_key)
-r.encode(mac_key.to_bytes())
 sender = COSE.new(alg_auto_inclusion=True)
 encoded = sender.encode_and_mac(b"Hello world!", mac_key, recipients=[r])
 
@@ -255,10 +270,16 @@ pub_key = COSEKey.from_jwk(
         "y": "HlLtdXARY_f55A3fnzQbPcm6hgr34Mp8p-nuzQCE0Zw",
     }
 )
-r = Recipient.new({"alg": "ECDH-ES+HKDF-256"}, recipient_key=pub_key)
-mac_key = r.encode(context={"alg": "HS256"})
+r = Recipient.new(
+    unprotected={"alg": "ECDH-ES+HKDF-256"},
+    recipient_key=pub_key,
+    context={"alg": "HS256"},
+)
 sender = COSE.new(alg_auto_inclusion=True)
-encoded = sender.encode_and_mac(b"Hello world!", mac_key, recipients=[r])
+encoded = sender.encode_and_mac(
+    b"Hello world!",
+    recipients=[r],
+)
 
 # The recipient side:
 # The following key is the private key of the above pub_key.
@@ -286,9 +307,8 @@ assert b"Hello world!" == recipient.decode(encoded, priv_key, context={"alg": "H
 ```py
 from cwt import COSE, COSEKey, Recipient
 
-mac_key = COSEKey.generate_symmetric_key(alg="HS256")
-
 # The sender side:
+mac_key = COSEKey.generate_symmetric_key(alg="HS256")
 pub_key = COSEKey.from_jwk(
     {
         "kty": "EC",
@@ -299,8 +319,11 @@ pub_key = COSEKey.from_jwk(
         "y": "HlLtdXARY_f55A3fnzQbPcm6hgr34Mp8p-nuzQCE0Zw",
     }
 )
-r = Recipient.new(unprotected={"alg": "ECDH-ES+A128KW"}, recipient_key=pub_key)
-r.encode(mac_key.to_bytes(), context={"alg": "HS256"})
+r = Recipient.new(
+    unprotected={"alg": "ECDH-ES+A128KW"},
+    recipient_key=pub_key,
+    context={"alg": "HS256"},
+)
 sender = COSE.new(alg_auto_inclusion=True)
 encoded = sender.encode_and_mac(
     b"Hello world!",
@@ -416,7 +439,7 @@ enc_key = COSEKey.generate_symmetric_key(alg="ChaCha20/Poly1305", kid="01")
 # The sender side:
 nonce = enc_key.generate_nonce()
 r = Recipient.new(unprotected={"alg": "direct", "kid": enc_key.kid})
-# r = Recipient.new(unprotected={1: -6, 4: enc_key.kid}) # is also acceptable
+# r = Recipient.new(unprotected={1: -6, 4: enc_key.kid}) # is also acceptable.
 
 sender = COSE.new()
 encoded = sender.encode_and_encrypt(
@@ -446,12 +469,12 @@ r = Recipient.new(
         "alg": "direct+HKDF-SHA-256",
         "salt": "aabbccddeeffgghh",
     },
+    context={"alg": "A256GCM"},
 )
-enc_key = r.encode(shared_key.to_bytes(), context={"alg": "A256GCM"})
 sender = COSE.new(alg_auto_inclusion=True)
 encoded = sender.encode_and_encrypt(
     b"Hello world!",
-    key=enc_key,
+    shared_key,
     recipients=[r],
 )
 
@@ -483,7 +506,6 @@ r = Recipient.new(
     unprotected={"alg": "A128KW"},
     sender_key=wrapping_key,
 )
-r.encode(enc_key.to_bytes())
 sender = COSE.new(alg_auto_inclusion=True)
 encoded = sender.encode_and_encrypt(b"Hello world!", key=enc_key, recipients=[r])
 
@@ -520,12 +542,14 @@ pub_key = COSEKey.from_jwk(
         "y": "HlLtdXARY_f55A3fnzQbPcm6hgr34Mp8p-nuzQCE0Zw",
     }
 )
-r = Recipient.new(unprotected={"alg": "ECDH-ES+HKDF-256"}, recipient_key=pub_key)
-enc_key = r.encode(context={"alg": "A128GCM"})
+r = Recipient.new(
+  unprotected={"alg": "ECDH-ES+HKDF-256"},
+  recipient_key=pub_key,
+  context={"alg": "A128GCM"},
+)
 sender = COSE.new(alg_auto_inclusion=True)
 encoded = sender.encode_and_encrypt(
     b"Hello world!",
-    key=enc_key,
     recipients=[r],
 )
 
@@ -572,8 +596,12 @@ s_priv_key = COSEKey.from_jwk(
         "d": "Uqr4fay_qYQykwcNCB2efj_NFaQRRQ-6fHZm763jt5w",
     }
 )
-r = Recipient.new(unprotected={"alg": "ECDH-SS+A128KW"}, sender_key=s_priv_key, recipient_key=r_pub_key)
-r.encode(enc_key.to_bytes(), context={"alg": "A128GCM"})
+r = Recipient.new(
+  unprotected={"alg": "ECDH-SS+A128KW"},
+  sender_key=s_priv_key,
+  recipient_key=r_pub_key,
+  context={"alg": "A128GCM"},
+)
 sender = COSE.new(alg_auto_inclusion=True)
 encoded = sender.encode_and_encrypt(
     b"Hello world!",
@@ -632,7 +660,6 @@ r = Recipient.new(
     },
     recipient_key=rpk,
 )
-r.encode(enc_key.to_bytes())
 sender = COSE.new()
 encoded = sender.encode_and_encrypt(
     b"This is the content.",
@@ -729,14 +756,12 @@ assert b"Hello world!" == recipient.decode(encoded, pub_key)
 
 ## CWT Usage Examples
 
-Followings are typical and basic examples which create various types of CWTs, verify and decode them.
+Followings are typical and basic examples which encode various types of CWTs, verify and decode them.
 
 [CWT API](https://python-cwt.readthedocs.io/en/stable/api.html) in the examples are built
 on top of [COSE API](https://python-cwt.readthedocs.io/en/stable/api.html#cwt.COSE).
 
-See [API Reference](https://python-cwt.readthedocs.io/en/stable/api.html) and
-[CWT Usage Examples on document](https://python-cwt.readthedocs.io/en/stable/cwt_usage.html)
-for more details.
+See [API Reference](https://python-cwt.readthedocs.io/en/stable/api.html).
 
 ### MACed CWT
 
@@ -748,7 +773,7 @@ from cwt import Claims, COSEKey
 
 try:
     key = COSEKey.generate_symmetric_key(alg="HS256", kid="01")
-    token = cwt.encode({"iss": "coaps://as.example", "sub": "dajiaji", "cti": "123"}, key)
+    token = cwt.{"iss": "coaps://as.example", "sub": "dajiaji", "cti": "123"}, key)
     decoded = cwt.decode(token, key)
 
     # If you want to treat the result like a JWT;
@@ -777,7 +802,7 @@ import cwt
 from cwt import COSEKey
 
 key = COSEKey.generate_symmetric_key(alg="HS256", kid="01")
-token = cwt.encode({1: "coaps://as.example", 2: "dajiaji", 7: b"123"}, key)
+token = cwt.{1: "coaps://as.example", 2: "dajiaji", 7: b"123"}, key)
 decoded = cwt.decode(token, key)
 ```
 
@@ -802,7 +827,7 @@ from cwt import COSEKey
 # The sender side:
 with open("./private_key.pem") as key_file:
     private_key = COSEKey.from_pem(key_file.read(), kid="01")
-token = cwt.encode(
+token = cwt.
     {"iss": "coaps://as.example", "sub": "dajiaji", "cti": "123"}, private_key
 )
 
@@ -828,7 +853,7 @@ private_key = COSEKey.from_jwk({
     "x": "2E6dX83gqD_D0eAmqnaHe1TC1xuld6iAKXfw2OVATr0",
     "d": "L8JS08VsFZoZxGa9JvzYmCWOwg7zaKcei3KZmYsj7dc",
 })
-token = cwt.encode(
+token = cwt.
     {"iss": "coaps://as.example", "sub": "dajiaji", "cti": "123"}, private_key
 )
 
@@ -855,7 +880,7 @@ import cwt
 from cwt import COSEKey
 
 enc_key = COSEKey.generate_symmetric_key(alg="ChaCha20/Poly1305", kid="01")
-token = cwt.encode({"iss": "coaps://as.example", "sub": "dajiaji", "cti": "123"}, enc_key)
+token = cwt.{"iss": "coaps://as.example", "sub": "dajiaji", "cti": "123"}, enc_key)
 decoded = cwt.decode(token, enc_key)
 ```
 
@@ -876,12 +901,12 @@ enc_key = COSEKey.generate_symmetric_key(alg="ChaCha20/Poly1305", kid="enc-01")
 # Creates a CWT with ES256 signing.
 with open("./private_key.pem") as key_file:
     private_key = COSEKey.from_pem(key_file.read(), kid="sig-01")
-token = cwt.encode(
+token = cwt.
     {"iss": "coaps://as.example", "sub": "dajiaji", "cti": "123"}, private_key
 )
 
 # Encrypts the signed CWT.
-nested = cwt.encode(token, enc_key)
+nested = cwt.token, enc_key)
 
 # Decrypts and verifies the nested CWT.
 with open("./public_key.pem") as key_file:
@@ -891,7 +916,7 @@ decoded = cwt.decode(nested, [enc_key, public_key])
 
 ### CWT with User Settings
 
-The `cwt` in `cwt.encode()` and `cwt.decode()` above is a global `CWT` class instance created
+The `cwt` in `cwt.)` and `cwt.decode()` above is a global `CWT` class instance created
 with default settings in advance. The default settings are as follows:
 - `expires_in`: `3600` seconds. This is the default lifetime in seconds of CWTs.
 - `leeway`: `60` seconds. This is the default leeway in seconds for validating `exp` and `nbf`.
@@ -903,7 +928,7 @@ from cwt import COSEKey, CWT
 
 key = COSEKey.generate_symmetric_key(alg="HS256", kid="01")
 mycwt = CWT.new(expires_in=3600*24, leeway=10)
-token = mycwt.encode({"iss": "coaps://as.example", "sub": "dajiaji", "cti": "123"}, key)
+token = mycwt.{"iss": "coaps://as.example", "sub": "dajiaji", "cti": "123"}, key)
 decoded = mycwt.decode(token, key)
 ```
 
@@ -920,7 +945,7 @@ from cwt import COSEKey
 # The sender side:
 with open("./private_key.pem") as key_file:
     private_key = COSEKey.from_pem(key_file.read(), kid="01")
-token = cwt.encode(
+token = cwt.
     {
         1: "coaps://as.example",  # iss
         2: "dajiaji",  # sub
@@ -966,7 +991,7 @@ my_claim_names = {
 }
 
 cwt.set_private_claim_names(my_claim_names)
-token = cwt.encode(
+token = cwt.
     {
         "iss": "coaps://as.example",
         "sub": "dajiaji",
@@ -1010,7 +1035,7 @@ with open("./private_key_of_issuer.pem") as key_file:
     private_key = COSEKey.from_pem(key_file.read(), kid="issuer-01")
 
 # Sets the PoP key to a CWT for the presenter.
-token = cwt.encode(
+token = cwt.
     {
         "iss": "coaps://as.example",
         "sub": "dajiaji",
@@ -1090,7 +1115,7 @@ from cwt import Claims, COSEKey
 with open("./private_key_of_cert.pem")) as f:
     private_key = COSEKey.from_pem(f.read(), kid="01")
 
-token = cwt.encode(
+token = cwt.
     {"iss": "coaps://as.example", "sub": "dajiaji", "cti": "123"}, private_key
 )