Árvore de páginas

Encripta textos usando o algoritmo AES no modo definido.

Sintaxe

AESEncrypt( < nCipherID >, < cPlainText >, [ cPassword ], [ cKey ], [ cIV ] )

Parâmetros

Nome

Tipo

Descrição

Obrigatório

Referência

nCipherID

numérico

Código identificador do modo do algoritmo AES a ser usado na encriptação.

X


cPlainText

caractere

Texto de entrada a ser encriptado.

X


cPassword

caractere

Texto auxiliar na geração da key da encriptação.



cKey

caractere

Key da encriptação, conforme o modo do algoritmo AES a ser usado.



cIV

caractere

IV (Vetor de Inicialização) da encriptação, conforme o modo do algoritmo AES a ser usado.



Retorno

Nome

Tipo

Descrição

aResEnc

vetor

Array com o resultado do processo de encriptação.

Observações


  • Modos do algoritmo AES suportados: a partir dos modos do algoritmo AES suportados, são definidos os códigos identificadores, os tamanho da Key e do IV e a obrigatoriedade do uso do IV:

    Modo do algoritmo AES

    Código Identificador

    Tamanho da Key (em bytes)

    Tamanho do IV (em bytes)

    IV Usado

    AES-128 CBC

    0

    16

    16

    Sim

    AES-192 CBC

    1

    24

    16

    Sim

    AES-256 CBC

    2

    32

    16

    Sim


  • Regra para uso ou geração da Key: a key fornecida somente será usada se o password não for fornecido, segundo a seguinte lógica:

    Password Fornecido

    Key Fornecida

    Resultado

    Sim

    Sim

    Ignora a Key fornecida, gera a Key usando o password fornecido e a usa.

    Sim

    Não

    Gera a Key usando o password fornecido e a usa.

    Não

    Sim

    Usa a Key fornecida.

    Não

    Não

    Gera a Key e a usa.


  • Sobre o uso de keys fornecidas: caso sejam utilizadas keys fornecidas, por razões de segurança da informação, recomenda-se:
    • somente usar keys derivadas a partir de algoritmos apropriados e com componente randômico;
    • não repetir a mesma key para diferentes textos de entrada.


  • Regra para uso ou geração do IV: para o modo CBC:

    IV Fornecido

    Resultado

    Sim

    Usa o IV fornecido.

    Não

    Gera o IV e o usa.


  • Sobre o uso de ivs fornecidos: para o modo CBC, caso sejam utilizados ivs fornecidos, por razões de segurança da informação, recomenda-se:
    • somente usar ivs gerados randomicamente.


  • Formato e conteúdo da array com o resultado da encriptação:

    Índice

    Nome

    Tipo

    Descrição

    Conteúdo

    1

    nResultCode

    numérico

    Código identificador do resultado da encriptação.

    0 (zero) em caso de sucesso ou diferente de 0 (zero) em caso de erro.

    2

    cCipherText

    caractere

    Texto de saída resultado da encriptação.

    Texto da entrada encriptado no modo definido em caso de sucesso ou vazio em caso de erro.

    3

    cKeyUsed

    caractere

    Key usada na encriptação.

    Key usada na encriptação em caso de sucesso ou vazio em caso de erro.

    4

    cIVUsed

    caractere

    IV usado na encriptação.

    IV usado na encriptação em caso de sucesso ou vazio em caso de erro.


  • Códigos identificadores do resultado da encriptação:

    Código

    Significado

    0

    Sucesso.

    1

    Erro de código identificador do modo do algoritmo de criptografia inválido.

    2

    Erro de comprimento da key fornecida é inválido para o modo definido.

    3

    Erro de comprimento do iv fornecido é inválido para o modo definido.

    4

    Erro de geração da key: erro gerando o salt.

    5

    Erro de geração da key: erro derivando a key.

    6

    Erro de geração do iv: erro gerando o iv.

    7

    Erro de texto encriptado vazio.

    8

    Erro de encriptação: o conteúdo de um ou mais dos parâmetros de entrada não corresponde ao esperado.

    9

    Erro de decriptação: o conteúdo de um ou mais dos parâmetros de entrada não corresponde ao esperado.

    10

    Erro de código de erro desconhecido.


