Struct Key 

pub struct Key<'d> { /* private fields */ }

A loaded TPM key. Its handle is unloaded from the TPM when dropped.

Borrows the Device it lives on, so it cannot outlive the connection.

Implementations

impl<'d> Key<'d>

pub fn ecdh_gen(&self) -> Result<EcdhResult>

One-shot ephemeral ECDH: the TPM generates an ephemeral key pair, derives Z against this key’s private part, and returns the ephemeral public point plus Z. A peer holding this key’s private part can recover the same Z from the point via ecdh_z.

pub fn ecdh_z(&self, point: &[u8]) -> Result<Secret>

Recompute the shared secret Z from a peer’s public point (x || y, the output of ecdh_gen) and this key’s private part.

impl<'d> Key<'d>

pub fn hmac(&self, data: &[u8], hash: HashAlg) -> Result<Vec<u8>>

Compute HMAC over data using this loaded keyed-hash key, whose secret stays inside the TPM. hash must match the algorithm the key was created with (see Template::hmac).

This is the one-shot TPM2_HMAC, so data must fit the TPM’s max command buffer; larger inputs are rejected rather than truncated.

impl<'d> Key<'d>

pub fn handle(&self) -> u32

The TPM handle value for this key.

Examples found in repository

examples/create_primary.rs (line 25)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let dev = Device::open()?;
    println!("wolfTPM initialized");

    let mut r = [0u8; 16];
    dev.get_random(&mut r)?;
    println!("GetRandom: {}", hex(&r));

    let ecc = dev.create_primary(Hierarchy::Owner, KeyAlg::EccP256, None)?;
    println!("ECC SRK handle: 0x{:08x}", ecc.handle());

    let rsa = dev.create_primary(Hierarchy::Owner, KeyAlg::Rsa, None)?;
    println!("RSA SRK handle: 0x{:08x}", rsa.handle());

    Ok(())
}

examples/full_flow.rs (line 29)

fn main() -> Result<(), wolftpm::TpmError> {
    let dev = Device::open()?;
    println!("device            connected to TPM");

    let mut nonce = [0u8; 16];
    dev.get_random(&mut nonce)?;
    println!("get_random        {}", hex(&nonce));

    let srk = dev.create_primary(Hierarchy::Owner, KeyAlg::EccP256, None)?;
    println!("create_primary    ECC SRK handle 0x{:08x}", srk.handle());

    let signer = dev.create_and_load(&srk, &Template::signing(KeyAlg::EccP256)?, None)?;
    println!(
        "create_and_load   signing key handle 0x{:08x}",
        signer.handle()
    );

    let digest = [0x11u8; 32];
    let sig = signer.sign_hash(&digest)?;
    signer.verify_hash(&digest, &sig)?;
    println!("sign/verify       {} byte signature, verified", sig.len());

    let sealed = dev.seal(&srk, b"my secret", None)?;
    let secret = dev.unseal(sealed, &srk, None)?;
    println!(
        "seal/unseal       recovered \"{}\"",
        core::str::from_utf8(&secret).unwrap_or("<bytes>")
    );

    // Scope the reloaded key so its handle is freed before the attestation
    // step below. A TPM only holds a few transient objects at once (often 3),
    // so keep the number of simultaneously-loaded keys small.
    {
        let blob = dev.create_key(&srk, &Template::signing(KeyAlg::EccP256)?, None)?;
        let bytes = blob.to_bytes()?;
        let restored = KeyBlob::from_bytes(&dev, &bytes)?;
        let loaded = restored.load(&srk, None)?;
        println!(
            "key blob          {} bytes, reloaded as handle 0x{:08x}",
            bytes.len(),
            loaded.handle()
        );
    }

    let before = dev.pcr_read(16, HashAlg::Sha256)?;
    dev.pcr_extend(16, HashAlg::Sha256, &[0xAB; 32])?;
    let after = dev.pcr_read(16, HashAlg::Sha256)?;
    println!(
        "pcr read/extend   PCR16 {}.. -> {}..",
        hex(&before[..6]),
        hex(&after[..6])
    );

    let index = 0x0150_0100;
    let _ = dev.nv_delete(index);
    let mut slot = dev.nv_create(index, 32, None)?;
    dev.nv_write(&mut slot, b"metadata", 0)?;
    let mut buf = [0u8; 32];
    let n = dev.nv_read(&mut slot, &mut buf, 0)?;
    dev.nv_delete(index)?;
    println!("nv define/rw      {} bytes at index 0x{:08x}", n, index);

    let aik = dev.create_and_load(&srk, &Template::attestation(KeyAlg::EccP256)?, None)?;
    let att = dev.certify(&signer, &aik, &nonce)?;
    println!("certify           {} byte attestation", att.attest.len());

    println!("done              all operations succeeded");
    Ok(())
}

