State

The Utila CLI uses a sophisticated state system to securely handle sensitive vault data that needs to persist across sessions. This includes device private keys and key shares—all protected through configurable encryption and flexible storage options.

Overview

State in Utila CLI refers to the persistent storage of sensitive cryptographic data required for vault operations. The system is built on two independent layers that can be configured separately to match your security and infrastructure requirements.

Flexible Storage

Store your encrypted state locally, in cloud storage solutions like AWS S3 and Google Cloud Storage, or using custom file paths.

Enterprise Security

Choose between passphrase-based encryption or integrate with cloud KMS providers for enterprise-grade key management.

Architecture

Physical Storage Location

The storage layer determines where your encrypted state files are physically stored. This is completely independent of how they're encrypted.

Local Filesystem

Default location: ~/.utila/state
Custom local paths: /custom/path/to/state
File URL scheme: file:///absolute/path/to/state
No network dependencies
Immediate access for single-user scenarios

Cloud Storage

AWS S3: s3://bucket-name
Google Cloud Storage: gs://bucket-name
Enables cross-device access and team collaboration
Built-in redundancy and high availability

What Gets Stored

The state system manages several types of sensitive data:

Device Private Keys

Cryptographic keys that uniquely identify your device within the vault system. These keys are essential for device authentication and authorization within the vault infrastructure.

Key Shares

Distributed cryptographic components used in threshold cryptography schemes. These shares work together to perform vault operations while ensuring no single component can compromise the system.

Configuration

State configuration follows a clear precedence hierarchy, allowing for flexible deployment patterns:

Storage Location Priority

Command-line flag: --state-location
Environment variable: UTILA_STATE_LOCATION
Configuration file setting
Default: ~/.utila/state

Supported Location Formats:

Local directory: ~/.utila/state or /absolute/path/to/state
File URL scheme: file:///absolute/path/to/state
AWS S3: s3://bucket-name
Google Cloud Storage: gs://bucket-name

Encryption Provider Priority

Command-line flag: --state-encryption-provider
Environment variable: UTILA_STATE_ENCRYPTION_PROVIDER
Configuration file setting
Default: Passphrase-based encryption

Security Model

Encryption at Rest

All state data uses AES-256 encryption before storage. Encryption happens locally within the CLI, ensuring sensitive information never exists in plaintext outside your device.

Access Control

Security is enforced through multiple layers:

Local storage: Filesystem permissions and device security
Cloud storage: IAM policies, bucket permissions, and network controls
KMS encryption: Key access policies and usage auditing
Passphrase encryption: User-controlled key derivation

Key Management

When using KMS providers:

Encryption keys remain within your cloud account
Utila CLI never has direct access to master keys
All key usage is logged and auditable
Automatic key rotation policies can be configured
Hardware Security Modules (HSMs) provide additional protection

Available Operations

The CLI provides several commands for state management:

utila state info

Shows current state configuration including storage location, encryption provider, and connection status.

utila state list

Lists all files in your state storage with encryption status and metadata.

utila state move

Migrates state between storage locations while preserving data integrity.

utila state encrypt

Re-encrypts state with a different provider or updates encryption keys.

Common Deployment Patterns

Individual Developer

Typical Setup:

Storage: Local filesystem (~/.utila/state)
Encryption: Passphrase-based
Use case: Personal development and testing

Simple setup with immediate access and no external dependencies.

Team Environment

Typical Setup:

Storage: Shared cloud bucket (s3://team-vault-state)
Encryption: KMS-based
Use case: Multiple developers accessing shared vaults

Enables secure collaboration with centralized key management and audit trails.

Production Systems

Typical Setup:

Storage: High-availability cloud storage
Encryption: KMS with automated rotation
Use case: Production vault operations

Enterprise-grade security with comprehensive monitoring and compliance features.

Troubleshooting

Storage Issues

Verify cloud credentials and IAM permissions
Check network connectivity and firewall rules
Ensure storage buckets exist and are accessible
Validate file path permissions for local storage

Encryption Problems

Confirm KMS key permissions and availability
Verify passphrase accuracy
Check for key rotation events or policy changes

Performance Considerations

Local storage provides fastest access times
Cloud storage may have latency depending on region
KMS operations add minimal overhead but require network access

Note: The state system is designed for resilience and recoverability. Regular testing of your configuration across different environments helps ensure reliable vault operations.