Skip to content

Latest commit

 

History

History
113 lines (65 loc) · 4.95 KB

v1.md

File metadata and controls

113 lines (65 loc) · 4.95 KB

Revenge Keys

A "Revenge Key" is a either public or private key file that is used to sign and verify data with certifications support. It is very much inspired by GPG, but has less features and a different file format.

The purpose of Revenge Keys is to provide a simple way to sign and verify files. For example, Revenge plugins that can run any arbitrary code. They allow the user to trust specific plugin developers to get updates to their plugins immediately without waiting for manual review from the Revenge team, for example.

Revenge Keys don't support revocation, so if a key is compromised, the user must manually untrust the key. However, you can always make a system that wraps around the keys to support revocation. Become your own certificate authority!

Specification

This is the specification for Revenge keys version 1.

Key file format

Revenge Keys are a ZIP file containing files with multiple data types. They don't have their own file extension.

Why ZIP?
We already use ZIP files for our plugins, so it makes sense to use them for the keys too. Making another file format is more effort, just to add even more size to our JS bundle.

Data type Description
BIN(l) l bytes of any binary data
ZIP ZIP file
UTF8 UTF-8 string
U64 Unsigned 64-bit big-endian integer
U4 Unsigned 4-bit big-endian integer
SIG(x) Signature of x (BIN(64))
KEY Key (BIN(32))
KEYID Last 128 bits of SHA-512 uppercased HEX representation of KEY (BIN(16))

Base key structure

  • t: Type & Version (BIN(1))

    The type and version of the key format.

    Structure

    Bit offset Data type Description
    0 U4 Version
    4 U4 Type

    Key types

    Value Description
    1 (0b0001) Public key
    2 (0b0010) Private key

  • k: Key material (KEY)

  • i: Information index (ZIP)

    Structure is specific to type of key.

  • is: Signature of the information index (SIG(SHA512(i)))

Public key

  • i: Information index (ZIP)

    • n: Name (UTF8)

      This is to ensure that the information is derived from the correct key

    • e: Expires (U64)

      A unix timestamp of when the key expires

  • c: Certifications index (ZIP)

    • Certifier.PublicKey.ID (KEYID): Signature (BIN)

      The key of this dictionary is the public key ID of the certifier, which can be derived from the certifier's private key.

    Note: At least one certification must exist. Revenge keys are self-signed which means that the first certification is from the public key's matching private key itself.

Why self-signed?

It ensures the given information is derived from the correct key, so the correct information from the key can be displayed to the user. However, this doesn't ensure that the information is true as you can self-sign the information with any arbitrary data.

Private key

The private key contains some of the public key's information.

Signature file format

Revenge signatures are also a ZIP file containing the signature material and the public ID of the signer.

  • s: Signature (SIG(SHA512(InputData)))

  • i: Public ID of the signer (KEYID)

Client behavior

Importing keys

When a new key is imported, the client must verify the key's information index signature with the public key. If the signature is valid, the client can then display the information to the user. Otherwise, the key is deemed invalid.

Trusting keys

The client must allow the user to trust keys and untrust keys. When a key is trusted, the client will be able to do automatic actions that'd be considered unsafe. For example, automatically executing plugins that have been signed with the trusted key. When a key is untrusted, the client will not do these automatic actions anymore.

Importing keys with updated information

Key information can be updated by the key owner (e.g. name, expire date). When a key is imported with updated information, the client must follow the same steps as importing a new key. The client should ideally prompt the user to verify the new information is correct before updating the key.