pub fn name(&self) -> Vec<u8>

The object’s cryptographic Name (the hash of its public area), as computed by the TPM when the key was loaded. Needed to address the key in credential activation (see Device::make_credential).

pub fn export_public(&self, pem: bool) -> Result<Vec<u8>>

Export this key’s public part. pem selects PEM, otherwise DER (ASN.1).

impl<'d> Key<'d>

pub fn rsa_encrypt(&self, msg: &[u8]) -> Result<Vec<u8>>

Encrypt msg to this key’s public part with RSA-OAEP.

pub fn rsa_decrypt(&self, ciphertext: &[u8]) -> Result<Secret>

Decrypt an RSA-OAEP ciphertext with this key’s private part.

pub fn rsa_encrypt_with_hash( &self, msg: &[u8], hash: HashAlg, ) -> Result<Vec<u8>>

Encrypt msg with RSA-OAEP using an explicit label-hash algorithm.

The plain rsa_encrypt uses the TPM’s default OAEP hash (SHA-256). This variant issues the low-level command directly so any hash the TPM supports can be selected, including HashAlg::Sha1, which Microsoft device enrollment (MS-OAPXBC) requires for its session-key wrap. SHA-1 is legacy and cryptographically weak; select it only for that interop, not for new designs.

pub fn rsa_decrypt_with_hash( &self, ciphertext: &[u8], hash: HashAlg, ) -> Result<Secret>

Decrypt an RSA-OAEP ciphertext using an explicit label-hash algorithm (see rsa_encrypt_with_hash). Supports HashAlg::Sha1 for Microsoft enrollment interop.

impl<'d> Key<'d>

pub fn sign_hash(&self, digest: &[u8]) -> Result<Vec<u8>>

Sign a pre-computed digest with this key, returning the raw signature.

The scheme/hash come from the key’s template (e.g. ECDSA-SHA256 for a P-256 signing key), so digest must be the matching hash length.

Examples found in repository

examples/full_flow.rs (line 38)

fn main() -> Result<(), wolftpm::TpmError> {
    let dev = Device::open()?;
    println!("device            connected to TPM");

    let mut nonce = [0u8; 16];
    dev.get_random(&mut nonce)?;
    println!("get_random        {}", hex(&nonce));

    let srk = dev.create_primary(Hierarchy::Owner, KeyAlg::EccP256, None)?;
    println!("create_primary    ECC SRK handle 0x{:08x}", srk.handle());

    let signer = dev.create_and_load(&srk, &Template::signing(KeyAlg::EccP256)?, None)?;
    println!(
        "create_and_load   signing key handle 0x{:08x}",
        signer.handle()
    );

    let digest = [0x11u8; 32];
    let sig = signer.sign_hash(&digest)?;
    signer.verify_hash(&digest, &sig)?;
    println!("sign/verify       {} byte signature, verified", sig.len());

    let sealed = dev.seal(&srk, b"my secret", None)?;
    let secret = dev.unseal(sealed, &srk, None)?;
    println!(
        "seal/unseal       recovered \"{}\"",
        core::str::from_utf8(&secret).unwrap_or("<bytes>")
    );

    // Scope the reloaded key so its handle is freed before the attestation
    // step below. A TPM only holds a few transient objects at once (often 3),
    // so keep the number of simultaneously-loaded keys small.
    {
        let blob = dev.create_key(&srk, &Template::signing(KeyAlg::EccP256)?, None)?;
        let bytes = blob.to_bytes()?;
        let restored = KeyBlob::from_bytes(&dev, &bytes)?;
        let loaded = restored.load(&srk, None)?;
        println!(
            "key blob          {} bytes, reloaded as handle 0x{:08x}",
            bytes.len(),
            loaded.handle()
        );
    }

    let before = dev.pcr_read(16, HashAlg::Sha256)?;
    dev.pcr_extend(16, HashAlg::Sha256, &[0xAB; 32])?;
    let after = dev.pcr_read(16, HashAlg::Sha256)?;
    println!(
        "pcr read/extend   PCR16 {}.. -> {}..",
        hex(&before[..6]),
        hex(&after[..6])
    );

    let index = 0x0150_0100;
    let _ = dev.nv_delete(index);
    let mut slot = dev.nv_create(index, 32, None)?;
    dev.nv_write(&mut slot, b"metadata", 0)?;
    let mut buf = [0u8; 32];
    let n = dev.nv_read(&mut slot, &mut buf, 0)?;
    dev.nv_delete(index)?;
    println!("nv define/rw      {} bytes at index 0x{:08x}", n, index);

    let aik = dev.create_and_load(&srk, &Template::attestation(KeyAlg::EccP256)?, None)?;
    let att = dev.certify(&signer, &aik, &nonce)?;
    println!("certify           {} byte attestation", att.attest.len());

    println!("done              all operations succeeded");
    Ok(())
}

