cryptostore-0.3.0.1: Serialization of cryptographic data types

License | BSD-style
Maintainer | Olivier Chéron <olivier.cheron@gmail.com>
Stability | experimental
Portability | unknown
Safe Haskell | Safe-Inferred
Language | Haskell2010

Crypto.Store.PKCS5

Contents

- High-level API
- Encryption schemes
- Key derivation
- Content encryption
- Low-level API

Description

Password-Based Cryptography, aka PKCS #5.

Synopsis

- data ProtectionPassword
- emptyNotTerminated :: ProtectionPassword
- fromProtectionPassword :: ProtectionPassword -> ByteString
- toProtectionPassword :: ByteString -> ProtectionPassword
- type EncryptedContent = ByteString
- data PKCS5 = PKCS5 {
  - encryptionAlgorithm :: EncryptionScheme
  - encryptedData :: EncryptedContent
  }
- encrypt :: EncryptionScheme -> ProtectionPassword -> ByteString -> Either StoreError PKCS5
- decrypt :: PKCS5 -> ProtectionPassword -> Either StoreError ByteString
- data EncryptionScheme
  - = PBES2 PBES2Parameter
  - | PBE_MD5_DES_CBC PBEParameter
  - | PBE_SHA1_DES_CBC PBEParameter
  - | PBE_SHA1_RC4_128 PBEParameter
  - | PBE_SHA1_RC4_40 PBEParameter
  - | PBE_SHA1_DES_EDE3_CBC PBEParameter
  - | PBE_SHA1_DES_EDE2_CBC PBEParameter
  - | PBE_SHA1_RC2_128 PBEParameter
  - | PBE_SHA1_RC2_40 PBEParameter
- data PBEParameter = PBEParameter {
  - pbeSalt :: Salt
  - pbeIterationCount :: Int
  }
- data PBES2Parameter = PBES2Parameter {
  - pbes2KDF :: KeyDerivationFunc
  - pbes2EScheme :: ContentEncryptionParams
  }
- data KeyDerivationFunc
  - = PBKDF2 {
    - pbkdf2Salt :: Salt
    - pbkdf2IterationCount :: Int
    - pbkdf2KeyLength :: Maybe Int
    - pbkdf2Prf :: PBKDF2_PRF
    }
  - | Scrypt {
    - scryptSalt :: Salt
    - scryptN :: Word64
    - scryptR :: Int
    - scryptP :: Int
    - scryptKeyLength :: Maybe Int
    }
- data PBKDF2_PRF
  - = PBKDF2_SHA1
  - | PBKDF2_SHA256
  - | PBKDF2_SHA512
- type Salt = ByteString
- generateSalt :: MonadRandom m => Int -> m Salt
- data ContentEncryptionParams
- data ContentEncryptionAlg
  - = forall c.BlockCipher c => ECB (ContentEncryptionCipher c)
  - | forall c.BlockCipher c => CBC (ContentEncryptionCipher c)
  - | CBC_RC2
  - | forall c.BlockCipher c => CFB (ContentEncryptionCipher c)
  - | forall c.BlockCipher c => CTR (ContentEncryptionCipher c)
- data ContentEncryptionCipher cipher where
  - DES :: ContentEncryptionCipher DES
  - DES_EDE2 :: ContentEncryptionCipher DES_EDE2
  - DES_EDE3 :: ContentEncryptionCipher DES_EDE3
  - AES128 :: ContentEncryptionCipher AES128
  - AES192 :: ContentEncryptionCipher AES192
  - AES256 :: ContentEncryptionCipher AES256
  - CAST5 :: ContentEncryptionCipher CAST5
  - Camellia128 :: ContentEncryptionCipher Camellia128
- generateEncryptionParams :: MonadRandom m => ContentEncryptionAlg -> m ContentEncryptionParams
- getContentEncryptionAlg :: ContentEncryptionParams -> ContentEncryptionAlg
- pbEncrypt :: EncryptionScheme -> ByteString -> ProtectionPassword -> Either StoreError EncryptedContent
- pbDecrypt :: EncryptionScheme -> EncryptedContent -> ProtectionPassword -> Either StoreError ByteString

# Documentation

data ProtectionPassword Source #

A password stored as a sequence of UTF-8 bytes.

Some key-derivation functions add restrictions to what characters are supported.

The data type provides a special value `emptyNotTerminated` that is used as alternate representation of empty passwords on some systems and that produces encryption results different than an empty bytearray.

