Package com.isode.dsapi

Class Identity

java.lang.Object
com.isode.dsapi.Identity
public class Identity extends Object
Identity is a class which wraps the DS_Identity structure.

The DSAPI interface can create a DS_Identity from a PKCS#12 file, although it retains no information about that file once the DS_Identity has been initialized. This class does keep track of the PKCS#12 file that was used in such cases, and it can be queried using getPKCS12Filename(). This also makes it easier to implement the "copy-constructor" which can create a new PKCS#12 file with a new passphrase. See Identity(Identity, String, String).

Since:
16.1 (internal 14.4)

  • Field Details

    • isodeIdentityDirectory

      public static final String isodeIdentityDirectory
      Isode specific directory for storing identities
      Since:
      16.1 (internal 14.6 in BPLiterals.java)

    • isodeIdentityDirectoryFile

      public static final File isodeIdentityDirectoryFile
      A File object which corresponds to isodeIdentityDirectory
      Since:
      16.1 (internal 16.0 in BPLiterals.java)

  • Constructor Details

    • Identity

      public Identity(String pkcs12File, String pkcs12Passphrase, String authz) throws NativeLibraryException, OperationFailedException, IOException
      Create a new Identity object, which may subsequently be used for strong binds.

      Note that the X509 library must have been initialized before using this method, using, for example DSapi.initializeSecurity(String). If this has not been done, then this method will throw OperationFailedException

      Parameters:
      pkcs12File - the name of a PKCS#12 file. May not be null.
      pkcs12Passphrase - the passphrase for pkcs12File. May not be null. If this passphrase is incorrect, then OperationFailedException will be thrown.
      authz - A String to be used for SASL authorization. This may be null.
      Throws:
      OperationFailedException - if the underlying library was unable to create an identity from the specified information. This will be thrown if the X509 library has not been initialized, or if pkcs12Passphrase is not valid.
      IOException - if pkcs12File does not exist or is not readable
      NativeLibraryException - if an unrecoverable error was detected by the native library
      See Also:

    • Identity

      public Identity(Identity otherIdentity)
      Create a new Identity object which is a copy of an existing one.
      Parameters:
      otherIdentity - existing Identity, which must not be null
      See Also:

    • Identity

      public Identity(Identity otherIdentity, String oldPassphrase, String newPassphrase) throws IOException, OperationFailedException
      Make a copy of an Identity, but associate it with a newly created PKCS#12 file. This file will be created in the Isode specific Identities directory and will have a random name derived from UUID.

      If this operation fails, an exception will be thrown and no new file will be created.

      Parameters:
      otherIdentity - the existing Identity. May not be null.
      oldPassphrase - the passphrase for this Identity's pkcs12File. May not be null. If this passphrase is not correct, then OperationFailedException will be thrown.
      newPassphrase - the passphrase to be used to encrypt the new file. This may be null, in which case the new file will be encrypted using oldPassphrase.
      Throws:
      IOException - if newFilename is the same file as the one associated with this Identity, or if an error occurs when trying to create newFilename
      OperationFailedException - if oldPassphrase is incorrect, or an error occurs when encrypting newFilename.
      Since:
      16.1 (internal 14.6)
      See Also:

  • Method Details

    • finalize

      protected void finalize() throws Throwable
      Releases any native structures associated with this object.
      Overrides:
      finalize in class Object
      Throws:
      Throwable

    • toString

      public String toString()
      Returns a String representation of this Identity.
      Overrides:
      toString in class Object
      Returns:
      a String representation of this Identity

    • getPKCS12Filename

      public String getPKCS12Filename()
      Return the name of the PKCS12 file which was used to create this identity.
      Returns:
      the pkcs12 filename

    • getTrustedCertificates

      public List<byte[]> getTrustedCertificates()
      Get the "trusted" certificates for this identity. This method returns the values that are stored in the PKCS#12 file.
      Returns:
      a List of arrays of bytes, each one containing the BER representation of a certificate in the "trusted" certificates for this Identity. If none are present, the method returns null.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • getOtherCertificates

      public List<byte[]> getOtherCertificates()
      Get the "other" certificates for this identity. This method returns the values that are stored in the PKCS#12 file.
      Returns:
      a List of arrays of bytes, each one containing the BER representation of a certificate in the "other", untrusted certificates for this Identity. If none are present, the method returns null.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • getUserCertificate

      public byte[] getUserCertificate() throws NativeLibraryException, OperationFailedException
      Return the user certificate from this Identity. This returns whatever value is stored in the PKCS#12 file.
      Returns:
      a byte array containing the BER representation of the user certificate
      Throws:
      OperationFailedException - if it was not possible to retrieve the encoded form of the user certificate.
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • hashCode

      public int hashCode()
      Simplified hashCode aggregate. It uses only canonical file name of the PKCS#12 certificate and used authz string rather than all internals.
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Simplified comparison method. Rather than in-depth comparison of all internal values it compares only canonical file name of the PKCS#12 certificate and used authz.
      Overrides:
      equals in class Object