One storage API for Google Drive, Nextcloud, and S3-compatible clouds, in TypeScript and Python.
TypeScript byoccloud-storagecloudflare-r2encryptiongoogle-drivenextcloudoauth2pkcepythons3sdkstoragetypescriptwebdav
{
"$comment": "BYOC E2EE envelope conformance vectors. The envelope is a binary format written into the user's cloud; a one-byte disagreement between SDKs makes encrypted files permanently unreadable. V3 uses independently authenticated frames for bounded-memory streaming. All hex is lowercase.",
"version": 2,
"algorithm": {
"cipher": "AES-256-GCM",
"kdf": "PBKDF2-HMAC-SHA256",
"key_length_bytes": 32,
"salt_length_bytes": 16,
"iv_length_bytes": 12,
"tag_length_bytes": 16,
"iter_field_length_bytes": 4,
"iter_field_encoding": "uint32 big-endian",
"v3_header_length_bytes": 44,
"v3_frame_prefix_bytes": 20
},
"iteration_bounds": {
"min": 10000,
"max": 2000000,
"$comment": "Read from untrusted storage before the GCM tag can authenticate it, so it MUST be range-checked before key derivation. Out-of-range MUST raise BYOC_CORRUPTED_DATA without deriving a key."
},
"layouts": {
"V3": [
"MAGIC(12)",
"ITER(4)",
"FRAME_SIZE(4)",
"SALT(16)",
"NONCE_BASE(8)",
"FRAME_LEN(4) || TAG(16) || CIPHERTEXT(FRAME_LEN), repeated"
],
"V2": [
"MAGIC(12)",
"ITER(4)",
"SALT(16)",
"IV(12)",
"TAG(16)",
"CIPHERTEXT(n)"
],
"V1": [
"MAGIC(12)",
"SALT(16)",
"IV(12)",
"TAG(16)",
"CIPHERTEXT(n)"
]
},
"aad": {
"V3": "HEADER(44) || FRAME_INDEX(uint32 BE) || IS_FINAL(1 byte)",
"V2": "MAGIC || ITER || SALT",
"V1": "MAGIC || SALT"
},
"vectors": [
{
"name": "V3 framed envelope, one final frame",
"version": "V3",
"magic": "BYOC_E2EE_V3",
"passphrase": "correct-horse-battery-staple",
"iterations": 600000,
"frame_size": 4096,
"salt_hex": "000102030405060708090a0b0c0d0e0f",
"nonce_base_hex": "1011121314151617",
"iv_hex": "101112131415161700000000",
"plaintext_utf8": "BYOC cross-SDK conformance payload",
"derived_key_hex": "bd012c265e9e3c0931ca12018be26efe1b5d6355bc3c72acf8dbc0cb811a0107",
"tag_hex": "13920cc0a52936f7155064eca3f8dd5f",
"ciphertext_hex": "7c8ce52fb8e27382f23b4dca6c67d6d257cb189991acbd7ae2c50a1553f8738f5e5a",
"envelope_hex": "42594f435f453245455f5633000927c000001000000102030405060708090a0b0c0d0e0f10111213141516170000002213920cc0a52936f7155064eca3f8dd5f7c8ce52fb8e27382f23b4dca6c67d6d257cb189991acbd7ae2c50a1553f8738f5e5a"
},
{
"name": "V2 envelope, 600000 iterations",
"version": "V2",
"magic": "BYOC_E2EE_V2",
"passphrase": "correct-horse-battery-staple",
"iterations": 600000,
"salt_hex": "000102030405060708090a0b0c0d0e0f",
"iv_hex": "101112131415161718191a1b",
"plaintext_utf8": "BYOC cross-SDK conformance payload",
"derived_key_hex": "bd012c265e9e3c0931ca12018be26efe1b5d6355bc3c72acf8dbc0cb811a0107",
"tag_hex": "916a930f1fa3634ddd740310628ab2e7",
"ciphertext_hex": "d3b86f9e5c9d265790d4049ac15aee6e56e10d3494037e323a72e340c845b4b8a26d",
"envelope_hex": "42594f435f453245455f5632000927c0000102030405060708090a0b0c0d0e0f101112131415161718191a1b916a930f1fa3634ddd740310628ab2e7d3b86f9e5c9d265790d4049ac15aee6e56e10d3494037e323a72e340c845b4b8a26d"
},
{
"name": "V1 legacy envelope, 100000 iterations (no ITER field)",
"version": "V1",
"magic": "BYOC_E2EE_V1",
"passphrase": "correct-horse-battery-staple",
"iterations": 100000,
"salt_hex": "000102030405060708090a0b0c0d0e0f",
"iv_hex": "101112131415161718191a1b",
"plaintext_utf8": "BYOC cross-SDK conformance payload",
"derived_key_hex": "074ca47d1f67efe76642863fb039d88757c2b8d95f526ea9715a38f5bb48be1f",
"tag_hex": "085544119aca0f7ca23a49e03e0ed56f",
"ciphertext_hex": "69f189c19f923fbc74abaf18dd34226a241367f0e0a5fa3f4501c95fd0a7850b37b9",
"envelope_hex": "42594f435f453245455f5631000102030405060708090a0b0c0d0e0f101112131415161718191a1b085544119aca0f7ca23a49e03e0ed56f69f189c19f923fbc74abaf18dd34226a241367f0e0a5fa3f4501c95fd0a7850b37b9"
}
],
"rejection_cases": [
{
"name": "iteration count above maximum",
"mutate": {
"offset": 12,
"uint32_be": 2000000001
},
"expect_error": "BYOC_CORRUPTED_DATA",
"$comment": "MUST be rejected before key derivation; a conforming impl returns in well under a second."
},
{
"name": "iteration count below minimum",
"mutate": {
"offset": 12,
"uint32_be": 1
},
"expect_error": "BYOC_CORRUPTED_DATA"
},
{
"name": "unknown magic version",
"mutate": {
"offset": 0,
"ascii": "BYOC_E2EE_V9"
},
"expect_error": "BYOC_CORRUPTED_DATA"
},
{
"name": "in-range iteration tamper caught by AAD",
"mutate": {
"offset": 12,
"uint32_be": 664000
},
"expect_error": "BYOC_AUTH_REQUIRED",
"$comment": "Passes the range check, then fails the GCM tag: both layers must be present."
},
{
"name": "wrong passphrase",
"passphrase": "not-the-right-passphrase",
"expect_error": "BYOC_AUTH_REQUIRED"
},
{
"name": "truncated below header length",
"truncate_to": 20,
"expect_error": "BYOC_CORRUPTED_DATA"
}
]
}