Class VaultIdentity

java.lang.Object
lol.trq.alts.vault.VaultIdentity

public final class VaultIdentity extends Object
A member's cryptographic identity: an Ed25519 key pair (the member key, which signs the member's AVP 0.5 commits and leave requests and authenticates it to hosts) plus an X25519 key pair (used only to unwrap repository data keys wrapped to this member). Both private keys are held in memory only while unlocked. Every failure is an AltsException: INVALID_INPUT for a stored record that is malformed, CRYPTO for a wrong passphrase or recovery code, a tampered record, or a key operation that fails.

The two private keys are concatenated into 64 bytes of "private material" and sealed under a passphrase-derived master key for storage as a WrappedIdentity. There is no account: the Ed25519 public key is the identity. Optionally a second sealing under an offline recovery code can be attached so the identity survives a forgotten passphrase, without any server-side escrow.

Since:
0.2.0, moved from lol.trq.alts.crypto in 1.0.0
  • Field Details

  • Method Details

    • create

      public static VaultIdentity create(char[] passphrase)
      Creates a brand-new identity from fresh key pairs, sealed under passphrase.
      Parameters:
      passphrase - the passphrase protecting the private material
      Returns:
      the unlocked identity
      Throws:
      AltsException - of kind AltsFailure.Kind.INVALID_INPUT if passphrase is null, and of kind AltsFailure.Kind.CRYPTO if key generation or sealing fails
      Since:
      0.2.0
    • unlock

      public static VaultIdentity unlock(WrappedIdentity stored, char[] passphrase)
      Unlocks a stored identity with its passphrase.

      The stored record is treated as untrusted: its iteration count must lie between 10,000 and 10,000,000 (PBKDF2-HMAC-SHA256), and the public keys it names must be the ones that belong to the unsealed private keys. A record whose public keys were swapped after sealing, so that peers would wrap repository keys to someone else, is rejected.

      Parameters:
      stored - the stored identity
      passphrase - the passphrase used at creation
      Returns:
      the unlocked identity
      Throws:
      AltsException - of kind AltsFailure.Kind.CRYPTO if the passphrase is wrong, the sealing was tampered with, or the record's public keys do not match the private material, and of kind AltsFailure.Kind.INVALID_INPUT if the record is malformed or its iteration count out of range, or passphrase is null
      Since:
      0.2.0
    • unlockWithRecovery

      public static VaultIdentity unlockWithRecovery(WrappedIdentity stored, String recoveryCode)
      Restores a stored identity from its offline recovery code, bypassing the passphrase.
      Parameters:
      stored - the stored identity (must carry a recovery sealing)
      recoveryCode - the recovery code shown at recovery setup
      Returns:
      the unlocked identity
      Throws:
      AltsException - of kind AltsFailure.Kind.CRYPTO if the code is wrong, the sealing was tampered with, or the record's public keys do not match the private material, and of kind AltsFailure.Kind.INVALID_INPUT if the record carries no recovery sealing or is malformed
      Since:
      0.2.0
    • withRecovery

      public WrappedIdentity withRecovery(String recoveryCode)
      Returns a copy of this identity's stored form with an offline recovery sealing added (or replaced) under recoveryCode. Persist the returned record; the live identity is unchanged.
      Parameters:
      recoveryCode - the recovery code (see RecoveryCode.newCode())
      Returns:
      the stored form including the recovery sealing
      Throws:
      AltsException - of kind AltsFailure.Kind.CRYPTO if sealing fails
      Since:
      0.2.0
    • export

      public WrappedIdentity export()
      Returns the stored, passphrase-protected form of this identity for persistence or upload.
      Returns:
      the wrapped identity
      Since:
      0.2.0
    • identityPublicKey

      public PublicKey identityPublicKey()
      Returns the Ed25519 identity public key — this member's stable identity.
      Returns:
      the identity public key
      Since:
      0.2.0
    • identityId

      public String identityId()
      Returns the raw 32-byte Ed25519 identity public key, Base64-encoded — the member id used on the wire and to key membership server-side.
      Returns:
      the Base64 identity public key
      Throws:
      AltsException - of kind AltsFailure.Kind.CRYPTO if the key cannot be encoded
      Since:
      0.2.0
    • fingerprint

      public String fingerprint()
      Returns the key fingerprint of this member (AVP SPEC 3.2), xxxx-xxxx-xxxx-xxxx: what an owner compares with InviteToken.fingerprint() and the roster shows as VaultMember.fingerprint().
      Returns:
      the fingerprint
      Throws:
      AltsException - of kind AltsFailure.Kind.CRYPTO if a key cannot be encoded
      Since:
      1.0.0
    • keyAgreementPublicKey

      public PublicKey keyAgreementPublicKey()
      Returns the X25519 public key, to which other members wrap repository data keys for this member.
      Returns:
      the key-agreement public key
      Since:
      0.2.0
    • signChallenge

      public byte[] signChallenge(byte[] nonce)
      Signs a challenge nonce from a 0.4 vault server with the Ed25519 identity key, as 0.4 authentication asks: over the raw nonce bytes. It exists so a host can still authenticate to its 0.4 server to fetch a repository's manifest and envelope for LegacyVaultReader.

      The same key is a 0.5 member key, and a 0.5 member signs only the canonical-encoding structures of AVP SPEC 4.1, never raw bytes a server chose. So that a server cannot pass one of those off as a nonce, this refuses, without signing, any input that begins with the ASCII bytes avp/ (every 0.5 canonical-encoding string begins with such a tag) or that is shorter than 16 or longer than 1024 bytes.

      Parameters:
      nonce - the challenge bytes
      Returns:
      the signature
      Throws:
      AltsException - of kind AltsFailure.Kind.INVALID_INPUT if the input is refused; nothing is signed. Of kind AltsFailure.Kind.CRYPTO if signing fails
      Since:
      0.2.0