hackage-security-0.6.3.2: Hackage security library

Safe Haskell | None
Language | Haskell2010

Hackage.Security.Client

Contents

- Checking for updates
- Downloading targets
- Access to the Hackage index
- Bootstrapping
- Re-exports
  - We only a few bits from .Repository
- Exceptions

Description

Main entry point into the Hackage Security framework for clients

Synopsis

- checkForUpdates :: forall (down :: Type -> Type). (Throws VerificationError, Throws SomeRemoteError) => Repository down -> Maybe UTCTime -> IO HasUpdates
- data HasUpdates
  - = HasUpdates
  - | NoUpdates
- downloadPackage :: forall (down :: Type -> Type). (Throws SomeRemoteError, Throws VerificationError, Throws InvalidPackageException) => Repository down -> PackageIdentifier -> Path Absolute -> IO ()
- downloadPackage' :: forall (down :: Type -> Type). (Throws SomeRemoteError, Throws VerificationError, Throws InvalidPackageException) => Repository down -> PackageIdentifier -> FilePath -> IO ()
- data Directory = Directory {
  - directoryFirst :: DirectoryEntry
  - directoryNext :: DirectoryEntry
  - directoryLookup :: forall dec. IndexFile dec -> Maybe DirectoryEntry
  - directoryEntries :: [(DirectoryEntry, IndexPath, Maybe (Some IndexFile))]
  }
- newtype DirectoryEntry = DirectoryEntry {
  - directoryEntryBlockNo :: TarEntryOffset
  }
- getDirectory :: forall (down :: Type -> Type). Repository down -> IO Directory
- data IndexFile a where
  - IndexPkgMetadata :: PackageIdentifier -> IndexFile (Signed Targets)
  - IndexPkgCabal :: PackageIdentifier -> IndexFile ()
  - IndexPkgPrefs :: PackageName -> IndexFile ()
- data IndexEntry dec = IndexEntry {
  - indexEntryPath :: IndexPath
  - indexEntryPathParsed :: Maybe (IndexFile dec)
  - indexEntryContent :: ByteString
  - indexEntryContentParsed :: Either SomeException dec
  - indexEntryTime :: EpochTime
  }
- data IndexCallbacks = IndexCallbacks {
  - indexLookupEntry :: DirectoryEntry -> IO (Some IndexEntry, Maybe DirectoryEntry)
  - indexLookupFile :: forall dec. IndexFile dec -> IO (Maybe (IndexEntry dec))
  - indexLookupFileEntry :: forall dec. DirectoryEntry -> IndexFile dec -> IO (IndexEntry dec)
  - indexLookupCabal :: Throws InvalidPackageException => PackageIdentifier -> IO (Trusted ByteString)
  - indexLookupMetadata :: Throws InvalidPackageException => PackageIdentifier -> IO (Trusted Targets)
  - indexLookupFileInfo :: (Throws InvalidPackageException, Throws VerificationError) => PackageIdentifier -> IO (Trusted FileInfo)
  - indexLookupHash :: (Throws InvalidPackageException, Throws VerificationError) => PackageIdentifier -> IO (Trusted Hash)
  - indexDirectory :: Directory
  }
- withIndex :: forall (down :: Type -> Type) a. Repository down -> (IndexCallbacks -> IO a) -> IO a
- requiresBootstrap :: forall (down :: Type -> Type). Repository down -> IO Bool
- bootstrap :: forall (down :: Type -> Type). (Throws SomeRemoteError, Throws VerificationError) => Repository down -> [KeyId] -> KeyThreshold -> IO ()
- data Signed a = Signed {
  - signed :: a
  - signatures :: Signatures
  }
- data Signature = Signature {
  - signature :: ByteString
  - signatureKey :: Some PublicKey
  }
- data IndexFile a where
  - IndexPkgMetadata :: PackageIdentifier -> IndexFile (Signed Targets)
  - IndexPkgCabal :: PackageIdentifier -> IndexFile ()
  - IndexPkgPrefs :: PackageName -> IndexFile ()
- data FileMap
- data TargetPath
  - = TargetPathRepo RepoPath
  - | TargetPathIndex IndexPath
- data FileChange
  - = FileChanged FileInfo
  - | FileDeleted
- fileMapChanges :: FileMap -> FileMap -> Map TargetPath FileChange
- data FileInfo = FileInfo {
  - fileInfoLength :: FileLength
  - fileInfoHashes :: Map HashFn Hash
  }
- data Int54
- data Header = Header {
  - headerExpires :: FileExpires
  - headerVersion :: FileVersion
  }
- data Mirrors = Mirrors {
  - mirrorsVersion :: FileVersion
  - mirrorsExpires :: FileExpires
  - mirrorsMirrors :: [Mirror]
  }
- data Root = Root {
  - rootVersion :: FileVersion
  - rootExpires :: FileExpires
  - rootKeys :: KeyEnv
  - rootRoles :: RootRoles
  }
- data Snapshot = Snapshot {
  - snapshotVersion :: FileVersion
  - snapshotExpires :: FileExpires
  - snapshotInfoRoot :: FileInfo
  - snapshotInfoMirrors :: FileInfo
  - snapshotInfoTarGz :: FileInfo
  - snapshotInfoTar :: Maybe FileInfo
  }
- data Targets = Targets {
  - targetsVersion :: FileVersion
  - targetsExpires :: FileExpires
  - targetsTargets :: FileMap
  - targetsDelegations :: Maybe Delegations
  }
- data Timestamp = Timestamp {
  - timestampVersion :: FileVersion
  - timestampExpires :: FileExpires
  - timestampInfoSnapshot :: FileInfo
  }
- newtype FileLength = FileLength {
  - fileLength :: Int54
  }
- newtype Hash = Hash String
- newtype KeyThreshold = KeyThreshold Int54
- data HashFn
  - = HashFnSHA256
  - | HashFnMD5
- fileInfo :: ByteString -> FileInfo
- computeFileInfo :: FsRoot root => Path root -> IO FileInfo
- compareTrustedFileInfo :: FileInfo -> FileInfo -> Bool
- knownFileInfoEqual :: FileInfo -> FileInfo -> Bool
- fileInfoSHA256 :: FileInfo -> Maybe Hash
- class HasHeader a where
  - fileExpires :: Lens' a FileExpires
  - fileVersion :: Lens' a FileVersion
- newtype FileVersion = FileVersion Int54
- newtype FileExpires = FileExpires (Maybe UTCTime)
- expiresInDays :: UTCTime -> Integer -> FileExpires
- expiresNever :: FileExpires
- isExpired :: UTCTime -> FileExpires -> Bool
- versionInitial :: FileVersion
- versionIncrement :: FileVersion -> FileVersion
- data CacheLayout = CacheLayout {
  - cacheLayoutRoot :: CachePath
  - cacheLayoutTimestamp :: CachePath
  - cacheLayoutSnapshot :: CachePath
  - cacheLayoutMirrors :: CachePath
  - cacheLayoutIndexTar :: CachePath
  - cacheLayoutIndexIdx :: CachePath
  - cacheLayoutIndexTarGz :: CachePath
  }
- cabalCacheLayout :: CacheLayout
- data IndexLayout = IndexLayout {
  - indexFileToPath :: forall dec. IndexFile dec -> IndexPath
  - indexFileFromPath :: IndexPath -> Maybe (Some IndexFile)
  }
- hackageIndexLayout :: IndexLayout
- indexLayoutPkgMetadata :: IndexLayout -> PackageIdentifier -> IndexPath
- indexLayoutPkgCabal :: IndexLayout -> PackageIdentifier -> IndexPath
- indexLayoutPkgPrefs :: IndexLayout -> PackageName -> IndexPath
- data RepoLayout = RepoLayout {
  - repoLayoutRoot :: RepoPath
  - repoLayoutTimestamp :: RepoPath
  - repoLayoutSnapshot :: RepoPath
  - repoLayoutMirrors :: RepoPath
  - repoLayoutIndexTarGz :: RepoPath
  - repoLayoutIndexTar :: RepoPath
  - repoLayoutPkgTarGz :: PackageIdentifier -> RepoPath
  }
- hackageRepoLayout :: RepoLayout
- cabalLocalRepoLayout :: RepoLayout
- data Mirror = Mirror {
  - mirrorUrlBase :: URI
  - mirrorContent :: MirrorContent
  }
- data MirrorContent = MirrorFull
- type MirrorDescription = String
- describeMirror :: Mirror -> MirrorDescription
- data RepoRoot
- type RepoPath = Path RepoRoot
- anchorRepoPathLocally :: Path root -> RepoPath -> Path root
- anchorRepoPathRemotely :: Path Web -> RepoPath -> Path Web
- data IndexRoot
- type IndexPath = Path IndexRoot
- data CacheRoot
- type CachePath = Path CacheRoot
- anchorCachePath :: Path root -> CachePath -> Path root
- data Delegation = Delegation (Pattern a) (Replacement a)
- data RootRoles = RootRoles {
  - rootRolesRoot :: RoleSpec Root
  - rootRolesSnapshot :: RoleSpec Snapshot
  - rootRolesTargets :: RoleSpec Targets
  - rootRolesTimestamp :: RoleSpec Timestamp
  - rootRolesMirrors :: RoleSpec Mirrors
  }
- data RoleSpec a = RoleSpec {
  - roleSpecKeys :: [Some PublicKey]
  - roleSpecThreshold :: KeyThreshold
  }
- newtype Signatures = Signatures [Signature]
- unsigned :: a -> Signed a
- withSignatures :: ToJSON WriteJSON a => RepoLayout -> [Some Key] -> a -> Signed a
- withSignatures' :: ToJSON Identity a => [Some Key] -> a -> Signed a
- signRendered :: [Some Key] -> ByteString -> Signatures
- verifySignature :: ByteString -> Signature -> Bool
- signedFromJSON :: (MonadKeys m, FromJSON m a) => JSValue -> m (Signed a)
- verifySignatures :: JSValue -> Signatures -> Bool
- data UninterpretedSignatures a = UninterpretedSignatures {
  - uninterpretedSigned :: a
  - uninterpretedSignatures :: [PreSignature]
  }
- data PreSignature = PreSignature {
  - presignature :: ByteString
  - presigMethod :: Some KeyType
  - presigKeyId :: KeyId
  }
- fromPreSignature :: MonadKeys m => PreSignature -> m Signature
- fromPreSignatures :: MonadKeys m => [PreSignature] -> m Signatures
- toPreSignature :: Signature -> PreSignature
- toPreSignatures :: Signatures -> [PreSignature]
- data Delegations = Delegations {
  - delegationsKeys :: KeyEnv
  - delegationsRoles :: [DelegationSpec]
  }
- data DelegationSpec = DelegationSpec {
  - delegationSpecKeys :: [Some PublicKey]
  - delegationSpecThreshold :: KeyThreshold
  - delegation :: Delegation
  }
- targetsLookup :: TargetPath -> Targets -> Maybe FileInfo
- data Key a where
  - KeyEd25519 :: PublicKey -> SecretKey -> Key Ed25519
- sign :: PrivateKey typ -> ByteString -> ByteString
- data PublicKey a where
  - PublicKeyEd25519 :: PublicKey -> PublicKey Ed25519
- verify :: PublicKey typ -> ByteString -> ByteString -> Bool
- data Ed25519
- data PrivateKey a where
  - PrivateKeyEd25519 :: SecretKey -> PrivateKey Ed25519
- data KeyType typ where
  - KeyTypeEd25519 :: KeyType Ed25519
- somePublicKey :: Some Key -> Some PublicKey
- somePublicKeyType :: Some PublicKey -> Some KeyType
- someKeyId :: forall (key :: Type -> Type). HasKeyId key => Some key -> KeyId
- publicKey :: Key a -> PublicKey a
- privateKey :: Key a -> PrivateKey a
- createKey :: KeyType key -> IO (Key key)
- createKey' :: KeyType key -> IO (Some Key)
- newtype KeyId = KeyId {
  - keyIdString :: String
  }
