Difference between revisions of "Principal"

From Internet Computer Wiki
Jump to: navigation, search
m (Added explanation how different types of principals are created.)
 
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
A '''principal''' is an identifier for an entity on the IC such as a user, a canister smart contract, or a subnet.   
+
A '''principal''' is an identifier for an entity on the IC such as a user, a canister (dapps/smart contracts), or a subnet.   
 +
 
 +
Motoko’s shared functions support a simple form of '''caller identification''' that allows to inspect the Internet Computer principal associated with the caller of a function. The principal associated with a call is a value that identifies a ''unique'' user or canister.
 +
Using the principal associated with the caller of a function allows to implement a basic form of '''access-control''' in a program.
  
 
== Types of principals ==
 
== Types of principals ==
Line 8: Line 11:
  
 
=== Opaque principal ===
 
=== Opaque principal ===
An opaque principal is chosen by the system. This kind of principal is used to reference any canister that is not the management canister.
+
An opaque principal is chosen by the protocol. This kind of principal is used to reference any canister that is not the management canister.
  
 
=== Self-Authenticating principal ===
 
=== Self-Authenticating principal ===
Line 22: Line 25:
  
 
=== Binary ===
 
=== Binary ===
A principal consists of a variable-length byte array. The last byte is used to indicate the type. The table below gives the type inferred from the last byte.
+
A principal consists of a variable-length byte array of up to 29 bytes. The last byte is used to indicate the type. The table below gives the type inferred from the last byte.
 
{| class="wikitable"
 
{| class="wikitable"
 
|'''Byte'''
 
|'''Byte'''
Line 47: Line 50:
  
 
=== Textual ===
 
=== Textual ===
A principal is shown in textual format by prepending it with its [[wikipedia:Cyclic_redundancy_check#CRC-32_algorithm|CRC-32]] value in big-endian byte order, applying [[wikipedia:Base32|Base32]] encoding without padding, grouping characters by length five, and separating them by a hyphen. The table below gives some common principals.
+
A principal is shown in textual format by prepending it with its [[wikipedia:Cyclic_redundancy_check#CRC-32_algorithm|CRC-32]] value in big-endian byte order, applying [[wikipedia:Base32|Base32]] encoding without padding, grouping characters by length five, and separating them by a hyphen. The maximal length of the encoding, including hyphens, is 63 characters. The table below gives some common principals.
 
{| class="wikitable"
 
{| class="wikitable"
 
!Principal
 
!Principal
Line 67: Line 70:
 
|anonymous user
 
|anonymous user
 
|}
 
|}
 +
 +
== Further Information ==
 +
* Check the [https://internetcomputer.org/docs/current/motoko/main/base/Principal/ Motoko Base Library] to see how to use principal functions.
 +
* See the [https://internetcomputer.org/docs/current/motoko/main/caller-id/ principals and caller identification] documentation for a more in-depth guide to the uses of principals on the IC.
 +
* See the [https://internetcomputer.org/docs/current/developer-docs/backend/motoko/access-control/ access-control with identity] tutorial to add extra functionality to a dapp.

Latest revision as of 20:19, 13 November 2023

A principal is an identifier for an entity on the IC such as a user, a canister (dapps/smart contracts), or a subnet.

Motoko’s shared functions support a simple form of caller identification that allows to inspect the Internet Computer principal associated with the caller of a function. The principal associated with a call is a value that identifies a unique user or canister. Using the principal associated with the caller of a function allows to implement a basic form of access-control in a program.

Types of principals

There are several types of principals.

Management principal

The management principal is used to reference the management canister.

Opaque principal

An opaque principal is chosen by the protocol. This kind of principal is used to reference any canister that is not the management canister.

Self-Authenticating principal

A self-authenticating principal is a hash of a public signature key. This kind of principal is for instance used to reference a subnet or user.

Derived principal

The principal is derived from a registering principal. This type of principal is currently not used.

Anonymous principal

The anonymous principal is used to reference an anonymous user.

Representation

Binary

A principal consists of a variable-length byte array of up to 29 bytes. The last byte is used to indicate the type. The table below gives the type inferred from the last byte.

Byte Type
none Management
0x01 Opaque
0x02 Self-Authenticating
0x03 Derived
0x04 Anonymous
0x05 Unassigned

Textual

A principal is shown in textual format by prepending it with its CRC-32 value in big-endian byte order, applying Base32 encoding without padding, grouping characters by length five, and separating them by a hyphen. The maximal length of the encoding, including hyphens, is 63 characters. The table below gives some common principals.

Principal Description
aaaaa-aa management canister
rrkah-fqaaa-aaaaa-aaaaq-cai governance canister
ryjl3-tyaaa-aaaaa-aaaba-cai ledger canister
tdb26-jop6k-aogll-7ltgs-eruif-6kk7m-qpktf-gdiqx-mxtrf-vb5e6-eqe network nervous system
2vxsx-fae anonymous user

Further Information