# README
kbfsmd
Types and functions to work with KBFS blocks. The package is named
kbfsmd rather than md to avoid clashes with existing
variable names.
All errors returned by this package are wrapped with pkg/errors, and so need errors.Cause() to unwrap them.
# Functions
CheckRKBID returns an error if the ID of the given reader key bundle doesn't match the given one.
CheckWKBID returns an error if the ID of the given writer key bundle doesn't match the given one.
DecodeRootMetadata deserializes a metadata block into the specified versioned structure.
DecodeRootMetadataSigned deserializes a metadata block into the specified versioned structure.
DeserializeTLFReaderKeyBundleV3 deserializes a TLFReaderKeyBundleV3 from the given path and returns it.
DeserializeTLFWriterKeyBundleV3 deserializes a TLFWriterKeyBundleV3 from the given path and returns it.
DumpConfig returns the *spew.ConfigState used by DumpRootMetadata and related functions.
DumpExtraMetadata returns a detailed dump of the given ExtraMetadata's contents.
DumpRootMetadata returns a detailed dump of the given RootMetadata's contents.
EncodeRootMetadataSigned serializes a metadata block.
FakeBranchID creates a fake branch ID from the given byte.
FakeID returns an ID derived from the given byte, suitable for testing.
FakeInitialRekey fakes the initial rekey for the given RootMetadata.
GetEphemeralPublicKeyInfoV2 encapsulates all the ugly logic needed to deal with the "negative hack" from RootMetadataV2.UpdateKeyGeneration.
MakeID creates a new ID from the given RootMetadata object.
MakeInitialRootMetadata creates a new MutableRootMetadata instance of the given MetadataVer with revision RevisionInitial, and the given TLF ID and handle.
MakeInitialRootMetadataV2 creates a new RootMetadataV2 object with revision RevisionInitial, and the given TLF ID and handle.
MakeInitialRootMetadataV3 creates a new RootMetadataV3 object with revision RevisionInitial, and the given TLF ID and handle.
MakeMerkleHash hashes the given signed RootMetadata object.
MakeRandomBranchID generates a per-device branch ID using a CSPRNG.
MakeTLFReaderKeyBundleID hashes a TLFReaderKeyBundleV3 to create an ID.
MakeTLFWriterKeyBundleID hashes a TLFWriterKeyBundleV3 to create an ID.
NewExtraMetadataV3 creates a new ExtraMetadataV3 given a pair of key bundles.
NewKeyBundleCacheLRU constructs a new KeyBundleCacheStandard with LRU eviction strategy.
NewKeyBundleCacheRandom constructs a new KeyBundleCacheStandard with random eviction strategy.
ParseBranchID parses a hex encoded BranchID.
ParseID parses a hex encoded ID.
SignRootMetadata signs the given RootMetadata and returns a *RootMetadataSigned object.
TLFReaderKeyBundleIDFromBytes creates a new TLFReaderKeyBundleID from the given bytes.
TLFReaderKeyBundleIDFromString creates a new TLFReaderKeyBundleID from the given string.
TLFWriterKeyBundleIDFromBytes creates a new TLFWriterKeyBundleID from the given bytes.
TLFWriterKeyBundleIDFromString creates a new TLFWriterKeyBundleID from the given string.
# Constants
BranchIDByteLen is the number of bytes in a per-device per-TLF branch ID.
BranchIDStringLen is the number of characters in the string representation of a per-device per-TLF branch ID.
FirstValidKeyGen is the first value that is considered a valid key generation.
FirstValidMetadataVer is the first value that is considered a valid data version.
ImplicitTeamsVer is the first metadata version to allow private and public TLFs to be backed by implicit teams (and thus use service-provided encryption keys).
InitialExtraMetadataVer is the first metadata version that did include support for extra MD fields.
Merged means that the TLF is merged and no conflict resolution needs to be done.
MerkleRootVersion is the current Merkle root version.
Possible flags set in the MetadataFlags bitfield.
Possible flags set in the MetadataFlags bitfield.
Possible flags set in the WriterFlags bitfield.
Possible flags set in the MetadataFlags bitfield.
PreExtraMetadataVer is the latest metadata version that did not include support for extra MD fields.
PublicKeyGen is the value used for public TLFs.
ReaderEPubKeys means the ephemeral public key is in the writers array.
RevisionInitial is always the first revision for an initialized top-level folder.
RevisionUninitialized indicates that a top-level folder has not yet been initialized.
SegregatedKeyBundlesVer is the first metadata version to allow separate storage of key bundles.
24 hours.
ServerTokenServer is the expected server type for mdserver authentication.
StatusCodeServerError is the error code for a generic server error.
StatusCodeServerErrorBadRequest is the error code for a generic client error.
StatusCodeServerErrorCannotReadFinalizedTLF is the error code to indicate that a reader has requested to read a TLF ID that has been finalized, which isn't allowed.
StatusCodeServerErrorClassicTLFDoesNotExist is the error code returned by a MD get operation to indicate that a classic TLF is not found, and client has specified not to create one.
StatusCodeServerErrorConditionFailed is the error code to indicate the write condition failed.
StatusCodeServerErrorConflictDiskUsage is the error code for a disk usage conflict error.
StatusCodeServerErrorConflictFolderMapping is the error code for a folder handle to folder ID mapping conflict error.
StatusCodeServerErrorConflictPrevRoot is the error code for a PrevRoot pointer conflict error.
StatusCodeServerErrorConflictRevision is the error code for a revision conflict error.
StatusCodeServerErrorLockConflict is the error code returned by a MD write operation to indicate a lock conflict has happened and the MD has not been written.
StatusCodeServerErrorLocked is the error code to indicate the folder truncation lock is locked.
StatusCodeServerErrorMissingFolderHandle is the error code returned by the MD GetFolderHandle operation to indicate that a handle isn't found for a particular folder ID.
StatusCodeServerErrorThrottle is the error code to indicate the client should initiate backoff.
StatusCodeServerErrorTooManyFoldersCreated is the error code to indicate that the user has created more folders than their limit.
StatusCodeServerErrorUnauthorized is the error code to indicate the client is unauthorized to perform a certain operation.
StatusCodeServerErrorWriteAccess is the error code to indicate the client isn't authorized to write to a TLF.
Unmerged means that the TLF is unmerged and conflict resolution needs to be done.
UnspecifiedKeyGen indicates that the application doesn't have a particular keygen in mind when requesting keys; any keygen will do.
WriterEPubKeys means the ephemeral public key is in the writers array.
# Variables
NullBranchID is an empty BranchID.
PendingLocalSquashBranchID indicates a local branch that is not in known conflict with the master branch, but just needs to be squashed locally.
# Structs
BranchID encapsulates a per-device per-TLF branch ID.
EncryptedMerkleLeaf is an encrypted Merkle leaf.
ExtraMetadataV3 contains references to key bundles stored outside of metadata blocks.
ID is the content-based ID for a metadata block.
InvalidBranchID indicates whether the branch ID string is not parseable or invalid.
InvalidIDError indicates that a metadata ID string is not parseable or invalid.
InvalidKeyGenerationError indicates that an invalid key generation was used.
InvalidMetadataVersionError indicates that an invalid metadata version was used.
InvalidNonPrivateTLFOperation indicates that an invalid operation was attempted on a public or team TLF.
KeyBundleCacheStandard is an LRU-based implementation of the KeyBundleCache interface.
MDDiskUsageMismatch indicates an inconsistency in the DiskUsage field of a RootMetadata object.
MDPrevRootMismatch indicates that the PrevRoot field of a successor MD doesn't match the metadata ID of its predecessor.
MDRevisionMismatch indicates that we tried to apply a revision that was not the next in line.
MDTlfIDMismatch indicates that the ID field of a successor MD doesn't match the ID field of its predecessor.
MerkleHash is the hash of a RootMetadataSigned block.
MerkleLeaf is the value of a Merkle leaf node.
MerkleRoot represents a signed Merkle tree root.
MetadataIsFinalError indicates that we tried to make or set a successor to a finalized folder.
MissingDataError indicates that we are trying to take get the metadata ID of a MD object with no serialized data field.
MutableRootMetadataNoImplError is returned when an interface expected to implement MutableRootMetadata does not do so.
NewKeyGenerationError indicates that the data at the given path has been written using keys that our client doesn't have.
NewMerkleVersionError indicates that the merkle tree on the server is using a new metadata version that our client doesn't understand.
NewMetadataVersionError indicates that the metadata for the given folder has been written using a new metadata version that our client doesn't understand.
RootMetadataSigned is the top-level MD object stored in MD server.
RootMetadataV2 is the MD that is signed by the reader or writer.
RootMetadataV3 is the MD that is signed by the reader or writer.
ServerError is a generic server-side error.
ServerErrorBadRequest is a generic client-side error.
ServerErrorCannotReadFinalizedTLF is returned when the client isn't authorized to read a finalized TLF.
ServerErrorClassicTLFDoesNotExist is the error type for StatusCodeServerErrorClassicTLFDoesNotExist.
ServerErrorConditionFailed is returned when a conditonal write failed.
ServerErrorConflictDiskUsage is returned when the passed MD block is inconsistent with current history.
ServerErrorConflictFolderMapping is returned when there is a folder handle to folder ID mapping mismatch.
ServerErrorConflictPrevRoot is returned when the passed MD block is inconsistent with current history.
ServerErrorConflictRevision is returned when the passed MD block is inconsistent with current history.
ServerErrorLockConflict is the error type for StatusCodeServerErrorLockConflict.
ServerErrorLocked is returned when the folder truncation lock is acquired by someone else.
ServerErrorMissingFolderHandle is the error type for StatusCodeServerErrorMissingFolderHandle.
ServerErrorThrottle is returned when the server wants the client to backoff.
ServerErrorTooManyFoldersCreated is returned when a user has created more folders than their limit allows.
ServerErrorUnauthorized is returned when a device requests a key half which doesn't belong to it.
ServerErrorUnwrapper is an implementation of rpc.ErrorUnwrapper for errors coming from the MDServer.
ServerErrorWriteAccess is returned when the client isn't authorized to write to a TLF.
TLFCryptKeyInfo is a per-device key half entry in the TLF{Writer,Reader}KeyBundleV{2,3}.
TLFCryptKeyNotPerDeviceEncrypted is returned when a given TLFCryptKey is not encrypted per-device but rather symmetrically encrypted with the current generation of the TLFCryptKey.
TLFReaderKeyBundleID is the hash of a serialized TLFReaderKeyBundle.
TLFReaderKeyBundleV2 stores all the reader keys with reader permissions on a TLF.
TLFReaderKeyBundleV3 stores all the reader keys with reader permissions on a TLF.
TLFWriterKeyBundleID is the hash of a serialized TLFWriterKeyBundle.
TLFWriterKeyBundleV2 is a bundle of all the writer keys for a top-level folder.
TLFWriterKeyBundleV3 is a bundle of writer keys and historic symmetric encryption keys for a top-level folder.
UserServerHalfRemovalInfo contains a map from devices (identified by its crypt public key) to a list of IDs for key server halves to remove (one per key generation).
WriterMetadataExtraV2 stores more fields for WriterMetadataV2.
WriterMetadataV2 stores the metadata for a TLF that is only editable by users with writer permissions.
WriterMetadataV3 stores the metadata for a TLF that is only editable by users with writer permissions.
# Interfaces
ExtraMetadata is a per-version blob of extra metadata which may exist outside of the given metadata block, e.g.
KeyBundleCache is an interface to a key bundle cache for use with v3 metadata.
MutableRootMetadata is a mutable interface to the bare serializeable MD that is signed by the reader or writer.
RootMetadata is a read-only interface to the bare serializeable MD that is signed by the reader or writer.
TeamMembershipChecker is an interface for objects that can check the writer/reader membership of teams.
# Type aliases
DeviceKeyInfoMapV2 is a map from a user devices (identified by the KID of the corresponding device CryptPublicKey) to the TLF's symmetric secret key information.
DeviceKeyInfoMapV3 is a map from a user devices (identified by the corresponding device CryptPublicKey) to the TLF's symmetric secret key information.
DeviceKeyServerHalves is a map from a user devices (identified by the corresponding device CryptPublicKey) to corresponding key server halves.
DevicePublicKeys is a set of a user's devices (identified by the corresponding device CryptPublicKey).
DeviceServerHalfRemovalInfo is a map from a device's crypt public key to a list of server halves to remove.
EPubKeyLocationV2 represents the location of a user's ephemeral public key.
KeyGen is the type of a key generation for a top-level folder.
MergeStatus represents the merge status of a TLF.
MetadataFlags bitfield.
MetadataVer is the type of a version for marshalled KBFS metadata structures.
Revision is the type for the revision number.
ServerHalfRemovalInfo is a map from users and devices to a list of server half IDs to remove from the server.
TLFReaderKeyGenerationsV2 stores a slice of TLFReaderKeyBundleV2, where the last element is the current generation.
TLFWriterKeyGenerationsV2 stores a slice of TLFWriterKeyBundleV2, where the last element is the current generation.
UserDeviceKeyInfoMapV2 maps a user's keybase UID to their DeviceKeyInfoMapV2.
UserDeviceKeyInfoMapV3 maps a user's keybase UID to their DeviceKeyInfoMapV3.
UserDeviceKeyServerHalves maps a user's keybase UID to their DeviceServerHalves map.
UserDevicePublicKeys is a map from users to that user's set of devices.
WriterFlags bitfield.