cryptostore-0.3.1.0: Serialization of cryptographic data types
LicenseBSD-style
MaintainerOlivier Chéron <olivier.cheron@gmail.com>
Stabilityexperimental
Portabilityunknown
Safe HaskellSafe-Inferred
LanguageHaskell2010

Crypto.Store.PKCS8

Description

Private-Key Information Syntax, aka PKCS #8.

Presents an API similar to Data.X509.Memory and Data.X509.File but allows to write private keys and provides support for password-based encryption.

Functions to read a private key return an object wrapped in the OptProtected data type.

Functions related to public keys, certificates and CRLs are available from Crypto.Store.X509.

Synopsis

Documentation

readKeyFile :: FilePath -> IO [OptProtected PrivKey] Source #

Read private keys from a PEM file.

readKeyFileFromMemory :: ByteString -> [OptProtected PrivKey] Source #

Read private keys from a bytearray in PEM format.

pemToKey :: [Maybe (OptProtected PrivKey)] -> PEM -> [Maybe (OptProtected PrivKey)] Source #

Read a private key from a PEM element and add it to the accumulator list.

writeKeyFile :: PrivateKeyFormat -> FilePath -> [PrivKey] -> IO () Source #

Write unencrypted private keys to a PEM file.

writeKeyFileToMemory :: PrivateKeyFormat -> [PrivKey] -> ByteString Source #

Write unencrypted private keys to a bytearray in PEM format.

keyToPEM :: PrivateKeyFormat -> PrivKey -> PEM Source #

Generate an unencrypted PEM for a private key.

writeEncryptedKeyFile :: FilePath -> EncryptionScheme -> ProtectionPassword -> PrivKey -> IO (Either StoreError ()) Source #

Write a PKCS #8 encrypted private key to a PEM file.

If multiple keys need to be stored in the same file, use functions encryptKeyToPEM and writePEMs.

Fresh EncryptionScheme parameters should be generated for each key to encrypt.

writeEncryptedKeyFileToMemory :: EncryptionScheme -> ProtectionPassword -> PrivKey -> Either StoreError ByteString Source #

Write a PKCS #8 encrypted private key to a bytearray in PEM format.

If multiple keys need to be stored in the same bytearray, use functions encryptKeyToPEM and pemWriteBS or pemWriteLBS.

Fresh EncryptionScheme parameters should be generated for each key to encrypt.

encryptKeyToPEM :: EncryptionScheme -> ProtectionPassword -> PrivKey -> Either StoreError PEM Source #

Generate a PKCS #8 encrypted PEM for a private key.

Fresh EncryptionScheme parameters should be generated for each key to encrypt.

Serialization formats

data PrivateKeyFormat Source #

Private-key serialization format.

Encryption in traditional format is not supported currently.

Constructors

TraditionalFormat

SSLeay compatible

PKCS8Format

PKCS #8

data FormattedKey a Source #

A key associated with format. Allows to implement ASN1Object instances.

Instances

Instances details
Functor FormattedKey Source # 
Instance details

Defined in Crypto.Store.PKCS8

Methods

fmap :: (a -> b) -> FormattedKey a -> FormattedKey b #

(<$) :: a -> FormattedKey b -> FormattedKey a #

ASN1Object (FormattedKey KeyPair) Source # 
Instance details

Defined in Crypto.Store.PKCS8

ASN1Object (FormattedKey PrivateKey) Source # 
Instance details

Defined in Crypto.Store.PKCS8

ASN1Object (FormattedKey PrivKey) Source # 
Instance details

Defined in Crypto.Store.PKCS8

ASN1Object (FormattedKey PrivKeyEC) Source # 
Instance details

Defined in Crypto.Store.PKCS8

Show a => Show (FormattedKey a) Source # 
Instance details

Defined in Crypto.Store.PKCS8

Eq a => Eq (FormattedKey a) Source # 
Instance details

Defined in Crypto.Store.PKCS8

Password-based protection

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.

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.

data OptProtected a Source #

Data type for objects that are possibly protected with a password.

Constructors

Unprotected a

Value is unprotected

Protected (ProtectionPassword -> Either StoreError a)

Value is protected with a password

Instances

Instances details
Functor OptProtected Source # 
Instance details

Defined in Crypto.Store.PKCS8

Methods

fmap :: (a -> b) -> OptProtected a -> OptProtected b #

(<$) :: a -> OptProtected b -> OptProtected a #

recover :: ProtectionPassword -> OptProtected a -> Either StoreError a Source #

Try to recover an OptProtected content using the specified password.

recoverA :: Applicative f => f ProtectionPassword -> OptProtected a -> f (Either StoreError a) Source #

Try to recover an OptProtected content in an applicative context. The applicative password is used if necessary.

import qualified Data.ByteString as B
import           Crypto.Store.PKCS8

[encryptedKey] <- readKeyFile "privkey.pem"
let askForPassword = putStr "Please enter password: " >> B.getLine
result <- recoverA (toProtectionPassword <$> askForPassword) encryptedKey
case result of
    Left err  -> putStrLn $ "Unable to recover key: " ++ show err
    Right key -> print key

Reading and writing PEM files

readPEMs :: FilePath -> IO [PEM] Source #

Read a PEM file from disk.

writePEMs :: FilePath -> [PEM] -> IO () Source #

Write a PEM file to disk.