- class HasKeyId (key :: Type -> Type) where
  - keyId :: key typ -> KeyId
- trusted :: Trusted a -> a
- data Repository (down :: Type -> Type)
- class DownloadedFile (down :: Type -> Type) where
  - downloadedVerify :: down a -> Trusted FileInfo -> IO Bool
  - downloadedRead :: down Metadata -> IO ByteString
  - downloadedCopyTo :: down a -> Path Absolute -> IO ()
- data SomeRemoteError where
  - SomeRemoteError :: forall e. Exception e => e -> SomeRemoteError
- data LogMessage
  - = LogRootUpdated
  - | LogVerificationError VerificationError
  - | LogDownloading (RemoteFile fs typ)
  - | LogUpdating (RemoteFile fs Binary)
  - | LogSelectedMirror MirrorDescription
  - | LogCannotUpdate (RemoteFile fs Binary) UpdateFailure
  - | LogMirrorFailed MirrorDescription SomeException
  - | LogLockWait (Path Absolute)
  - | LogLockWaitDone (Path Absolute)
  - | LogUnlock (Path Absolute)
- uncheckClientErrors :: ((Throws VerificationError, Throws SomeRemoteError, Throws InvalidPackageException) => IO a) -> IO a
- data VerificationError
  - = VerificationErrorSignatures TargetPath Integer [KeyId] [KeyId]
  - | VerificationErrorExpired TargetPath
  - | VerificationErrorVersion TargetPath
  - | VerificationErrorFileInfo TargetPath
  - | VerificationErrorUnknownTarget TargetPath
  - | VerificationErrorMissingSHA256 TargetPath
  - | VerificationErrorDeserialization TargetPath DeserializationError
  - | VerificationErrorLoop VerificationHistory
- type VerificationHistory = [Either RootUpdated VerificationError]
- data RootUpdated = RootUpdated
- data InvalidPackageException = InvalidPackageException PackageIdentifier
- data InvalidFileInIndex = InvalidFileInIndex {
  - invalidFileInIndex :: IndexFile dec
  - invalidFileInIndexRaw :: ByteString
  - invalidFileInIndexError :: DeserializationError
  }
- data LocalFileCorrupted = LocalFileCorrupted DeserializationError

# Checking for updates

checkForUpdates Source #

Arguments

:: forall (down :: Type -> Type). (Throws VerificationError, Throws SomeRemoteError) |
=> Repository down |
-> Maybe UTCTime | To check expiry times against (if using)
-> IO HasUpdates |

Generic logic for checking if there are updates

This implements the logic described in Section 5.1, "The client application", of the TUF spec. It checks which of the server metadata has changed, and downloads all changed metadata to the local cache. (Metadata here refers both to the TUF security metadata as well as the Hackage package index.)

You should pass `Nothing` for the UTCTime _only_ under exceptional circumstances (such as when the main server is down for longer than the expiry dates used in the timestamp files on mirrors).

data HasUpdates Source #

Constructors

HasUpdates |
NoUpdates |

#### Instances

Instances details

Show HasUpdates Source # |
Instance details Defined in Hackage.Security.Client Methods showsPrec :: Int -> HasUpdates -> ShowS Source # show :: HasUpdates -> String Source # showList :: [HasUpdates] -> ShowS Source #
Eq HasUpdates Source # |
Instance details Defined in Hackage.Security.Client Methods (==) :: HasUpdates -> HasUpdates -> Bool Source # (/=) :: HasUpdates -> HasUpdates -> Bool Source #
Ord HasUpdates Source # |

Instance details

Defined in Hackage.Security.Client

Methods

compare :: HasUpdates -> HasUpdates -> Ordering Source #

(<) :: HasUpdates -> HasUpdates -> Bool Source #

(<=) :: HasUpdates -> HasUpdates -> Bool Source #

(>) :: HasUpdates -> HasUpdates -> Bool Source #

(>=) :: HasUpdates -> HasUpdates -> Bool Source #

max :: HasUpdates -> HasUpdates -> HasUpdates Source #

min :: HasUpdates -> HasUpdates -> HasUpdates Source #

# Downloading targets

downloadPackage Source #

Arguments

:: forall (down :: Type -> Type). (Throws SomeRemoteError, Throws VerificationError, Throws InvalidPackageException) |
=> Repository down | Repository
-> PackageIdentifier | Package to download
-> Path Absolute | Destination (see also `downloadPackage'`)
-> IO () |

Download a package

downloadPackage' Source #

Arguments

:: forall (down :: Type -> Type). (Throws SomeRemoteError, Throws VerificationError, Throws InvalidPackageException) |
=> Repository down | Repository
-> PackageIdentifier | Package to download
-> FilePath | Destination
-> IO () |

Variation on `downloadPackage` that takes a FilePath instead.

# Access to the Hackage index

data Directory Source #

Index directory

Constructors

Directory |

Fields

- directoryFirst :: DirectoryEntry

  The first entry in the dictionary

- directoryNext :: DirectoryEntry

  The next available (i.e., one after last) directory entry

- directoryLookup :: forall dec. IndexFile dec -> Maybe DirectoryEntry

  Lookup an entry in the dictionary

  This is an efficient operation.

- directoryEntries :: [(DirectoryEntry, IndexPath, Maybe (Some IndexFile))]

  An enumeration of all entries

  This field is lazily constructed, so if you don't need it, it does not incur a performance overhead. Moreover, the `IndexFile` is also created lazily so if you only need the raw `IndexPath` there is no parsing overhead.

  The entries are ordered by `DirectoryEntry` so that the entries can efficiently be read in sequence.

  NOTE: This means that there are two ways to enumerate all entries in the tar file, since when lookup an entry using `indexLookupEntry` the `DirectoryEntry` of the next entry is also returned. However, this involves reading through the entire `tar` file. If you only need to read some files, it is significantly more efficient to enumerate the tar entries using `directoryEntries` instead and only call `indexLookupEntry` when required.

newtype DirectoryEntry Source #

Entry into the Hackage index.

Constructors

DirectoryEntry |

Fields

- directoryEntryBlockNo :: TarEntryOffset

  (Low-level) block number of the tar index entry

  Exposed for the benefit of clients who read the `.tar` file directly. For this reason also the `Show` and `Read` instances for `DirectoryEntry` just print and parse the underlying `TarEntryOffset`.

#### Instances

Instances details

Read DirectoryEntry Source # |
Instance details Defined in Hackage.Security.Client Methods readsPrec :: Int -> ReadS DirectoryEntry Source # readList :: ReadS [DirectoryEntry] Source # readPrec :: ReadPrec DirectoryEntry Source # readListPrec :: ReadPrec [DirectoryEntry] Source #
Show DirectoryEntry Source # |
Instance details Defined in Hackage.Security.Client Methods showsPrec :: Int -> DirectoryEntry -> ShowS Source # show :: DirectoryEntry -> String Source # showList :: [DirectoryEntry] -> ShowS Source #
Eq DirectoryEntry Source # |
Instance details Defined in Hackage.Security.Client Methods (==) :: DirectoryEntry -> DirectoryEntry -> Bool Source # (/=) :: DirectoryEntry -> DirectoryEntry -> Bool Source #
Ord DirectoryEntry Source # |

Instance details

Defined in Hackage.Security.Client

Methods

compare :: DirectoryEntry -> DirectoryEntry -> Ordering Source #

(<) :: DirectoryEntry -> DirectoryEntry -> Bool Source #

(<=) :: DirectoryEntry -> DirectoryEntry -> Bool Source #

(>) :: DirectoryEntry -> DirectoryEntry -> Bool Source #

(>=) :: DirectoryEntry -> DirectoryEntry -> Bool Source #

max :: DirectoryEntry -> DirectoryEntry -> DirectoryEntry Source #

min :: DirectoryEntry -> DirectoryEntry -> DirectoryEntry Source #

getDirectory :: forall (down :: Type -> Type). Repository down -> IO Directory Source #

Read the Hackage index directory

Should only be called after `checkForUpdates`.

data IndexFile a where Source #

Files that we might request from the index

The type index tells us the type of the decoded file, if any. For files for which the library does not support decoding this will be `()`. NOTE: Clients should NOT rely on this type index being `()`, or they might break if we add support for parsing additional file formats in the future.

TODO: If we wanted to support legacy Hackage, we should also have a case for the global preferred-versions file. But supporting legacy Hackage will probably require more work anyway..

Constructors

IndexPkgMetadata :: PackageIdentifier -> IndexFile (Signed Targets) |
IndexPkgCabal :: PackageIdentifier -> IndexFile () |
IndexPkgPrefs :: PackageName -> IndexFile () |

#### Instances

Instances details

SomePretty IndexFile Source # |
Instance details Defined in Hackage.Security.TUF.Layout.Index Methods somePretty :: DictPretty (IndexFile a) Source #
SomeShow IndexFile Source # |
Instance details Defined in Hackage.Security.TUF.Layout.Index Methods someShow :: DictShow (IndexFile a) Source #
Show (IndexFile dec) Source # |
Instance details Defined in Hackage.Security.TUF.Layout.Index Methods showsPrec :: Int -> IndexFile dec -> ShowS Source # show :: IndexFile dec -> String Source # showList :: [IndexFile dec] -> ShowS Source #
Pretty (IndexFile dec) Source # |
Instance details Defined in Hackage.Security.TUF.Layout.Index Methods pretty :: IndexFile dec -> String Source #

data IndexEntry dec Source #

Entry from the Hackage index; see `withIndex`.

Constructors

IndexEntry |

Fields

- indexEntryPath :: IndexPath

  The raw path in the tarfile

- indexEntryPathParsed :: Maybe (IndexFile dec)

  The parsed file (if recognised)

- indexEntryContent :: ByteString

  The raw contents

  Although this is a lazy bytestring, this is actually read into memory strictly (i.e., it can safely be used outside the scope of withIndex and friends).

- indexEntryContentParsed :: Either SomeException dec

  The parsed contents

  This field is lazily constructed; the parser is not unless you do a pattern match on this value.

- indexEntryTime :: EpochTime

  The time of the entry in the tarfile.

data IndexCallbacks Source #

Various operations that we can perform on the index once its open

Note that `IndexEntry` contains a fields both for the raw file contents and the parsed file contents; clients can choose which to use.

In principle these callbacks will do verification (once we have implemented author signing). Right now they don't need to do that, because the index as a whole will have been verified.

Constructors

IndexCallbacks |

Fields

- indexLookupEntry :: DirectoryEntry -> IO (Some IndexEntry, Maybe DirectoryEntry)

  Look up an entry by `DirectoryEntry`

  Since these `DirectoryEntry`s must come from somewhere (probably from the `Directory`), it is assumed that they are valid; if they are not, an (unchecked) exception will be thrown.

  This function also returns the `DirectoryEntry` of the next file in the index (if any) for the benefit of clients who wish to walk through the entire index.

- indexLookupFile :: forall dec. IndexFile dec -> IO (Maybe (IndexEntry dec))

  Look up an entry by `IndexFile`

  Returns `Nothing` if the `IndexFile` does not refer to an existing file.

- indexLookupFileEntry :: forall dec. DirectoryEntry -> IndexFile dec -> IO (IndexEntry dec)

  Variation if both the `DirectoryEntry` and the `IndexFile` are known

  You might use this when scanning the index using `directoryEntries`.

- indexLookupCabal :: Throws InvalidPackageException => PackageIdentifier -> IO (Trusted ByteString)

  Get (raw) cabal file (wrapper around `indexLookupFile`)

- indexLookupMetadata :: Throws InvalidPackageException => PackageIdentifier -> IO (Trusted Targets)

  Lookup package metadata (wrapper around `indexLookupFile`)

  This will throw an (unchecked) exception if the `targets.json` file could not be parsed.

