dev.o1c.jcryptobox

Class JCryptoBox

java.lang.Object

dev.o1c.jcryptobox.JCryptoBox

public class JCryptoBox
extends Object

Toolkit for authenticated public key and secret key cryptography. Data can be boxed to provide confidentiality and authenticity which can only be opened by intended recipients.

Boxes uses authenticated encryption (AES-GCM) which relies on two input parameters: a secret key and a nonce. Secret keys are automatically generated based on the given sender and recipient public keys. Public keys and their corresponding private keys form a keypair where the public keys can be safely shared with others while the private key should be kept safe.

The nonce parameter is an accompanying value to the secret key used in encrypting or decrypting a single message/packet. A nonce must not be reused with the same key! Use of a nonce can either be sequential numbers (useful in contexts where stable increasing numbers are guaranteed) or random byte strings. While a nonce can be of arbitrary length, the effective size of a GCM nonce is 12 bytes as longer values are hashed into a 12 byte value.

See Also:

JCryptoBox.Seal, JCryptoBox.Unseal

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	JCryptoBox.Seal Sealed boxes provide the ability for an anonymous sender to encrypt a message to a known recipient given their public key.
static class	JCryptoBox.Unseal Provides functionality to unseal a sealed box.

Field Summary

Fields

Modifier and Type	Field and Description
static int	TAG_LENGTH Number of bytes needed to store the authentication tag at the end of a box.

Method Summary

Modifier and Type	Method and Description
byte[]	box(byte[] nonce, byte[] message) Boxes the given message bytes and returns the boxed message.
byte[]	box(byte[] nonce, byte[] message, int offset, int length) Boxes the given message slice and returns the boxed message.
void	box(byte[] nonce, byte[] input, int inOffset, int inLength, byte[] output, int outOffset) Boxes the given slice of input data into the given output array at the given offset.
static JCryptoBox	boxing(KeyPair senderKeyPair, PublicKey recipientKey) Initializes a box to box data from the provided sender to the provided recipient.
static PrivateKey	decodePrivateKey(byte[] encodedPrivateKey) Decodes an encoded private key.
static PublicKey	decodePublicKey(byte[] encodedPublicKey) Decodes an encoded public key.
static byte[]	encodeKey(Key key) Encodes a key into its default encoded format.
static KeyPair	generateKeyPair() Generates a random public and private keypair.
byte[]	open(byte[] nonce, byte[] box) Opens the given boxed message and returns the decrypted message.
byte[]	open(byte[] nonce, byte[] box, int offset, int length) Opens the given boxed message slice and returns the decrypted message.
void	open(byte[] nonce, byte[] input, int inOffset, int inLength, byte[] output, int outOffset) Opens the given boxed input slice and writes the decrypted data to the given output array at the given offset.
static JCryptoBox	opening(KeyPair recipientKeyPair, PublicKey senderKey) Initializes a box to open data from the provided sender to the provided recipient.
static JCryptoBox.Seal	sealing(PublicKey recipient) Creates a box to seal to the provided recipient key for creating sealed boxes.
static JCryptoBox.Unseal	unsealing(KeyPair recipient) Creates a box to unseal from the provided recipient keypair for decrypting sealed boxes sent to the recipient.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TAG_LENGTH

public static final int TAG_LENGTH

Number of bytes needed to store the authentication tag at the end of a box.

See Also:

Constant Field Values

Method Detail

box

public void box(byte[] nonce,
                byte[] input,
                int inOffset,
                int inLength,
                byte[] output,
                int outOffset)

Boxes the given slice of input data into the given output array at the given offset.

Parameters:

nonce - nonce to use to encrypt the input data

input - array of bytes to read data to encrypt

inOffset - where in the input array to begin reading data

inLength - how many bytes to read and encrypt

output - array of bytes to write encrypted data to

outOffset - where in the output array to begin writing data

Throws:

IllegalArgumentException - if the output buffer is too small

NullPointerException - if any arrays are null

box

public byte[] box(byte[] nonce,
                  byte[] message,
                  int offset,
                  int length)

Boxes the given message slice and returns the boxed message.

Parameters:

nonce - nonce to use to encrypt the input message

message - array of bytes to read data to encrypt

offset - where in the message array to begin reading data to encrypt

length - how many bytes to read and encrypt

Returns:

the boxed message

Throws:

NullPointerException - if any arrays are null

box

public byte[] box(byte[] nonce,
                  byte[] message)

Boxes the given message bytes and returns the boxed message.

Parameters:

nonce - nonce to use to encrypt the input message

