# JsDoc Reference - Ciform.Cipher

Class Index | File Index

## Classes

- _global_
- Ciform
- Ciform.Cipher
- Ciform.ciphers
- Ciform.ciphers.ChainEncoder
- Ciform.ciphers.CiformPacketizer
- Ciform.ciphers.Encoder
- Ciform.ciphers.RSAEncoder
- Ciform.ciphers.RSAPublicKey
- Ciform.ciphers.SHA1Encoder
- Ciform.Field
- Ciform.protocol

# Class Ciform.Cipher

This class provides a simple way to encrypt different kind of elements (text, form fields, URL).
It has first to be built with options to define the encryption ; then one of its method must be called on the element to encrypt.
Defined in: ciform.js.

Class Summary
Constructor Attributes | Constructor Name and Description
--- | ---
| Ciform.Cipher(options)

Field Summary
Field Attributes | Field Name and Description
--- | ---
| encoder The encoder to use on each of the #targets Default : a Ciform.ciphers.RSAEncoder inside a Ciform.ciphers.CiformPacketizer if at least the `pubKey` property is provided in the options

Method Summary
Method Attributes | Method Name and Description
--- | ---
| encryptField(target, options) Encrypts an HTML field.
| encryptFields(fields, options) Tries its best to encrypt all fields in a single atomic operation.
| encryptForm(target, options) Encrypts fields of a form.
| encryptText(text, options) Encrypts a text.
| encryptURL(url, options) Encrypts the parameters in an URL.
| onEncryptionEnd(target, options) This function is called once the encryption of an object has ended.
| onEncryptionStart(target, options) This function is called just before the encryption of an object starts.
| onerror(e, context) A custom error handler that will be called with the error as an argument during encryption operations.

Class Detail
Ciform.Cipher(options)

Parameters:
{Object} options
  (optional) (and next arguments) Overrides the default properties and functions of this object.
  For instance, provide `{'encoder':myencoder,'onerror':function(e,context){dosomething()}}` to use a custom encoder and a custom error handler.

Field Detail
{Ciform.ciphers.Encoder} encoder

The encoder to use on each of the #targets

Default : a Ciform.ciphers.RSAEncoder inside a Ciform.ciphers.CiformPacketizer if at least the `pubKey` property is provided in the options

Method Detail
{boolean|Ciform.Field} encryptField(target, options)
Encrypts an HTML field.

Parameters:
{HTMLElement} target
  The element to encrypt.
  As an alternative, this parameter can be ignored if the element is given in the options.
{Object} options
  (optional) An object with the following properties : As a convenience, this may be the field itself, all default options will then be applied.
  - `<Ciform.Field> field` - Same as (replaces) `target`.
  - `<boolean> commit` - If true, will write ciphertext into the output field.
    If false, will not touch the in and out field, but instead will return the Ciform.Field with the following properties added :
    - `<String> text` - The value of the input field at the end of the operation.
    - `<String> ciphertext` - The value of the output field at the end of the operation.
    Defaults to true.
    This parameter is usefull to handle transactional operations on several fields at once.
  As an alternative,`sha1` or `ciform-sha1` css classes can be set in the `class` attribute of output fields, in order to set the Ciform.Field#sha1 property to 1 or 2 respectively.

Returns:
  false if there was an error, true or a Ciform.Field object if not

encryptFields(fields, options)
Tries its best to encrypt all fields in a single atomic operation.

If an error occurs during the encryption of any field, no field is encrypted.

Parameters:
{Array} fields
  An array of Ciform.Field
{Object} options
  See #encryptField

See:
  #encryptField

{boolean} encryptForm(target, options)
Encrypts fields of a form.

For instance, the following encrypts input fields of type password in a form :

    encryptForm(myForm,{'allowTypes':["password"]})

Parameters:
{HTMLFormElement} target
  The form to encrypt.
  As an alternative, this parameter can be ignored if the target is given in the options.
{Object} options
  (optional) An object with the following properties :
  - `<HTMLFormElement> form` - Same as (replaces) `target` argument.
  - `<Array> allowTypes` - If set, this array lists the only 'type' attributes allowed for an <INPUT> tag to be encrypted. If not set, all tags are allowed.
  - `<Array> rejectTypes` - If set, this array lists the 'type' attributes of the <INPUT> tags not to encrypt. If not set, all tags are allowed.

Returns:
  false if there was an error, true if not

{String} encryptText(text, options)
Encrypts a text.

Parameters:
{String} text
  The message to encode (will also be made 'ciform-encoded' using a Ciform.ciphers.CiformPacketizer).
  As an alternative, this parameter can be ignored if the text is given in the options.
{Object} options
  (optional) An object with the following properties :
  - `<String> text` - The text to encrypt

Returns:
  null if the text could not be encrypted

{String} encryptURL(url, options)
Encrypts the parameters in an URL.

Parameters:
{String} url
  The full URL to encrypt (e.g. `"http://plugnauth.sf.net/ciform/demo.php?password=mysecret"`)
{Object} options
  (optional) An object with the following properties :
  - `<Array<String>> fields` - The list containing the name of the fields that must be encrypted (if not present, all detected fields are encrypted)

Returns:
  The same URL, with the fields encrypted.
  E.g. `"http://plugnauth.sf.net/ciform/demo.php?password=mysecret"` could become `"http://plugnauth.sf.net/ciform/demo.php?password=ciform:rsa:0x2137230230234832423723"`

onEncryptionEnd(target, options)
This function is called once the encryption of an object has ended.

This default implementation does nothing. It should be overridden to match specific needs.

Parameters:
target
  The object that has just been be encrypted
options
  (optional) The parameters of the current context, if any

onEncryptionStart(target, options)
This function is called just before the encryption of an object starts.

This default implementation does nothing. It should be overridden to match specific needs.

Parameters:
target
  The object that's going to be encrypted
options
  (optional) The parameters of the current context, if any

{function} onerror(e, context)
A custom error handler that will be called with the error as an argument during encryption operations.

Default function will log the error and pass it to the upper error handler.

Parameters:
{Error} e
  the error that happened
{Object} context
  any information about the context, in the form of an object with properties

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 06 2012 00:12:49 GMT+0100 (CET)