What the Class Is Used For

Use Chilkat.Rsa when an application needs direct RSA operations: encrypting data with a public key, decrypting with a private key, creating RSA signatures, verifying signatures, signing precomputed hashes, or generating RSA keys. It is also useful when the key is provided indirectly through a certificate, including cases where the private key is non-exportable or stored in a smart card, USB token, Windows certificate store, or Apple Keychain.

Encrypt and Decrypt Encrypt strings, byte arrays, or BinData, and return either raw bytes or encoded output such as Base64 or hex.

Sign and Verify Create RSA signatures over strings, bytes, BinData, or precomputed hashes.

Padding Control Use PKCS#1 v1.5 by default, or switch to PSS for signatures and OAEP for encryption.

Key Flexibility Use explicit PrivateKey / PublicKey objects or provide keys through a Cert.

Typical Workflow

Load or generate an RSA key using UsePublicKey, UsePrivateKey, SetX509Cert, or GenKey.
Set Charset to utf-8 when encrypting or signing strings.
Set EncodingMode when using methods ending in ENC, such as EncryptStringENC or SignBytesENC.
Choose padding behavior with PkcsPadding. Leave it true for PKCS#1 v1.5, or set it false to use OAEP for encryption and PSS for signatures.
For OAEP, configure OaepHash, OaepMgfHash, and optionally OaepLabel.
Call the appropriate encrypt, decrypt, sign, or verify method for the data type being used.
Check LastErrorText after failures or unexpected results.

Core Concepts

Concept	Meaning	Important Members
Public Key Encryption	The usual RSA encryption pattern: anyone with the public key can encrypt, and only the private key holder can decrypt.	UsePublicKey, EncryptBytes, EncryptStringENC
Private Key Decryption	The normal counterpart to public-key encryption.	UsePrivateKey, DecryptBytes, DecryptStringENC
RSA Signature	A signature is created by hashing the data and signing the hash with the private key. The public key verifies it.	SignStringENC, SignBytes, VerifyStringENC
Precomputed Hash Signing	A hash is computed elsewhere, then signed directly.	SignHash, SignHashENC, VerifyHash
ENC Methods	Methods ending in ENC use EncodingMode for encoded inputs or outputs.	EncodingMode, EncryptBytesENC, VerifyHashENC
Padding Mode	Padding affects RSA encryption and signatures. PKCS#1 v1.5 is the default; OAEP and PSS are selected by setting PkcsPadding to false.	PkcsPadding, OaepHash, PssSaltLen

Core Properties

Property	Purpose	Guidance
Charset	Character encoding used to convert text to bytes for encryption, decryption, signing, and verification.	Default is the computer’s ANSI charset. Most applications should set this to utf-8.
EncodingMode	Encoding used by methods ending in ENC.	Common values include base64, hex, and hex_lower.
NumBits	Bit length of the imported or generated RSA key.	Examples include 2048 or 4096.
PkcsPadding	Controls padding for both encryption and signing.	Default true uses PKCS#1 v1.5. Set false to use OAEP for encryption and PSS for signatures.
OaepHash	Hash algorithm used within OAEP padding.	Valid choices are sha1, sha256, sha384, and sha512. Default is SHA1; SHA256 is usually preferred.
OaepMgfHash	MGF hash algorithm used within OAEP padding.	Usually set to the same value as OaepHash because many implementations do not handle different OAEP and MGF hashes.
OaepLabel	Optional OAEP label, represented as hex bytes.	Typically left empty unless a protocol specifically requires it.
PssSaltLen	Salt length for RSASSA-PSS signatures.	Default -1 uses the hash length, such as 32 bytes for SHA256.
LittleEndian	Controls signature endianness.	Set false for big-endian signatures. The documentation notes this is needed when matching OpenSSL results.
NoUnpad	Skips unpadding when decrypting.	Default is false. Typically left unchanged.
LastErrorText	Diagnostic text for the last method or property access.	Check after failures or unexpected behavior.

Key Setup

Need	Method	Use Case
Use a public key	UsePublicKey	Imports a PublicKey for encryption or signature verification.
Use a private key	UsePrivateKey	Imports a PrivateKey for signing or decryption.
Use key from certificate	SetX509Cert	Provides a public or private key indirectly through a Cert. Useful for non-exportable private keys, smart cards, USB tokens, Windows registry-backed keys, or Apple Keychain.
Generate a new RSA key	GenKey	Generates a key from 512 to 8192 bits and stores it in a PrivateKey.
Convert SNK to XML key	SnkToXml	Imports a .snk file to XML suitable for import by the private-key import workflow.

