Key address

Topic: base low level architecture concept

This is one of architecture concepts important to know during the software development for Universa integration. Among such topics are:

See Github for more details.

Overview

Key address is a text string, 50/51 (short address) or 71/72 (long address) symbols long, that can be used to refer to a public key, instead of the public key itself.

Preface

Universa uses asymmetric cryptography and key pairs (see Basics and main concepts for details), to identify a user as an owner (or holder of some other role) in the smart contract. Normally, the public key of a user can be stored in the contract to identify them; though it is often long and inconvenient to use.

Other platforms (like Bitcoin) may use different methods to avoid that, usually having a single address as a cryptographic hash of the public key. With this approach, though, each particular key pair has a unique address.

In Universa, the single key pair can be used to derive multiple (though not infinitely many, and they are implicitly linked) addresses, each of them can be used independently but still refer to the same public key.

Features

  • More compact than the public key: 51 or 72 symbols long;
  • Can be used for manual input:
    • The used alphabet contains of word-only symbols (no punctuation or special symbols), what makes it possible to select the whole address just by double-clicking it, in many GUI interfaces;
    • Fixed (shorter) length, that can be validated in the forms;
    • Contains CRC code to spot mistypes;
  • Binary format is extensible and future-proof;
  • Uses SHA-3 family cryptography digests for improved quantum resistance: SHA3-384 for long address and SHA3-256 for short address.

Implementation

(See Github for more details).

Components

Key type mask

Contains a mask to specify the exact implementation of the key behind this address.

At the current moment, only two types of keys are supported, with the following “masks” to be used:

  • 0x01 mask – RSA Public key, 2048 bits long, public exponent 0x10001 (65537);
  • 0x02 mask – RSA Public key, 4096 bits long, public exponent 0x10001 (65537).

Type mark

Used to specify the usage purpose of the address. Varying this byte causes the address be visually different; though the binary form is still heavily correlated. You should not rely upon varying this type mark to generate the addresses which should be hard to correlate, this is not it’s purpose!

At the current moment, the primary used and default value of the type mark is 0x00.

SHA-3 digest

Use SHA3-256 (short address) or SHA3-384 (long address) from the public key behind this address.

When hashing the public key, you should first update the digest with the e component of the RSA public key (represented in bytes), then with the n component.

For the bytewise details of implementation, see the source code in Github).

CRC-32

The trailing bytes of the address contain just the CRC-32 calculated of the previous bytes.

Binary representation

Binary representation is the primary internal representation for processing.

Short address (37 bytes)

  • Byte 0: contains the key type mask (bits 0x01…0x08) and the type mark (bits 0x10…0x80);
  • bytes 1…32: value of SHA3-256 digest of the RSA public key behind this address;
  • bytes 33…36: value of CRC-32 from the previous bytes.

Long address (53 bytes)

  • Byte 0: (similarly to the short address) contains the key type mask (bits 0x01…0x08) and the type mark (bits 0x10…0x80);
  • bytes 1…48: value of SHA3-384 digest of the RSA public key behind this address;
  • bytes 49…52: (similarly to the short address) value of CRC-32 from the previous bytes.

Text representation

To convert between the binary (internal) representation of the address and the text one (for end-user usage), use the Safe58 encoding.