MBS Xojo Encryption Kit 1.0

Class CommonCryptorMB

Sub Constructor(Operation as CommonCryptoMB.CryptoOperation, Algorithm as CommonCryptoMB.CryptoAlgorithm, Options as Integer, key as MemoryBlock, iv as MemoryBlock = nil) // Create a cryptographic context. // // op Defines the basic operation: Encrypt or Decrypt. // alg Defines the algorithm. // options A word of flags defining options. can be 0, kCCOptionPKCS7Padding and/or kCCOptionECBMode. // key Raw key material. Must be appropriate in length for the selected operation and algorithm. Some algorithms provide for varying key lengths. // iv Initialization vector, optional. Used by block ciphers when Cipher Block Chaining (CBC) mode is enabled. If present, must be the same length as the selected algorithm's block size. // If CBC mode is selected (by the absence of the kCCOptionECBMode bit in the options flags) and no // IV is present, a NULL (all zeroes) IV will be used. // This parameter is ignored if ECB mode is used or if a stream cipher algorithm is selected. // Can raise exception with error returns are kCCParamError and kCCMemoryFailure. End

Sub Constructor(Operation as CommonCryptoMB.CryptoOperation, Algorithm as CommonCryptoMB.CryptoAlgorithm, Options as Integer, key as Xojo.Core.MemoryBlock, iv as xojo.core.MemoryBlock = nil) // Create a cryptographic context. // // op Defines the basic operation: Encrypt or Decrypt. // alg Defines the algorithm. // options A word of flags defining options. can be 0, kCCOptionPKCS7Padding and/or kCCOptionECBMode. // key Raw key material. Must be appropriate in length for the selected operation and algorithm. Some algorithms provide for varying key lengths. // iv Initialization vector, optional. Used by block ciphers when Cipher Block Chaining (CBC) mode is enabled. If present, must be the same length as the selected algorithm's block size. // If CBC mode is selected (by the absence of the kCCOptionECBMode bit in the options flags) and no // IV is present, a NULL (all zeroes) IV will be used. // This parameter is ignored if ECB mode is used or if a stream cipher algorithm is selected. // Can raise exception with error returns are kCCParamError and kCCMemoryFailure. End

Sub Constructor(Operation as CommonCryptoMB.CryptoOperation, Algorithm as CommonCryptoMB.CryptoAlgorithm, Options as Integer, key as string, iv as MemoryBlock = nil) // Create a cryptographic context. // // op Defines the basic operation: Encrypt or Decrypt. // alg Defines the algorithm. // options A word of flags defining options. can be 0, kCCOptionPKCS7Padding and/or kCCOptionECBMode. // key Raw key material. Must be appropriate in length for the selected operation and algorithm. Some algorithms provide for varying key lengths. // iv Initialization vector, optional. Used by block ciphers when Cipher Block Chaining (CBC) mode is enabled. If present, must be the same length as the selected algorithm's block size. // If CBC mode is selected (by the absence of the kCCOptionECBMode bit in the options flags) and no // IV is present, a NULL (all zeroes) IV will be used. // This parameter is ignored if ECB mode is used or if a stream cipher algorithm is selected. // Can raise exception with error returns are kCCParamError and kCCMemoryFailure. // convert string in current encoding to MemoryBlock End

Sub Constructor(Operation as CommonCryptoMB.CryptoOperation, Algorithm as CommonCryptoMB.CryptoAlgorithm, Options as Integer, key as text, iv as xojo.core.MemoryBlock = nil) // Create a cryptographic context. // // op Defines the basic operation: Encrypt or Decrypt. // alg Defines the algorithm. // options A word of flags defining options. can be 0, kCCOptionPKCS7Padding and/or kCCOptionECBMode. // key Raw key material. Must be appropriate in length for the selected operation and algorithm. Some algorithms provide for varying key lengths. // iv Initialization vector, optional. Used by block ciphers when Cipher Block Chaining (CBC) mode is enabled. If present, must be the same length as the selected algorithm's block size. // If CBC mode is selected (by the absence of the kCCOptionECBMode bit in the options flags) and no // IV is present, a NULL (all zeroes) IV will be used. // This parameter is ignored if ECB mode is used or if a stream cipher algorithm is selected. // Can raise exception with error returns are kCCParamError and kCCMemoryFailure. End

