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

Class RSAPrivateHWKey

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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final PSSParameterSpec
    DEFAULT
    The PSS parameter set with all default values
    static final int
    TRAILER_FIELD_BC
    The TrailerFieldBC constant as defined in PKCS#1

    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)
     
    protected
    RSAPrivateHWKey(byte[] keyToken, RSAKeyHWAttributes attribs)
    Creates a RSA private hardware key from a keytoken and key attributes.

  • 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.
    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.
    String
    getFormat()
    Return the format for this key.
    String
    getLabelString()
    Returns the PKDS record label if the key object is a PKDS type of key.
    BigInteger
    getModulus()
    This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
    AlgorithmParameterSpec
    getParams()
     
    BigInteger
    getPrimeExponentP()
    This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
    BigInteger
    getPrimeExponentQ()
    This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
    BigInteger
    getPrimeP()
    This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
    BigInteger
    getPrimeQ()
    This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
    BigInteger
    getPrivateExponent()
    This function is not valid for hardware private keys, it throws a UnsupportedOperationException exception and only exists for compatability.
    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.
    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

  • Field Details

    • TRAILER_FIELD_BC

      public static final int TRAILER_FIELD_BC
      The TrailerFieldBC constant as defined in PKCS#1
      Since:
      11
      See Also:

    • DEFAULT

      public static final PSSParameterSpec DEFAULT
      The PSS parameter set with all default values
      Since:
      1.5

  • Constructor Details

    • RSAPrivateHWKey

      protected RSAPrivateHWKey(byte[] keyToken, RSAKeyHWAttributes attribs) throws InvalidKeyException
      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:
      InvalidKeyException - is thrown if the key could not be DER encoded.

    • RSAPrivateHWKey

      protected RSAPrivateHWKey(byte[] encoded) throws 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:
      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 InvalidKeyException
      Parameters:
      encoded - PKCS#8 DER encoded RSA private key.
      decodePSS - Flag to decode as RSASSA-PSS key
      Throws:
      InvalidKeyException

  • Method Details

    • getFormat

      public String getFormat()
      Return the format for this key.
      Specified by:
      getFormat in interface Key
      Overrides:
      getFormat in class com.ibm.security.pkcs8.PrivateKeyInfo
      Returns:
      one of "PKDSLabel", "RETAIN", "ICSFToken"
      Throws:
      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 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:
      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:
      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()
      Returns a clone of the private key external token.
      Returns:
      the value of externalKeyToken.
      Throws:
      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:
      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:
      IllegalStateException - if destroy() has been called in this key object

    • getModulus

      public BigInteger getModulus() throws 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 RSAKey
      Throws:
      UnsupportedOperationException - is always thrown if this method is invoked.

    • getPrivateExponent

      public 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 RSAPrivateKey
      Throws:
      UnsupportedOperationException - is always thrown if this method is invoked.

    • getPublicExponent

      public 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 RSAPrivateCrtKey
      Throws:
      UnsupportedOperationException - is always thrown if this method is invoked.

    • getPrimeP

      public 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 RSAPrivateCrtKey
      Throws:
      UnsupportedOperationException - is always thrown if this method is invoked.

    • getPrimeQ

      public 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 RSAPrivateCrtKey
      Throws:
      UnsupportedOperationException - is always thrown if this method is invoked.

    • getPrimeExponentP

      public 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 RSAPrivateCrtKey
      Throws:
      UnsupportedOperationException - is always thrown if this method is invoked.

    • getPrimeExponentQ

      public 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 RSAPrivateCrtKey
      Throws:
      UnsupportedOperationException - is always thrown if this method is invoked.

    • getCrtCoefficient

      public 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 RSAPrivateCrtKey
      Throws:
      UnsupportedOperationException - is always thrown if this method is invoked.

    • toString

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

    • getParams

      public AlgorithmParameterSpec getParams()
      Specified by:
      getParams in interface RSAKey

    • parseKeyBits

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