Package com.isode.dsapi

Class Identity

  • public class Identity
extends java.lang.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)

    • Constructor Summary

      Constructors 
      Constructor Description
      Identity​(Identity otherIdentity)
      Create a new Identity object which is a copy of an existing one.
      Identity​(Identity otherIdentity, java.lang.String oldPassphrase, java.lang.String newPassphrase)
      Make a copy of an Identity, but associate it with a newly created PKCS#12 file.
      Identity​(java.lang.String pkcs12File, java.lang.String pkcs12Passphrase, java.lang.String authz)
      Create a new Identity object, which may subsequently be used for strong binds.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean equals​(java.lang.Object obj)
      Simplified comparison method.
      protected void finalize()
      Releases any native structures associated with this object.
      java.util.List<byte[]> getOtherCertificates()
      Get the "other" certificates for this identity.
      java.lang.String getPKCS12Filename()
      Return the name of the PKCS12 file which was used to create this identity.
      java.util.List<byte[]> getTrustedCertificates()
      Get the "trusted" certificates for this identity.
      byte[] getUserCertificate()
      Return the user certificate from this Identity.
      int hashCode()
      Simplified hashCode aggregate.
      java.lang.String toString()
      Returns a String representation of this Identity.

      • Methods inherited from class java.lang.Object

        clone, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • isodeIdentityDirectory

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

      • isodeIdentityDirectoryFile

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

    • Constructor Detail

      • Identity

        public Identity​(java.lang.String pkcs12File,
                java.lang.String pkcs12Passphrase,
                java.lang.String authz)
         throws NativeLibraryException,
                OperationFailedException,
                java.io.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.
        java.io.IOException - if pkcs12File does not exist or is not readable
        NativeLibraryException - if an unrecoverable error was detected by the native library
        See Also:
        DSapi.initializeSecurity(String)

      • 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(Identity, String, String)

      • Identity

        public Identity​(Identity otherIdentity,
                java.lang.String oldPassphrase,
                java.lang.String newPassphrase)
         throws java.io.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:
        java.io.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:
        Identity(Identity)

    • Method Detail

      • finalize

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

      • toString

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

      • getPKCS12Filename

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

      • getTrustedCertificates

        public java.util.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 java.util.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 java.lang.Object

      • equals

        public boolean equals​(java.lang.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 java.lang.Object