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:
nameidThe 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 following example decrypts and returns the name property of an EncryptedCustomer object.
Copied!1 2 3 4 5 6 7import { 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 11import { 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 7from 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 8String plaintext = client.ontology() .objects() .EncryptedCustomer() .fetch(123) .orElseThrow() .name() .orElseThrow() .decrypt();
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 8import { 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 18import { 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 11from 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()
To create a new encrypted value or update an existing value, you must select a Cipher Channel.
To control update behavior, specify one of the four Cipher Channel selection strategies. If no strategy is specified, PREFER_EXISTING is used.
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): 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): Use the property's default Channel only, and fail if no default Channel is configured.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 5import { CipherChannelStrategy } from "@foundry/functions-api"; await customer.name?.updateAsync(newName, { cipherChannelStrategy: CipherChannelStrategy.PREFER_DEFAULT, });
Copied!1 2 3 4 5 6batch.update(customer, { name: { plaintext: newName, strategy: "PREFER_DEFAULT", } });
Copied!1 2 3 4editable_customer.name.set( plaintext=new_name, cipher_channel_strategy="PREFER_DEFAULT", )