---
# System prepended metadata

title: Key handling & rotation in CARO

---

# Key handling & rotation in CARO

## Problem statement
- key material is highly confidential
- access to the app can be leveraged to issue forged credentials that are totally valid
- leaked key material is not traceable when it's in the hand of the wrong persons
    - ~~could some kind of second factor help here? E.x. periodically ask for confirmation with the selected key~~
- activity with that key material may not even be visible
- in case of a leaking signing key of an issuer did, you would need to revoke all credentials that have been issued by that key
    - huge risk of single point of failure
    - reissuance is a big task


# Definitions
- *key rotation* means the DID remains the same, verification and/or authorization keys within DID document are exchanged

# Requirements

- OCI mandates rotation after 1 Year (subject to change) + rotation after a set amount of public key material has been distributed ([NFR004](https://open-credentialing-initiative.github.io/Digital-Wallet-Conformance-Criteria/latest/#oci-non-functional-wallet-features))

## Ideas


- KMS should be used so that key material cannot leak from our systems
    - monitor usage on KMS
        - cross check usage with our application
    - only misuse would be possible on our side (somebody gaining access to our applications/infrastructure)
    - KMS could sit centrally with us (custodial service) or be customer's own KMS that connects to CARO
- revocation methods should allow retrospective revocation
    - today I revoke a credential for today minus 1 day
    - reverification will happen and show transaction from yesterday as invalid even though the system worked as intended
        - this could enable alerts, that transactions that happened didn't meet the legal requirements
- enable automatic key rotation (routine task, happy path)
    - time- and/or usage-based trigger
    - replace signing key in DID with newly generated one
    - verification should happen by getting DID from time of issuance of the VC/VP
- split authorization & signing key on/after did creation
    - to minimize risk


- smart contracts
    - 1. contract
        - publication of VC hashes on chain
            - implicitly links a VC to a timestamp of issuance
    - 2. contract
        - revocation method
        - registers timestamp with revocation entries
            - system uses the current timestamp
        - allows revocation with timestamp
            - user supplies timestamp
            - revokes credentials from that point on forward

## Flows

### VC issuance flow

1. issuer prepares credential as usual (prepare body)
2. register revocation entry on smart contract number 2
    3. Ask SC for some index which is then used in the credentialStatus of the VC 
4. hash body of VC
5. register the hash on smart contract 1
6. issue credential to holder

### VP verification flow

1. look up VP issuer DID
2. verify VP signature with VP issuer DID verification key material
3. extract VC from VP
4. hash VC
5. look up hash on smart contract 1 & get timestamp
6. look up VC issuer DID at VC issuance time (2.)
7. verify VC signature with VC issuer DID verification key material
8. resolve revocation by
    8.1. current time
    8.2. VC issuance time? What value does that bring