h-gpgme-0.4.0.0: High Level Binding for GnuPG Made Easy (gpgme)

Copyright(c) Reto Hablützel 2015
LicenseMIT
Maintainerrethab@rethab.ch
Stabilityexperimental
Portabilityuntested
Safe HaskellNone
LanguageHaskell2010

Crypto.Gpgme

Contents

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 PubKeyAlgo Source

A public-key encryption algorithm

Constructors

Rsa 
RsaE 
RsaS 
ElgE 
Dsa 
Elg 

data UserId Source

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

Constructors

UserId 

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

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.

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 

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

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