hackage-security-0.6.2.3: Hackage security library
Safe HaskellSafe-Inferred
LanguageHaskell2010

Hackage.Security.Client

Description

Main entry point into the Hackage Security framework for clients

Synopsis

Checking for updates

checkForUpdates #

Arguments

:: (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 #

Constructors

HasUpdates 
NoUpdates 

Instances

Instances details
Show HasUpdates # 
Instance details

Defined in Hackage.Security.Client

Methods

showsPrec :: Int -> HasUpdates -> ShowS

show :: HasUpdates -> String

showList :: [HasUpdates] -> ShowS

Eq HasUpdates # 
Instance details

Defined in Hackage.Security.Client

Methods

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

(/=) :: HasUpdates -> HasUpdates -> Bool

Ord HasUpdates # 
Instance details

Defined in Hackage.Security.Client

Downloading targets

downloadPackage #

Arguments

:: (Throws SomeRemoteError, Throws VerificationError, Throws InvalidPackageException) 
=> Repository down

Repository

-> PackageIdentifier

Package to download

-> Path Absolute

Destination (see also downloadPackage')

-> IO () 

Download a package

downloadPackage' #

Arguments

:: (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 #

Index directory

Constructors

Directory 

Fields

newtype DirectoryEntry #

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 # 
Instance details

Defined in Hackage.Security.Client

Methods

readsPrec :: Int -> ReadS DirectoryEntry

readList :: ReadS [DirectoryEntry]

readPrec :: ReadPrec DirectoryEntry

readListPrec :: ReadPrec [DirectoryEntry]

Show DirectoryEntry # 
Instance details

Defined in Hackage.Security.Client

Methods

showsPrec :: Int -> DirectoryEntry -> ShowS

show :: DirectoryEntry -> String

showList :: [DirectoryEntry] -> ShowS

Eq DirectoryEntry # 
Instance details

Defined in Hackage.Security.Client

Ord DirectoryEntry # 
Instance details

Defined in Hackage.Security.Client

getDirectory :: Repository down -> IO Directory #

Read the Hackage index directory

Should only be called after checkForUpdates.

data IndexFile :: * -> * where #

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 # 
Instance details

Defined in Hackage.Security.TUF.Layout.Index

SomeShow IndexFile # 
Instance details

Defined in Hackage.Security.TUF.Layout.Index

Show (IndexFile dec) # 
Instance details

Defined in Hackage.Security.TUF.Layout.Index

Methods

showsPrec :: Int -> IndexFile dec -> ShowS

show :: IndexFile dec -> String

showList :: [IndexFile dec] -> ShowS

Pretty (IndexFile dec) # 
Instance details

Defined in Hackage.Security.TUF.Layout.Index

Methods

pretty :: IndexFile dec -> String #

data IndexEntry dec #

Entry from the Hackage index; see withIndex.

Constructors

IndexEntry 

Fields

data IndexCallbacks #

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

withIndex :: Repository down -> (IndexCallbacks -> IO a) -> IO a #

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 :: Repository down -> IO Bool #

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

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

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

Types

newtype FileLength #

File length

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

Constructors

FileLength 

Fields

Instances

Instances details
Show FileLength # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

showsPrec :: Int -> FileLength -> ShowS

show :: FileLength -> String

showList :: [FileLength] -> ShowS

Eq FileLength # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

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

(/=) :: FileLength -> FileLength -> Bool

Ord FileLength # 
Instance details

Defined in Hackage.Security.TUF.Common

ReportSchemaErrors m => FromJSON m FileLength # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

fromJSON :: JSValue -> m FileLength #

Monad m => ToJSON m FileLength # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

toJSON :: FileLength -> m JSValue #

newtype Hash #

File hash

Constructors

Hash String 

Instances

Instances details
Show Hash # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

showsPrec :: Int -> Hash -> ShowS

show :: Hash -> String

showList :: [Hash] -> ShowS

Eq Hash # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

(==) :: Hash -> Hash -> Bool

(/=) :: Hash -> Hash -> Bool

Ord Hash # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

compare :: Hash -> Hash -> Ordering

(<) :: Hash -> Hash -> Bool

(<=) :: Hash -> Hash -> Bool

(>) :: Hash -> Hash -> Bool

(>=) :: Hash -> Hash -> Bool

max :: Hash -> Hash -> Hash

min :: Hash -> Hash -> Hash

ReportSchemaErrors m => FromJSON m Hash # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

fromJSON :: JSValue -> m Hash #

Monad m => ToJSON m Hash # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

toJSON :: Hash -> m JSValue #

newtype KeyThreshold #

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 # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

showsPrec :: Int -> KeyThreshold -> ShowS

show :: KeyThreshold -> String

showList :: [KeyThreshold] -> ShowS

Eq KeyThreshold # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

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

(/=) :: KeyThreshold -> KeyThreshold -> Bool

Ord KeyThreshold # 
Instance details

Defined in Hackage.Security.TUF.Common

ReportSchemaErrors m => FromJSON m KeyThreshold # 
Instance details

Defined in Hackage.Security.TUF.Common

Monad m => ToJSON m KeyThreshold # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

toJSON :: KeyThreshold -> m JSValue #

data FileInfo #

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.

Instances

Instances details
Show FileInfo # 
Instance details

Defined in Hackage.Security.TUF.FileInfo

Methods

showsPrec :: Int -> FileInfo -> ShowS

show :: FileInfo -> String

showList :: [FileInfo] -> ShowS

ReportSchemaErrors m => FromJSON m FileInfo # 
Instance details

Defined in Hackage.Security.TUF.FileInfo

Methods

fromJSON :: JSValue -> m FileInfo #

Monad m => ToJSON m FileInfo # 
Instance details

Defined in Hackage.Security.TUF.FileInfo

Methods

toJSON :: FileInfo -> m JSValue #

data HashFn #

Constructors

HashFnSHA256 
HashFnMD5 

Instances

Instances details
Show HashFn # 
Instance details

Defined in Hackage.Security.TUF.FileInfo

Methods

showsPrec :: Int -> HashFn -> ShowS

show :: HashFn -> String

showList :: [HashFn] -> ShowS

Eq HashFn # 
Instance details

Defined in Hackage.Security.TUF.FileInfo

Methods

(==) :: HashFn -> HashFn -> Bool

(/=) :: HashFn -> HashFn -> Bool

Ord HashFn # 
Instance details

Defined in Hackage.Security.TUF.FileInfo

Methods

compare :: HashFn -> HashFn -> Ordering

(<) :: HashFn -> HashFn -> Bool

(<=) :: HashFn -> HashFn -> Bool

(>) :: HashFn -> HashFn -> Bool

(>=) :: HashFn -> HashFn -> Bool

max :: HashFn -> HashFn -> HashFn

min :: HashFn -> HashFn -> HashFn

ReportSchemaErrors m => FromObjectKey m HashFn # 
Instance details

Defined in Hackage.Security.TUF.FileInfo

Methods

fromObjectKey :: String -> m (Maybe HashFn) #

Monad m => ToObjectKey m HashFn # 
Instance details

Defined in Hackage.Security.TUF.FileInfo

Methods

toObjectKey :: HashFn -> m String #

newtype Hash #

File hash

Constructors

Hash String 

Instances

Instances details
Show Hash # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

showsPrec :: Int -> Hash -> ShowS

show :: Hash -> String

showList :: [Hash] -> ShowS

Eq Hash # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

(==) :: Hash -> Hash -> Bool

(/=) :: Hash -> Hash -> Bool

Ord Hash # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

compare :: Hash -> Hash -> Ordering

(<) :: Hash -> Hash -> Bool

(<=) :: Hash -> Hash -> Bool

(>) :: Hash -> Hash -> Bool

(>=) :: Hash -> Hash -> Bool

max :: Hash -> Hash -> Hash

min :: Hash -> Hash -> Hash

ReportSchemaErrors m => FromJSON m Hash # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

fromJSON :: JSValue -> m Hash #

Monad m => ToJSON m Hash # 
Instance details

Defined in Hackage.Security.TUF.Common

Methods

toJSON :: Hash -> m JSValue #

Utility

fileInfo :: ByteString -> FileInfo #

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 #

Compute FileInfo

compareTrustedFileInfo #

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).

fileInfoSHA256 :: FileInfo -> Maybe Hash #

Extract SHA256 hash from FileInfo (if present)

Re-exports

data Int54 #

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
Data Int54 # 
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

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

toConstr :: Int54 -> Constr

dataTypeOf :: Int54 -> DataType

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

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

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

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

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

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

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

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

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

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

Storable Int54 # 
Instance details

Defined in Text.JSON.Canonical

Methods

sizeOf :: Int54 -> Int

alignment :: Int54 -> Int

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

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

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

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

peek :: Ptr Int54 -> IO Int54

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

Bits Int54 # 
Instance details

Defined in Text.JSON.Canonical

Methods

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

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

xor :: Int54 -> Int54 -> Int54

complement :: Int54 -> Int54

shift :: Int54 -> Int -> Int54

rotate :: Int54 -> Int -> Int54

zeroBits :: Int54

bit :: Int -> Int54

setBit :: Int54 -> Int -> Int54

clearBit :: Int54 -> Int -> Int54

complementBit :: Int54 -> Int -> Int54

testBit :: Int54 -> Int -> Bool

bitSizeMaybe :: Int54 -> Maybe Int

bitSize :: Int54 -> Int

isSigned :: Int54 -> Bool

shiftL :: Int54 -> Int -> Int54

unsafeShiftL :: Int54 -> Int -> Int54

shiftR :: Int54 -> Int -> Int54

unsafeShiftR :: Int54 -> Int -> Int54

rotateL :: Int54 -> Int -> Int54

rotateR :: Int54 -> Int -> Int54

popCount :: Int54 -> Int

FiniteBits Int54 # 
Instance details

Defined in Text.JSON.Canonical

Bounded Int54 # 
Instance details

Defined in Text.JSON.Canonical

Enum Int54 # 
Instance details

Defined in Text.JSON.Canonical

Ix Int54 # 
Instance details

Defined in Text.JSON.Canonical

Methods

range :: (Int54, Int54) -> [Int54]

index :: (Int54, Int54) -> Int54 -> Int

unsafeIndex :: (Int54, Int54) -> Int54 -> Int

inRange :: (Int54, Int54) -> Int54 -> Bool

rangeSize :: (Int54, Int54) -> Int

unsafeRangeSize :: (Int54, Int54) -> Int

Num Int54 # 
Instance details

Defined in Text.JSON.Canonical

Methods

(+) :: Int54 -> Int54 -> Int54

(-) :: Int54 -> Int54 -> Int54

(*) :: Int54 -> Int54 -> Int54

negate :: Int54 -> Int54

abs :: Int54 -> Int54

signum :: Int54 -> Int54

fromInteger :: Integer -> Int54

Read Int54 # 
Instance details

Defined in Text.JSON.Canonical

Methods

readsPrec :: Int -> ReadS Int54

readList :: ReadS [Int54]

readPrec :: ReadPrec Int54

readListPrec :: ReadPrec [Int54]

Integral Int54 # 
Instance details

Defined in Text.JSON.Canonical

Methods

quot :: Int54 -> Int54 -> Int54

rem :: Int54 -> Int54 -> Int54

div :: Int54 -> Int54 -> Int54

mod :: Int54 -> Int54 -> Int54

quotRem :: Int54 -> Int54 -> (Int54, Int54)

divMod :: Int54 -> Int54 -> (Int54, Int54)

toInteger :: Int54 -> Integer

Real Int54 # 
Instance details

Defined in Text.JSON.Canonical

Methods

toRational :: Int54 -> Rational

Show Int54 # 
Instance details

Defined in Text.JSON.Canonical

Methods

showsPrec :: Int -> Int54 -> ShowS

show :: Int54 -> String

showList :: [Int54] -> ShowS

PrintfArg Int54 # 
Instance details

Defined in Text.JSON.Canonical

Methods

formatArg :: Int54 -> FieldFormatter

parseFormat :: Int54 -> ModifierParser

Eq Int54 # 
Instance details

Defined in Text.JSON.Canonical

Methods

(==) :: Int54 -> Int54 -> Bool

(/=) :: Int54 -> Int54 -> Bool

Ord Int54 # 
Instance details

Defined in Text.JSON.Canonical

Methods

compare :: Int54 -> Int54 -> Ordering

(<) :: Int54 -> Int54 -> Bool

(<=) :: Int54 -> Int54 -> Bool

(>) :: Int54 -> Int54 -> Bool

(>=) :: Int54 -> Int54 -> Bool

max :: Int54 -> Int54 -> Int54

min :: Int54 -> Int54 -> Int54

ReportSchemaErrors m => FromJSON m Int54 # 
Instance details

Defined in Hackage.Security.Util.JSON

Methods

fromJSON :: JSValue -> m Int54 #

Monad m => ToJSON m Int54 # 
Instance details

Defined in Hackage.Security.Util.JSON

Methods

toJSON :: Int54 -> m JSValue #

data FileMap #

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 # 
Instance details

Defined in Hackage.Security.TUF.FileMap

Methods

showsPrec :: Int -> FileMap -> ShowS

show :: FileMap -> String

showList :: [FileMap] -> ShowS

ReportSchemaErrors m => FromJSON m FileMap # 
Instance details

Defined in Hackage.Security.TUF.FileMap

Methods

fromJSON :: JSValue -> m FileMap #

Monad m => ToJSON m FileMap # 
Instance details

Defined in Hackage.Security.TUF.FileMap

Methods

toJSON :: FileMap -> m JSValue #

data TargetPath #

Entries in FileMap either talk about the repository or the index

Instances

Instances details
Show TargetPath # 
Instance details

Defined in Hackage.Security.TUF.FileMap

Methods

showsPrec :: Int -> TargetPath -> ShowS

show :: TargetPath -> String

showList :: [TargetPath] -> ShowS

Eq TargetPath # 
Instance details

Defined in Hackage.Security.TUF.FileMap

Methods

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

(/=) :: TargetPath -> TargetPath -> Bool

Ord TargetPath # 
Instance details

Defined in Hackage.Security.TUF.FileMap

Pretty TargetPath # 
Instance details

Defined in Hackage.Security.TUF.FileMap

Methods

pretty :: TargetPath -> String #

ReportSchemaErrors m => FromObjectKey m TargetPath # 
Instance details

Defined in Hackage.Security.TUF.FileMap

Methods

fromObjectKey :: String -> m (Maybe TargetPath) #

Monad m => ToObjectKey m TargetPath # 
Instance details

Defined in Hackage.Security.TUF.FileMap

Methods

toObjectKey :: TargetPath -> m String #

data FileChange #

Constructors

FileChanged FileInfo

File got added or modified; we record the new file info

FileDeleted

File got deleted

Instances

Instances details
Show FileChange # 
Instance details

Defined in Hackage.Security.TUF.FileMap

Methods

showsPrec :: Int -> FileChange -> ShowS

show :: FileChange -> String

showList :: [FileChange] -> ShowS

class HasHeader a where #

Methods

fileExpires :: Lens' a FileExpires #

File expiry date

fileVersion :: Lens' a FileVersion #

File version (monotonically increasing counter)

newtype FileVersion #

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 # 
Instance details

Defined in Hackage.Security.TUF.Header

Methods

readsPrec :: Int -> ReadS FileVersion

readList :: ReadS [FileVersion]

readPrec :: ReadPrec FileVersion

readListPrec :: ReadPrec [FileVersion]

Show FileVersion # 
Instance details

Defined in Hackage.Security.TUF.Header

Methods

showsPrec :: Int -> FileVersion -> ShowS

show :: FileVersion -> String

showList :: [FileVersion] -> ShowS

Eq FileVersion # 
Instance details

Defined in Hackage.Security.TUF.Header

Methods

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

(/=) :: FileVersion -> FileVersion -> Bool

Ord FileVersion # 
Instance details

Defined in Hackage.Security.TUF.Header

ReportSchemaErrors m => FromJSON m FileVersion # 
Instance details

Defined in Hackage.Security.TUF.Header

Methods

fromJSON :: JSValue -> m FileVersion #

Monad m => ToJSON m FileVersion # 
Instance details

Defined in Hackage.Security.TUF.Header

Methods

toJSON :: FileVersion -> m JSValue #

newtype FileExpires #

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 # 
Instance details

Defined in Hackage.Security.TUF.Header

Methods

showsPrec :: Int -> FileExpires -> ShowS

show :: FileExpires -> String

showList :: [FileExpires] -> ShowS

Eq FileExpires # 
Instance details

Defined in Hackage.Security.TUF.Header

Methods

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

(/=) :: FileExpires -> FileExpires -> Bool

Ord FileExpires # 
Instance details

Defined in Hackage.Security.TUF.Header

ReportSchemaErrors m => FromJSON m FileExpires # 
Instance details

Defined in Hackage.Security.TUF.Header

Methods

fromJSON :: JSValue -> m FileExpires #

Monad m => ToJSON m FileExpires # 
Instance details

Defined in Hackage.Security.TUF.Header

Methods

toJSON :: FileExpires -> m JSValue #

data Header #

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

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

Instances

Instances details
HasHeader Header # 
Instance details

Defined in Hackage.Security.TUF.Header

ReportSchemaErrors m => FromJSON m Header # 
Instance details

Defined in Hackage.Security.TUF.Header

Methods

fromJSON :: JSValue -> m Header #

Utility

expiresInDays :: UTCTime -> Integer -> FileExpires #

isExpired :: UTCTime -> FileExpires -> Bool #

Cache layout

data CacheLayout #

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

cabalCacheLayout :: CacheLayout #

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).

Repository layout

data IndexLayout #

Layout of the files within the index tarball

Constructors

IndexLayout 

Fields

data IndexFile :: * -> * where #

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 # 
Instance details

Defined in Hackage.Security.TUF.Layout.Index

SomeShow IndexFile # 
Instance details

Defined in Hackage.Security.TUF.Layout.Index

Show (IndexFile dec) # 
Instance details

Defined in Hackage.Security.TUF.Layout.Index

Methods

showsPrec :: Int -> IndexFile dec -> ShowS

show :: IndexFile dec -> String

showList :: [IndexFile dec] -> ShowS

Pretty (IndexFile dec) # 
Instance details

Defined in Hackage.Security.TUF.Layout.Index

Methods

pretty :: IndexFile dec -> String #

hackageIndexLayout :: IndexLayout #

The layout of the index as maintained on Hackage

Utility

indexLayoutPkgMetadata :: IndexLayout -> PackageIdentifier -> IndexPath #

indexLayoutPkgCabal :: IndexLayout -> PackageIdentifier -> IndexPath #

Repository layout

data RepoLayout #

Layout of a repository

Constructors

RepoLayout 

Fields

Instances

Instances details
MonadReader RepoLayout ReadJSON_Keys_Layout 
Instance details

Defined in Hackage.Security.JSON

MonadReader RepoLayout WriteJSON 
Instance details

Defined in Hackage.Security.JSON

hackageRepoLayout :: RepoLayout #

The layout used on Hackage

cabalLocalRepoLayout :: RepoLayout #

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.

TUF types

data Mirrors #

Instances

Instances details
HasHeader Mirrors # 
Instance details

Defined in Hackage.Security.TUF.Mirrors

VerifyRole Mirrors # 
Instance details

Defined in Hackage.Security.Trusted

(MonadError DeserializationError m, ReportSchemaErrors m) => FromJSON m Mirrors # 
Instance details

Defined in Hackage.Security.TUF.Mirrors

Methods

fromJSON :: JSValue -> m Mirrors #

Monad m => ToJSON m Mirrors # 
Instance details

Defined in Hackage.Security.TUF.Mirrors

Methods

toJSON :: Mirrors -> m JSValue #

MonadKeys m => FromJSON m (Signed Mirrors) # 
Instance details

Defined in Hackage.Security.TUF.Mirrors

Methods

fromJSON :: JSValue -> m (Signed Mirrors) #

data Mirror #

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 

Instances

Instances details
Show Mirror # 
Instance details

Defined in Hackage.Security.TUF.Mirrors

Methods

showsPrec :: Int -> Mirror -> ShowS

show :: Mirror -> String

showList :: [Mirror] -> ShowS

ReportSchemaErrors m => FromJSON m Mirror # 
Instance details

Defined in Hackage.Security.TUF.Mirrors

Methods

fromJSON :: JSValue -> m Mirror #

Monad m => ToJSON m Mirror # 
Instance details

Defined in Hackage.Security.TUF.Mirrors

Methods

toJSON :: Mirror -> m JSValue #

data MirrorContent #

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 # 
Instance details

Defined in Hackage.Security.TUF.Mirrors

Methods

showsPrec :: Int -> MirrorContent -> ShowS

show :: MirrorContent -> String

showList :: [MirrorContent] -> ShowS

Utility

type MirrorDescription = String #

describeMirror :: Mirror -> MirrorDescription #

Give a human-readable description of a particular mirror

(for use in error messages)

Repository

data RepoRoot #

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) # 
Instance details

