tar-0.6.4.0: Reading, writing and manipulating ".tar" archive files.

Copyright | (c) 2008-2012 Duncan Coutts 2011 Max Bolingbroke
License | BSD3
Maintainer | duncan@community.haskell.org
Portability | portable
Safe Haskell | None
Language | Haskell2010

Codec.Archive.Tar.Check

Contents

- Security
- Tarbombs
- Portability

Description

Perform various checks on tar file entries.

Synopsis

- checkSecurity :: Entries e -> GenEntries FilePath FilePath (Either (Either e DecodeLongNamesError) FileNameError)
- checkEntrySecurity :: GenEntry FilePath FilePath -> Maybe FileNameError
- data FileNameError
  - = InvalidFileName FilePath
  - | AbsoluteFileName FilePath
  - | UnsafeLinkTarget FilePath
- checkTarbomb :: FilePath -> Entries e -> GenEntries FilePath FilePath (Either (Either e DecodeLongNamesError) TarBombError)
- checkEntryTarbomb :: FilePath -> GenEntry FilePath linkTarget -> Maybe TarBombError
- data TarBombError = TarBombError FilePath FilePath
- checkPortability :: Entries e -> GenEntries FilePath FilePath (Either (Either e DecodeLongNamesError) PortabilityError)
- checkEntryPortability :: GenEntry FilePath linkTarget -> Maybe PortabilityError
- data PortabilityError
  - = NonPortableFormat Format
  - | NonPortableFileType
  - | NonPortableEntryNameChar FilePath
  - | NonPortableFileName PortabilityPlatform FileNameError
- type PortabilityPlatform = String

# Security

checkSecurity :: Entries e -> GenEntries FilePath FilePath (Either (Either e DecodeLongNamesError) FileNameError) #

This function checks a sequence of tar entries for file name security problems. It checks that:

- file paths are not absolute
- file paths do not refer outside of the archive
- file names are valid

These checks are from the perspective of the current OS. That means we check for "`C:blah`" files on Windows and "/blah" files on Unix. For archive entry types `HardLink` and `SymbolicLink` the same checks are done for the link target. A failure in any entry terminates the sequence of entries with an error.

Whenever possible, consider fusing `checkSecurity` with packing / unpacking by using `packAndCheck` / `unpackAndCheck` with `checkEntrySecurity`. Not only it is faster, but also alleviates issues with lazy I/O such as exhaustion of file handlers.

checkEntrySecurity :: GenEntry FilePath FilePath -> Maybe FileNameError #

Worker of `checkSecurity`.

Since: 0.6.0.0

data FileNameError #

Errors arising from tar file names being in some way invalid or dangerous

Constructors

InvalidFileName FilePath |
AbsoluteFileName FilePath |
UnsafeLinkTarget FilePath | Since: 0.6.0.0

#### Instances

Instances details

Exception FileNameError # |
Instance details Defined in Codec.Archive.Tar.Check.Internal Methods toException :: FileNameError -> SomeException # fromException :: SomeException -> Maybe FileNameError # displayException :: FileNameError -> String # backtraceDesired :: FileNameError -> Bool #
Show FileNameError # |
Instance details Defined in Codec.Archive.Tar.Check.Internal Methods showsPrec :: Int -> FileNameError -> ShowS # show :: FileNameError -> String # showList :: [FileNameError] -> ShowS #

# Tarbombs

checkTarbomb :: FilePath -> Entries e -> GenEntries FilePath FilePath (Either (Either e DecodeLongNamesError) TarBombError) #

This function checks a sequence of tar entries for being a "tar bomb". This means that the tar file does not follow the standard convention that all entries are within a single subdirectory, e.g. a file "foo.tar" would usually have all entries within the "foo/" subdirectory.

Given the expected subdirectory, this function checks all entries are within that subdirectroy.

Note: This check must be used in conjunction with `checkSecurity` (or `checkPortability`).

Whenever possible, consider fusing `checkTarbomb` with packing / unpacking by using `packAndCheck` / `unpackAndCheck` with `checkEntryTarbomb`. Not only it is faster, but also alleviates issues with lazy I/O such as exhaustion of file handlers.

checkEntryTarbomb :: FilePath -> GenEntry FilePath linkTarget -> Maybe TarBombError #

Worker of `checkTarbomb`.

Since: 0.6.0.0

data TarBombError #

An error that occurs if a tar file is a "tar bomb" that would extract files outside of the intended directory.

Constructors

TarBombError |

Fields

- FilePath

  Path inside archive.

  Since: 0.6.0.0

- FilePath

  Expected top directory.

#### Instances

Instances details

Exception TarBombError # |
Instance details Defined in Codec.Archive.Tar.Check.Internal Methods toException :: TarBombError -> SomeException # fromException :: SomeException -> Maybe TarBombError # displayException :: TarBombError -> String # backtraceDesired :: TarBombError -> Bool #
Show TarBombError # |
Instance details Defined in Codec.Archive.Tar.Check.Internal Methods showsPrec :: Int -> TarBombError -> ShowS # show :: TarBombError -> String # showList :: [TarBombError] -> ShowS #

# Portability

checkPortability :: Entries e -> GenEntries FilePath FilePath (Either (Either e DecodeLongNamesError) PortabilityError) #

This function checks a sequence of tar entries for a number of portability issues. It will complain if:

- The old "Unix V7" or "gnu" formats are used. For maximum portability only the POSIX standard "ustar" format should be used.
- A non-portable entry type is used. Only ordinary files, hard links, symlinks and directories are portable. Device files, pipes and others are not portable between all common operating systems.
- Non-ASCII characters are used in file names. There is no agreed portable convention for Unicode or other extended character sets in file names in tar archives.
- File names that would not be portable to both Unix and Windows. This check includes characters that are valid in both systems and the '/' vs '\' directory separator conventions.

Whenever possible, consider fusing `checkPortability` with packing / unpacking by using `packAndCheck` / `unpackAndCheck` with `checkEntryPortability`. Not only it is faster, but also alleviates issues with lazy I/O such as exhaustion of file handlers.

checkEntryPortability :: GenEntry FilePath linkTarget -> Maybe PortabilityError #

Worker of `checkPortability`.

Since: 0.6.0.0

data PortabilityError #

Portability problems in a tar archive

Constructors

NonPortableFormat Format |
NonPortableFileType |
NonPortableEntryNameChar FilePath |
NonPortableFileName PortabilityPlatform FileNameError |

#### Instances

Instances details

Exception PortabilityError # |
Instance details Defined in Codec.Archive.Tar.Check.Internal Methods toException :: PortabilityError -> SomeException # fromException :: SomeException -> Maybe PortabilityError # displayException :: PortabilityError -> String # backtraceDesired :: PortabilityError -> Bool #
Show PortabilityError # |
Instance details Defined in Codec.Archive.Tar.Check.Internal Methods showsPrec :: Int -> PortabilityError -> ShowS # show :: PortabilityError -> String # showList :: [PortabilityError] -> ShowS #

type PortabilityPlatform = String #

The name of a platform that portability issues arise from