message - array of bytes to encrypt

Returns:

the boxed message

Throws:

NullPointerException - if any args are null

open

public void open(byte[] nonce,
                 byte[] input,
                 int inOffset,
                 int inLength,
                 byte[] output,
                 int outOffset)

Opens the given boxed input slice and writes the decrypted data to the given output array at the given offset.

Parameters:

nonce - nonce used to encrypt the boxed message

input - array of bytes to read boxed data to decrypt

inOffset - where in the input array to begin reading data to decrypt

inLength - length of the boxed message in bytes (includes authentication tag)

output - array of bytes to write decrypted message to

outOffset - where in the output array to begin writing decrypted data

Throws:

IllegalArgumentException - if the boxed data cannot be successfully authenticated and decrypted or if the output buffer is too small

NullPointerException - if any arrays are null

open

public byte[] open(byte[] nonce,
                   byte[] box,
                   int offset,
                   int length)

Opens the given boxed message slice and returns the decrypted message.

Parameters:

nonce - nonce used to encrypt the boxed message

box - array of bytes to read boxed data to decrypt

offset - where in the input array to begin reading data to decrypt

length - length of the boxed message in bytes (includes authentication tag)

Returns:

the decrypted message

Throws:

IllegalArgumentException - if the boxed data cannot be successfully authenticated and decrypted

NullPointerException - if any arrays are null

open

public byte[] open(byte[] nonce,
                   byte[] box)

Opens the given boxed message and returns the decrypted message.

Parameters:

nonce - nonce used to encrypt the boxed message

box - array of boxed data to decrypt

Returns:

the decrypted message

Throws:

IllegalArgumentException - if the boxed data cannot be successfully authenticated and decrypted

NullPointerException - if any args are null

boxing

public static JCryptoBox boxing(KeyPair senderKeyPair,
                                PublicKey recipientKey)

Initializes a box to box data from the provided sender to the provided recipient.

Parameters:

senderKeyPair - keypair of the principal sending the boxed data

recipientKey - public key of the principal opening the boxed data

Returns:

a new box ready to encrypt data from the sender to the recipient

Throws:

NullPointerException - if any args are null

See Also:

opening(KeyPair, PublicKey)

opening

public static JCryptoBox opening(KeyPair recipientKeyPair,
                                 PublicKey senderKey)

Initializes a box to open data from the provided sender to the provided recipient.

Parameters:

recipientKeyPair - keypair of the principal opening the boxed data

senderKey - public key of the principal who sent the boxed data

Returns:

a new box ready to decrypt data from the sender to the recipient

Throws:

NullPointerException - if any args are null

See Also:

boxing(KeyPair, PublicKey)

sealing

public static JCryptoBox.Seal sealing(PublicKey recipient)

Creates a box to seal to the provided recipient key for creating sealed boxes.

Parameters:

recipient - public key of the principal receiving the sealed box

Returns:

a new box seal ready to encrypt data to the recipient

Throws:

NullPointerException - if the provided key is null

See Also:

unsealing(KeyPair)

unsealing

public static JCryptoBox.Unseal unsealing(KeyPair recipient)

Creates a box to unseal from the provided recipient keypair for decrypting sealed boxes sent to the recipient.

Parameters:

recipient - keypair of recipient of sealed boxes

Returns:

a new box unseal ready to decrypt data to the recipient

Throws:

NullPointerException - if the provided keypair is null

See Also:

sealing(PublicKey)

generateKeyPair

public static KeyPair generateKeyPair()

Generates a random public and private keypair.

Returns:

newly generated random keypair

encodeKey

public static byte[] encodeKey(Key key)

Encodes a key into its default encoded format. For public keys, this format is suitable for X509EncodedKeySpec, while private keys are formatted for PKCS8EncodedKeySpec.

Parameters:

key - key to encode

Returns:

the encoded form of the key

Throws:

NullPointerException - if the provided key is null

decodePublicKey

public static PublicKey decodePublicKey(byte[] encodedPublicKey)

Decodes an encoded public key.

Parameters:

encodedPublicKey - encoded key data to parse and decode

Returns:

the decoded PublicKey

Throws:

IllegalArgumentException - if the provided public key data is invalid

NullPointerException - if the provided key is null

decodePrivateKey

public static PrivateKey decodePrivateKey(byte[] encodedPrivateKey)

Decodes an encoded private key.

Parameters:

encodedPrivateKey - encoded key data to parse and decode

Returns:

the decoded PrivateKey

Throws:

IllegalArgumentException - if the provided private key data is invalid

NullPointerException - if the provided key is null