Search Knowledge Base

Created On

Too complicated, too time-consuming, not easy to use – there are many reasons why neither S/MIME nor PGP are used. In this article, we explain how REDDCRYPT works and show you how to integrate REDDCRYPT into your solution with just two HTTP API calls.

Problems with classic email encryption

Classic email encryption with S/MIME and PGP is based on key pairs consisting of a private and a public key. In order for two parties to communicate with each other in encrypted form, these key pairs must be generated and public keys exchanged with the communication partners.

The biggest hurdles to these approaches:

  • Generating key pairs is time-consuming and a technical challenge for the “normal” user
  • The exchange of public certificates must take place before communication
  • These public certificates must be installed for future use in mail clients (e.g. Microsoft Outlook and smartphones), which again requires a high level of technical understanding
  • If one of the two communication partners has no certificates, encryption is not possible

As a result, emails with classic encryption are not

  • between every man and every woman,
  • at any time and
  • in a simple way

can be transmitted. A high degree of technical understanding is always required – and this is essential for both the sender and recipient.

(Technical) Functionality of REDDCRYPT

Although REDDCRYPT is also based on the PGP standard, the time-consuming creation and exchange of certificates is a thing of the past. REDDCRYPT automates the biggest hurdles and also enables ad hoc encryption with any recipient address.

Free registration with REDDCRYPT automatically generates a PGP key pair without this being visible to the user. REDDCRYPT is used exclusively via a central login based on an email address and password. This means that REDDCRYPT is no different to other email providers or shopping on Amazon in terms of handling and complexity for the user.

The entire encryption and decryption process takes place automatically in the background. The technology behind REDDCRPYT is described in brief below; the full description can be found at https://www.reddcrypt.com/technologie/.

The encryption of emails

After successful authentication (= login) via one of the available REDDCRYPT apps, a random session key is generated on the user’s device, which is used to encrypt the email for the first time. To ensure that no one other than the recipient has access to the content, the session key is now also encrypted. A distinction is made here as to whether the recipient also has a REDDCRYPT account or not.

Recipient is already a REDDCRYPT user
When the recipient’s email address is entered, the REDDCRYPT key server is automatically requested. If the recipient already uses REDDCRYPT, their public key is stored on our servers and is downloaded at this moment in order to encrypt the session key.

Recipient is not yet a REDDCRYPT user
If there is no public key for the email address entered, the sender defines an encryption key with which the session key is encrypted.

If the REDDCRYPT user now sends the email, the encrypted email is combined with the encrypted session key in a container and transferred to the REDDCRYPT servers.

The decryption of emails

Decryption also takes place locally on the user’s end device.

The recipient is already a REDDCRYPT user
Once the recipient has successfully authenticated with the REDDCRYPT app (=login), the private key and the container are downloaded in the background. The private key is decrypted with the password entered during authentication and is now used to decrypt the session key.

The decrypted session key is now used to decrypt the encrypted email. The entire process takes place in the background and the email opens automatically when you click on it.

The recipient is not a REDDCRYPT user
As the session key was not encrypted with a public key but with an encryption key defined by the sender, the recipient now needs this to decrypt the email. Once the encryption key has been successfully entered, the decrypted session key is used to decrypt the email.

The recipient can now read and reply to the email. If the recipient wants to send e-mails proactively, free registration is required.

Integration of REDDCRYPT into your client or server application

REDDCRYPT has been designed so that it can be easily integrated into third-party software. A component for clients (REDDCRYPT Desktop) and a central service (REDDCRYPT Gateway) are currently available for this purpose. The actual integration and connection is identical in both cases.

REDDCRYPT Desktop

REDDCRYPT Desktop is ideal if your application is operated locally on the end device and interaction by the user is necessary or desired. One example of this is the integration of REDDCRYPT into existing e-mail clients. The Outlook plugin provided by us works according to the same principle. The Outlook plugin itself has no encryption logic, but interacts with the REDDCRYPT desktop, which handles the entire encryption and decryption process.

