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

Class ECPrivateHWKey

java.lang.Object
com.ibm.security.pkcsutil.PKCSDerObject
com.ibm.security.pkcs8.PrivateKeyInfo
com.ibm.crypto.hdwrCCA.provider.ECPrivateHWKey
All Implemented Interfaces:
Serializable, Cloneable, ECKey, ECPrivateKey, Key, PrivateKey, Destroyable
public final class ECPrivateHWKey extends com.ibm.security.pkcs8.PrivateKeyInfo implements ECPrivateKey, ECKey, 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:

  • 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

    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.
    String
    getFormat()
    Returns either 'ICSFToken' for a CLEAR type key or 'PKDSLabel' for a PKDS type key.
    String
    getLabelString()
    Returns the PKDS record label if the key object is a PKDS type of key.
    ECParameterSpec
    getParams()
    Return the Elliptic Curve domain parameters.
    BigInteger
    getS()
    This method is not supported for hardware based private keys.
    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.
    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 Details

    • parseKeyBits

      protected void parseKeyBits() throws 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:
      IOException - if unable to construct Elliptic Curve domain parameters
      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:
      IllegalStateException - If destroy() has been called in this key object

    • getLabelString

      public String getLabelString() throws 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:
      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:
      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:
      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:
      IllegalStateException - if destroy() has been called in this key object

    • getS

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

    • getParams

      public ECParameterSpec getParams()
      Return the Elliptic Curve domain parameters.
      Specified by:
      getParams in interface ECKey
      Returns:
      Elliptic Curve domain parameters
      Throws:
      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 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:
      IllegalStateException - if destroy() has been called in this key object

    • getFormat

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

    • getSoftwareECPrivateKey

      public ECPrivateKey getSoftwareECPrivateKey() throws 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:
      InvalidKeyException - if this is a PKDS hardware key or if unable to create the equivalent JCE provider software private key
      IllegalStateException - if destroy() has been called in this key object

    • toString

      public 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:
      IllegalStateException - if destroy() has been called in this key object

    • deletePKDSEntry

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

    • destroy

      public void destroy() throws 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 Destroyable
      Throws:
      DestroyFailedException

    • isDestroyed

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