Defined in Hackage.Security.TUF.Paths

Methods

pretty :: Path RepoRoot -> String #

type RepoPath = Path RepoRoot #

Paths relative to the root of the repository

Index

data IndexRoot #

The root of the index tarball

Instances

Instances details
Pretty (Path IndexRoot) # 
Instance details

Defined in Hackage.Security.TUF.Paths

Methods

pretty :: Path IndexRoot -> String #

type IndexPath = Path IndexRoot #

Paths relative to the root of the index tarball

Cache

data CacheRoot #

The cache directory

Instances

Instances details
Pretty (Path CacheRoot) # 
Instance details

Defined in Hackage.Security.TUF.Paths

Methods

pretty :: Path CacheRoot -> String #

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

Anchor a cache path to the location of the cache

Datatypes

data Root #

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.)

Instances

Instances details
HasHeader Root # 
Instance details

Defined in Hackage.Security.TUF.Root

VerifyRole Root # 
Instance details

Defined in Hackage.Security.Trusted

Methods

verifyRole :: Trusted Root -> TargetPath -> Maybe FileVersion -> Maybe UTCTime -> Signed Root -> Either VerificationError (SignaturesVerified Root) #

Monad m => ToJSON m Root # 
Instance details

Defined in Hackage.Security.TUF.Root

