pub struct Principal(_);
Expand description
A principal describes the security context of an identity, namely any identity that can be authenticated along with a specific role. In the case of the Internet Computer this maps currently to the identities that can be authenticated by a canister. For example, a canister ID is a Principal. So is a user.
Note a principal is not necessarily tied with a public key-pair, yet we need at least a key-pair of a related principal to sign requests.
A Principal can be serialized to a byte array (Vec<u8>
) or a text
representation, but the inner structure of the byte representation
is kept private.
Example of using a Principal object:
use ic_types::Principal;
let text = "aaaaa-aa"; // The management canister ID.
let principal = Principal::from_text(text).expect("Could not decode the principal.");
assert_eq!(principal.as_slice(), &[]);
assert_eq!(principal.to_text(), text);
Serialization is enabled with the “serde” feature. It supports serializing to a byte bufer for non-human readable serializer, and a string version for human readable serializers.
use ic_types::Principal;
use serde::{Deserialize, Serialize};
use std::str::FromStr;
#[derive(Serialize)]
struct Data {
id: Principal,
}
let id = Principal::from_str("2chl6-4hpzw-vqaaa-aaaaa-c").unwrap();
// JSON is human readable, so this will serialize to a textual
// representation of the Principal.
assert_eq!(
serde_json::to_string(&Data { id: id.clone() }).unwrap(),
r#"{"id":"2chl6-4hpzw-vqaaa-aaaaa-c"}"#
);
// CBOR is not human readable, so will serialize to bytes.
assert_eq!(
serde_cbor::to_vec(&Data { id: id.clone() }).unwrap(),
&[161, 98, 105, 100, 73, 239, 205, 171, 0, 0, 0, 0, 0, 1],
);
Implementations
sourceimpl Principal
impl Principal
sourcepub const fn management_canister() -> Principal
pub const fn management_canister() -> Principal
An empty principal that marks the system canister.
sourcepub fn self_authenticating<P>(public_key: P) -> Principal where
P: AsRef<[u8]>,
pub fn self_authenticating<P>(public_key: P) -> Principal where
P: AsRef<[u8]>,
Right now we are enforcing a Twisted Edwards Curve 25519 point as the public key.
sourcepub const fn from_slice(bytes: &[u8]) -> Principal
pub const fn from_slice(bytes: &[u8]) -> Principal
Attempt to decode a slice into a Principal.
Panics
Panics if the bytes can’t be interpreted.
Examples
const FOO: Principal = Principal::from_slice(&[0; 29]); // normal length
const MGMT: Principal = Principal::from_slice(&[]); // management
const OPQ: Principal = Principal::from_slice(&[4,3,2,1]); // opaque id
const BAR: Principal = Principal::from_slice(&[0; 32]); // Fails, too long
// Fails, ends in 0x04 (anonymous), but has a prefix
const BAZ: Principal = Principal::from_slice(&[1,2,3,4]);
sourcepub const fn try_from_slice(bytes: &[u8]) -> Result<Principal, PrincipalError>
pub const fn try_from_slice(bytes: &[u8]) -> Result<Principal, PrincipalError>
Attempt to decode a slice into a Principal.
sourcepub fn from_text<S>(text: S) -> Result<Principal, PrincipalError> where
S: AsRef<str>,
pub fn from_text<S>(text: S) -> Result<Principal, PrincipalError> where
S: AsRef<str>,
Parse the text format for canister IDs (e.g., jkies-sibbb-ap6
).
The text format follows the public spec (see Textual IDs section).
Trait Implementations
sourceimpl CandidType for Principal
impl CandidType for Principal
sourceimpl<'de> Deserialize<'de> for Principal
impl<'de> Deserialize<'de> for Principal
sourcepub fn deserialize<D>(
deserializer: D
) -> Result<Principal, <D as Deserializer<'de>>::Error> where
D: Deserializer<'de>,
pub fn deserialize<D>(
deserializer: D
) -> Result<Principal, <D as Deserializer<'de>>::Error> where
D: Deserializer<'de>,
Deserialize this value from the given Serde deserializer. Read more
sourceimpl Ord for Principal
impl Ord for Principal
sourceimpl PartialOrd<Principal> for Principal
impl PartialOrd<Principal> for Principal
sourcepub fn partial_cmp(&self, other: &Principal) -> Option<Ordering>
pub fn partial_cmp(&self, other: &Principal) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
1.0.0 · sourcefn lt(&self, other: &Rhs) -> bool
fn lt(&self, other: &Rhs) -> bool
This method tests less than (for self
and other
) and is used by the <
operator. Read more
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
sourceimpl Serialize for Principal
impl Serialize for Principal
sourcepub fn serialize<S>(
&self,
serializer: S
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error> where
S: Serializer,
pub fn serialize<S>(
&self,
serializer: S
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error> where
S: Serializer,
Serialize this value into the given Serde serializer. Read more
sourceimpl TryFrom<Vec<u8, Global>> for Principal
impl TryFrom<Vec<u8, Global>> for Principal
Vector TryFrom. The slice and array version of this trait are defined below.
impl Copy for Principal
impl Eq for Principal
impl StructuralEq for Principal
impl StructuralPartialEq for Principal
Auto Trait Implementations
impl RefUnwindSafe for Principal
impl Send for Principal
impl Sync for Principal
impl Unpin for Principal
impl UnwindSafe for Principal
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToHex for T where
T: AsRef<[u8]>,
impl<T> ToHex for T where
T: AsRef<[u8]>,
sourcepub fn encode_hex<U>(&self) -> U where
U: FromIterator<char>,
pub fn encode_hex<U>(&self) -> U where
U: FromIterator<char>,
Encode the hex strict representing self
into the result. Lower case
letters are used (e.g. f9b4ca
) Read more
sourcepub fn encode_hex_upper<U>(&self) -> U where
U: FromIterator<char>,
pub fn encode_hex_upper<U>(&self) -> U where
U: FromIterator<char>,
Encode the hex strict representing self
into the result. Upper case
letters are used (e.g. F9B4CA
) Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcepub fn to_owned(&self) -> T
pub fn to_owned(&self) -> T
Creates owned data from borrowed data, usually by cloning. Read more
sourcepub fn clone_into(&self, target: &mut T)
pub fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more