Entity.java

/*
 *  Copyright (c) 2014, Facebook, Inc.
 *  All rights reserved.
 *
 *  This source code is licensed under the BSD-style license found in the
 *  LICENSE file in the root directory of this source tree. An additional grant
 *  of patent rights can be found in the PATENTS file in the same directory.
 *
 */

package com.facebook.crypto;

import java.io.UnsupportedEncodingException;
import java.nio.charset.Charset;

/**
 * Use this object to keep track of the data you are encrypting/decrypting. Every piece of data
 * being encrypted should have a unique entity identifying what that data is.
 *
 * This is used for an authenticity check i.e. to ensure that when you read from the input stream,
 * you are actually reading the data you expect to be reading. If the entity differs between the
 * output and input streams, decryption will fail.
 *
 * Use {@link #create(String)}
 */
public class Entity {

  private static final Charset UTF_16 = Charset.forName("UTF-16");
  private static final Charset UTF_8 = Charset.forName("UTF-8");

  private byte[] mBytes;

  /**
   * Creates an Entity object.
   *
   * @param name The name of the 'entity' you expect to be performing operations on.
   * @deprecated This uses UTF-16 to get the identifying bytes, which is discouraged.
   *             If you need to create an compatible Entity with 1.0.x use Entity.utf16(String)
   *             If you are encrypting a new entity use Entity.for(String)
   */
  @Deprecated
  public Entity(String name) {
    this.mBytes = name.getBytes(UTF_16);
  }

  private Entity(byte[] bytes) {
    this.mBytes = bytes;
  }

  public byte[] getBytes() {
    return mBytes;
  }

  /**
   * Use this factory method (instead of new Entity(String)) only to create Entities that need to
   * be compatible with Conceal 1.0.x, it is, when you need to decrypt content generated by 1.0.x.
   * For new Entities use {@link #create(String)}
   * @param name The name of the 'entity' you expect to be performing operations on.
   */
  @Deprecated
  public static Entity utf16(String name) {
    return new Entity(name);
  }

  public static Entity create(String name) {
    return new Entity(name.getBytes(UTF_8));
  }
}