Methods

toJSON :: Root -> m JSValue #

MonadKeys m => FromJSON m (Signed Root) #

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) #

data RootRoles #

Instances

Instances details
MonadKeys m => FromJSON m RootRoles # 
Instance details

Defined in Hackage.Security.TUF.Root

Methods

fromJSON :: JSValue -> m RootRoles #

Monad m => ToJSON m RootRoles # 
Instance details

Defined in Hackage.Security.TUF.Root

Methods

toJSON :: RootRoles -> m JSValue #

data RoleSpec a #

Role specification

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

Instances

Instances details
MonadKeys m => FromJSON m (RoleSpec a) # 
Instance details

Defined in Hackage.Security.TUF.Root

Methods

fromJSON :: JSValue -> m (RoleSpec a) #

Monad m => ToJSON m (RoleSpec a) # 
Instance details

Defined in Hackage.Security.TUF.Root

Methods

toJSON :: RoleSpec a -> m JSValue #

Show (RoleSpec a) # 
Instance details

Defined in Hackage.Security.TUF.Root

Methods

showsPrec :: Int -> RoleSpec a -> ShowS

show :: RoleSpec a -> String

showList :: [RoleSpec a] -> ShowS

TUF types

data Signed a #

Constructors

Signed 

Fields

Instances

