Chilkat.Crypt2 Class Overview
Chilkat.Crypt2 is a general-purpose cryptography class for encryption, decryption, hashing, message authentication, password hashing, key derivation, encoding, random data generation, digital signatures, CMS/PKCS#7, CAdES, and certificate-based public-key workflows.
What the Class Is Used For
Use Crypt2 when an application needs to protect data, verify data integrity, create or validate signatures, derive keys from passwords, work with binary encodings, or build CMS/PKCS#7 security containers. It supports both simple one-shot methods and streaming-friendly methods for large files or chunked data.
Symmetric Encryption
Encrypt and decrypt strings, bytes, files, BinData,
StringBuilder, and secure strings using AES,
ChaCha20, Twofish, Blowfish, and legacy algorithms.
Public-Key / CMS Encryption
Use certificates for PKCS#7/CMS enveloped-data encryption and automatic private-key
lookup during decryption.
Hashing and MACs
Compute SHA-2, SHA-3, SHA-1, MD5, RIPEMD, HAVAL, HMAC, Poly1305, CRC values,
bcrypt password hashes, HOTP, and TOTP codes.
Digital Signatures
Create and verify detached or opaque PKCS#7 signatures, CAdES signatures,
P7M/P7S files, and RSA signatures using certificate/private-key material.
Typical Symmetric Encryption Workflow
- Choose the algorithm with CryptAlgorithm, such as aes or chacha20.
- Set KeyLength, then provide the key with SetEncodedKey, SecretKey, or SetSecretKey.
- For block ciphers, choose a CipherMode, such as CBC, CTR, GCM, or XTS.
- Set or generate the IV when required, using SetEncodedIV or RandomizeIV. For GCM, set AAD and retrieve or provide the authentication tag as needed.
- Choose the method that matches the data shape: EncryptStringENC, EncryptBytes, EncryptBd, CkEncryptFile, or a related method.
- During decryption, use the same algorithm, mode, key length, key, IV, padding, charset, and encoding settings used for encryption.
Core Concepts
| Concept | Meaning | Important Members |
|---|---|---|
| Algorithm | The cryptographic primitive used for encryption, such as AES, ChaCha20, or public-key CMS encryption. | CryptAlgorithm, Pkcs7CryptAlg, PbesAlgorithm |
| Cipher Mode | The mode of operation for block ciphers. Examples include CBC, CTR, GCM, CFB, OFB, ECB, and AES-XTS. | CipherMode, PaddingScheme |
| Key | The secret value used for symmetric encryption or MAC calculation. Its byte length must match the configured key length. | KeyLength, SecretKey, SetEncodedKey, SetMacKeyEncoded |
| IV / Nonce | A non-secret value used with many cipher modes to avoid repeating ciphertext for identical plaintext. | IV, SetEncodedIV, RandomizeIV, GetEncodedIV |
| Encoding | How binary data is represented as text, such as base64, hex, base64url, URL encoding, or quoted-printable. | EncodingMode, Encode, DecodeString, ReEncode |
| Charset | How text is converted to bytes before encryption, hashing, MAC calculation, or signing. | Charset, EncryptStringENC, HashStringENC, SignStringENC |
| CMS / PKCS#7 | A standard container format for public-key encryption and digital signatures, including detached and opaque signatures. | AddEncryptCert, SetSigningCert, CreateP7M, CreateP7S |
| CAdES | CMS signatures with additional signed attributes for advanced electronic-signature profiles. | CadesEnabled, CadesSigPolicyId, CadesSigPolicyUri, CadesSigPolicyHash |
Major Feature Areas
| Area | What You Can Do | Representative Members |
|---|---|---|
| Symmetric Encryption | Encrypt and decrypt strings, byte arrays, files, secure strings, streams of chunks, and mutable binary containers. | EncryptStringENC, DecryptStringENC, EncryptBytes, DecryptBytes, EncryptBd, DecryptBd, CkEncryptFile, CkDecryptFile |
| Authenticated Encryption | Use AES-GCM with optional AAD and an authentication tag to detect tampering. | CipherMode = "GCM", SetEncodedAad, GetEncodedAuthTag, SetEncodedAuthTag |
| AES-XTS | Use AES-XTS mode with a tweak key and tweak value or data-unit number. | CipherMode = "XTS", XtsSetEncodedTweakKey, XtsSetEncodedTweakValue, XtsSetDataUnitNumber |
| Password-Based Encryption | Encrypt using PBES1 or PBES2 with a password, salt, iteration count, and underlying symmetric algorithm. | CryptAlgorithm = "pbes2", PbesAlgorithm, PbesPassword, IterationCount, Salt |
| Key Derivation | Derive encryption keys from passwords using PBKDF1 or PBKDF2. | Pbkdf1, Pbkdf2, GenRandomBytesENC |
| Hashing | Hash strings, bytes, files, and chunked data using SHA-2, SHA-3, SHA-1, MD5, HAVAL, RIPEMD, and related algorithms. | HashAlgorithm, HashStringENC, HashBytesENC, HashFileENC, HashBeginBytes, HashMoreBytes, HashFinalENC |
| MACs | Create message authentication codes using HMAC or Poly1305. | MacAlgorithm, HashAlgorithm, SetMacKeyEncoded, MacStringENC, MacBytesENC, MacBdENC |
| Password Hashing | Create and verify bcrypt password hashes with configurable work factor. | BCryptWorkFactor, BCryptHash, BCryptVerify |
| Public-Key Encryption | Create or decrypt CMS/PKCS#7 enveloped-data using certificates and private keys. | CryptAlgorithm = "pki", AddEncryptCert, SetEncryptCert, SetDecryptCert, AddPfxSourceFile, UseCertVault |
| Digital Signatures | Create and verify detached signatures, opaque signatures, P7M/P7S files, and signatures over precomputed hashes. | SetSigningCert, SignBytesENC, VerifyBytesENC, OpaqueSignStringENC, OpaqueVerifyStringENC, CreateP7M, VerifyP7M |
| CAdES / CMS Options | Add CAdES-BES attributes, signature policy attributes, signing attributes, timestamp-validation options, and specialized CMS behavior. | CadesEnabled, SigningAttributes, CmsOptions, SetTsaHttpObj, GetSignedAttributes |
| Encoding Utilities | Encode, decode, and convert data between base64, hex, URL encodings, quoted-printable, UU, HTML entities, and other encodings. | Encode, EncodeString, DecodeString, ReEncode, EncodingMode |
| Randomness and OTP | Generate random bytes, UUIDs, HOTP codes, and TOTP codes. | GenRandomBytesENC, GenerateUuid, Hotp, Totp |
| Compatibility Helpers | Support specific crypto formats and legacy interoperability needs. | AesKeyWrap, AesKeyUnwrap, MySqlAesEncrypt, MySqlAesDecrypt, UuFilename, UuMode |
Encryption Algorithms
| CryptAlgorithm | Category | Typical Use | Guidance |
|---|---|---|---|
| aes | Symmetric block cipher | General-purpose encryption, file encryption, AES-GCM, AES-CBC, AES-CTR, AES-XTS. | Recommended default for most symmetric encryption needs. |
| chacha20 | Symmetric stream cipher | Fast stream encryption with a 256-bit key. | Useful when a stream cipher is preferred. |
| pki | Public-key CMS encryption | Encrypt to one or more certificates and decrypt using a matching private key. | Used for PKCS#7/CMS enveloped-data, not bulk streaming file encryption. |
| pbes2 | Password-based encryption | Derive an encryption key from a password, salt, and iteration count. | Prefer PBES2 with AES and a modern iteration count. |
| twofish | Symmetric block cipher | Alternative block cipher with up to 256-bit keys. | Still useful for compatibility or specific algorithm requirements. |
| blowfish2 | Symmetric block cipher | Legacy-compatible Blowfish encryption. | Be aware of its 64-bit block size limitation. |
| 3des, des, rc2, arc4 | Legacy algorithms | Interoperability with older systems. | Use only when required for compatibility; prefer AES or ChaCha20 for new designs. |
Cipher Modes and Padding
| Mode | Meaning | Notes |
|---|---|---|
| CBC | Cipher Block Chaining | Requires an IV and padding. Common legacy mode. |
| CTR, CFB, OFB | Stream-like block cipher modes | Use an IV/counter and do not use padding. |
| GCM | Authenticated encryption mode | Provides confidentiality and integrity. Use AAD and authentication tag methods when needed. |
| XTS | AES-XTS mode | Uses a tweak key and tweak value. Supports ciphertext stealing for data not divisible by 16 bytes. |
| ECB | Electronic Codebook | Does not use an IV and leaks patterns. Avoid for new applications. |
| PaddingScheme | How final blocks are padded | Default is PKCS#5/PKCS#7. Padding is unused in stream-like modes such as CTR, CFB, OFB, and GCM. |
Common Data Shapes and Method Choices
| Data Shape | Encryption / Decryption | Hashing / MAC / Signing |
|---|---|---|
| Text string | EncryptStringENC, DecryptStringENC | HashStringENC, MacStringENC, SignStringENC, VerifyStringENC |
| Byte array | EncryptBytes, EncryptBytesENC, DecryptBytes, DecryptBytesENC | HashBytesENC, MacBytesENC, SignBytesENC, VerifyBytesENC |
| File | CkEncryptFile, CkDecryptFile | HashFileENC, CreateP7M, CreateP7S, VerifyP7M, VerifyP7S |
| BinData | EncryptBd, DecryptBd | HashBdENC, MacBdENC, SignBdENC, VerifyBdENC |
| StringBuilder | EncryptSb, DecryptSb | SignSbENC, VerifySbENC |
| SecureString | EncryptSecureENC, DecryptSecureENC | Use string/bytes methods only when the data can safely leave secure-string storage. |
Public-Key Encryption and Certificate Sources
Set CryptAlgorithm = "pki" to use CMS/PKCS#7 public-key encryption. Encryption uses recipient certificates; decryption requires the matching private key. Chilkat can search certificate stores and application-provided sources.
| Task | Members | Purpose |
|---|---|---|
| Encrypt to one certificate | SetEncryptCert | Clears existing encryption recipients and adds the specified certificate. |
| Encrypt to multiple certificates | AddEncryptCert, ClearEncryptCerts | Add one recipient certificate per call. |
| Specify decrypt certificate/private key | SetDecryptCert, SetDecryptCert2 | Use when the application wants to explicitly provide the decryption certificate and private key. |
| Add PFX sources | AddPfxSourceFile, AddPfxSourceData, AddPfxSourceBd | Provide PKCS#12/PFX certificate stores for locating private keys. |
| Use an XML certificate vault | UseCertVault | Adds a certificate/private-key source for signing, verification, encryption, and decryption. |
| Inspect the certificate used for decryption | LastDecryptCert | Returns the certificate used in the most recent public-key decryption. |
Digital Signatures, CMS, and CAdES
Crypt2 can create and verify PKCS#7/CMS signatures in detached form or opaque/enveloping form. Detached signatures store the signature separately from the original data. Opaque signatures embed the original data inside the signed container.
| Signature Need | Use | Notes |
|---|---|---|
| Set the signing certificate | SetSigningCert, SetSigningCert2, AddSigningCert | Signing requires a certificate with access to the corresponding private key. |
| Create detached signatures | SignBytesENC, SignStringENC, SignBdENC, CreateP7S | The original data is kept separate from the signature. |
| Verify detached signatures | VerifyBytesENC, VerifyStringENC, VerifyBdENC, VerifyP7S | Requires both the original data and the signature. |
| Create opaque signatures | OpaqueSignBytesENC, OpaqueSignStringENC, OpaqueSignBd, CreateP7M | The original data is embedded in the PKCS#7 signed-data. |
| Verify opaque signatures | OpaqueVerifyBytesENC, OpaqueVerifyStringENC, OpaqueVerifyBd, VerifyP7M | Verification returns or extracts the embedded original data. |
| Sign a precomputed hash | SignHashENC | Useful when hashing was performed externally or separately. |
| Use RSA-PSS | SigningAlg = "pss" | Switches from PKCS#1 v1.5 signatures to RSASSA-PSS where applicable. |
| Retrieve signer information | NumSignerCerts, LastSignerCert, HasSignatureSigningTime, GetSignatureSigningTimeStr | Use after verification to inspect signer certificates and signing time. |
| Enable CAdES attributes | CadesEnabled, CadesSigPolicyId, CadesSigPolicyUri, CadesSigPolicyHash | Used when a CMS signature must satisfy CAdES-BES or include signature policy attributes. |
Hashing, MACs, and Passwords
| Task | Members | Guidance |
|---|---|---|
| Hash strings or bytes | HashStringENC, HashBytesENC | Set HashAlgorithm and EncodingMode first. |
| Hash large files | HashFile, HashFileENC | File hashing is performed in streaming mode with low memory use. |
| Hash chunked data | HashBeginBytes, HashMoreBytes, HashFinalENC | Use for data that arrives incrementally or should not be buffered all at once. |
| Create HMAC or Poly1305 MAC | MacAlgorithm, SetMacKeyEncoded, MacStringENC, MacBytesENC | For HMAC, HashAlgorithm selects the internal hash function. |
| Hash passwords with bcrypt | BCryptWorkFactor, BCryptHash, BCryptVerify | The work factor controls computational cost. Higher values slow brute-force attacks. |
| Derive keys from passwords | Pbkdf2, Pbkdf1 | Prefer PBKDF2 over PBKDF1. Use a random salt and an iteration count suited to the target hardware. |
| Generate HOTP/TOTP codes | Hotp, Totp | Implements standard one-time password algorithms for shared-secret authentication workflows. |
Encoding and Random Data Utilities
Many Crypt2 methods have an ENC suffix. These methods either accept or return binary data encoded as text. The EncodingMode property controls the encoding for these methods.
| Need | Use | Example Encodings |
|---|---|---|
| Encode binary data | Encode, EncodeBytes, EncodeInt | base64, hex, base64url |
| Encode text as binary representation | EncodeString | Charset controls the text-to-byte conversion before encoding. |
| Decode encoded text | DecodeString | Supports base64, hex, URL encoding, quoted-printable, UU, and HTML entity encoding. |
| Convert between encodings | ReEncode | For example, convert base64 to hex without manually decoding and re-encoding. |
| Generate random bytes | GenRandomBytesENC | Returns random bytes encoded according to EncodingMode. |
| Generate a UUID | GenerateUuid | Creates a random version 4 UUID string. |
Streaming and Large Data
For files, use CkEncryptFile, CkDecryptFile, HashFile, or HashFileENC. These methods are designed for large inputs. For chunked encryption and decryption, use FirstChunk and LastChunk to tell Chilkat when a stream begins and ends.
| Chunk | FirstChunk | LastChunk | Meaning |
|---|---|---|---|
| Only chunk | true | true | The input is complete in one call. |
| First of many | true | false | Starts a streaming encryption/decryption operation. |
| Middle chunk | false | false | Continues processing without final padding or finalization. |
| Final chunk | false | true | Finalizes encryption/decryption and applies or removes padding as needed. |
Diagnostics
| Diagnostic Need | Use |
|---|---|
| Detailed text about the last method or property call | LastErrorText |
| Structured details after selected operations | GetLastJsonData |
| Abort a long-running operation | AbortCurrent |
| AbortCheck event interval | HeartbeatMs |
| Load the caller of an async task | LoadTaskCaller |
Best Practices
| Recommendation | Reason |
|---|---|
| Set Charset = "utf-8" for text-based encryption, hashing, MACs, and signatures. | The documented default may be the platform ANSI charset. UTF-8 is usually the safest modern choice for predictable cross-platform behavior. |
| Prefer AES or ChaCha20 for new symmetric encryption. | Legacy algorithms such as DES, 3DES, RC2, and RC4 exist primarily for compatibility with older systems. |
| Avoid ECB mode. | ECB does not use an IV and can reveal patterns in repeated plaintext blocks. |
| Use random IVs where required, and store or transmit the IV with the ciphertext. | The IV is not secret, but it is required for decryption and prevents repeated plaintext from producing identical ciphertext. |
| Use AES-GCM when authenticated encryption is required. | GCM provides both encryption and integrity/authenticity checking through the authentication tag. |
| Use PBES2 with AES and a modern iteration count for password-based encryption. | PBES2 is the modern PBE option. Iteration counts should be high enough to slow brute-force attacks on target hardware. |
| Prefer PBKDF2 over PBKDF1. | PBKDF2 is stronger and more flexible, especially for deriving longer keys. |
| Use LastErrorText whenever a method returns failure. | Cryptographic operations often fail due to mismatched key, IV, padding, encoding, certificate, or signature settings. |
Summary
Chilkat.Crypt2 is a broad cryptographic utility class. It can encrypt and decrypt data, hash and authenticate messages, derive keys, generate random values and one-time passwords, encode and decode binary data, create and verify PKCS#7/CMS signatures, support CAdES options, and perform certificate-based public-key encryption and decryption.
This page is intended as a structured overview. For precise parameter behavior, return values, and language-specific signatures, refer to the full reference documentation.