[][src]Struct sequoia_openpgp::packet::UserID

pub struct UserID { /* fields omitted */ }

Holds a UserID packet.

See Section 5.11 of RFC 4880 for details.

Methods

impl UserID[src]

pub fn from_address<O, S>(name: O, comment: O, address: S) -> Result<Self> where
    S: AsRef<str>,
    O: Into<Option<S>>, 
[src]

Constructs a User ID.

This escapes the name. The comment and address must be well formed according to RFC 2822. Only the address is required.

If you already have a full RFC 2822 mailbox, then you can just use UserID::from().

assert_eq!(UserID::from_address(
               "John \"the Boat\" Smith".into(),
               None, "boat@example.org").unwrap().value(),
           &b"\"John \\\"the Boat\\\" Smith\" <boat@example.org>"[..]);

pub fn from_unchecked_address<O, S>(
    name: O,
    comment: O,
    address: S
) -> Result<Self> where
    S: AsRef<str>,
    O: Into<Option<S>>, 
[src]

Constructs a User ID.

This escapes the name. The comment must be well formed, the address can be arbitrary.

This is useful when you want to specify a URI instead of an email address.

If you have a full RFC 2822 mailbox, then you can just use UserID::from().

assert_eq!(UserID::from_unchecked_address(
               "NAS".into(),
               None, "ssh://host.example.org").unwrap().value(),
           &b"NAS <ssh://host.example.org>"[..]);

pub fn value(&self) -> &[u8][src]

Gets the user ID packet's value.

pub fn name(&self) -> Result<Option<String>>[src]

Treats the user ID as an RFC 2822 name-addr and extracts the display name, if any.

Note: if the email address is invalid, but the rest of the input is okay, this still returns the display name.

pub fn comment(&self) -> Result<Option<String>>[src]

Treats the user ID as an RFC 2822 name-addr and extracts the first comment, if any.

Note: if the email address is invalid, but the rest of the input is okay, this still returns the first comment.

pub fn address(&self) -> Result<Option<String>>[src]

Treats the user ID as an RFC 2822 name-addr and extracts the address, if valid.

If the email address is invalid, returns Ok(None). In this case, the invalid email address can be returned using UserID::other_address().

pub fn other(&self) -> Result<Option<String>>[src]

Treats the user ID as an RFC 2822 name-addr and, if the address is invalid, returns that.

If the address is valid, this returns None.

This is particularly useful with the following types of User IDs:

First Last (Comment) <ssh://server.example.net>

will be successfully parsed. In this case, NameAddrOrOther::address() will return the parse error, and the invalid address can be obtained using NameAddrOrOther::other().

pub fn other_or_address(&self) -> Result<Option<String>>[src]

Treats the user ID as an RFC 2822 name-addr and returns the address.

If the address is invalid, that is returned. For instance:

First Last (Comment) <ssh://server.example.net>

will be successfully parsed and this function will return ssh://server.example.net.

pub fn address_normalized(&self) -> Result<Option<String>>[src]

Returns a normalized version of the UserID's email address.

Normalized email addresses are primarily needed when email addresses are compared.

Note: normalized email addresses are still valid email addresses.

This function normalizes an email address by doing puny-code normalization on the domain, and lowercasing the local part in the so-called empty locale.

Note: this normalization procedure is the same as the normalization procedure recommended by Autocrypt.

impl UserID[src]

pub fn bind<H, T>(
    &self,
    signer: &mut dyn Signer,
    tpk: &TPK,
    signature: Builder,
    hash_algo: H,
    creation_time: T
) -> Result<Signature> where
    H: Into<Option<HashAlgorithm>>,
    T: Into<Option<Tm>>, 
[src]

Creates a binding signature.

The signature binds this userid to tpk. signer will be used to create a signature using signature as builder. Thehash_algo defaults to SHA512, creation_time to the current time.

This function adds a creation time subpacket, a issuer fingerprint subpacket, and a issuer subpacket to the signature.

Example

This example demonstrates how to bind this userid to a TPK. Note that in general, the TPKBuilder is a better way to add userids to a TPK.

// Generate a TPK, and create a keypair from the primary key.
let (tpk, _) = TPKBuilder::new().generate()?;
let mut keypair = tpk.primary().clone().into_keypair()?;
assert_eq!(tpk.userids().len(), 0);

// Generate a userid and a binding signature.
let userid = UserID::from("test@example.org");
let builder =
    signature::Builder::new(SignatureType::PositiveCertificate);
let binding = userid.bind(&mut keypair, &tpk, builder, None, None)?;

// Now merge the userid and binding signature into the TPK.
let tpk = tpk.merge_packets(vec![userid.into(), binding.into()])?;

