Skip to content

Latest commit

 

History

History
437 lines (308 loc) · 21.5 KB

README.md

File metadata and controls

437 lines (308 loc) · 21.5 KB
Raw

Looking for contributors: It's boring to work alone - If you are interested in contributing to an open source project please open an issue to discuss your ideas or create a PR

Build Status codecov Codacy Badge license Download Known Vulnerabilities

Say Thanks!

Mission Statement

Make using Bouncy Castle with OpenPGP great fun again!

This project gives you the following super-powers

Examples

Bouncy GPG comes with several examples build in.

Key management

Bouncy GPG supports reading gpg keyrings and parsing keys exported via gpg --export and gpg --export-secret-key.

The unit tests have some examples creating/reading keyrings.

The easiest way to manage keyrings is to use the pre-defined KeyringConfigs.

Encrypt & sign a file and then decrypt it & validate the signature

The following snippet encrypts a secret message to recipient@example.com (and also self-encrypts it to sender@example.com), and signs with sender@example.com.

The encrypted message is then decrypted and the signature is verified. (This is from a documentation test).

    final String original_message = "I love deadlines. I like the whooshing sound they make as they fly by. Douglas Adams";

    // Most likely you will use  one of the KeyringConfigs.... methods.
    // These are wrappers for the test.
    KeyringConfig keyringConfigOfSender = Configs
        .keyringConfigFromResourceForSender();

    ByteArrayOutputStream result = new ByteArrayOutputStream();

    try (
        BufferedOutputStream bufferedOutputStream = new BufferedOutputStream(result);

        final OutputStream outputStream = BouncyGPG
            .encryptToStream()
            .withConfig(keyringConfigOfSender)
            .withStrongAlgorithms()
            .toRecipients("recipient@example.com", "sender@example.com")
            .andSignWith("sender@example.com")
            .binaryOutput()
            .andWriteTo(bufferedOutputStream);
        // Maybe read a file or a webservice?
        final ByteArrayInputStream is = new ByteArrayInputStream(original_message.getBytes())
    ) {
      Streams.pipeAll(is, outputStream);
    // It is very important that outputStream is closed before the result stream is read.
    // The reason is that GPG writes the signature at the end of the stream.
    // This is triggered by closing the stream.
    // In this example outputStream is closed via the try-with-resources mechanism of Java
    }

    result.close();
    byte[] chipertext = result.toByteArray();

    //////// Now decrypt the stream and check the signature

    // Most likely you will use  one of the KeyringConfigs.... methods.
    // These are wrappers for the test.
    KeyringConfig keyringConfigOfRecipient = Configs
        .keyringConfigFromResourceForRecipient();

    final OutputStream output = new ByteArrayOutputStream();
    try (
        final InputStream cipherTextStream = new ByteArrayInputStream(chipertext);

        final BufferedOutputStream bufferedOut = new BufferedOutputStream(output);

        final InputStream plaintextStream = BouncyGPG
            .decryptAndVerifyStream()
            .withConfig(keyringConfigOfRecipient)
            .andRequireSignatureFromAllKeys("sender@example.com")
            .fromEncryptedInputStream(cipherTextStream)

    ) {
      Streams.pipeAll(plaintextStream, bufferedOut);
    }

    output.close();
    final String decrypted_message = new String(((ByteArrayOutputStream) output).toByteArray());

    assertEquals(original_message, decrypted_message);

Performance

Bouncy castle is often fast enough to not be the bottleneck. That said, here are some metrics to give you an indication of the performance:

Use Case MBP 2,9 GHz Intel Core i5, Java 1.8.0_111 (please add more via PR)
Encrypt & sign 1GB random ~64s (16 MB/s)
Decrypt 1GB random ~32s (32 MB/s)

Demos

The directory examples contains several examples that show how easy some common use cases are implemented.

demo_decrypt.sh

Decrypt a file and verify the signature.

  • decrypt.sh SOURCEFILE DESTFILE

Uses the testing keys to decrypt a file. Useful for performance measurements and gpg interoperability.

demo_encrypt.sh

Encrypt and sign a file.

  • encrypt.sh SOURCEFILE DESTFILE

Uses the testing keys to encrypt a file. Useful for performance measurements and gpg interoperability.

demo_reencrypt.sh

A GPG encrypted ZIP file is decrypted on the fly. The structure of the ZIP is then written to disk. All files are re-encrypted before saving them.

  • demo_reencrypt.sh TARGET -- decrypts an encrypted ZIP file containing three files (total size: 1.2 GB) AND re-encrypts each of the files in the ZIP to the TARGET dir.

The sample shows how e.g. batch jobs can work with large files without leaving plaintext on disk (together with Transparent GPG decryption).

This scheme has some very appealing benefits:

  • Data in transit is always encrypted with public key cryptography. Indispensable when you have to use ftp, comforting when you use https and the next Heartbleed pops up.
  • Data at rest is always encrypted with public key cryptography. When (not if) you get hacked, this can make all the difference between "Move along folks, nothing to see here!" and "I lost confidential customer data to the competition".
  • You still need to protect the private keys, but this is considerable easier than the alternatives.