Key-generation note: GenKey can generate keys up to 8192 bits, but very large keys may take significant time. The method blocks until completion and does not provide progress callbacks.

Padding Modes

Setting	Encryption Behavior	Signature Behavior
PkcsPadding = true	Uses PKCS#1 v1.5 padding for RSA encryption.	Uses PKCS#1 v1.5 padding for RSA signatures.
PkcsPadding = false	Uses OAEP padding for RSA encryption.	Uses RSASSA-PSS padding for RSA signatures.

Compatibility note: PkcsPadding replaces the deprecated OaepPadding property. While both exist, setting one automatically adjusts the other in the opposite direction for backward compatibility.

Encryption and Decryption

The usual RSA workflow is to encrypt with the public key and decrypt with the private key. The methods allow private-key encryption and public-key decryption in rare cases, controlled by the usePrivateKey argument.

Data Form	Encrypt Methods	Decrypt Methods
String → bytes	EncryptString	DecryptString
String → encoded text	EncryptStringENC	DecryptStringENC
Byte array	EncryptBytes	DecryptBytes
Encoded encrypted bytes	EncryptBytesENC	DecryptBytesENC
BinData in place	EncryptBd	DecryptBd

Recommended pattern: Use usePrivateKey = false for encryption and usePrivateKey = true for decryption. This matches the normal public-key encryption model.

OpenSSL matching: The documentation notes that when trying to match OpenSSL results, set LittleEndian = false.

Signing Data

Signature methods hash the original data using the requested hash algorithm, then sign the hash with the RSA private key. Supported hash algorithm names include sha1, sha256, sha384, and sha512.

Input Data	Binary Signature	Encoded Signature
String	SignString	SignStringENC
Byte array	SignBytes	SignBytesENC
BinData	SignBd writes the resulting signature to a BinData output object.
Precomputed hash	SignHash	SignHashENC
Legacy raw data	SignRawBd performs low-level raw RSA and replaces the BinData contents with the signed data.

String signing: For string signatures, set Charset to utf-8 so the text-to-byte conversion is predictable across platforms and locales.

Verifying Signatures

Verification methods hash the original data and compare it with the RSA signature. For standard verification methods, the documentation notes that if the specified hash algorithm does not validate the signature, Chilkat automatically tries the other supported algorithms and returns success if any validate.

Original Data	Binary Signature	Encoded Signature
String	VerifyString	VerifyStringENC
Byte array	VerifyBytes	VerifyBytesENC
BinData	VerifyBd verifies a BinData signature against BinData original data.
Precomputed hash	VerifyHash	VerifyHashENC
Legacy raw RSA	VerifyRawBd validates raw RSA signed data and replaces the BinData contents with the recovered original data.

Hash-size check: For VerifyHash and VerifyHashENC, ensure the supplied hash length matches the algorithm, such as 32 bytes for SHA256, 48 bytes for SHA384, 64 bytes for SHA512, or 20 bytes for SHA1.

ENC Methods and EncodingMode

Pattern	Meaning	Examples
Method ends in ENC	The method accepts or returns encoded text instead of raw bytes.	EncryptStringENC, DecryptBytesENC, SignHashENC
EncodingMode = "base64"	Encoded input/output is Base64.	Useful for transmitting signatures or encrypted bytes as text.
EncodingMode = "hex"	Encoded input/output is hexadecimal.	Useful for debugging, logs, or APIs that expect hex.
EncodingMode = "hex_lower"	Encoded input/output is lowercase hexadecimal.	Useful when exact lowercase hex formatting is required.

Choosing the Right Method Family

Data You Have	Encrypt / Decrypt	Sign / Verify
Text string	EncryptString, EncryptStringENC, DecryptString, DecryptStringENC	SignString, SignStringENC, VerifyString, VerifyStringENC
Byte array	EncryptBytes, EncryptBytesENC, DecryptBytes, DecryptBytesENC	SignBytes, SignBytesENC, VerifyBytes, VerifyBytesENC
BinData	EncryptBd, DecryptBd	SignBd, VerifyBd
Precomputed hash	Not applicable.	SignHash, SignHashENC, VerifyHash, VerifyHashENC