Instances details
MonadKeys m => FromJSON m (Signed Mirrors) # 
Instance details

Defined in Hackage.Security.TUF.Mirrors

Methods

fromJSON :: JSValue -> m (Signed Mirrors) #

MonadKeys m => FromJSON m (Signed Root) #

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) #

(MonadKeys m, MonadReader RepoLayout m) => FromJSON m (Signed Snapshot) # 
Instance details

Defined in Hackage.Security.TUF.Snapshot

Methods

fromJSON :: JSValue -> m (Signed Snapshot) #

MonadKeys m => FromJSON m (Signed Targets) # 
Instance details

Defined in Hackage.Security.TUF.Targets

Methods

fromJSON :: JSValue -> m (Signed Targets) #

(MonadKeys m, MonadReader RepoLayout m) => FromJSON m (Signed Timestamp) # 
Instance details

Defined in Hackage.Security.TUF.Timestamp

Methods

fromJSON :: JSValue -> m (Signed Timestamp) #

(Monad m, ToJSON m a) => ToJSON m (Signed a) # 
Instance details

Defined in Hackage.Security.TUF.Signed

Methods

toJSON :: Signed a -> m JSValue #

newtype Signatures #

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 # 
Instance details

Defined in Hackage.Security.TUF.Signed

Methods

