Package com.chilkatsoft.chilkat2

Class Rsa

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Rsa
All Implemented Interfaces:
AutoCloseable
public class Rsa extends ChilkatObject
<section class="rsa-summary">

Encrypt, decrypt, sign, verify, and generate RSA keys.

Use Chilkat.Rsa when an application needs direct RSA cryptographic operations. It can encrypt data with a public key, decrypt with a private key, create RSA signatures, verify signatures, sign precomputed hashes, verify signed hashes, and generate RSA key pairs. It also works with keys supplied directly as PrivateKey or PublicKey objects, or indirectly through certificates.

RSA encryption

Encrypt data with a public key for workflows where only the matching private key should be able to decrypt the result.

RSA decryption

Decrypt RSA-encrypted data using a private key, including keys loaded directly or accessed through a certificate.

Sign and verify data

Create and verify RSA signatures over data using the hash algorithm and padding mode required by the application or protocol.

Sign precomputed hashes

Sign or verify already-computed message digests when the hashing step is performed separately or by another component.

Generate RSA keys

Generate RSA key pairs for applications that need new public/private key material.

Certificate-backed keys

Use RSA keys associated with certificates, including non-exportable private keys in smart cards, USB tokens, Windows stores, or Apple Keychain.

Common pattern: Load or generate the RSA key material, configure the padding, hash, charset, and encoding options needed by the protocol, then call the method matching the operation: encrypt, decrypt, sign, verify, sign-hash, or verify-hash. Use Chilkat.Rsa for direct RSA operations; use higher-level classes such as Crypt2, Jws, Jwt, or Mime when the RSA operation is part of a larger format or protocol.

