Secrets Management Service

Overview

The Secrets Management Service provides a secure way to store and access sensitive information such as API keys, private credentials, and other secrets within the Neo N3 Service Layer ecosystem. All secrets are encrypted at rest and only accessible within the Trusted Execution Environment (TEE).

Key Features

Secure storage of sensitive data using encryption at rest and in transit
Access control with fine-grained permissions
Versioning of secrets to track changes
Automatic rotation support for applicable secrets
Seamless integration with the Functions service
Secure access within the TEE environment only

Why Use the Secrets Management Service?

Storing sensitive information directly in your application code or configuration files is insecure and creates maintenance challenges. The Secrets Management Service solves these problems by:

Providing a central, secure repository for all your secrets
Enabling access to secrets only in secure execution environments
Separating secret management from application deployment
Allowing secret updates without code changes
Supporting audit trails for secret access and modifications

Creating and Managing Secrets

You can create, update, and delete secrets through the API or web dashboard. Each secret has:

A unique name for identification
The sensitive value to be stored securely
Optional metadata (description, tags, etc.)
Access permissions
Version history

Secret Types

The Secrets Management Service supports different types of secrets:

String Secrets: For API keys, passwords, and other text-based secrets
File Secrets: For certificates, private keys, and other file-based secrets
JSON Secrets: For structured data like configuration objects

Accessing Secrets in Functions

Secrets can be accessed from within JavaScript functions using the secrets object:

function main(args) {
  // Get a secret by name
  const apiKey = secrets.get('my_api_key');
  
  // Get a JSON secret
  const credentials = secrets.get('database_credentials');
  
  // Use the secret
  const response = await fetch('https://api.example.com/data', {
    headers: {
      'Authorization': 'Bearer ' + apiKey
    }
  });
  
  // Never return secrets directly in your function response!
  return {
    success: true,
    data: await response.json()
  };
}

Important Security Note

Never return secrets directly in your function responses. This would expose the secret values to the caller. Always use secrets internally and only return derived data.

Security Considerations

The Secrets Management Service is designed with security as the top priority:

Encryption at Rest: All secrets are encrypted before being stored, using industry-standard encryption algorithms.
Encryption in Transit: All communications with the Secrets API use TLS to protect data in transit.
Access Control: Fine-grained access controls determine which functions and users can access each secret.
TEE Isolation: Secrets are only decrypted inside the secure Trusted Execution Environment, which protects against host and infrastructure attacks.
Audit Logging: All access to secrets is logged for audit and compliance purposes.

Best Practices

Follow these best practices when working with the Secrets Management Service:

Use descriptive names for secrets that indicate their purpose
Rotate secrets regularly, especially for high-sensitivity credentials
Set appropriate access permissions for each secret
Never log or display secret values, even in debug output
Use the minimum number of secrets needed for your application
Document the purpose and usage of each secret in your organization

Using Secrets with Other Services

Secrets can be used with other Service Layer components:

Functions Service: Access secrets securely in your JavaScript functions
Automation Service: Use secrets in automated tasks without exposing sensitive data
Oracle Service: Authenticate with external APIs using securely stored credentials

Example Use Cases

API Authentication

function main(args) {
  // Get the API key from secrets
  const apiKey = secrets.get('weather_api_key');
  
  // Call weather API for the requested location
  const location = args.location || 'New York';
  const response = await fetch(
    `https://api.weatherservice.com/data?location=${location}`,
    { headers: { 'X-API-Key': apiKey } }
  );
  
  if (!response.ok) {
    throw new Error('Weather API request failed');
  }
  
  const weatherData = await response.json();
  
  return {
    location: location,
    temperature: weatherData.temperature,
    conditions: weatherData.conditions,
    forecast: weatherData.forecast,
    timestamp: new Date().toISOString()
  };
}

Database Connection

function main(args) {
  // Get database credentials from secrets
  const dbConfig = secrets.get('database_credentials');
  
  // This is a simulated database query
  // In a real function, you would connect to your database
  // using the credentials from the secret
  
  // Return simulated data
  return {
    message: "Database queried successfully using stored credentials",
    recordCount: 42,
    success: true,
    timestamp: new Date().toISOString()
  };
}

API Reference

For a complete API reference, see the Secrets API documentation.