232 lines
4.8 KiB
Markdown
232 lines
4.8 KiB
Markdown
# Admin Key Management for CCIP Contracts
|
|
|
|
**Date**: 2025-01-27
|
|
**Network**: ChainID 138 (DeFi Oracle Meta Mainnet)
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This document outlines best practices for managing admin keys for CCIP contracts on ChainID 138.
|
|
|
|
---
|
|
|
|
## Admin Functions
|
|
|
|
### CCIP Router Admin Functions
|
|
|
|
- `addSupportedChain(uint64 chainSelector)`
|
|
- `removeSupportedChain(uint64 chainSelector)`
|
|
- `addSupportedToken(uint64 chainSelector, address token)`
|
|
- `updateFees(uint256 baseFee, uint256 dataFeePerByte)`
|
|
- `changeAdmin(address newAdmin)`
|
|
- `withdrawFees(uint256 amount)`
|
|
- `withdrawNativeFees()`
|
|
|
|
### Bridge Admin Functions
|
|
|
|
- `addDestination(uint64 chainSelector, address receiverBridge)`
|
|
- `removeDestination(uint64 chainSelector)`
|
|
- `updateDestination(uint64 chainSelector, address receiverBridge)`
|
|
- `updateFeeToken(address newFeeToken)`
|
|
- `changeAdmin(address newAdmin)`
|
|
|
|
---
|
|
|
|
## Key Management Best Practices
|
|
|
|
### 1. Key Storage
|
|
|
|
**DO**:
|
|
- Use hardware wallets (Ledger, Trezor)
|
|
- Use secure key management systems (HSM, AWS KMS, Azure Key Vault)
|
|
- Store keys in encrypted format
|
|
- Use separate keys for different environments (testnet/mainnet)
|
|
- Implement key rotation procedures
|
|
|
|
**DON'T**:
|
|
- Store keys in plain text files
|
|
- Commit keys to version control
|
|
- Share keys via insecure channels
|
|
- Use same key for multiple purposes
|
|
- Store keys on shared systems
|
|
|
|
### 2. Access Control
|
|
|
|
**DO**:
|
|
- Implement multi-sig for admin functions
|
|
- Use role-based access control
|
|
- Require multiple approvals for critical changes
|
|
- Log all admin actions
|
|
- Monitor for unauthorized access
|
|
|
|
**DON'T**:
|
|
- Grant admin access to untrusted parties
|
|
- Skip approval processes
|
|
- Ignore access logs
|
|
- Allow unmonitored admin access
|
|
|
|
### 3. Key Rotation
|
|
|
|
**Procedure**:
|
|
|
|
1. **Generate New Key**
|
|
- Create new key pair
|
|
- Store securely
|
|
- Verify key works
|
|
|
|
2. **Transfer Admin**
|
|
```bash
|
|
cast send $CONTRACT \
|
|
"changeAdmin(address)" \
|
|
$NEW_ADMIN \
|
|
--rpc-url $RPC_URL \
|
|
--private-key $OLD_ADMIN_KEY
|
|
```
|
|
|
|
3. **Verify Transfer**
|
|
```bash
|
|
cast call $CONTRACT "admin()" --rpc-url $RPC_URL
|
|
```
|
|
|
|
4. **Revoke Old Key**
|
|
- Securely delete old key
|
|
- Update documentation
|
|
- Notify team
|
|
|
|
### 4. Emergency Procedures
|
|
|
|
**If Key is Compromised**:
|
|
|
|
1. **Immediate Actions**:
|
|
- Transfer admin to new secure key
|
|
- Review recent transactions
|
|
- Check for unauthorized changes
|
|
- Notify team and stakeholders
|
|
|
|
2. **Investigation**:
|
|
- Analyze access logs
|
|
- Identify compromise source
|
|
- Document incident
|
|
|
|
3. **Recovery**:
|
|
- Restore from backup if needed
|
|
- Revert unauthorized changes
|
|
- Implement additional security
|
|
|
|
---
|
|
|
|
## Multi-Sig Setup
|
|
|
|
### Recommended: Use Multi-Sig Wallet
|
|
|
|
For production deployments, use a multi-sig wallet:
|
|
|
|
1. **Deploy Multi-Sig**
|
|
- Use OpenZeppelin's MultiSigWallet
|
|
- Set required confirmations (e.g., 2 of 3)
|
|
- Add trusted signers
|
|
|
|
2. **Set Multi-Sig as Admin**
|
|
```bash
|
|
cast send $CONTRACT \
|
|
"changeAdmin(address)" \
|
|
$MULTISIG_ADDRESS \
|
|
--rpc-url $RPC_URL \
|
|
--private-key $DEPLOYER_KEY
|
|
```
|
|
|
|
3. **Use Multi-Sig for Admin Functions**
|
|
- Submit transactions through multi-sig
|
|
- Require multiple approvals
|
|
- Track all proposals
|
|
|
|
---
|
|
|
|
## Key Rotation Schedule
|
|
|
|
### Recommended Schedule
|
|
|
|
- **Quarterly**: Review key security
|
|
- **Annually**: Rotate keys (if no issues)
|
|
- **Immediately**: Rotate if compromised
|
|
- **After Incidents**: Rotate as part of recovery
|
|
|
|
---
|
|
|
|
## Monitoring
|
|
|
|
### Monitor Admin Actions
|
|
|
|
Track all admin function calls:
|
|
|
|
```bash
|
|
# Monitor admin changes
|
|
cast logs --address $CONTRACT \
|
|
"AdminChanged(address,address)" \
|
|
--rpc-url $RPC_URL
|
|
|
|
# Monitor configuration changes
|
|
cast logs --address $CONTRACT \
|
|
"DestinationAdded(uint64,address)" \
|
|
--rpc-url $RPC_URL
|
|
```
|
|
|
|
### Alerts
|
|
|
|
Set up alerts for:
|
|
- Admin changes
|
|
- Configuration changes
|
|
- Unusual admin activity
|
|
- Failed admin operations
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
### Required Documentation
|
|
|
|
1. **Key Inventory**: List all admin keys and their purposes
|
|
2. **Access Logs**: Maintain logs of all admin actions
|
|
3. **Rotation Records**: Document all key rotations
|
|
4. **Incident Reports**: Document security incidents
|
|
|
|
### Key Information to Document
|
|
|
|
- Key purpose (router admin, bridge admin, etc.)
|
|
- Key location (hardware wallet, HSM, etc.)
|
|
- Key holders (who has access)
|
|
- Last rotation date
|
|
- Next rotation date
|
|
|
|
---
|
|
|
|
## Compliance
|
|
|
|
### Audit Requirements
|
|
|
|
- Regular security audits
|
|
- Key management reviews
|
|
- Access control audits
|
|
- Incident response reviews
|
|
|
|
### Regulatory Considerations
|
|
|
|
- Follow industry best practices
|
|
- Maintain audit trails
|
|
- Implement proper controls
|
|
- Document procedures
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- [CCIP Security Guide](../security/CCIP_SECURITY.md)
|
|
- [CCIP Runbooks](CCIP_RUNBOOKS.md)
|
|
- [CCIP Monitoring](CCIP_MONITORING.md)
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-01-27
|
|
|