The API documentation for the REDDCRYPT Desktop can be found here (in progress)

REDDCRYPT Gateway

REDDCRYPT Gateway is intended for applications in which, for example, no user interaction is desired or possible. One example of this is sending payslips to employees by email. This is traditionally an automated process from the payroll accounting software and not a manual email dispatch by users.

In addition, REDDCRYPT Gateway has been designed to enable integration into central server applications such as CRM, DMS, ERP or ticket systems. Another example is the integration into our central email gateway, the REDDOXX Appliance.

Download REDDCRYPT Gateway for Windows

Under Windows(download), the REDDCRYT Gateway Service is simply installed via MSI setup. The installation takes place in the directory: 

%ProgramFiles%\REDDCRYPT Gateway

Download REDDCRYPT Gateway for Linux

This installation path is used under Linux(Download TGZ or Debian):

/opt/reddoxx/reddcrypt-gateway

Simple installation:

curl -o /tmp/ReddcryptGateway.tgz https://URL/ReddcryptGateway.tgz

rm -Rf /opt/reddcrypt-gateway/bin
mkdir -p /opt/reddcrypt-gateway/bin
cd /opt/reddcrypt-gateway/bin
tar xzf /tmp/ReddcryptGateway.tgz

Start (as foreground process):

cd /opt/reddoxx/reddcrypt-gateway
bin/ReddcryptGateway

API to encrypt the email

There are various ways to send encrypted emails with the REDDCRYPT Gateway. In the simplest variant, the email is encrypted by the gateway and sent directly to the recipient via the REDDCRYPT Cloud Service. However, the gateway can also only encrypt the emails and generate a transport email, which can then be sent by your service via SMTP.

The mail to be encrypted is either transmitted to the gateway via a simple multipart form data HTTP request or as a file name. The latter assumes that the gateway can access the file.

Encrypt and send directly

In this variant, the transferred email is encrypted by the gateway and then transferred directly to the REDDCRYPT Cloud Service. The REDDCRYPT Cloud Service then takes care of sending it to the actual recipients. Within the REDDCRYPT applications (Web App, Mobile App, REDDCRYPT Desktop), the email is visible immediately after it has been transferred to the REDDCRYPT Cloud Service.

Encrypting for SMTP transport

In this variant, the transferred email is only encrypted by the gateway, but not sent. In this case, the encrypted email (transport email) can be sent as normal via SMTP.

SMTP dispatch via the REDDCRYPT Cloud Service

SMTP dispatch via the REDDCRYPT Cloud Service is the recommended variant. In this case, the transport mail is sent to the REDDCRYPT Cloud Service via SMTP. The REDDCRYPT Cloud Service then handles the dispatch to the actual recipients. The advantage of this variant is that the recipients can also find the mail in all REDDCRYPT applications and access it directly.

SMTP dispatch directly to therecipients

Sending SMTP directly to the recipient only makes sense for certain environments, e.g. if the recipient also uses a REDDCRYPT gateway. The disadvantage of this variant is that neither the sender nor the recipient can access the emails via the REDDCRYPT applications.

HTTP requests

Has public key

The application can use the API HasPublicKey to determine whether a public key (or a REDDCRYPT account) is available for encryption for a specific recipient. If a public key is available, the email can be encrypted directly for the recipient. If no public key is available for the recipient, a One Time Encryption Key must be transferred when encrypting the email. Optionally, the REDDCRYPT gateway can also generate a random One Time Encryption Key during encryption.

Request:

  • Url: /v1/public-keys/exists
  • Method: POST
  • Parameters:
{
  "address": "recipient@mail.com"
}

Response:

{
  "hasKey": true
}

Encrypt Mail

