Module ibm.crypto.hdwrcca
Package com.ibm.crypto.hdwrCCA.provider

Class ECPrivateHWKey

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.security.interfaces.ECKey, java.security.interfaces.ECPrivateKey, java.security.Key, java.security.PrivateKey, javax.security.auth.Destroyable
    public final class ECPrivateHWKey
extends com.ibm.security.pkcs8.PrivateKeyInfo
implements java.security.interfaces.ECPrivateKey, java.security.interfaces.ECKey, java.io.Serializable
    This class represents an Elliptic Curve private key. This private key can be either CLEAR or PKDS. A CLEAR private key contains an external PKA private key token along with an imported internal private key token. A PKDS private key contains only a label to the PKDS record entry, and does not have an external PKA private key token.

    For more information on different Elliptic Curve key token formats, refer to Appendix B of the "z/OS Cryptographic Services ICSF Application Programmer's Guide, SA22-7522".

    See Also:
    Serialized Form

    • Field Summary

      • Fields inherited from class com.ibm.security.pkcs8.PrivateKeyInfo

        algid, attributes, encodedKeyNoOptional, key, version

      • Fields inherited from class com.ibm.security.pkcsutil.PKCSDerObject

        provider

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void deletePKDSEntry()
      This method is used to delete the PKDS information that is associated with this key object.
      void destroy()
      Destroy or clear sensitive information contained in this private key.
      byte[] getEncoded()
      Returns a clone of either the external PKA key token of a CLEAR key or the PKDS record label of a PKDS key.
      byte[] getExternalKeyToken()
      Return a clone of the external private key token.
      java.lang.String getFormat()
      Returns either 'ICSFToken' for a CLEAR type key or 'PKDSLabel' for a PKDS type key.
      java.lang.String getLabelString()
      Returns the PKDS record label if the key object is a PKDS type of key.
      java.security.spec.ECParameterSpec getParams()
      Return the Elliptic Curve domain parameters.
      java.math.BigInteger getS()
      This method is not supported for hardware based private keys.
      java.security.interfaces.ECPrivateKey getSoftwareECPrivateKey()
      The preferred method for retrieving an equivalent software Elliptic Curve private key from a CLEAR hardware Elliptic Curve private key is to use the KeyFactory class.
      byte[] getToken()
      Return a clone of either the internal private key token or the PKDS record label.
      byte getType()
      Return whether this is a CLEAR or PKDS private key.
      byte getUsage()
      Return whether this key is used for key management or signature services.
      boolean isDestroyed()
      This method is called to determine whether this key object still contains key material.
      protected void parseKeyBits()
      Construct a set of Elliptic Curve domain parameters from the algorithm ID.
      java.lang.String toString()
      Returns the private key in human readable format.

      • Methods inherited from class com.ibm.security.pkcs8.PrivateKeyInfo

        addAttribute, addAttributes, clone, decode, encode, equals, finalize, getAlgorithm, getAlgorithmId, getAttribute, getAttributes, getEncodedKeyNoOptionalAttributes, getKeyBytes, hasAttribute, hasAttributes, hashCode, parseKey, parseKey

      • Methods inherited from class com.ibm.security.pkcsutil.PKCSDerObject

        decode, encode, getObjectIdentifier, read, readBASE64, write, write, writeBASE64

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.security.Key

        getAlgorithm

    • Method Detail

      • parseKeyBits

        protected void parseKeyBits()
                     throws java.io.IOException
        Construct a set of Elliptic Curve domain parameters from the algorithm ID. This method is called by the parent class PrivateKeyInfo. The 'key' instance variable is a byte array containing the DER-encoded key. Contrary to the method name, this method will not do key parsing, this will be done by the constructor.
        Overrides:
        parseKeyBits in class com.ibm.security.pkcs8.PrivateKeyInfo
        Throws:
        java.io.IOException - if unable to construct Elliptic Curve domain parameters
        java.lang.IllegalStateException - if destroy() has been called in this key object

      • getToken

        public byte[] getToken()
        Return a clone of either the internal private key token or the PKDS record label. If a PKDS record label, it will be in ISO_8859_1 character set encoding. Please note that this method is deprecated for use of obtaining a PKDSLabel, it is recommended that the caller make use of the method getLabelString() instead to fetch PKDSLabels.

        Note that this method returns a clone of sensitive information. It is the caller's responsibility to zero out the information after it is no longer needed.

        Returns:
        A clone of the internal private key token or PKDS record label
        Throws:
        java.lang.IllegalStateException - If destroy() has been called in this key object

      • getLabelString

        public java.lang.String getLabelString()
                                throws java.security.InvalidKeyException
        Returns the PKDS record label if the key object is a PKDS type of key.
        Returns:
        The PKDS label. This value will be exactly what is used within the CCA key repository as a label, including trailing blanks.
        Throws:
        java.security.InvalidKeyException - If the key is not a PKDS type of key.

      • getExternalKeyToken

        public byte[] getExternalKeyToken()
        Return a clone of the external private key token.

        Note that this method returns a clone of sensitive information. It is the caller's responsibility to zero out the information after it is no longer needed.

        Returns:
        A clone of the external private key token of a CLEAR private key, or null if a PKDS private key
        Throws:
        java.lang.IllegalStateException - If destroy() has been called in this key object

      • getType

        public byte getType()
        Return whether this is a CLEAR or PKDS private key.
        Returns:
        whether this is a CLEAR or PKDS private key
        Throws:
        java.lang.IllegalStateException - if destroy() has been called in this key object

      • getUsage

        public byte getUsage()
        Return whether this key is used for key management or signature services.
        Returns:
        whether this key is used for key management or signature services
        Throws:
        java.lang.IllegalStateException - if destroy() has been called in this key object

      • getS

        public java.math.BigInteger getS()
        This method is not supported for hardware based private keys.
        Specified by:
        getS in interface java.security.interfaces.ECPrivateKey
        Throws:
        java.lang.UnsupportedOperationException - is always thrown

      • getParams

        public java.security.spec.ECParameterSpec getParams()
        Return the Elliptic Curve domain parameters.
        Specified by:
        getParams in interface java.security.interfaces.ECKey
        Returns:
        Elliptic Curve domain parameters
        Throws:
        java.lang.IllegalStateException - if destroy() has been called in this key object

      • getEncoded

        public byte[] getEncoded()
        Returns a clone of either the external PKA key token of a CLEAR key or the PKDS record label of a PKDS key.

        Note that this method returns a clone of sensitive information. It is the caller's responsibility to zero out the information after it is no longer needed.

        Specified by:
        getEncoded in interface java.security.Key
        Overrides:
        getEncoded in class com.ibm.security.pkcs8.PrivateKeyInfo
        Returns:
        either the external PKA key token of a CLEAR key or the PKDS record label of a PKDS key. If a PKDS record label is returned the bytes will be encoded in the 8859_1 encoding.
        Throws:
        java.lang.IllegalStateException - if destroy() has been called in this key object

      • getFormat

        public java.lang.String getFormat()
        Returns either 'ICSFToken' for a CLEAR type key or 'PKDSLabel' for a PKDS type key.
        Specified by:
        getFormat in interface java.security.Key
        Overrides:
        getFormat in class com.ibm.security.pkcs8.PrivateKeyInfo
        Returns:
        either 'ICSFToken' or 'PKDSLabel' keywords
        Throws:
        java.lang.IllegalStateException - if destroy() has been called in this key object

      • getSoftwareECPrivateKey

        public java.security.interfaces.ECPrivateKey getSoftwareECPrivateKey()
                                                              throws java.security.InvalidKeyException
        The preferred method for retrieving an equivalent software Elliptic Curve private key from a CLEAR hardware Elliptic Curve private key is to use the KeyFactory class.

        Use the JCECCA KeyFactory.getKeySpec(Key key, Class keySpec) method to retrieve ECPrivateKeySpec from a CLEAR hardware Elliptic Curve private key. The ECPrivateKeySpec object can then be used as a parameter to any software provider's KeyFactory.generatePrivate(KeySpec keySpec) method in order to retrieve the equivalent software private key for that provider.

        This method creates and returns the equivalent JCE provider software Elliptic Curve private key. This functionality is only available to CLEAR hardware Elliptic Curve keys.

        Please note that in order for the returned JCE provider software key to function normally, such as returning the correct encoded private key value, the JCE provider must support the Elliptic Curve being used by this key.

        If the JCE provider does not support the Elliptic Curve used by this key, then the returned JCE software key will encode the associated domain parameters piece by piece, rather than encoding just the OID of the Elliptic Curve used by this key. As a result, the encoded value may not be recognized by other services.

        Returns:
        the equivalent JCE provider software Elliptic Curve private key
        Throws:
        java.security.InvalidKeyException - if this is a PKDS hardware key or if unable to create the equivalent JCE provider software private key
        java.lang.IllegalStateException - if destroy() has been called in this key object

      • toString

        public java.lang.String toString()
        Returns the private key in human readable format.
        Overrides:
        toString in class com.ibm.security.pkcs8.PrivateKeyInfo
        Returns:
        a string that represents the private key
        Throws:
        java.lang.IllegalStateException - if destroy() has been called in this key object

      • deletePKDSEntry

        public void deletePKDSEntry()
                     throws java.security.InvalidKeyException
        This method is used to delete the PKDS information that is associated with this key object.
        Throws:
        java.security.InvalidKeyException - Key object is not PKDS type.
        java.lang.RuntimeException - PKDS label length is incorrect or if the ICSF operation is not successful
        java.lang.IllegalStateException - if destroy() has been called in this key object

      • destroy

        public void destroy()
             throws javax.security.auth.DestroyFailedException
        Destroy or clear sensitive information contained in this private key. This method is required because the class implements ECPrivateKey, which implements Destroyable. This method destroys data stored in this java object. It does not delete key material from the PKDS.
        Specified by:
        destroy in interface javax.security.auth.Destroyable
        Throws:
        javax.security.auth.DestroyFailedException

      • isDestroyed

        public boolean isDestroyed()
        This method is called to determine whether this key object still contains key material.
        Specified by:
        isDestroyed in interface javax.security.auth.Destroyable
        Returns:
        true if destroy() has been called, otherwise false.