Skip to content

Identity Management Guide

Manage your Kunuleco identity, password, and backups.

Commands here are node verbs. Type them as shown over SSH, or in the Urchin client's command mode (add / in chat mode). Commands that start with / exist only in the client.

What Your Identity Is

Your identity is a cryptographic key on your own machine, protected by your password. Other people see it as a handle, your name followed by # and six characters derived from your identity, such as mira#4Q7K2M. The six characters use Crockford base32, so they contain no I, L, O or U, and case does not matter when you type them.

When your node connects to another, each side proves who it is with a signed hello. What it proves is an AID, a KERI identifier. A name can change and anyone can claim one, so anything that must hold on to a person, such as a block or an invite to a presence, is kept against the AID the connection proved.

View Your Identity

whoami
@whoami

whoami shows your name, where you are, and what you carry. @whoami shows your peer-to-peer identity, with your DID, peer ID and routes. To see what your node knows about someone else, use finger <name>.

Create an Account

In the Urchin client, enter a username on the welcome screen and choose Create Identity. You set a username, a password and a theme.

The first account on a new node is created freely and becomes the node's owner. After that, a new account needs a sponsor, someone who holds the right to create accounts (create_user). In the client this is the Sponsor step, where the newcomer gives their chosen credentials with a sponsor's username and password.

The node also has an account of its own, the node user. It signs the owner's first grants and can never be signed into.

Where Your Identity Lives

Your account lives in the node's data directory, with the node's database and keystores. On an installed node that is ~/.local/share/kunuleco/data/ on Linux and %LOCALAPPDATA%\Kunuleco\data\ on Windows. The KUNULECO_DATA_DIR environment variable overrides it. The configuration reference has the details, including macOS.

Change Password

In the Urchin client:

/passwd

The client asks for your current password, then the new one.

Export Identity

Create an encrypted backup of your identity:

export-identity '<path>' <base64_passphrase>

The node writes the file on its own machine, readable only by its owner. The passphrase must be base64-encoded and at least 12 characters once decoded. Encode it with echo -n 'passphrase' | base64 rather than typing a raw secret where it can land in your shell history.

In the Urchin client, type export-identity on its own. A dialog picks the path, masks the passphrase, and handles the quoting and encoding for you.

Put the path in single quotes when you type it yourself. The parser treats a bare backslash as an escape, so an unquoted Windows path turns into a different filename without an error.

The file and the passphrase together are complete control of your identity. Keep the file somewhere safe and offline.

Import Identity

Restore from a backup:

import-identity <file> <base64_passphrase>

The node reads the file only from its imports directory, <data>/imports, so copy the file there first and name it relative to that directory. The import refuses to replace an identity that is already there unless you add --overwrite, which is irreversible. It also refuses a name another account on the node holds, and the node's own name.

After a successful import, start a new session and sign in with the imported identity.

A restore brings back who you are. It does not bring back what a node let you do. Permissions live on the node that granted them, and a node you restore onto has no record of you.

Key Events and Rotation

KERI records each key event in an append-only chain that commits in advance to the next key, which is what will let a key be rotated later. There is no command yet to view the event chain, verify it, or rotate a key.

Owner Rights and Grants

The right to create accounts (create_user), the owner's right (node_admin), and the right to pass either on (delegate:...) each expire 90 days after they are granted, unless the person who granted them renews them. Nothing renews by itself. The owner's first grants, made by the node user, do not expire. When you sign in, the node tells you about grants you gave that lapse within 30 days.

delegations
renew mira#4Q7K2M
renew all
yes
undelegate <id>
  • delegations lists the grants you gave or hold, with their ids and when each expires. The owner sees every grant on the node.
  • renew <name> renews every expiring grant you gave that person.
  • renew all lists every grant you gave that can be renewed, and signs nothing. yes, typed within 10 minutes, renews exactly that list.
  • undelegate <id> revokes a grant, and what was passed on from it. It refuses the node user's own grants and the last node_admin.

Holding create_user does not make someone an owner. Only node_admin does.

More Than One Account

A node can hold more than one account. The first is the owner, and each later one joins through a sponsor. Each person signs in with their own username and password, in the client or over SSH.

How accounts on the same node talk to each other is still changing.

Security Recommendations

  1. Use a strong password. Your password protects your identity, and there is no reset.
  2. Export a backup. Keep the encrypted file offline, and keep the passphrase separate from it.
  3. Don't share your export. Anyone with the file and the passphrase holds your identity.
  4. Record your node's trust bundle. When you connect the client to a node on another machine, record the bundle its operator gives you with /trust, so the client can tell it reached the right node.

Recovery

Forgot Password

There is no password reset. A reset would need someone else to control your identity, and no one does. Without your password, your identity is inaccessible.

If you have a backup: import it with import-identity, as above, and sign in with the password that goes with it.

If you don't have a backup: you must create a new identity. Anyone who invited you will need to invite the new one.

Compromised Key

There is no key-rotation command yet, so a compromised key cannot be replaced by rotating it.