- indexLookupFileInfo :: (Throws InvalidPackageException, Throws VerificationError) => PackageIdentifier -> IO (Trusted FileInfo)

  Get file info (including hash) (wrapper around `indexLookupFile`)

- indexLookupHash :: (Throws InvalidPackageException, Throws VerificationError) => PackageIdentifier -> IO (Trusted Hash)

  Get the SHA256 hash for a package (wrapper around `indexLookupInfo`)

  In addition to the exceptions thrown by `indexLookupInfo`, this will also throw an exception if the SHA256 is not listed in the `FileMap` (again, this will not happen with a well-formed Hackage index.)

- indexDirectory :: Directory

  The `Directory` for the index

  We provide this here because `withIndex` will have read this anyway.

withIndex :: forall (down :: Type -> Type) a. Repository down -> (IndexCallbacks -> IO a) -> IO a Source #

Look up entries in the Hackage index

This is in `withFile` style so that clients can efficiently look up multiple files from the index.

Should only be called after `checkForUpdates`.

# Bootstrapping

requiresBootstrap :: forall (down :: Type -> Type). Repository down -> IO Bool Source #

Check if we need to bootstrap (i.e., if we have root info)

bootstrap :: forall (down :: Type -> Type). (Throws SomeRemoteError, Throws VerificationError) => Repository down -> [KeyId] -> KeyThreshold -> IO () Source #

Bootstrap the chain of trust

New clients might need to obtain a copy of the root metadata. This however represents a chicken-and-egg problem: how can we verify the root metadata we downloaded? The only possibility is to be provided with a set of an out-of-band set of root keys and an appropriate threshold.

Clients who provide a threshold of 0 can do an initial "unsafe" update of the root information, if they wish.

The downloaded root information will _only_ be verified against the provided keys, and _not_ against previously downloaded root info (if any). It is the responsibility of the client to call `bootstrap` only when this is the desired behaviour.

# Re-exports

data Signed a Source #

Constructors

Signed |

Fields

- signed :: a
- signatures :: Signatures

#### Instances

Instances details

MonadKeys m => FromJSON m (Signed Mirrors) Source # |
Instance details Defined in Hackage.Security.TUF.Mirrors Methods fromJSON :: JSValue -> m (Signed Mirrors) Source #
MonadKeys m => FromJSON m (Signed Root) Source # | We give an instance for Signed Root rather than Root because the key environment from the root data is necessary to resolve the explicit sharing in the signatures.
Instance details Defined in Hackage.Security.TUF.Root Methods fromJSON :: JSValue -> m (Signed Root) Source #
(MonadKeys m, MonadReader RepoLayout m) => FromJSON m (Signed Snapshot) Source # |
Instance details Defined in Hackage.Security.TUF.Snapshot Methods fromJSON :: JSValue -> m (Signed Snapshot) Source #
MonadKeys m => FromJSON m (Signed Targets) Source # |
Instance details Defined in Hackage.Security.TUF.Targets Methods fromJSON :: JSValue -> m (Signed Targets) Source #
(MonadKeys m, MonadReader RepoLayout m) => FromJSON m (Signed Timestamp) Source # |
Instance details Defined in Hackage.Security.TUF.Timestamp Methods fromJSON :: JSValue -> m (Signed Timestamp) Source #
(Monad m, ToJSON m a) => ToJSON m (Signed a) Source # |
Instance details Defined in Hackage.Security.TUF.Signed Methods toJSON :: Signed a -> m JSValue Source #

data Signature Source #

Constructors

Signature |

Fields

- signature :: ByteString
- signatureKey :: Some PublicKey

data IndexFile a where Source #

Files that we might request from the index

The type index tells us the type of the decoded file, if any. For files for which the library does not support decoding this will be `()`. NOTE: Clients should NOT rely on this type index being `()`, or they might break if we add support for parsing additional file formats in the future.

TODO: If we wanted to support legacy Hackage, we should also have a case for the global preferred-versions file. But supporting legacy Hackage will probably require more work anyway..

Constructors

IndexPkgMetadata :: PackageIdentifier -> IndexFile (Signed Targets) |
IndexPkgCabal :: PackageIdentifier -> IndexFile () |
IndexPkgPrefs :: PackageName -> IndexFile () |

#### Instances

Instances details

SomePretty IndexFile Source # |
Instance details Defined in Hackage.Security.TUF.Layout.Index Methods somePretty :: DictPretty (IndexFile a) Source #
SomeShow IndexFile Source # |
Instance details Defined in Hackage.Security.TUF.Layout.Index Methods someShow :: DictShow (IndexFile a) Source #
Show (IndexFile dec) Source # |
Instance details Defined in Hackage.Security.TUF.Layout.Index Methods showsPrec :: Int -> IndexFile dec -> ShowS Source # show :: IndexFile dec -> String Source # showList :: [IndexFile dec] -> ShowS Source #
Pretty (IndexFile dec) Source # |
Instance details Defined in Hackage.Security.TUF.Layout.Index Methods pretty :: IndexFile dec -> String Source #

data FileMap Source #

Mapping from paths to file info

File maps are used in target files; the paths are relative to the location of the target files containing the file map.

#### Instances

Instances details

Show FileMap Source # |
Instance details Defined in Hackage.Security.TUF.FileMap Methods showsPrec :: Int -> FileMap -> ShowS Source # show :: FileMap -> String Source # showList :: [FileMap] -> ShowS Source #
ReportSchemaErrors m => FromJSON m FileMap Source # |
Instance details Defined in Hackage.Security.TUF.FileMap Methods fromJSON :: JSValue -> m FileMap Source #
Monad m => ToJSON m FileMap Source # |
Instance details Defined in Hackage.Security.TUF.FileMap Methods toJSON :: FileMap -> m JSValue Source #

data TargetPath Source #

Entries in `FileMap` either talk about the repository or the index

Constructors

TargetPathRepo RepoPath |
TargetPathIndex IndexPath |

#### Instances

Instances details

Show TargetPath Source # |
Instance details Defined in Hackage.Security.TUF.FileMap Methods showsPrec :: Int -> TargetPath -> ShowS Source # show :: TargetPath -> String Source # showList :: [TargetPath] -> ShowS Source #
Eq TargetPath Source # |
Instance details Defined in Hackage.Security.TUF.FileMap Methods (==) :: TargetPath -> TargetPath -> Bool Source # (/=) :: TargetPath -> TargetPath -> Bool Source #
Ord TargetPath Source # |

Instance details

Defined in Hackage.Security.TUF.FileMap

Methods

compare :: TargetPath -> TargetPath -> Ordering Source #

(<) :: TargetPath -> TargetPath -> Bool Source #

(<=) :: TargetPath -> TargetPath -> Bool Source #

(>) :: TargetPath -> TargetPath -> Bool Source #

(>=) :: TargetPath -> TargetPath -> Bool Source #

max :: TargetPath -> TargetPath -> TargetPath Source #

min :: TargetPath -> TargetPath -> TargetPath Source #

Pretty TargetPath Source # |
Instance details Defined in Hackage.Security.TUF.FileMap Methods pretty :: TargetPath -> String Source #
ReportSchemaErrors m => FromObjectKey m TargetPath Source # |
Instance details Defined in Hackage.Security.TUF.FileMap Methods fromObjectKey :: String -> m (Maybe TargetPath) Source #
Monad m => ToObjectKey m TargetPath Source # |
Instance details Defined in Hackage.Security.TUF.FileMap Methods toObjectKey :: TargetPath -> m String Source #

data FileChange Source #

Constructors

FileChanged FileInfo | File got added or modified; we record the new file info
FileDeleted | File got deleted

#### Instances

Instances details

Show FileChange Source # |
Instance details Defined in Hackage.Security.TUF.FileMap Methods showsPrec :: Int -> FileChange -> ShowS Source # show :: FileChange -> String Source # showList :: [FileChange] -> ShowS Source #

fileMapChanges Source #

Arguments

:: FileMap | Old
-> FileMap | New
-> Map TargetPath FileChange |

data FileInfo Source #

File information

This intentionally does not have an `Eq` instance; see `knownFileInfoEqual` and `verifyFileInfo` instead.

NOTE: Throughout we compute file information always over the raw bytes. For example, when `timestamp.json` lists the hash of `snapshot.json`, this hash is computed over the actual `snapshot.json` file (as opposed to the canonical form of the embedded JSON). This brings it in line with the hash computed over target files, where that is the only choice available.

Constructors

FileInfo |

Fields

- fileInfoLength :: FileLength
- fileInfoHashes :: Map HashFn Hash

#### Instances

Instances details

Show FileInfo Source # |
Instance details Defined in Hackage.Security.TUF.FileInfo Methods showsPrec :: Int -> FileInfo -> ShowS Source # show :: FileInfo -> String Source # showList :: [FileInfo] -> ShowS Source #
ReportSchemaErrors m => FromJSON m FileInfo Source # |
Instance details Defined in Hackage.Security.TUF.FileInfo Methods fromJSON :: JSValue -> m FileInfo Source #
Monad m => ToJSON m FileInfo Source # |
Instance details Defined in Hackage.Security.TUF.FileInfo Methods toJSON :: FileInfo -> m JSValue Source #

data Int54 Source #

54-bit integer values

JavaScript can only safely represent numbers between `-(2^53 - 1)` and `2^53 - 1`.

TODO: Although we introduce the type here, we don't actually do any bounds checking and just inherit all type class instance from Int64. We should probably define `fromInteger` to do bounds checking, give different instances for type classes such as `Bounded` and `FiniteBits`, etc.

#### Instances

Instances details

PrintfArg Int54 Source # |
Instance details Defined in Text.JSON.Canonical Methods formatArg :: Int54 -> FieldFormatter Source # parseFormat :: Int54 -> ModifierParser Source #
Bits Int54 Source # |

Instance details

Defined in Text.JSON.Canonical

Methods

(.&.) :: Int54 -> Int54 -> Int54 Source #

(.|.) :: Int54 -> Int54 -> Int54 Source #

xor :: Int54 -> Int54 -> Int54 Source #

complement :: Int54 -> Int54 Source #

shift :: Int54 -> Int -> Int54 Source #

rotate :: Int54 -> Int -> Int54 Source #

zeroBits :: Int54 Source #

bit :: Int -> Int54 Source #

setBit :: Int54 -> Int -> Int54 Source #

clearBit :: Int54 -> Int -> Int54 Source #

complementBit :: Int54 -> Int -> Int54 Source #

testBit :: Int54 -> Int -> Bool Source #

bitSizeMaybe :: Int54 -> Maybe Int Source #

bitSize :: Int54 -> Int Source #

isSigned :: Int54 -> Bool Source #

shiftL :: Int54 -> Int -> Int54 Source #

unsafeShiftL :: Int54 -> Int -> Int54 Source #

shiftR :: Int54 -> Int -> Int54 Source #

unsafeShiftR :: Int54 -> Int -> Int54 Source #

rotateL :: Int54 -> Int -> Int54 Source #

rotateR :: Int54 -> Int -> Int54 Source #

popCount :: Int54 -> Int Source #

FiniteBits Int54 Source # |
Instance details Defined in Text.JSON.Canonical Methods finiteBitSize :: Int54 -> Int Source # countLeadingZeros :: Int54 -> Int Source # countTrailingZeros :: Int54 -> Int Source #
Data Int54 Source # |

Instance details

Defined in Text.JSON.Canonical

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Int54 -> c Int54 Source #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Int54 Source #

toConstr :: Int54 -> Constr Source #

dataTypeOf :: Int54 -> DataType Source #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Int54) Source #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Int54) Source #

gmapT :: (forall b. Data b => b -> b) -> Int54 -> Int54 Source #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Int54 -> r Source #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Int54 -> r Source #

gmapQ :: (forall d. Data d => d -> u) -> Int54 -> [u] Source #

