API do OpenSSL: Estruturas Principais e Armadilhas

A API EVP (Envelope) é a interface de alto nível do OpenSSL para operações criptográficas e é a API correta para usar no código da aplicação. Ela abstrai detalhes específicos dos algoritmos por meio de uma interface consistente, oferece aceleração de hardware por mecanismos e provedores automaticamente e trata corretamente os detalhes de preenchimento e modo. As APIs de baixo nível específicas de algoritmos do OpenSSL estão obsoletas nas versões modernas e devem ser evitadas.

A criptografia simétrica no OpenSSL usa o objeto de contexto EVP_CIPHER_CTX. A sequência de operações é: EVP_CIPHER_CTX_new para alocar o contexto, EVP_EncryptInit_ex para inicializá-lo com a cifra e a chave, EVP_EncryptUpdate repetidamente para processar os dados, EVP_EncryptFinal_ex para liberar o bloco final e recuperar a saída restante, e EVP_CIPHER_CTX_free para liberar a memória. Ignorar EncryptFinal_ex é um erro comum que produz uma saída truncada.

O cálculo do resumo da mensagem usa EVP_MD_CTX de forma semelhante: EVP_MD_CTX_new, EVP_DigestInit_ex com o algoritmo (EVP_sha256(), EVP_sha3_256() etc.), EVP_DigestUpdate com partes dos dados e EVP_DigestFinal_ex para recuperar o hash. As operações HMAC usam um HMAC_CTX separado ou a API EVP_MAC mais recente. A abstração EVP permite trocar os algoritmos de hash alterando uma única chamada de função.

EVP_PKEY é o objeto unificado de chave assimétrica no OpenSSL, compatível com RSA, ECDSA, Ed25519, DH e outros algoritmos por meio de uma única interface. As chaves são criadas a partir de arquivos PEM ou DER com PEM_read_PrivateKey e PEM_read_PUBKEY, ou geradas com EVP_PKEY_keygen. EVP_PKEY_sign e EVP_PKEY_verify executam a assinatura e a verificação para qualquer tipo de chave usando as mesmas chamadas de função.

BIO (E/S básica) é a camada de abstração de entrada e saída do OpenSSL, que permite ler e gravar dados protegidos por TLS ou dados brutos por meio de uma cadeia de objetos BIO. Uma cadeia BIO pode ser: BIO_new_ssl (camada TLS) encadeado a BIO_new_connect (conexão TCP). Gravar no BIO SSL criptografa e envia os dados automaticamente; ler descriptografa os dados recebidos. Os objetos BIO são compatíveis com arquivos, soquetes, buffers de memória e filtros (base64, armazenamento em buffer).

As conexões TLS no OpenSSL usam dois objetos: SSL_CTX (contexto) armazena a configuração compartilhada: certificado, chave privada, conjunto de certificados de CA, limites de versão do protocolo e lista de cifras. SSL representa uma conexão individual derivada do contexto. Crie um SSL_CTX por aplicação e, em seguida, crie objetos SSL a partir dele para cada conexão. SSL_read e SSL_write transferem texto simples; o OpenSSL trata internamente de todo o enquadramento e da criptografia TLS.

O erro mais perigoso ao usar OpenSSL é ignorar os valores de retorno. EVP_EncryptFinal_ex, SSL_read e SSL_write retornam valores negativos ou zero para indicar erros. Chamar SSL_read em um laço sem verificar SSL_get_error pode causar laços infinitos ou fazer com que erros não sejam percebidos. O valor de retorno de toda função do OpenSSL que possa falhar deve ser verificado; as falhas frequentemente indicam condições relevantes para a segurança, como falhas no handshake ou erros na validação de certificados.

SSL_read e SSL_write podem retornar SSL_ERROR_WANT_READ ou SSL_ERROR_WANT_WRITE, indicando que a operação deve ser repetida depois de aguardar a entrada e a saída. Essas condições não são erros verdadeiros, mas notificações de entrada e saída sem bloqueio. O código que não chama SSL_get_error e não escolhe corretamente o ramo para leitura ou gravação pendente entrará em um laço ocupado ou tratará incorretamente essas condições como erros. Sempre use SSL_get_error para interpretar valores de retorno negativos das operações de entrada e saída de TLS.

O OpenSSL contém muitas funções de baixo nível obsoletas que não devem aparecer em código novo: chamadas diretas a DES_encrypt1, uso direto das funções de hash SHA1 ou MD5 sem a camada EVP, RSA_private_encrypt em vez de EVP_PKEY_sign e AES_encrypt (AES ECB sem autenticação). Essas APIs ignoram verificações de segurança, usam algoritmos obsoletos ou são simplesmente menos seguras que seus equivalentes EVP. Avisos do compilador frequentemente sinalizam o uso de APIs obsoletas.

O OpenSSL usa gerenciamento explícito de memória; todo objeto alocado deve ser liberado explicitamente. Vazamentos de memória comuns incluem esquecer EVP_CIPHER_CTX_free após a criptografia, não chamar SSL_free depois de fechar uma conexão ou não chamar X509_free após a verificação de um certificado. Em servidores de longa execução, esses vazamentos causam esgotamento gradual da memória. Use ferramentas como valgrind ou AddressSanitizer para detectar vazamentos de memória do OpenSSL durante o desenvolvimento.

O OpenSSL 3.0 introduziu o modelo de provedores, substituindo a API ENGINE anterior para aceleração de hardware. Os provedores são módulos carregáveis que implementam algoritmos criptográficos: o provedor padrão (software), o provedor legado (algoritmos mais antigos), o provedor FIPS (validado segundo FIPS 140-2) e provedores de terceiros para HSMs. O provedor FIPS permite uma operação em conformidade ao restringir os algoritmos disponíveis àqueles aprovados pelo FIPS 140-2, sem alterar o código da aplicação.

Por que a API EVP do OpenSSL é preferida às APIs de baixo nível específicas de algoritmos?

Resumo da API do OpenSSL: use sempre a API EVP de alto nível; EVP_CIPHER_CTX para operações simétricas; EVP_MD_CTX para cálculo de hashes; EVP_PKEY para chaves assimétricas; cadeias BIO para abstração de entrada e saída; SSL_CTX e SSL para conexões TLS; verifique sempre os valores de retorno e chame SSL_get_error; libere todos os objetos alocados para evitar vazamentos; evite funções de baixo nível obsoletas; e use os provedores do OpenSSL 3.0 para conformidade com FIPS ou aceleração de hardware.