-----
 Usage
 -----
 Brett Porter
 -----
 10 December 2005
 -----
 
Usage Instructions
 
  Currently only creation and verification of detached signatures is supported. This can be done in streaming and
  non-streaming mode.

  Both modes require that you have created a key ring.
  
* Creating a Key Ring

  A key ring object needs to be created, containing an input stream for both the public and secret key rings.
  The password for the secret key ring also needs to be passed in for creating signatures.
  
  For example, to create the Bouncy Castle key ring, the constructor is used:

-----
BouncyCastleKeyRing( InputStream secretKeyRing, InputStream publicKeyRing, char[] password );
-----

* Non-streaming Mode

  ~~TODO: link to Javadoc

  To sign data with a detached signature, create a <<<OpenPgpSigner>>>.
  
-----
signer = new BouncyCastleOpenPgpSigner();

signer.detachedSign(
  getClass().getResourceAsStream( "/test-input" ),  // binary input file
  signature,                                        // outputstream for the signature
  keyId,                                            // key ID
  keyRing,
  true );                                           // ascii armor?
-----

  Verifying the signature is similar.

-----
verifier = new BouncyCastleOpenPgpSignatureVerifier();

SignatureStatus status = verifier.verifyDetachedSignature(
  getClass().getResourceAsStream( "/test-input" ),  // binary input file
  signature,                                        // inputstream for the signature
  keyRing);
-----

* Streaming Mode

  ~~TODO: link to Javadoc
  
  To sign data in streaming mode, create an instance of <<<OpenPgpStreamingSigner>>>.
  
  The <<<update()>>> method is called on blocks of data to update the signature. Finally, <<<finish()>>> is called
  to receive the detached signature as a byte array.
  
-----
signer = new BouncyCastleOpenPgpStreamingSigner(
  new FileOutputStream( "file.asc" ),           // detached signature
  "ABC123D",                                    // key ID
  keyRing,
  true );                                       // ascii armor?
  
int len;
do
{
  len = read( buf );
  if ( len > 0 )
  {
    signer.update( buf );
  }
}
while ( len >= 0 );

byte[] signature = signer.finish();
-----

  Verifying a signature in streaming mode is similar.

-----
verifier = new BouncyCastleOpenPgpStreamingSignatureVerifier(
  new FileInputStream( "file.asc" ),            // detached signature
  keyRing,
  true );                                       // ascii armor?
  
int len;
do
{
  len = read( buf );
  if ( len > 0 )
  {
    verifier.update( buf );
  }
}
while ( len >= 0 );

SignatureStatus status = verifier.finish();
-----

  The <<<SignatureStatus>>> returned indicates whether the signature was valid and whether it was trusted.