Class EncryptionKeySourceBase`Abstract`

Abstract base class for encryption key source providers.

Key sources are responsible for securely retrieving encryption key material from various backends. The MemberJunction encryption system uses the ClassFactory pattern to instantiate the appropriate provider based on database configuration.

Security Considerations

Never log or expose key material - Key bytes should only be returned via the GetKey() method and immediately used for crypto operations.
Validate inputs - Always validate lookupValue parameters to prevent injection attacks against your backend.
Use secure connections - For network-based sources (vaults, KMS), always use TLS and verify certificates.
Handle errors securely - Don't expose internal details in error messages that could help attackers.

Lifecycle

Construction - Provider is instantiated with config
Initialize() - Called once before first use (async setup)
GetKey()/KeyExists() - Called for each operation
Dispose() - Called during cleanup (close connections)

Hierarchy (View Summary)

EncryptionKeySourceBase

Index

Constructors

constructor

new EncryptionKeySourceBase(
config?: EncryptionKeySourceConfig,
): EncryptionKeySourceBase
Creates a new key source instance.

Note: The config may be empty/undefined when using ClassFactory. Configuration is typically loaded from the database and passed when retrieving keys.
Parameters
- Optionalconfig: EncryptionKeySourceConfig
  Optional configuration for the key source
Returns EncryptionKeySourceBase
- Defined in Encryption/src/EncryptionKeySourceBase.ts:94

Properties

`Protected`_config

_config: EncryptionKeySourceConfig

Configuration passed during instantiation. Contains lookupValue and any source-specific additional config.

Accessors

`Abstract`SourceName

get SourceName(): string
Human-readable name of this key source.

Used for logging, error messages, and UI display. Should be concise but descriptive.

Returns string
Example
```
'Environment Variable', 'AWS KMS', 'HashiCorp Vault'
```
- Defined in Encryption/src/EncryptionKeySourceBase.ts:106

Methods

Dispose

Dispose(): Promise<void>
Optional cleanup for sources with connections or resources.

Called during graceful shutdown to release resources. Use this for:
- Closing vault connections
- Releasing pooled resources
- Flushing any pending operations
The default implementation is a no-op for stateless sources.

Override in subclasses that hold resources
Returns Promise<void>
- Defined in Encryption/src/EncryptionKeySourceBase.ts:251

`Abstract`GetKey

GetKey(lookupValue: string, keyVersion?: string): Promise<Buffer>
Retrieves the raw key material for the given lookup value.

Security Requirements
- Return key bytes directly, don't cache them in the provider
- Never log the key material
- Throw descriptive errors on failure (without exposing secrets)
- Validate lookupValue format before using it
Key Format

Keys should be base64-encoded in the source storage. The provider decodes and returns raw bytes.
Parameters
- lookupValue: string
  Identifier for the key in this source
  
  Env vars: the variable name (e.g., 'MJ_ENCRYPTION_KEY_PII')
  
  Config files: the key name (e.g., 'pii_master_key')
  
  Vaults: the secret path (e.g., '/secrets/encryption/pii')
- OptionalkeyVersion: string
  Optional version for versioned key stores. Some sources (like vaults) maintain multiple versions. If not specified, returns the current/latest version.
Returns Promise<Buffer>
Promise resolving to raw key bytes as a Buffer. The buffer length must match the algorithm's KeyLengthBits/8.
Throws
Error if the key cannot be retrieved with a descriptive message
Example
```
// Simple retrieval
const key = await source.GetKey('MJ_ENCRYPTION_KEY_PII');

// With version for rotation
const oldKey = await source.GetKey('MJ_ENCRYPTION_KEY_PII', '1');
const newKey = await source.GetKey('MJ_ENCRYPTION_KEY_PII', '2');
```
- Defined in Encryption/src/EncryptionKeySourceBase.ts:160

Initialize

Initialize(): Promise<void>
Optional async initialization for sources that need setup.

