Skip to main content
In MLS, a KeyPackage is a signed object that binds a client’s identity credential to its HPKE public key. Another group member fetches a target client’s key package from the Delivery Service and includes it in an Add proposal or commit, which delivers the Welcome message encrypted to that key. Key packages are inherently single-use: once consumed in a Welcome, the private key material is deleted. CoreCrypto manages the generation, storage, and cleanup lifecycle automatically.

​
Constants

​
KEYPACKAGE_DEFAULT_LIFETIME

pub const KEYPACKAGE_DEFAULT_LIFETIME: Duration =
    Duration::from_secs(60 * 60 * 24 * 28 * 3); // ~3 months
The default expiry span applied to all generated key packages when no explicit lifetime is provided. Matches the OpenMLS internal limit.

​
Types

​
Keypackage

// re-export of openmls::prelude::KeyPackage
pub use openmls::prelude::KeyPackage as Keypackage;
The full key package object including the leaf node, extensions, signature, and HPKE init key. Implements the KeypackageExt trait for CoreCrypto-specific helpers.

​
KeypackageRef

A lightweight reference to a Keypackage. Contains the hash reference and associated metadata without holding the full key material. 
pub struct KeypackageRef {
    hash_ref: KpHashRef,      // opaque hash bytes
    ciphersuite: Ciphersuite,
    credential_type: CredentialType,
    lifetime: Option<Lifetime>,
}
Methods
MethodReturn typeDescription
hash_ref()&[u8]Raw bytes of the hash reference
ciphersuite()CiphersuiteCiphersuite of the originating key package
signature_scheme()SignatureSchemeDerived from the ciphersuite
credential_type()CredentialTypeBasic or X509
lifetime()Option<&Lifetime>Expiry window, if present
is_valid()booltrue if the lifetime has not expired

​
TransactionContext methods

​
generate_keypackage

pub async fn generate_keypackage(
    &self,
    credential_ref: &CredentialRef,
    lifetime: Option<Duration>,
) -> Result<Keypackage>
Generates a new KeyPackage from the referenced credential. The key package is persisted to the keystore along with its HPKE private key and encryption keypair. No pruning of existing key packages is performed.
​
credential_ref
&CredentialRef
required
Reference to the credential to embed in the key package leaf node. Must belong to the current session.
​
lifetime
Option<Duration>
Explicit validity window. If None, KEYPACKAGE_DEFAULT_LIFETIME (~3 months) is used.
​
Keypackage
Keypackage
The generated key package, ready to be uploaded to the Delivery Service.
Example 
use std::time::Duration;

let tx = cc.new_transaction().await?;
// generate with default lifetime
let kp = tx.generate_keypackage(&credential_ref, None).await?;
// generate with custom 30-day lifetime
let kp_30d = tx.generate_keypackage(
    &credential_ref,
    Some(Duration::from_secs(60 * 60 * 24 * 30)),
).await?;
tx.finish().await?;

​
get_keypackage_refs

pub async fn get_keypackage_refs(&self) -> Result<Vec<KeypackageRef>>
Returns KeypackageRefs for all key packages currently stored in the keystore for this session. Use is_valid() on each ref to filter out expired ones.
​
Vec<KeypackageRef>
Vec<KeypackageRef>
All stored key package references.
Example 
let tx = cc.new_transaction().await?;
let refs = tx.get_keypackage_refs().await?;
let valid_count = refs.iter().filter(|r| r.is_valid()).count();
println!("{valid_count} valid key packages available");
tx.finish().await?;

​
remove_keypackage

pub async fn remove_keypackage(
    &self,
    kp_ref: &KeypackageRef,
) -> Result<()>
Deletes a single key package and its associated private key material from the keystore. Succeeds silently if the key package no longer exists. Removes from three tables: the key package, the HPKE private key, and the leaf encryption keypair.
​
kp_ref
&KeypackageRef
required
Reference to the key package to remove.
Example 
let tx = cc.new_transaction().await?;
for kp_ref in tx.get_keypackage_refs().await? {
    if !kp_ref.is_valid() {
        tx.remove_keypackage(&kp_ref).await?;
    }
}
tx.finish().await?;

​
remove_keypackages_for

pub async fn remove_keypackages_for(
    &self,
    credential_ref: &CredentialRef,
) -> Result<()>
Removes all key packages that were generated from the given credential. This is an expensive operation as it loads all key packages to find matches. Called automatically by remove_credential.
​
credential_ref
&CredentialRef
required
The credential whose key packages should be purged.

​
Lifecycle summary

 generate_keypackage()      → uploaded to DS
                            ↓
                 another member fetches it
                            ↓
                 included in Add commit → Welcome sent
                            ↓
            CoreCrypto deletes key package on merge
Manually delete stale key packages (expired lifetime) with remove_keypackage. Replace a credential by generating new key packages and removing the old ones with remove_keypackages_for.

Build docs developers (and LLMs) love

Get started for freeTalk to us