Introduction

This technical note outlines the process of encrypting a JSON value and representing the result in a JSON object.

The intent of this structure is to conform to the specifications issued by the WOES IETF working group. Therefore, as their specifications evolve, so too shall this technical note, as well as OpenIDM's implementation. Meanwhile, an interim format "x-simple-encryption" will be implemented.

The following data structure can be used for transmitting encrypted values to OpenIDM, as well how managed object properties are encrypted when stored in the repository.

Usage

root object

{
  "$crypto": {
    "type": "x-simple-encryption",
    "value": any value
  }
}

The "$crypto" property indicates that the value of the object is encrypted. When decrypted, the decrypted value should replace the entire object.

"type": string, required
The type of cryptographic representation contained in the associated value. Currently, the only supported representaiton is "x-simple-encryption", which is temporary until WOES codifies a standardized representation.

"value": any value, required
A value (usually a JSON object) that corresponds to the specified type. For the "x-simple-encryption" type, the value is a simple-encryption object, described below.

simple-encryption object

A JSON object that represents a simple encryption of a JSON value.

{
  "cipher": string,
  "key": string or key object,
  "iv": string,
  "data": string
}

"cipher": string, required
The full transformation that was used to encrypt the property value, specified per the Java Cryptographic Extension. Example: "AES/CBC/PKCS5Padding".

"key": string or session-key object, required
The alias of the symmetric key that should be used to decrypt the data (as string), or a session-key object that represents the symmetric key material, encrypted using a public key (as session-key object).

"iv": string, optional
The initialization vector applied when a cipher block chaining cipher (CBC) mode was used. Contains the binary octet string of the IV encoded in Base64. If CBC is used, this value MUST be provided.

"data": string, required
The encrypted data. Produced by encrypting the serialized JSON value and Base64 encoding the result.

session-key object

A JSON object that represents the symmetric key material that was used to encrypt the data, which in turn was encrypted with a public key.

{
  "cipher": string,
  "key": string,
  "data": string
}

"cipher": string, required
The transformation that was used to encrypt the session key, specified per the Java Cryptographic Extension. Example: "RSA/ECB/OAEPWithSHA1AndMGF1Padding".

"key": string, required
The alias of the private key that should be used to decrypt the session key.

"data": string, required
The encrypted session key. Produced by encrypting the symmetric key bytes and Base64 encoding the result.