General Migration Questions

Here's what questions you should ask when migrating cryptographic content with minimal impact to production. You might need migrate when your secrets are compromised or your chosen algorithms are vulnerable.

I need to change secrets which are encrypted at rest. Or I need to change secrets that an untrusted party or client receives and later sends back to me. The client does not inspect the secret.

• Do your secrets identify what key was used?
• Are your secrets bound to some version or database column and row or purpose with authenticated encryption with associated data (AEAD)?
• Are your secrets encrypted by you and decrypted by you? If so, are you using an symmetric algorithm?
• Are your old secrets using authenticated encryption?
• Will you be using authenticated encryption in the future?
• How long will you accept old secrets?
• Are you able to replace old secrets?
• How long will you upgrade old secrets in place?

I need to change secrets which are shared between me and another party.

• What algorithms do you support?
• What algorithms does the other party support?
• If another party is encrypting or decrypting data, what key encapsulation mechanisms are supported and which symmetric algorithm is used for the message?
• Are there any content length limits on encrypted messages?
• Are there any content length limits on encryption keys?
• How long will it take you and the other party to coordinate an upgrade?

• Are your secrets encrypted by you and decrypted by someone else?
• If another party is decrypting data, are their public keys available and constantly fetched? How long do you cache their keys?
• Are your secrets encrypted by the other party and decrypted by you?
• If you are decrypting data from another party, are your public keys available and constantly fetched by that party? How long do they cache your keys?
• Is there an external standard you and the other party are implementing?

I need to change signed tokens that I give an untrusted party or client. Clients are not expected to inspect those tokens. Clients send these tokens back to the service which issued the token.

• Does the other party make assumptions on token length?
• Does your application, firewall, or any intermediary load balancer limit request sizes?
• Does your application internally limit token length?
• How does your application respond to receiving a truncated token?
• Does the other party behave identically if given a shorter or longer token?

I need to change signed tokens that I give an untrusted party or client. Clients are not expected to inspect those tokens. Clients send these tokens to other services which do not issue similar tokens.

• Are you using public keys?
• Are your public keys visible to services that receive those tokens?
• Are your public keys constantly fetched by those services? How long are the keys cached?
• Is there an external standard you and the other party are implementing?
• Does the other service make assumptions on token length?
• Does the other service's application, firewall, or any intermediary load balancer limit request sizes?
• How does the other service's application respond to receiving a truncated token?
• Does the other service's application behave identically if given a shorter or longer token?

Any last general questions to consider?

• Is there a key identifier embedded in the token or secret?
• Is there a version embedded in the token or secret?
• If there is a version or key identifier, is it bound to the signature or AEAD?
• Do your tokens or secrets include unique identifiers?
• Do your tokens or secrets expire?
• Are you using a library to encrypt your secrets or create signed tokens?
• Do you really need a signed token or an encrypted secret? Would application state and a unique 128-256 bit token suffice?
• Is the algorithm used bound to the key?
• Can you avoid orphaning old tokens and secrets during the migration?