[![pkg.go.dev][GoBadge]][GoDoc]

![Coz][CozLogo]

Try Coz out!

[Presentation][Presentation]

Coz

Coz is a cryptographic JSON messaging specification that uses digital signatures and hashes to ensure secure, human-readable, and interoperable communication.

Example Coz

{
  "pay": {
    "msg": "Coz is a cryptographic JSON messaging specification.",
    "alg": "ES256",
    "now": 1623132000,
    "tmb": "U5XUZots-WmQYcQWmsO751Xk0yeVi9XUKWQ2mGz6Aqg",
    "typ": "cyphr.me/msg/create"
  },
  "sig": "OJ4_timgp-wxpLF3hllrbe55wdjhzGOLgRYsGO1BmIMYbo4VKAdgZHnYyIU907ZTJkVr8B81A2K8U4nQA6ONEg"
}

Coz Design Goals

1. Idiomatic JSON
2. Human readable
3. Limited scope
4. Providing defined cipher suites

See also the Coz philosophy

Coz Fields

Coz defines standard fields for the objects pay, key, and coz. Applications may include additional fields as desired. While all fields are optional, omitting standard fields may limit compatibility. Binary values are encoded as [RFC 4648 base 64 URI canonical with padding truncated][RFC4648] (b64ut). JSON components are serialized into UTF-8 for signing, verification, and hashing. All JSON fields must be unique, and unmarshalling JSON with duplicate fields must result in an error. All timestamp values should be UTC Unix time.

All Coz Standard Fields

Pay

pay contains the fields alg, now, tmb, and typ and optionally any additional application fields. In the first example msg is additional.

pay Standard Fields

• alg - Specific cryptographic algorithm. E.g. "ES256"
• now - Unix time of message signature. E.g. 1623132000
• tmb - Thumbprint of the signature's key. E.g. "U5XUZ..."
• typ - Type of pay. E.g. "cyphr.me/msg/create"
• msg - Message payload (string). E.g. "Coz is a cryptographic JSON messaging specification."
• dig - Digest of external content. E.g. "LSgWE4v..."

typ's value may be used by applications as desired. The value is recommended to denote API information such as versioning, expected fields, and/or other application defined programmatic functions. In the first example, "typ":"cyphr.me/msg" denotes a pay with the fields ["msg","alg","now","tmb","typ"] as defined by an application.

Coz Key

Example Public Coz Key

{
  "alg":"ES256",
  "now":1623132000,
  "pub":"2nTOaFVm2QLxmUO_SjgyscVHBtvHEfo2rq65MvgNRjORojq39Haq9rXNxvXxwba_Xj0F5vZibJR3isBdOWbo5g",
  "tag":"Coz Example Key",
  "tmb":"U5XUZots-WmQYcQWmsO751Xk0yeVi9XUKWQ2mGz6Aqg"
}

Example Private Coz Key

{
  "alg":"ES256",
  "now":1623132000,
  "prv":"bNstg4_H3m3SlROufwRSEgibLrBuRq9114OvdapcpVA",
  "pub":"2nTOaFVm2QLxmUO_SjgyscVHBtvHEfo2rq65MvgNRjORojq39Haq9rXNxvXxwba_Xj0F5vZibJR3isBdOWbo5g",
  "tag":"Coz Example Key",
  "tmb":"U5XUZots-WmQYcQWmsO751Xk0yeVi9XUKWQ2mGz6Aqg"
}

key Standard Fields

• key - Key object. E.g. "key":{"alg":"ES256", ...}
• alg - Algorithm. E.g. "ES256"
• now - Key creation Unix time. E.g. 1623132000
• prv - Private component. E.g. "bNstg4..."
• pub - Public component. E.g. "2nTOaF..."
• tmb - Thumbprint. E.g. "U5XUZ..."
• typ - Application defined programmatic type. E.g. "cyphr.me/key"
• rvk - Key revocation Unix time. E.g. 1623132000

