.. highlight:: xml
.. index:: Encrypting Properties

.. _encrypting_props:

Encrypting Properties/Variables
===============================

You can encrypt DataPower passwords or any other property used by DPBuddy or by Apache Ant. DPBuddy provides commands/tasks for encrypting and decrypting arbitrary values. These commands utilize  open-source `Jascrypt <http://www.jasypt.org/>`_ library.

Encrypted values have the format of "ENC{encrypted value}". When DPBuddy encounters this format in the "conf" file, it attempts to decrypt it automatically (unless ``autoDecrypt`` property is set to ``false``). For Ant properties (defined in a property file or using the ``property`` task), you must use ``decrypt`` task documented below.

DataPower passwords (``dp.password`` property) are always decrypted automatically.

The key (a.k.a "master password") used for encryption/decryption must be provided externally. It can be specified as an environment variable or as a JVM system property.

To obtain master password, DPBuddy first checks the environment variable ``DP_MASTER_PASSWORD``. If it's not defined, it checks ``dp.master.password`` JVM system property. If the property is not defined and the value is encrypted, DPBuddy will raise an error.

You can set JVM system property using DBPUDD_OPTS or ANT_OPTS environment variable. E.g.:

.. code-block:: bat

  export ANT_OPTS="-Xms256m -Xmx1648m -Ddp.master.password=master_secret"

.. _encrypt_task:

``encrypt``
-----------

Encrypts the provided value using the available master password and prints the encrypted value to standard out. The printed output can then be manually copied and saved in a "conf" file or in a properties file.

Attributes/Options
^^^^^^^^^^^^^^^^^^
.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - value
     - Value to encrypt.
     - Yes
   * - passwd
     - Encryption key/password. If not provided, the command will use the value from ``DP_MASTER_PASSWORD`` environment variable or  ``dp.master.password`` system property. If both are missing, an error will be raised.
     - No

Examples
^^^^^^^^
.. code-block:: bat

  dpbuddy encrypt -value secret -passwd master_password


``decrypt``
-----------

Decrypts the provided value using the available master password and saves the decrypted value in the property specified by the ``property`` attribute. If used from the command line, prints the decrypted value to standard out.

Attributes/Options
^^^^^^^^^^^^^^^^^^
.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - encrypted
     - Encrypted value to decrypt. Must be in the format "ENC{encrypted value}".
     - Yes
   * - passwd
     - Decryption key/password. If not provided, the command will use the value from ``DP_MASTER_PASSWORD`` environment variable or  ``dp.master.password`` system property. If both are missing, an error will be raised.
     - No
   * - property
     - Name of Ant property to populate with the decrypted value
     - No

Examples
^^^^^^^^
.. code-block:: xml

  <property name="encr.prop" value="ENC{r5MmGcyzV01h1ErKUx6/uA==}" />
  <dp:decrypt property="decrypted" encrypted="${encr.prop}" />