Exemplos

  • Exemplo 1: criptografia AES-128 CBC usando key gerada a partir do password fornecido e IV gerado randômico:

    User Function ExeAES1()
    
      Local nCipherID   := 0  // AES-128 CBC
      Local cPlainText  := "<Texto de entrada>"
      Local cPassword   := "<Texto auxiliar na geração da key da encriptação>"
      Local cKeyUsed    := ""
      Local cIVUsed     := ""
      Local cCipherText := ""
      Local aResEnc     := {}
      Local aResDec     := {}
    
      aResEnc := AESEncrypt( nCipherID, cPlainText, cPassword )
      
      VarInfo( "AESEncrypt", aResEnc )
    
      // AESEncrypt -> ARRAY (    4) [...]
      //      AESEncrypt[1] -> N (   15) [         0.0000]
      //      AESEncrypt[2] -> C (   32) [<Texto de saída da encriptação>]
      //      AESEncrypt[3] -> C (   16) [<Key usada na encriptação, derivada a partir do password pela função de encriptação>]
      //      AESEncrypt[4] -> C (   16) [<IV usado na encriptação, gerado randomicamente pela função de encriptação>]
    
      cCipherText := aResEnc[2]
      cKeyUsed    := aResEnc[3]
      cIVUsed     := aResEnc[4]
    
      aResDec := AESDecrypt( nCipherID, cCipherText, cKeyUsed, cIVUsed )
      
      VarInfo( "AESDecrypt", aResDec )
    
      // AESDecrypt -> ARRAY (    2) [...]
      //      AESDecrypt[1] -> N (   15) [         0.0000]
      //      AESDecrypt[2] -> C (   16) [<Texto de saída da decriptação, idêntico ao texto de entrada>]
    
    Return
    
  • Exemplo 2: criptografia AES-128 CBC usando key fornecida e IV fornecido:

    User Function ExeAES2()
    
      Local nCipherID   := 0  // AES-128 CBC
      Local cPlainText  := "<Texto de entrada>"
      Local cKeyInput   := "<Key a ser usada na encriptação e na decriptação, gerada previamente>"
      Local cIVInput    := "<IV a ser usado na encriptação e na decriptação, gerado previamente>"
      Local cKeyUsed    := ""
      Local cIVUsed     := ""
      Local cCipherText := ""
      Local aResEnc     := {}
      Local aResDec     := {}
    
      aResEnc := AESEncrypt( nCipherID, cPlainText, , cKeyInput, cIVInput )
      
      VarInfo( "AESEncrypt", aResEnc )
    
      // AESEncrypt -> ARRAY (    4) [...]
      //      AESEncrypt[1] -> N (   15) [         0.0000]
      //      AESEncrypt[2] -> C (   32) [<Texto de saída da encriptação>]
      //      AESEncrypt[3] -> C (   16) [<Key usada na encriptação, gerada previamente>]
      //      AESEncrypt[4] -> C (   16) [<IV usado na encriptação, gerado previamente>]
    
      cCipherText := aResEnc[2]
      cKeyUsed    := aResEnc[3]
      cIVUsed     := aResEnc[4]
    
      aResDec := AESDecrypt( nCipherID, cCipherText, cKeyUsed, cIVUsed )
      
      VarInfo( "AESDecrypt", aResDec )
    
      // AESDecrypt -> ARRAY (    2) [...]
      //      AESDecrypt[1] -> N (   15) [         0.0000]
      //      AESDecrypt[2] -> C (   16) [<Texto de saída da decriptação, idêntico ao texto de entrada>]
    
    Return
    

Abrangência

Disponível no AppServer a partir da build 17.3.0.15

Veja também