freiheit.com technologies gmbh

com.freiheit.gnupg
Class GnuPGContext

java.lang.Object
  extended by com.freiheit.gnupg.GnuPGPeer
      extended by com.freiheit.gnupg.GnuPGContext

public class GnuPGContext
extends GnuPGPeer

Start here, because for all operations, you first need to create a GnuPGContext. Use one context object for every single thread or (really) take care about synchronizing access to the context from different threads.

How to create a context?

   GnuPGContext ctx = new GnuPGContext();
   
   
If you execute an operation, where GnuPG needs a passphrase (password, mantra) from you, you need to tell the library which Class is listening for such a request and is able to deliver the entered passphrase to the library. You can implement such a listener by yourself, but you can also use two pre-fabricated ones. (Of course, normally you should install gpg-agent/pinentry for this job...but some will need this ability to get passphrases from a database or so. And: This release is not checking for the existence of gpg-agent...so it won't work anyway.)

How to add a Passphrase-Listener to read a password from the console?

   ctx.setPassphraseListener(new GnuPGPassphraseConsole());
     //caution: you can still see the password while you are typing...
   
   
How to add a Passphrase-Listener to read a password from the swing dialog?
   ctx.setPassphraseListener(new GnuPGPassphraseWindow());
   
   

Author:
Stefan Richter, stefan@freiheit.com

Constructor Summary
GnuPGContext()
          Creates a new Context (use on context for one thread!)
 
Method Summary
 void addSigner(GnuPGKey key)
          Adds a Signer to this context.
 void clearSigners()
          Removes all signers from this context.
 GnuPGData createDataObject()
          Factory method to generate an empty GnuPGData-Object.
 GnuPGData createDataObject(byte[] data)
          Factory method to generate a GnuPGData-Object from a byte array.
 GnuPGData createDataObject(java.lang.String data)
          Factory method to generate a GnuPGData-Object from a String.
 void decrypt(GnuPGData cipher, GnuPGData plain)
          Decrypts the data from cipher and stores the result in plain.
 void destroy()
          This calls immediately the release method for the context in the underlying gpgme library.
 void encrypt(GnuPGKey[] recipients, GnuPGData plain, GnuPGData cipher)
          Encrypts the data from plain with the public key of each recipient.
protected  void finalize()
          Releases underlying datastructures.
 GnuPGKey[] generateEmptyKeyArray(int withLengthOf)
          Convenience method to generate empty key arrays.
 java.lang.String getFilename()
          Returns the executable gpg with path
 GnuPGKey getKeyByFingerprint(java.lang.String fingerprint)
          Gets the key with the supplied fingerprint from the keyring.
 java.lang.String getRequiredVersion()
          Returns the required version of the underlying GPGME lib.
 java.lang.String getVersion()
          Returns the version of the underlying GPGME lib version.
 boolean isArmor()
          Tells you, is the gpg engine uses ASCII armor.
 boolean isTextmode()
          Tells you, is the gpg engine is in text mode.
 GnuPGKey[] searchKeys(java.lang.String query)
          Find all keys matching query in keyring.
 void setArmor(boolean state)
          Tell the gpg engine to use ASCII armor.
 void setPassphraseListener(GnuPGPassphraseListener l)
          Sets a listener, if GPGME needs to request a passphrase from the user (or even from a program or a database..)
 void setTextmode(boolean state)
          Tell the gpg engine to set the text mode.
 void sign(GnuPGData plain, GnuPGData signature)
          Signs the data in plain and stores the result in signature.
 void verify(GnuPGData signature, GnuPGData signed, GnuPGData plain)
          Verifies a signature.
 
Methods inherited from class com.freiheit.gnupg.GnuPGPeer
getInternalRepresentation, setInternalRepresentation
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

GnuPGContext

public GnuPGContext()
Creates a new Context (use on context for one thread!)

Method Detail

getVersion

public java.lang.String getVersion()
Returns the version of the underlying GPGME lib version.

Returns:
library version as String (like "1.1.1")

getFilename

public java.lang.String getFilename()
Returns the executable gpg with path

Returns:
gpg executable as String (like "/usr/bin/gpg")

getRequiredVersion

public java.lang.String getRequiredVersion()
Returns the required version of the underlying GPGME lib.

Returns:
required library version as String (like "1.1.1")

isArmor

public boolean isArmor()
Tells you, is the gpg engine uses ASCII armor. Please check GPG/GPGME for documentation if you don't know what this means. (Try 'man gpg' on the command line and look for 'armor')

Returns:
boolean true if results will be ASCII armored, if false binary

setArmor

public void setArmor(boolean state)
Tell the gpg engine to use ASCII armor. Please check GPG/GPGME for documentation if you don't know what this means. (Try 'man gpg' on the command line and look for 'armor')

Parameters:
state - set true if results should be ASCII armored, set false if binary

isTextmode

public boolean isTextmode()
Tells you, is the gpg engine is in text mode. Please check GPG/GPGME for documentation if you don't know what this means.

Returns:
boolean true means text mode is on

setTextmode

public void setTextmode(boolean state)
Tell the gpg engine to set the text mode. Please check GPG/GPGME for documentation if you don't know what this means.

Parameters:
state - set true if you want text mode switched on

setPassphraseListener

public void setPassphraseListener(GnuPGPassphraseListener l)
Sets a listener, if GPGME needs to request a passphrase from the user (or even from a program or a database..)

A passphrase-listener is global to a jvm. This means, you can register only one listener.

I am working on this, but it is not so easy to access jvm methods from a specific object from a non-jvm thread, which the passphrase callback is...

Parameters:
l - a GnuPGPassphraseListener implementation
See Also:
GnuPGPassphraseListener

getKeyByFingerprint

public GnuPGKey getKeyByFingerprint(java.lang.String fingerprint)
                             throws GnuPGException
Gets the key with the supplied fingerprint from the keyring. This is also kind of a factory method to generate key objects, because you always need a context to access the keys in your keyring.

Parameters:
fingerprint - gpg fingerprint (must be in your keyring)
Returns:
GnuPGKey the key with the matching fingerprint
Throws:
GnuPGException
See Also:
GnuPGKey

createDataObject

public GnuPGData createDataObject(java.lang.String data)
                           throws GnuPGException
Factory method to generate a GnuPGData-Object from a String.

Parameters:
data - should not be null and should have a length > 0
Returns:
GnuPGData null is data is null or empty, otherwise a GnuPGData-Object
Throws:
GnuPGException

createDataObject

public GnuPGData createDataObject(byte[] data)
                           throws GnuPGException
Factory method to generate a GnuPGData-Object from a byte array.

Parameters:
data - should not be null and should have a length > 0
Returns:
GnuPGData null is data is null or empty, otherwise a GnuPGData-Object
Throws:
GnuPGException

createDataObject

public GnuPGData createDataObject()
                           throws GnuPGException
Factory method to generate an empty GnuPGData-Object.

Parameters:
data - should not be null and should have a length > 0
Returns:
GnuPGData null is data is null or empty, otherwise a GnuPGData-Object
Throws:
GnuPGException

generateEmptyKeyArray

public GnuPGKey[] generateEmptyKeyArray(int withLengthOf)
Convenience method to generate empty key arrays. To encrypt data, you need to supply a list of recipients in an array. This is a little helper. It will not search for keys! Its just an empty array.

Parameters:
withLengthOf - length of the array to generate (number of recipients)
Returns:
GnuPGKey empty array of keys
See Also:
GnuPGKey

searchKeys

public GnuPGKey[] searchKeys(java.lang.String query)
                      throws GnuPGException
Find all keys matching query in keyring.

Parameters:
query - allows the same expressions as gpg on command line
Returns:
GnuPGKey array of key objects with all matching keys
Throws:
GnuPGException
See Also:
GnuPGKey

encrypt

public void encrypt(GnuPGKey[] recipients,
                    GnuPGData plain,
                    GnuPGData cipher)
             throws GnuPGException
Encrypts the data from plain with the public key of each recipient. The result is stored in cipher.

Parameters:
recipients - Array with the public keys of all recipients
plain - text, that should be encrypted
cipher - text, the encrypted plain text after method call
Throws:
GnuPGException
See Also:
GnuPGData, GnuPGKey

decrypt

public void decrypt(GnuPGData cipher,
                    GnuPGData plain)
             throws GnuPGException
Decrypts the data from cipher and stores the result in plain.

Parameters:
cipher - text, holds the cipher to be decrypted
plain - text, holds the decrypted text after decryption
Throws:
GnuPGException
See Also:
GnuPGData

sign

public void sign(GnuPGData plain,
                 GnuPGData signature)
          throws GnuPGException
Signs the data in plain and stores the result in signature.

Parameters:
plain - data that you want to sign
signature - result of the operation
Throws:
GnuPGException

verify

public void verify(GnuPGData signature,
                   GnuPGData signed,
                   GnuPGData plain)
            throws GnuPGException
Verifies a signature.

Parameters:
signature - TODO
signed - TODO
plain - TODO
Throws:
GnuPGException

addSigner

public void addSigner(GnuPGKey key)
               throws GnuPGException
Adds a Signer to this context. All signature operation will uses this/these signer(s), until you clear the signers from the context. You remove all signers at once with a call to clearSigners().

Parameters:
key - that should be used for signing operations
Throws:
GnuPGException
See Also:
GnuPGKey

clearSigners

public void clearSigners()
                  throws GnuPGException
Removes all signers from this context. You add Signers with addSigner().

Throws:
GnuPGException

destroy

public void destroy()
This calls immediately the release method for the context in the underlying gpgme library. This method is called by the finalizer of the class anyway, but you can call it yourself if you want to get rid of a context at once and don't want to wait for the non-deterministic garbage-collector of the JVM.


finalize

protected void finalize()
Releases underlying datastructures. Simple calls the destroy() method.

Overrides:
finalize in class java.lang.Object

freiheit.com technologies gmbh

© 2005 freiheit.com technologies gmbh