Sub Constructor(Operation as CommonCryptoMB.CryptoOperation, Mode as CommonCryptoMB.CryptoMode, Algorithm as CommonCryptoMB.CryptoAlgorithm, Padding as CommonCryptoMB.CryptoPadding, key as MemoryBlock, Tweak as Memoryblock = nil, iv as MemoryBlock = nil, NumRounds as Integer = 0, Options as Integer = 0) // Create a cryptographic context. // Operation Defines the basic operation: Encrypt or Decrypt. // mode Specifies the cipher mode to use for operations. // Algorithm Defines the algorithm. // padding Specifies the padding to use. // iv Initialization vector, optional. Used by block ciphers with the following modes: // // Cipher Block Chaining (CBC) // Cipher Feedback (CFB and CFB8) // Output Feedback (OFB) // Counter (CTR) // // If present, must be the same length as the selected // algorithm's block size. If no IV is present, a NULL // (all zeroes) IV will be used. // This parameter is ignored if ECB mode is used or // if a stream cipher algorithm is selected. // key Raw key material, length keyLength bytes. Key length must be appropriate // for the selected operation and algorithm. Some algorithms provide for varying key lengths. // tweak Raw key material, length keyLength bytes. Used for the tweak key in XEX-based Tweaked CodeBook (XTS) mode. // Length of tweak key material must be appropriate for the selected operation and algorithm. Some // algorithms provide for varying key lengths. For XTS this is the same length as the encryption key. // // numRounds The number of rounds of the cipher to use. 0 uses the default. // options A word of flags defining options. See discussion // for the CCModeOptions type. // // Can raise exception for with errors kCCParamError and kCCMemoryFailure. End

Sub Constructor(Operation as CommonCryptoMB.CryptoOperation, Mode as CommonCryptoMB.CryptoMode, Algorithm as CommonCryptoMB.CryptoAlgorithm, Padding as CommonCryptoMB.CryptoPadding, key as Xojo.Core.MemoryBlock, Tweak as xojo.core.Memoryblock = nil, iv as xojo.core.MemoryBlock = nil, NumRounds as Integer = 0, Options as Integer = 0) // Create a cryptographic context. // Operation Defines the basic operation: Encrypt or Decrypt. // mode Specifies the cipher mode to use for operations. // Algorithm Defines the algorithm. // padding Specifies the padding to use. // iv Initialization vector, optional. Used by block ciphers with the following modes: // // Cipher Block Chaining (CBC) // Cipher Feedback (CFB and CFB8) // Output Feedback (OFB) // Counter (CTR) // // If present, must be the same length as the selected // algorithm's block size. If no IV is present, a NULL // (all zeroes) IV will be used. // This parameter is ignored if ECB mode is used or // if a stream cipher algorithm is selected. // key Raw key material, length keyLength bytes. Key length must be appropriate // for the selected operation and algorithm. Some algorithms provide for varying key lengths. // tweak Raw key material, length keyLength bytes. Used for the tweak key in XEX-based Tweaked CodeBook (XTS) mode. // Length of tweak key material must be appropriate for the selected operation and algorithm. Some // algorithms provide for varying key lengths. For XTS this is the same length as the encryption key. // // numRounds The number of rounds of the cipher to use. 0 uses the default. // options A word of flags defining options. See discussion // for the CCModeOptions type. // // Can raise exception for with errors kCCParamError and kCCMemoryFailure. End

Sub Constructor(Operation as CommonCryptoMB.CryptoOperation, Mode as CommonCryptoMB.CryptoMode, Algorithm as CommonCryptoMB.CryptoAlgorithm, Padding as CommonCryptoMB.CryptoPadding, key as string, Tweak as Memoryblock = nil, iv as MemoryBlock = nil, NumRounds as Integer = 0, Options as Integer = 0) // Create a cryptographic context. // Operation Defines the basic operation: Encrypt or Decrypt. // mode Specifies the cipher mode to use for operations. // Algorithm Defines the algorithm. // padding Specifies the padding to use. // iv Initialization vector, optional. Used by block ciphers with the following modes: // // Cipher Block Chaining (CBC) // Cipher Feedback (CFB and CFB8) // Output Feedback (OFB) // Counter (CTR) // // If present, must be the same length as the selected // algorithm's block size. If no IV is present, a NULL // (all zeroes) IV will be used. // This parameter is ignored if ECB mode is used or // if a stream cipher algorithm is selected. // key Raw key material, length keyLength bytes. Key length must be appropriate // for the selected operation and algorithm. Some algorithms provide for varying key lengths. // tweak Raw key material, length keyLength bytes. Used for the tweak key in XEX-based Tweaked CodeBook (XTS) mode. // Length of tweak key material must be appropriate for the selected operation and algorithm. Some // algorithms provide for varying key lengths. For XTS this is the same length as the encryption key. // // numRounds The number of rounds of the cipher to use. 0 uses the default. // options A word of flags defining options. See discussion // for the CCModeOptions type. // // Can raise exception for with errors kCCParamError and kCCMemoryFailure. // convert string in current encoding to MemoryBlock End

