Logo

Download
AcraTranslator, an API service

AcraTranslator, an API service #

AcraTranslator is an API server, that exposes most of Acra’s features as HTTP / gRPC API with client SDKs and traffic protection. AcraTranslator doesn’t depend on a database and makes application responsible for actually putting data into storage.

AcraTranslator is your the main choice when your application should make encryption calls, or you use NoSQL/KV datastore.

Refer to Integrating AcraTranslator into infrastructure to learn how to configure AcraTranslator.

AcraTranslator’s functionality #

AcraTranslator provides an API (either gRPC or HTTP) for applications giving them the ability to perform different data protection operations, like encryption/decryption, generating hash for searchable encryption, tokenization/detokenization.

AcraTranslator reacts on poison records in received data (intrusion detection), provides programmatic reactions on security incidents, and full-on monitoring: security logging & audit logging, security events, metrics, traces, etc.

Refer to a Acra security features to learn the full list.

Functional requirements #

Your application explicitly sends data to the AcraTranslator via API. Your application defines AcraTranslator’s behavior regarding the data – for example, encrypt plaintext and return encrypted container. Then your app is responsible for storing the data, or sending it to another services.

Your application doesn’t need to handle any cryptographic code or have access to any keys.

  • Data encryption/decryption as API.
  • Generating searchable hash for search of encrypted value in a database.
  • Tokenization/detokenization as API (it’s kind of pseudonymization, read more about tokenization).
  • Encrypted data will remain protected and useless unless AcraTranslator has access to decryption keys.

Non-functional requirements #

Dataflows #

We outlined typical dataflows for AcraTranslator in the Dataflow chapter.

Here is the simplest connection:

Client application connects to the AcraTranslator via API, then client app is responsible for storing/using encrypted data. If the client app wants to decrypt data, it reads encrypted data from the storage (or another app), and asks AcraTranslator to decrypt it.

Acra provides SDK for AcraTranslator to improve working with its API and make integration easier.

Connection with other parts #

Except talking with the client app, AcraTranslator also connects to other parts of your system. Some connections are required – for example, if you place Acra Master Key to KMS, AcraTranslator should know how to connect to the KMS.

Other connections are optional – for example, you can use Redis as external key storage for intermediate keys (useful when you have a cluster of AcraTranslator), or put them into FS on AcraTranslator side.

  • Redis – external key storage for intermediate keys (optional), or required storage for tokens if AcraTranslator performs tokenization.

  • KMS – if you put Acra Master Key to KMS, like HashiCorp Vault, AcraTranslator should read this key during startup.

  • SDK for AcraTranslator – optional client-side SDK for easier usage of AcraTranslator’s API in the app.

  • AcraWriter, AcraReader – optional client-side SDKs to encrypt or decrypt AcraBlocks/AcraStructs without AcraTranslator.

  • AcraConnector – optional client-side service/daemon that implements transport security and authentication for client application that doesn’t support TLS 1.2+.

Architectural considerations #

Similar to AcraServer’s recomendations, it is strictly recommended to host AcraTranslator on a different machine (virtual or physical), isolated from both client applications and the database.

This comes from the fact that Acra works with a sensitive data (such as encryption keys) and isolation will decrease risks of other components doing malicious things with it.

When using AcraTranslator, it is considered that you trust it, but do not trust the database. Anyway, AcraTranslator won’t be able to decrypt data for which it does not have the encryption keys, as well as it won’t decrypt data for application clients not supposed to access it.

However, in cases when you need to make application the only component that interacts with plaintext, AcraTranslator won’t help you, you will have to use things like AcraWriter to encrypt data on application-side before it leaves.

Refer to Scaling and HA to learn how to scale and support growing infrastructure when you use AcraTranslator.