Cryptor Object

Description

The Cryptor object provides access to a number of symmetric encryption algorithms. Symmetric encryption algorithms come in two "flavors" - block ciphers, and stream ciphers. Block ciphers process data (while both encrypting and decrypting) in discrete chunks of data called blocks; stream ciphers operate on arbitrary sized data.

The Cryptor object provides access to both block ciphers and stream ciphers with the same API; however some options are available for block ciphers that do not apply to stream ciphers. The Android version of this module only exposes block ciphers.

The general operation of a Cryptor is:

  1. Initialize it with raw key data and other optional fields with crypto.createCryptor()
  2. Process input data via one or more calls to cryptor.update()
  3. Obtain possible remaining output data with cryptor.final()
  4. The cryptor object is disposed of by setting the cryptor variable to null. The cryptor object can be reused (with the same key data as provided to crypto.createCryptor()) by calling cryptor.reset() or cryptor.release().

Alternatively, cryptor.encrypt() and cryptor.decrypt() methods are provided for a stateless, one-shot encrypt or decrypt operation.

Methods

createCryptor

Creates a crypto.cryptor object for use in encrypting or decrypting data.

Arguments

Takes one argument, a dictionary with keys:

Properties

Example

<pre> var cryptor = crypto.createCryptor({ algorithm: crypto.ALGORITHMAES128, options: crypto.OPTIONPKCS7PADDING, key: key, initializationVector: initializationVector }); </pre>

encrypt

Stateless, one-shot encryption operation.

Arguments

Return Value

Returns the number of bytes encrypted into the dataOut buffer. If an error occurred, then the return value will be less than zero and will be one of the following values:

Example

<pre> // Encrypt the entire buffer var numBytes = cryptor.encrypt(bufferIn, -1, bufferOut, -1); -or- // Encrypt in-place var numBytes = cryptor.encrypt(bufferIn); </pre>

decrypt

Stateless, one-shot decryption operation.

Arguments

Return Value

Returns the number of bytes decrypted into the dataOut buffer. If an error occurred, then the return value will be less than zero and will be one of the following values:

Example

<pre> // Decrypt the entire buffer var numBytes = cryptor.decrypt(bufferIn, -1, bufferOut, -1); -or- // Decrypt in-place var numBytes = cryptor.decrypt(bufferIn); </pre>

getOutputLength

getOutputLength is used to determine the output buffer size required to process a given input size.

Arguments

Return Value

Returns the number of bytes required for the output buffer

Example

<pre> var numBytesNeeded = cryptor.getOutputLength(bufferIn.length, false); </pre>

update

update is used to encrypt or decrypt data. This method can be called multiple times. The caller does not need to align input data lengths to block sizes; input is buffered as necessary for block ciphers.

Arguments

Return Value

Returns the number of bytes moved into the dataOut buffer. If an error occurred, then the return value will be less than zero and will be one of the following values:

Example

<pre> // Encrypt the entire buffer into a buffer of fixed size var numBytes = cryptor.update(buffer, -1, fixedBuffer); </pre>

finish

Finishes encryption and decryption operations and obtains the final data output.

Arguments

Return Value

Returns the number of bytes moved into the dataOut buffer. If an error occurred, then the return value will be less than zero and will be one of the following values:

Example

<pre> var numBytes = cryptor.final(fixedBuffer) </pre>

reset

reset reinitializes an existing cryptor object with a (possibly) new initialization vector.

Arguments

Return Value

Example

<pre> cryptor.reset(initializationVector); </pre>

release

release will dispose of the internal cryptor data

Return Value

Example

<pre> cryptor.release(); </pre>

License

Copyright(c) 2010-2013 by Appcelerator, Inc. All Rights Reserved. Please see the LICENSE file included in the distribution for further details.