Called once by the encryption engine before first use. Use this for:
- Loading config files
- Establishing connections to vault services
- Authenticating with cloud key management
- Caching frequently-accessed metadata
The default implementation is a no-op for simple sources.

Override in subclasses that need async initialization
Returns Promise<void>
- Defined in Encryption/src/EncryptionKeySourceBase.ts:233

`Abstract`KeyExists

KeyExists(lookupValue: string): Promise<boolean>
Checks if a key exists without retrieving it.

Used for validation before operations that would fail on missing keys. More efficient than GetKey() when you only need existence check.
Parameters
- lookupValue: string
  Identifier for the key in this source
Returns Promise<boolean>
Promise resolving to true if key exists, false otherwise
Example
```
if (await source.KeyExists('NEW_ROTATION_KEY')) {
  // Safe to proceed with key rotation
} else {
  throw new Error('New key must be set before rotation');
}
```
- Defined in Encryption/src/EncryptionKeySourceBase.ts:180

`Abstract`ValidateConfiguration

ValidateConfiguration(): boolean
Validates that the source is properly configured.

Called before attempting key operations to fail fast on misconfiguration. Check for:
- Required config values are present
- Config values are in expected format
- Connectivity to backend (for network sources)
Returns boolean
true if configuration is valid, false otherwise
- Defined in Encryption/src/EncryptionKeySourceBase.ts:119

`Abstract`ValidateKeyAccessibility

ValidateKeyAccessibility(
    lookupValue: string,
    keyVersion?: string,
    expectedKeyLengthBytes?: number,
): Promise<KeyValidationResult>
Validates that a specific key is accessible and usable from this source.

Each provider implements source-specific validation logic and returns actionable remediation messages on failure. This keeps key-source-specific knowledge encapsulated within the provider rather than in the engine.

Contract
- MUST NOT expose key material to the caller — key bytes stay inside the provider
- MUST return { IsAccessible: true } only if key material can be retrieved and passes all validation (exists, valid format, correct length if expectedKeyLengthBytes provided)
- MUST return a human-readable Error string with remediation steps on failure
- SHOULD catch all exceptions internally and return them as Error strings
Parameters
- lookupValue: string
  Identifier for the key in this source
- OptionalkeyVersion: string
  Optional version for versioned key stores
- OptionalexpectedKeyLengthBytes: number
  Optional expected key length in bytes for validation. When provided, the provider should retrieve the key and verify its length matches.
Returns Promise<KeyValidationResult>
Promise resolving to a validation result
Example
```
const result = await source.ValidateKeyAccessibility('MJ_BASE_ENCRYPTION_KEY', '1', 32);
if (!result.IsAccessible) {
  console.error(result.Error);
  // "Environment variable "MJ_BASE_ENCRYPTION_KEY" is not set.
  //  Set it with: export MJ_BASE_ENCRYPTION_KEY=$(openssl rand -base64 32)"
}
```
- Defined in Encryption/src/EncryptionKeySourceBase.ts:213

Class EncryptionKeySourceBaseAbstract

Security Considerations

Lifecycle

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns EncryptionKeySourceBase

Properties

Protected_config

Accessors

AbstractSourceName

Returns string

Example

Methods

Dispose

Returns Promise<void>

AbstractGetKey

Security Requirements

Key Format

Parameters

Returns Promise<Buffer>

Throws

Example

Initialize

Returns Promise<void>

AbstractKeyExists

Parameters

Returns Promise<boolean>

Example

AbstractValidateConfiguration

Returns boolean

AbstractValidateKeyAccessibility

Contract

Parameters

Returns Promise<KeyValidationResult>

Example

Settings

On This Page

Class EncryptionKeySourceBase`Abstract`

`Protected`_config

`Abstract`SourceName

`Abstract`GetKey

`Abstract`KeyExists

`Abstract`ValidateConfiguration

`Abstract`ValidateKeyAccessibility