{"id":21023,"library":"castellan","title":"Castellan","description":"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.","status":"active","version":"5.6.0","language":"python","source_language":"en","source_url":"https://opendev.org/openstack/castellan","tags":["openstack","key-management","barbican","kmip","security"],"install":[{"cmd":"pip install castellan","lang":"bash","label":"Install Castellan"}],"dependencies":[{"reason":"Authentication for OpenStack identity","package":"keystoneauth1","optional":true},{"reason":"Configuration management","package":"oslo.config","optional":true}],"imports":[{"note":"Key manager factory to get backend instances","wrong":null,"symbol":"key_manager","correct":"from castellan import key_manager"},{"note":"Wrong path: must include full module path","wrong":"from castellan.barbican_key_manager import BarbicanKeyManager","symbol":"BarbicanKeyManager","correct":"from castellan.key_manager.barbican_key_manager import BarbicanKeyManager"},{"note":"","wrong":null,"symbol":"KMIPKeyManager","correct":"from castellan.key_manager.kmip_key_manager import KMIPKeyManager"},{"note":"Key base class is in common.objects","wrong":"from castellan.objects import Key","symbol":"Key","correct":"from castellan.common.objects import Key"},{"note":"","wrong":null,"symbol":"Passphrase","correct":"from castellan.common.objects import Passphrase"}],"quickstart":{"code":"import os\nfrom castellan import key_manager\nfrom castellan.common.objects import Passphrase, SymmetricKey\n\nconf = {\n    'key_manager': 'barbican',\n    'barbican': {\n        'auth_url': os.environ.get('OS_AUTH_URL', ''),\n        'project_name': os.environ.get('OS_PROJECT_NAME', ''),\n    }\n}\n\nkm = key_manager.KeyManager(conf)\n# Create a passphrase\npassphrase = Passphrase('my-secret-passphrase')\nstored = km.store('default', passphrase)\nprint(f\"Stored passphrase with ID: {stored}\")\n\n# Retrieve\nretrieved = km.get('default', stored)\nprint(f\"Retrieved passphrase: {retrieved.get_encoded()}\")","lang":"python","description":"Basic usage: create a key manager using config, store and retrieve a passphrase."},"warnings":[{"fix":"Upgrade to Python >=3.10 or stay on castellan 4.x for Python 3.8/3.9 support.","message":"castellan 5.0.0 dropped support for Python versions <3.10. Ensure your environment uses Python 3.10+.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Switch to backend-specific config options like 'barbican_api_version' if using Barbican.","message":"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.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Use oslo.config's ConfigOpts or build nested dict as shown in the quickstart.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Always provide a non-None context string that corresponds to your backend configuration.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use: from castellan import key_manager","cause":"Incorrect import path; castellan.key_manager is a module, not a top-level attribute.","error":"ImportError: cannot import name 'key_manager' from 'castellan'"},{"fix":"km = key_manager.KeyManager(conf) then km.store(...)","cause":"KeyManager is a factory; you must call it to get a backend manager instance.","error":"castellan.key_manager.KeyManager object has no attribute 'store'"},{"fix":"Check OS_AUTH_URL and OS_PROJECT_NAME environment variables, or provide correct barbican_url in config.","cause":"Barbican endpoint is unreachable or misconfigured.","error":"castellan.common.exception.KeyManagerError: Connection refused"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}