Consider the following batch job:

  1. The customer sends a large (several GB) GPG encrypted ZIP archive containing a directory structure with several data files
  2. Your pre-processing needs to split up the data for further processing
  3. pre-processing stream-processes the GPG/ZIP archive
    1. The GPG stream is decrypted using the BouncyGPG.decryptAndVerifyStream() InputStream
    2. The ZIP file is processed with ExplodeAndReencrypt
      1. Each file from the archive is processed
      2. And transparently encrypted with GPG and stored for further processing
  4. The processing job transparently reads the files without writing plaintext to the disk.

HOWTO

Have a look at the example classes to see how easy it is to use Bouncy Castle PGP.

#1 Register Bouncy Castle Provider

Add bouncy castle as a dependency and then install the provider before in your application.

Add Build Dependency

Gradle

// build.gradle
// in build.gradle add a dependency to bouncy castle and bouncy-gpg

//...

repositories {
    mavenCentral()
    // jcenter() - optional.
}

//...

//  ...
dependencies {
    compile 'org.bouncycastle:bcprov-jdk15on:1.64'
    compile 'org.bouncycastle:bcpg-jdk15on:1.64'
    //  ...
    compile 'name.neuhalfen.projects.crypto.bouncycastle.openpgp:bouncy-gpg:2.+'
   // ...
  }

Maven

    <dependency>
        <groupId>name.neuhalfen.projects.crypto.bouncycastle.openpgp</groupId>
        <artifactId>bouncy-gpg</artifactId>
        <version>2.2.0</version>
    </dependency>

 

Install Provider

    // in one of you classed install the BC provider
    BouncyGPG.registerProvider();

#2 Important Classes

Class Use when you want to
BouncyGPG Starting point for the convenient fluent en- and decryption API.
KeyringConfigs Create default implementations for GPG keyring access. You can also create your own implementations by implementing KeyringConfig.
KeyringConfigCallbacks Used by KeyringConfigs. Create default implementations to provide secret-key passwords.
DefaultPGPAlgorithmSuites Select from predefined algorithms suites or create your won with PGPAlgorithmSuite.
ReencryptExplodedZipSinglethread Work with encrypted ZIPs

FAQ

Why should I use this?
For common use cases this project is easier than vanilla Bouncy Castle. It also has a pretty decent unit test coverage. It is free (speech & beer).
Can I just grab a class or two for my project?
Sure! Just grab it and hack away! The code is placed under the Apache License 2.0, you can't get much more permissive than this.
Why is the test coverage so low?
Test coverage for 'non-example' code is >85%. Most of the not tested cases are either trivial OR lines that throw exceptions when the input format is broken/handled by bouncycastle directly.
How can I contribute?
Pullrequests are welcome! Please state in your PR that you put your code under the LICENSE.
I am getting 'org.bouncycastle.openpgp.PGPException: checksum mismatch ..' exceptions
The passphrase to your private key is very likely wrong (or you did not pass a passphrase).
I am getting 'java.security.InvalidKeyException: Illegal key size' / 'java.lang.SecurityException: Unsupported keysize or algorithm parameters'
The unrestricted policy files for the JVM are probably not installed.
I am getting 'java.io.EOFException: premature end of stream in PartialInputStream' while decrypting / Sender can't validate signature
This often happens when encrypting to a 'ByteArrayOutputStream' and the encryption stream is not propely closed. The reason is that GPG writes the signature at the end of the stream. This is triggered by closing the stream.
Where is 'secring.pgp'?
'secring.gpg' has been removed in gpg 2.1. Use the other methods to read private keys.
Should I use secring.pgp?
No, you should implement your own key handling strategy. See On using (sec|pub)ring.gpg below.
Can I generate keys?
Yes, RSA key generation is supported since 2.2.0. Generating ECC keys is NOT supported yet, although the code is there (gpg integration tests fail)
Is compatibility with GnuPG tested?
Yes, since 2.2.0 the gradle task integrationTest tests the interoperability with gpg.

On using (sec|pub)ring.gpg

I strongly advise against using secring.gpg or pubring.gpg for production systems. These files are an undocumented API of gnupg: usable, but can change or show unexpected results. E.g. with GPG 2.1 the secring.gpg file gets no longer updated and will provide you with stale data (emphasis by me):

To ease the migration to the no-secring method, gpg detects the presence of a secring.gpg and converts the keys on-the-fly to the the key store of gpg-agent (this is the private-keys-v1.d directory below the GnuPG home directory (~/.gnupg)). This is done only once and an existing secring.gpg is then not anymore touched by gpg. This allows co-existence of older GnuPG versions with GnuPG 2.1. However, any change to the private keys using the new gpg will not show up when using pre-2.1 versions of GnuPG and vice versa.

Recommendation: InMemoryKeyring

