AESEncoder()

Syntax

Result = AESEncoder(*Input, InputOffset, *Output, OutputOffset, Size, *Key, Bits, *InitializationVector [, Mode])

Encodes the specified input buffer using the AES algorithm into the output buffer.

Parameters

*Input	The input buffer. It has to be allocated with AllocateMemory().
InputOffset	The offset (in bytes) in the input buffer.
*Output	The output buffer. It has to be allocated with AllocateMemory() and be different than the input buffer.
InputOffset	The offset (in bytes) in the output buffer.
Size	The amount of bytes to encode. It has to be at least 16 bytes. To encode something smaller, padding has to be added before the encoding.
*Key	A buffer containing the key for encoding. Its size depends of the 'Bits' parameter: 16 bytes for 128-bit encryption, 24 bytes for 192 bit and 32 bytes for 256-bit.
Bits	The size of the key used by the ciphering. Valid values are 128, 192 and 256.
*InitializationVector	The InitializationVector is a random data block, used to initialize the ciphering to avoid breach in decoding (only needed when using the #PB_Cipher_CBC mode). The initialization vector is always 16 bytes long.
Mode (optional)	This can be one of the following value: #PB_Cipher_CBC: Default mode of encoding (Cipher Block Chaining). Needs an '*InitializationVector'. Recommended as more secure than ECB mode. #PB_Cipher_ECB: Alternative mode (Electronic CodeBook). It doesn't uses random value nor chaining (each block is ciphered independently) making it very weak compared to CBC, and shouldn't be used for serious ciphering.

Return value

Returns nonzero if the encoding was successful, zero otherwise.

Remarks

AES is an industry class cipher algorithm and is good balanced between speed and security. Here is the Wikipedia introduction about AES: 'In cryptography, the Advanced Encryption Standard (AES) is an encryption standard adopted by the U.S. government. The standard comprises three block ciphers, AES-128, AES-192 and AES-256, adopted from a larger collection originally published as Rijndael. Each AES cipher has a 128-bit block size, with key sizes of 128, 192 and 256-bit, respectively. The AES ciphers have been analyzed extensively and are now used worldwide.'

PureBasic uses a RFC compliant implementation of AES. More information can be found in the RFC 3602: http://www.ietf.org/rfc/rfc3602.txt.

Example: CBC

  ; Easy procedure to convert a datasection to an allocated memory block
  ;
  Procedure DataSectionToMemory(Size)
    Protected *Buffer
    
    *Buffer = AllocateMemory(Size)
    For k = 0 To Size-1
      Read.b value
      PokeB(*Buffer, k, value)
    Next
    
    ProcedureReturn *Buffer
  EndProcedure
  
  Text$ = "Single block msg"
  Debug "Original text: " + Text$
  
  ; AES encoder can only work with memory buffer, so put our text in a memory buffer
  ;
  *AsciiText = AllocateMemory(128)
  PokeS(*AsciiText, 0, Text$, -1, #PB_Ascii)
  
  ; Get the InitializationVector value (needed for CBC encoding)
  ;
  Restore AESInitializationVector1
  *AESInitializationVector1 = DataSectionToMemory(16)
  
  ; Our private key
  ;
  Restore AESKey1
  *AESKey1 = DataSectionToMemory(16)
  
  ; The output buffer, needs to be input buffer size+1, aligned to the next 16-byte block
  ;
  *Output = AllocateMemory(16+16)
  AESEncoder(*AsciiText, 0, *Output, 0, 16, *AESKey1, 128, *AESInitializationVector1)
  
  ; Display the encoded message
  ;
  For k = 0 To 15
    HexView$ + Hex(PeekB(*Output, k), #PB_Byte) + " "
  Next
  Debug "Text encoded (hex view): " + HexView$
  
  ; Decode it with the same InitializationVector and private key
  ;
  *DecodedText = AllocateMemory(128)
  AESDecoder(*Output, 0, *DecodedText, 0, 32, *AESKey1, 128, *AESInitializationVector1)
  Debug "Decoded text: " + PeekS(*DecodedText, 0, 16, #PB_Ascii)
  
  DataSection
    AESInitializationVector1:
      Data.b $3d, $af, $ba, $42, $9d, $9e, $b4, $30, $b4, $22, $da, $80, $2c, $9f, $ac, $41
  
    AESKey1:
      Data.b $06, $a9, $21, $40, $36, $b8, $a1, $5b, $51, $2e, $03, $d5, $34, $12, $00, $06
  EndDataSection

See Also

AESDecoder(), StartAESCipher()

Supported OS

All