// Check that we have a userid.
assert_eq!(tpk.userids().len(), 1);

pub fn certify<S, H, T>(
    &self,
    signer: &mut dyn Signer,
    tpk: &TPK,
    signature_type: S,
    hash_algo: H,
    creation_time: T
) -> Result<Signature> where
    S: Into<Option<SignatureType>>,
    H: Into<Option<HashAlgorithm>>,
    T: Into<Option<Tm>>, 
[src]

Returns a certificate for the user id.

The signature binds this userid to tpk. signer will be used to create a certification signature of type signature_type. signature_type defaults to SignatureType::GenericCertificate, hash_algo to SHA512, creation_time to the current time.

This function adds a creation time subpacket, a issuer fingerprint subpacket, and a issuer subpacket to the signature.

Errors

Returns Error::InvalidArgument if signature_type is not one of SignatureType::{Generic, Persona, Casual, Positive}Certificate

Example

This example demonstrates how to certify a userid.

// Generate a TPK, and create a keypair from the primary key.
let (alice, _) = TPKBuilder::new()
    .primary_keyflags(KeyFlags::default().set_certify(true))
    .add_userid("alice@example.org")
    .generate()?;
let mut keypair = alice.primary().clone().into_keypair()?;

// Generate a TPK for Bob.
let (bob, _) = TPKBuilder::new()
    .primary_keyflags(KeyFlags::default().set_certify(true))
    .add_userid("bob@example.org")
    .generate()?;

// Alice now certifies the binding between `bob@example.org` and `bob`.
let certificate =
    bob.userids().nth(0).unwrap().userid()
    .certify(&mut keypair, &bob, SignatureType::PositiveCertificate,
             None, None)?;

// `certificate` can now be used, e.g. by merging it into `bob`.
let bob = bob.merge_packets(vec![certificate.into()])?;

// Check that we have a certification on the userid.
assert_eq!(bob.userids().nth(0).unwrap().certifications().len(), 1);

pub fn revoke<H, T>(
    &self,
    signer: &mut dyn Signer,
    tpk: &TPK,
    code: ReasonForRevocation,
    reason: &[u8],
    hash_algo: H,
    creation_time: T
) -> Result<Signature> where
    H: Into<Option<HashAlgorithm>>,
    T: Into<Option<Tm>>, 
[src]

Returns a revocation certificate for the user id.

The revocation signature revokes the binding between this user attribute and tpk. signer will be used to create a signature with the given reason in code and reason. signature_type. hash_algo defaults to SHA512, creation_time to the current time.

This function adds a creation time subpacket, a issuer fingerprint subpacket, and a issuer subpacket to the signature.

Example

// Generate a TPK, and create a keypair from the primary key.
let (tpk, _) = TPKBuilder::new()
    .add_userid("some@example.org")
    .generate()?;
let mut keypair = tpk.primary().clone().into_keypair()?;

// Generate the revocation for the first and only UserID.
let revocation =
    tpk.userids().nth(0).unwrap().userid()
        .revoke(&mut keypair, &tpk,
                ReasonForRevocation::UIDRetired,
                b"Left example.org.", None, None)?;
assert_eq!(revocation.sigtype(), SignatureType::CertificateRevocation);

// Now merge the revocation signature into the TPK.
let tpk = tpk.merge_packets(vec![revocation.clone().into()])?;

// Check that it is revoked.
let uid = tpk.userids().nth(0).unwrap();
if let RevocationStatus::Revoked(revocations) = uid.revoked(None) {
    assert_eq!(revocations.len(), 1);
    assert_eq!(revocations[0], revocation);
} else {
    panic!("UserID is not revoked.");
}

Trait Implementations

impl Arbitrary for UserID[src]

impl Clone for UserID[src]

impl Debug for UserID[src]

impl Display for UserID[src]

impl Eq for UserID[src]

impl<'_> From<&'_ [u8]> for UserID[src]

impl<'a> From<&'a str> for UserID[src]

impl<'a> From<Cow<'a, str>> for UserID[src]

impl From<String> for UserID[src]

impl From<UserID> for Packet[src]

impl From<Vec<u8>> for UserID[src]

impl Hash for UserID[src]

fn hash(&self, hash: &mut Context)[src]

Update the Hash with a hash of the user id.

impl Hash for UserID[src]

impl<'a> Parse<'a, UserID> for UserID[src]

impl PartialEq<UserID> for UserID[src]

impl Serialize for UserID[src]

impl SerializeInto for UserID[src]

Auto Trait Implementations

impl !RefUnwindSafe for UserID

impl Send for UserID

impl !Sync for UserID

impl Unpin for UserID

impl !UnwindSafe for UserID

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T> ToString for T where
    T: Display + ?Sized
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.