The private component prv is not included in tmb generation. Also note that tag must not be used programmatically while typ may be used programmatically.

Coz object

The JSON name coz may be used to wrap a coz.

{
  "coz":{
    "pay": {
      "msg": "Coz is a cryptographic JSON messaging specification.",
      "alg": "ES256",
      "now": 1623132000,
      "tmb": "U5XUZots-WmQYcQWmsO751Xk0yeVi9XUKWQ2mGz6Aqg",
      "typ": "cyphr.me/msg/create"
    },
    "sig": "OJ4_timgp-wxpLF3hllrbe55wdjhzGOLgRYsGO1BmIMYbo4VKAdgZHnYyIU907ZTJkVr8B81A2K8U4nQA6ONEg"
  }
}

coz Standard Fields

• coz "Coz" Coz object. E.g. {"coz":{"pay":..., sig:...}}
• can "Canon" Canon of pay. E.g. ["msg","alg","now","tmb","typ"]
• cad "Canon digest" Digest of pay. E.g. "XzrXMG..."
• czd "Coz digest" Digest of ["cad","sig"]. E.g. xrYMu8...
• pay "Payload" Signed payload. E.g. "pay":{"msg":...,"alg":...}
• sig "Signature" Signature over cad. E.g. "sig":"OJ4_ti..."

sig is the signature over the raw bytes of cad (the b64ut-decoded digest). cad is not rehashed before signing. czd's hashing algorithm must align with alg in pay. czd refers to a particular signed message just as cad refers to a particular payload. cad and czd are calculated from brace to brace, including the braces. cad and czd are recalculatable and are recommended to be omitted from cozies, although they may be useful for reference.

As an added technical constraint, because sig and czd are used as identifiers, sig must be non-malleable. Malleable schemes like ECDSA must perform signature canonicalization that constrains signatures to a non-malleable form.

Verbose coz

Including unnecessary labels is not recommended. For example, the JSON object {"pay":{...},"sig":...} doesn't need the label coz if implicitly known by applications. The following may generally be omitted: key may be looked up by applications by using tmb, the fields can, cad, and czd are recalculatable, and the label coz may be inferred.

A tautologic coz:

{
  "coz": {
    "pay": {
      "msg": "Coz is a cryptographic JSON messaging specification.",
      "alg": "ES256",
      "now": 1623132000,
      "tmb": "U5XUZots-WmQYcQWmsO751Xk0yeVi9XUKWQ2mGz6Aqg",
      "typ": "cyphr.me/msg/create"
    },
    "key": {
      "alg":"ES256",
      "now":1623132000,
      "pub":"2nTOaFVm2QLxmUO_SjgyscVHBtvHEfo2rq65MvgNRjORojq39Haq9rXNxvXxwba_Xj0F5vZibJR3isBdOWbo5g",
      "tag":"Coz Example Key",
      "tmb":"U5XUZots-WmQYcQWmsO751Xk0yeVi9XUKWQ2mGz6Aqg"
    },
    "can": ["msg","alg","now","tmb","typ"],
    "cad": "XzrXMGnY0QFwAKkr43Hh-Ku3yUS8NVE0BdzSlMLSuTU",
    "czd": "xrYMu87EXes58PnEACcDW1t0jF2ez4FCN-njTF0MHNo",
    "sig": "OJ4_timgp-wxpLF3hllrbe55wdjhzGOLgRYsGO1BmIMYbo4VKAdgZHnYyIU907ZTJkVr8B81A2K8U4nQA6ONEg"
  }
}

Simplified:

{
  "pay": {
    "msg": "Coz is a cryptographic JSON messaging specification.",
    "alg": "ES256",
    "now": 1623132000,
    "tmb": "U5XUZots-WmQYcQWmsO751Xk0yeVi9XUKWQ2mGz6Aqg",
    "typ": "cyphr.me/msg/create"
  },
  "sig": "OJ4_timgp-wxpLF3hllrbe55wdjhzGOLgRYsGO1BmIMYbo4VKAdgZHnYyIU907ZTJkVr8B81A2K8U4nQA6ONEg"
}