gmapQi :: Int -> (forall d. Data d => d -> u) -> Int54 -> u Source #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Int54 -> m Int54 Source #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Int54 -> m Int54 Source #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Int54 -> m Int54 Source #

Bounded Int54 Source # |
Instance details Defined in Text.JSON.Canonical Methods minBound :: Int54 Source # maxBound :: Int54 Source #
Enum Int54 Source # |
Instance details Defined in Text.JSON.Canonical Methods succ :: Int54 -> Int54 Source # pred :: Int54 -> Int54 Source # toEnum :: Int -> Int54 Source # fromEnum :: Int54 -> Int Source # enumFrom :: Int54 -> [Int54] Source # enumFromThen :: Int54 -> Int54 -> [Int54] Source # enumFromTo :: Int54 -> Int54 -> [Int54] Source # enumFromThenTo :: Int54 -> Int54 -> Int54 -> [Int54] Source #
Storable Int54 Source # |

Instance details

Defined in Text.JSON.Canonical

Methods

sizeOf :: Int54 -> Int Source #

alignment :: Int54 -> Int Source #

peekElemOff :: Ptr Int54 -> Int -> IO Int54 Source #

pokeElemOff :: Ptr Int54 -> Int -> Int54 -> IO () Source #

peekByteOff :: Ptr b -> Int -> IO Int54 Source #

pokeByteOff :: Ptr b -> Int -> Int54 -> IO () Source #

peek :: Ptr Int54 -> IO Int54 Source #

poke :: Ptr Int54 -> Int54 -> IO () Source #

Ix Int54 Source # |
Instance details Defined in Text.JSON.Canonical Methods range :: (Int54, Int54) -> [Int54] Source # index :: (Int54, Int54) -> Int54 -> Int Source # unsafeIndex :: (Int54, Int54) -> Int54 -> Int Source # inRange :: (Int54, Int54) -> Int54 -> Bool Source # rangeSize :: (Int54, Int54) -> Int Source # unsafeRangeSize :: (Int54, Int54) -> Int Source #
Num Int54 Source # |
Instance details Defined in Text.JSON.Canonical Methods (+) :: Int54 -> Int54 -> Int54 Source # (-) :: Int54 -> Int54 -> Int54 Source # (*) :: Int54 -> Int54 -> Int54 Source # negate :: Int54 -> Int54 Source # abs :: Int54 -> Int54 Source # signum :: Int54 -> Int54 Source # fromInteger :: Integer -> Int54 Source #
Read Int54 Source # |
Instance details Defined in Text.JSON.Canonical Methods readsPrec :: Int -> ReadS Int54 Source # readList :: ReadS [Int54] Source # readPrec :: ReadPrec Int54 Source # readListPrec :: ReadPrec [Int54] Source #
Integral Int54 Source # |
Instance details Defined in Text.JSON.Canonical Methods quot :: Int54 -> Int54 -> Int54 Source # rem :: Int54 -> Int54 -> Int54 Source # div :: Int54 -> Int54 -> Int54 Source # mod :: Int54 -> Int54 -> Int54 Source # quotRem :: Int54 -> Int54 -> (Int54, Int54) Source # divMod :: Int54 -> Int54 -> (Int54, Int54) Source # toInteger :: Int54 -> Integer Source #
Real Int54 Source # |
Instance details Defined in Text.JSON.Canonical Methods toRational :: Int54 -> Rational Source #
Show Int54 Source # |
Instance details Defined in Text.JSON.Canonical Methods showsPrec :: Int -> Int54 -> ShowS Source # show :: Int54 -> String Source # showList :: [Int54] -> ShowS Source #
Eq Int54 Source # |
Instance details Defined in Text.JSON.Canonical Methods (==) :: Int54 -> Int54 -> Bool Source # (/=) :: Int54 -> Int54 -> Bool Source #
Ord Int54 Source # |
Instance details Defined in Text.JSON.Canonical Methods compare :: Int54 -> Int54 -> Ordering Source # (<) :: Int54 -> Int54 -> Bool Source # (<=) :: Int54 -> Int54 -> Bool Source # (>) :: Int54 -> Int54 -> Bool Source # (>=) :: Int54 -> Int54 -> Bool Source # max :: Int54 -> Int54 -> Int54 Source # min :: Int54 -> Int54 -> Int54 Source #
ReportSchemaErrors m => FromJSON m Int54 Source # |
Instance details Defined in Hackage.Security.Util.JSON Methods fromJSON :: JSValue -> m Int54 Source #
Monad m => ToJSON m Int54 Source # |
Instance details Defined in Hackage.Security.Util.JSON Methods toJSON :: Int54 -> m JSValue Source #

data Header Source #

Occasionally it is useful to read only a header from a file.

`HeaderOnly` intentionally only has a `FromJSON` instance (no `ToJSON`).

Constructors

Header |

Fields

- headerExpires :: FileExpires
- headerVersion :: FileVersion

#### Instances

Instances details

HasHeader Header Source # |
Instance details Defined in Hackage.Security.TUF.Header Methods fileExpires :: Lens' Header FileExpires Source # fileVersion :: Lens' Header FileVersion Source #
ReportSchemaErrors m => FromJSON m Header Source # |
Instance details Defined in Hackage.Security.TUF.Header Methods fromJSON :: JSValue -> m Header Source #

data Mirrors Source #

Constructors

Mirrors |

Fields

- mirrorsVersion :: FileVersion
- mirrorsExpires :: FileExpires
- mirrorsMirrors :: [Mirror]

#### Instances

Instances details

HasHeader Mirrors Source # |
Instance details Defined in Hackage.Security.TUF.Mirrors Methods fileExpires :: Lens' Mirrors FileExpires Source # fileVersion :: Lens' Mirrors FileVersion Source #
VerifyRole Mirrors Source # |
Instance details Defined in Hackage.Security.Trusted Methods verifyRole :: Trusted Root -> TargetPath -> Maybe FileVersion -> Maybe UTCTime -> Signed Mirrors -> Either VerificationError (SignaturesVerified Mirrors) Source #
(MonadError DeserializationError m, ReportSchemaErrors m) => FromJSON m Mirrors Source # |
Instance details Defined in Hackage.Security.TUF.Mirrors Methods fromJSON :: JSValue -> m Mirrors Source #
Monad m => ToJSON m Mirrors Source # |
Instance details Defined in Hackage.Security.TUF.Mirrors Methods toJSON :: Mirrors -> m JSValue Source #
MonadKeys m => FromJSON m (Signed Mirrors) Source # |
Instance details Defined in Hackage.Security.TUF.Mirrors Methods fromJSON :: JSValue -> m (Signed Mirrors) Source #

data Root Source #

The root metadata

NOTE: We must have the invariant that ALL keys (apart from delegation keys) must be listed in `rootKeys`. (Delegation keys satisfy a similar invariant, see Targets.)

Constructors

Root |

Fields

- rootVersion :: FileVersion
- rootExpires :: FileExpires
- rootKeys :: KeyEnv
- rootRoles :: RootRoles

#### Instances

Instances details

HasHeader Root Source # |
Instance details Defined in Hackage.Security.TUF.Root Methods fileExpires :: Lens' Root FileExpires Source # fileVersion :: Lens' Root FileVersion Source #
VerifyRole Root Source # |
Instance details Defined in Hackage.Security.Trusted Methods verifyRole :: Trusted Root -> TargetPath -> Maybe FileVersion -> Maybe UTCTime -> Signed Root -> Either VerificationError (SignaturesVerified Root) Source #
Monad m => ToJSON m Root Source # |
Instance details Defined in Hackage.Security.TUF.Root Methods toJSON :: Root -> m JSValue Source #
MonadKeys m => FromJSON m (Signed Root) Source # | We give an instance for Signed Root rather than Root because the key environment from the root data is necessary to resolve the explicit sharing in the signatures.
Instance details Defined in Hackage.Security.TUF.Root Methods fromJSON :: JSValue -> m (Signed Root) Source #

data Snapshot Source #

Constructors

Snapshot |

Fields

- snapshotVersion :: FileVersion
- snapshotExpires :: FileExpires
- snapshotInfoRoot :: FileInfo

  File info for the root metadata

  We list this explicitly in the snapshot so that we can check if we need to update the root metadata without first having to download the entire index tarball.

- snapshotInfoMirrors :: FileInfo

  File info for the mirror metadata

- snapshotInfoTarGz :: FileInfo

  Compressed index tarball

- snapshotInfoTar :: Maybe FileInfo

  Uncompressed index tarball

  Repositories are not required to provide this.

#### Instances

Instances details

HasHeader Snapshot Source # |
Instance details Defined in Hackage.Security.TUF.Snapshot Methods fileExpires :: Lens' Snapshot FileExpires Source # fileVersion :: Lens' Snapshot FileVersion Source #
VerifyRole Snapshot Source # |
Instance details Defined in Hackage.Security.Trusted Methods verifyRole :: Trusted Root -> TargetPath -> Maybe FileVersion -> Maybe UTCTime -> Signed Snapshot -> Either VerificationError (SignaturesVerified Snapshot) Source #
(MonadReader RepoLayout m, MonadError DeserializationError m, ReportSchemaErrors m) => FromJSON m Snapshot Source # |
Instance details Defined in Hackage.Security.TUF.Snapshot Methods fromJSON :: JSValue -> m Snapshot Source #
MonadReader RepoLayout m => ToJSON m Snapshot Source # |
Instance details Defined in Hackage.Security.TUF.Snapshot Methods toJSON :: Snapshot -> m JSValue Source #
(MonadKeys m, MonadReader RepoLayout m) => FromJSON m (Signed Snapshot) Source # |
Instance details Defined in Hackage.Security.TUF.Snapshot Methods fromJSON :: JSValue -> m (Signed Snapshot) Source #

data Targets Source #

Target metadata

Most target files do not need expiry dates because they are not subject to change (and hence attacks like freeze attacks are not a concern).

Constructors

Targets |

Fields

- targetsVersion :: FileVersion
- targetsExpires :: FileExpires
- targetsTargets :: FileMap
- targetsDelegations :: Maybe Delegations

#### Instances

Instances details

Show Targets Source # |
Instance details Defined in Hackage.Security.TUF.Targets Methods showsPrec :: Int -> Targets -> ShowS Source # show :: Targets -> String Source # showList :: [Targets] -> ShowS Source #
HasHeader Targets Source # |
Instance details Defined in Hackage.Security.TUF.Targets Methods fileExpires :: Lens' Targets FileExpires Source # fileVersion :: Lens' Targets FileVersion Source #
MonadKeys m => FromJSON m Targets Source # |
Instance details Defined in Hackage.Security.TUF.Targets Methods fromJSON :: JSValue -> m Targets Source #
Monad m => ToJSON m Targets Source # |
Instance details Defined in Hackage.Security.TUF.Targets Methods toJSON :: Targets -> m JSValue Source #
MonadKeys m => FromJSON m (Signed Targets) Source # |
Instance details Defined in Hackage.Security.TUF.Targets Methods fromJSON :: JSValue -> m (Signed Targets) Source #

data Timestamp Source #

Constructors

Timestamp |

Fields

- timestampVersion :: FileVersion
- timestampExpires :: FileExpires
- timestampInfoSnapshot :: FileInfo

#### Instances

Instances details

