B4J Programming Press on the image to return to the main documentation page.

Encryption

Written by Andrew Graham

This library implements various encryption and encoding methods

The following objects are available:

Base64: used to encode and decode data in Base64 representation.
Cipher: used for encrypting/decrypting data.
KeyGenerator: used to generate and mainpulate secret keys for symmetric ciphers.
MAC: (Message Authentication Code) used generate secret key encrypted message digests.
MessageDigest: used to calculate the message digest (hash) of specified data.
SecureRandom: used to generate pseudo-random numbers.
Signature: are used to sign data and verify digital signatures.

More information is given on each object in its help comments.

These comments are intended to document the facilities provided by this library.
They are not intended in any way to cover their practical use. It is assumed that
you know what you are doing when you use this library.

Documentation on the Java Cryptography Architecture may be found here.

A list of standard names used in the Java Cryptography Architecture may be found here.

Any implementation does not neccessarily include the complete list. A list of included
Service Providers may be obtained with the Cipher.GetServices method and they may be passed
individually to Cipher.GetAlgorithms to get the list of supported algorithms for that provider.

List of types:

Base64
Cipher
KeyGenerator
KeyPairGenerator
Mac
MessageDigest
SecureRandom
Signature

Base64

The Base64 object encodes and decodes to and from Base64 notation.

Events:

None

Members:


  BreakLines As Boolean

  DecodeBtoB (b64bytes() As Byte, offset As Int, length As Int) As Byte()

  DecodeBtoS (b64bytes() As Byte, offset As Int, length As Int, encoding As String) As String

  DecodeStoB (b64string As String) As Byte()

  DecodeStoS (b64string As String, encoding As String) As String

  EncodeBtoB (data() As Byte, offset As Int, length As Int) As Byte()

  EncodeBtoS (data() As Byte, offset As Int, length As Int) As String

  EncodeStoB (data As String, encoding As String) As Byte()

  EncodeStoS (data As String, encoding As String) As String

  LineLength As Int

  UrlSafe As Boolean

  Version As Double [read only]

Members description:

BreakLines As Boolean
Gets or sets whether line breaks are added to the Base64 output when encoding.
DecodeBtoB (b64bytes() As Byte, offset As Int, length As Int) As Byte()
Decode a byte array of Base64 characters into a byte array. Tab, CR, LF and Space
characters in the data are ignored, invalid Base64 characters throw an exception.
DecodeBtoS (b64bytes() As Byte, offset As Int, length As Int, encoding As String) As String
Decode an array of Base64 characters into a string. Tab, CR, LF and Space
characters in the data are ignored, invalid Base64 characters throw an exception.
Encoding defines the encoding of the byte data of the original coded string.
DecodeStoB (b64string As String) As Byte()
Decode a String of Base64 characters into a byte array. Tab, CR, LF and Space
characters in the string are ignored, invalid Base64 characters throw an exception.
DecodeStoS (b64string As String, encoding As String) As String
Decode a string of Base64 characters into a string. Tab, CR, LF and Space
characters in the data are ignored, invalid Base64 characters throw an exception.
Encoding defines the encoding of the byte data of the original coded string.
EncodeBtoB (data() As Byte, offset As Int, length As Int) As Byte()
Encode a byte array into a byte array of Base64 characters.
EncodeBtoS (data() As Byte, offset As Int, length As Int) As String
Encode a byte array into a string of Base64 characters.
EncodeStoB (data As String, encoding As String) As Byte()
Encode a string into a byte array of Base64 characters. The string is converted
into an array of bytes according to encoding and then coded as Base64.
EncodeStoS (data As String, encoding As String) As String
Encode a string into a string of Base64 characters. The string is converted
into an array of bytes according to encoding and then coded as Base64.
LineLength As Int
Gets or sets the number of Base64 characters placed on each line when line breaks
are being added to the Base64 output when encoding.
UrlSafe As Boolean
Gets or sets whether the Base64 encoding and decoding is done in a "URL safe" manner.
In "URL safe mode" the "plus" character in the Base64 becomes a "hyphen" and the
"slash" character becomes an "underscore".
Version As Double [read only]
Returns the version number of the library.

Cipher

This object provides the functionality of a secret (symmetric) key encryptor and
decryptor. The algorithms may commonly be one of the following, there are others not listed here.