fromJSON :: JSValue -> m Signatures #

Monad m => ToJSON m Signatures # 
Instance details

Defined in Hackage.Security.TUF.Signed

Methods

toJSON :: Signatures -> m JSValue #

data Signature #

Constructors

Signature 

Fields

Construction and verification

unsigned :: a -> Signed a #

Create a new document without any signatures

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

Sign a document

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

Variation on withSignatures that doesn't need the repo layout

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

Construct signatures for already rendered value

verifySignature :: ByteString -> Signature -> Bool #

JSON aids

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

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 #

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.

Avoid interpreting signatures

data UninterpretedSignatures a #

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.

Instances

Instances details
(ReportSchemaErrors m, FromJSON m a) => FromJSON m (UninterpretedSignatures a) # 
Instance details

Defined in Hackage.Security.TUF.Signed

(Monad m, ToJSON m a) => ToJSON m (UninterpretedSignatures a) # 
Instance details

Defined in Hackage.Security.TUF.Signed

Show a => Show (UninterpretedSignatures a) # 
Instance details

Defined in Hackage.Security.TUF.Signed

Methods

showsPrec :: Int -> UninterpretedSignatures a -> ShowS

show :: UninterpretedSignatures a -> String

showList :: [UninterpretedSignatures a] -> ShowS

data PreSignature #

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

This corresponds precisely to the TUF representation of a signature.

Constructors

PreSignature 

Fields

Instances

Instances details
Show PreSignature # 
Instance details

Defined in Hackage.Security.TUF.Signed

Methods

showsPrec :: Int -> PreSignature -> ShowS

show :: PreSignature -> String

showList :: [PreSignature] -> ShowS

ReportSchemaErrors m => FromJSON m PreSignature # 
Instance details

Defined in Hackage.Security.TUF.Signed

Monad m => ToJSON m PreSignature # 
Instance details

Defined in Hackage.Security.TUF.Signed

Methods

toJSON :: PreSignature -> m JSValue #

Utility

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

Convert a pre-signature to a signature

Verifies that the key type matches the advertised method.

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

Convert a list of PreSignatures to a list of Signatures

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 #

Convert signature to pre-signature

toPreSignatures :: Signatures -> [PreSignature] #

Convert list of pre-signatures to a list of signatures

data Snapshot #

Constructors

Snapshot 

Fields

Instances

Instances details
HasHeader Snapshot # 
Instance details

Defined in Hackage.Security.TUF.Snapshot

VerifyRole Snapshot # 
Instance details

Defined in Hackage.Security.Trusted

(MonadReader RepoLayout m, MonadError DeserializationError m, ReportSchemaErrors m) => FromJSON m Snapshot # 
Instance details

