Xojo Conferences
XDCMay2019MiamiUSA

Platforms to show: All Mac Windows Linux Cross-Platform

CCCryptorMBS class

Type Topic Plugin Version macOS Windows Linux Console & Web iOS
class Encryption and Hash MBS MacOSX Plugin 11.3 Yes No No Yes, macOS only No
Function: Generic interface for symmetric encryption.
Example:
// initialize
dim h as new CCCryptorMBS(CCCryptorMBS.kCCEncrypt, CCCryptorMBS.kCCAlgorithmAES128, 0, "Hello12312345678")

if h.Lasterror<>0 then break

// destination memoryblock

dim m as new MemoryBlock(100)
dim Position as Uint64 = 0
dim BytesLeft as UInt64 = m.Size

// add a few bytes
dim q as UInt64 = 0

h.Update "Hello World!1234", m, BytesLeft, q
if h.Lasterror<>0 then break

Position = Position + q
BytesLeft = BytesLeft - q

// now finalize:
q = 0

dim dp as ptr = m.AddressPtrMBS(Position)

h.Final dp, BytesLeft, q
if h.Lasterror<>0 then break

Position = Position + q
BytesLeft = BytesLeft - q

// and show result
dim d as string = m.StringValue(0, Position)
MsgBox EncodingToHexMBS(d)
Notes:
This interface provides access to a number of symmetric encryption algorithms. Symmetric encryption algorithms come in two "flavors" - block ciphers, and stream ciphers. Block ciphers process data (while both encrypting and decrypting) in discrete chunks of data called blocks; stream ciphers operate on arbitrary sized data.

The object declared in this interface, CCCryptorMBS, provides access to both block ciphers and stream ciphers with the same API; however some options are available for block ciphers that do not apply to stream ciphers.

The general operation of a CCCryptor is: initialize it with raw key data and other optional fields with Constructor(); process input data via one or more calls to Update(), each of which may result in output data being written to caller-supplied memory; and obtain possible remaining output data with Final(). The CCCryptor is disposed of via Destructor(), or it can be reused (with the same key data as provided to Constructor()) by calling Reset().

One option for block ciphers is padding, as defined in PKCS7; when padding is enabled, the total amount of data encrypted does not have to be an even multiple of the block size, and the actual length of plaintext is calculated during decryption.

Another option for block ciphers is Cipher Block Chaining, known as CBC mode. When using CBC mode, an Initialization Vector (IV) is provided along with the key when starting an encrypt or decrypt operation. If CBC mode is selected and no IV is provided, an IV of all zeroes will be used.

CCCryptorMBS also implements block bufferring, so that individual calls to Update() do not have to provide data whose length is aligned to the block size. (If padding is disabled, encrypting with block ciphers does require that the *total* length of data input to Update() call(s) be aligned to the block size.)

A given CCCryptorMBS can only be used by one thread at a time; multiple threads can use safely different CCCryptors at the same time.

This class uses the CommonCrypto interface which is available on Mac OS X 10.5 or newer and also on iOS. So you can use it to get the same results on both operation systems. Also as you simply use Apple provided encryption, you don't need to apply for an export license for this classes here.

Feedback, Comments & Corrections

  • 2 properties
  • 7 methods
    • method Constructor(operation as Integer, Algorithm as Integer, options as Integer, key as Ptr, keyLength as UInt64, iv as Ptr = nil)
    • method Constructor(operation as Integer, Algorithm as Integer, options as Integer, key as String, iv as Ptr = nil)
    • method Final(DataOut as Ptr, dataOutAvailable as UInt64, byref dataOutMoved as UInt64)
    • method GetOutputLength(inputLength as UInt64, Final as Boolean = true) as UInt64
    • method Reset(iv as Ptr = nil)
    • method Update(dataIn as Ptr, dataInLength as UInt64, dataOut as Ptr, dataOutAvailable as UInt64, byref dataOutMoved as UInt64)
    • method Update(dataIn as String, dataOut as Ptr, dataOutAvailable as UInt64, byref dataOutMoved as UInt64)
  • 2 shared methods
    • shared method Crypt(Operation as Integer, Algorithm as Integer, Options as Integer, key as Ptr, KeyLength as UInt64, IV as Ptr, DataIn as Ptr, DataInLength as UInt64, DataOut as Ptr, DataOutAvailable as UInt64, byref DataOutMoved as UInt64) as Integer
    • shared method Crypt(Operation as Integer, Algorithm as Integer, Options as Integer, key as string, IV as Ptr, DataIn as string, byref DataOut as string) as Integer
  • 33 constants

Encryption Algorithms Constants.

Constant Value Description
kCCAlgorithm3DES 2 Triple-DES, three key, EDE configuration
kCCAlgorithmAES128 0 Advanced Encryption Standard, 128-bit block
kCCAlgorithmCAST 3 CAST
kCCAlgorithmDES 1 Data Encryption Standard
kCCAlgorithmRC2 5 RC2 stream cipher
kCCAlgorithmRC4 4 RC4 stream cipher

Error codes.

Constant Value Description
kCCAlignmentError -4303 Input size was not aligned properly.
kCCBufferTooSmall -4301 Insufficent buffer provided for specified operation.
kCCDecodeError -4304 Input data did not decode or decrypt properly.
kCCMemoryFailure -4302 Memory allocation failure.
kCCParamError -4300 Illegal parameter value.
kCCSuccess 0 Operation completed normally.
kCCUnimplemented -4305 Function not implemented for the current algorithm.

Block Size Constants.

Constant Value Description
kCCBlockSize3DES 8 Triple DES block size.
kCCBlockSizeAES128 16 AES block size (currently, only 128-bit blocks are supported).
kCCBlockSizeCAST 8 CAST block size.
kCCBlockSizeDES 8 DES block size.
kCCBlockSizeRC2 8 RC2 block size.

Operation Modes

Constant Value Description
kCCDecrypt 1 Symmetric decryption.
kCCEncrypt 0 Symmetric encryption.

Key Size Constants

Constant Value Description
kCCKeySize3DES 24 Triple DES key size.
DES and TripleDES have fixed key sizes.
kCCKeySizeAES128 16 128 bit AES key size.
AES has three discrete key sizes.
kCCKeySizeAES192 24 192 bit AES key size.
AES has three discrete key sizes.
kCCKeySizeAES256 32 256 bit AES key size.
AES has three discrete key sizes.
kCCKeySizeDES 8 DES key size.
DES and TripleDES have fixed key sizes.
kCCKeySizeMaxCAST 16 CAST maximum key size.
CAST and RC4 have variable key sizes.
kCCKeySizeMaxRC2 128 RC2 maximum key size.
CAST and RC4 have variable key sizes.
kCCKeySizeMaxRC4 512 RC4 maximum key size.
CAST and RC4 have variable key sizes.
kCCKeySizeMinCAST 5 CAST minimum key size.
CAST and RC4 have variable key sizes.
kCCKeySizeMinRC2 1 RC2 minimum key size.
CAST and RC4 have variable key sizes.
kCCKeySizeMinRC4 1 RC4 minimum key size.
CAST and RC4 have variable key sizes.

Option Constants

Constant Value Description
kCCOptionECBMode 2 Electronic Code Book Mode. Default is CBC.
Stream ciphers currently have no options
kCCOptionPKCS7Padding 1 Perform PKCS7 padding.
Stream ciphers currently have no options

This class has no sub classes.


The items on this page are in the following plugins: MBS MacOSX Plugin.


CBUUIDMBS   -   CCHMacMBS




Links
MBS FileMaker tutorial videos