HasHeader Timestamp Source # |
Instance details Defined in Hackage.Security.TUF.Timestamp Methods fileExpires :: Lens' Timestamp FileExpires Source # fileVersion :: Lens' Timestamp FileVersion Source #
VerifyRole Timestamp Source # |
Instance details Defined in Hackage.Security.Trusted Methods verifyRole :: Trusted Root -> TargetPath -> Maybe FileVersion -> Maybe UTCTime -> Signed Timestamp -> Either VerificationError (SignaturesVerified Timestamp) Source #
(MonadReader RepoLayout m, MonadError DeserializationError m, ReportSchemaErrors m) => FromJSON m Timestamp Source # |
Instance details Defined in Hackage.Security.TUF.Timestamp Methods fromJSON :: JSValue -> m Timestamp Source #
MonadReader RepoLayout m => ToJSON m Timestamp Source # |
Instance details Defined in Hackage.Security.TUF.Timestamp Methods toJSON :: Timestamp -> m JSValue Source #
(MonadKeys m, MonadReader RepoLayout m) => FromJSON m (Signed Timestamp) Source # |
Instance details Defined in Hackage.Security.TUF.Timestamp Methods fromJSON :: JSValue -> m (Signed Timestamp) Source #

newtype FileLength Source #

File length

Having verified file length information means we can protect against endless data attacks and similar.

Constructors

FileLength |

Fields

- fileLength :: Int54

#### Instances

Instances details

Show FileLength Source # |
Instance details Defined in Hackage.Security.TUF.Common Methods showsPrec :: Int -> FileLength -> ShowS Source # show :: FileLength -> String Source # showList :: [FileLength] -> ShowS Source #
Eq FileLength Source # |
Instance details Defined in Hackage.Security.TUF.Common Methods (==) :: FileLength -> FileLength -> Bool Source # (/=) :: FileLength -> FileLength -> Bool Source #
Ord FileLength Source # |

Instance details

Defined in Hackage.Security.TUF.Common

Methods

compare :: FileLength -> FileLength -> Ordering Source #

(<) :: FileLength -> FileLength -> Bool Source #

(<=) :: FileLength -> FileLength -> Bool Source #

(>) :: FileLength -> FileLength -> Bool Source #

(>=) :: FileLength -> FileLength -> Bool Source #

max :: FileLength -> FileLength -> FileLength Source #

min :: FileLength -> FileLength -> FileLength Source #

ReportSchemaErrors m => FromJSON m FileLength Source # |
Instance details Defined in Hackage.Security.TUF.Common Methods fromJSON :: JSValue -> m FileLength Source #
Monad m => ToJSON m FileLength Source # |
Instance details Defined in Hackage.Security.TUF.Common Methods toJSON :: FileLength -> m JSValue Source #

newtype Hash Source #

File hash

Constructors

Hash String |

#### Instances

Instances details

Show Hash Source # |
Instance details Defined in Hackage.Security.TUF.Common Methods showsPrec :: Int -> Hash -> ShowS Source # show :: Hash -> String Source # showList :: [Hash] -> ShowS Source #
Eq Hash Source # |
Instance details Defined in Hackage.Security.TUF.Common Methods (==) :: Hash -> Hash -> Bool Source # (/=) :: Hash -> Hash -> Bool Source #
Ord Hash Source # |
Instance details Defined in Hackage.Security.TUF.Common Methods compare :: Hash -> Hash -> Ordering Source # (<) :: Hash -> Hash -> Bool Source # (<=) :: Hash -> Hash -> Bool Source # (>) :: Hash -> Hash -> Bool Source # (>=) :: Hash -> Hash -> Bool Source # max :: Hash -> Hash -> Hash Source # min :: Hash -> Hash -> Hash Source #
ReportSchemaErrors m => FromJSON m Hash Source # |
Instance details Defined in Hackage.Security.TUF.Common Methods fromJSON :: JSValue -> m Hash Source #
Monad m => ToJSON m Hash Source # |
Instance details Defined in Hackage.Security.TUF.Common Methods toJSON :: Hash -> m JSValue Source #

newtype KeyThreshold Source #

Key threshold

The key threshold is the minimum number of keys a document must be signed with. Key thresholds are specified in `RoleSpec` or `DelegationsSpec`.

Constructors

KeyThreshold Int54 |

#### Instances

Instances details

Show KeyThreshold Source # |
Instance details Defined in Hackage.Security.TUF.Common Methods showsPrec :: Int -> KeyThreshold -> ShowS Source # show :: KeyThreshold -> String Source # showList :: [KeyThreshold] -> ShowS Source #
Eq KeyThreshold Source # |
Instance details Defined in Hackage.Security.TUF.Common Methods (==) :: KeyThreshold -> KeyThreshold -> Bool Source # (/=) :: KeyThreshold -> KeyThreshold -> Bool Source #
Ord KeyThreshold Source # |

Instance details

Defined in Hackage.Security.TUF.Common

Methods

compare :: KeyThreshold -> KeyThreshold -> Ordering Source #

(<) :: KeyThreshold -> KeyThreshold -> Bool Source #

(<=) :: KeyThreshold -> KeyThreshold -> Bool Source #

(>) :: KeyThreshold -> KeyThreshold -> Bool Source #

(>=) :: KeyThreshold -> KeyThreshold -> Bool Source #

max :: KeyThreshold -> KeyThreshold -> KeyThreshold Source #

min :: KeyThreshold -> KeyThreshold -> KeyThreshold Source #

ReportSchemaErrors m => FromJSON m KeyThreshold Source # |
Instance details Defined in Hackage.Security.TUF.Common Methods fromJSON :: JSValue -> m KeyThreshold Source #
Monad m => ToJSON m KeyThreshold Source # |
Instance details Defined in Hackage.Security.TUF.Common Methods toJSON :: KeyThreshold -> m JSValue Source #

data HashFn Source #

Constructors

HashFnSHA256 |
HashFnMD5 |

#### Instances

Instances details

Show HashFn Source # |
Instance details Defined in Hackage.Security.TUF.FileInfo Methods showsPrec :: Int -> HashFn -> ShowS Source # show :: HashFn -> String Source # showList :: [HashFn] -> ShowS Source #
Eq HashFn Source # |
Instance details Defined in Hackage.Security.TUF.FileInfo Methods (==) :: HashFn -> HashFn -> Bool Source # (/=) :: HashFn -> HashFn -> Bool Source #
Ord HashFn Source # |
Instance details Defined in Hackage.Security.TUF.FileInfo Methods compare :: HashFn -> HashFn -> Ordering Source # (<) :: HashFn -> HashFn -> Bool Source # (<=) :: HashFn -> HashFn -> Bool Source # (>) :: HashFn -> HashFn -> Bool Source # (>=) :: HashFn -> HashFn -> Bool Source # max :: HashFn -> HashFn -> HashFn Source # min :: HashFn -> HashFn -> HashFn Source #
ReportSchemaErrors m => FromObjectKey m HashFn Source # |
Instance details Defined in Hackage.Security.TUF.FileInfo Methods fromObjectKey :: String -> m (Maybe HashFn) Source #
Monad m => ToObjectKey m HashFn Source # |
Instance details Defined in Hackage.Security.TUF.FileInfo Methods toObjectKey :: HashFn -> m String Source #

fileInfo :: ByteString -> FileInfo Source #

Compute `FileInfo`

TODO: Currently this will load the entire input bytestring into memory. We need to make this incremental, by computing the length and all hashes in a single traversal over the input.

computeFileInfo :: FsRoot root => Path root -> IO FileInfo Source #

Compute `FileInfo`

compareTrustedFileInfo Source #

Arguments

:: FileInfo | expected (from trusted TUF files)
-> FileInfo | actual (from `fileInfo` on target file)
-> Bool |

Compare the expected trusted file info against the actual file info of a target file.

This should be used only when the `FileInfo` is already known. If we want to compare known `FileInfo` against a file on disk we should delay until we have confirmed that the file lengths match (see `downloadedVerify`).

knownFileInfoEqual :: FileInfo -> FileInfo -> Bool Source #

fileInfoSHA256 :: FileInfo -> Maybe Hash Source #

Extract SHA256 hash from `FileInfo` (if present)

class HasHeader a where Source #

Methods

fileExpires :: Lens' a FileExpires Source #

File expiry date

fileVersion :: Lens' a FileVersion Source #

File version (monotonically increasing counter)

#### Instances

Instances details

HasHeader Header Source # |
Instance details Defined in Hackage.Security.TUF.Header Methods fileExpires :: Lens' Header FileExpires Source # fileVersion :: Lens' Header FileVersion Source #
HasHeader Mirrors Source # |
Instance details Defined in Hackage.Security.TUF.Mirrors Methods fileExpires :: Lens' Mirrors FileExpires Source # fileVersion :: Lens' Mirrors FileVersion Source #
HasHeader Root Source # |
Instance details Defined in Hackage.Security.TUF.Root Methods fileExpires :: Lens' Root FileExpires Source # fileVersion :: Lens' Root FileVersion Source #
HasHeader Snapshot Source # |
Instance details Defined in Hackage.Security.TUF.Snapshot Methods fileExpires :: Lens' Snapshot FileExpires Source # fileVersion :: Lens' Snapshot FileVersion Source #
HasHeader Targets Source # |
Instance details Defined in Hackage.Security.TUF.Targets Methods fileExpires :: Lens' Targets FileExpires Source # fileVersion :: Lens' Targets FileVersion Source #
HasHeader Timestamp Source # |
Instance details Defined in Hackage.Security.TUF.Timestamp Methods fileExpires :: Lens' Timestamp FileExpires Source # fileVersion :: Lens' Timestamp FileVersion Source #

newtype FileVersion Source #

File version

The file version is a flat integer which must monotonically increase on every file update.

`Show` and `Read` instance are defined in terms of the underlying `Int` (this is used for example by Hackage during the backup process).

Constructors

FileVersion Int54 |

#### Instances

Instances details

Read FileVersion Source # |
Instance details Defined in Hackage.Security.TUF.Header Methods readsPrec :: Int -> ReadS FileVersion Source # readList :: ReadS [FileVersion] Source # readPrec :: ReadPrec FileVersion Source # readListPrec :: ReadPrec [FileVersion] Source #
Show FileVersion Source # |
Instance details Defined in Hackage.Security.TUF.Header Methods showsPrec :: Int -> FileVersion -> ShowS Source # show :: FileVersion -> String Source # showList :: [FileVersion] -> ShowS Source #
Eq FileVersion Source # |
Instance details Defined in Hackage.Security.TUF.Header Methods (==) :: FileVersion -> FileVersion -> Bool Source # (/=) :: FileVersion -> FileVersion -> Bool Source #
Ord FileVersion Source # |

Instance details

Defined in Hackage.Security.TUF.Header

Methods

compare :: FileVersion -> FileVersion -> Ordering Source #

(<) :: FileVersion -> FileVersion -> Bool Source #

(<=) :: FileVersion -> FileVersion -> Bool Source #

(>) :: FileVersion -> FileVersion -> Bool Source #

(>=) :: FileVersion -> FileVersion -> Bool Source #

max :: FileVersion -> FileVersion -> FileVersion Source #

min :: FileVersion -> FileVersion -> FileVersion Source #

ReportSchemaErrors m => FromJSON m FileVersion Source # |
Instance details Defined in Hackage.Security.TUF.Header Methods fromJSON :: JSValue -> m FileVersion Source #
Monad m => ToJSON m FileVersion Source # |
Instance details Defined in Hackage.Security.TUF.Header Methods toJSON :: FileVersion -> m JSValue Source #

newtype FileExpires Source #

File expiry date

A `Nothing` value here means no expiry. That makes it possible to set some files to never expire. (Note that not having the Maybe in the type here still allows that, because you could set an expiry date 2000 years into the future. By having the Maybe here we avoid the _need_ for such encoding issues.)

Constructors

FileExpires (Maybe UTCTime) |

#### Instances

Instances details

Show FileExpires Source # |
Instance details Defined in Hackage.Security.TUF.Header Methods showsPrec :: Int -> FileExpires -> ShowS Source # show :: FileExpires -> String Source # showList :: [FileExpires] -> ShowS Source #
Eq FileExpires Source # |
Instance details Defined in Hackage.Security.TUF.Header Methods (==) :: FileExpires -> FileExpires -> Bool Source # (/=) :: FileExpires -> FileExpires -> Bool Source #
Ord FileExpires Source # |