Defined in Hackage.Security.TUF.Snapshot

Methods

fromJSON :: JSValue -> m Snapshot #

MonadReader RepoLayout m => ToJSON m Snapshot # 
Instance details

Defined in Hackage.Security.TUF.Snapshot

Methods

toJSON :: Snapshot -> m JSValue #

(MonadKeys m, MonadReader RepoLayout m) => FromJSON m (Signed Snapshot) # 
Instance details

Defined in Hackage.Security.TUF.Snapshot

Methods

fromJSON :: JSValue -> m (Signed Snapshot) #

TUF types

data Targets #

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).

Instances

Instances details
Show Targets # 
Instance details

Defined in Hackage.Security.TUF.Targets

Methods

showsPrec :: Int -> Targets -> ShowS

show :: Targets -> String

showList :: [Targets] -> ShowS

HasHeader Targets # 
Instance details

Defined in Hackage.Security.TUF.Targets

MonadKeys m => FromJSON m Targets # 
Instance details

Defined in Hackage.Security.TUF.Targets

Methods

fromJSON :: JSValue -> m Targets #

Monad m => ToJSON m Targets # 
Instance details

Defined in Hackage.Security.TUF.Targets

Methods

toJSON :: Targets -> m JSValue #

MonadKeys m => FromJSON m (Signed Targets) # 
Instance details

Defined in Hackage.Security.TUF.Targets

Methods

fromJSON :: JSValue -> m (Signed Targets) #

data Delegations #

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.

Instances

Instances details
Show Delegations # 
Instance details

Defined in Hackage.Security.TUF.Targets

Methods

showsPrec :: Int -> Delegations -> ShowS

show :: Delegations -> String

showList :: [Delegations] -> ShowS

MonadKeys m => FromJSON m Delegations # 
Instance details

Defined in Hackage.Security.TUF.Targets

Methods

fromJSON :: JSValue -> m Delegations #

Monad m => ToJSON m Delegations # 
Instance details

Defined in Hackage.Security.TUF.Targets

Methods

toJSON :: Delegations -> m JSValue #

data DelegationSpec #

Delegation specification

NOTE: This is a close analogue of RoleSpec.

Instances

Instances details
Show DelegationSpec # 
Instance details

Defined in Hackage.Security.TUF.Targets

Methods

showsPrec :: Int -> DelegationSpec -> ShowS

show :: DelegationSpec -> String

showList :: [DelegationSpec] -> ShowS

MonadKeys m => FromJSON m DelegationSpec # 
Instance details

Defined in Hackage.Security.TUF.Targets

Monad m => ToJSON m DelegationSpec # 
Instance details

Defined in Hackage.Security.TUF.Targets

data Delegation #

A delegation

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

See match for an example.

Constructors

forall a. Delegation (Pattern a) (Replacement a) 

Instances

Instances details
Show Delegation # 
Instance details

Defined in Hackage.Security.TUF.Patterns

Methods

showsPrec :: Int -> Delegation -> ShowS

show :: Delegation -> String

showList :: [Delegation] -> ShowS

Lift Delegation # 
Instance details

Defined in Hackage.Security.TUF.Patterns

Methods

lift :: Quote m => Delegation -> m Exp

liftTyped :: forall (m :: Type -> Type). Quote m => Delegation -> Code m Delegation

Util

data Timestamp #

Instances

Instances details
HasHeader Timestamp # 
Instance details

Defined in Hackage.Security.TUF.Timestamp

VerifyRole Timestamp # 
Instance details

Defined in Hackage.Security.Trusted

(MonadReader RepoLayout m, MonadError DeserializationError m, ReportSchemaErrors m) => FromJSON m Timestamp # 
Instance details

Defined in Hackage.Security.TUF.Timestamp

Methods

fromJSON :: JSValue -> m Timestamp #

MonadReader RepoLayout m => ToJSON m Timestamp # 
Instance details

Defined in Hackage.Security.TUF.Timestamp

Methods

toJSON :: Timestamp -> m JSValue #

(MonadKeys m, MonadReader RepoLayout m) => FromJSON m (Signed Timestamp) # 
Instance details

Defined in Hackage.Security.TUF.Timestamp

Methods

fromJSON :: JSValue -> m (Signed Timestamp) #

Key types

data Ed25519 #

Types abstracting over key types

data Key a where #

Constructors

KeyEd25519 :: PublicKey -> SecretKey -> Key Ed25519 

Instances

Instances details
HasKeyId Key # 
Instance details

Defined in Hackage.Security.Key

Methods

keyId :: Key typ -> KeyId #

SomeEq Key # 
Instance details

Defined in Hackage.Security.Key

Methods

someEq :: DictEq (Key a) #

SomeShow Key # 
Instance details

Defined in Hackage.Security.Key

Methods

someShow :: DictShow (Key a) #

ReportSchemaErrors m => FromJSON m (Some Key) # 
Instance details

Defined in Hackage.Security.Key

Methods

fromJSON :: JSValue -> m (Some Key) #

Monad m => ToJSON m (Key typ) # 
Instance details

Defined in Hackage.Security.Key

Methods

toJSON :: Key typ -> m JSValue #

Monad m => ToJSON m (Some Key) # 
Instance details

Defined in Hackage.Security.Key

Methods

toJSON :: Some Key -> m JSValue #

Show (Key typ) # 
Instance details

Defined in Hackage.Security.Key

Methods

showsPrec :: Int -> Key typ -> ShowS

show :: Key typ -> String

showList :: [Key typ] -> ShowS

