CodamAIDocs
Topicdone

Retention, legal hold and erasure

How long CRMS keeps a final document, how a legal hold blocks erasure, how erasure works, and which roles may do what.

Variants
retention runningretention endedlegal hold seterasure by the retention passerasure on request (GDPR Art. 17)

What this is about

A final document stays as long as the law requires, and no longer. This period is called retention. While it runs, nobody can erase the document. Afterwards CRMS erases it on its own.

A legal hold keeps a document in addition, for example because a lawsuit is running. As long as it applies, nothing is erased, not even after the retention has ended.

The retention period

  • It is set in CODAMAI_CRMS_DOCUMENT_RETENTION as an ISO 8601 period, for example P10Y for ten years, or P6Y6M.
  • There is no default. As long as document revisions are on, CRMS does not start without it. How long records are kept is a legal obligation of the operator (GoBD, HGB, GMP …). A guessed value erases too early or keeps personal data too long.
  • When storing, CRMS computes retainUntil = time of storing (UTC) + period and writes the result into the revision. It locks the object in the storage with the same date.

The life of a revision

stateDiagram-v2
  [*] --> Kept: FINAL stored
  Kept --> Held: legal hold set
  Held --> Kept: legal hold released
  Kept --> Erasable: retainUntil reached
  Held --> Held: retainUntil reached
  Erasable --> Held: legal hold set
  Erasable --> Tombstone: erased
  Tombstone --> [*]
  • It applies to the whole chain: all revisions that still have bytes, and also every revision that is stored while it applies.
  • It is recorded in the chain as an entry LEGAL_HOLD_SET and set in the storage as an S3 legal hold on every object.
  • Setting and releasing it requires a reason as a key, for example litigation-hold and litigation-ended.
Request
POST /crms/documents/7c1e…/legal-hold
{ "reason": "litigation-hold" }
Response
204 No Content

The revision in the address only selects the chain. The hold then applies to all its revisions. You release it with POST /crms/documents/{revision}/legal-hold/release, also with a reason.

CaseAnswer
set a hold while one already applies409 document-legal-hold-active
release a hold while none applies409 document-legal-hold-inactive

When a revision can be erased

Revision already erased?Legal hold on the chain?retainUntil reached?What happens on erasure
yes––410 document-erased
noyes–409 document-legal-hold-active
nonono409 document-retention-active
nonoyesbytes deleted, key destroyed, tombstone stays

There is no way to erase before the retention ends. If CRMS tried, the storage would refuse it (document-locked).

What happens on erasure

  1. 1
    CRMS
    checks legal hold and retention, as in the table above
  2. 2
    CRMS→File storage
    deletes exactly the object's version
  3. 3
    CRMS→Database
    destroys the document key. Its row stays as a tombstone, and the journal gets document-key-destroyed
  4. 4
    CRMS→Database
    appends an entry ERASED with user and reason to the chain and writes document-erased into the journal
    Result: From now on reading answers 410 document-erased. The chain still verifies as intact

The encrypted payload is in the database. It becomes unreadable with the same key. This kind of erasure by destroying the key is called crypto-shredding.

Two ways to erase

Who erases

When: the normal case, the retention has expired

  1. 1
    CRMS
    works through the work list every CODAMAI_CRMS_RETENTION_INTERVAL (default PT24H), first in the system, then in every tenant
  2. 2
    CRMS
    erases every revision that is due, user crms-retention, reason retention-expired
  3. 3
    CRMS
    leaves revisions under a legal hold on the list, the next pass tries again
    Result: Revisions that were due are tombstones

When: someone requests erasure, for example under GDPR Art. 17, and no retention obligation stands in the way any more

  1. 1
    Client→CRMS
    sends POST /crms/documents/{revision}/erase with {"reason": "data-subject-request"}
  2. 2
    CRMS
    checks role, legal hold and retention as above
  3. 3
    CRMS→Client
    answers 204
    Result: The revision is a tombstone, and the requester is recorded as the user in the chain

Like the anchoring pass, the retention pass runs in every instance with CODAMAI_CRMS_SCHEDULING_ENABLED=true and reaches all tenants that CIAS knows, suspended and closed ones too.

Who may do what

CallRole (default)Variable
set and release a legal holdcrms-document-custodianCODAMAI_CRMS_REST_DOCUMENT_ROLES_HOLD
erasecrms-document-eraserCODAMAI_CRMS_REST_DOCUMENT_ROLES_ERASE

If the role is missing, CRMS answers 403 document-access-denied before it even looks for the document. So a refusal does not reveal whether the document exists. The full list of roles is in Roles.

Pitfalls

Next

Search