Sub Constructor(Operation as CommonCryptoMB.CryptoOperation, Mode as CommonCryptoMB.CryptoMode, Algorithm as CommonCryptoMB.CryptoAlgorithm, Padding as CommonCryptoMB.CryptoPadding, key as text, Tweak as xojo.core.Memoryblock = nil, iv as xojo.core.MemoryBlock = nil, NumRounds as Integer = 0, Options as Integer = 0) // Create a cryptographic context. // Operation Defines the basic operation: Encrypt or Decrypt. // mode Specifies the cipher mode to use for operations. // Algorithm Defines the algorithm. // padding Specifies the padding to use. // iv Initialization vector, optional. Used by block ciphers with the following modes: // // Cipher Block Chaining (CBC) // Cipher Feedback (CFB and CFB8) // Output Feedback (OFB) // Counter (CTR) // // If present, must be the same length as the selected // algorithm's block size. If no IV is present, a NULL // (all zeroes) IV will be used. // This parameter is ignored if ECB mode is used or // if a stream cipher algorithm is selected. // key Raw key material, length keyLength bytes. Key length must be appropriate // for the selected operation and algorithm. Some algorithms provide for varying key lengths. // tweak Raw key material, length keyLength bytes. Used for the tweak key in XEX-based Tweaked CodeBook (XTS) mode. // Length of tweak key material must be appropriate for the selected operation and algorithm. Some // algorithms provide for varying key lengths. For XTS this is the same length as the encryption key. // // numRounds The number of rounds of the cipher to use. 0 uses the default. // options A word of flags defining options. See discussion // for the CCModeOptions type. // // Can raise exception for with errors kCCParamError and kCCMemoryFailure. End

Sub Destructor() // Cleanup End

Function Final1() As xojo.Core.MemoryBlock // Finish an encrypt or decrypt operation, and obtain the (possible) // final data output. // // Returns final bytes of the encrypted/decrypted data. This can be empty memoryblock. // // Raises exceptions on error. kCCBufferTooSmall indicates insufficent space in the dataOut buffer. // kCCAlignmentError When decrypting, or when encrypting with a block cipher with padding disabled, // kCCAlignmentError will be returned if the total number of bytes provided to Update is // not an integral multiple of the current algorithm's block size. // kCCDecodeError Indicates garbled ciphertext or the wrong key during decryption. This can only // be returned while decrypting with padding enabled. // // Except when kCCBufferTooSmall is returned, the Cryptor // can no longer be used for subsequent operations unless // Reset() is called on it. // // It is not necessary to call Final() when performing // symmetric encryption or decryption if padding is disabled, or // when using a stream cipher. // // It is not necessary to call Final() when aborting an operation. End

Function Final2() As MemoryBlock // Finish an encrypt or decrypt operation, and obtain the (possible) // final data output. // // Returns final bytes of the encrypted/decrypted data. This can be empty memoryblock. // // Raises exceptions on error. kCCBufferTooSmall indicates insufficent space in the dataOut buffer. // kCCAlignmentError When decrypting, or when encrypting with a block cipher with padding disabled, // kCCAlignmentError will be returned if the total number of bytes provided to Update is // not an integral multiple of the current algorithm's block size. // kCCDecodeError Indicates garbled ciphertext or the wrong key during decryption. This can only // be returned while decrypting with padding enabled. // // Except when kCCBufferTooSmall is returned, the Cryptor // can no longer be used for subsequent operations unless // Reset() is called on it. // // It is not necessary to call Final() when performing // symmetric encryption or decryption if padding is disabled, or // when using a stream cipher. // // It is not necessary to call Final() when aborting an operation. End

Sub Reset(iv as MemoryBlock) // Reinitializes an existing CCCryptorRef with a (possibly) // new initialization vector. Not implemented for stream ciphers. // // iv Optional initialization vector; if present, must // be the same size as the current algorithm's block size. // // The the only possible errors are kCCParamError and kCCUnimplemented which cause exceptions. // // This can be called on a cryptor with data pending (i.e. // in a padded mode operation before Final is called); // however any pending data will be lost in that case. End

Sub Reset(iv as xojo.core.memoryblock = nil) // Reinitializes an existing CCCryptorRef with a (possibly) // new initialization vector. Not implemented for stream ciphers. // // iv Optional initialization vector; if present, must // be the same size as the current algorithm's block size. // // The the only possible errors are kCCParamError and kCCUnimplemented which cause exceptions. // // This can be called on a cryptor with data pending (i.e. // in a padded mode operation before Final is called); // however any pending data will be lost in that case. End