AES also known as Rijndael is a 128-bit block cipher supporting keys of 128, 192, and 256 bits.
DES The Digital Encryption Standard as described in FIPS PUB 46-3.
DESede Triple DES Encryption (also known as DES-EDE, 3DES, or Triple-DES).

Events:

None

Members:


  Decrypt (data() As Byte, key As java.security.Key, useIV As Boolean) As Byte()

  Encrypt (data() As Byte, key As java.security.Key, useIV As Boolean) As Byte()

  GetAlgorithms (servicename As String) As String()

  GetServices As String()

  InitialisationVector() As Byte

  Initialize (transformation As String)

  Version As Double [read only]

Members description:

Decrypt (data() As Byte, key As java.security.Key, useIV As Boolean) As Byte()
Encrypts the supplied data using the key provided. If an initialisation vector is
to be used then useIV should be set True and the InitialisationVector property set
to the required data.
Encrypt (data() As Byte, key As java.security.Key, useIV As Boolean) As Byte()
Decrypts the supplied data using the key provided. If an initialisation vector is
to be used then useIV should be set True and the InitialisationVector property set
to the required data.
GetAlgorithms (servicename As String) As String()
Returns an array of strings containing the algorithms that the specified security
provider implements.
GetServices As String()
Returns an array of strings containing the security providers present on the system.
InitialisationVector() As Byte
Gets or sets the initialisation vector array.
Initialize (transformation As String)
Initialises the Cipher object to perform the supplied transformation.

A transformation is a string that describes the operation (or set of operations) to be performed
on the given input to produce some output. A transformation always includes the name of a
cryptographic algorithm (e.g., DES), and may be followed by a mode and padding scheme.

A transformation is of the form "algorithm/mode/padding" or "algorithm".
For example, the following are valid transformations:
"DES/CBC/PKCS5Padding"
"DES" note that this is actually a synonym for "DES/ECB/PKCS5Padding".
"DES/ECB/NoPadding" use this for simple single block encoding.

Algorithm may commonly be one of the following, there are others not listed here.
AES also known as Rijndael is a 128-bit block cipher supporting keys of 128, 192, and 256 bits.
DES The Digital Encryption Standard as described in FIPS PUB 46-3.
DESede Triple DES Encryption (also known as DES-EDE, 3DES, or Triple-DES).

Mode may commonly be one of the following, there are others not listed here.
NONE No mode.
CBC Cipher Block Chaining Mode, as defined in FIPS PUB 81.
CFB, CFBx Cipher Feedback Mode, as defined in FIPS PUB 81.
ECB Electronic Codebook Mode, as defined in FIPS PUB 81.
OFB, OFBx Output Feedback Mode, as defined in FIPS PUB 81.
Using modes such as CFB and OFB, block ciphers can encrypt data in units smaller than
the cipher's actual block size. When requesting such a mode, you may optionally specify the
number of bits to be processed at a time by appending this number to the mode name as shown
in the "DES/CFB8/NoPadding" and "DES/OFB32/PKCS5Padding" transformations. If no such
number is specified, a provider-specific default is used. Thus block ciphers can be turned into
byte-oriented stream ciphers by using an 8 bit mode such as CFB8 or OFB8.

Padding may be one of
NoPadding
ISO10126Padding
PKCS1Padding The padding scheme described in PKCS1, used with the RSA algorithm.
PKCS5Padding The padding scheme described in RSA Laboratories, "PKCS5: version 1.5, November 1993.
SSL3Padding The padding scheme defined in the SSL Protocol Version 3.0, November 18, 1996,
section 5.2.3.2 (CBC block cipher):
Version As Double [read only]
Returns the version number of the library.

KeyGenerator

This object provides the functionality of a secret (symmetric) key generator.
KeyGenerator objects are reusable, i.e., after a key has been generated, the same
KeyGenerator object can be re-used to generate further keys.

Algorithm may commonly be one of the following, there are others not listed here.
AES also known as Rijndael is a 128-bit block cipher supporting keys of 128, 192, and 256 bits.
DES The Digital Encryption Standard as described in FIPS PUB 46-3.
DESede Triple DES Encryption (also known as DES-EDE, 3DES, or Triple-DES).

Events:

None