To encrypt an email, it is sent to the REDDCRYPT gateway using an Multipart Form Data request. Additional fields with optional parameters can be transferred. If the application and the REDDCRYPT Gateway can access a shared file system, the emails can also be transferred via the file system (see API example).

Request:

  • Url: /v1/mails/encrypt
  • Method: POST
  • Parameters:
    • OneTimeEncryptionKey
      If no public key for encryption is available for a recipient, this parameter can be used to transfer a One Time Encryption Key with which the REDDCRYPT Gateway should encrypt the e-mail.
    • EnableOtekGeneration
      If this parameter is set to true, a random One Time Encryption Key is generated when the email is encrypted if no public key for encryption is available for a recipient and no One Time Encryption Key has been transferred.
    • SendAfterEncryption
      If this parameter is set to true, the email is transferred directly to the REDDCRYPT Cloud Service after encryption and sent to the recipients. The email is then immediately visible to all recipients in the REDDCRYPT applications.

Response: 

{
  "transactionId": "eed81c40-eb9c-4453-a6b4-c40e4e12194e",
  "recipientAddress": "C07B806E33D42EEF@smtp.staging.reddcrypt.com"
}

Download Transaction

For transmission via SMTP, the encrypted email must be retrieved from the REDDCRYPT Gateway via a simple download and then sent to the REDDCRYPT Cloud Service via SMTP.

Important: Each transaction can only be downloaded once. The encrypted email is deleted by the REDDCRYPT Gateway after the first download.

Request:

  • Url: /v1/download/transacion/{TRANSACTION_ID}
  • Method: GET

Response:

  • File-Download of the REDDCRYPT Transport Mail.

API to decrypt the email

Decrypting emails encrypted with REDDCRYPT is very easy with the REDDCRYPT Gateway.
The encrypted email is transmitted to the gateway either via a simple multipart form data HTTP request or as a file name. The latter requires the gateway to be able to access the file.

HTTP requests

Decrypt Mail

To decrypt an email, a REDDCRYPT Transport Mail or a redddcrypt.securemail file can simply be sent to the REDDCRYPT gateway using a Multipart Form Data request. Additional fields with optional parameters can be transferred. If the application and the REDDCRYPT Gateway can access a shared file system, the mails can also be transferred via the file system (see API example).

Request:

  • Url: /v1/mails/encrypt
  • Method: POST
  • Parameters:
    • OneTimeEncryptionKey
      This parameter can be used to transfer an One Time Encryption Key which the REDDCRYPT gateway can use to decrypt the email. This parameter is not required for most applications.

Response:

{
  "transactionId": "d602519a-d420-41fb-bd6b-305c05099684",
  "signatureStatus": "Valid"
}

Download Transaction

The decrypted email can be retrieved from the REDDCRYPT Gateway via a simple download.

Important: Each transaction can only be downloaded once. The encrypted email is deleted by the REDDCRYPT Gateway after the first download.

Request:

  • Url: /v1/download/transacion/{TRANSACTION_ID}
  • Method: GET

Response:

  • File download of the decrypted email.

API examples for the use of the REDDCRYPT Gateway API

The examples are all described using the command line program curl for illustration purposes. In these examples, the requests are sent to the REDDCRYPT gateway via HTTP. HTTPS should always be used in a production environment.

General information

Simple API requests are executed as JSON web requests. The content type must be specified as application/json. 

Content-Type: application/json

Only the transfer of emails for encryption or decryption takes place via Multipart Form Data. In this case, multipart/form-data must be specified as the content type. 

Content-Type: multipart/form-data

Authentication

Authentication on the REDDCRYPT Gateway is carried out using an API key. If several applications use a REDDCRYPT Gateway, it is recommended to use a separate API key for each application. The API keys can be easily generated via the WEB UI of the REDDCRYPT Gateway.

API keytransferred as bearer token

The recommended variant is to use the API key as a bearer token. In this case, the API key is simply transferred as an HTTP header field with every request for authentication.

Example:

