Use CipherText properties in functions and actions

Use of Cipher in functions requires an Operational User License. If checkpoints are configured for this operation (hashing, encrypting, decrypting), the license must be allowed to bypass checkpoints.

You can use functions code repositories to work with CipherText object properties, for example to encrypt or decrypt values in bulk. To get started, follow the function-backed actions tutorial.

Decryption is available in the TypeScript and Python OSDKs and in Java OSDK 2.0.0 release candidates starting with 2.0.0-rc3. Encryption (writing a new value) is available in the TypeScript and Python OSDKs. The Java OSDK supports decryption only; Java OSDK 1.x does not support CipherText properties.

The examples below use an EncryptedCustomer object with the following properties:

  • An encrypted CipherText name
  • A unique, unencrypted integer id

The examples use two functions:

  • decryptEncryptedCustomer() takes an EncryptedCustomer object and returns the plaintext name.
  • updateEncryptedName() takes an EncryptedCustomer object and a newName, and updates the object's encrypted name to newName.

The Encrypted Customer object type with an encrypted Name property and an integer Id property.

Decrypt CipherText properties

The following example decrypts and returns the name property of an EncryptedCustomer object.

Copied!
1 2 3 4 5 6 7 import { Function, Integer, OntologyEditFunction, Edits } from "@foundry/functions-api"; import { Objects, EncryptedCustomers } from "@foundry/ontology-api"; @Function() public async decryptEncryptedCustomer(customer: EncryptedCustomers): Promise<string | undefined> { return await customer.name?.decryptAsync(); }
Copied!
1 2 3 4 5 6 7 8 9 10 11 import { Osdk } from "@osdk/client"; import { EncryptedCustomer } from "@ontology/sdk"; export const config = { apiName: "decryptEncryptedCustomer" }; async function decryptEncryptedCustomer(customer: Osdk.Instance<EncryptedCustomer>): Promise<string | undefined> { return await customer.name?.decrypt(); } export default decryptEncryptedCustomer;
Copied!
1 2 3 4 5 6 7 from ontology_sdk import FoundryClient client = FoundryClient() customer = client.ontology.objects.EncryptedCustomer.get(123) if customer is None: raise ValueError("Customer not found") plaintext = customer.name.decrypt() if customer.name is not None else None
Copied!
1 2 3 4 5 6 7 8 String plaintext = client.ontology() .objects() .EncryptedCustomer() .fetch(123) .orElseThrow() .name() .orElseThrow() .decrypt();

Update CipherText properties

The following example updates the name property of an EncryptedCustomer object. Running this function in preview does not edit the object. The function in the TypeScript v1 example, like any function that updates objects, must be annotated with @OntologyEditFunction() and @Edits(EncryptedCustomers).

The Java OSDK supports decryption only and cannot write new CipherText values.

Copied!
1 2 3 4 5 6 7 8 import { Function, Integer, OntologyEditFunction, Edits } from "@foundry/functions-api"; import { Objects, EncryptedCustomers } from "@foundry/ontology-api"; @OntologyEditFunction() @Edits(EncryptedCustomers) public async updateEncryptedName(customer: EncryptedCustomers, newName: string): Promise<void> { await customer.name?.updateAsync(newName); }
Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 import { Client, Osdk } from "@osdk/client"; import { createEditBatch, Edits } from "@osdk/functions"; import { EncryptedCustomer } from "@ontology/sdk"; type OntologyEdit = Edits.Object<EncryptedCustomer>; export default function updateEncryptedName( client: Client, customer: Osdk.Instance<EncryptedCustomer>, newName: string): OntologyEdit[] { const batch = createEditBatch<OntologyEdit>(client); batch.update(customer, { name: { plaintext: newName, } }); return batch.getEdits(); }
Copied!
1 2 3 4 5 6 7 8 9 10 11 from functions.api import function from foundry_sdk_runtime import OntologyEdits from ontology_sdk import FoundryClient from ontology_sdk.ontology.objects import EncryptedCustomer @function(edits=[EncryptedCustomer]) def update_encrypted_name(customer: EncryptedCustomer, new_name: str) -> OntologyEdits: edits = FoundryClient().ontology.edits() editable_customer = edits.objects.EncryptedCustomer.edit(customer) editable_customer.name.set(plaintext=new_name) return edits.get_edits()

Cipher Channel selection strategies

To create a new encrypted value or update an existing value, you must select a Cipher Channel.

  • For creation, a default Cipher Channel must be configured on the CipherText property. The Channel selection strategy is ignored in this case.
  • For updates, either a default Cipher Channel or the preexisting Channel used to encrypt the previous value can be used to encrypt the CipherText property.

To control update behavior, specify one of the four Cipher Channel selection strategies. If no strategy is specified, PREFER_EXISTING is used.

  • Prefer existing (PREFER_EXISTING): The default strategy. Use the Channel from the existing encrypted value; if the value is not yet encrypted, fall back to the property's default Channel. Fails if neither is available.
  • Prefer default (PREFER_DEFAULT): Use the property's default Channel; if none is configured, fall back to the Channel from the existing encrypted value. Fails if neither is available.
  • Default only (DEFAULT_ONLY): Use the property's default Channel only, and fail if no default Channel is configured.
  • Existing only (EXISTING_ONLY): Use the Channel from the existing encrypted value only, and fail if the value is not yet encrypted.

The following examples encrypt newName using the PREFER_DEFAULT strategy. Substitute any of the four values above to change the Channel resolution behavior.

Copied!
1 2 3 4 5 import { CipherChannelStrategy } from "@foundry/functions-api"; await customer.name?.updateAsync(newName, { cipherChannelStrategy: CipherChannelStrategy.PREFER_DEFAULT, });
Copied!
1 2 3 4 5 6 batch.update(customer, { name: { plaintext: newName, strategy: "PREFER_DEFAULT", } });
Copied!
1 2 3 4 editable_customer.name.set( plaintext=new_name, cipher_channel_strategy="PREFER_DEFAULT", )