Members:


  Format As String [read only]

  GenerateKey As javax.crypto.SecretKey

  Initialize (algorithm As String)

  Key As javax.crypto.SecretKey

  KeyFromBytes (keydata() As Byte)

  KeyToBytes As Byte()

  Version As Double [read only]

Members description:

Format As String [read only]
Returns the format of the key data obtained by KeyToBytes. This will almost certainly be "RAW".
GenerateKey As javax.crypto.SecretKey
Creates and saves internally a SecretKey object appropriate for use with the specified
algorithm using internally provided random data .
Initialize (algorithm As String)
Initialise this KeyGenerator to work with the specified algorithm.
Key As javax.crypto.SecretKey
Gets or sets the SecretKey object.
KeyFromBytes (keydata() As Byte)
Creates and saves internally a SecretKey object appropriate for use with the specified
algorithm using the data in the byte array provided.
KeyToBytes As Byte()
Returns a byte array representing the SecretKey.
Version As Double [read only]
Returns the version number of the library.

KeyPairGenerator

The KeyPairGenerator is used to generate pairs of public and private keys.
A key pair generator for a particular algorithm creates a public/private key pair
that can be used with this algorithm.

Algorithm is commonly be the following, there may be others not listed here. *
RSA The RSA encryption algorithm as defined in PRSA Public-Key Cryptography Standards .

Events:

None

Members:


  Formats() As String [read only]

  GenerateKey

  Initialize (algorithm As String, keysize As Int)

  PrivateKey As java.security.PrivateKey [read only]

  PrivateKeyFromBytes (keydata() As Byte)

  PrivateKeyToBytes As Byte()

  PublicKey As java.security.PublicKey [read only]

  PublicKeyFromBytes (keydata() As Byte)

  PublicKeyToBytes As Byte()

  Version As Double [read only]

Members description:

Formats() As String [read only]
Returns the formats of the key data obtained by xxxKeyToBytes in a String array.
The public key format is at index 0 and will almost certainly be "X.509".
The private key format is at index 1 and will almost certainly be "PKCS#8".
GenerateKey
Generates a key pair appropriate for use with the specified algorithm.
This is a simple holder for a key pair (a public key and a private key).
It does not enforce any security, and, when initialized, should be treated like
a private key.
Initialize (algorithm As String, keysize As Int)
Initialises the KeyPairGenerator with the specified algorithm and keysize.
PrivateKey As java.security.PrivateKey [read only]
Gets the private key of the KeyPairGenerator object.
PrivateKeyFromBytes (keydata() As Byte)
Creates and saves internally a private key appropriate for use with the specified
algorithm using the data in the PKCS#8 format from the byte array provided.
PrivateKeyToBytes As Byte()
Returns a byte array in the PKC#8 format representing the PrivateKey.
PublicKey As java.security.PublicKey [read only]
Gets the public key of the KeyPairGenerator object.
PublicKeyFromBytes (keydata() As Byte)
Creates and saves internally a public key appropriate for use with the specified
algorithm using the data in X.509 format from the byte array provided.
PublicKeyToBytes As Byte()
Returns a byte array in the X.509 format representing the PublicKey.
Version As Double [read only]
Returns the version number of the library.

Mac

Similar to a MessageDigest, a Message Authentication Code (MAC) provides a way to check
the integrity of information transmitted over or stored in an unreliable medium, but includes
a secret key in the calculation. Only someone with the proper key will be able to verify the
received message. Typically, message authentication codes are used between two parties that
share a secret key in order to validate information transmitted between these parties.

A MAC object is initialized for signing with a secret key and is given the data to be signed.
The resulting signature bytes are typically kept with the signed data. When verification is needed,
another MAC object is created and initialized with the same secret key.The data is uploaded and the
signature obtained is compared with the signature provided with the message. The comparison may
be made externally by comparing the signature provided with the data to that returned by Sign or
the MAC object can do the comparison itself by using the Verify method with the provided signature.

Events:

None

Members:


  Initialise (algorithm As String, key As java.security.Key)

  Sign As Byte()

  Update (data() As Byte)

  Verify (signature() As Byte) As Boolean

  Version As Double [read only]

Members description:

