admin library
The admin side of the Tom Secrets Manager's local protocol (protocol.md
6): the admin client with its mutual challenge and claim, the runtime
directory, starting the service with its admin-key handover, and where the
product keeps its data. Used by the manager app, tsm and the service
itself; a client that only reads secrets needs none of it.
Classes
- TomSecretsAdminClient
- An authenticated admin connection.
- TomSecretsAdminKeyring
-
The admin keys in a keychain reached through
read,writeanddelete(the keychain's own operations; their failures pass through). - TomSecretsAlreadyStarted
-
A service was already running: attach to it (with the key held, or by
claim). - TomSecretsBrowserHosts
- The host's manifests of this user: installed, removed, checked.
- TomSecretsBrowserHostState
- Where the host stands for one browser.
- TomSecretsHandover
- The handover line the service reads from its standard input.
- TomSecretsIntegrations
- The integrations of one user on this machine.
- TomSecretsIntegrationState
- Where an integration stands.
- TomSecretsPairingHandover
- The pairing mode's handover line.
- TomSecretsPairingReport
- What a pairing gave, as the pairing mode reports it (no key, no token).
- TomSecretsRegExe
-
TomSecretsRegistry through Windows' own
reg.exe. - TomSecretsRegistry
-
The Windows registry, as far as the manifests need it (
HKCUkeys and their default value). - TomSecretsRuntime
- The runtime directory of this OS user.
- TomSecretsServicePairing
- A conversation with the service in its pairing mode.
- TomSecretsStarted
- A new service runs with adminKey.
- TomSecretsStartFailed
- The service could not start, for code.
- TomSecretsStartResult
- What a start found.
- TomSecretsUnlockBundle
- The key material of one vault's OS unlock: its compositeKey and, for a vault with the outer encryption, its outerKey (the repository key as the keychain keeps it).
Enums
- TomSecretsBrowser
- A browser the host can be installed for.
- TomSecretsIntegration
- An integration of a developer tool.
- TomSecretsTransport
- How the endpoints are offered: Unix domain sockets (Linux, macOS) or localhost TCP ports with a client token (Windows).
Constants
- tomSecretsAdminKeyIndexHandle → const String
- The handle of the index of the starts whose admin key is kept: their start times, comma-separated.
- tomSecretsAdminLabel → const String
- The admin's label.
- tomSecretsAppExecutable → const String
-
The manager app's executable name, without
.exe. - tomSecretsBlockBegin → const String
- The first line of a block the product writes.
- tomSecretsBlockEnd → const String
- The last line of a block the product writes.
- tomSecretsBrowserHostId → const String
-
The native-messaging host's name (the manifest's
name, its file name and the Windows registry key). - tomSecretsBundleInfo → const String
- The HKDF info of the bundle key.
- tomSecretsBundleNonceBytes → const int
- The length of a bundle's nonce.
- tomSecretsChromiumDevelopmentId → const String
-
The Chromium development build's extension id (the first 32 hex digits of
the SHA-256 of tomSecretsChromiumDevelopmentKey, each mapped to
a–p). - tomSecretsChromiumDevelopmentKey → const String
-
The public key of the Chromium development build (the extension
manifest's
key, base64 of its SubjectPublicKeyInfo), which fixes its id to tomSecretsChromiumDevelopmentId; its private key is not kept (an unpacked build needs none). -
tomSecretsChromiumExtensionIds
→ const List<
String> - The Chromium extension ids the host serves and the manifests allow: the development build's; the Chrome Web Store's and Edge Add-ons' ids join when the extension is published there (part-browser, Publishing).
- tomSecretsCompositeKeyBytes → const int
- The length of a composite key.
- tomSecretsFirefoxExtensionId → const String
-
The Firefox extension's id (
browser_specific_settings.gecko.id). - tomSecretsKeyBytes → const int
- The length of an admin key and of a nonce.
- tomSecretsKeychainService → const String
- The service name of the product's items in the OS keychain.
- tomSecretsPairingPasswordTries → const int
- How many master passwords the pairing mode takes.
- tomSecretsPairingWrongPassword → const String
- The code of a wrong master password; another may be sent.
- tomSecretsServiceExecutable → const String
-
The service's executable name, without
.exe. - tomSecretsServiceLabel → const String
- The service's label.
- tomSecretsToolsFolder → const String
- The folder of the distribution holding the command-line tools.
Properties
-
tomSecretsChromiumExtensionOrigins
→ List<
String> -
The origins of tomSecretsChromiumExtensionIds (
allowed_origins).no setter
Functions
-
tomSecretsAdminKeyHandle(
int serviceStart) → String -
The handle of the admin key of the service started at
serviceStart(service.json'sstart, milliseconds since the epoch): the app andtsmkeep the key there between invocations; a new start has a new key. -
tomSecretsApprovalLinkProblem(
String text, {bool anyPort = false}) → String? -
Why
textcannot be the device settingapprovalLink(the address the approval link listens on, protocol.md 9.7), or null:host:port, an IPv6 address in brackets ([fd00::1]:47731), a port 1–65535 (withanyPortalso 0, the system picks one), and never every interface (0.0.0.0,::): the link listens on a VPN or LAN address only. -
tomSecretsAuthDelay(
int failures) → Duration -
The delay before the next authentication after
failuresfailed ones: 0, then 1 s, 2 s, 4 s … up to 60 s (protocol.md 6.1). -
tomSecretsBlockOf(
String text) → List< String> ? -
The lines between the marks of
text's block, or null when it has none. -
tomSecretsBootstrapPath(
{Map< String, String> ? environment, String? operatingSystem}) → String -
The default bootstrap file:
bootstrap.yamlin tomSecretsDataDirectory. -
tomSecretsBrowserHostBeside(
String serviceExecutable, {required String operatingSystem}) → String -
The browser host
tsm-browser-hostbeside the service whose executable isserviceExecutable(where the service recognises it, protocol.md 5.5, and where the distribution carries it). -
tomSecretsBundleAad(
String vault, int serviceStart) → Uint8List -
The associated data of
vault's bundle: its name's UTF-8 bytes andserviceStartas 8 bytes big-endian. -
tomSecretsBundleKey(
List< int> adminKey, List<int> serviceNonce, List<int> adminNonce) → Uint8List -
The bundle key of one admin connection:
HKDF-SHA256(adminKey, salt = serviceNonce || adminNonce, info = "tsm-bundle-v1"), 32 bytes. -
tomSecretsChallengeInput(
String label, List< int> serviceNonce, List<int> adminNonce, int serviceStart) → Uint8List -
The MAC input:
label's ASCII, both nonces,serviceStartas 8 bytes big-endian. -
tomSecretsChallengeMac(
List< int> adminKey, String label, List<int> serviceNonce, List<int> adminNonce, int serviceStart) → Uint8List -
The MAC of
labelover the challenge underadminKey. -
tomSecretsConstantTimeEquals(
List< int> a, List<int> b) → bool -
Whether
aequalsb, in time independent of where they differ. -
tomSecretsDataDirectory(
{Map< String, String> ? environment, String? operatingSystem}) → String -
The data directory:
TSM_DATA_DIRwhen set; on macOS~/Library/Application Support/TomSecretsManager; on Windows%LOCALAPPDATA%\TomSecretsManager(the runtime directory is itsrun\); elsewhere$XDG_DATA_HOME/tom-secrets-manager, else~/.local/share/tom-secrets-manager.environmentandoperatingSystemdefault to this process's. -
tomSecretsDistributionApp(
String serviceDirectory, {required String operatingSystem}) → String -
The app of the distribution around a service whose executable is in
serviceDirectory(…/tsm/bin): the path its executable has when the service is the distribution's, which the service admits as an admin besidestsmand the app beside itself. -
tomSecretsOpenBundle(
{required List< int> bundleKey, required String vault, required int serviceStart, required Map<String, Object?> bundle}) → Future<Uint8List> -
Opens the
bundleobject ofunlockforvault: the plaintext bytes, which the caller wipes after use. Throws TomSecretsBundleException when it is malformed or does not open (another key, vault or service start). -
tomSecretsRandomBytes(
[int count = tomSecretsKeyBytes]) → Uint8List -
countbytes from the OS's secure generator. -
tomSecretsSealBundle(
{required List< int> bundleKey, required String vault, required int serviceStart, required List<int> plaintext, List<int> ? nonce}) → Future<Map< String, String> > -
Seals
plaintextforvaultunderbundleKey: thebundleobject ofunlock(nonce,ciphertextwith the tag, both base64).nonceis random unless given (test vectors). -
tomSecretsServiceCandidates(
String appDirectory, {required String operatingSystem}) → List< String> -
Where the app whose executable is in
appDirectorylooks for the service, in order: beside itself (a development build, or a fleet install), then in its distribution's tools folder (operatingSystemasPlatform.operatingSystemnames it). -
tomSecretsStartService(
{required String executable, List< String> arguments = const [], required String bootstrap, Map<String, String> ? environment, Duration timeout = const Duration(seconds: 60)}) → Future<TomSecretsStartResult> -
Starts the service
executable(witharguments) forbootstrap, detached; waits up totimeoutfor its answer line. -
tomSecretsWithBlock(
String text, List< String> ? block, {bool atTop = false}) → String -
textwith its block's lines replaced byblock(marks added), or the block removed whenblockis null. A new block goes at the top whenatTop, else at the end; an existing one stays where it is. Every line outside the block is kept as it was (line ends astexthas them).
Typedefs
- TomSecretsPairedVault = ({String locator, String name, bool primary})
- One vault a pairing gave, as the pairing mode reports it.
Exceptions / Errors
- TomSecretsAdminException
- The admin endpoint refused or broke the conversation.
- TomSecretsAlreadyRunning
- Another service already holds the lock: the starter attaches to it.
- TomSecretsBundleException
- A sealed bundle did not open, or its plaintext is no bundle. Carries no key material.
- TomSecretsPairingModeException
- The pairing mode answered an error.
- TomSecretsRuntimeException
- A runtime directory that is not the user's alone, or cannot be made.