Class VaultIdentity
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.cryptoin 1.0.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intThe longest challengesignChallenge(byte[])signs.static final intThe shortest challengesignChallenge(byte[])signs. -
Method Summary
Modifier and TypeMethodDescriptionstatic VaultIdentitycreate(char[] passphrase) Creates a brand-new identity from fresh key pairs, sealed underpassphrase.export()Returns the stored, passphrase-protected form of this identity for persistence or upload.Returns the key fingerprint of this member (AVP SPEC 3.2),xxxx-xxxx-xxxx-xxxx: what an owner compares withInviteToken.fingerprint()and the roster shows asVaultMember.fingerprint().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 Ed25519 identity public key — this member's stable identity.Returns the X25519 public key, to which other members wrap repository data keys for this member.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.static VaultIdentityunlock(WrappedIdentity stored, char[] passphrase) Unlocks a stored identity with its passphrase.static VaultIdentityunlockWithRecovery(WrappedIdentity stored, String recoveryCode) Restores a stored identity from its offline recovery code, bypassing the passphrase.withRecovery(String recoveryCode) Returns a copy of this identity's stored form with an offline recovery sealing added (or replaced) underrecoveryCode.
-
Field Details
-
MIN_CHALLENGE_BYTES
public static final int MIN_CHALLENGE_BYTESThe shortest challengesignChallenge(byte[])signs.- Since:
- 1.0.0
- See Also:
-
MAX_CHALLENGE_BYTES
public static final int MAX_CHALLENGE_BYTESThe longest challengesignChallenge(byte[])signs.- Since:
- 1.0.0
- See Also:
-
-
Method Details
-
create
Creates a brand-new identity from fresh key pairs, sealed underpassphrase.- Parameters:
passphrase- the passphrase protecting the private material- Returns:
- the unlocked identity
- Throws:
AltsException- of kindAltsFailure.Kind.INVALID_INPUTifpassphraseis null, and of kindAltsFailure.Kind.CRYPTOif key generation or sealing fails- Since:
- 0.2.0
-
unlock
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 identitypassphrase- the passphrase used at creation- Returns:
- the unlocked identity
- Throws:
AltsException- of kindAltsFailure.Kind.CRYPTOif the passphrase is wrong, the sealing was tampered with, or the record's public keys do not match the private material, and of kindAltsFailure.Kind.INVALID_INPUTif the record is malformed or its iteration count out of range, orpassphraseis null- Since:
- 0.2.0
-
unlockWithRecovery
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 kindAltsFailure.Kind.CRYPTOif the code is wrong, the sealing was tampered with, or the record's public keys do not match the private material, and of kindAltsFailure.Kind.INVALID_INPUTif the record carries no recovery sealing or is malformed- Since:
- 0.2.0
-
withRecovery
Returns a copy of this identity's stored form with an offline recovery sealing added (or replaced) underrecoveryCode. Persist the returned record; the live identity is unchanged.- Parameters:
recoveryCode- the recovery code (seeRecoveryCode.newCode())- Returns:
- the stored form including the recovery sealing
- Throws:
AltsException- of kindAltsFailure.Kind.CRYPTOif sealing fails- Since:
- 0.2.0
-
export
Returns the stored, passphrase-protected form of this identity for persistence or upload.- Returns:
- the wrapped identity
- Since:
- 0.2.0
-
identityPublicKey
Returns the Ed25519 identity public key — this member's stable identity.- Returns:
- the identity public key
- Since:
- 0.2.0
-
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 kindAltsFailure.Kind.CRYPTOif the key cannot be encoded- Since:
- 0.2.0
-
fingerprint
Returns the key fingerprint of this member (AVP SPEC 3.2),xxxx-xxxx-xxxx-xxxx: what an owner compares withInviteToken.fingerprint()and the roster shows asVaultMember.fingerprint().- Returns:
- the fingerprint
- Throws:
AltsException- of kindAltsFailure.Kind.CRYPTOif a key cannot be encoded- Since:
- 1.0.0
-
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 forLegacyVaultReader.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 kindAltsFailure.Kind.INVALID_INPUTif the input is refused; nothing is signed. Of kindAltsFailure.Kind.CRYPTOif signing fails- Since:
- 0.2.0
-