« Changelog History


acra v0.93.0 Release Notes

Release Date: 2021-05-27 // almost 3 years ago

  • 🚀 This release brings type awareness which improves transparent encryption on AcraServer. Type awareness means that it's possible to tell AcraServer what are the original data types for fields. During decryption, AcraServer will convert decrypted fields to their original data types. No need to change client application code to work with "binary data".

    0️⃣ It's also possible to choose a default value for each data field if its decryption failed. AcraServer can send a a default value like "" instead of decryption errors, making developers' and users' life easier.

    Core:

    • AcraServer:
      • Added type awareness and ability to map binary data to a certain data type when sending decrypted data back to the application. Extended encryptor_config which allow configure mapping application data type to proper database's type. #515, #517, #523, #519, #520
      • Extended encryptor_config with new parameters:
      • data_type - specify data type expected by application. Accept str, bytes, int64, int32 values. #515, #517
      • default_data_value - specify a placeholder (default value) to replace data that couldn't be decrypted. #515, #517
      • response_on_fail - specify action on decryption failure. Accepts ciphertext (returns encrypted data as is), default_value (returns values from default_data_value parameter), error (returns error as DB error with message like encoding error in column {column_name}). #521, #533
      • Deprecated tokenize parameter in encryptor_config and changed focus on token_type parameter. Now is enough to specify token_type parameter without tokenize: true to turn on tokenization. Read more in the documentation. #527
      • Removed auto-generation poison record's keys but leaved for acra-poisonrecordmaker. It improves decryption due to omitting extra key generation and poison record recognition. #516
      • Improvements in handling error cases on DB protocol layer. #511, #515, #517, #520, #528, #535, #537
      • Improved sql parser and support of set command. #534
      • Ignored legacy keys on startup loading to cache. #510, #522
      • Improved PostgreSQL/MySQL protocol support. #525, #526, #539, #540, #541, #542, #543, #544
    • AcraCensor:
      • Removed legacy IsForbidden field from acra-censor’s logs. Read more here in notes. #508
    • AcraKeys:
      • Removed duplicate entries in list command. #530
    • Other:
      • Makefile target install_dev_deps install required golang's dependencies for development and code generation. #531

    📚 Documentation:

    • 👌 Improved description of AcraServer's encryptor_config, adding details and examples about data processing options: encryption, searchable encryption, masking, tokenization, type awareness, etc.
    • ⚡️ Updated "Debugging and troubleshooting" section with more tips and tricks.

    Example projects and demos:


