Castellan

5.6.0 verified Mon Apr 27 auth: no python

Castellan is a generic key management interface for OpenStack, providing a unified API to manage secrets (symmetric keys, certificates, passphrases) across different backends like Barbican or KMIP. Current version 5.6.0 targets Python >=3.10. Releases follow OpenStack cycle cadence.

pip install castellan

Common errors

error ImportError: cannot import name 'key_manager' from 'castellan' ↓

cause Incorrect import path; castellan.key_manager is a module, not a top-level attribute.

fix

Use: from castellan import key_manager

error castellan.key_manager.KeyManager object has no attribute 'store' ↓

cause KeyManager is a factory; you must call it to get a backend manager instance.

fix

km = key_manager.KeyManager(conf) then km.store(...)

error castellan.common.exception.KeyManagerError: Connection refused ↓

cause Barbican endpoint is unreachable or misconfigured.

fix

Check OS_AUTH_URL and OS_PROJECT_NAME environment variables, or provide correct barbican_url in config.

Warnings

breaking castellan 5.0.0 dropped support for Python versions <3.10. Ensure your environment uses Python 3.10+. ↓

fix Upgrade to Python >=3.10 or stay on castellan 4.x for Python 3.8/3.9 support.

deprecated The configuration option 'castellan_api_version' is deprecated since 3.0.0 and will be removed in a future release. Use 'backend' specific configuration instead. ↓

fix Switch to backend-specific config options like 'barbican_api_version' if using Barbican.

gotcha The KeyManager constructor expects a dictionary with specific keys (e.g., 'key_manager' for backend type). Passing a flat config won't work; use oslo.config or a nested dict. ↓

fix Use oslo.config's ConfigOpts or build nested dict as shown in the quickstart.

gotcha When storing a key, the context argument (e.g., 'default') is required and must match a backend context. Using None may lead to errors in certain backends. ↓

fix Always provide a non-None context string that corresponds to your backend configuration.

Imports

key_manager
```
from castellan import key_manager
```
Key manager factory to get backend instances

BarbicanKeyManager

wrong

from castellan.barbican_key_manager import BarbicanKeyManager

correct

from castellan.key_manager.barbican_key_manager import BarbicanKeyManager

Wrong path: must include full module path

KMIPKeyManager

from castellan.key_manager.kmip_key_manager import KMIPKeyManager

Key

wrong

from castellan.objects import Key

correct

from castellan.common.objects import Key

Key base class is in common.objects

Passphrase

from castellan.common.objects import Passphrase

Quickstart

Basic usage: create a key manager using config, store and retrieve a passphrase.

import os
from castellan import key_manager
from castellan.common.objects import Passphrase, SymmetricKey

conf = {
    'key_manager': 'barbican',
    'barbican': {
        'auth_url': os.environ.get('OS_AUTH_URL', ''),
        'project_name': os.environ.get('OS_PROJECT_NAME', ''),
    }
}

km = key_manager.KeyManager(conf)
# Create a passphrase
passphrase = Passphrase('my-secret-passphrase')
stored = km.store('default', passphrase)
print(f"Stored passphrase with ID: {stored}")

# Retrieve
retrieved = km.get('default', stored)
print(f"Retrieved passphrase: {retrieved.get_encoded()}")