Function Update(Data as MemoryBlock) As MemoryBlock // Process (encrypt, decrypt) some data. The result, if any, is returned as memoryblock. // // data: Data to process. // // Returns data. The result memoryblock can be smaller or bigger due to alignment. // // Can raise error. kCCBufferTooSmall indicates insufficent space in the dataOut buffer. // // This routine can be called multiple times. The caller does not need to align input data lengths to block sizes; input is // bufferred as necessary for block ciphers. // // When performing symmetric encryption with block ciphers, // and padding is enabled via kCCOptionPKCS7Padding, the total // number of bytes provided by all the calls to this function // when encrypting can be arbitrary (i.e., the total number // of bytes does not have to be block aligned). However if // padding is disabled, or when decrypting, the total number // of bytes does have to be aligned to the block size; otherwise // Final() will return kCCAlignmentError. // // Generally, when all data has been processed, call Final(). // // In the following cases, the CCCryptorFinal() is superfluous as // it will not yield any data nor return an error: // 1. Encrypting or decrypting with a block cipher with padding // disabled, when the total amount of data provided to // Update() is an integral multiple of the block size. // 2. Encrypting or decrypting with a stream cipher. End

Function Update(Data as string) As MemoryBlock // Process (encrypt, decrypt) some data. The result, if any, is returned as memoryblock. // // data: Data to process. // // Returns data. The result memoryblock can be smaller or bigger due to alignment. // // Can raise error. kCCBufferTooSmall indicates insufficent space in the dataOut buffer. // // This routine can be called multiple times. The caller does not need to align input data lengths to block sizes; input is // bufferred as necessary for block ciphers. // // When performing symmetric encryption with block ciphers, // and padding is enabled via kCCOptionPKCS7Padding, the total // number of bytes provided by all the calls to this function // when encrypting can be arbitrary (i.e., the total number // of bytes does not have to be block aligned). However if // padding is disabled, or when decrypting, the total number // of bytes does have to be aligned to the block size; otherwise // Final() will return kCCAlignmentError. // // Generally, when all data has been processed, call Final(). // // In the following cases, the CCCryptorFinal() is superfluous as // it will not yield any data nor return an error: // 1. Encrypting or decrypting with a block cipher with padding // disabled, when the total amount of data provided to // Update() is an integral multiple of the block size. // 2. Encrypting or decrypting with a stream cipher. // convert string in current encoding to MemoryBlock End

Function Update(Data as text) As xojo.Core.MemoryBlock // Process (encrypt, decrypt) some data. The result, if any, is returned as memoryblock. // // data: Data to process. // // Returns data. The result memoryblock can be smaller or bigger due to alignment. // // Can raise error. kCCBufferTooSmall indicates insufficent space in the dataOut buffer. // // This routine can be called multiple times. The caller does not need to align input data lengths to block sizes; input is // bufferred as necessary for block ciphers. // // When performing symmetric encryption with block ciphers, // and padding is enabled via kCCOptionPKCS7Padding, the total // number of bytes provided by all the calls to this function // when encrypting can be arbitrary (i.e., the total number // of bytes does not have to be block aligned). However if // padding is disabled, or when decrypting, the total number // of bytes does have to be aligned to the block size; otherwise // Final() will return kCCAlignmentError. // // Generally, when all data has been processed, call Final(). // // In the following cases, the CCCryptorFinal() is superfluous as // it will not yield any data nor return an error: // 1. Encrypting or decrypting with a block cipher with padding // disabled, when the total amount of data provided to // Update() is an integral multiple of the block size. // 2. Encrypting or decrypting with a stream cipher. End

Function Update(Data as xojo.Core.MemoryBlock) As xojo.Core.MemoryBlock // Process (encrypt, decrypt) some data. The result, if any, is returned as memoryblock. // // data: Data to process. // // Returns data. The result memoryblock can be smaller or bigger due to alignment. // // Can raise error. kCCBufferTooSmall indicates insufficent space in the dataOut buffer. // // This routine can be called multiple times. The caller does not need to align input data lengths to block sizes; input is // bufferred as necessary for block ciphers. // // When performing symmetric encryption with block ciphers, // and padding is enabled via kCCOptionPKCS7Padding, the total // number of bytes provided by all the calls to this function // when encrypting can be arbitrary (i.e., the total number // of bytes does not have to be block aligned). However if // padding is disabled, or when decrypting, the total number // of bytes does have to be aligned to the block size; otherwise // Final() will return kCCAlignmentError. // // Generally, when all data has been processed, call Final(). // // In the following cases, the CCCryptorFinal() is superfluous as // it will not yield any data nor return an error: // 1. Encrypting or decrypting with a block cipher with padding // disabled, when the total amount of data provided to // Update() is an integral multiple of the block size. // 2. Encrypting or decrypting with a stream cipher. End

Note About

Property Algorithm As CommonCryptoMB.CryptoAlgorithm

Property Operation As CommonCryptoMB.CryptoOperation

Property Options As Integer

Property Padding As CommonCryptoMB.CryptoPadding

End Class