Instance details

Defined in Hackage.Security.TUF.Header

Methods

compare :: FileExpires -> FileExpires -> Ordering Source #

(<) :: FileExpires -> FileExpires -> Bool Source #

(<=) :: FileExpires -> FileExpires -> Bool Source #

(>) :: FileExpires -> FileExpires -> Bool Source #

(>=) :: FileExpires -> FileExpires -> Bool Source #

max :: FileExpires -> FileExpires -> FileExpires Source #

min :: FileExpires -> FileExpires -> FileExpires Source #

ReportSchemaErrors m => FromJSON m FileExpires Source # |
Instance details Defined in Hackage.Security.TUF.Header Methods fromJSON :: JSValue -> m FileExpires Source #
Monad m => ToJSON m FileExpires Source # |
Instance details Defined in Hackage.Security.TUF.Header Methods toJSON :: FileExpires -> m JSValue Source #

expiresInDays :: UTCTime -> Integer -> FileExpires Source #

expiresNever :: FileExpires Source #

isExpired :: UTCTime -> FileExpires -> Bool Source #

versionInitial :: FileVersion Source #

versionIncrement :: FileVersion -> FileVersion Source #

data CacheLayout Source #

Location of the various files we cache

Although the generic TUF algorithms do not care how we organize the cache, we nonetheless specify this here because as long as there are tools which access files in the cache directly we need to define the cache layout. See also comments for `defaultCacheLayout`.

Constructors

CacheLayout |

Fields

- cacheLayoutRoot :: CachePath

  TUF root metadata

- cacheLayoutTimestamp :: CachePath

  TUF timestamp

- cacheLayoutSnapshot :: CachePath

  TUF snapshot

- cacheLayoutMirrors :: CachePath

  TUF mirrors list

- cacheLayoutIndexTar :: CachePath

  Uncompressed index tarball

- cacheLayoutIndexIdx :: CachePath

  Index to the uncompressed index tarball

- cacheLayoutIndexTarGz :: CachePath

  Compressed index tarball

  We cache both the compressed and the uncompressed tarballs, because incremental updates happen through the compressed tarball, but reads happen through the uncompressed one (with the help of the tarball index).

cabalCacheLayout :: CacheLayout Source #

The cache layout cabal-install uses

We cache the index as `cache/00-index.tar`; this is important because `cabal-install` expects to find it there (and does not currently go through the hackage-security library to get files from the index).

data IndexLayout Source #

Layout of the files within the index tarball

Constructors

IndexLayout |

Fields

- indexFileToPath :: forall dec. IndexFile dec -> IndexPath

  Translate an `IndexFile` to a path

- indexFileFromPath :: IndexPath -> Maybe (Some IndexFile)

  Parse an `FilePath`

hackageIndexLayout :: IndexLayout Source #

The layout of the index as maintained on Hackage

indexLayoutPkgMetadata :: IndexLayout -> PackageIdentifier -> IndexPath Source #

indexLayoutPkgCabal :: IndexLayout -> PackageIdentifier -> IndexPath Source #

indexLayoutPkgPrefs :: IndexLayout -> PackageName -> IndexPath Source #

data RepoLayout Source #

Layout of a repository

Constructors

RepoLayout |

Fields

- repoLayoutRoot :: RepoPath

  TUF root metadata

- repoLayoutTimestamp :: RepoPath

  TUF timestamp

- repoLayoutSnapshot :: RepoPath

  TUF snapshot

- repoLayoutMirrors :: RepoPath

  TUF mirrors list

- repoLayoutIndexTarGz :: RepoPath

  Compressed index tarball

- repoLayoutIndexTar :: RepoPath

  Uncompressed index tarball

- repoLayoutPkgTarGz :: PackageIdentifier -> RepoPath

  Path to the package tarball

#### Instances

Instances details

MonadReader RepoLayout ReadJSON_Keys_Layout Source # |
Instance details Defined in Hackage.Security.JSON Methods ask :: ReadJSON_Keys_Layout RepoLayout Source # local :: (RepoLayout -> RepoLayout) -> ReadJSON_Keys_Layout a -> ReadJSON_Keys_Layout a Source # reader :: (RepoLayout -> a) -> ReadJSON_Keys_Layout a Source #
MonadReader RepoLayout WriteJSON Source # |
Instance details Defined in Hackage.Security.JSON Methods ask :: WriteJSON RepoLayout Source # local :: (RepoLayout -> RepoLayout) -> WriteJSON a -> WriteJSON a Source # reader :: (RepoLayout -> a) -> WriteJSON a Source #

hackageRepoLayout :: RepoLayout Source #

The layout used on Hackage

cabalLocalRepoLayout :: RepoLayout Source #

Layout used by cabal for ("legacy") local repos

Obviously, such repos do not normally contain any of the TUF files, so their location is more or less arbitrary here.

data Mirror Source #

Definition of a mirror

NOTE: Unlike the TUF specification, we require that all mirrors must have the same format. That is, we omit `metapath` and `targetspath`.

Constructors

Mirror |

Fields

- mirrorUrlBase :: URI
- mirrorContent :: MirrorContent

#### Instances

Instances details

Show Mirror Source # |
Instance details Defined in Hackage.Security.TUF.Mirrors Methods showsPrec :: Int -> Mirror -> ShowS Source # show :: Mirror -> String Source # showList :: [Mirror] -> ShowS Source #
ReportSchemaErrors m => FromJSON m Mirror Source # |
Instance details Defined in Hackage.Security.TUF.Mirrors Methods fromJSON :: JSValue -> m Mirror Source #
Monad m => ToJSON m Mirror Source # |
Instance details Defined in Hackage.Security.TUF.Mirrors Methods toJSON :: Mirror -> m JSValue Source #

data MirrorContent Source #

Full versus partial mirrors

The TUF spec explicitly allows for partial mirrors, with the mirrors file specifying (through patterns) what is available from partial mirrors.

For now we only support full mirrors; if we wanted to add partial mirrors, we would add a second `MirrorPartial` constructor here with arguments corresponding to TUF's `metacontent` and `targetscontent` fields.

Constructors

MirrorFull |

#### Instances

Instances details

Show MirrorContent Source # |
Instance details Defined in Hackage.Security.TUF.Mirrors Methods showsPrec :: Int -> MirrorContent -> ShowS Source # show :: MirrorContent -> String Source # showList :: [MirrorContent] -> ShowS Source #

type MirrorDescription = String Source #

describeMirror :: Mirror -> MirrorDescription Source #

Give a human-readable description of a particular mirror

(for use in error messages)

data RepoRoot Source #

The root of the repository

Repository roots can be anchored at a remote URL or a local directory.

Note that even for remote repos `RepoRoot` is (potentially) different from `Web` -- for a repository located at, say, `http://hackage.haskell.org` they happen to coincide, but for one location at `http://example.com/some/subdirectory` they do not.

#### Instances

Instances details

Pretty (Path RepoRoot) Source # |
Instance details Defined in Hackage.Security.TUF.Paths Methods pretty :: Path RepoRoot -> String Source #

type RepoPath = Path RepoRoot Source #

Paths relative to the root of the repository

anchorRepoPathLocally :: Path root -> RepoPath -> Path root Source #

anchorRepoPathRemotely :: Path Web -> RepoPath -> Path Web Source #

data IndexRoot Source #

The root of the index tarball

#### Instances

Instances details

Pretty (Path IndexRoot) Source # |
Instance details Defined in Hackage.Security.TUF.Paths Methods pretty :: Path IndexRoot -> String Source #

type IndexPath = Path IndexRoot Source #

Paths relative to the root of the index tarball

data CacheRoot Source #

The cache directory

#### Instances

Instances details

Pretty (Path CacheRoot) Source # |
Instance details Defined in Hackage.Security.TUF.Paths Methods pretty :: Path CacheRoot -> String Source #

type CachePath = Path CacheRoot Source #

anchorCachePath :: Path root -> CachePath -> Path root Source #

Anchor a cache path to the location of the cache

data Delegation Source #

A delegation

A delegation is a pair of a pattern and a replacement.

See `match` for an example.

Constructors

Delegation (Pattern a) (Replacement a) |

#### Instances

Instances details

Show Delegation Source # |
Instance details Defined in Hackage.Security.TUF.Patterns Methods showsPrec :: Int -> Delegation -> ShowS Source # show :: Delegation -> String Source # showList :: [Delegation] -> ShowS Source #
Lift Delegation Source # |
Instance details Defined in Hackage.Security.TUF.Patterns Methods lift :: Quote m => Delegation -> m Exp Source # liftTyped :: forall (m :: Type -> Type). Quote m => Delegation -> Code m Delegation Source #

data RootRoles Source #

Constructors

RootRoles |

Fields

- rootRolesRoot :: RoleSpec Root
- rootRolesSnapshot :: RoleSpec Snapshot
- rootRolesTargets :: RoleSpec Targets
- rootRolesTimestamp :: RoleSpec Timestamp
- rootRolesMirrors :: RoleSpec Mirrors

#### Instances

Instances details

MonadKeys m => FromJSON m RootRoles Source # |
Instance details Defined in Hackage.Security.TUF.Root Methods fromJSON :: JSValue -> m RootRoles Source #
Monad m => ToJSON m RootRoles Source # |
Instance details Defined in Hackage.Security.TUF.Root Methods toJSON :: RootRoles -> m JSValue Source #

data RoleSpec a Source #

Role specification

The phantom type indicates what kind of type this role is meant to verify.

Constructors

RoleSpec |

Fields

- roleSpecKeys :: [Some PublicKey]
- roleSpecThreshold :: KeyThreshold

#### Instances

Instances details

MonadKeys m => FromJSON m (RoleSpec a) Source # |
Instance details Defined in Hackage.Security.TUF.Root Methods fromJSON :: JSValue -> m (RoleSpec a) Source #
Monad m => ToJSON m (RoleSpec a) Source # |
Instance details Defined in Hackage.Security.TUF.Root Methods toJSON :: RoleSpec a -> m JSValue Source #
Show (RoleSpec a) Source # |
Instance details Defined in Hackage.Security.TUF.Root Methods showsPrec :: Int -> RoleSpec a -> ShowS Source # show :: RoleSpec a -> String Source # showList :: [RoleSpec a] -> ShowS Source #

newtype Signatures Source #

A list of signatures

Invariant: each signature must be made with a different key. We enforce this invariant for incoming untrusted data (`fromPreSignatures`) but not for lists of signatures that we create in code.

Constructors

Signatures [Signature] |

#### Instances

Instances details

MonadKeys m => FromJSON m Signatures Source # |
Instance details Defined in Hackage.Security.TUF.Signed Methods fromJSON :: JSValue -> m Signatures Source #
Monad m => ToJSON m Signatures Source # |
Instance details Defined in Hackage.Security.TUF.Signed Methods toJSON :: Signatures -> m JSValue Source #

unsigned :: a -> Signed a Source #

Create a new document without any signatures

withSignatures :: ToJSON WriteJSON a => RepoLayout -> [Some Key] -> a -> Signed a Source #

Sign a document

withSignatures' :: ToJSON Identity a => [Some Key] -> a -> Signed a Source #

Variation on `withSignatures` that doesn't need the repo layout

signRendered :: [Some Key] -> ByteString -> Signatures Source #

Construct signatures for already rendered value

verifySignature :: ByteString -> Signature -> Bool Source #

signedFromJSON :: (MonadKeys m, FromJSON m a) => JSValue -> m (Signed a) Source #

General FromJSON instance for signed datatypes

We don't give a general FromJSON instance for Signed because for some datatypes we need to do something special (datatypes where we need to read key environments); for instance, see the "Signed Root" instance.

verifySignatures :: JSValue -> Signatures -> Bool Source #

Signature verification

