Internet Computer Basics — Part 1: Principals and Identities

Essential concepts that developers need to know to begin interacting with the Internet Computer and building simple apps.

This article initiates an Internet Computer Basics series with definitions of “principal” and “identity” to manage apps deployed on the Internet Computer.

About this series

In this series, I will describe the essential concepts that developers need to know to begin interacting with the Internet Computer and building simple apps.

Examples would be easier to understand if you already have a background in building web applications, know at least one programming language, and are comfortable interacting with your computer through the command line.

In the first article, we will start getting comfortable with the concepts of a principal and an identity to manage apps deployed to the Internet Computer.

What is the Internet Computer?

The Internet Computer is a new platform for building internet apps that combines features of a cloud provider, like AWS, with a distributed blockchain, like Ethereum or Solana. The Internet Computer is a good match for three use cases:

1. Make web / mobile apps more transparent, resilient, and censorship proof
2. Accelerate blockchain apps like Tokens, NFTs, DeFi to run at web speeds, hundreds or thousands of times faster and cheaper than blockchains like Ethereum
3. Combine both types of apps into a single package that allows developers to offer new kinds of services like next-generation NFTs and open governance

On the implementation level, the Internet Computer is a network of distributed data centers (nodes) across the globe that run the application code and store the data. The Internet Computer is a protocol, which means that the network of the nodes is open, so anyone can join to provide computational capacity and earn gas fees in return.

Internet Computer apps consist of simple building blocks called canister smart contracts. You can think of a canister as something similar to an object from object-oriented programming. A canister combines both code and data and can communicate with the external world: users, network services, and other canisters.

What is a “principal”?

A “principal” is someone who can interact with a computer system and can be identified for this purpose. Internet Computer has two types of principals:

• Users, who can interact with the Internet Computer by deploying canisters, moving ICP tokens from one account to another, or calling canister methods
• Canisters that can do the same set of actions programmatically

Most of the time when we talk about principals we really mean “principal id”, a unique identifier assigned to a principal and could be used, for example, to specify which resources the user or the canister has access to. In Internet Computer documentation and tools we will use “principal” and “principal id “interchangeably. Here’s an example of a text representation of a principal id:

% dfx identity get-principal
nfxu4-cn7qt-x7r3c-5dhnk-dcrct-gmgoz-67gcg-5glvc-2krhv-gcmsr-qqe

Principals are similar to public SSH keys. For example, you add your public SSH key to GitHub to be able to access a private repository. Similarly, you need to register your principal with the services that you plan to interact with in the future. Principals (like public SSH keys) are not confidential, so you can share them with anyone when needed.

Typical properties of Principals and public SSH keys:

• They are not secret
• They need to be registered with the services you need to access
• You need an additional secret key to authenticate (don’t worry — you already have one automatically created!)

Why do you need a principal?

As a developer, you need a principal to identify yourself to the Internet Computer to perform the following functions:

• Deploy canisters (same as deploying dapps or smart contracts)
• Interact with already deployed canisters, for example, by calling a canister method.
• Manage canisters, for example, stop, or change parameters, and manage the hosting payments (see later article on Cycle Wallets)

Canisters use principals to ensure that each operation is performed only by an authorized user. For example, a user needs to identify themselves as a particular principal to be able to re-deploy a canister with an updated code or move the canister payment balance to another wallet.

Principals are also used by the Internet Identity behind the scenes to identify you to various user-facing dapps. However, in this case, you will seldom see your principals directly.

How to get the current principal?

Most of the time, you will interact with principals during the development of IC dapps. On your development machine, you can get the current principal by typing this command into the console:

% dfx identity get-principal
nfxu4-cn7qt-x7r3c-5dhnk-dcrct-gmgoz-67gcg-5glvc-2krhv-gcmsr-qqe

Please note that you need to install and run dfx command before you can see your principal.

What is an “identity”?

