Copyright	(c) Reto Hablützel 2015
License	MIT
Maintainer	rethab@rethab.ch
Stability	experimental
Portability	untested
Safe Haskell	None
Language	Haskell2010

Crypto.Gpgme

Contents

Context
- Passphrase callbacks
Keys
Information about keys
Encryption
Error handling
Other Types

Description

High Level Binding for GnuPG Made Easy (gpgme)

Most of these functions are a one-to-one translation from GnuPG API with some Haskell idiomatics to make the API more convenient.

See the GnuPG manual for more information: https://www.gnupg.org/documentation/manuals/gpgme.pdf

Example (from the tests):

let alice_pub_fpr = "EAACEB8A"                                      
                                                                    
Just enc <- withCtx "test/bob" "C" OpenPGP $ \bCtx -> runMaybeT $ do
        aPubKey <- MaybeT $ getKey bCtx alice_pub_fpr NoSecret      
        fromRight $ encrypt bCtx [aPubKey] NoFlag plain             
                                                                    
-- decrypt                                                          
dec <- withCtx "test/alice" "C" OpenPGP $ \aCtx ->                  
        decrypt aCtx enc

Synopsis

Context

data Ctx Source

Context to be passed around with operations. Use newCtx or withCtx in order to obtain an instance.

newCtx Source

Arguments

:: String	path to gpg homedirectory
-> String	locale
-> Protocol	protocol
-> IO Ctx

Creates a new Ctx from a homedirectory, a locale and a protocol. Needs to be freed with freeCtx, which is why you are encouraged to use withCtx.

freeCtx :: Ctx -> IO () Source

Free a previously created Ctx

withCtx Source

Arguments

:: String	path to gpg homedirectory
-> String	locale
-> Protocol	protocol
-> (Ctx -> IO a)	action to be run with ctx
-> IO a

Runs the action with a new Ctx and frees it afterwards

See newCtx for a descrption of the parameters.

setArmor :: Bool -> Ctx -> IO () Source

Sets armor output on ctx

Passphrase callbacks

isPassphraseCbSupported :: Ctx -> Bool Source

Are passphrase callbacks supported?

This functionality is known to be broken in some gpg versions, see setPassphraseCb for details.

type PassphraseCb Source

Arguments

= String	user ID hint
-> String	passphrase info
-> Bool	`True` if the previous attempt was bad
-> IO (Maybe String)

A callback invoked when the engine requires a passphrase to proceed. The callback should return Just the requested passphrase, or Nothing to cancel the operation.

setPassphraseCallback Source

Arguments

:: Ctx	context
-> Maybe PassphraseCb	a callback, or Nothing to disable
-> IO ()

Set the callback invoked when a passphrase is required from the user.