NOTES: 1. By definition, the signature must be verified against the canonical JSON format. This means we _must_ parse and then pretty print (as we do here) because the document as stored may or may not be in canonical format. 2. However, it is important that we NOT translate from the JSValue to whatever internal datatype we are using and then back to JSValue, because that may not roundtrip: we must allow for additional fields in the JSValue that we ignore (and would therefore lose when we attempt to roundtrip). 3. We verify that all signatures are valid, but we cannot verify (here) that these signatures are signed with the right key, or that we have a sufficient number of signatures. This will be the responsibility of the calling code.

data UninterpretedSignatures a Source #

File with uninterpreted signatures

Sometimes we want to be able to read a file without interpreting the signatures (that is, resolving the key IDs) or doing any kind of checks on them. One advantage of this is that this allows us to read many file types without any key environment at all, which is sometimes useful.

Constructors

UninterpretedSignatures |

Fields

- uninterpretedSigned :: a
- uninterpretedSignatures :: [PreSignature]

#### Instances

Instances details

(ReportSchemaErrors m, FromJSON m a) => FromJSON m (UninterpretedSignatures a) Source # |
Instance details Defined in Hackage.Security.TUF.Signed Methods fromJSON :: JSValue -> m (UninterpretedSignatures a) Source #
(Monad m, ToJSON m a) => ToJSON m (UninterpretedSignatures a) Source # |
Instance details Defined in Hackage.Security.TUF.Signed Methods toJSON :: UninterpretedSignatures a -> m JSValue Source #
Show a => Show (UninterpretedSignatures a) Source # |
Instance details Defined in Hackage.Security.TUF.Signed Methods showsPrec :: Int -> UninterpretedSignatures a -> ShowS Source # show :: UninterpretedSignatures a -> String Source # showList :: [UninterpretedSignatures a] -> ShowS Source #

data PreSignature Source #

A signature with a key ID (rather than an actual key)

This corresponds precisely to the TUF representation of a signature.

Constructors

PreSignature |

Fields

- presignature :: ByteString
- presigMethod :: Some KeyType
- presigKeyId :: KeyId

#### Instances

Instances details

Show PreSignature Source # |
Instance details Defined in Hackage.Security.TUF.Signed Methods showsPrec :: Int -> PreSignature -> ShowS Source # show :: PreSignature -> String Source # showList :: [PreSignature] -> ShowS Source #
ReportSchemaErrors m => FromJSON m PreSignature Source # |
Instance details Defined in Hackage.Security.TUF.Signed Methods fromJSON :: JSValue -> m PreSignature Source #
Monad m => ToJSON m PreSignature Source # |
Instance details Defined in Hackage.Security.TUF.Signed Methods toJSON :: PreSignature -> m JSValue Source #

fromPreSignature :: MonadKeys m => PreSignature -> m Signature Source #

Convert a pre-signature to a signature

Verifies that the key type matches the advertised method.

fromPreSignatures :: MonadKeys m => [PreSignature] -> m Signatures Source #

Convert a list of `PreSignature`s to a list of `Signature`s