Conversion to/from a regular sequence of bytes is possible with functions `toProtectionPassword` and `fromProtectionPassword`.

Beware: the `fromString` implementation correctly handles multi-byte characters, so here is not equivalent to the `ByteString` counterpart.

#### Instances

Instances details

IsString ProtectionPassword Source # |
Instance details Defined in Crypto.Store.PKCS5.PBES1 Methods fromString :: String -> ProtectionPassword Source #
Show ProtectionPassword Source # |
Instance details Defined in Crypto.Store.PKCS5.PBES1 Methods showsPrec :: Int -> ProtectionPassword -> ShowS Source # show :: ProtectionPassword -> String Source # showList :: [ProtectionPassword] -> ShowS Source #
Eq ProtectionPassword Source # |
Instance details Defined in Crypto.Store.PKCS5.PBES1 Methods (==) :: ProtectionPassword -> ProtectionPassword -> Bool Source # (/=) :: ProtectionPassword -> ProtectionPassword -> Bool Source #
ByteArrayAccess ProtectionPassword Source # |
Instance details Defined in Crypto.Store.PKCS5.PBES1 Methods length :: ProtectionPassword -> Int Source # withByteArray :: ProtectionPassword -> (Ptr p -> IO a) -> IO a Source # copyByteArrayToPtr :: ProtectionPassword -> Ptr p -> IO () Source #

emptyNotTerminated :: ProtectionPassword Source #

A value denoting an empty password, but having a special encoding when deriving a symmetric key on some systems, like the certificate export wizard on Windows.

This value is different from ``toProtectionPassword` ""` and can be tried when decrypting content with a password known to be empty.

fromProtectionPassword :: ProtectionPassword -> ByteString Source #

Extract the UTF-8 bytes in a password value.

toProtectionPassword :: ByteString -> ProtectionPassword Source #

Build a password value from a sequence of UTF-8 bytes.

When the password is empty, the special value `emptyNotTerminated` may be tried as well.

type EncryptedContent = ByteString Source #

Encrypted content.

# High-level API

data PKCS5 Source #

Content encrypted with a Password-Based Encryption Scheme (PBES).

The content will usually be the binary representation of an ASN.1 object, however the transformation may be applied to any bytestring.

Constructors

PKCS5 |

Fields

- encryptionAlgorithm :: EncryptionScheme

  Scheme used to encrypt content

- encryptedData :: EncryptedContent

  Encrypted content

#### Instances

Instances details

ASN1Object PKCS5 Source # |
Instance details Defined in Crypto.Store.PKCS5 Methods toASN1 :: PKCS5 -> ASN1S Source # fromASN1 :: [ASN1] -> Either String (PKCS5, [ASN1]) Source #
Show PKCS5 Source # |
Instance details Defined in Crypto.Store.PKCS5 Methods showsPrec :: Int -> PKCS5 -> ShowS Source # show :: PKCS5 -> String Source # showList :: [PKCS5] -> ShowS Source #
Eq PKCS5 Source # |
Instance details Defined in Crypto.Store.PKCS5 Methods (==) :: PKCS5 -> PKCS5 -> Bool Source # (/=) :: PKCS5 -> PKCS5 -> Bool Source #

encrypt :: EncryptionScheme -> ProtectionPassword -> ByteString -> Either StoreError PKCS5 Source #

Encrypt a bytestring with the specified encryption scheme and password.

decrypt :: PKCS5 -> ProtectionPassword -> Either StoreError ByteString Source #

Decrypt the PKCS #5 content with the specified password.

# Encryption schemes

data EncryptionScheme Source #

Password-Based Encryption Scheme (PBES).

Constructors

PBES2 PBES2Parameter | PBES2
PBE_MD5_DES_CBC PBEParameter | pbeWithMD5AndDES-CBC
PBE_SHA1_DES_CBC PBEParameter | pbeWithSHA1AndDES-CBC
PBE_SHA1_RC4_128 PBEParameter | pbeWithSHAAnd128BitRC4
PBE_SHA1_RC4_40 PBEParameter | pbeWithSHAAnd40BitRC4
PBE_SHA1_DES_EDE3_CBC PBEParameter | pbeWithSHAAnd3-KeyTripleDES-CBC
PBE_SHA1_DES_EDE2_CBC PBEParameter | pbeWithSHAAnd2-KeyTripleDES-CBC
PBE_SHA1_RC2_128 PBEParameter | pbeWithSHAAnd128BitRC2-CBC
PBE_SHA1_RC2_40 PBEParameter | pbewithSHAAnd40BitRC2-CBC

