Cayenne User Documentation
Password Encoding

Cayenne stores the database connection details within the XML model file. This includes the database URI, database name, user name and password. For many people this works perfectly well and is the simplest approach. For others, storing the database as plain text poses a security problem and a more sophisticated approach is needed.

### Modeler

Let's start with configuring the Modeler.

The new fields are:

- Password Encoder The class used to encode and decode passwords. Two standard encoders are included: PlainTextPasswordEncoder and Rot13PasswordEncoder. The plain text encoder is essentially the current Cayenne default – passwords are stored in plain text. The ROT-13 encoder does a simple Caesar cipher of the password, which is easily unscrambled, but provides a slight degree of obfuscation. This field is user-editable and a different/custom class can be entered.

- Password Salt A user-entered text string which can be used to salt the encoder. Not all encoders make use of this value: for example the plain text and ROT-13 encoders do not.

- Password Location A pulldown list for where to obtain the password. The default is from inside the Cayenne model (the normal Cayenne method). Other options include Classpath (searches the Java CLASSPATH for it), Executable Program (run a command to obtain the password), and URL (file: or http: based URLs are common choices).

- Password Source This field is ignored if the Password Location is Model. If the Password Location is Classpath, Executable Program, or URL, then it is used to specify the filename to find in the CLASSPATH, the program to run (with all parameters), or the URL.

### API

If you want to implement your own password encoder, you will need to implement the `PasswordEncoding` interface:

PasswordEncoding.java

    public interface PasswordEncoding
    {
      final String[] standardEncoders =
        new String[] { PlainTextPasswordEncoder.class.getName(),
                       Rot13PasswordEncoder.class.getName() };

      /**
       * Decodes an encoded database password.
       *
       * @param encodedPassword - The encoded password to be decoded
       * @param salt - An optional data element which can be used to salt the algorithm.
       * @return The decoded normal/plain plassword.
       */
      public String decodePassword(String encodedPassword, String salt);

      /**
       * Encodes a normal/plain database password.
       *
       * @param normalPassword - The normal/plain password to be encoded
       * @param salt - An optional data element which can be used to salt the algorithm.
       * @return The encoded password.
       */
      public String encodePassword(String normalPassword, String salt);
    }

When loading the model, the retrieved password is passed through the `decodePassword(encodedPassword, salt)` method to obtain the actual password. When saving the model, if the Password Location is in the Cayenne Model or Java Classpath, then the `encodePassword(normalPassword, salt)` method is called and the returned value is saved.

The standard encoders, such as the plain text encoder, are trival:

PlainTextPasswordEncoder.java

    package org.objectstyle.cayenne.conf;

    public class PlainTextPasswordEncoder implements PasswordEncoding
    {
      public String decodePassword(String encodedPassword, String salt)
      {
        return encodedPassword;
      }

      public String encodePassword(String normalPassword, String salt)
      {
        return normalPassword;
      }
    }

If your organization requires something more advanced, say to use real encryption or to fetch the password from a web service or LDAP source, then you can write an encoder to handle it and plug it into Cayenne (make sure to add the JAR with your custom encoder to the Modeler's Classpath Preferences settings and to the Java Classpath at runtime).

| Useful Information The encoding is only applied to the database password on the Cayenne side. The data stream between the application and database is unaffected, so the password could (and usually will) be transmitted in-the-clear over the network to the database.

.
Copyright ©2001-2010 Apache Software Foundation