CkCrypt2 C++ Class Reference (Visual C++)
CkCrypt2
Chilkat encryption component.
Properties
int get_BlockSize(void) const;
The block-size (in bytes) of the selected encryption algorithm. For example, if the CryptAlgorithm property is set to "aes", the BlockSize property is automatically set to 16. The block-size for the ARC4 streaming encryption algorithm is 1.
void get_Charset(CkString &out);
void put_Charset(const char *str);
Controls the character encoding of the text encrypted, signed, hashed or compressed. This property is relevant wherever strings are used as inputs or outputs. When working with strings, it is important to know the exact bytes that are being encrypted/hashed/signed/compressed. This is critical when interoperating with other systems. If your application is sending an encrypted string to another system that will decrypt it, you will need to know the encoding of the string that is expected on the receiving end (after decryption). If you pass Unicode data (2 byte per character) to the encryptor, subsequent decryption will reproduce the original Unicode. However, it may be that your program works with Unicode strings, but the recipient of the encrypted data works with iso-8859-1 strings. In such a case, setting the Charset property to "iso-8859-1" causes the character data to be automatically converted to the Charset before being encrypted (or compressed, or hashed, or signed). The set of valid charsets is listed below:
ANSI
us-ascii
unicode
unicodefffe
iso-8859-1
iso-8859-2
iso-8859-3
iso-8859-4
iso-8859-5
iso-8859-6
iso-8859-7
iso-8859-8
iso-8859-9
iso-8859-13
iso-8859-15
windows-874
windows-1250
windows-1251
windows-1252
windows-1253
windows-1254
windows-1255
windows-1256
windows-1257
windows-1258
utf-7
utf-8
utf-32
utf-32be
shift_jis
gb2312
ks_c_5601-1987
big5
iso-2022-jp
iso-2022-kr
euc-jp
euc-kr
macintosh
x-mac-japanese
x-mac-chinesetrad
x-mac-korean
x-mac-arabic
x-mac-hebrew
x-mac-greek
x-mac-cyrillic
x-mac-chinesesimp
x-mac-romanian
x-mac-ukrainian
x-mac-thai
x-mac-ce
x-mac-icelandic
x-mac-turkish
x-mac-croatian
asmo-708
dos-720
dos-862
ibm037
ibm437
ibm500
ibm737
ibm775
ibm850
ibm852
ibm855
ibm857
ibm00858
ibm860
ibm861
ibm863
ibm864
ibm865
cp866
ibm869
ibm870
cp875
koi8-r
koi8-u
void get_CipherMode(CkString &out);
void put_CipherMode(const char *newVal);
Controls the cipher mode for Rijndael and Twofish encryption. Possible values are "CBC" (the default) and "ECB". CBC is an acronym for Cipher Block Chaining, ECB is an acronym for Electronic CookBook.
void get_CompressionAlgorithm(CkString &out);
void put_CompressionAlgorithm(const char *alg);
Selects the compression algorithm to be used. Currently, the only valid setting is "BZIP2".
void get_CryptAlgorithm(CkString &out);
void put_CryptAlgorithm(const char *str);
Selects the encryption algorithm for encrypting and decrypting. Possible values are: "pki", "aes", "rijndael", "blowfish", "blowfish2", "des", "rc2", "arc4", and "twofish". The "pki" encryption algorithm isn't a specific algorithm, but instead tells the component to encrypt/decrypt using public-key encryption with digital certificates. The other choices, rijndael, blowfish, and twofish, are symmetric encryption algorithms that do not involve digital certificates and public/private keys.
The original Chilkat implementation of Blowfish has a 4321 byte-swapping issue (the results are 4321 byte-swapped). The new implementation ("blowfish2") does not byte swap. This should be used for compatibility with other Blowfish software.
void get_EncodingMode(CkString &out);
void put_EncodingMode(const char *str);
Controls the encoding of binary data to a printable string for many methods. The valid modes are "Base64", "QP" (for quoted-printable), "URL" (for url-encoding), and "Hex".
bool get_FirstChunk(void) const;
void put_FirstChunk(bool b);
Chilkat Crypt2 provides the ability to feed the encryption/decryption methods with chunks of data. This allows a large amount of data, or a data stream, to be fed piecemeal for encrypting or decrypting. It applies to all symmetric algorithms currently supported (AES, Blowfish, Twofish, 3DES, RC2, DES, ARC4), and all algorithms supported in the future.
The default value for both FirstChunk and LastChunk is true — meaning that when you call an Encrypt* or Decrypt* method, it is both the first and last chunk (i.e. it’s the entire amount of data to be encrypted or decrypted).
If you wish to feed the data piecemeal, do this:
- Set FirstChunk = true, LastChunk = false for the first chunk of data.
- For all “middle” chunks (i.e. all chunks except for the final chunk) set FirstChunk = false and LastChunk = false.
- For the final chunk, set FirstChunk = false and LastChunk = true
You don’t need to worry about feeding data according to the block size of the encryption algorithm. For example, AES has a block size of 16 bytes. You may feed data in chunks of any size. The Chilkat Crypt2 component will buffer the data. When the final chunk is passed, the output is padded to the algorithm’s block size according to the PaddingScheme. more info about FirstChunk/LastChunk
void get_HashAlgorithm(CkString &out);
void put_HashAlgorithm(const char *str);
Selects the hash algorithm used by methods that create hashes. The valid choices are "sha1", "sha256", "sha384", "sha512", "md2", "md5", and "haval".
long get_HavalRounds(void);
void put_HavalRounds(long newVal);
Applies to the HAVAL hash algorithm only and must be set to the integer value 3, 4, or 5. The default value is 3.
void get_IV(CkByteData &bData);
void put_IV(const CkByteData &bData);
The initialization vector to be used with symmetric encryption algorithms (Rijndael, Blowfish, Twofish). If left unset, no initialization vector is used.
bool get_IncludeCertChain(void);
void put_IncludeCertChain(bool newVal);
To be documented soon.
long get_KeyLength(void);
void put_KeyLength(long newVal);
The key length in bits for symmetric encryption algorithms. The default value is 128.
bool get_LastChunk(void) const;
void put_LastChunk(bool b);
(See the description for the FirstChunk property.)
void LastErrorHtml(CkString &str);
Error information in HTML format for the last method called.
void LastErrorText(CkString &str);
Error information in plain-text format for the last method called.
void LastErrorXml(CkString &str);
Error information in XML format for the last method called.
long get_PaddingScheme(void);
void put_PaddingScheme(long newVal);
The padding scheme used by block encryption algorithms such as AES (Rijndael), Blowfish, Twofish, RC2, DES, 3DES, etc. Block encryption algorithms pad encrypted data to a multiple of algorithm's block size. The default value of this property is 0.
Possible values are:
0 = RFC 1423 padding scheme: Each padding byte is set to the number of padding bytes. If the data is already a multiple of algorithm's block size bytes, an extra block is appended each having a value equal to the block size. (for example, if the algorithm's block size is 16, then 16 bytes having the value 0x10 are added.). (This is also known as PKCS7 padding: PKCS #7 padding string consists of a sequence of bytes, each of which is equal to the total number of padding bytes added. )
1 = FIPS81 (Federal Information Processing Standards 81) where the last byte contains the number of padding bytes, including itself, and the other padding bytes are set to random values.
2 = Each padding byte is set to a random value. The decryptor must know how many bytes are in the original unencrypted data.
3 = Pad with NULLs. (If already a multiple of the algorithm's block size, no padding is added).
4 = Pad with SPACE chars(0x20). (If already a multiple of algorithm's block size, no padding is added).
long get_Rc2EffectiveKeyLength(void);
void put_Rc2EffectiveKeyLength(long newVal);
The effective key length (in bits) for the RC2 encryption algorithm. When RC2 is used, both the KeyLength and Rc2EffectiveKeyLength properties should be set. For RC2, both should be between 8 and 1024 (inclusive).
void get_SecretKey(CkByteData &bData);
void put_SecretKey(const CkByteData &bData);
The binary secret key used for symmetric encryption (Rijndael, Blowfish, Twofish). The secret key must be identical for decryption to succeed. The length in bytes of the SecretKey must equal the KeyLength/8.
bool get_Utf8(void) const;
void put_Utf8(bool b);
When set to true, all "const char *" arguments are expected to be utf-8 strings. If set to false, the "const char *" arguments are expected to be ANSI strings.
void get_Version(CkString &out);
The version of the component, such as "4.0.0".
Methods
void ByteSwap4321(CkByteData & inOut);
Convenience method for byte swapping between little-endian byte ordering and big-endian byte ordering.
bool BytesToString(CkByteData & inData, const char * charset, CkString & outStr);
Convert a VARIANT containing a byte array to a String. Returns true for success, false for failure.
bool CkDecryptFile(const char * inFile, const char * outFile);
File-to-file decryption. There is no limit to the size of the file that can be decrypted because the component will operate in streaming mode internally. Returns true for success, false for failure.
bool CkEncryptFile(const char * inFile, const char * outFile);
File-to-file encryption. There is no limit to the size of the file that can be encrypted because the component will operate in streaming mode internally. Returns true for success, false for failure.
bool CompressBytes(const CkByteData & bData, CkByteData & out);
Memory-to-memory compression. Compresses a byte array and returns a byte array of compressed data. The compression algorithm specified by the CompressionAlgorithm property is used. Currently, the only choice is "BZIP2".
bool CompressBytesENC(const CkByteData & bData, CkString & out);
Same as CompressBytes, except an encoded string is returned. The encoding is controlled by the EncodingMode property, which can be set to "Base64", "QP" (for quoted-printable), or "Hex". Returns true for success, false for failure.
bool CompressString(const char * str, CkByteData & out);
Compresses a string and returns a byte array of the compressed data. For languages such as C#, VB.NET, Visual Basic 6, etc. the string input argument is Unicode. The Charset property controls the conversion of the Unicode string to a multibyte string before compression is applied. For example, if Charset is set to "iso-8859-1", then the input string argument is first converted from Unicode (2 bytes per char) to iso-8859-1 (1 byte per char) before compressing according to the CompressionAlgorithm property ("BZIP2"). If the Charset property is set to "unicode", then no character encoding conversion will happen, and the full Unicode string is compressed.
bool CompressStringENC(const char * str, CkString & out);
Compresses a string and returns an encoded string of the compressed data. For languages such as C#, VB.NET, Visual Basic 6, etc. the string input argument is Unicode. The Charset property controls the conversion of the Unicode string to a multibyte string before compression is applied. For example, if Charset is set to "iso-8859-1", then the input string argument is first converted from Unicode (2 bytes per char) to iso-8859-1 (1 byte per char) before compressing according to the CompressionAlgorithm property ("BZIP2"). If the Charset property is set to "unicode", then no character encoding conversion will happen, and the full Unicode string is compressed. Compressed data is typically binary data which is not a printable string. This method encodes the output compressed data to a printable string according to the EncodingMode property, which can be set to "Base64", "QP" (for quoted-printable), or "Hex". Returns true for success, false for failure.
bool CreateDetachedSignature(const char * inFile, const char * sigFile);
To be documented soon...
bool CreateP7M(const char * inFilename, const char * p7mFilename);
To be documented soon...
bool CreateP7S(const char * inFilename, const char * p7sFilename);
To be documented soon...
void Decode(const char * str, const char * encoding, CkByteData & bData);
Decode binary data from base64, hex, quoted-printable, or URL-encoding. The encoding argument can be any of the following strings: "base64", "hex", "url", or "quoted-printable".
bool DecryptBytes(const CkByteData & bData, CkByteData & out);
Decrypts a byte array and returns the unencrypted byte array. The property settings used when encrypting the data must match the settings when decrypting. Specifically, the CryptAlgorithm, CipherMode, PaddingScheme, KeyLength, IV, and SecretKey properties must match.
bool DecryptBytesENC(const char * str, CkByteData & out);
Decrypts string-encoded encrypted data and returns the unencrypted byte array. Data encrypted with EncryptBytesENC can be decrypted with this method. The property settings used when encrypting the data must match the settings when decrypting. Specifically, the EncodingMode, CryptAlgorithm, CipherMode, PaddingScheme, KeyLength, IV, and SecretKey properties must match.
bool DecryptEncoded(const char * encodedEncryptedData, CkString & outStr);
Encrypted data is passed to this method as an encoded string (base64, hex, etc.). This method first decodes the input data according to the EncodingMode property setting. It then decrypts and re-encodes using the EncodingMode setting, and returns the decrypted data in encoded string form. Returns true for success, false for failure.
bool DecryptString(const CkByteData & bData, CkString & out);
The reverse of EncryptString. Decrypts encrypted byte data and returns the original string. The property settings used when encrypting the string must match the settings when decrypting. Specifically, the Charset, CryptAlgorithm, CipherMode, PaddingScheme, KeyLength, IV, and SecretKey properties must match. Returns true for success, false for failure.
bool DecryptStringENC(const char * str, CkString & out);
The reverse of EncryptStringENC. Decrypts string-encoded encrypted data and returns the original string. The property settings used when encrypting the string must match the settings when decrypting. Specifically, the Charset, EncodingMode, CryptAlgorithm, CipherMode, PaddingScheme, KeyLength, IV, and SecretKey properties must match. Returns true for success, false for failure.
void Encode(const CkByteData & bData, const char * encoding, CkString & str);
Encode binary data to base64, hex, quoted-printable, or URL-encoding. The encoding argument can be set to any of the following strings: "base64", "hex", "quoted-printable", or "url". Returns true for success, false for failure.
bool EncryptBytes(const CkByteData & bData, CkByteData & out);
Encrypts a byte array. The minimal set of properties that should be set before encrypting are: CryptAlgorithm, SecretKey. Other properties that control encryption are: CipherMode, PaddingScheme, KeyLength, IV. When decrypting, all property settings must match otherwise garbled data is returned.
bool EncryptBytesENC(const CkByteData & bData, CkString & out);
Encrypts a byte array and returns the encrypted data as an encoded (printable) string. The minimal set of properties that should be set before encrypting are: CryptAlgorithm, SecretKey, EncodingMode. Other properties that control encryption are: CipherMode, PaddingScheme, KeyLength, IV. When decrypting, all property settings must match otherwise garbled data is returned. The encoding of the string that is returned is controlled by the EncodingMode property, which can be set to "Base64", "QP", or "Hex". Returns true for success, false for failure.
bool EncryptEncoded(const char * str, CkString & outStr);
To be documented soon...
bool EncryptString(const char * str, CkByteData & out);
Encrypts a string and returns the encrypted data as a byte array. The minimal set of properties that should be set before encrypting are: CryptAlgorithm, SecretKey, Charset. Other properties that control encryption are: CipherMode, PaddingScheme, KeyLength, IV. When decrypting, all property settings must match otherwise garbled data is returned. The Charset property controls the exact bytes that get encrypted. Languages such as VB.NET, C#, and Visual Basic work with Unicode strings, thus the input string is Unicode. If Unicode is to be encrypted (i.e. 2 bytes per character) then set the Charset property to "Unicode". To implicitly convert the string to another charset before the encryption is applied, set the Charset property to something else, such as "iso-8859-1", "Shift_JIS", "big5", "windows-1252", etc. The complete list of possible charsets is listed here:
us-ascii
unicode
unicodefffe
iso-8859-1
iso-8859-2
iso-8859-3
iso-8859-4
iso-8859-5
iso-8859-6
iso-8859-7
iso-8859-8
iso-8859-9
iso-8859-13
iso-8859-15
windows-874
windows-1250
windows-1251
windows-1252
windows-1253
windows-1254
windows-1255
windows-1256
windows-1257
windows-1258
utf-7
utf-8
utf-32
utf-32be
shift_jis
gb2312
ks_c_5601-1987
big5
iso-2022-jp
iso-2022-kr
euc-jp
euc-kr
macintosh
x-mac-japanese
x-mac-chinesetrad
x-mac-korean
x-mac-arabic
x-mac-hebrew
x-mac-greek
x-mac-cyrillic
x-mac-chinesesimp
x-mac-romanian
x-mac-ukrainian
x-mac-thai
x-mac-ce
x-mac-icelandic
x-mac-turkish
x-mac-croatian
asmo-708
dos-720
dos-862
ibm037
ibm437
ibm500
ibm737
ibm775
ibm850
ibm852
ibm855
ibm857
ibm00858
ibm860
ibm861
ibm863
ibm864
ibm865
cp866
ibm869
ibm870
cp875
koi8-r
koi8-u
bool EncryptStringENC(const char * str, CkString & out);
Encrypts a string and returns the encrypted data as an encoded (printable) string. The minimal set of properties that should be set before encrypting are: CryptAlgorithm, SecretKey, Charset, and EncodingMode. Other properties that control encryption are: CipherMode, PaddingScheme, KeyLength, IV. When decrypting (with DecryptStringENC), all property settings must match otherwise garbled data is returned. The Charset property controls the exact bytes that get encrypted. Languages such as VB.NET, C#, and Visual Basic work with Unicode strings, thus the input string is Unicode. If Unicode is to be encrypted (i.e. 2 bytes per character) then set the Charset property to "Unicode". To implicitly convert the string to another charset before the encryption is applied, set the Charset property to something else, such as "iso-8859-1", "Shift_JIS", "big5", "windows-1252", etc. (Refer to EncryptString for the complete list of charsets.) The EncodingMode property controls the encoding of the string that is returned. It can be set to "Base64", "QP", or "Hex". Returns true for success, false for failure.
void GenEncodedSecretKey(const char * password, const char * encoding, CkString & outStr);
To be documented soon. Returns true for success, false for failure.
void GenerateSecretKey(const char * password, CkByteData & out);
Hashes a string to a byte array that has the same number of bits as the current value of the KeyLength property. For example, if KeyLength is equal to 128 bits, then a 16-byte array is returned. This can be used to set the SecretKey property. In order to decrypt, the SecretKey must match exactly. To use "password-based" encryption, the password is passed to this method to generate a binary secret key that can then be assigned to the SecretKey property.
void GetEncodedIV(const char * encoding, CkString & strIV);
Returns the initialization vector as an encoded string. The encoding argument can be set to any of the following strings: "base64", "hex", "quoted-printable", or "url". Returns true for success, false for failure.
void GetEncodedKey(const char * encoding, CkString & strKey);
Returns the secret key as an encoded string. The encoding argument can be set to any of the following strings: "base64", "hex", "quoted-printable", or "url". Returns true for success, false for failure.
CkCert * GetLastCert();
Returns the last certificate used when decrypting data or verifying a signature. This is only valid when public-key encryption is used, and does not apply to symmetric algorithms such as Rijndael, Blowfish, or Twofish.
bool HashBytes(const CkByteData & bData, CkByteData & out);
Hashes a byte array. The hash algorithm to be used is controlled by the HashAlgorithm property, which can be set to "sha1", "sha384", "sha512", "md2", "md5", or "haval".
The HAVAL hash algorithm is affected by two other properties: HavalRounds and KeyLength.
The HavalRounds may have values of 3, 4, or 5.
The KeyLength may have values of 128, 160, 192, 224, or 256.
bool HashBytesENC(const CkByteData & bData, CkString & out);
Hashes a byte array and returns an encoded (printable) string of the binary hash. The hash algorithm to be used is controlled by the HashAlgorithm property, which can be set to "sha1", "sha384", "sha512", "md2", "md5", or "haval". The encoding is controlled by the EncodingMode property, which can be set to "Base64", "QP", or "Hex". Returns true for success, false for failure.
bool HashFile(const char * filename, CkByteData & out);
Hashes a file. The hash algorithm to be used is controlled by the HashAlgorithm property, which can be set to "sha1", "sha384", "sha512", "md2", "md5", or "haval". The function returns the hash bytes. Any size file is supported because the file is hashed internally in streaming mode.
The HAVAL hash algorithm is affected by two other properties: HavalRounds and KeyLength.
The HavalRounds may have values of 3, 4, or 5.
The KeyLength may have values of 128, 160, 192, 224, or 256.
bool HashFileENC(const char * filename, CkString & out);
Hashes a file. The hash algorithm to be used is controlled by the HashAlgorithm property, which can be set to "sha1", "sha384", "sha512", "md2", "md5", or "haval". The function returns the hash as a string encoded according to the EncodingMode property. Any size file is supported because the file is hashed internally in streaming mode. Returns true for success, false for failure.
bool HashString(const char * str, CkByteData & out);
Hashes a string and returns a binary hash. The hash algorithm to be used is controlled by the HashAlgorithm property, which can be set to "sha1", "sha384", "sha512", "md2", "md5", or "haval". The Charset property controls the character encoding of the string that is hashed. Languages such as VB.NET, C#, and Visual Basic work with Unicode strings. If it is desired to hash Unicode directly (2 bytes/char) then set the Charset property to "Unicode". To implicitly convert to another charset before hashing, set the Charset property to the desired charset. For example, if Charset is set to "iso-8859-1", the input string is first implicitly converted to iso-8859-1 (1 byte per character) before hashing. The full list fo supported charsets is listed in the EncryptString method description.
bool HashStringENC(const char * str, CkString & out);
Hashes a string and returns an encoded (printable) string of the binary hash. The hash algorithm to be used is controlled by the HashAlgorithm property, which can be set to "sha1", "sha384", "sha512", "md2", "md5", or "haval". The Charset property controls the character encoding of the string that is hashed. Languages such as VB.NET, C#, and Visual Basic work with Unicode strings. If it is desired to hash Unicode directly (2 bytes/char) then set the Charset property to "Unicode". To implicitly convert to another charset before hashing, set the Charset property to the desired charset. For example, if Charset is set to "iso-8859-1", the input string is first implicitly converted to iso-8859-1 (1 byte per character) before hashing. The full list of supported charsets is listed in the EncryptString method description.
The encoding of the output string is controlled by the EncodingMode property, which can be set to "Base64", "QP", or "Hex".
The HAVAL hash algorithm is affected by two other properties: HavalRounds and KeyLength.
The HavalRounds may have values of 3, 4, or 5.
The KeyLength may have values of 128, 160, 192, 224, or 256. Returns true for success, false for failure.
void HmacBytes(const CkByteData & inBytes, CkByteData & hmacOut);
Computes a keyed-Hash Message Authentication Code (HMAC or KHMAC), which is a type of message authentication code (MAC) calculated using a specific algorithm involving a cryptographic hash function in combination with a secret key. As with any MAC, it may be used to simultaneously verify both the data integrity and the authenticity of a message. Any iterative cryptographic hash function, such as MD5 or SHA-1, may be used in the calculation of an HMAC; the resulting MAC algorithm is termed HMAC-MD5 or HMAC-SHA-1 accordingly. The cryptographic strength of the HMAC depends upon the cryptographic strength of the underlying hash function, on the size and quality of the key and the size of the hash output length in bits.
The secret key is set by calling one of these methods prior to calling this method: SetHmacKeyBytes, SetHmacKeyEncoded, or SetHmacKeyString.
The hash algorithm is specified by the HashAlgorithm property.
void HmacBytesENC(const CkByteData & inBytes, CkString & encodedHmacOut);
Computes an HMAC using a secret key and hash algorithm. The result is encoded to a string using the encoding (base64, hex, etc.) specified by the EncodingMode property.
The secret key is set by calling one of these methods prior to calling this method: SetHmacKeyBytes, SetHmacKeyEncoded, or SetHmacKeyString.
The hash algorithm is specified by the HashAlgorithm property. Returns true for success, false for failure.
void HmacString(const char * inText, CkByteData & hmacOut);
Computes an HMAC using a secret key and hash algorithm.
The secret key is set by calling one of these methods prior to calling this method: SetHmacKeyBytes, SetHmacKeyEncoded, or SetHmacKeyString.
The hash algorithm is specified by the HashAlgorithm property.
void HmacStringENC(const char * inText, CkString & encodedHmacOut);
Computes an HMAC using a secret key and hash algorithm. The result is encoded to a string using the encoding (base64, hex, etc.) specified by the EncodingMode property.
The secret key is set by calling one of these methods prior to calling this method: SetHmacKeyBytes, SetHmacKeyEncoded, or SetHmacKeyString.
The hash algorithm is specified by the HashAlgorithm property. Returns true for success, false for failure.
bool InflateBytes(const CkByteData & bData, CkByteData & out);
The opposite of CompressBytes.
bool InflateBytesENC(const char * str, CkByteData & out);
The opposite of CompressBytesENC. The EncodingMode and CompressionAlgorithm properties should match what was used when compressing.
bool InflateString(const CkByteData & bData, CkString & out);
The opposite of CompressString. The Charset and CompressionAlgorithm properties should match what was used when compressing. Returns true for success, false for failure.
bool InflateStringENC(const char * str, CkString & out);
The opposite of CompressStringENC. The Charset, EncodingMode, and CompressionAlgorithm properties should match what was used when compressing. Returns true for success, false for failure.
bool IsUnlocked();
Returns true if the component is unlocked.
bool OpaqueSignBytes(const CkByteData & bData, CkByteData & out);
Digitally signs a byte array and returns the opaque digital signature. A certificate must be set by calling SetSigningCert prior to calling this method.
bool OpaqueSignBytesENC(const CkByteData & bData, CkString & out);
Digitally signs a byte array and returns the opaque digital signature encoded as a printable string. A certificate must be set by calling SetSigningCert prior to calling this method. The EncodingMode property controls the output encoding, which can be "Base64", "QP", or "Hex". Returns true for success, false for failure.
bool OpaqueSignString(const char * str, CkByteData & out);
Digitally signs a string and returns the opaque digital signature. A certificate must be set by calling SetSigningCert prior to calling this method. The Charset property controls the character encoding of the string that is signed. (Languages such as VB.NET, C#, and Visual Basic work with Unicode strings.) To sign Unicode data (2 bytes per char), set the Charset property to "Unicode". To implicitly convert the string to a mutlibyte charset such as "iso-8859-1", "Shift_JIS", "utf-8", or something else, then set the Charset property to the name of the charset before signing. The complete list of charsets is listed in the EncryptString method description.
bool OpaqueSignStringENC(const char * str, CkString & out);
Digitally signs a string and returns the opaque digital signature as an encoded string. A certificate must be set by calling SetSigningCert prior to calling this method. The Charset property controls the character encoding of the string that is signed. (Languages such as VB.NET, C#, and Visual Basic work with Unicode strings.) To sign Unicode data (2 bytes per char), set the Charset property to "Unicode". To implicitly convert the string to a mutlibyte charset such as "iso-8859-1", "Shift_JIS", "utf-8", or something else, then set the Charset property to the name of the charset before signing. The complete list of charsets is listed in the EncryptString method description. The encoding of the output string is controlled by the EncodingMode property, which can be set to "Base64", "QP", or "Hex". Returns true for success, false for failure.
bool OpaqueVerifyBytes(const CkByteData & p7s, CkByteData & original);
Verifies an opaque signature and returns the original data. If the signature verification fails, the returned data will be 0 bytes in length.
bool OpaqueVerifyBytesENC(const char * p7s, CkByteData & original);
Verifies an opaque signature (encoded in string form) and returns the original data. If the signature verification fails, the returned data will be 0 bytes in length.
bool OpaqueVerifyString(const CkByteData & p7s, CkString & original);
Verifies an opaque signature and returns the original string. If the signature verification fails, the returned string will be 0 characters in length. Returns true for success, false for failure.
bool OpaqueVerifyStringENC(const char * p7s, CkString & original);
Verifies an opaque signature (encoded in string form) and returns the original data string. If the signature verification fails, the returned string will be 0 characters in length. Returns true for success, false for failure.
void RandomizeIV();
Sets the initialization vector to a random value.
void RandomizeKey();
Sets the secret key to a random value.
bool ReEncode(const char * data, const char * fromEncoding, const char * toEncoding, CkString & outStr);
To be documented soon...
bool ReadFile(const char * filename, CkByteData & outBytes);
Convenience method to read an entire file and return as a byte array.
bool SaveLastError(const char * filename);
Saves the last error information to an XML formatted file.
bool SetCSP(const CkCSP * csp);
Allows for any Cryptographic Service Provider to be used with public-key encryption.
bool SetCSP(const CkCSP & csp);
Allows for any Cryptographic Service Provider to be used with public-key encryption.
bool SetDecryptCert(CkCert & cert);
To be documented soon...
bool SetDecryptCert2(const CkCert & cert, CkPrivateKey & key);
To be documented soon...
void SetEncodedIV(const char * ivStr, const char * encoding);
Sets the initialization vector from an encoded string. The encoding argument can be set to any of the following strings: "base64", "hex", "quoted-printable", or "url".
void SetEncodedKey(const char * keyStr, const char * encoding);
Sets the secret key from an encoded string. The encoding argument can be set to any of the following strings: "base64", "hex", "quoted-printable", or "url".
void SetEncryptCert(const CkCert * cert);
Tells the encryption library to use a specific digital certificate for public-key encryption.
void SetEncryptCert(const CkCert & cert);
Tells the encryption library to use a specific digital certificate for public-key encryption.
void SetHmacKeyBytes(const CkByteData & keyBytes);
Sets the secret key to be used for one of the HMAC methods.
void SetHmacKeyEncoded(const char * key, const char * encoding);
Sets the secret key to be used for one of the HMAC methods. The encoding can be set to any of the following strings: "base64", "hex", "quoted-printable", or "url".
void SetHmacKeyString(const char * key);
Sets the secret key to be used for one of the HMAC methods.
void SetIV(const unsigned char * ivData, int numBytes);
To be documented soon...
void SetSecretKey(const unsigned char * keyData, int numBytes);
To be documented soon...
void SetSecretKeyViaPassword(const char * password);
Accepts a password string and (internally) generates a binary secret key of the appropriate bit length and sets the SecretKey property. This method should only be used if you are using Chilkat for both encryption and decryption because the password-to-secret-key algorithm would need to be identical for the decryption to match the encryption.
void SetSigningCert(const CkCert * cert);
Tells the encryption library to use a specific digital certificate for digital signature creation.
void SetSigningCert(const CkCert & cert);
Tells the encryption library to use a specific digital certificate for digital signature creation.
bool SetSigningCert2(const CkCert & cert, CkPrivateKey & key);
To be documented soon...
void SetVerifyCert(const CkCert * cert);
Sets the digital certificate to be used in verifying a signature.
void SetVerifyCert(const CkCert & cert);
Sets the digital certificate to be used in verifying a signature.
bool SignBytes(const CkByteData & bData, CkByteData & out);
Digitally signs a byte array and returns the detached digital signature. A certificate must be set by calling SetSigningCert prior to calling this method.
bool SignBytesENC(const CkByteData & bData, CkString & out);
Digitally signs a byte array and returns the detached digital signature encoded as a printable string. A certificate must be set by calling SetSigningCert prior to calling this method. The EncodingMode property controls the output encoding, which can be "Base64", "QP", or "Hex". Returns true for success, false for failure.
bool SignString(const char * str, CkByteData & out);
Digitally signs a string and returns the detached digital signature. A certificate must be set by calling SetSigningCert prior to calling this method. The Charset property controls the character encoding of the string that is signed. (Languages such as VB.NET, C#, and Visual Basic work with Unicode strings.) To sign Unicode data (2 bytes per char), set the Charset property to "Unicode". To implicitly convert the string to a mutlibyte charset such as "iso-8859-1", "Shift_JIS", "utf-8", or something else, then set the Charset property to the name of the charset before signing. The complete list of charsets is listed in the EncryptString method description.
bool SignStringENC(const char * str, CkString & out);
Digitally signs a string and returns the PKCS7 detached digital signature as an encoded string. A certificate must be set by calling SetSigningCert prior to calling this method. The Charset property controls the character encoding of the string that is signed. (Languages such as VB.NET, C#, and Visual Basic work with Unicode strings.) To sign Unicode data (2 bytes per char), set the Charset property to "Unicode". To implicitly convert the string to a mutlibyte charset such as "iso-8859-1", "Shift_JIS", "utf-8", or something else, then set the Charset property to the name of the charset before signing. The complete list of charsets is listed in the EncryptString method description. The encoding of the output string is controlled by the EncodingMode property, which can be set to "Base64", "QP", or "Hex". Returns true for success, false for failure.
bool StringToBytes(const char * inStr, const char * charset, CkByteData & outBytes);
Convert a String to a VARIANT containing a byte array where the characters are encoded according to the charset specified.
void TrimEndingWith(const char * inStr, const char * ending, CkString & outStr);
Trim a string ending with a specific substring until the string no longer ends with that substring. Returns true for success, false for failure.
bool UnlockComponent(const char * unlockCode);
Unlocks the component. This must be called once prior to calling any other method.
bool VerifyBytes(const CkByteData & bData1, const CkByteData & sigData);
Verifies a byte array against a digital signature and returns true if the byte array is unaltered.
bool VerifyBytesENC(const CkByteData & bData, const char * encodedSig);
Verifies a byte array against a string-encoded digital signature and returns true if the byte array is unaltered. This method can be used to verify a signature produced by SignBytesENC. The EncodingMode property must be set prior to calling to match the encoding of the digital signature string ("Base64", "QP", or "Hex").
bool VerifyDetachedSignature(const char * inFile, const char * sigFile);
To be documented soon...
bool VerifyP7M(const char * p7mFilename, const char * outFilename);
To be documented soon...
bool VerifyP7S(const char * inFilename, const char * p7sFilename);
To be documented soon...
bool VerifyString(const char * str, const CkByteData & sigData);
Verifies a string against a binary digital signature and returns true if the string is unaltered. This method can be used to verify a signature produced by SignString. The Charset property must be set to the charset that was used when creating the signature.
bool VerifyStringENC(const char * str, const char * encodedSig);
Verifies a string against a string-encoded digital signature and returns true if the string is unaltered. This method can be used to verify a signature produced by SignStringENC. The Charset and EncodingMode properties must be set to the same values that were used when creating the signature.
bool WriteFile(const char * filename, CkByteData & fileData);
Convenience method to write an entire byte array to a file.
const char * bytesToString(CkByteData & inData, const char * charset);
Convert a VARIANT containing a byte array to a String.
const char * charset();
Controls the character encoding of the text encrypted, signed, hashed or compressed. This property is relevant wherever strings are used as inputs or outputs. When working with strings, it is important to know the exact bytes that are being encrypted/hashed/signed/compressed. This is critical when interoperating with other systems. If your application is sending an encrypted string to another system that will decrypt it, you will need to know the encoding of the string that is expected on the receiving end (after decryption). If you pass Unicode data (2 byte per character) to the encryptor, subsequent decryption will reproduce the original Unicode. However, it may be that your program works with Unicode strings, but the recipient of the encrypted data works with iso-8859-1 strings. In such a case, setting the Charset property to "iso-8859-1" causes the character data to be automatically converted to the Charset before being encrypted (or compressed, or hashed, or signed). The set of valid charsets is listed below:
ANSI
us-ascii
unicode
unicodefffe
iso-8859-1
iso-8859-2
iso-8859-3
iso-8859-4
iso-8859-5
iso-8859-6
iso-8859-7
iso-8859-8
iso-8859-9
iso-8859-13
iso-8859-15
windows-874
windows-1250
windows-1251
windows-1252
windows-1253
windows-1254
windows-1255
windows-1256
windows-1257
windows-1258
utf-7
utf-8
utf-32
utf-32be
shift_jis
gb2312
ks_c_5601-1987
big5
iso-2022-jp
iso-2022-kr
euc-jp
euc-kr
macintosh
x-mac-japanese
x-mac-chinesetrad
x-mac-korean
x-mac-arabic
x-mac-hebrew
x-mac-greek
x-mac-cyrillic
x-mac-chinesesimp
x-mac-romanian
x-mac-ukrainian
x-mac-thai
x-mac-ce
x-mac-icelandic
x-mac-turkish
x-mac-croatian
asmo-708
dos-720
dos-862
ibm037
ibm437
ibm500
ibm737
ibm775
ibm850
ibm852
ibm855
ibm857
ibm00858
ibm860
ibm861
ibm863
ibm864
ibm865
cp866
ibm869
ibm870
cp875
koi8-r
koi8-u
const char * cipherMode();
Controls the cipher mode for Rijndael and Twofish encryption. Possible values are "CBC" (the default) and "ECB". CBC is an acronym for Cipher Block Chaining, ECB is an acronym for Electronic CookBook.
const char * compressBytesENC(const CkByteData & bData);
Same as CompressBytes, except an encoded string is returned. The encoding is controlled by the EncodingMode property, which can be set to "Base64", "QP" (for quoted-printable), or "Hex".
const char * compressStringENC(const char * str);
Compresses a string and returns an encoded string of the compressed data. For languages such as C#, VB.NET, Visual Basic 6, etc. the string input argument is Unicode. The Charset property controls the conversion of the Unicode string to a multibyte string before compression is applied. For example, if Charset is set to "iso-8859-1", then the input string argument is first converted from Unicode (2 bytes per char) to iso-8859-1 (1 byte per char) before compressing according to the CompressionAlgorithm property ("BZIP2"). If the Charset property is set to "unicode", then no character encoding conversion will happen, and the full Unicode string is compressed. Compressed data is typically binary data which is not a printable string. This method encodes the output compressed data to a printable string according to the EncodingMode property, which can be set to "Base64", "QP" (for quoted-printable), or "Hex".
const char * compressionAlgorithm();
Selects the compression algorithm to be used. Currently, the only valid setting is "BZIP2".
const char * cryptAlgorithm();
Selects the encryption algorithm for encrypting and decrypting. Possible values are: "pki", "aes", "rijndael", "blowfish", "blowfish2", "des", "rc2", "arc4", and "twofish". The "pki" encryption algorithm isn't a specific algorithm, but instead tells the component to encrypt/decrypt using public-key encryption with digital certificates. The other choices, rijndael, blowfish, and twofish, are symmetric encryption algorithms that do not involve digital certificates and public/private keys.
The original Chilkat implementation of Blowfish has a 4321 byte-swapping issue (the results are 4321 byte-swapped). The new implementation ("blowfish2") does not byte swap. This should be used for compatibility with other Blowfish software.
const char * decryptEncoded(const char * encodedEncryptedData);
Encrypted data is passed to this method as an encoded string (base64, hex, etc.). This method first decodes the input data according to the EncodingMode property setting. It then decrypts and re-encodes using the EncodingMode setting, and returns the decrypted data in encoded string form.
const char * decryptString(const CkByteData & bData);
The reverse of EncryptString. Decrypts encrypted byte data and returns the original string. The property settings used when encrypting the string must match the settings when decrypting. Specifically, the Charset, CryptAlgorithm, CipherMode, PaddingScheme, KeyLength, IV, and SecretKey properties must match.
const char * decryptStringENC(const char * str);
The reverse of EncryptStringENC. Decrypts string-encoded encrypted data and returns the original string. The property settings used when encrypting the string must match the settings when decrypting. Specifically, the Charset, EncodingMode, CryptAlgorithm, CipherMode, PaddingScheme, KeyLength, IV, and SecretKey properties must match.
const char * encode(const CkByteData & bData, const char * encoding);
Encode binary data to base64, hex, quoted-printable, or URL-encoding. The encoding argument can be set to any of the following strings: "base64", "hex", "quoted-printable", or "url".
const char * encodeBytes(const unsigned char * byteData, int numBytes, const char * encoding);
To be documented soon...
const char * encodeBytes(const char * byteData, int numBytes, const char * encoding);
To be documented soon...
const char * encodingMode();
Controls the encoding of binary data to a printable string for many methods. The valid modes are "Base64", "QP" (for quoted-printable), "URL" (for url-encoding), and "Hex".
const char * encryptBytesENC(const CkByteData & bData);
Encrypts a byte array and returns the encrypted data as an encoded (printable) string. The minimal set of properties that should be set before encrypting are: CryptAlgorithm, SecretKey, EncodingMode. Other properties that control encryption are: CipherMode, PaddingScheme, KeyLength, IV. When decrypting, all property settings must match otherwise garbled data is returned. The encoding of the string that is returned is controlled by the EncodingMode property, which can be set to "Base64", "QP", or "Hex".
const char * encryptEncoded(const char * str);
To be documented soon...
const char * encryptStringENC(const char * str);
Encrypts a string and returns the encrypted data as an encoded (printable) string. The minimal set of properties that should be set before encrypting are: CryptAlgorithm, SecretKey, Charset, and EncodingMode. Other properties that control encryption are: CipherMode, PaddingScheme, KeyLength, IV. When decrypting (with DecryptStringENC), all property settings must match otherwise garbled data is returned. The Charset property controls the exact bytes that get encrypted. Languages such as VB.NET, C#, and Visual Basic work with Unicode strings, thus the input string is Unicode. If Unicode is to be encrypted (i.e. 2 bytes per character) then set the Charset property to "Unicode". To implicitly convert the string to another charset before the encryption is applied, set the Charset property to something else, such as "iso-8859-1", "Shift_JIS", "big5", "windows-1252", etc. (Refer to EncryptString for the complete list of charsets.) The EncodingMode property controls the encoding of the string that is returned. It can be set to "Base64", "QP", or "Hex".
const char * genEncodedSecretKey(const char * password, const char * encoding);
To be documented soon.
const char * getEncodedIV(const char * encoding);
Returns the initialization vector as an encoded string. The encoding argument can be set to any of the following strings: "base64", "hex", "quoted-printable", or "url".
const char * getEncodedKey(const char * encoding);
Returns the secret key as an encoded string. The encoding argument can be set to any of the following strings: "base64", "hex", "quoted-printable", or "url".
const char * hashAlgorithm();
Selects the hash algorithm used by methods that create hashes. The valid choices are "sha1", "sha256", "sha384", "sha512", "md2", "md5", and "haval".
const char * hashBytesENC(const CkByteData & bData);
Hashes a byte array and returns an encoded (printable) string of the binary hash. The hash algorithm to be used is controlled by the HashAlgorithm property, which can be set to "sha1", "sha384", "sha512", "md2", "md5", or "haval". The encoding is controlled by the EncodingMode property, which can be set to "Base64", "QP", or "Hex".
const char * hashFileENC(const char * filename);
Hashes a file. The hash algorithm to be used is controlled by the HashAlgorithm property, which can be set to "sha1", "sha384", "sha512", "md2", "md5", or "haval". The function returns the hash as a string encoded according to the EncodingMode property. Any size file is supported because the file is hashed internally in streaming mode.
const char * hashStringENC(const char * str);
Hashes a string and returns an encoded (printable) string of the binary hash. The hash algorithm to be used is controlled by the HashAlgorithm property, which can be set to "sha1", "sha384", "sha512", "md2", "md5", or "haval". The Charset property controls the character encoding of the string that is hashed. Languages such as VB.NET, C#, and Visual Basic work with Unicode strings. If it is desired to hash Unicode directly (2 bytes/char) then set the Charset property to "Unicode". To implicitly convert to another charset before hashing, set the Charset property to the desired charset. For example, if Charset is set to "iso-8859-1", the input string is first implicitly converted to iso-8859-1 (1 byte per character) before hashing. The full list of supported charsets is listed in the EncryptString method description.
The encoding of the output string is controlled by the EncodingMode property, which can be set to "Base64", "QP", or "Hex".
The HAVAL hash algorithm is affected by two other properties: HavalRounds and KeyLength.
The HavalRounds may have values of 3, 4, or 5.
The KeyLength may have values of 128, 160, 192, 224, or 256.
const char * hmacBytesENC(const CkByteData & inBytes);
Computes an HMAC using a secret key and hash algorithm. The result is encoded to a string using the encoding (base64, hex, etc.) specified by the EncodingMode property.
The secret key is set by calling one of these methods prior to calling this method: SetHmacKeyBytes, SetHmacKeyEncoded, or SetHmacKeyString.
The hash algorithm is specified by the HashAlgorithm property.
const char * hmacStringENC(const char * inText);
Computes an HMAC using a secret key and hash algorithm. The result is encoded to a string using the encoding (base64, hex, etc.) specified by the EncodingMode property.
The secret key is set by calling one of these methods prior to calling this method: SetHmacKeyBytes, SetHmacKeyEncoded, or SetHmacKeyString.
The hash algorithm is specified by the HashAlgorithm property.
const char * inflateString(const CkByteData & bData);
The opposite of CompressString. The Charset and CompressionAlgorithm properties should match what was used when compressing.
const char * inflateStringENC(const char * str);
The opposite of CompressStringENC. The Charset, EncodingMode, and CompressionAlgorithm properties should match what was used when compressing.
const char * lastErrorHtml();
Error information in HTML format for the last method called.
const char * lastErrorText();
Error information in plain-text format for the last method called.
const char * lastErrorXml();
Error information in XML format for the last method called.
const char * opaqueSignBytesENC(const CkByteData & bData);
Digitally signs a byte array and returns the opaque digital signature encoded as a printable string. A certificate must be set by calling SetSigningCert prior to calling this method. The EncodingMode property controls the output encoding, which can be "Base64", "QP", or "Hex".
const char * opaqueSignStringENC(const char * str);
Digitally signs a string and returns the opaque digital signature as an encoded string. A certificate must be set by calling SetSigningCert prior to calling this method. The Charset property controls the character encoding of the string that is signed. (Languages such as VB.NET, C#, and Visual Basic work with Unicode strings.) To sign Unicode data (2 bytes per char), set the Charset property to "Unicode". To implicitly convert the string to a mutlibyte charset such as "iso-8859-1", "Shift_JIS", "utf-8", or something else, then set the Charset property to the name of the charset before signing. The complete list of charsets is listed in the EncryptString method description. The encoding of the output string is controlled by the EncodingMode property, which can be set to "Base64", "QP", or "Hex".
const char * opaqueVerifyString(const CkByteData & p7s);
Verifies an opaque signature and returns the original string. If the signature verification fails, the returned string will be 0 characters in length.
const char * opaqueVerifyStringENC(const char * p7s);
Verifies an opaque signature (encoded in string form) and returns the original data string. If the signature verification fails, the returned string will be 0 characters in length.
const char * reEncode(const char * data, const char * fromEncoding, const char * toEncoding);
To be documented soon...
const char * signBytesENC(const CkByteData & bData);
Digitally signs a byte array and returns the detached digital signature encoded as a printable string. A certificate must be set by calling SetSigningCert prior to calling this method. The EncodingMode property controls the output encoding, which can be "Base64", "QP", or "Hex".
const char * signStringENC(const char * str);
Digitally signs a string and returns the PKCS7 detached digital signature as an encoded string. A certificate must be set by calling SetSigningCert prior to calling this method. The Charset property controls the character encoding of the string that is signed. (Languages such as VB.NET, C#, and Visual Basic work with Unicode strings.) To sign Unicode data (2 bytes per char), set the Charset property to "Unicode". To implicitly convert the string to a mutlibyte charset such as "iso-8859-1", "Shift_JIS", "utf-8", or something else, then set the Charset property to the name of the charset before signing. The complete list of charsets is listed in the EncryptString method description. The encoding of the output string is controlled by the EncodingMode property, which can be set to "Base64", "QP", or "Hex".
const char * trimEndingWith(const char * inStr, const char * ending);
Trim a string ending with a specific substring until the string no longer ends with that substring.
const char * version();
The version of the component, such as "4.0.0".
|