#### Instances

Instances details

Show EncryptionScheme Source # |
Instance details Defined in Crypto.Store.PKCS5 Methods showsPrec :: Int -> EncryptionScheme -> ShowS Source # show :: EncryptionScheme -> String Source # showList :: [EncryptionScheme] -> ShowS Source #
Eq EncryptionScheme Source # |
Instance details Defined in Crypto.Store.PKCS5 Methods (==) :: EncryptionScheme -> EncryptionScheme -> Bool Source # (/=) :: EncryptionScheme -> EncryptionScheme -> Bool Source #

data PBEParameter Source #

PBES1 parameters.

Constructors

PBEParameter |

Fields

- pbeSalt :: Salt

  8-octet salt value

- pbeIterationCount :: Int

  Iteration count

#### Instances

Instances details

Show PBEParameter Source # |
Instance details Defined in Crypto.Store.PKCS5.PBES1 Methods showsPrec :: Int -> PBEParameter -> ShowS Source # show :: PBEParameter -> String Source # showList :: [PBEParameter] -> ShowS Source #
Eq PBEParameter Source # |
Instance details Defined in Crypto.Store.PKCS5.PBES1 Methods (==) :: PBEParameter -> PBEParameter -> Bool Source # (/=) :: PBEParameter -> PBEParameter -> Bool Source #

data PBES2Parameter Source #

PBES2 parameters.

Constructors

PBES2Parameter |

Fields

- pbes2KDF :: KeyDerivationFunc

  Key derivation function

- pbes2EScheme :: ContentEncryptionParams

  Underlying encryption scheme

#### Instances

Instances details

Show PBES2Parameter Source # |
Instance details Defined in Crypto.Store.PKCS5 Methods showsPrec :: Int -> PBES2Parameter -> ShowS Source # show :: PBES2Parameter -> String Source # showList :: [PBES2Parameter] -> ShowS Source #
Eq PBES2Parameter Source # |
Instance details Defined in Crypto.Store.PKCS5 Methods (==) :: PBES2Parameter -> PBES2Parameter -> Bool Source # (/=) :: PBES2Parameter -> PBES2Parameter -> Bool Source #

# Key derivation

data KeyDerivationFunc Source #

Key derivation algorithm and associated parameters.

Constructors

PBKDF2 | Key derivation with PBKDF2

Fields

- pbkdf2Salt :: Salt

  Salt value

- pbkdf2IterationCount :: Int

  Iteration count

- pbkdf2KeyLength :: Maybe Int

  Optional key length

- pbkdf2Prf :: PBKDF2_PRF

  Pseudorandom function

Scrypt | Key derivation with Scrypt

Fields

- scryptSalt :: Salt

  Salt value

- scryptN :: Word64

  N value

- scryptR :: Int

  R value

- scryptP :: Int

  P value

- scryptKeyLength :: Maybe Int

  Optional key length

#### Instances

Instances details

Show KeyDerivationFunc Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods showsPrec :: Int -> KeyDerivationFunc -> ShowS Source # show :: KeyDerivationFunc -> String Source # showList :: [KeyDerivationFunc] -> ShowS Source #
Eq KeyDerivationFunc Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods (==) :: KeyDerivationFunc -> KeyDerivationFunc -> Bool Source # (/=) :: KeyDerivationFunc -> KeyDerivationFunc -> Bool Source #

data PBKDF2_PRF Source #

Pseudorandom function used for PBKDF2.

Constructors

PBKDF2_SHA1 | hmacWithSHA1
PBKDF2_SHA256 | hmacWithSHA256
PBKDF2_SHA512 | hmacWithSHA512

#### Instances

Instances details

OIDNameable PBKDF2_PRF Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods fromObjectID :: OID -> Maybe PBKDF2_PRF Source #
OIDable PBKDF2_PRF Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods getObjectID :: PBKDF2_PRF -> OID Source #
Show PBKDF2_PRF Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods showsPrec :: Int -> PBKDF2_PRF -> ShowS Source # show :: PBKDF2_PRF -> String Source # showList :: [PBKDF2_PRF] -> ShowS Source #
Eq PBKDF2_PRF Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods (==) :: PBKDF2_PRF -> PBKDF2_PRF -> Bool Source # (/=) :: PBKDF2_PRF -> PBKDF2_PRF -> Bool Source #