Eq (Key typ) # 
Instance details

Defined in Hackage.Security.Key

Methods

(==) :: Key typ -> Key typ -> Bool

(/=) :: Key typ -> Key typ -> Bool

data PublicKey a where #

Instances

Instances details
HasKeyId PublicKey # 
Instance details

Defined in Hackage.Security.Key

Methods

keyId :: PublicKey typ -> KeyId #

SomeEq PublicKey # 
Instance details

Defined in Hackage.Security.Key

Methods

someEq :: DictEq (PublicKey a) #

SomeShow PublicKey # 
Instance details

Defined in Hackage.Security.Key

ReportSchemaErrors m => FromJSON m (Some PublicKey) # 
Instance details

Defined in Hackage.Security.Key

Methods

fromJSON :: JSValue -> m (Some PublicKey) #

Monad m => ToJSON m (PublicKey typ) # 
Instance details

Defined in Hackage.Security.Key

Methods

toJSON :: PublicKey typ -> m JSValue #

Monad m => ToJSON m (Some PublicKey) # 
Instance details

Defined in Hackage.Security.Key

Methods

toJSON :: Some PublicKey -> m JSValue #

Show (PublicKey typ) # 
Instance details

Defined in Hackage.Security.Key

Methods

showsPrec :: Int -> PublicKey typ -> ShowS

show :: PublicKey typ -> String

showList :: [PublicKey typ] -> ShowS

Eq (PublicKey typ) # 
Instance details

Defined in Hackage.Security.Key

Methods

(==) :: PublicKey typ -> PublicKey typ -> Bool

(/=) :: PublicKey typ -> PublicKey typ -> Bool

data PrivateKey a where #

Instances

Instances details
SomeEq PrivateKey # 
Instance details

Defined in Hackage.Security.Key

Methods

someEq :: DictEq (PrivateKey a) #

SomeShow PrivateKey # 
Instance details

Defined in Hackage.Security.Key

Show (PrivateKey typ) # 
Instance details

Defined in Hackage.Security.Key

Methods

showsPrec :: Int -> PrivateKey typ -> ShowS

show :: PrivateKey typ -> String

showList :: [PrivateKey typ] -> ShowS

Eq (PrivateKey typ) # 
Instance details

Defined in Hackage.Security.Key

Methods

(==) :: PrivateKey typ -> PrivateKey typ -> Bool

(/=) :: PrivateKey typ -> PrivateKey typ -> Bool

Key types in isolation

data KeyType typ where #

Constructors

KeyTypeEd25519 :: KeyType Ed25519 

Instances

Instances details
SomeEq KeyType # 
Instance details

Defined in Hackage.Security.Key

Methods

someEq :: DictEq (KeyType a) #

SomeShow KeyType # 
Instance details

Defined in Hackage.Security.Key

Methods

someShow :: DictShow (KeyType a) #

ReportSchemaErrors m => FromJSON m (Some KeyType) # 
Instance details

Defined in Hackage.Security.Key

Methods

fromJSON :: JSValue -> m (Some KeyType) #

Monad m => ToJSON m (KeyType typ) # 
Instance details

Defined in Hackage.Security.Key

Methods

toJSON :: KeyType typ -> m JSValue #

Monad m => ToJSON m (Some KeyType) # 
Instance details

Defined in Hackage.Security.Key

Methods

toJSON :: Some KeyType -> m JSValue #

Show (KeyType typ) # 
Instance details

Defined in Hackage.Security.Key

Methods

showsPrec :: Int -> KeyType typ -> ShowS

show :: KeyType typ -> String

showList :: [KeyType typ] -> ShowS

Eq (KeyType typ) # 
Instance details

Defined in Hackage.Security.Key

Methods

(==) :: KeyType typ -> KeyType typ -> Bool

(/=) :: KeyType typ -> KeyType typ -> Bool

Hiding key types

someKeyId :: HasKeyId key => Some key -> KeyId #

Operations on keys

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

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

Key IDs

newtype KeyId #

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

Instances

Instances details
Show KeyId # 
Instance details

Defined in Hackage.Security.Key

Methods

showsPrec :: Int -> KeyId -> ShowS

show :: KeyId -> String

showList :: [KeyId] -> ShowS

Eq KeyId # 
Instance details

Defined in Hackage.Security.Key

Methods

(==) :: KeyId -> KeyId -> Bool

(/=) :: KeyId -> KeyId -> Bool

Ord KeyId # 
Instance details

Defined in Hackage.Security.Key

Methods

compare :: KeyId -> KeyId -> Ordering

(<) :: KeyId -> KeyId -> Bool

(<=) :: KeyId -> KeyId -> Bool

(>) :: KeyId -> KeyId -> Bool

(>=) :: KeyId -> KeyId -> Bool

max :: KeyId -> KeyId -> KeyId

min :: KeyId -> KeyId -> KeyId

Monad m => FromObjectKey m KeyId # 
Instance details

Defined in Hackage.Security.Key

Methods

fromObjectKey :: String -> m (Maybe KeyId) #

Monad m => ToObjectKey m KeyId # 
Instance details

Defined in Hackage.Security.Key

Methods

toObjectKey :: KeyId -> m String #

class HasKeyId key where #

Compute the key ID of a key

Methods

keyId :: key typ -> KeyId #

Instances

Instances details
HasKeyId Key # 
Instance details

Defined in Hackage.Security.Key

Methods

keyId :: Key typ -> KeyId #

HasKeyId PublicKey # 
Instance details

Defined in Hackage.Security.Key

Methods

keyId :: PublicKey typ -> KeyId #

Signing

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