Note that the operation of this feature is a bit inconsistent between GPG versions. GPG 1.4 using the use-agent option and GPG >= 2.1 require that the gpg-agent for the session has the allow-loopback-pinentry option enabled (this can be achieved by adding allow-loopback-pinentry to gpg-agent.conf. GPG versions between 2.0 and 2.1 do not support the --pinentry-mode option necessary for this support.

See http://lists.gnupg.org/pipermail/gnupg-devel/2013-February/027345.html and the gpgme-tool example included in the gpgme tree for details.

Keys

data Key Source

A key from the context

getKey Source

Arguments

:: Ctx	context to operate in
-> Fpr	fingerprint
-> IncludeSecret	whether to include secrets when searching for the key
-> IO (Maybe Key)

Returns a Key from the context based on its fingerprint. Returns Nothing if no Key with this Fpr exists.

listKeys Source

Arguments

:: Ctx	context to operate in
-> IncludeSecret	whether to include the secrets
-> IO [Key]

Returns a list of known Keys from the context.

Information about keys

data Validity Source

The validity of a user identity

Constructors

ValidityUnknown
ValidityUndefined
ValidityNever
ValidityMarginal
ValidityFull
ValidityUltimate

Instances

Eq Validity Source
Ord Validity Source
Show Validity Source

data PubKeyAlgo Source

A public-key encryption algorithm

Constructors

Rsa
RsaE
RsaS
ElgE
Dsa
Elg

Instances

Eq PubKeyAlgo Source
Ord PubKeyAlgo Source
Show PubKeyAlgo Source

data KeySignature Source

A key signature

Constructors

KeySig
Fields keysigAlgorithm :: PubKeyAlgo keysigKeyId :: String keysigTimestamp :: Maybe UTCTime keysigExpires :: Maybe UTCTime keysigUserId :: UserId

data UserId Source

A user ID consisting of a name, comment, and email address.

Constructors

UserId
Fields userId :: String userName :: String userEmail :: String userComment :: String

Instances

Eq UserId Source
Ord UserId Source
Show UserId Source

data KeyUserId Source

A user ID

Constructors

KeyUserId
Fields keyuserValidity :: Validity keyuserId :: UserId keyuserSignatures :: [KeySignature]

keyUserIds :: Key -> [KeyUserId] Source

data SubKey Source

Constructors

SubKey
Fields subkeyAlgorithm :: PubKeyAlgo subkeyLength :: Int subkeyKeyId :: String subkeyFpr :: Fpr subkeyTimestamp :: Maybe UTCTime subkeyExpires :: Maybe UTCTime subkeyCardNumber :: Maybe String

keySubKeys :: Key -> [SubKey] Source

Encryption

type Signature = ByteString Source

a signature

data SignatureSummary Source

the summary of a signature status

Constructors

BadPolicy	A policy requirement was not met
CrlMissing	The CRL is not available
CrlTooOld	Available CRL is too old
Green	The signature is good but one might want to display some extra information
KeyExpired	The key or one of the certificates has expired
KeyMissing	Can’t verify due to a missing key or certificate
KeyRevoked	The key or at least one certificate has been revoked
Red	The signature is bad
SigExpired	The signature has expired
SysError	A system error occured
UnknownSummary C'gpgme_sigsum_t	The summary is something else
Valid	The signature is fully valid

Instances

Eq SignatureSummary Source
Ord SignatureSummary Source
Show SignatureSummary Source

type VerificationResult = [(GpgmeError, [SignatureSummary], Fpr)] Source

encrypt :: Ctx -> [Key] -> Flag -> Plain -> IO (Either [InvalidKey] Encrypted) Source

encrypt for a list of recipients

encryptSign :: Ctx -> [Key] -> Flag -> Plain -> IO (Either [InvalidKey] Encrypted) Source

encrypt and sign for a list of recipients

encrypt' :: String -> Fpr -> Plain -> IO (Either String Encrypted) Source

Convenience wrapper around withCtx and withKey to encrypt a single plaintext for a single recipient with its homedirectory.

encryptSign' :: String -> Fpr -> Plain -> IO (Either String Encrypted) Source

Convenience wrapper around withCtx and withKey to encrypt and sign a single plaintext for a single recipient with its homedirectory.

decrypt :: Ctx -> Encrypted -> IO (Either DecryptError Plain) Source

Decrypts a ciphertext

decrypt' :: String -> Encrypted -> IO (Either DecryptError Plain) Source

Convenience wrapper around withCtx and withKey to decrypt a single ciphertext with its homedirectory.

decryptVerify :: Ctx -> Encrypted -> IO (Either DecryptError Plain) Source

Decrypts and verifies a ciphertext

decryptVerify' :: String -> Encrypted -> IO (Either DecryptError Plain) Source

Convenience wrapper around withCtx and withKey to decrypt and verify a single ciphertext with its homedirectory.

verifyDetached :: Ctx -> Signature -> ByteString -> IO (Either GpgmeError VerificationResult) Source

Verify a payload with a detached signature

verifyDetached' :: String -> Signature -> ByteString -> IO (Either GpgmeError VerificationResult) Source

Convenience wrapper around withCtx to verify a single detached signature with its homedirectory.

verifyPlain :: Ctx -> Signature -> ByteString -> IO (Either GpgmeError (VerificationResult, ByteString)) Source

Verify a payload with a plain signature

verifyPlain' :: String -> Signature -> ByteString -> IO (Either GpgmeError (VerificationResult, ByteString)) Source

Convenience wrapper around withCtx to verify a single plain signature with its homedirectory.

Error handling

data GpgmeError Source

A GPGME error.

Errors in GPGME consist of two parts: a code indicating the nature of the fault, and a source indicating from which subsystem the error originated.

Instances

Eq GpgmeError Source
Ord GpgmeError Source
Show GpgmeError Source

errorString :: GpgmeError -> String Source

An explanatory string for a GPGME error.

sourceString :: GpgmeError -> String Source

An explanatory string describing the source of a GPGME error

Other Types

type Fpr = ByteString Source

a fingerprint

type Encrypted = ByteString Source

an ciphertext

type Plain = ByteString Source

a plaintext

data Protocol Source

the protocol to be used in the crypto engine

Constructors

CMS
GPGCONF
OpenPGP
UNKNOWN

Instances

Eq Protocol Source
Ord Protocol Source
Show Protocol Source

type InvalidKey = (String, Int) Source

The fingerprint and an error code

data IncludeSecret Source

Whether to include secret keys when searching

Constructors

WithSecret	do not include secret keys
NoSecret	include secret keys

Instances

Eq IncludeSecret Source
Ord IncludeSecret Source
Show IncludeSecret Source

data Flag Source

Constructors

AlwaysTrust
NoFlag

Instances

Eq Flag Source
Ord Flag Source
Show Flag Source

data DecryptError Source

error indicating what went wrong in decryption

Constructors

NoData	no data to decrypt
Failed	not a valid cipher
BadPass	passphrase for secret was wrong
Unknown GpgmeError	something else went wrong

Instances

Eq DecryptError Source
Ord DecryptError Source
Show DecryptError Source