freiheit.com technologies gmbh

## com.freiheit.gnupg
Class GnuPGContext

    java.lang.Object
      com.freiheit.gnupg.GnuPGPeer
          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