Authorization: Bearer sJYCmwaWaGPY4c0gOFECT99jUZkWvvbX

Basic authentication with API key

Alternatively, authentication with an API key can also be carried out using Basic Authentication. In this case, the API key is transferred as the user name and the password remains empty.

Example requests for encryption

The application should check whether a public key is available for each recipient of an email before encrypting it. If no public key is available for a recipient of the email, a One Time Encryption Key is required when encrypting the email.

Check whether a public key is available for a recipient address:

curl -s -X POST \
    -H 'Authorization: Bearer sJYCmwaWaGPY4c0gOFECT99jUZkWvvbX' \
    -H 'Content-Type: application/json' \
    -d '{"Address":"recipient@mail.com"}' \
    http://localhost:8025/v1/public-keys/exists

Response:

{
  "hasKey": false
}

Encrypting and sending emails

The REDDCRYPT Gateway can automatically transfer the email to the REDDCRYPT Cloud Service directly after encryption. In this case, the email is sent to the recipients by the REDDCRYPT Cloud Service. This is the easiest way to send encrypted emails.

In this example, the mail is transferred to the REDDCRYPT gateway via Multipart Form Data.

curl -s -X POST \
    -H 'Authorization: Bearer sJYCmwaWaGPY4c0gOFECT99jUZkWvvbX' \
    -H 'Content-Type: multipart/form-data' \
    -F 'sendAfterEncryption=true' \
    -F 'message=@plain.eml' \
    http://localhost:8025/v1/mails/encrypt

Response:

{
  "transactionId": "740f3c1f-67c1-45cf-8ee4-73672f3e61ad"
}

Encrypt email only, do not send

If the application itself is to send the data via SMTP, this is also possible.

curl -s -X POST \
    -H 'Authorization: Bearer sJYCmwaWaGPY4c0gOFECT99jUZkWvvbX' \
    -H 'Content-Type: multipart/form-data' \
    -F 'message=@plain.eml' \
    http://localhost:8025/v1/mails/encrypt

Response:

{
  "transactionId": "740f3c1f-67c1-45cf-8ee4-73672f3e61ad",
  "recipientAddress": "C07B806E33D42EEF@smtp.staging.reddcrypt.com"
}

Retrieve encrypted email

The Transaction ID can be used to retrieve the encrypted email directly from the gateway.

curl -s -X GET \
    -H 'Authorization: Bearer sJYCmwaWaGPY4c0gOFECT99jUZkWvvbX' \
    -o 'encrypted.eml' \
    http://localhost:8025/v1/mails/encrypt

The REDDCRYPT transport mail is returned as the response, which must then be sent by the application itself via SMTP.

Encrypting with OTEK

If the email needs to be encrypted for a recipient who does not yet have a REDDCRYPT account – and therefore no public key – this email is encrypted for this recipient with a One Time Encryption Key (one-time password). The One Time Encryption Key can either be specified by the application or generated by the REDDCRYPT Gateway.

Encrypt with specified One Time Encryption Key

curl -s -X POST \
    -H 'Authorization: Bearer sJYCmwaWaGPY4c0gOFECT99jUZkWvvbX' \
    -H 'Content-Type: multipart/form-data' \
    -F 'oneTimeEncryptionKey=S0m3S3cr3tK3y' \
    -F 'message=@plain.eml' \
    http://localhost:8025/v1/mails/encrypt

Reponse:

{
  "transactionId": "740f3c1f-67c1-45cf-8ee4-73672f3e61ad",
  "recipientAddress": "C07B806E33D42EEF@smtp.staging.reddcrypt.com"
}

Encrypt with random One Time Encryption Key

curl -s -X POST \
    -H 'Authorization: Bearer sJYCmwaWaGPY4c0gOFECT99jUZkWvvbX' \
    -H 'Content-Type: multipart/form-data' \
    -F 'enableOtekGeneration=true' \
    -F 'message=@plain.eml' \
    http://localhost:8025/v1/mails/encrypt