Since a user principal is a text representation of a public key of an asymmetric cryptographic key pair, each principal has an associated private key. Both keys are stored as an object called an “identity.” You could install multiple identities on your machine, and each identity has a name.

While similar in name, command like Identities are different from web identities created through Internet Identity service.

Identities are stored in your user directory at ~/.config/dfx/identity/<identity_name>/identity.pem the path. Command-line apps will use the .pem file to confirm your identity to services. This process is similar to getting access to an SSH server, where you need the private SSH key to prove your identity and get access to servers where you previously added the public key.

If you lose your identity file (for example, by losing your computer), you won’t be able to identify yourself as this principal anymore.

Identity .pem files are highly confidential. You should never share them with anyone.

By default, a new identity is created when you run dfx on a new machine for the first time. This identity is called “default identity” and will be used for all IC interactions by default unless you manually select a different one.

You can also copy your identity from your old computer, where you have created it, as you can copy your SSH keys.

How to manage multiple identities?

You can have multiple identities installed on the same machine. To create a new identity, you can run dfx identity new <identity_name>. For example, you can run this command to create a new identity name “new_identity”:

% dfx identity new new_identity
Creating identity: "new_identity".
Created identity: "new_identity".

To switch identities, you can use dfx identity use <identity_name>:

% dfx identity use new_identity
Using identity: "new_identity".

To get which principal is used right now, you can use dfx identity whoami:

% dfx identity whoami
new_identity

To get the list of all identities, you can use dfx identity list command:

% dfx identity list
anonymous
default
new_identity *

How can you copy an identity between machines?

As I mentioned before, you can copy your identity between machines to avoid registering multiple principals with your services. This process is similar to copying SSH keys between computers.

To start, you need to copy your identity .pem file from the original computer where it was created. The .pem file for each identity is stored at ~/.config/dfx/identity/<identity_name>/identity.pem.

Let’s say you copied the identity.pem file from your old computer to ~/import/identity.pem on the new machine. Then you can run this command to import this file to be recognized as one of the identities on this computer:

% dfx identity import old_identity ~/import/identity.pem
Creating identity: "old_identity".
Created identity: "old_identity".

Then you can activate the imported identity by calling:

% dfx identity use old_identity
Using identity: "old_identity".

How to set your principal as a canister controller?

When you deploy a canister, you need to ensure that your current principal is set as a canister controller. A controller is a principal who can manage a canister, for example:

• Deploy and update the canister
• Control cycles in the canister’s wallet (to pay for computation and data storage)

To display the principals for one of the canisters, you can run the dfx canister status <canister_name>. For example:

% dfx canister status hello
Canister status call result for hello.
Status: Running
Controllers: nfxu4-cn7qt-x7r3c-5dhnk-dcrct-gmgoz-67gcg-5glvc-2krhv-gcmsr-qqe
Memory allocation: 0
Compute allocation: 0
Freezing threshold: 2_592_000
Memory Size: Nat(363948)
Balance: 4_000_000_000_000 Cycles
Module hash: 0xfa16da03d37cffe89382b29db2077de1229841ea31b91b8c040b740317390cb7

To set one of the identities as the controller, you can use dfx canister update-settings <canister_name> --controller <identity_name_or_principal_id>. For example:

% dfx canister update-settings hello --controller old_identity
Set controller of "hello" to: old_identity

Summary

Principals are text representations of public keys that identify canisters and users. Each principal is a part of an identity, a pair of public keys (the principal) and a secret key.

Identities are stored on your machine in the ~/.config/dfx/identity folder.

There are a few commands that you need to know to manage identities:

• dfx identity import - to copy identities between machines and import them
• dfx identity new - to create a new identity
• dfx identity use - to switch between identities
• dfx identity whoami- to check which identity is currently used

In the following article of the series, we will cover cycle wallets and how to pay for hosting your canisters on ICP.

____

Start building at smartcontracts.org and join the developer community at forum.dfinity.org.