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

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 # show :: EncryptionScheme -> String # showList :: [EncryptionScheme] -> ShowS #
Eq EncryptionScheme Source #
Instance details Defined in Crypto.Store.PKCS5 Methods (==) :: EncryptionScheme -> EncryptionScheme -> Bool # (/=) :: EncryptionScheme -> EncryptionScheme -> Bool #

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 # show :: PBEParameter -> String # showList :: [PBEParameter] -> ShowS #
Eq PBEParameter Source #
Instance details Defined in Crypto.Store.PKCS5.PBES1 Methods (==) :: PBEParameter -> PBEParameter -> Bool # (/=) :: PBEParameter -> PBEParameter -> Bool #

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 # show :: PBES2Parameter -> String # showList :: [PBES2Parameter] -> ShowS #
Eq PBES2Parameter Source #
Instance details Defined in Crypto.Store.PKCS5 Methods (==) :: PBES2Parameter -> PBES2Parameter -> Bool # (/=) :: PBES2Parameter -> PBES2Parameter -> Bool #

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 # show :: KeyDerivationFunc -> String # showList :: [KeyDerivationFunc] -> ShowS #
Eq KeyDerivationFunc Source #
Instance details Defined in Crypto.Store.CMS.Algorithms Methods (==) :: KeyDerivationFunc -> KeyDerivationFunc -> Bool # (/=) :: KeyDerivationFunc -> KeyDerivationFunc -> Bool #

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 # show :: PBKDF2_PRF -> String # showList :: [PBKDF2_PRF] -> ShowS #
Eq PBKDF2_PRF Source #
Instance details Defined in Crypto.Store.CMS.Algorithms Methods (==) :: PBKDF2_PRF -> PBKDF2_PRF -> Bool # (/=) :: PBKDF2_PRF -> PBKDF2_PRF -> Bool #

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 # show :: ContentEncryptionParams -> String # showList :: [ContentEncryptionParams] -> ShowS #
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 # (/=) :: ContentEncryptionParams -> ContentEncryptionParams -> Bool #

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 # show :: ContentEncryptionAlg -> String # showList :: [ContentEncryptionAlg] -> ShowS #

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 # show :: ContentEncryptionCipher cipher -> String # showList :: [ContentEncryptionCipher cipher] -> ShowS #
Eq (ContentEncryptionCipher cipher) Source #
Instance details Defined in Crypto.Store.CMS.Algorithms Methods (==) :: ContentEncryptionCipher cipher -> ContentEncryptionCipher cipher -> Bool # (/=) :: ContentEncryptionCipher cipher -> ContentEncryptionCipher cipher -> Bool #

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.