Previous changes from v0.85.0

  • 🚀 0.85.0, March 15th 2018

    Core:

    💥 Breaking changes:

    🔧 Introducing a new more flexible configuration format for AcraCensor rules. AcraCensor doesn't support the old format, all users should migrate (don't worry, it's a simple procedure).

    Search through encrypted data

    You now can run SQL queries over encrypted AcraStructs allowing users to search through sensitive data without exposing it. This feature is only available in Acra Enterprise version.

    Transparent proxy mode

    TLDR: Transparent proxy mode allows you to configure AcraServer to encrypt records in specific database columns without altering the application code.

    📜 The application flow doesn't need to change: application sends SQL requests through AcraConnector and AcraServer to the database. AcraServer parses each request, encrypts the desired values into AcraStructs, and passes the modified requests to the database. To retrieve the decrypted data, your application talks to AcraServer again: upon receiving the database response, AcraServer tries to detect AcraStructs, decrypts them, and returns the decrypted data to the application.

    ⚡️ Transparent proxy mode is useful for large distributed applications where updating the source code of each client app separately would be complicated.

    To enable this mode, you need to create a separate encryptor configuration file (acra-encryptor.yaml) that describes which columns to encrypt and provide a path to it in the AcraServer configuration file (or via CLI params --encryptor_config_file=acra-encryptor.yaml).

    📚 Read more details in the Readme and in the Acra documentation section dedicated to Transparent encryption.

    (#285, #309, #314).

    AcraCensor – SQL firewall to prevent SQL injections

    TLDR: Improved stability of AcraCensor, switched to more flexible rules' configuration.

    💥 Breaking changes: Introducing a new format for configuration files, the previous format is no longer supported, you should migrate to the new one.

    🆕 New configuration file format allows configuring the allowlist and the denylist separately or simultaneously.

    The allow handler allows something specific and restricts/forbids everything else. The allowall handler should be a final statement as that means that all the other queries will be allowed.

    The deny handler allows everything and forbids something specific. The denyall means "block all queries!" (that haven't been allowed or ignored before).

    🔧 For each handler, there are settings that regulate queries, tables, and patterns. The order of priority for the lists is defined by their position in the configuration file. The processing priority for each list is as follows: queries, followed by tables, followed by patterns.

    (#298, #297, #304, #306).

    📚 Read more in AcraCensor docs.

    ➕ Added version to the configuration file. This allows detecting an outdated configuration easily. From now on, AcraCensor supports explicit configuration version and logs errors if the configuration is not valid (#321).

    👌 Improved parsing of SQL queries with prepared statements (#303, #283).

    👌 Improved error handling for queries that AcraCensor can't parse (#291, #284).

    ➕ Added ability to log unparsed queries to a separate log file for the debugging and configuration purposes. Sometimes AcraCensor can't parse all of the incoming queries and it is useful to have a separate log for them.

    How to use it: Provide the path to the unparsed queries log file in the configuration file parse_errors_log: unparsed_queries.log (#295).

    👌 Improved support of PostgreSQL queries ("RETURNING" clause) and quoted identifiers (now you can use "tablename" and WHERE "column"=1) (#296).

    🛠 Fixed the bug in QueryCapture log that caused duplicated of records in the log to appear (#318).

    AcraServer

    🛠 Fixed handling of null-size packets in PostgreSQL protocol (#286).

    🛠 Fixed handling of setting a custom connection API port (#294).

    🛠 Fixed handling of the plain text data response: if the database returns a plain text response, it is redirected "as is" (#305).

    🛠 Fixed handling of casted placeholders in expressions like SELECT $1::type1::type2 FROM table1 WHERE column1=$2::type3::type4 (#328).

    👌 Improved code quality (some refactoring here and there) (#302, #301).

    AcraServer, AcraTranslator, AcraConnector

    🔨 Refactored logs and error messages got even more descriptive and user-friendly (#312, #299, #317).

    ➕ Added on-start version logging to make it easier to understand which version is running (#319).

    ➕ Added versioning for configuration files of each service (#322).

    ➕ Added exporting version to metrics (#330, #320).

    📚 Updated some configuration parameters descriptions for better user-friendliness (please see our docs of AcraConnector and AcraServer for detailed descriptions of each parameter and usage examples) (#329).

    AcraWriter

    ⚡️ Updated AcraWriter for ActiveRecord (Ruby), fixed dependencies, added support of mysql2 adapter (#287).

    ⚡️ Updated AcraWriter for Django (Python), fixed potential encoding issues (#293, #292).

    ⚡️ Updated AcraWriter for C++, improved cpp codec usage (#290, #289).

    ➕ Added bitcode for AcraWriter iOS and added Swift example project (#327, #326, #325, #324, #323, #323, #307).

    👌 Improved distribution of AcraWriter for Android, now it's available via Maven (#310).

    Other

    ➕ Added more tests and then — added even more tests. We just love automating things! (#331, #311, #308, #292).

    ⚡️ Updated the version of pyyaml used in the tests due to CVE-2017-18342. This change doesn't affect the users of Acra, it only affects our test suite (#300).

    Infrastructure:

    • ⚡️ Updated Docker files, added more comments, and updated Go version (#313, #288).

    Example projects and demos:

    iOS Swift example project that shows how to generate AcraStructs with and without Zones.

    Android example project that shows how to integrate AcraWriter library into Android app using maven, and then to generate AcraStructs with and without Zones, and to decrypt them using AcraTranslator.

    🔧 AcraCensor demo that shows how to configure AcraCensor for SQL injections prevention in OWASP Mutillidae 2 example app.

    💎 Protecting data in a Rails application demo based on AcraServer, PostgreSQL, and Ruby on Rails client application.

    Protecting metrics in TimescaleDB demo based on AcraServer, TimescaleDB, and Grafana.

    🔧 Transparent proxy mode demo that shows how to configure AcraServer in Transparent proxy mode to protect Django-based application.

    Related blog posts:

    🌐 The difference between SQL firewalls and Web Application Firewalls.

    🏗 Engineering details on how we built AcraCensor.

    🔋 Features coming soon:

    🔌 Pseudonymisation: an early version of pseudonymisation library/plugin for Acra for transparent data pseudonymisation.

    🔊 Cryptographically protected audit log: protection for logs against tampering.

    📚 Documentation:

    📚 Updated AcraServer documentation to describe Transparent mode in more details.

    📚 Updated AcraCensor documentation to describe the new configuration format and procedures for migration from the previous one.

    📚 Updated AcraWriter documentation for iOS and Android to reflect the improved installation ways.