For an extended overview, see Rsa Class Overview.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Rsa

      public Rsa()
      Creates a new Rsa object.

  • Method Details

    • getCharset

      public String getCharset()
      This property specifies the character encoding used to represent text as bytes for encryption, decryption, signing, and signature validation. By default, it uses the computer's ANSI charset, such as Windows-1252 for locales like the United States, United Kingdom, Western Europe, Australia, and New Zealand.

      Most applications are advised to set this property to UTF-8. Chilkat plans to change its default to UTF-8 in a future major version to align with current standards. The current default of ANSI stems from a time when UTF-8 was not widely adopted.

      Returns:
      the value of the Charset property

    • setCharset

      public void setCharset​(String value)
      Sets the Charset property; see getCharset().
      Parameters:
      value - the new value (not null)

    • getEncodingMode

      public String getEncodingMode()
      This property defines the encoding for methods ending in ENC, such as EncryptStringENC. Valid modes include base64, hex, hex_lower, and more. The encoding mode applies to signatures, encrypted data, and hashes used in or returned by a method.
      Returns:
      the value of the EncodingMode property

    • setEncodingMode

      public void setEncodingMode​(String value)
      Sets the EncodingMode property; see getEncodingMode().
      Parameters:
      value - the new value (not null)

    • getLittleEndian

      public boolean getLittleEndian()
      When creating RSA signatures, this property determines the endianness: set it to true for little-endian signatures and false for big-endian signatures.
      Returns:
      the value of the LittleEndian property

    • setLittleEndian

      public void setLittleEndian​(boolean value)
      Sets the LittleEndian property; see getLittleEndian().
      Parameters:
      value - the new value

    • getNoUnpad

      public boolean getNoUnpad()
      If true, skips unpadding when decrypting. The default is false. This property value is typically left unchanged.
      Returns:
      the value of the NoUnpad property

    • setNoUnpad

      public void setNoUnpad​(boolean value)
      Sets the NoUnpad property; see getNoUnpad().
      Parameters:
      value - the new value

    • getNumBits

      public int getNumBits()
      The bit length, such as 2048, of the imported or generated RSA key.
      Returns:
      the value of the NumBits property (read-only)

    • getOaepHash

      public String getOaepHash()
      Selects the hash algorithm for use within OAEP padding for encryption. The valid choices are sha256, sha384, sha512, or sha1.

      The default is SHA1. You'll likely want to change this to to SHA256. The next major version of Chilkat (11.0.0) will change the default to SHA256.

      Returns:
      the value of the OaepHash property

    • setOaepHash

      public void setOaepHash​(String value)
      Sets the OaepHash property; see getOaepHash().
      Parameters:
      value - the new value (not null)

    • getOaepLabel

      public String getOaepLabel()
      The optional RSA encryption OAEP label is a hex representation of the label bytes used for encrypting with OAEP padding. Typically, this is left empty (0 bytes) unless there's a specific requirement to set it.
      Returns:
      the value of the OaepLabel property

    • setOaepLabel

      public void setOaepLabel​(String value)
      Sets the OaepLabel property; see getOaepLabel().
      Parameters:
      value - the new value (not null)

    • getOaepMgfHash

      public String getOaepMgfHash()
      Selects the MGF (mask generation) hash algorithm for use within OAEP padding for encryption. The valid choices are sha256, sha384, sha512, or sha1.

      Note: This property should typically be set to the same value as the OaepHash property. Many software implementations are not able to handle cases where the MGF hash is different than the OAEP hash.

      The default is SHA1. You'll likely want to change this to to SHA256. The next major version of Chilkat (11.0.0) will change the default to SHA256.

      Returns:
      the value of the OaepMgfHash property

    • setOaepMgfHash

      public void setOaepMgfHash​(String value)
      Sets the OaepMgfHash property; see getOaepMgfHash().
      Parameters:
      value - the new value (not null)

    • getPkcsPadding

      public boolean getPkcsPadding()
      This property controls padding for both signing and encryption. The default value is true, which is to use PKCS#1 v1.5 padding. If set to false, then PSS padding is used for signatures and OAEP padding is used for encryption.

      This property replaces the deprecated OaepPadding property. Until the OaepPadding property is removed, setting this property will automatically set OaepPadding to the opposite, and vice-versa. This is to maintain backward compatibility until applications can switch to using this new property.

      Returns:
      the value of the PkcsPadding property

    • setPkcsPadding

      public void setPkcsPadding​(boolean value)
      Sets the PkcsPadding property; see getPkcsPadding().
      Parameters:
      value - the new value

    • getPssSaltLen

      public int getPssSaltLen()
      When using RSASSA-PSS padding for signatures, you can choose the PSS salt length. By default, the salt length is set to -1, which uses the length of the hash function. For instance, with the SHA256 hash function, the salt length will be 32 bytes. You can specify a different salt length, like 20 bytes, if needed, but it's generally recommended to keep the default setting.
      Returns:
      the value of the PssSaltLen property

    • setPssSaltLen

      public void setPssSaltLen​(int value)
      Sets the PssSaltLen property; see getPssSaltLen().
      Parameters:
      value - the new value

    • getUncommonOptions

      public String getUncommonOptions()
      This is a catch-all property to be used for uncommon needs. This property defaults to the empty string and should typically remain empty.
      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • decryptBd

      public void decryptBd​(BinData bd, boolean usePrivateKey)
      RSA decrypts the contents of bd. usePrivateKey should be set to true if the private key is to be used for decrypting. Otherwise it should be set to false if (in rare cases) the public key is to be used for decrypting.

      Important: If trying to match OpenSSL results, set the LittleEndian property = false.

      Parameters:
      bd - the bd argument (not null)
      usePrivateKey - the usePrivateKey argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • decryptStringENC

      public String decryptStringENC​(String str, boolean usePrivateKey)
      Decrypts str with the RSA algorithm. str is the encoded form of the encrypted binary data. The EncodingMode property defines str's encoding. The Charset property specifies the byte representation for interpreting the decrypted text. Set usePrivateKey to true to use the private key for decryption; otherwise, set usePrivateKey to false to use the public key (used rarely). Returns the decrypted string.

      Important: If trying to match OpenSSL results, set the LittleEndian property = false.

      Parameters:
      str - the str argument (not null)
      usePrivateKey - the usePrivateKey argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • encryptBd

      public void encryptBd​(BinData bd, boolean usePrivateKey)
      RSA encrypts the contents of bd. Set usePrivateKey to false to use the public key for encrypting; otherwise, set it to true to use the private key (in rare cases).

      Important: If trying to match OpenSSL results, set the LittleEndian property = false.

      Note: The public key's role is to make encryption accessible to anyone while ensuring that only the private key holder can decrypt the messages. The public key is designed to be widely distributed so anyone can use it to encrypt messages intended for the owner of the private key.

      Parameters:
      bd - the bd argument (not null)
      usePrivateKey - the usePrivateKey argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • encryptStringENC

      public String encryptStringENC​(String str, boolean bUsePrivateKey)
      Encrypts str with the RSA algorithm. The Charset property specifies the byte representation of the string that is encrypted. Set bUsePrivateKey to false to use the public key for encrypting; otherwise, set it to true to use the private key (in rare cases). The encrypted data is returned in the format specified by the EncodingMode property.

      Important: If trying to match OpenSSL results, set the LittleEndian property = false.

      Note: The public key's role is to make encryption accessible to anyone while ensuring that only the private key holder can decrypt the messages. The public key is designed to be widely distributed so anyone can use it to encrypt messages intended for the owner of the private key.

      Parameters:
      str - the str argument (not null)
      bUsePrivateKey - the bUsePrivateKey argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • genKey

      public void genKey​(int numBits, PrivateKey privKey)
      Generates a new RSA key and stores it in privKey. numBits specifies the key length, which can range from 512 to 8192 bits. Common key lengths are 1024, 2048, or 4096 bits.

      Note: Generating an 8192-bit key may take a significant amount of time. The method does not support event callbacks or progress monitoring and will block the thread until completion.

      Parameters:
      numBits - the numBits argument
      privKey - the privKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setX509Cert

      public void setX509Cert​(Cert cert, boolean usePrivateKey)
      Provides the private or public key indirectly through a certificate. This method is used when the private key is inaccessible, such as when stored on a smart card, USB token, in the Windows registry (marked as non-exportable), or in the Apple Keychain.
      Parameters:
      cert - the cert argument (not null)
      usePrivateKey - the usePrivateKey argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • signBd

      public void signBd​(BinData bdData, String hashAlgorithm, BinData bdSig)
      Generates an RSA digital signature by first hashing the contents of bdData with the hash algorithm specified by hashAlgorithm, which can be sha256, sha384, sha512, or sha1. The resulting signature is written to bdSig.

      Note: It is important to be aware of endianness. Make sure the LittleEndian property is set according to your specific needs.

      Parameters:
      bdData - the bdData argument (not null)
      hashAlgorithm - the hashAlgorithm argument (not null)
      bdSig - the bdSig argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • signHashENC

      public String signHashENC​(String encodedHash, String hashAlg)
      This function creates an RSA digital signature for the hash provided in encodedHash, which should be encoded according to the EncodingMode setting (e.g., base64 if EncodingMode = base64). hashAlg specifies the hash algorithm and can be sha256, sha384, sha512, or sha1. The function returns the signature encoded as specified by EncodingMode.
      Parameters:
      encodedHash - the encodedHash argument (not null)
      hashAlg - the hashAlg argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • signRawBd

      public void signRawBd​(BinData bd)
      This is legacy low-level raw RSA that duplicates the (now deprecated) OpenSSL rsautl utility. It directly signs raw data rather than signing a hash of the data. PKCS#1 v1.5 padding is always used. The data to be signed is passed in bd, and on return the content of bd is replaced with the RSA signed data.

      Note: It is possible to validate and recover the original data by calling VerifyRawBd.

      Parameters:
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • signStringENC

      public String signStringENC​(String strToBeHashed, String hashAlgorithm)
      Generates an RSA digital signature by first hashing strToBeHashed with the hash algorithm specified by hashAlgorithm, which can be sha256, sha384, sha512, or sha1. Returns the signature encoded based on the EncodingMode property.

      Note: It is important to be aware of endianness. Make sure the LittleEndian property is set according to your specific needs.

      Note: It is recommended to set the Charset property equal to utf-8 before signing strings.

      Parameters:
      strToBeHashed - the strToBeHashed argument (not null)
      hashAlgorithm - the hashAlgorithm argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • snkToXml

      public String snkToXml​(String filename)
      Imports a .snk file to an XML document that can be imported via the ImportPrivateKey method.
      Parameters:
      filename - the filename argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • usePrivateKey

      public void usePrivateKey​(PrivateKey privKey)
      Imports a private key from privKey to use for signing or decrypting.
      Parameters:
      privKey - the privKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • usePublicKey

      public void usePublicKey​(PublicKey pubKey)
      Imports a public key from pubKey to use for encrypting or signature verification.
      Parameters:
      pubKey - the pubKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • verifyBd

      public void verifyBd​(BinData bdData, String hashAlgorithm, BinData bdSig)
      Verifies the RSA signature passed in bdSig against the original data passed in bdData. The original data passed in bdData is hashed using the hash algorithm passed in hashAlgorithm (such as sha256, sha384, sha512, or sha1). Returns true if the signature is validated, and false if not.

      Note: Knowing the exact hash algorithm used to create the signature is not required. If the signature is not validated using the hash algorithm specified in hashAlgorithm, Chilkat will automatically try validating using the other supported algorithms and return success if any validate.

      Parameters:
      bdData - the bdData argument (not null)
      hashAlgorithm - the hashAlgorithm argument (not null)
      bdSig - the bdSig argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • verifyHashENC

      public void verifyHashENC​(String encodedHash, String hashAlg, String encodedSig)
      Validates an RSA signature provided in encodedSig against the hash of the original data in encodedHash. Returns true if validation is successful, otherwise returns false. hashAlg specifies the hash algorithm used for encodedHash, such as sha256, sha384, sha512, or sha1. Ensure the hash's size (e.g., 32 bytes for sha256, 48 bytes for sha384, 64 bytes for sha512, 20 bytes for sha1) matches that of encodedHash.

      Both encodedHash and encodedSig should be encoded according to the EncodingMode property (e.g., base64 if EncodingMode = base64)

      Parameters:
      encodedHash - the encodedHash argument (not null)
      hashAlg - the hashAlg argument (not null)
      encodedSig - the encodedSig argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • verifyRawBd

      public void verifyRawBd​(BinData bd)
      This is legacy low-level raw RSA that duplicates the (now deprecated) OpenSSL rsautl utility. It validates signed raw data and recovers the original data. The RSA signature to be verified is passed in bd, and on return the content of bd is replaced with the original data.
      Parameters:
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • verifyStringENC

      public void verifyStringENC​(String originalString, String hashAlgorithm, String encodedSig)
      Verifies the encoded RSA signature passed in encodedSig against the original data passed in originalString. The original data passed in originalString is hashed using the hash algorithm passed in hashAlgorithm (such as sha256, sha384, sha512, or sha1). Returns true if the signature is validated, and false if not.

      The signature passed in encodedSig should be encoded according to the EncodingMode property (e.g., base64 if EncodingMode = base64)

      Note: Knowing the exact hash algorithm used to create the signature is not required. If the signature is not validated using the hash algorithm specified in hashAlgorithm, Chilkat will automatically try validating using the other supported algorithms and return success if any validate.

      Parameters:
      originalString - the originalString argument (not null)
      hashAlgorithm - the hashAlgorithm argument (not null)
      encodedSig - the encodedSig argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why