Sign a bytestring and return the signature

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

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

trusted :: Trusted a -> a #

We only a few bits from .Repository

data Repository down #

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) # 
Instance details

Defined in Hackage.Security.Client.Repository

Methods

showsPrec :: Int -> Repository down -> ShowS

show :: Repository down -> String

showList :: [Repository down] -> ShowS

class DownloadedFile (down :: * -> *) where #

Methods

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

Verify a download file

downloadedRead :: down Metadata -> IO ByteString #

Read the file we just downloaded into memory

We never read binary data, only metadata.

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

Copy a downloaded file to its destination

Instances

Instances details
DownloadedFile LocalFile # 
Instance details

Defined in Hackage.Security.Client.Repository.Local

Methods

downloadedVerify :: LocalFile a -> Trusted FileInfo -> IO Bool #

downloadedRead :: LocalFile Metadata -> IO ByteString #

downloadedCopyTo :: LocalFile a -> Path Absolute -> IO () #

DownloadedFile RemoteTemp # 
Instance details

Defined in Hackage.Security.Client.Repository.Remote

data SomeRemoteError :: * where #

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 :: Exception e => e -> SomeRemoteError 

Instances

Instances details
Exception SomeRemoteError # 
Instance details

Defined in Hackage.Security.Client.Repository

Methods

toException :: SomeRemoteError -> SomeException

fromException :: SomeException -> Maybe SomeRemoteError

displayException :: SomeRemoteError -> String

Show SomeRemoteError # 
Instance details

Defined in Hackage.Security.Client.Repository

Methods

showsPrec :: Int -> SomeRemoteError -> ShowS

show :: SomeRemoteError -> String

showList :: [SomeRemoteError] -> ShowS

Pretty SomeRemoteError # 
Instance details

Defined in Hackage.Security.Client.Repository

Methods

pretty :: SomeRemoteError -> String #

data LogMessage #

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.)

forall fs typ. LogDownloading (RemoteFile fs typ)

Download a file from a repository

forall fs. LogUpdating (RemoteFile fs Binary)

Incrementally updating a file from a repository

LogSelectedMirror MirrorDescription

Selected a particular mirror

forall fs. 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 # 
Instance details

Defined in Hackage.Security.Client.Repository

Methods

pretty :: LogMessage -> String #

Exceptions

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

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

data VerificationError #

Errors thrown during role validation

Constructors

VerificationErrorSignatures TargetPath

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 # 
Instance details

Defined in Hackage.Security.Trusted.TCB

Methods

toException :: VerificationError -> SomeException

fromException :: SomeException -> Maybe VerificationError

displayException :: VerificationError -> String

Show VerificationError # 
Instance details

Defined in Hackage.Security.Trusted.TCB

Methods

showsPrec :: Int -> VerificationError -> ShowS

show :: VerificationError -> String

showList :: [VerificationError] -> ShowS

Pretty VerificationError # 
Instance details

Defined in Hackage.Security.Trusted.TCB

Methods

pretty :: VerificationError -> String #

data RootUpdated #

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

Constructors

RootUpdated 

Instances

Instances details
Exception RootUpdated # 
Instance details

Defined in Hackage.Security.Trusted.TCB

Methods

toException :: RootUpdated -> SomeException

fromException :: SomeException -> Maybe RootUpdated

displayException :: RootUpdated -> String

Show RootUpdated # 
Instance details

Defined in Hackage.Security.Trusted.TCB

Methods

showsPrec :: Int -> RootUpdated -> ShowS

show :: RootUpdated -> String

showList :: [RootUpdated] -> ShowS

Pretty RootUpdated # 
Instance details

Defined in Hackage.Security.Trusted.TCB

Methods

pretty :: RootUpdated -> String #

data InvalidPackageException #

Constructors

InvalidPackageException PackageIdentifier 

Instances

Instances details
Exception InvalidPackageException # 
Instance details

Defined in Hackage.Security.Client

Show InvalidPackageException # 
Instance details

Defined in Hackage.Security.Client

Pretty InvalidPackageException # 
Instance details

Defined in Hackage.Security.Client

Methods

pretty :: InvalidPackageException -> String #

data InvalidFileInIndex #

Instances

Instances details
Exception InvalidFileInIndex # 
Instance details

Defined in Hackage.Security.Client

Methods

toException :: InvalidFileInIndex -> SomeException

fromException :: SomeException -> Maybe InvalidFileInIndex

displayException :: InvalidFileInIndex -> String

Show InvalidFileInIndex # 
Instance details

Defined in Hackage.Security.Client

Methods

showsPrec :: Int -> InvalidFileInIndex -> ShowS

show :: InvalidFileInIndex -> String

showList :: [InvalidFileInIndex] -> ShowS

Pretty InvalidFileInIndex # 
Instance details

Defined in Hackage.Security.Client

Methods

pretty :: InvalidFileInIndex -> String #

data LocalFileCorrupted #

Instances

Instances details
Exception LocalFileCorrupted # 
Instance details

Defined in Hackage.Security.Client

Methods

toException :: LocalFileCorrupted -> SomeException

fromException :: SomeException -> Maybe LocalFileCorrupted

displayException :: LocalFileCorrupted -> String

Show LocalFileCorrupted # 
Instance details

Defined in Hackage.Security.Client

Methods

showsPrec :: Int -> LocalFileCorrupted -> ShowS

show :: LocalFileCorrupted -> String

showList :: [LocalFileCorrupted] -> ShowS

Pretty LocalFileCorrupted # 
Instance details

Defined in Hackage.Security.Client

Methods

pretty :: LocalFileCorrupted -> String #