type Salt = ByteString Source #

Salt value used for key derivation.

generateSalt :: MonadRandom m => Int -> m Salt Source #

Generate a random salt with the specified length in bytes. To be most effective, the length should be at least 8 bytes.

# Content encryption

data ContentEncryptionParams Source #

Content encryption algorithm with associated parameters (i.e. the initialization vector).

A value can be generated with `generateEncryptionParams`.

#### Instances

Instances details

Show ContentEncryptionParams Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods showsPrec :: Int -> ContentEncryptionParams -> ShowS Source # show :: ContentEncryptionParams -> String Source # showList :: [ContentEncryptionParams] -> ShowS Source #
HasKeySize ContentEncryptionParams Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods getKeySizeSpecifier :: ContentEncryptionParams -> KeySizeSpecifier Source #
Eq ContentEncryptionParams Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods (==) :: ContentEncryptionParams -> ContentEncryptionParams -> Bool Source # (/=) :: ContentEncryptionParams -> ContentEncryptionParams -> Bool Source #

data ContentEncryptionAlg Source #

Cipher and mode of operation for content encryption.

Constructors

forall c.BlockCipher c => ECB (ContentEncryptionCipher c) | Electronic Codebook
forall c.BlockCipher c => CBC (ContentEncryptionCipher c) | Cipher Block Chaining
CBC_RC2 | RC2 in CBC mode
forall c.BlockCipher c => CFB (ContentEncryptionCipher c) | Cipher Feedback
forall c.BlockCipher c => CTR (ContentEncryptionCipher c) | Counter

#### Instances

Instances details

OIDNameable ContentEncryptionAlg Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods fromObjectID :: OID -> Maybe ContentEncryptionAlg Source #
OIDable ContentEncryptionAlg Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods getObjectID :: ContentEncryptionAlg -> OID Source #
Show ContentEncryptionAlg Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods showsPrec :: Int -> ContentEncryptionAlg -> ShowS Source # show :: ContentEncryptionAlg -> String Source # showList :: [ContentEncryptionAlg] -> ShowS Source #

data ContentEncryptionCipher cipher where Source #

CMS content encryption cipher.

Constructors

DES :: ContentEncryptionCipher DES | DES
DES_EDE2 :: ContentEncryptionCipher DES_EDE2 | Triple-DES with 2 keys used in alternative direction
DES_EDE3 :: ContentEncryptionCipher DES_EDE3 | Triple-DES with 3 keys used in alternative direction
AES128 :: ContentEncryptionCipher AES128 | AES with 128-bit key
AES192 :: ContentEncryptionCipher AES192 | AES with 192-bit key
AES256 :: ContentEncryptionCipher AES256 | AES with 256-bit key
CAST5 :: ContentEncryptionCipher CAST5 | CAST5 (aka CAST-128) with key between 40 and 128 bits
Camellia128 :: ContentEncryptionCipher Camellia128 | Camellia with 128-bit key

#### Instances

Instances details

Show (ContentEncryptionCipher cipher) Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods showsPrec :: Int -> ContentEncryptionCipher cipher -> ShowS Source # show :: ContentEncryptionCipher cipher -> String Source # showList :: [ContentEncryptionCipher cipher] -> ShowS Source #
Eq (ContentEncryptionCipher cipher) Source # |
Instance details Defined in Crypto.Store.CMS.Algorithms Methods (==) :: ContentEncryptionCipher cipher -> ContentEncryptionCipher cipher -> Bool Source # (/=) :: ContentEncryptionCipher cipher -> ContentEncryptionCipher cipher -> Bool Source #

generateEncryptionParams :: MonadRandom m => ContentEncryptionAlg -> m ContentEncryptionParams Source #

Generate random parameters for the specified content encryption algorithm.

getContentEncryptionAlg :: ContentEncryptionParams -> ContentEncryptionAlg Source #

Get the content encryption algorithm.

# Low-level API

pbEncrypt :: EncryptionScheme -> ByteString -> ProtectionPassword -> Either StoreError EncryptedContent Source #

Encrypt a bytestring with the specified encryption scheme and password.

pbDecrypt :: EncryptionScheme -> EncryptedContent -> ProtectionPassword -> Either StoreError ByteString Source #

Decrypt an encrypted bytestring with the specified encryption scheme and password.