CloudCoin File Format 10

1. Scope and conformance

Format 10 is the wallet-internal encrypted file format for exactly one CloudCoin. The first byte of every CloudCoin .bin file selects its parser. A Format 10 reader MUST examine byte 0 before interpreting any other byte.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are normative.

• The physical file size MUST be exactly 612 bytes.
• The file MUST represent exactly one CloudCoin, 25 RAIDA identifiers, and 25 authenticity numbers (ANs).
• Only the 400 AN bytes are encrypted. Metadata, POWN, salt, nonce, and CRC remain plaintext.
• Every multi-byte integer is stored most-significant byte first (big-endian).
• There is no password verifier, authentication tag, recognizable encrypted constant, or plaintext structure inside the encrypted region.
• Decrypted ANs and stored POWN values remain untrusted until RAIDA validation.

2. Packet-style byte map

The large RAIDA identifier and ciphertext regions are collapsed. Their first and last entries are shown instead of drawing all 150 and 400 bytes.

3. Complete file layout

4. Encryption suite table

encryption_type identifies an immutable suite, not a software library. Different libraries conform when they produce the same Argon2id key and AES-CTR ciphertext for the same test vector.

The password is passed to Argon2id as its exact UTF-8 byte sequence. Software MUST NOT normalize Unicode, change case, trim whitespace, pad, truncate, or append a terminating NUL byte. Empty passwords and embedded NUL bytes are invalid.

The suite parameters are immutable. A different cipher, KDF, work factor, or key size requires another encryption_type value.

5. POWN encoding

POWN stores one four-bit status for each RAIDA. Even RAIDA indexes occupy the high nibble and odd indexes occupy the low nibble:

The low nibble of byte 28 MUST equal 0x9 and is not a twenty-sixth status. POWN is a readable cache, not proof of authenticity.

6. RAIDA identifier and AN mapping

Each six-byte RAIDA identifier, POWN nibble, and 16-byte AN share the same index n from 0 through 24.

RAIDA identifiers are unsigned 48-bit big-endian values and MUST be unique within the file. Duplicate identifiers are a format error.

7. AES-CTR encryption

The 400-byte plaintext is exactly the concatenation below. It contains no record header, padding, checksum, delimiter, tag, or recognizable constant.

The 12-byte nonce is stored at offsets 195–206. Format 10 fixes the initial counter at 1; it is not stored.

Nonce lifecycle

• A writer MUST obtain a fresh 12-byte nonce from the operating system cryptographic random source for every new encrypted representation.
• The nonce MUST NOT be derived from the password, salt, serial number, timestamp, filename, machine identity, or an external counter file.
• Every AN, POWN, or metadata rewrite MUST use a fresh nonce and regenerate all 400 ciphertext bytes.
• A failed write consumes its nonce. A retry MUST generate another nonce.
• Reading and byte-for-byte backup copying preserve the existing nonce because they do not create ciphertext.
• Changing the password MUST generate a new salt and nonce and re-encrypt all ANs.

8. CRC-32C

file_crc32c is calculated over exactly bytes 0–607 and stored big-endian at offsets 608–611.

9. Canonical processing

Read procedure

1. Read byte 0 and dispatch to this reader only when it equals 0x0A.
2. Require a physical size of exactly 612 bytes.
3. Validate CRC-32C, denomination, POWN padding, unique RAIDA identifiers, and a supported encryption suite.
4. Return metadata and POWN as untrusted when a metadata-only read is requested.
5. Derive the candidate AES key using the exact suite selected by byte 9.
6. Decrypt bytes 208–607 and split the result into 25 consecutive 16-byte candidate ANs.
7. Do not inspect candidate ANs for structure or report local password success or failure.
8. Query the corresponding RAIDA servers when validation is requested.
9. Permit persistent mutation only after the client confirmation policy is satisfied.

Write procedure

1. Require exactly one structurally valid CloudCoin and, for existing encrypted files, sufficient RAIDA confirmation for mutation.
2. Allocate and zero exactly 612 bytes, set byte 0 to 0x0A, and encode all metadata.
3. Select suite 0x05 by default. Select 0x06 only when reduced portability is accepted.
4. For a new file or password change, generate a new 16-byte salt. Preserve the salt for ordinary updates under the same password.
5. Generate a fresh 12-byte nonce, concatenate the ANs, and encrypt all 400 bytes.
6. Calculate CRC-32C and write the complete representation to an encrypted temporary file on the destination filesystem.
7. Before replacement, verify that the destination still exactly matches the representation originally read.
8. Flush and close the temporary file, then replace the destination using the safest operation supported by the filesystem.
9. Clear password, derived-key, plaintext-AN, and KDF intermediate buffers when no longer required.

RAIDA confirmation

The confirmation threshold is client policy and is not stored in Format 10. A failed or inconclusive candidate validation MUST NOT overwrite, delete, re-encrypt, rotate ANs, or persist POWN to the original file.

If usable RAIDA replies reject every candidate AN, the client MAY say: “The password may be incorrect, or the coin may be counterfeit.” Network failure is inconclusive.

Backup and export

• A normal encrypted backup copies all 612 bytes unchanged and remains protected by the wallet password.
• Recipient export is distinct from backup. After RAIDA validation, export writes the existing plaintext interoperable CloudCoin format.
• Format 10 is wallet-internal and MUST NOT be presented as a recipient-compatible plaintext export.

10. Security properties and limitations

Provided

• Confidentiality of the 25 ANs while the password-derived key remains secret.
• A single isolated file contains no password-dependent confirmation value.
• Portable decryption through immutable suite definitions.
• Accidental corruption detection through CRC-32C.

Not provided

• Cryptographic integrity or authenticity. AES-CTR ciphertext is malleable.
• A local determination that the supplied password is correct.
• Protection from malware, keyloggers, process-memory inspection, or a compromised host.
• Protection from deletion, denial of service, malicious rollback, or secure-deletion limitations of flash storage.
• Offline non-confirmability when an attacker knows a true AN or possesses historical versions containing unchanged ANs.
• Protection from online password testing through RAIDA.

11. Required interoperability tests

• Publish canonical 612-byte vectors for suites 0x05 and 0x06, including password, salt, nonce, derived key, counter blocks, ciphertext, and CRC.
• Verify identical results across selected libraries on Windows, macOS, Linux, Android, and iPhone.
• Test multibyte UTF-8 passwords without normalization.
• Test POWN indexes 0, 1, 23, and 24 and the final 0x9 padding nibble.
• Test RAIDA indexes 0 and 24, denominations -8 through +11, and big-endian serial/task identifiers.
• Reject duplicate RAIDA IDs, wrong sizes, trailing bytes, bad CRCs, and unsupported suites.
• Verify that a wrong password still produces exactly 400 untrusted candidate bytes with no local password verdict.
• Verify fresh nonces for AN-only, POWN-only, and metadata-only rewrites.

12. References

• NIST SP 800-38A — block cipher modes, including CTR
• RFC 9106 — Argon2id
• RFC 9588 — offline password-confirmation discussion