Reponse:

{
  "transactionId": "740f3c1f-67c1-45cf-8ee4-73672f3e61ad",
  "recipientAddress": "C07B806E33D42EEF@smtp.staging.reddcrypt.com",
  "oneTimeEncryptionKey": "S0m3S3cr3tK3y"
}

Transfer email with file name

It is possible to transfer the email to be encrypted as a file reference. In this case, only a file name with a complete path is transferred to the REDDCRYPT Gateway to encrypt an email.

If the email is not to be sent directly by the REDDCRYPT Gateway but by the application, a second file name must also be transferred. The REDDCRYPT Gateway then saves the REDDCRYPT Transport Mail in this file.

Important: The files are not deleted by the REDDCRYPT Gateway. The application must ensure that the files are deleted after processing. 

curl -s -X POST \
    -H 'Authorization: Bearer sJYCmwaWaGPY4c0gOFECT99jUZkWvvbX' \
    -H 'Content-Type: application/json' \
    -F 'sendAfterEncryption=false' \
    -F 'inFileName=/path/to/plain.eml' \
    -F 'outFileName=/path/to/encrypted.eml' \
    http://localhost:8025/v1/mails/encrypt

Response:

{
  "transactionId": "740f3c1f-67c1-45cf-8ee4-73672f3e61ad"
}

Example requests for decryption

Below you will find some examples of how to decrypt emails with the REDDCRYPT Gateway Service.

Decrypt email

To decrypt, a REDDCRYPT Transport Mail or reddcrypt.securemail file is simply sent to the REDDCRYPT gateway using a Multipart Form Data request.

In this example, the email is transferred to the REDDCRYPT gateway via Multipart Form Data.

curl -s -X POST \
    -H 'Authorization: Bearer sJYCmwaWaGPY4c0gOFECT99jUZkWvvbX' \
    -H 'Content-Type: multipart/form-data' \
    -F 'message=@encrypted.eml' \
    http://localhost:8025/v1/mails/decrypt

Reponse:

{
  "transactionId": "99db0101-160b-45e2-af8c-5830589c651e",
  "signature": "Valid"
}

Transfer email with file name

It is possible to transfer the email to be decrypted as a file reference. In this case, only a file name with a complete path is passed to the REDDCRYPT Gateway to decrypt an email.

In addition, a second file name is required with which the REDDCRYPT Gateway saves the decrypted file.

Important: The files are not deleted by the REDDCRYPT Gateway. The application must ensure that the files are deleted after processing. 

curl -s -X POST \
    -H 'Authorization: Bearer sJYCmwaWaGPY4c0gOFECT99jUZkWvvbX' \
    -H 'Content-Type: application/json' \
    -F 'inFileName=/path/to/encrypted.eml' \
    -F 'outFileName=/path/to/plain.eml' \
    http://localhost:8025/v1/mails/decrypt

Response:

{
  "transactionId": "99db0101-160b-45e2-af8c-5830589c651e",
  "signature": "Valid"
}

Decryption with OTEK

If the encrypted email was encrypted with a One Time Encryption Key and the REDDCRYPT Gateway does not have a suitable private key to decrypt the email, the One Time Encryption Key can also be transferred for decryption. This scenario is not required for normal applications.

curl -s -X POST \
    -H 'Authorization: Bearer sJYCmwaWaGPY4c0gOFECT99jUZkWvvbX' \
    -H 'Content-Type: multipart/form-data' \
    -F 'oneTimeEncryptionKey=S0m3S3cr3tK3y' \
    -F 'message=@encrypted.eml' \
    http://localhost:8025/v1/mails/decrypt

Response:

{
  "transactionId": "99db0101-160b-45e2-af8c-5830589c651e",
  "signature": "Valid"
}

Try for free
This site is registered on wpml.org as a development site. Switch to a production site key to remove this banner.