{"record":{"id":"ccc85805f64d2723","repo":"gravitational/teleport","slug":"pkcs11-hsm-support-requires-a-license-with-the-hsm","errorCode":null,"errorMessage":"PKCS11 HSM support requires a license with the HSM feature enabled: %w","messagePattern":"PKCS11 HSM support requires a license with the HSM feature enabled: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"lib/auth/auth.go","lineNumber":286,"sourceCode":"\t}\n\tif cfg.ClusterConfiguration == nil {\n\t\tclusterConfig, err := local.NewClusterConfigurationService(cfg.Backend)\n\t\tif err != nil {\n\t\t\treturn nil, trace.Wrap(err)\n\t\t}\n\t\tcfg.ClusterConfiguration = clusterConfig\n\t}\n\tif cfg.KeyStore == nil {\n\t\tkeystoreOpts := &keystore.Options{\n\t\t\tHostUUID:             cfg.HostUUID,\n\t\t\tClusterName:          cfg.ClusterName,\n\t\t\tAuthPreferenceGetter: cfg.ClusterConfiguration,\n\t\t\tFIPS:                 cfg.FIPS,\n\t\t\tClock:                cfg.Clock,\n\t\t}\n\t\tif cfg.KeyStoreConfig.PKCS11 != (servicecfg.PKCS11Config{}) {\n\t\t\tif !cfg.Modules.Features().GetEntitlement(entitlements.HSM).Enabled {\n\t\t\t\treturn nil, fmt.Errorf(\"PKCS11 HSM support requires a license with the HSM feature enabled: %w\", ErrRequiresEnterprise)\n\t\t\t}\n\t\t} else if cfg.KeyStoreConfig.GCPKMS != (servicecfg.GCPKMSConfig{}) {\n\t\t\tif !cfg.Modules.Features().GetEntitlement(entitlements.HSM).Enabled {\n\t\t\t\treturn nil, fmt.Errorf(\"GCP KMS support requires a license with the HSM feature enabled: %w\", ErrRequiresEnterprise)\n\t\t\t}\n\t\t} else if cfg.KeyStoreConfig.AWSKMS != nil {\n\t\t\tif !cfg.Modules.Features().GetEntitlement(entitlements.HSM).Enabled {\n\t\t\t\treturn nil, fmt.Errorf(\"AWS KMS support requires a license with the HSM feature enabled: %w\", ErrRequiresEnterprise)\n\t\t\t}\n\t\t}\n\t\tcfg.KeyStore, err = keystore.NewManager(context.Background(), &cfg.KeyStoreConfig, keystoreOpts)\n\t\tif err != nil {\n\t\t\treturn nil, trace.Wrap(err)\n\t\t}\n\t}\n\tif cfg.RecordingEncryption == nil {\n\t\tlocalRecordingEncryption, err := local.NewRecordingEncryptionService(cfg.Backend)\n\t\tif err != nil {","sourceCodeStart":268,"sourceCodeEnd":304,"githubUrl":"https://github.com/gravitational/teleport/blob/1283425b60ec5f60d509ba4c791183d452923ff7/lib/auth/auth.go#L268-L304","documentation":"During auth server startup, NewServer checks that the license carries the HSM entitlement before allowing a PKCS11 KeyStoreConfig. If a PKCS11 HSM is configured but the running modules' features do not enable entitlements.HSM (e.g. OSS or non-HSM Enterprise license), startup fails with this error wrapping ErrRequiresEnterprise.","triggerScenarios":"Starting the Teleport auth service with key_store configuration pointing at a PKCS11 HSM (pin/slot/module_path set) while the loaded license lacks the HSM feature entitlement.","commonSituations":"Running OSS Teleport with an HSM config copied from an Enterprise deployment; an Enterprise license without the HSM add-on; license file not loaded/expired so features default to disabled.","solutions":["Obtain/load an Enterprise license with the HSM entitlement enabled and restart the auth service.","If HSM is not intended, remove the PKCS11 section from key_store configuration and use the default software key store.","Verify with `teleport version` / license diagnostics that the Enterprise modules are actually active (not falling back to OSS)."],"exampleFix":"// before (auth_service config)\nkey_store: { type: pkcs11, module_path: /usr/lib/softhsm.so, pin: \"1234\", slot: 0 }\n// after (OSS fallback) — remove the pkcs11 block\nkey_store: {}\n// or upgrade to Enterprise HSM license and keep the config","handlingStrategy":"validation","validationCode":"if cfg.KeyStoreConfig.PKCS11 != (servicecfg.PKCS11Config{}) &&\n\t!cfg.Modules.Features().GetEntitlement(entitlements.HSM).Enabled {\n\treturn errors.New(\"PKCS11 key store configured but license lacks HSM entitlement; remove pkcs11 config or upgrade license\")\n}","typeGuard":null,"tryCatchPattern":"srv, err := auth.NewServer(...)\nif err != nil {\n\tif strings.Contains(err.Error(), \"PKCS11 HSM support requires a license\") {\n\t\t// startup-blocked: fix config/license before retrying; do not blindly restart\n\t}\n}","preventionTips":["Check license entitlements before deploying HSM configs to a cluster.","Ensure the Enterprise license file is present and loading at boot.","Keep HSM key_store settings in environment-specific config overlays applied only where licensed."],"tags":["licensing","hsm","pkcs11","startup"],"backgroundTag":"enterprise-feature-license-required","analyzedSha":"1283425b60ec5f60d509ba4c791183d452923ff7","analyzedAt":"2026-09-02T04:06:41.601Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}