====== $password: ======

<hi #ffd700>~~SP~~~~SP~~</hi> The $password: function shortcut lets you use a password credential without embedding the password directly in your Ant script or loading it into easily leaked Ant properties. Whether the referred to password is clear text or cipher text is application dependent. This funcut works by reading passwords stored in a external source, typically an appropriately protected password file. The $password: funcut is a //query only// feature-- you cannot use it to modify existing data.

By default the password funcut handler looks for the password source in the following places (in order). If it cannot find a match for any of these sources, the funcut handler returns //null// (which Ant interprets as an unresolved property). Currently AntXtras only supports a single passwords source for any given execution cycle. 
  - It looks for a “passwordfile” artifact URL by checking for a $artifact: function shortcut.
  - It looks for memory-based properties-like object under the “run.passwords” id. [USE FOR DEBUG]
  - It looks for a //file name// under the “jware.antxtras.defaults.passwordfile” property.
  - It looks for a file “run.passwords” under directory ''${user.home}/.ant/.private''.
  - It looks for a fallback password //value// under the “jware.antxtras.defaults.password” property.

<note warning>
If you use a source password file, you still need to secure it using whatever access control mechanisms your filesystem provides. The running Ant process requires only read access to the file.
</note>

Although this funcut is called the “$password:” shortcut, you can also use it to load the user id or user name part of a basic auth credential as well. For instance, you could use fixed marker ids in your scripts, but load both real user name //and// password from an external file at runtime.

The $password: funcut is automatically installed and enabled by the standard AntXtras funcuts antlib. You can also explicitly install this funcut’s handler; read the [[#Examples]] section to see how this is done.

===== Parameters =====

The general form of the function shortcut is: //$password:key// where //key// is the key name for the password to be loaded. Note that we keep saying the password will be //loaded// (as opposed to will be //selected//). Unless you’re using a memory-based properties object (not a good idea outside of testing unless values are cipher text), AntXtras will load the password source every time and purge it once done using the data. 


===== Examples =====

== Installing $password: shortcut ==
The following snippet explicitly declares the password function shortcut and links it to the ‘$password:’ scheme. If you choose to activate shortcuts manually, you’ll need to do something like this at the start of your Ant script’s execution.
<code xml 1>
<oja:managefuncuts action="enable">
  <parameter name="password"
    value="${ojaf}.info.PasswordFunctionShortcut"/>
</oja:managefuncuts>
</code>

== Reading a password ==
The following snippet is an updated form of one of the standard Ant <sql> task examples. This example shows how you would use $password: instead of embedding the ''sa'' password directly into your Ant script. Note that the script also verifies that the password file location has been initialized earlier (typically done in an ‘initialize’ target of some kind).
<code xml 1>
<fixturecheck isset="${$defaultsproperty:passwordfile}"
  message="The default password file property setup properly"/>
…
<sql
    driver="org.database.jdbcDriver";
    url="jdbc:database-url"
    userid="sa"
    password="${$password:dbsa}"
    src="${data.sql}"
/>
</code>

== Using debug-only passwords ==
The following snippet shows an example of how you can setup a local <properties> object to hold dummy or local-only credentials during script development. The memory-based development passwords are defined iff the ''.official'' property does not exist and the ''dryrun.enabled'' flag is set to a positive boolean value like “true”.
<code xml 1>
<do unless=".official" ifTrue="dryrun.enabled">
  <datadef name="run.passwords" setid="yes">
    <properties>
      <property name="uploader" value="unsecure12"/>
      <property name="deployer" value="seekrit007"/>
    </properties>
  </datadef>
</do>
…
<signjar jar="${out.d}/lib/mylib.jar"
   alias="mygroup" storepass="${$password:uploader}"/>
…
<targz tarfile="${pkg.d}/mypkg.tgz" basedir="${out.d}"/>
…
<scp file="${pkg.d}/mypkg.tgz" 
   todir="deployer@somehost:/home/deployer/packages" 
   password="${$password:deployer}"/>
</code>


===== Related Topics =====
  * The //latest// [[/apis/antxtras/latest/org/jwaresoftware/antxtras/funcuts/info/PasswordFunctionShortcut.html|PasswordFunctionShortcut]] javadocs with more examples.
  * The [[fc_isdefined|$isdefined:]] funcut lets you check a password to see if it’s empty.

~~UP~~