Documentation
¶
Overview ¶
Package usernames implements Signal username validation and username links.
It is a pure-Go port of the non-zk parts of upstream libsignal rust/usernames at v0.96.4. Username proof APIs require the upstream poksho proof stack and are intentionally not exposed here yet.
Index ¶
- Constants
- Variables
- func CandidatesFrom(nickname string, limits NicknameLimits) ([]string, error)
- func CandidatesFromReader(r io.Reader, nickname string, limits NicknameLimits) ([]string, error)
- func DecryptUsername(entropy [LinkEntropySize]byte, encryptedUsername []byte) (string, error)
- func HashHex(username string) (string, error)
- type HashCandidate
- type Link
- type NicknameLimits
- type Username
- type UsernameHash
Constants ¶
const (
// LinkEntropySize is the byte length of username-link entropy.
LinkEntropySize = 32
)
Variables ¶
var ( // ErrMissingSeparator reports a username without a "." separator. ErrMissingSeparator = errors.New("username must contain a separator") // ErrNicknameCannotBeEmpty reports an empty username nickname. ErrNicknameCannotBeEmpty = errors.New("nickname cannot be empty") // ErrNicknameCannotStartWithDigit reports a nickname beginning with a digit. ErrNicknameCannotStartWithDigit = errors.New("nickname cannot start with digit") // ErrBadNicknameCharacter reports a nickname containing a disallowed character. ErrBadNicknameCharacter = errors.New("bad nickname character") // ErrNicknameTooShort reports a nickname below the configured soft minimum. ErrNicknameTooShort = errors.New("nickname too short") // ErrNicknameTooLong reports a nickname above the configured soft or hard maximum. ErrNicknameTooLong = errors.New("nickname too long") // ErrDiscriminatorCannotBeEmpty reports an empty discriminator. ErrDiscriminatorCannotBeEmpty = errors.New("discriminator cannot be empty") // ErrDiscriminatorCannotBeZero reports a zero discriminator. ErrDiscriminatorCannotBeZero = errors.New("discriminator cannot be zero") // ErrDiscriminatorCannotBeSingleDigit reports a single-digit discriminator. ErrDiscriminatorCannotBeSingleDigit = errors.New("discriminator cannot be a single digit") // ErrDiscriminatorCannotHaveLeadingZeros reports a multi-digit discriminator with leading zeros. ErrDiscriminatorCannotHaveLeadingZeros = errors.New("discriminator cannot have leading zeros") // ErrBadDiscriminatorCharacter reports a discriminator containing non-digits. ErrBadDiscriminatorCharacter = errors.New("bad discriminator character") // ErrDiscriminatorTooLarge reports a discriminator too large for uint64. ErrDiscriminatorTooLarge = errors.New("discriminator too large") // ErrInputDataTooLong reports username-link plaintext that exceeds Signal's four-block bound. ErrInputDataTooLong = errors.New("username link input data too long") // ErrInvalidEntropyDataLength reports entropy that is not LinkEntropySize bytes. ErrInvalidEntropyDataLength = errors.New("invalid username link entropy length") // ErrUsernameLinkDataTooShort reports encrypted username-link data missing IV/ciphertext/HMAC. ErrUsernameLinkDataTooShort = errors.New("username link data too short") // ErrHMACMismatch reports a username-link authentication failure. ErrHMACMismatch = errors.New("username link hmac mismatch") // ErrBadCiphertext reports username-link ciphertext that fails AES-CBC decryption. ErrBadCiphertext = errors.New("bad username link ciphertext") // ErrInvalidDecryptedDataStructure reports username-link plaintext that is not valid UsernameData. ErrInvalidDecryptedDataStructure = errors.New("invalid username link decrypted data") )
Functions ¶
func CandidatesFrom ¶
func CandidatesFrom(nickname string, limits NicknameLimits) ([]string, error)
CandidatesFrom returns randomized candidate usernames for nickname.
func CandidatesFromReader ¶
CandidatesFromReader returns randomized candidate usernames for nickname using r.
func DecryptUsername ¶
func DecryptUsername(entropy [LinkEntropySize]byte, encryptedUsername []byte) (string, error)
DecryptUsername decrypts encryptedUsername with entropy and returns the username.
Types ¶
type HashCandidate ¶ added in v0.7.0
type HashCandidate struct {
Username string
Hash UsernameHash
HashHex string
}
HashCandidate pairs a candidate username with its reservation hash.
func CandidatesWithHashes ¶ added in v0.7.0
func CandidatesWithHashes(nickname string, limits NicknameLimits) ([]HashCandidate, error)
CandidatesWithHashes returns randomized candidate usernames and their reservation hashes for nickname.
func CandidatesWithHashesFromReader ¶ added in v0.7.0
func CandidatesWithHashesFromReader(r io.Reader, nickname string, limits NicknameLimits) ([]HashCandidate, error)
CandidatesWithHashesFromReader returns randomized candidate usernames and their reservation hashes using r.
type Link ¶
type Link struct {
Entropy [LinkEntropySize]byte
EncryptedUsername []byte
}
Link contains a username-link entropy/ciphertext pair.
func CreateLink ¶
func CreateLink(username string, entropy *[LinkEntropySize]byte) (Link, error)
CreateLink creates an encrypted username link using crypto/rand.
func CreateLinkFromReader ¶
func CreateLinkFromReader(r io.Reader, username string, entropy *[LinkEntropySize]byte) (Link, error)
CreateLinkFromReader creates an encrypted username link using r for entropy and IV bytes.
func ParseLinkBuffer ¶
ParseLinkBuffer parses the bridge-compatible entropy||encrypted_username form.
type NicknameLimits ¶
NicknameLimits defines the soft nickname length bounds for validation.
func DefaultNicknameLimits ¶
func DefaultNicknameLimits() NicknameLimits
DefaultNicknameLimits returns Signal's default 3..32 nickname limits.
func NewNicknameLimits ¶
func NewNicknameLimits(minLen, maxLen int) NicknameLimits
NewNicknameLimits constructs nickname limits, panicking for invalid bounds.
func (NicknameLimits) Validate ¶
func (l NicknameLimits) Validate(n int) error
Validate checks n against the configured nickname length bounds.
type Username ¶
type Username struct {
// contains filtered or unexported fields
}
Username is a parsed Signal username.
func FromParts ¶
func FromParts(nickname, discriminator string, limits NicknameLimits) (Username, error)
FromParts validates and parses a nickname/discriminator pair.
func (Username) Discriminator ¶
Discriminator returns the numeric username discriminator.
func (Username) Hash ¶ added in v0.7.0
func (u Username) Hash() (UsernameHash, error)
Hash computes Signal's username reservation hash for a parsed username.
This is an alias for ReserveHash. It does not create or verify username proofs.
func (Username) ReserveHash ¶ added in v0.6.0
func (u Username) ReserveHash() (UsernameHash, error)
ReserveHash computes Signal's username reservation hash for a parsed username.
type UsernameHash ¶ added in v0.6.0
type UsernameHash [32]byte
UsernameHash is the 32-byte compressed Ristretto username hash used by username reservation APIs.
func Hash ¶ added in v0.7.0
func Hash(username string) (UsernameHash, error)
Hash computes Signal's username reservation hash for username.
This is an alias for ReserveUsernameHash. It does not create or verify username proofs.
func HashFromParts ¶ added in v0.7.0
func HashFromParts(nickname string, discriminator uint64) (UsernameHash, error)
HashFromParts computes Signal's username reservation hash for a nickname/discriminator pair.
The discriminator is numeric, so this accepts discriminator 1 as the same value represented by username strings such as "name.01".
func ReserveUsernameHash ¶ added in v0.6.0
func ReserveUsernameHash(username string) (UsernameHash, error)
ReserveUsernameHash computes Signal's username reservation hash for username.
The hash is vector-backed against upstream rust/usernames at v0.96.4. This API does not create or verify username proofs.
func (UsernameHash) Bytes ¶ added in v0.6.0
func (h UsernameHash) Bytes() [32]byte
Bytes returns the fixed-width hash bytes.
func (UsernameHash) String ¶ added in v0.6.0
func (h UsernameHash) String() string
String returns the lower-case hexadecimal hash.