Merge pull request #437 from dajiaji/v2_6_0

Bump version to v2.6.0.

CHANGES.rst

@@ -4,6 +4,19 @@ Changes
 Unreleased
 ----------
 
+Version 2.6.0
+-------------
+
+Released 2023-10-09
+
+- Add enum COSEKeyTypes. `#437 <https://github.com/dajiaji/python-cwt/pull/437>`__
+- Add enum COSEKeyCrvs. `#437 <https://github.com/dajiaji/python-cwt/pull/437>`__
+- Add enum COSEKeyOps. `#437 <https://github.com/dajiaji/python-cwt/pull/437>`__
+- Follow draft-cose-hpke-06. `#437 <https://github.com/dajiaji/python-cwt/pull/437>`__
+- Fix typo of private attribute. `#435 <https://github.com/dajiaji/python-cwt/pull/435>`__
+- Update dev dependencies.
+ - Bump urllib3 to 2.0.6. `#436 <https://github.com/dajiaji/python-cwt/pull/436>`__
+
 Version 2.5.1
 -------------
 

README.md

@@ -13,7 +13,7 @@ implementation compliant with:
 - [RFC9053: CBOR Object Signing and Encryption (COSE): Initial Algorithms](https://www.rfc-editor.org/rfc/rfc9053.html)
 - [RFC9338: CBOR Object Signing and Encryption (COSE): Countersignatures](https://www.rfc-editor.org/rfc/rfc9338.html) - experimental
 - [RFC8392: CWT (CBOR Web Token)](https://tools.ietf.org/html/rfc8392)
-- [draft-05: Use of HPKE with COSE](https://www.ietf.org/archive/id/draft-ietf-cose-hpke-05.html) - experimental
+- [draft-06: Use of HPKE with COSE](https://www.ietf.org/archive/id/draft-ietf-cose-hpke-06.html) - experimental
 - [draft-06: CWT Claims in COSE Headers](https://www.ietf.org/archive/id/draft-ietf-cose-cwt-claims-in-headers-06.html) - experimental
 - and related various specifications. See [Referenced Specifications](#referenced-specifications).
 
@@ -517,7 +517,7 @@ assert countersignature.unprotected[4] == b"01" # kid: b"01"
 Create a COSE-HPKE MAC message, verify and decode it as follows:
 
 ```py
-from cwt import COSE, COSEHeaders, COSEKey, Recipient
+from cwt import COSE, COSEAlgs, COSEHeaders, COSEKey, Recipient
 
 # The sender side:
 mac_key = COSEKey.generate_symmetric_key(alg="HS256")
@@ -532,23 +532,18 @@ rpk = COSEKey.from_jwk(
 )
 r = Recipient.new(
  protected={
- COSEHeaders.ALG: -1, # alg: "HPKE"
+ COSEHeaders.ALG: COSEAlgs.HPKE_BASE_P256_SHA256_AES128GCM,
  },
  unprotected={
  COSEHeaders.KID: b"01", # kid: "01"
- COSEHeaders.HPKE_SENDER_INFO: [ # HPKE sender information
- 0x0010, # kem: DHKEM(P-256, HKDF-SHA256)
- 0x0001, # kdf: HKDF-SHA256
- 0x0001, # aead: AES-128-GCM
- ],
  },
  recipient_key=rpk,
 )
 sender = COSE.new()
 encoded = sender.encode(
  b"This is the content.",
  mac_key,
- protected={COSEHeaders.ALG: 5}, # alg: HS256
+ protected={COSEHeaders.ALG: COSEAlgs.HS256},
  recipients=[r],
 )
 
@@ -667,7 +662,7 @@ assert countersignature.unprotected[4] == b"01" # kid: b"01"
 Create a COSE-HPKE Encrypt0 message and decrypt it as follows:
 
 ```py
-from cwt import COSE, COSEHeaders, COSEKey
+from cwt import COSE, COSEAlgs, COSEHeaders, COSEKey
 
 # The sender side:
 rpk = COSEKey.from_jwk(
@@ -685,15 +680,10 @@ encoded = sender.encode(
  b"This is the content.",
  rpk,
  protected={
- COSEHeaders.ALG: -1, # alg: "HPKE"
+ COSEHeaders.ALG: COSEAlgs.HPKE_BASE_P256_SHA256_AES128GCM,
  },
  unprotected={
  COSEHeaders.KID: b"01", # kid: "01"
- COSEHeaders.HPKE_SENDER_INFO: [ # HPKE sender information
- 0x0010, # kem: DHKEM(P-256, HKDF-SHA256)
- 0x0001, # kdf: HKDF-SHA256
- 0x0001, # aead: AES-128-GCM
- ],
  },
 )
 
@@ -981,7 +971,7 @@ assert countersignature.unprotected[4] == b"01" # kid: b"01"
 Create a COSE-HPKE Encrypt message and decrypt it as follows:
 
 ```py
-from cwt import COSE, COSEHeaders, COSEKey, Recipient
+from cwt import COSE, COSEAlgs, COSEHeaders, COSEKey, Recipient
 
 # The sender side:
 enc_key = COSEKey.generate_symmetric_key(alg="A128GCM")
@@ -996,15 +986,10 @@ rpk = COSEKey.from_jwk(
 )
 r = Recipient.new(
  protected={
- COSEHeaders.ALG: -1, # alg: "HPKE"
+ COSEHeaders.ALG: COSEAlgs.HPKE_BASE_P256_SHA256_AES128GCM,
  },
  unprotected={
  COSEHeaders.KID: b"01", # kid: "01"
- COSEHeaders.HPKE_SENDER_INFO: [ # HPKE sender information
- 0x0010, # kem: DHKEM(P-256, HKDF-SHA256)
- 0x0001, # kdf: HKDF-SHA256
- 0x0001, # aead: AES-128-GCM
- ],
  },
  recipient_key=rpk,
 )
@@ -1760,7 +1745,7 @@ Python CWT is (partially) compliant with following specifications:
 - [RFC8392: CWT (CBOR Web Token)](https://tools.ietf.org/html/rfc8392)
 - [RFC8230: Using RSA Algorithms with COSE Messages](https://tools.ietf.org/html/rfc8230)
 - [RFC8152: CBOR Object Signing and Encryption (COSE)](https://tools.ietf.org/html/rfc8152)
-- [draft-05: Use of HPKE with COSE](https://www.ietf.org/archive/id/draft-ietf-cose-hpke-05.html) - experimental
+- [draft-05: Use of HPKE with COSE](https://www.ietf.org/archive/id/draft-ietf-cose-hpke-06.html) - experimental
 - [draft-06: CWT Claims in COSE Headers](https://www.ietf.org/archive/id/draft-ietf-cose-cwt-claims-in-headers-06.html) - experimental
 - [Electronic Health Certificate Specification](https://github.com/ehn-dcc-development/hcert-spec/blob/main/hcert_spec.md)
 - [Technical Specifications for Digital Green Certificates Volume 1](https://ec.europa.eu/health/sites/default/files/ehealth/docs/digital-green-certificates_v1_en.pdf)

SECURITY.md

@@ -4,8 +4,8 @@
 
 | Version | Supported |
 | ------- | ------------------ |
-| 2.5.x | :white_check_mark: |
-| < 2.5  | :x: |
+| 2.6.x | :white_check_mark: |
+| < 2.6 | :x: |
 
 ## Reporting a Vulnerability
 

cwt/__init__.py

@@ -12,13 +12,22 @@
  set_private_claim_names,
 )
 from .encrypted_cose_key import EncryptedCOSEKey
-from .enums import COSEAlgs, COSEHeaders, COSEKeyParams, COSETypes, CWTClaims
+from .enums import (
+ COSEAlgs,
+ COSEHeaders,
+ COSEKeyCrvs,
+ COSEKeyOps,
+ COSEKeyParams,
+ COSEKeyTypes,
+ COSETypes,
+ CWTClaims,
+)
 from .exceptions import CWTError, DecodeError, EncodeError, VerifyError
 from .helpers.hcert import load_pem_hcert_dsc
 from .recipient import Recipient
 from .signer import Signer
 
-__version__ = "2.5.1"
+__version__ = "2.6.0"
 __title__ = "cwt"
 __description__ = "A Python implementation of CWT/COSE"
 __url__ = "https://python-cwt.readthedocs.io"
@@ -38,7 +47,10 @@
  "COSE",
  "COSEAlgs",
  "COSEHeaders",
+ "COSEKeyCrvs",
+ "COSEKeyOps",
  "COSEKeyParams",
+ "COSEKeyTypes",
  "COSETypes",
  "COSEKey",
  "COSEMessage",

cwt/algs/okp.py

@@ -68,17 +68,21 @@ def __init__(self, params: Dict[int, Any]):
  if self._crv not in [4, 5, 6, 7]:
  raise ValueError(f"Unsupported or unknown crv(-1) for OKP: {self._crv}.")
  if self._crv in [4, 5]:
- if not self._alg:
- raise ValueError("X25519/X448 needs alg explicitly.")
+ # if not self._alg:
+ #  raise ValueError("X25519/X448 needs alg explicitly.")
  if self._alg in [-25, -27]:
  self._hash_alg = hashes.SHA256
  elif self._alg in [-26, -28]:
  self._hash_alg = hashes.SHA512
- elif self._alg == -1:
+ elif self._alg in COSE_ALGORITHMS_HPKE.values():
  self._hash_alg = hashes.SHA256 if self._crv == 4 else hashes.SHA512
- else:
+ elif self._alg is not None:
  raise ValueError(f"Unsupported or unknown alg used with X25519/X448: {self._alg}.")
 
+ # Check the existence of the key.
+ if -2 not in params and -4 not in params:
+ raise ValueError("The body of the key not found.")
+
  # Validate alg and key_ops.
  if self._key_ops:
  if set(self._key_ops) & set([3, 4, 5, 6, 9, 10]):
@@ -126,11 +130,13 @@ def __init__(self, params: Dict[int, Any]):
  self._alg = -8 # EdDSA
  else:
  # public key.
- if 2 in self._key_ops:
- if len(self._key_ops) > 1:
+ if self._crv in [4, 5]: # X25519/X448
+ if not set(self._key_ops) & set([7, 8]):
  raise ValueError("Invalid key_ops for public key.")
- else:
- raise ValueError("Invalid key_ops for public key.")
+ else: # Ed25519/Ed448
+ if len(self._key_ops) != 1 or self._key_ops[0] != 2:
+ raise ValueError("Invalid key_ops for public key.")
+ self._alg = -8 # EdDSA
 
  if self._alg in COSE_ALGORITHMS_CKDM_KEY_AGREEMENT_ES.values():
  if -2 not in params:

cwt/const.py

@@ -173,7 +173,16 @@
 }
 
 COSE_ALGORITHMS_HPKE = {
- "HPKE": -1, # HPKE
+ "HPKE-Base-P256-SHA256-AES128GCM": 35,
+ "HPKE-Base-P256-SHA256-ChaCha20Poly1305": 36,
+ "HPKE-Base-P384-SHA384-AES256GCM": 37,
+ "HPKE-Base-P384-SHA384-ChaCha20Poly1305": 38,
+ "HPKE-Base-P521-SHA512-AES256GCM": 39,
+ "HPKE-Base-P521-SHA512-ChaCha20Poly1305": 40,
+ "HPKE-Base-X448-SHA512-AES256GCM": 43,
+ "HPKE-Base-X448-SHA512-ChaCha20Poly1305": 44,
+ "HPKE-Base-X25519-SHA256-AES128GCM": 41,
+ "HPKE-Base-X25519-SHA256-ChaCha20Poly1305": 42,
 }
 
 COSE_ALGORITHMS_CKDM_KEY_AGREEMENT_WITH_KEY_WRAP_SS = {

cwt/cose.py

@@ -395,7 +395,7 @@ def decode_with_headers(
  if k.kid != kid:
  continue
  try:
- if not isinstance(p, bytes) and alg == -1: # HPKE
+ if not isinstance(p, bytes) and alg in COSE_ALGORITHMS_HPKE.values(): # HPKE
  hpke = HPKE(p, u, data.value[2])
  res = hpke.decode(k, aad)
  if not isinstance(res, bytes):
@@ -685,7 +685,7 @@ def _encode_and_encrypt(
  if len(recipients) == 0:
  enc_structure = ["Encrypt0", b_protected, external_aad]
  aad = self._dumps(enc_structure)
- if 1 in p and p[1] == -1: # HPKE
+ if 1 in p and p[1] in COSE_ALGORITHMS_HPKE.values(): # HPKE
  hpke = HPKE(p, u, recipient_key=key)
  encoded, _ = hpke.encode(payload, aad)
  res = CBORTag(16, encoded)

cwt/enums.py

@@ -14,7 +14,6 @@ class COSETypes(enum.IntEnum):
 
 
 class COSEHeaders(enum.IntEnum):
- HPKE_SENDER_INFO = -4
  ALG = 1
  CRIT = 2
  CTY = 3
@@ -88,7 +87,6 @@ class COSEAlgs(enum.IntEnum):
  A256KW = -5
  A192KW = -4
  A128KW = -3
- HPKE_V1_BASE = -1
  A128GCM = 1
  A192GCM = 2
  A256GCM = 3
@@ -105,6 +103,16 @@ class COSEAlgs(enum.IntEnum):
  AES_CCM_16_128_256 = 31
  AES_CCM_64_128_128 = 32
  AES_CCM_64_128_256 = 33
+ HPKE_BASE_P256_SHA256_AES128GCM = 35
+ HPKE_BASE_P256_SHA256_CHACHA20POLY1305 = 36
+ HPKE_BASE_P384_SHA384_AES256GCM = 37
+ HPKE_BASE_P384_SHA384_CHACHA20POLY1305 = 38
+ HPKE_BASE_P521_SHA512_AES256GCM = 39
+ HPKE_BASE_P521_SHA512_CHACHA20POLY1305 = 40
+ HPKE_BASE_X25519_SHA256_AES128GCM = 41
+ HPKE_BASE_X25519_SHA256_CHACHA20POLY1305 = 42
+ HPKE_BASE_X448_SHA512_AES256GCM = 43
+ HPKE_BASE_X448_SHA512_CHACHA20POLY1305 = 44
 
 
 class CWTClaims(enum.IntEnum):
@@ -129,3 +137,36 @@ class CWTClaims(enum.IntEnum):
  LOCATION = 17
  EAT_PROFILE = 18
  SUBMODS = 20
+
+
+class COSEKeyTypes(enum.IntEnum):
+ OKP = 1
+ EC2 = 2
+ RSA = 3
+ ASYMMETRIC = 4
+ # HSS_LMS = 5
+ # WALNUT_DSA = 6
+
+
+class COSEKeyCrvs(enum.IntEnum):
+ P256 = 1
+ P384 = 2
+ P521 = 3
+ X25519 = 4
+ X448 = 5
+ ED25519 = 6
+ ED448 = 7
+ SECP256K1 = 8
+
+
+class COSEKeyOps(enum.IntEnum):
+ SIGN = 1
+ VERIFY = 2
+ ENCRYPT = 3
+ DECRYPT = 4
+ WRAP_KEY = 5
+ UNWRAP_KEY = 6
+ DERIVE_KEY = 7
+ DERIVE_BITS = 8
+ MAC_CREATE = 9
+ MAC_VERIFY = 10

cwt/recipient_algs/hpke.py

@@ -4,10 +4,35 @@
 
 from ..cose_key import COSEKey
 from ..cose_key_interface import COSEKeyInterface
+from ..enums import COSEAlgs
 from ..exceptions import DecodeError, EncodeError
 from ..recipient_interface import RecipientInterface
 
 
+def to_hpke_ciphersuites(alg: int) -> Tuple[int, int, int]:
+ if alg == COSEAlgs.HPKE_BASE_P256_SHA256_AES128GCM:
+ return 16, 1, 1
+ if alg == COSEAlgs.HPKE_BASE_P256_SHA256_CHACHA20POLY1305:
+ return 16, 1, 3
+ if alg == COSEAlgs.HPKE_BASE_P384_SHA384_AES256GCM:
+ return 17, 2, 2
+ if alg == COSEAlgs.HPKE_BASE_P384_SHA384_CHACHA20POLY1305:
+ return 17, 2, 3
+ if alg == COSEAlgs.HPKE_BASE_P521_SHA512_AES256GCM:
+ return 18, 3, 2
+ if alg == COSEAlgs.HPKE_BASE_P521_SHA512_CHACHA20POLY1305:
+ return 18, 3, 3
+ if alg == COSEAlgs.HPKE_BASE_X25519_SHA256_AES128GCM:
+ return 32, 1, 1
+ if alg == COSEAlgs.HPKE_BASE_X25519_SHA256_CHACHA20POLY1305:
+ return 32, 1, 3
+ if alg == COSEAlgs.HPKE_BASE_X448_SHA512_AES256GCM:
+ return 33, 3, 2
+ if alg == COSEAlgs.HPKE_BASE_X448_SHA512_CHACHA20POLY1305:
+ return 33, 3, 3
+ raise ValueError("alg should be one of the HPKE algorithms.")
+
+
 class HPKE(RecipientInterface):
  def __init__(
  self,
@@ -19,14 +44,8 @@ def __init__(
  ):
  super().__init__(protected, unprotected, ciphertext, recipients)
  self._recipient_key = recipient_key
-
- if self._alg != -1:
- raise ValueError("alg should be HPKE(-1).")
- if -4 not in unprotected:
- raise ValueError("HPKE sender information(-4) not found.")
- if not isinstance(unprotected[-4], list) or len(unprotected[-4]) not in [3, 4]:
- raise ValueError("HPKE sender information(-4) should be a list of length 3 or 4.")
- self._suite = CipherSuite.new(KEMId(unprotected[-4][0]), KDFId(unprotected[-4][1]), AEADId(unprotected[-4][2]))
+ kem, kdf, aead = to_hpke_ciphersuites(self._alg)
+ self._suite = CipherSuite.new(KEMId(kem), KDFId(kdf), AEADId(aead))
  return
 
  def encode(self, plaintext: bytes = b"", aad: bytes = b"") -> Tuple[List[Any], Optional[COSEKeyInterface]]:
@@ -35,10 +54,7 @@ def encode(self, plaintext: bytes = b"", aad: bytes = b"") -> Tuple[List[Any], O
  self._kem_key = self._to_kem_key(self._recipient_key)
  try:
  enc, ctx = self._suite.create_sender_context(self._kem_key)
- if len(self._unprotected[-4]) == 3:
- self._unprotected[-4].append(enc)
- else:
- self._unprotected[-4][3] = enc
+ self._unprotected[-4] = enc
  self._ciphertext = ctx.seal(plaintext, aad=aad)
  except Exception as err:
  raise EncodeError("Failed to seal.") from err
@@ -52,7 +68,7 @@ def decode(
  as_cose_key: bool = False,
  ) -> Union[bytes, COSEKeyInterface]:
  try:
- ctx = self._suite.create_recipient_context(self._unprotected[-4][3], self._to_kem_key(key))
+ ctx = self._suite.create_recipient_context(self._unprotected[-4], self._to_kem_key(key))
  raw = ctx.open(self._ciphertext, aad=aad)
  if not as_cose_key:
  return raw