AESEncoder()

Syntax

Result = AESEncoder(*Input, InputOffset, *Output, OutputOffset, Size, *Key, Bits, *InitializationVector [, Mode])
Description
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()
<- AESDecoder() - Cipher Index - AddCipherBuffer() ->