Most applications should manage their keys in an application specific database. Though this might seem more complex than just using the existing keyring files it has a some nice advantages:

  • No dependency on the gpg executable
  • Keys can be managed remotely (e.g. via the applications database)
  • Key management is enforced to happen via the application
  • Key management for distributed (scale out / cloud) systems is much easier when keys are not managed by the operating system

HOWTO use InMemoryKeyring

To use the InMemoryKeyring you first need to export the keys. Then you put them in your application data(base).

Exporting the keys from gpg

Export the keys with gpg (gpg --export-secret-key -a user@example.com and gpg --export -a user@example.com):

gpg --export -a user@example.com > user@example.com.pub.gpg
cat user@example.com.pub.gpg

-----BEGIN PGP PUBLIC KEY BLOCK-----
...
-----END PGP PUBLIC KEY BLOCK-----

# You need to input keys passphrase here
gpg --export-secret-key -a user@example.com > user@example.com.secret.gpg
cat user@example.com.secret.gpg

-----BEGIN PGP PRIVATE KEY BLOCK-----
...
-----END PGP PRIVATE KEY BLOCK-----

Importing the keys

A few examples for using the InMemoryKeyring can be found in the Test code.

Here is the short version:

  public static KeyringConfig keyringConfigInMemoryForKeys(final String exportedPubKey, final String exportedPrivateKey, final String passphrase) throws IOException, PGPException {

    final InMemoryKeyring keyring = KeyringConfigs.forGpgExportedKeys(KeyringConfigCallbacks.withPassword(passphrase);

    keyring.addPublicKey(exportedPubKey.getBytes("US-ASCII"));
   // you can add many more public keys

    keyring.addSecretKey(exportedPrivateKey.getBytes("US-ASCII"));
   // you can add many more privvate keys

    return keyring;
  }

Generating Keys

The most straight forward way is to call BouncyGPG::createSimpleKeyring():

    final KeyringConfig rsaKeyRing = BouncyGPG.createSimpleKeyring()
        .simpleRsaKeyRing(UID_JULIET, RsaLength.RSA_3072_BIT);

Here is a more complex case with dedicated subkeys for signing, encryption, and authentication:

        final KeySpec signingSubey = KeySpecBuilder
                .newSpec(RSAForSigningKeyType.withLength(RsaLength.RSA_2048_BIT))
                .allowKeyToBeUsedTo(KeyFlag.SIGN_DATA)
                .withDefaultAlgorithms();

        final KeySpec authenticationSubey = KeySpecBuilder
                .newSpec(RSAForEncryptionKeyType.withLength(RsaLength.RSA_2048_BIT))
                .allowKeyToBeUsedTo(KeyFlag.AUTHENTICATION)
                .withDefaultAlgorithms();

        final KeySpec encryptionSubey = KeySpecBuilder
                .newSpec(RSAForEncryptionKeyType.withLength(RsaLength.RSA_2048_BIT))
                .allowKeyToBeUsedTo(KeyFlag.ENCRYPT_COMMS, KeyFlag.ENCRYPT_STORAGE)
                .withDefaultAlgorithms();

        final KeySpec masterKey = KeySpecBuilder.newSpec(
                RSAForSigningKeyType.withLength(RsaLength.RSA_3072_BIT)
        )
                .allowKeyToBeUsedTo(KeyFlag.CERTIFY_OTHER)
                .withDetailedConfiguration()
                .withPreferredSymmetricAlgorithms(
                        PGPSymmetricEncryptionAlgorithms.recommendedAlgorithms()
                )
                .withPreferredHashAlgorithms(
                        PGPHashAlgorithms.recommendedAlgorithms()
                )
                .withPreferredCompressionAlgorithms(
                        PGPCompressionAlgorithms.recommendedAlgorithms()
                )
                .withFeature(Feature.MODIFICATION_DETECTION)
                .done();

        final KeyringConfig complexKeyRing = BouncyGPG
                .createKeyring()
                .withSubKey(signingSubey)
                .withSubKey(authenticationSubey)
                .withSubKey(encryptionSubey)
                .withMasterKey(masterKey)
                .withPrimaryUserId(uid)
                .withPassphrase(Passphrase.fromString(passphrase))
                .build();

        return complexKeyRing;
Persisting generated keys

The bouncy castle functions can be used to persist keys. ExportGeneratedKeysTest.java shows how to do that.

Using the config

final InMemoryKeyring keyring = keyringConfigInMemoryForKeys(...);

final InputStream decryptedPlaintextStream = BouncyGPG
        .decryptAndVerifyStream()
        .withConfig(keyring)
        ....

Building

The project is a basic gradle build. All the scripts use ./gradlew installDist

The coverage report (incl. running tests) is generated with ./gradlew check.

Publish to jcenter

./gradlew bintrayUpload

CAVE

LICENSE

This code is placed under the Apache License 2.0. Don't forget to adhere to the BouncyCastle License (http://bouncycastle.org/license.html).