pub fn verify_hash(&self, digest: &[u8], sig: &[u8]) -> Result<()>

Verify sig over digest with this key.

Examples found in repository

examples/full_flow.rs (line 39)

fn main() -> Result<(), wolftpm::TpmError> {
    let dev = Device::open()?;
    println!("device            connected to TPM");

    let mut nonce = [0u8; 16];
    dev.get_random(&mut nonce)?;
    println!("get_random        {}", hex(&nonce));

    let srk = dev.create_primary(Hierarchy::Owner, KeyAlg::EccP256, None)?;
    println!("create_primary    ECC SRK handle 0x{:08x}", srk.handle());

    let signer = dev.create_and_load(&srk, &Template::signing(KeyAlg::EccP256)?, None)?;
    println!(
        "create_and_load   signing key handle 0x{:08x}",
        signer.handle()
    );

    let digest = [0x11u8; 32];
    let sig = signer.sign_hash(&digest)?;
    signer.verify_hash(&digest, &sig)?;
    println!("sign/verify       {} byte signature, verified", sig.len());

    let sealed = dev.seal(&srk, b"my secret", None)?;
    let secret = dev.unseal(sealed, &srk, None)?;
    println!(
        "seal/unseal       recovered \"{}\"",
        core::str::from_utf8(&secret).unwrap_or("<bytes>")
    );

    // Scope the reloaded key so its handle is freed before the attestation
    // step below. A TPM only holds a few transient objects at once (often 3),
    // so keep the number of simultaneously-loaded keys small.
    {
        let blob = dev.create_key(&srk, &Template::signing(KeyAlg::EccP256)?, None)?;
        let bytes = blob.to_bytes()?;
        let restored = KeyBlob::from_bytes(&dev, &bytes)?;
        let loaded = restored.load(&srk, None)?;
        println!(
            "key blob          {} bytes, reloaded as handle 0x{:08x}",
            bytes.len(),
            loaded.handle()
        );
    }

    let before = dev.pcr_read(16, HashAlg::Sha256)?;
    dev.pcr_extend(16, HashAlg::Sha256, &[0xAB; 32])?;
    let after = dev.pcr_read(16, HashAlg::Sha256)?;
    println!(
        "pcr read/extend   PCR16 {}.. -> {}..",
        hex(&before[..6]),
        hex(&after[..6])
    );

    let index = 0x0150_0100;
    let _ = dev.nv_delete(index);
    let mut slot = dev.nv_create(index, 32, None)?;
    dev.nv_write(&mut slot, b"metadata", 0)?;
    let mut buf = [0u8; 32];
    let n = dev.nv_read(&mut slot, &mut buf, 0)?;
    dev.nv_delete(index)?;
    println!("nv define/rw      {} bytes at index 0x{:08x}", n, index);

    let aik = dev.create_and_load(&srk, &Template::attestation(KeyAlg::EccP256)?, None)?;
    let att = dev.certify(&signer, &aik, &nonce)?;
    println!("certify           {} byte attestation", att.attest.len());

    println!("done              all operations succeeded");
    Ok(())
}

impl<'d> Key<'d>

pub fn aes_encrypt(&self, data: &[u8], iv: &[u8]) -> Result<Vec<u8>>

Encrypt data with this loaded AES key (see Template::symmetric). iv is the CFB initialization vector (16 bytes for AES).

pub fn aes_decrypt(&self, data: &[u8], iv: &[u8]) -> Result<Secret>

Decrypt data produced by aes_encrypt with the same key and iv. The recovered plaintext is returned in a zeroizing Secret.

Trait Implementations

impl<'d> Drop for Key<'d>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.