Initialise (algorithm As String, key As java.security.Key)
Initialises a Mac object that uses the specified algorithm and the specified secret key.
Once the object is Initialised the data to be signed or verified is provided by one or more
successive calls to Update. When the entire data to be signed or verified has been loaded
Sign or Verify is called.
Sign As Byte()
Sign the uploaded data using the secret key provided on initialisation.
Return the calculated signature data.
Update (data() As Byte)
One or more calls to this method are required after initialisation to load the data to be
signed or verified.
Verify (signature() As Byte) As Boolean
Verify the uploaded data using the public key provided on initialisation and the signature
provided. Return true if the verification is successful.
Version As Double [read only]
Returns the version number of the library.

MessageDigest

Message digests are used to produce unique and reliable identifiers of data.
They are sometimes called "checksums" or the "digital fingerprints" of the data.
Changes to just one bit of the message should produce a different digest value.

Algorithm can be "MD2", "MD5", "SHA-1", "SHA-256", "SHA-384" or "SHA-512".

Events:

None

Members:


  GetMessageDigest (data() As Byte, algorithm As String) As Byte()

  Version As Double [read only]

Members description:

GetMessageDigest (data() As Byte, algorithm As String) As Byte()
Returns a byte array containing the message digest of the contents of the supplied
array if bytes using the specified algorithm.
Algorithm can be "MD5", "SHA-1", "SHA-224", "SHA-256", "SHA-384" or "SHA-512"
Version As Double [read only]
Returns the version number of the library.

SecureRandom

A seed is an array of bytes used to bootstrap random number generation.
To produce cryptographically secure random numbers, both the seed and the algorithm
must be secure. By default, instances of this class will generate an initial seed
using an internal entropy source. This seed is unpredictable and appropriate for secure use.
You may alternatively specify the initial seed explicitly by calling setSeed(byte[]) before
any random numbers have been generated. Specifying a fixed seed will cause the instance to
return a predictable sequence of numbers. This may be useful for testing but it is not
appropriate for secure use.

Although it is common practice to seed Random with the current time, that is dangerous with
SecureRandom since that value is predictable to an attacker and not appropriate for secure use.

Events:

None

Members:


  GetRandomBytes (bytes() As Byte)

  SetRandomSeed (seed As Long)

  Version As Double [read only]

Members description:

GetRandomBytes (bytes() As Byte)
Fills the provided array with cryptographically strong random numbers produced
by the secure random number generator.
SetRandomSeed (seed As Long)
The random number generator seeds itself when created with a random seed. If it is
required, say for testing purposes, to repeatedly reproduce the same sequence of
random numbers then the generator may be seeded with a specific value before use.
Version As Double [read only]
Returns the version number of the library.

Signature

Similar to a MessageDigest, a Signature provides a way to check the integrity of information
transmitted over or stored in an unreliable medium and also ensures that it can be verified
that it originated from the person it purports to originate from. It accomplishes this by using
a private key to encode a hash of the original data and the corresponding public key of the key
pair to decode and check that hash value.

A Signature object is initialized for signing with a private key and is given the data
to be signed. The resulting signature bytes are typically kept with the signed data.
When verification is needed, another Signature object is created and initialized for
verification and given the corresponding public key. The data and the signature bytes
are fed to the signature object, and if the data and signature match, the Signature
object reports success.

Events:

None

Members:


  Initialise (algorithm As String, mode As Int, key As java.security.Key)

  Sign As Byte()

  SIGNATURE_SIGN As Int

  SIGNATURE_VERIFY As Int

  Update (data() As Byte)

  Verify (signature() As Byte) As Boolean

  Version As Double [read only]

Members description:

Initialise (algorithm As String, mode As Int, key As java.security.Key)
Initialises a Signature object that uses the specified algorithm for the specified mode.
Mode must be either SIGNATURE_VERIFY or SIGNATURE_SIGN. Once the object is Initialised
the data to be signed or verified is provided by one or more successive calls to Update.
When the entire data to be signed or verified has been loaded Sign or Verify is called.
Sign As Byte()
Sign the uploaded data using the private key provided on initialisation.
Return the calculated signature data.
SIGNATURE_SIGN As Int
SIGNATURE_VERIFY As Int
Update (data() As Byte)
One or more calls to this method are required after initialisation to load the data to be
signed or verified.
Verify (signature() As Byte) As Boolean
Verify the uploaded data using the public key provided on initialisation and the signature
provided. Return true if the verification is successful.
Version As Double [read only]
Returns the version number of the library.
Top