This verifies the invariant that all signatures are made with different keys. We do this on the presignatures rather than the signatures so that we can do the check on key IDs, rather than keys (the latter don't have an Ord instance).

toPreSignature :: Signature -> PreSignature Source #

Convert signature to pre-signature

toPreSignatures :: Signatures -> [PreSignature] Source #

Convert list of pre-signatures to a list of signatures

data Delegations Source #

Delegations

Much like the Root datatype, this must have an invariant that ALL used keys (apart from the global keys, which are in the root key environment) must be listed in `delegationsKeys`.

Constructors

Delegations |

Fields

- delegationsKeys :: KeyEnv
- delegationsRoles :: [DelegationSpec]

#### Instances

Instances details

Show Delegations Source # |
Instance details Defined in Hackage.Security.TUF.Targets Methods showsPrec :: Int -> Delegations -> ShowS Source # show :: Delegations -> String Source # showList :: [Delegations] -> ShowS Source #
MonadKeys m => FromJSON m Delegations Source # |
Instance details Defined in Hackage.Security.TUF.Targets Methods fromJSON :: JSValue -> m Delegations Source #
Monad m => ToJSON m Delegations Source # |
Instance details Defined in Hackage.Security.TUF.Targets Methods toJSON :: Delegations -> m JSValue Source #

data DelegationSpec Source #

Delegation specification

NOTE: This is a close analogue of `RoleSpec`.

Constructors

DelegationSpec |

Fields

- delegationSpecKeys :: [Some PublicKey]
- delegationSpecThreshold :: KeyThreshold
- delegation :: Delegation

#### Instances

Instances details

Show DelegationSpec Source # |
Instance details Defined in Hackage.Security.TUF.Targets Methods showsPrec :: Int -> DelegationSpec -> ShowS Source # show :: DelegationSpec -> String Source # showList :: [DelegationSpec] -> ShowS Source #
MonadKeys m => FromJSON m DelegationSpec Source # |
Instance details Defined in Hackage.Security.TUF.Targets Methods fromJSON :: JSValue -> m DelegationSpec Source #
Monad m => ToJSON m DelegationSpec Source # |
Instance details Defined in Hackage.Security.TUF.Targets Methods toJSON :: DelegationSpec -> m JSValue Source #

targetsLookup :: TargetPath -> Targets -> Maybe FileInfo Source #

data Key a where Source #

Constructors

KeyEd25519 :: PublicKey -> SecretKey -> Key Ed25519 |

#### Instances

Instances details

HasKeyId Key Source # |
Instance details Defined in Hackage.Security.Key Methods keyId :: Key typ -> KeyId Source #
SomeEq Key Source # |
Instance details Defined in Hackage.Security.Key Methods someEq :: DictEq (Key a) Source #
SomeShow Key Source # |
Instance details Defined in Hackage.Security.Key Methods someShow :: DictShow (Key a) Source #
ReportSchemaErrors m => FromJSON m (Some Key) Source # |
Instance details Defined in Hackage.Security.Key Methods fromJSON :: JSValue -> m (Some Key) Source #
Monad m => ToJSON m (Key typ) Source # |
Instance details Defined in Hackage.Security.Key Methods toJSON :: Key typ -> m JSValue Source #
Monad m => ToJSON m (Some Key) Source # |
Instance details Defined in Hackage.Security.Key Methods toJSON :: Some Key -> m JSValue Source #
Show (Key typ) Source # |
Instance details Defined in Hackage.Security.Key Methods showsPrec :: Int -> Key typ -> ShowS Source # show :: Key typ -> String Source # showList :: [Key typ] -> ShowS Source #
Eq (Key typ) Source # |
Instance details Defined in Hackage.Security.Key Methods (==) :: Key typ -> Key typ -> Bool Source # (/=) :: Key typ -> Key typ -> Bool Source #

sign :: PrivateKey typ -> ByteString -> ByteString Source #

Sign a bytestring and return the signature

TODO: It is unfortunate that we have to convert to a strict bytestring for ed25519

data PublicKey a where Source #

Constructors

PublicKeyEd25519 :: PublicKey -> PublicKey Ed25519 |

#### Instances

Instances details

HasKeyId PublicKey Source # |
Instance details Defined in Hackage.Security.Key Methods keyId :: PublicKey typ -> KeyId Source #
SomeEq PublicKey Source # |
Instance details Defined in Hackage.Security.Key Methods someEq :: DictEq (PublicKey a) Source #
SomeShow PublicKey Source # |
Instance details Defined in Hackage.Security.Key Methods someShow :: DictShow (PublicKey a) Source #
ReportSchemaErrors m => FromJSON m (Some PublicKey) Source # |
Instance details Defined in Hackage.Security.Key Methods fromJSON :: JSValue -> m (Some PublicKey) Source #
Monad m => ToJSON m (PublicKey typ) Source # |
Instance details Defined in Hackage.Security.Key Methods toJSON :: PublicKey typ -> m JSValue Source #
Monad m => ToJSON m (Some PublicKey) Source # |
Instance details Defined in Hackage.Security.Key Methods toJSON :: Some PublicKey -> m JSValue Source #
Show (PublicKey typ) Source # |
Instance details Defined in Hackage.Security.Key Methods showsPrec :: Int -> PublicKey typ -> ShowS Source # show :: PublicKey typ -> String Source # showList :: [PublicKey typ] -> ShowS Source #
Eq (PublicKey typ) Source # |
Instance details Defined in Hackage.Security.Key Methods (==) :: PublicKey typ -> PublicKey typ -> Bool Source # (/=) :: PublicKey typ -> PublicKey typ -> Bool Source #

verify :: PublicKey typ -> ByteString -> ByteString -> Bool Source #

data Ed25519 Source #

data PrivateKey a where Source #

Constructors

PrivateKeyEd25519 :: SecretKey -> PrivateKey Ed25519 |

#### Instances

Instances details

SomeEq PrivateKey Source # |
Instance details Defined in Hackage.Security.Key Methods someEq :: DictEq (PrivateKey a) Source #
SomeShow PrivateKey Source # |
Instance details Defined in Hackage.Security.Key Methods someShow :: DictShow (PrivateKey a) Source #
Show (PrivateKey typ) Source # |
Instance details Defined in Hackage.Security.Key Methods showsPrec :: Int -> PrivateKey typ -> ShowS Source # show :: PrivateKey typ -> String Source # showList :: [PrivateKey typ] -> ShowS Source #
Eq (PrivateKey typ) Source # |
Instance details Defined in Hackage.Security.Key Methods (==) :: PrivateKey typ -> PrivateKey typ -> Bool Source # (/=) :: PrivateKey typ -> PrivateKey typ -> Bool Source #

data KeyType typ where Source #

Constructors

KeyTypeEd25519 :: KeyType Ed25519 |

#### Instances

Instances details

SomeEq KeyType Source # |
Instance details Defined in Hackage.Security.Key Methods someEq :: DictEq (KeyType a) Source #
SomeShow KeyType Source # |
Instance details Defined in Hackage.Security.Key Methods someShow :: DictShow (KeyType a) Source #
ReportSchemaErrors m => FromJSON m (Some KeyType) Source # |
Instance details Defined in Hackage.Security.Key Methods fromJSON :: JSValue -> m (Some KeyType) Source #
Monad m => ToJSON m (KeyType typ) Source # |
Instance details Defined in Hackage.Security.Key Methods toJSON :: KeyType typ -> m JSValue Source #
Monad m => ToJSON m (Some KeyType) Source # |
Instance details Defined in Hackage.Security.Key Methods toJSON :: Some KeyType -> m JSValue Source #
Show (KeyType typ) Source # |
Instance details Defined in Hackage.Security.Key Methods showsPrec :: Int -> KeyType typ -> ShowS Source # show :: KeyType typ -> String Source # showList :: [KeyType typ] -> ShowS Source #
Eq (KeyType typ) Source # |
Instance details Defined in Hackage.Security.Key Methods (==) :: KeyType typ -> KeyType typ -> Bool Source # (/=) :: KeyType typ -> KeyType typ -> Bool Source #

somePublicKey :: Some Key -> Some PublicKey Source #

somePublicKeyType :: Some PublicKey -> Some KeyType Source #

someKeyId :: forall (key :: Type -> Type). HasKeyId key => Some key -> KeyId Source #

publicKey :: Key a -> PublicKey a Source #

privateKey :: Key a -> PrivateKey a Source #

createKey :: KeyType key -> IO (Key key) Source #

createKey' :: KeyType key -> IO (Some Key) Source #

newtype KeyId Source #

The key ID of a key, by definition, is the hexdigest of the SHA-256 hash of the canonical JSON form of the key where the private object key is excluded.

NOTE: The FromJSON and ToJSON instances for KeyId are intentionally omitted. Use writeKeyAsId instead.

Constructors

KeyId |

Fields

- keyIdString :: String

#### Instances

Instances details

Show KeyId Source # |
Instance details Defined in Hackage.Security.Key Methods showsPrec :: Int -> KeyId -> ShowS Source # show :: KeyId -> String Source # showList :: [KeyId] -> ShowS Source #
Eq KeyId Source # |
Instance details Defined in Hackage.Security.Key Methods (==) :: KeyId -> KeyId -> Bool Source # (/=) :: KeyId -> KeyId -> Bool Source #
Ord KeyId Source # |
Instance details Defined in Hackage.Security.Key Methods compare :: KeyId -> KeyId -> Ordering Source # (<) :: KeyId -> KeyId -> Bool Source # (<=) :: KeyId -> KeyId -> Bool Source # (>) :: KeyId -> KeyId -> Bool Source # (>=) :: KeyId -> KeyId -> Bool Source # max :: KeyId -> KeyId -> KeyId Source # min :: KeyId -> KeyId -> KeyId Source #
Monad m => FromObjectKey m KeyId Source # |
Instance details Defined in Hackage.Security.Key Methods fromObjectKey :: String -> m (Maybe KeyId) Source #
Monad m => ToObjectKey m KeyId Source # |
Instance details Defined in Hackage.Security.Key Methods toObjectKey :: KeyId -> m String Source #

class HasKeyId (key :: Type -> Type) where Source #

Compute the key ID of a key

Methods

keyId :: key typ -> KeyId Source #

#### Instances

Instances details

HasKeyId Key Source # |
Instance details Defined in Hackage.Security.Key Methods keyId :: Key typ -> KeyId Source #
HasKeyId PublicKey Source # |
Instance details Defined in Hackage.Security.Key Methods keyId :: PublicKey typ -> KeyId Source #

trusted :: Trusted a -> a Source #

## We only a few bits from .Repository

data Repository (down :: Type -> Type) Source #

Repository

This is an abstract representation of a repository. It simply provides a way to download metafiles and target files, without specifying how this is done. For instance, for a local repository this could just be doing a file read, whereas for remote repositories this could be using any kind of HTTP client.

#### Instances

Instances details

Show (Repository down) Source # |
Instance details Defined in Hackage.Security.Client.Repository Methods showsPrec :: Int -> Repository down -> ShowS Source # show :: Repository down -> String Source # showList :: [Repository down] -> ShowS Source #

class DownloadedFile (down :: Type -> Type) where Source #

Methods

downloadedVerify :: down a -> Trusted FileInfo -> IO Bool Source #

Verify a download file

downloadedRead :: down Metadata -> IO ByteString Source #

Read the file we just downloaded into memory

We never read binary data, only metadata.

downloadedCopyTo :: down a -> Path Absolute -> IO () Source #

Copy a downloaded file to its destination

#### Instances

Instances details

DownloadedFile LocalFile Source # |
Instance details Defined in Hackage.Security.Client.Repository.Local Methods downloadedVerify :: LocalFile a -> Trusted FileInfo -> IO Bool Source # downloadedRead :: LocalFile Metadata -> IO ByteString Source # downloadedCopyTo :: LocalFile a -> Path Absolute -> IO () Source #
DownloadedFile RemoteTemp Source # |
Instance details Defined in Hackage.Security.Client.Repository.Remote Methods downloadedVerify :: RemoteTemp a -> Trusted FileInfo -> IO Bool Source # downloadedRead :: RemoteTemp Metadata -> IO ByteString Source # downloadedCopyTo :: RemoteTemp a -> Path Absolute -> IO () Source #

data SomeRemoteError where Source #

Repository-specific exceptions

For instance, for repositories using HTTP this might correspond to a 404; for local repositories this might correspond to file-not-found, etc.

Constructors

SomeRemoteError :: forall e. Exception e => e -> SomeRemoteError |

#### Instances

Instances details

Exception SomeRemoteError Source # |
Instance details Defined in Hackage.Security.Client.Repository Methods toException :: SomeRemoteError -> SomeException Source # fromException :: SomeException -> Maybe SomeRemoteError Source # displayException :: SomeRemoteError -> String Source # backtraceDesired :: SomeRemoteError -> Bool Source #
Show SomeRemoteError Source # |
Instance details Defined in Hackage.Security.Client.Repository Methods showsPrec :: Int -> SomeRemoteError -> ShowS Source # show :: SomeRemoteError -> String Source # showList :: [SomeRemoteError] -> ShowS Source #
Pretty SomeRemoteError Source # |
Instance details Defined in Hackage.Security.Client.Repository Methods pretty :: SomeRemoteError -> String Source #

data LogMessage Source #

Log messages

We use a `RemoteFile` rather than a `RepoPath` here because we might not have a `RepoPath` for the file that we were trying to download (that is, for example if the server does not provide an uncompressed tarball, it doesn't make much sense to list the path to that non-existing uncompressed tarball).

Constructors

LogRootUpdated | Root information was updated This message is issued when the root information is updated as part of the normal check for updates procedure. If the root information is updated because of a verification error WarningVerificationError is issued instead.
LogVerificationError VerificationError | A verification error Verification errors can be temporary, and may be resolved later; hence these are just warnings. (Verification errors that cannot be resolved are thrown as exceptions.)
LogDownloading (RemoteFile fs typ) | Download a file from a repository
LogUpdating (RemoteFile fs Binary) | Incrementally updating a file from a repository
LogSelectedMirror MirrorDescription | Selected a particular mirror
LogCannotUpdate (RemoteFile fs Binary) UpdateFailure | Updating a file failed (we will instead download it whole)
LogMirrorFailed MirrorDescription SomeException | We got an exception with a particular mirror (we will try with a different mirror if any are available)
LogLockWait (Path Absolute) | This log event is triggered before invoking a filesystem lock operation that may block for a significant amount of time; once the possibly blocking call completes successfully, `LogLockWaitDone` will be emitted. Since: 0.6.0
LogLockWaitDone (Path Absolute) | Denotes completion of the operation that advertised a `LogLockWait` event Since: 0.6.0
LogUnlock (Path Absolute) | Denotes the filesystem lock previously acquired (signaled by `LogLockWait`) has been released. Since: 0.6.0

#### Instances

Instances details

Pretty LogMessage Source # |
Instance details Defined in Hackage.Security.Client.Repository Methods pretty :: LogMessage -> String Source #

# Exceptions

uncheckClientErrors :: ((Throws VerificationError, Throws SomeRemoteError, Throws InvalidPackageException) => IO a) -> IO a Source #

Re-throw all exceptions thrown by the client API as unchecked exceptions

data VerificationError Source #

Errors thrown during role validation

Constructors

VerificationErrorSignatures TargetPath Integer [KeyId] [KeyId] | Not enough signatures signed with the appropriate keys
VerificationErrorExpired TargetPath | The file is expired
VerificationErrorVersion TargetPath | The file version is less than the previous version
VerificationErrorFileInfo TargetPath | File information mismatch
VerificationErrorUnknownTarget TargetPath | We tried to lookup file information about a particular target file, but the information wasn't in the corresponding `targets.json` file.
VerificationErrorMissingSHA256 TargetPath | The metadata for the specified target is missing a SHA256
VerificationErrorDeserialization TargetPath DeserializationError | Some verification errors materialize as deserialization errors For example: if we try to deserialize a timestamp file but the timestamp key has been rolled over, deserialization of the file will fail with `DeserializationErrorUnknownKey`.
VerificationErrorLoop VerificationHistory | The spec stipulates that if a verification error occurs during the check for updates, we must download new root information and start over. However, we limit how often we attempt this. We record all verification errors that occurred before we gave up.

#### Instances

Instances details

Exception VerificationError Source # |
Instance details Defined in Hackage.Security.Trusted.TCB Methods toException :: VerificationError -> SomeException Source # fromException :: SomeException -> Maybe VerificationError Source # displayException :: VerificationError -> String Source # backtraceDesired :: VerificationError -> Bool Source #
Show VerificationError Source # |
Instance details Defined in Hackage.Security.Trusted.TCB Methods showsPrec :: Int -> VerificationError -> ShowS Source # show :: VerificationError -> String Source # showList :: [VerificationError] -> ShowS Source #
Pretty VerificationError Source # |
Instance details Defined in Hackage.Security.Trusted.TCB Methods pretty :: VerificationError -> String Source #

type VerificationHistory = [Either RootUpdated VerificationError] Source #

data RootUpdated Source #

Root metadata updated (as part of the normal update process)

Constructors

RootUpdated |

#### Instances

Instances details

Exception RootUpdated Source # |
Instance details Defined in Hackage.Security.Trusted.TCB Methods toException :: RootUpdated -> SomeException Source # fromException :: SomeException -> Maybe RootUpdated Source # displayException :: RootUpdated -> String Source # backtraceDesired :: RootUpdated -> Bool Source #
Show RootUpdated Source # |
Instance details Defined in Hackage.Security.Trusted.TCB Methods showsPrec :: Int -> RootUpdated -> ShowS Source # show :: RootUpdated -> String Source # showList :: [RootUpdated] -> ShowS Source #
Pretty RootUpdated Source # |
Instance details Defined in Hackage.Security.Trusted.TCB Methods pretty :: RootUpdated -> String Source #

data InvalidPackageException Source #

Constructors

InvalidPackageException PackageIdentifier |

#### Instances

Instances details

Exception InvalidPackageException Source # |
Instance details Defined in Hackage.Security.Client Methods toException :: InvalidPackageException -> SomeException Source # fromException :: SomeException -> Maybe InvalidPackageException Source # displayException :: InvalidPackageException -> String Source # backtraceDesired :: InvalidPackageException -> Bool Source #
Show InvalidPackageException Source # |
Instance details Defined in Hackage.Security.Client Methods showsPrec :: Int -> InvalidPackageException -> ShowS Source # show :: InvalidPackageException -> String Source # showList :: [InvalidPackageException] -> ShowS Source #
Pretty InvalidPackageException Source # |
Instance details Defined in Hackage.Security.Client Methods pretty :: InvalidPackageException -> String Source #

data InvalidFileInIndex Source #

Constructors

InvalidFileInIndex |

Fields

- invalidFileInIndex :: IndexFile dec
- invalidFileInIndexRaw :: ByteString
- invalidFileInIndexError :: DeserializationError

#### Instances

Instances details

Exception InvalidFileInIndex Source # |
Instance details Defined in Hackage.Security.Client Methods toException :: InvalidFileInIndex -> SomeException Source # fromException :: SomeException -> Maybe InvalidFileInIndex Source # displayException :: InvalidFileInIndex -> String Source # backtraceDesired :: InvalidFileInIndex -> Bool Source #
Show InvalidFileInIndex Source # |
Instance details Defined in Hackage.Security.Client Methods showsPrec :: Int -> InvalidFileInIndex -> ShowS Source # show :: InvalidFileInIndex -> String Source # showList :: [InvalidFileInIndex] -> ShowS Source #
Pretty InvalidFileInIndex Source # |
Instance details Defined in Hackage.Security.Client Methods pretty :: InvalidFileInIndex -> String Source #

data LocalFileCorrupted Source #

Constructors

LocalFileCorrupted DeserializationError |

#### Instances

Instances details

Exception LocalFileCorrupted Source # |
Instance details Defined in Hackage.Security.Client Methods toException :: LocalFileCorrupted -> SomeException Source # fromException :: SomeException -> Maybe LocalFileCorrupted Source # displayException :: LocalFileCorrupted -> String Source # backtraceDesired :: LocalFileCorrupted -> Bool Source #
Show LocalFileCorrupted Source # |
Instance details Defined in Hackage.Security.Client Methods showsPrec :: Int -> LocalFileCorrupted -> ShowS Source # show :: LocalFileCorrupted -> String Source # showList :: [LocalFileCorrupted] -> ShowS Source #
Pretty LocalFileCorrupted Source # |
Instance details Defined in Hackage.Security.Client Methods pretty :: LocalFileCorrupted -> String Source #