Rsa Chilkat2 Perl Reference Documentation
Chilkat2::Rsa
Current Version: 11.7.0
Markdown version of this page for AI tools (v 11.7.0) · all AI docs
Chilkat.Rsa
Use
Encrypt data with a public key for workflows where only the matching
private key should be able to decrypt the result.
Decrypt RSA-encrypted data using a private key, including keys loaded
directly or accessed through a certificate.
Create and verify RSA signatures over data using the hash algorithm and
padding mode required by the application or protocol.
Sign or verify already-computed message digests when the hashing step is
performed separately or by another component.
Generate RSA key pairs for applications that need new public/private key
material.
Use RSA keys associated with certificates, including non-exportable
private keys in smart cards, USB tokens, Windows stores, or Apple
Keychain.
For an extended overview, see
Rsa Class Overview.
Encrypt, decrypt, sign, verify, and generate RSA keys.
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
RSA decryption
Sign and verify data
Sign precomputed hashes
Generate RSA keys
Certificate-backed keys
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.
Object Creation
use Chilkat2;
my $rsa = Chilkat2::Rsa->new;
# or set properties (and RaiseError) at creation:
# my $rsa = Chilkat2::Rsa->new(VerboseLogging => 1, RaiseError => 1);Creates the object. The optional pairs set writable properties (and RaiseError) in order, as if set one by one; an unknown or read-only name croaks. use Chilkat2; loads every class; the Chilkat2/Rsa.pm file holds only this class's documentation (perldoc Chilkat2::Rsa).
Perl frees the object when its last reference goes (undef $rsa, or the variable going out of scope); there is nothing to close. Objects returned by methods are independent and freed the same way. The class may be subclassed (use parent -norequire, 'Chilkat2::Rsa';): an object is a blessed hash reference whose hash is free for the subclass's own fields.
When false (the default), a method that fails returns false (or undef), and the reason is in LastErrorText. When true, it dies with a Chilkat2::Error instead, as DBI does with its RaiseError. Objects returned by a method inherit the value of the object that returned them.
Errors
A Chilkat2::Error stringifies to the failed call's full LastErrorText, and has the methods text, class ('Chilkat2::Rsa'), method (the method name) and object. Methods that look something up and find nothing return undef without dying (each such method says so), methods that answer a question (HasMember, IsUnlocked, ...) return a plain boolean, and property reads and writes never fail for Chilkat reasons.
Misuse always croaks, with your file and line, whatever RaiseError is: a wrong number of arguments, a reference or undef where a string or number is expected, an object of the wrong class, an out-of-range integer, a string containing a NUL character, a wide character in a byte string, or a write to a read-only property.
Strings are Perl character strings in both directions (length, regexes and :encoding layers see characters); binary data (BinData) is a byte string. Unlocking: call Chilkat2::Global->new->UnlockBundle('...') once at startup.
Properties
Charset
my $strVal = $rsa->Charset;
$rsa->Charset($strVal);
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.
DebugLogFilePath
my $strVal = $rsa->DebugLogFilePath;
$rsa->DebugLogFilePath($strVal);
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
EncodingMode
my $strVal = $rsa->EncodingMode;
$rsa->EncodingMode($strVal);
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.
LastErrorHtml
my $strVal = $rsa->LastErrorHtml;
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
my $strVal = $rsa->LastErrorText;
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
my $strVal = $rsa->LastErrorXml;
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastMethodSuccess
my $boolVal = $rsa->LastMethodSuccess;
$rsa->LastMethodSuccess($boolVal);
Indicates the success or failure of the most recent method call: 1 means success, 0 means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
LittleEndian
my $boolVal = $rsa->LittleEndian;
$rsa->LittleEndian($boolVal);
When creating RSA signatures, this property determines the endianness: set it to 1 for little-endian signatures and 0 for big-endian signatures.
NoUnpad
my $boolVal = $rsa->NoUnpad;
$rsa->NoUnpad($boolVal);
If 1, skips unpadding when decrypting. The default is 0. This property value is typically left unchanged.
NumBits
my $intVal = $rsa->NumBits;
The bit length, such as 2048, of the imported or generated RSA key.
topOaepHash
my $strVal = $rsa->OaepHash;
$rsa->OaepHash($strVal);
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.
OaepLabel
my $strVal = $rsa->OaepLabel;
$rsa->OaepLabel($strVal);
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.
OaepMgfHash
my $strVal = $rsa->OaepMgfHash;
$rsa->OaepMgfHash($strVal);
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.
PkcsPadding
my $boolVal = $rsa->PkcsPadding;
$rsa->PkcsPadding($boolVal);
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.
PssSaltLen
my $intVal = $rsa->PssSaltLen;
$rsa->PssSaltLen($intVal);
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.
topUncommonOptions
my $strVal = $rsa->UncommonOptions;
$rsa->UncommonOptions($strVal);
This is a catch-all property to be used for uncommon needs. This property defaults to the empty string and should typically remain empty.
topVerboseLogging
my $boolVal = $rsa->VerboseLogging;
$rsa->VerboseLogging($boolVal);
If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
my $strVal = $rsa->Version;
Methods
DecryptBd
# $usePrivateKey is a boolean
# $success is true or false
my $success = $rsa->DecryptBd($bd, $usePrivateKey);
RSA decrypts the contents of $bd. $usePrivateKey should be set to 1 if the private key is to be used for decrypting. Otherwise it should be set to 0 if (in rare cases) the public key is to be used for decrypting.
Important: If trying to match OpenSSL results, set the LittleEndian property = 0.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
DecryptStringENC
# $usePrivateKey is a boolean
# $str is a string or undef
my $str = $rsa->DecryptStringENC($str, $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 1 to use the private key for decryption; otherwise, set $usePrivateKey to 0 to use the public key (used rarely). Returns the decrypted string.
Important: If trying to match OpenSSL results, set the LittleEndian property = 0.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
EncryptBd
# $usePrivateKey is a boolean
# $success is true or false
my $success = $rsa->EncryptBd($bd, $usePrivateKey);
RSA encrypts the contents of $bd. Set $usePrivateKey to 0 to use the public key for encrypting; otherwise, set it to 1 to use the private key (in rare cases).
Important: If trying to match OpenSSL results, set the LittleEndian property = 0.
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.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
EncryptStringENC
# $bUsePrivateKey is a boolean
# $str is a string or undef
my $str = $rsa->EncryptStringENC($str, $bUsePrivateKey);
Encrypts $str with the RSA algorithm. The Charset property specifies the byte representation of the string that is encrypted. Set $bUsePrivateKey to 0 to use the public key for encrypting; otherwise, set it to 1 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 = 0.
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.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenKey
# $privKey is a Chilkat2::PrivateKey
# $success is true or false
my $success = $rsa->GenKey($numBits, $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.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetX509Cert
# $usePrivateKey is a boolean
# $success is true or false
my $success = $rsa->SetX509Cert($cert, $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.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SignBd
# $hashAlgorithm is a string
# $bdSig is a Chilkat2::BinData
# $success is true or false
my $success = $rsa->SignBd($bdData, $hashAlgorithm, $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.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SignHashENC
# $hashAlg is a string
# $str is a string or undef
my $str = $rsa->SignHashENC($encodedHash, $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.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SignRawBd
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.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SignStringENC
# $hashAlgorithm is a string
# $str is a string or undef
my $str = $rsa->SignStringENC($strToBeHashed, $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.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SnkToXml
# $str is a string or undef
my $str = $rsa->SnkToXml($filename);
Imports a .snk file to an XML document that can be imported via the ImportPrivateKey method.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
UsePrivateKey
# $success is true or false
my $success = $rsa->UsePrivateKey($privKey);
Imports a private key from $privKey to use for signing or decrypting.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
UsePublicKey
# $success is true or false
my $success = $rsa->UsePublicKey($pubKey);
Imports a public key from $pubKey to use for encrypting or signature verification.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
VerifyBd
# $hashAlgorithm is a string
# $bdSig is a Chilkat2::BinData
# $success is true or false
my $success = $rsa->VerifyBd($bdData, $hashAlgorithm, $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 1 if the signature is validated, and 0 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.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
VerifyHashENC
# $hashAlg is a string
# $encodedSig is a string
# $success is true or false
my $success = $rsa->VerifyHashENC($encodedHash, $hashAlg, $encodedSig);
Validates an RSA signature provided in $encodedSig against the hash of the original data in $encodedHash. Returns 1 if validation is successful, otherwise returns 0. $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)
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
VerifyRawBd
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.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
VerifyStringENC
# $hashAlgorithm is a string
# $encodedSig is a string
# $success is true or false
my $success = $rsa->VerifyStringENC($originalString, $hashAlgorithm, $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 1 if the signature is validated, and 0 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.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.