Class RSAPrivateHWKey

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.security.interfaces.RSAKey, java.security.interfaces.RSAPrivateCrtKey, java.security.interfaces.RSAPrivateKey, java.security.Key, java.security.PrivateKey, javax.security.auth.Destroyable

    public final class RSAPrivateHWKey
    extends com.ibm.security.pkcs8.PrivateKeyInfo
    implements java.security.interfaces.RSAPrivateCrtKey, java.io.Serializable
    A private hardware key for the RSA Algorithm. This key contains a token (which can be either a tokenized representation of a CLEAR key or a label to the stored key) and attributes (KeyHWAttributeValues, which include the key type and key usage).
    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
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected RSAPrivateHWKey​(byte[] encoded)
      Create an RSA hardware private key from a PKCS#8 DER encoded RSA private key.
      protected RSAPrivateHWKey​(byte[] encoded, boolean decodePSS)
      Create an RSA hardware private key from a PKCS#8 DER encoded RSA private key.
        RSAPrivateHWKey​(byte[] keyToken, RSAKeyHWAttributes attribs)
      Deprecated.
      this method should not be used by the public, instead the key should be created through the appropriate key factory or key generator.
    • 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.
      java.math.BigInteger getCrtCoefficient()
      This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatablility.
      byte[] getEncoded()
      Returns a clone of the label if the key is in format PKDS or RETAIN, a clone of the token if the key is in format TOKEN.
      byte[] getExternalKeyToken()
      Returns a clone of the private key external token.
      java.lang.String getFormat()
      Return the format for this key.
      java.lang.String getLabelString()
      Returns the PKDS record label if the key object is a PKDS type of key.
      java.math.BigInteger getModulus()
      This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
      java.security.spec.AlgorithmParameterSpec getParams()  
      java.math.BigInteger getPrimeExponentP()
      This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
      java.math.BigInteger getPrimeExponentQ()
      This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
      java.math.BigInteger getPrimeP()
      This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
      java.math.BigInteger getPrimeQ()
      This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
      java.math.BigInteger getPrivateExponent()
      This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
      java.math.BigInteger getPublicExponent()
      This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
      byte[] getToken()
      Returns a clone of the private key token.
      byte getType()
      Return the key Type.
      byte getUsage()
      Return the key Usage.
      boolean isDestroyed()
      This method is called to determine whether this key object still contains key material.
      protected void parseKeyBits()
      Parses a key encoding in order to create a new private hardware key.
      java.lang.String toString()
      Returns a string that contains the 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
    • Constructor Detail

      • RSAPrivateHWKey

        @Deprecated
        public RSAPrivateHWKey​(byte[] keyToken,
                               RSAKeyHWAttributes attribs)
                        throws java.security.InvalidKeyException
        Deprecated.
        this method should not be used by the public, instead the key should be created through the appropriate key factory or key generator.
        Creates a RSA private hardware key from a keytoken and key attributes.
        Parameters:
        keyToken - IBMCCA hardware token for this key. The label must conform to the character restrictions imposed by the platform you are executing on. In addition, when passed to this method as a byte array, it must be encoded using the "8859_1" code page. For example, if the label is "MyLabel" then the correct form for this parameter is "MyLabel".getBytes("8859_1")
        attribs - indicates the key attributes associated with this key.
        Throws:
        java.security.InvalidKeyException - is thrown if the key could not be DER encoded.
      • RSAPrivateHWKey

        protected RSAPrivateHWKey​(byte[] encoded)
                           throws java.security.InvalidKeyException
        Create an RSA hardware private key from a PKCS#8 DER encoded RSA private key. If the RSAPrivateKeySpec class was used in the generation of the software RSA private key, a value of 65537 is used for public exponent when the RSA hardware private key is created. However, if the user requires control over the value of public exponent, the RSAPrivateCrtKeySpec class should be used in the generation of the software RSA private key.
        Parameters:
        encoded - PKCS#8 DER encoded RSA private key.
        Throws:
        java.security.InvalidKeyException - is thrown if the PKCS#8 private key can not be decoded or if an internal error occurs while converting the PKCS#8 RSA private key to an RSA hardware private key
      • RSAPrivateHWKey

        protected RSAPrivateHWKey​(byte[] encoded,
                                  boolean decodePSS)
                           throws java.security.InvalidKeyException
        Create an RSA hardware private key from a PKCS#8 DER encoded RSA private key.
        Parameters:
        encoded - PKCS#8 DER encoded RSA private key.
        decodePSS - Flag to decode as RSASSA-PSS key
        Throws:
        java.security.InvalidKeyException
    • Method Detail

      • getFormat

        public java.lang.String getFormat()
        Return the format for this key.
        Specified by:
        getFormat in interface java.security.Key
        Overrides:
        getFormat in class com.ibm.security.pkcs8.PrivateKeyInfo
        Returns:
        one of "PKDSLabel", "RETAIN", "ICSFToken"
        Throws:
        java.lang.IllegalStateException - if destroy() has been called in this key object
      • getEncoded

        public byte[] getEncoded()
        Returns a clone of the label if the key is in format PKDS or RETAIN, a clone of the token if the key is in format TOKEN.
        Specified by:
        getEncoded in interface java.security.Key
        Overrides:
        getEncoded in class com.ibm.security.pkcs8.PrivateKeyInfo
        Returns:
        PKDS record label or token. If a PKDS record label the bytes will be encoded in 8859_1 encoding.
        Throws:
        java.lang.IllegalStateException - if destroy() has been called in this key object
      • getToken

        public byte[] getToken()
        Returns a clone of the private key token.
        Returns:
        the value of keyLabel which is a token or a label. If a PKDS record label the bytes will be encoded in 8859_1 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.
        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()
        Returns a clone of the private key external token.
        Returns:
        the value of externalKeyToken.
        Throws:
        java.lang.IllegalStateException - if destroy() has been called in this key object
      • getType

        public byte getType()
        Return the key Type.
        Returns:
        byte the value of key Storage Type either KeyHWAttributeValues.PKDS KeyHWAttributeValues.RETAIN or KeyHWAttributeValues.CLEAR.
        Throws:
        java.lang.IllegalStateException - if destroy() has been called in this key object
      • getUsage

        public byte getUsage()
        Return the key Usage.
        Returns:
        byte the value of key Storage Type either KeyHWAttributeValues.SIGNATURE or KeyHWAttributeValues.KEYMANAGEMENT.
        Throws:
        java.lang.IllegalStateException - if destroy() has been called in this key object
      • getModulus

        public java.math.BigInteger getModulus()
                                        throws java.lang.UnsupportedOperationException
        This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
        Specified by:
        getModulus in interface java.security.interfaces.RSAKey
        Throws:
        java.lang.UnsupportedOperationException - is always thrown if this method is invoked.
      • getPrivateExponent

        public java.math.BigInteger getPrivateExponent()
        This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
        Specified by:
        getPrivateExponent in interface java.security.interfaces.RSAPrivateKey
        Throws:
        java.lang.UnsupportedOperationException - is always thrown if this method is invoked.
      • getPublicExponent

        public java.math.BigInteger getPublicExponent()
        This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
        Specified by:
        getPublicExponent in interface java.security.interfaces.RSAPrivateCrtKey
        Throws:
        java.lang.UnsupportedOperationException - is always thrown if this method is invoked.
      • getPrimeP

        public java.math.BigInteger getPrimeP()
        This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
        Specified by:
        getPrimeP in interface java.security.interfaces.RSAPrivateCrtKey
        Throws:
        java.lang.UnsupportedOperationException - is always thrown if this method is invoked.
      • getPrimeQ

        public java.math.BigInteger getPrimeQ()
        This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
        Specified by:
        getPrimeQ in interface java.security.interfaces.RSAPrivateCrtKey
        Throws:
        java.lang.UnsupportedOperationException - is always thrown if this method is invoked.
      • getPrimeExponentP

        public java.math.BigInteger getPrimeExponentP()
        This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
        Specified by:
        getPrimeExponentP in interface java.security.interfaces.RSAPrivateCrtKey
        Throws:
        java.lang.UnsupportedOperationException - is always thrown if this method is invoked.
      • getPrimeExponentQ

        public java.math.BigInteger getPrimeExponentQ()
        This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
        Specified by:
        getPrimeExponentQ in interface java.security.interfaces.RSAPrivateCrtKey
        Throws:
        java.lang.UnsupportedOperationException - is always thrown if this method is invoked.
      • getCrtCoefficient

        public java.math.BigInteger getCrtCoefficient()
        This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatablility.
        Specified by:
        getCrtCoefficient in interface java.security.interfaces.RSAPrivateCrtKey
        Throws:
        java.lang.UnsupportedOperationException - is always thrown if this method is invoked.
      • toString

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

        public java.security.spec.AlgorithmParameterSpec getParams()
        Specified by:
        getParams in interface java.security.interfaces.RSAKey
      • parseKeyBits

        protected void parseKeyBits()
                             throws java.io.IOException
        Parses a key encoding in order to create a new private hardware key.
        Overrides:
        parseKeyBits in class com.ibm.security.pkcs8.PrivateKeyInfo
        Throws:
        java.io.IOException - if the encoding is of the wrong format.
        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
        java.lang.RuntimeException - 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.