Legacy Raw RSA

Method	Purpose	Important Warning
SignRawBd	Performs low-level raw RSA signing directly on the data in BinData.	This is legacy behavior that duplicates the now-deprecated OpenSSL rsautl utility. It signs raw data rather than hashing first.
VerifyRawBd	Validates raw RSA signed data and recovers the original data.	Use standard hash-based signing and verification methods for normal application signatures.

Prefer standard signatures: For ordinary digital signatures, use SignString, SignBytes, SignBd, or SignHash and their corresponding verify methods.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
General failure	LastErrorText	Check after any failed encryption, decryption, signing, verification, key setup, or key-generation operation.
String encryption or signature mismatch	Charset	Ensure both sides use the same text-to-byte encoding. For new code, use utf-8.
Encoded signature or ciphertext is not interpreted correctly	EncodingMode	Confirm both sides use the same encoding, such as base64 or hex.
OpenSSL interoperability mismatch	LittleEndian	The documentation notes that matching OpenSSL results requires LittleEndian = false.
OAEP decryption fails	PkcsPadding, OaepHash, OaepMgfHash, OaepLabel	Confirm padding mode and all OAEP parameters match the encrypting side.
PSS signature verification fails	PkcsPadding, PssSaltLen, hashAlgorithm	Confirm PSS mode, salt length, and the expected hash algorithm.
Private key unavailable	UsePrivateKey, SetX509Cert	For non-exportable private keys, use SetX509Cert with the certificate that provides indirect access to the private key.

Common Pitfalls

Pitfall	Better Approach
Using the default ANSI charset for string cryptography.	Set Charset = "utf-8" before encrypting, decrypting, signing, or verifying strings.
Using the wrong key direction for encryption.	Normally encrypt with the public key and decrypt with the private key.
Forgetting that ENC methods depend on EncodingMode.	Set EncodingMode explicitly before using encoded ciphertext, signatures, or hashes.
Mixing PKCS#1 v1.5 and OAEP/PSS expectations.	Check PkcsPadding. True means PKCS#1 v1.5; false means OAEP for encryption and PSS for signatures.
Using different OAEP hash and MGF hash values without a reason.	Set OaepMgfHash to the same value as OaepHash unless a protocol requires otherwise.
Using raw RSA methods for ordinary signatures.	Use standard hash-based signing methods instead of SignRawBd and VerifyRawBd.
Expecting 8192-bit key generation to return quickly.	Large key generation may take significant time and blocks until completion.

Best Practices

Recommendation	Reason
Set Charset = "utf-8" for string operations.	It avoids locale-dependent ANSI behavior and produces predictable text-to-byte conversions.
Set EncodingMode explicitly for all ENC methods.	It makes encoded ciphertext, signatures, and hashes unambiguous.
Use public-key encryption and private-key decryption for confidentiality.	This is the intended RSA encryption model.
Use private-key signing and public-key verification for authenticity.	This is the intended RSA signature model.
Prefer SHA256 or stronger hash algorithms for new signatures.	The supported signing hash algorithms include SHA256, SHA384, and SHA512.
Use OAEP and PSS when interoperability requirements allow it.	Set PkcsPadding = false and configure OAEP/PSS parameters consistently with the other side.
Use SetX509Cert for non-exportable private keys.	It allows RSA operations through certificates whose private keys are stored externally or protected by the OS or hardware.
Check LastErrorText after failures.	It provides the most useful diagnostic detail for key import, padding, encoding, signing, verification, encryption, and decryption problems.

Summary

Chilkat.Rsa is the primary Chilkat class for direct RSA operations. It supports RSA encryption/decryption, signing/verification, precomputed hash signatures, key generation, public/private key use, certificate based key access, encoded input/output, and BinData workflows. The key configuration points are Charset, EncodingMode, PkcsPadding, OAEP hash settings, PSS salt length, and LittleEndian for interoperability.

For most new code: use UTF-8 for strings, Base64 or hex explicitly for encoded outputs, public-key encryption with private-key decryption, private-key signing with public-key verification, and SHA256 or stronger hash algorithms.

Chilkat.Rsa Class Overview