# Cryptographic specs

# Key management

If users have the idPass app (iOS/Android), they will keep their private key (a signing key pair is required in this system, while encryption key is generated if they use a password) on device and its corresponding public key is stored on a blockchain along with user ID (UUID). On the other hand, users who don't have the idPass app need to set up their password so that they can securely store their private key leveraging AWS KMS after symmetric-encryption with their password (AES-CBC 256 bits with PBKDF2 and HMAC with SHA-256 hashing). Finally, the output will be stored in the Credify system.

# Key generation

When users register their account on idPass, they will generate a signing key pair with EdDSA (curve: ed25519).

When users create their account on a web interface, then they will need to set up their password in order for Credify to securely keep their encrypted PII. This flow will generate an encryption key pair as well as a signing key pair. The encryption key pair uses RSA algorithm, and its length is 4096 bits.

# Hashing

Credify uses SHA-2 (SHA256) inside the system. The output is base64 URL encoded.

# Use cases of hashing

# PII provided by users themselves

PII_DIGEST = sha256({
  "name": {
    "first_name": sha256("John"),
    "last_name": sha256("Cred"),
    "verified": true
  },
  "phones": [
    {
      "phone_number": sha256("+84"),
      "country_code": sha256("0321234567"),
      "verified": true
    }
  ],
  "emails": [
    {
      "email": sha256("john.cred@credify.one"),
      "verified": true
    }
  ],
  ...
})

# Claims / Scopes

The standard scopes (e.g. phone, profile, email, address) are maintained by users themselves on their device. On the other hand, the custom scopes are maintained by the providing organizations themselves. Credify will keep only hashed data of the scope values provided by data maintainers along with a signature. The data maintainers are to generate a commitment for each scope and to retain the commitments on their system (Credify keeps only the hashed values, not with the commitments).

A scope has many claims inside. phone scope has phone_number claim and verified claim in itself.

SCOPE_HASH = {
  "phone": {
    "phone_number": "+84321234567",
    "verified": true,
    "commitment": RANDOM_COMMITMENT
  }
}

SCOPE_HASH = sha256(SCOPE_DATA)

# Signing

Credify uses signature for the following cases.

Generate an access token
Ensure an integrity of PII
Ensure consents are made by a data owner itself regarding data sharing
Ensure ephemeral encryption key is coming from the entity that has generated the key (In OIDC)

It utilizes Curve25519, which is one of the industry standard algorithms.

# Generate an access token

Credify uses JWT for end-users to guarantee their authenticity. As of January 2021, Credify is using ed25519 for JWT as well, though JWT standard is not supporting this algorithm.

{
  "alg": "EdDSA",
  "typ": "JWT"
}

# Payload

{
  "iat": 1611810918,
  "exp": 1611814518,
  "signing_key": SIGNING_PUBLIC_KEY_PEM_PKCS1
}

# Composition

const encodedHeader = base64UrlEncode(header);
const encodedPayload = base64UrlEncode(payload); 
const signature = sign(encodedHeader + "." + encodedPayload); // Sign with the corresponding private key
const jwt = encodedHeader + "." + encodedPayload + "." + signature;

Credify will validate this JWT and generate a new access token to this user if the JWT is valid. This access token identifies this user and contains user's scopes (access control). Its expiration time is 1 hour.

# Ensure an integrity of PII

This generates a signature to guarantee its authenticity. PII's holder generates this signature by her private key. PII_DIGEST is described above.

const signature = sign(PII_DIGEST) // Sign with a private key of the user of this PII

# Encryption

An algorithm of asymmetric encryption in the Credify system is RSA. The padding format is RSA OAEP. Each piece of PII will be encrypted with the RSA public key, and the data owner can decrypt it with the private key.

⟵ Libraries Data flow ⟶