Canon

A canon is a list of fields used for normalization, e.g. ["alg","pub"]. Coz objects are canonicalized for creating digests, signing, and verification. The canon of pay is the currently present fields in order of appearance. The following Coz fields have predefined canons:

• cad's canon is pay's canon.
• tmb's canon is ["alg","pub"].
• czd's canon is ["cad","sig"].

Using a canon, the canonical form of an object is generated by removing fields not appearing in the canon, ordering remaining fields by appearance in the canon, and eliding unnecessary whitespace. The canonical form is serialized into UTF-8 for signing, verification, and hashing.

Canonical form generation steps:

• Omit fields not present in canon.
• Order fields by canon.
• Omit insignificant whitespace.

A canonical digest is generated by hashing the UTF-8 serialized canonical form using the hashing algorithm specified by alg. For example,"ES256"'s hashing algorithm is "SHA-256".

The key thumbprint, tmb, is the canonical digest of key using the canon ["alg","pub"] and hashing algorithm specified by key.alg. For example, a key alg of ES256 corresponds to the hashing algorithm SHA-256. The canonical form of the example key is:

{"alg":"ES256","pub":"2nTOaFVm2QLxmUO_SjgyscVHBtvHEfo2rq65MvgNRjORojq39Haq9rXNxvXxwba_Xj0F5vZibJR3isBdOWbo5g"}

Hashing this canonical form results in the following digest, which is tmb: U5XUZots-WmQYcQWmsO751Xk0yeVi9XUKWQ2mGz6Aqg.

czd is the canonical digest of coz with the canon ["cad","sig"], which results in the JSON {"cad":"...","sig":"..."}. czd's hash must align with alg in pay.

The canonical digest of

• pay is cad,
• ["alg","pub"] is tmb,
• ["cad","sig"] is czd.

Using the first example, the following canonical digests are calculated:

• tmb is U5XUZots-WmQYcQWmsO751Xk0yeVi9XUKWQ2mGz6Aqg
• cad is XzrXMGnY0QFwAKkr43Hh-Ku3yUS8NVE0BdzSlMLSuTU.
• czd is xrYMu87EXes58PnEACcDW1t0jF2ez4FCN-njTF0MHNo.

Signing and verification functions must not mutate pay. Since pay's canon is the present fields, no fields are removed when canonicalizing pay. Any mutation of pay via can must occur by canon related functions.

Coz and Binaries

The canonical digest of a binary file may simply be the digest of the file. The hashing algorithm and any other metadata may be denoted by an accompanying coz. For example, an image ("coz_logo_icon_256.png") may be referred to by its digest.

{
  "alg":"SHA-256",
  "file_name":"coz_logo_icon_256.png",
  "id":"oDBDAg4xplHQby6iQ2lZMS1Jz4Op0bNoD5LK3KxEUZo"
}

For example, a file's digest, denoted by id, may represent the authorization to upload a file to a user's account. Note that Coz associates the signature alg ES256 to hashing alg SHA-256.

{
  "pay": {
    "alg": "ES256",
    "file_name": "coz_logo_icon_256.png",
    "id": "oDBDAg4xplHQby6iQ2lZMS1Jz4Op0bNoD5LK3KxEUZo",
    "now": 1623132000,
    "tmb": "U5XUZots-WmQYcQWmsO751Xk0yeVi9XUKWQ2mGz6Aqg",
    "typ": "cyphr.me/file/create"
  },
  "sig": "AV_gPaDCEd9OEyA1oZPo7LwpypzXkk2htmA-bEobpmcA4Vc7xNcaFPVaEBgU8DDCAZcQZcBHgRlOIjNk9g-Mkw"
}

External Digest Serialization

When Coz digest values (such as tmb, dig, cad, or czd) are stored outside of a coz and alg is not otherwise av