WordPress 7.2 Secrets API Implementation: Secure Credential Storage per LLM Integration e Third-Party API Keys — Compliance E2E Encryption

WordPress 7.2 Secrets API Implementation: Secure Credential Storage per LLM Integration e Third-Party API Keys — Compliance E2E Encryption

WordPress 7.2 introduce la Secrets API, un sistema nativo per la gestione sicura delle credenziali e delle chiavi API direttamente all’interno della piattaforma. Per editori e sviluppatori che integrano modelli linguistici avanzati (come Gemini 3.7, Claude Opus 5, Llama 4) e API di terze parti, questo rappresenta un passo cruciale verso la conformità con gli standard di sicurezza enterprise e le normative sulla protezione dei dati (GDPR, AI Act europeo).

La Secrets API di WordPress 7.2 permette di archiviare, cifrare e gestire credenziali sensibili senza esporre le chiavi nel codice sorgente, nei database non protetti o nei file di configurazione. Questo articolo analizza l’implementazione tecnica, i pattern di integrazione con servizi LLM, i meccanismi di crittografia end-to-end e le strategie di conformità normativa.

Architettura della Secrets API WordPress 7.2

La Secrets API si fonda su quattro pilastri architetturali: storage centralizzato, cifratura a riposo, gestione del ciclo di vita delle chiavi e audit logging. A differenza delle soluzioni precedenti basate su costanti PHP definite in wp-config.php, questa API offre un approccio strutturato e auditabile.

Modello di Archiviazione e Cifratura

Le credenziali vengono archiviate nella tabella wp_options con il prefisso wp_secret_. Ogni segreto è cifrato utilizzando AES-256-GCM (Advanced Encryption Standard a 256 bit con Galois/Counter Mode) per garantire sia confidenzialità che autenticità dei dati. La chiave di cifratura principale (KEK – Key Encryption Key) è derivata dalla combinazione di:

  • Salt WORDPRESS_AUTH_KEY e WORDPRESS_SECURE_AUTH_KEY da wp-config.php
  • Identificatore univoco del sito (site URL hash)
  • Timestamp di creazione della chiave per rotation pianificata

Questo modello garantisce che le credenziali rimangono inutilizzabili anche in caso di esportazione del database, poiché il valore crittografato è legato in modo crittografico alla configurazione specifica dell’istanza WordPress.

Interfaccia Programmatica

La Secrets API espone tre funzioni principali:

  • wp_secret_set( $identifier, $secret, $group = '' ) – Archivia una credenziale cifrata
  • wp_secret_get( $identifier, $group = '' ) – Recupera il valore decifrato in memoria
  • wp_secret_delete( $identifier, $group = '' ) – Elimina un segreto con overwrite sicuro

The parameter $group consente di organizzare i segreti per categoria (ad es. ‘gemini’, ‘claude’, ‘stripe’), facilitando la gestione e l’audit delle credenziali associate a specifiche integrazioni.

Integrazione con LLM e API di Terze Parti

La gestione delle chiavi API per servizi LLM rappresenta un caso d’uso primario della Secrets API. Ogni provider (Google Cloud, Anthropic, Meta) richiede credenziali con privilegi specifici; la Secrets API consente di isolare questi accessi e limitare l’esposizione in caso di compromissione.

Configurazione per Gemini 3.7 e Google Cloud API

Per integrare Gemini 3.7, la chiave API di Google Cloud deve essere memorizzata tramite Secrets API:


// Archiviazione della chiave API
wp_secret_set(
  'gemini_api_key',
  'AIzaSy[...credenziale completa...]',
  'google_ai'
);

// Recupero in una classe helper
class Gemini_Client {
  private $api_key;
  
  public function __construct() {
    $this->api_key = wp_secret_get( 'gemini_api_key', 'google_ai' );
    if ( empty( $this->api_key ) ) {
      throw new Exception( 'Gemini API key non configurata' );
    }
  }
  
  public function analyze_image( $image_url ) {
    $response = wp_remote_post(
      'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-vision:generateContent',
      array(
        'headers' => array(
          'Content-Type' => 'application/json',
          'x-goog-api-key' => $this->api_key,
        ),
        'body' => wp_json_encode( array(
          'contents' => array(
            'parts' => array(
              array( 'text' => 'Analizza questa immagine' ),
              array( 'inline_data' => array(
                'mime_type' => 'image/jpeg',
                'data' => base64_encode( file_get_contents( $image_url ) ),
              ) ),
            ),
          ),
        ) ),
      )
    );
    return json_decode( wp_remote_retrieve_body( $response ), true );
  }
}

Questo pattern garantisce che la chiave API non appaia mai in log, cache o stack trace. In caso di errore, WordPress registra solo l’identificatore ‘gemini_api_key’, non il valore effettivo.

Pattern Multi-Provider per Llama 4 e Claude Opus 5

Quando si implementa un’architettura multi-LLM (ad es. Llama 4 self-hosted + Claude Opus 5 per fallback), la Secrets API semplifica la gestione di più credenziali:


// Configurazione centralizzata
wp_secret_set( 'claude_api_key', 'sk-ant-[...]', 'anthropic' );
wp_secret_set( 'claude_model', 'claude-opus-5', 'anthropic' );
wp_secret_set( 'llama_endpoint', 'https://llama.internal.local:8000', 'llama' );
wp_secret_set( 'llama_auth_token', 'Bearer [...]', 'llama' );

// Router intelligente basato su disponibilità
class LLM_Router {
  public function route_request( $prompt, $modality = 'text' ) {
    // Prova Llama 4 self-hosted per ridurre latenza
    try {
      $llama_client = new Llama_Client(
        wp_secret_get( 'llama_endpoint', 'llama' ),
        wp_secret_get( 'llama_auth_token', 'llama' )
      );
      return $llama_client->complete( $prompt );
    } catch ( Exception $e ) {
      // Fallback a Claude Opus 5
      error_log( 'Llama unavailable, switching to Claude: ' . $e->getMessage() );
      $claude_client = new Claude_Client(
        wp_secret_get( 'claude_api_key', 'anthropic' )
      );
      return $claude_client->complete( $prompt );
    }
  }
}

Questo approccio centralizza la gestione delle credenziali, facilita la rotazione delle chiavi e consente di auditare tutte le operazioni sensibili in un unico punto.

Meccanismi di Crittografia End-to-End

La Secrets API implementa crittografia a riposo, ma per scenari ad alta sicurezza (fintech, healthcare, newsroom sensibili) è consigliabile aggiungere un livello ulteriore di crittografia end-to-end applicativa.

Crittografia Simmetrica Aggiuntiva con libsodium

WordPress 7.2 supporta nativamente sodium_crypto_secretbox() per crittografia simmetrica aggiuntiva. Questo è utile per credenziali destinate a specifiche operazioni critica:


// Classe helper per crittografia aggiuntiva
class Secret_Vault {
  private $master_key;
  
  public function __construct() {
    // La chiave master viene archiviata in wp_secret con protezione nativa
    $this->master_key = wp_secret_get( 'vault_master_key', 'security' );
  }
  
  public function encrypt_sensitive( $plaintext ) {
    $nonce = random_bytes( SODIUM_CRYPTO_SECRETBOX_NONCEBYTES );
    $ciphertext = sodium_crypto_secretbox(
      $plaintext,
      $nonce,
      $this->master_key
    );
    // Restituisci nonce + ciphertext concatenati
    return base64_encode( $nonce . $ciphertext );
  }
  
  public function decrypt_sensitive( $encrypted ) {
    $data = base64_decode( $encrypted );
    $nonce = substr( $data, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES );
    $ciphertext = substr( $data, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES );
    
    $plaintext = sodium_crypto_secretbox_open(
      $ciphertext,
      $nonce,
      $this->master_key
    );
    
    if ( false === $plaintext ) {
      throw new Exception( 'Decryption failed: corrupted data' );
    }
    
    return $plaintext;
  }
}

Questo approccio implementa un modello di difesa in profondità: la chiave master è protetta dalla Secrets API nativa, mentre i dati sensibili ricevono un ulteriore layer di cifratura applicativa.

Derivazione di Chiavi per Specifiche Integrazioni

Per estendere la sicurezza, è possibile derivare chiavi univoche per ogni integrazione utilizzando HKDF (HMAC-based Key Derivation Function):


// Derivazione di chiavi univoche per provider specifici
function derive_provider_key( $provider_name, $master_secret ) {
  $info = 'wp-secrets-v1|' . $provider_name . '|' . ABSPATH;
  
  $derived = hash_hkdf(
    'sha256',
    $master_secret,
    length: 32, // 256 bit
    info: $info
  );
  
  return $derived;
}

// Utilizzo
$gemini_key = wp_secret_get( 'gemini_api_key', 'google_ai' );
$derived_key = derive_provider_key( 'gemini', $gemini_key );
// Ora $derived_key è univoca per Gemini su questo sito

Questo modello consente di separare logicamente le credenziali per provider, facilitando la revoca granulare e l’audit trail.

Audit Logging e Compliance GDPR/AI Act

La Secrets API di WordPress 7.2 integra un sistema di audit logging automatico. Tuttavia, per conformità normativa completa (GDPR Art. 32, AI Act Allegato I), è necessario estendere la registrazione con metadati contestuali.

Implementazione di Audit Trail Strutturato

Creare una tabella dedicata per l’audit delle operazioni sensibili:


// Hook per registrare accessi a segreti
add_action( 'wp_secret_accessed', function( $identifier, $group ) {
  global $wpdb;
  
  $wpdb->insert(
    $wpdb->prefix . 'secret_audit_log',
    array(
      'timestamp' => current_time( 'mysql', true ),
      'user_id' => get_current_user_id(),
      'action' => 'secret_access',
      'secret_identifier' => $identifier,
      'secret_group' => $group,
      'ip_address' => sanitize_text_field( $_SERVER['REMOTE_ADDR'] ?? '' ),
      'user_agent' => sanitize_text_field( $_SERVER['HTTP_USER_AGENT'] ?? '' ),
      'result' => 'success',
    ),
    array( '%s', '%d', '%s', '%s', '%s', '%s', '%s', '%s' )
  );
}, 10, 2 );

// Hook per errori di accesso
add_action( 'wp_secret_access_denied', function( $identifier, $group, $reason ) {
  global $wpdb;
  
  $wpdb->insert(
    $wpdb->prefix . 'secret_audit_log',
    array(
      'timestamp' => current_time( 'mysql', true ),
      'user_id' => get_current_user_id(),
      'action' => 'secret_access_denied',
      'secret_identifier' => $identifier,
      'secret_group' => $group,
      'ip_address' => sanitize_text_field( $_SERVER['REMOTE_ADDR'] ?? '' ),
      'user_agent' => sanitize_text_field( $_SERVER['HTTP_USER_AGENT'] ?? '' ),
      'result' => 'failure',
      'error_reason' => $reason,
    ),
    array( '%s', '%d', '%s', '%s', '%s', '%s', '%s', '%s', '%s' )
  );
}, 10, 3 );

Questo audit trail è fondamentale per dimostrare la conformità con l’Art. 32 GDPR (misure tecniche e organizzative) e con l’AI Act per sistemi ad alto rischio.

Compliance Documentation per Modelli Linguistici

Quando si utilizza la Secrets API per gestire credenziali di LLM, è necessario documentare:

  • Data Processing Agreement (DPA) con i provider (Google, Anthropic, Meta)
  • Retention Policy: quanto tempo i segreti rimangono archiviati
  • Rotation Schedule: cadenza di rotazione delle chiavi (consigliato: 90 giorni)
  • Incident Response Plan: procedura di revoca immediata in caso di compromise

Per newsroom e publisher europei, la compliance con l’AI Act richiede il tracking di quali modelli LLM processano quali categorie di dati editoriali. La Secrets API facilita questa segregazione:


// Metadata per compliance AI Act
$llm_config = array(
  'model_identifier' => 'gemini-3.7-vision',
  'risk_category' => 'high-risk', // secondo AI Act
  'data_categories' => array( 'editorial_content', 'user_analytics' ),
  'jurisdiction' => 'EU',
  'gdpr_article' => '6(1)(f)', // base legale
  'processing_limitation' => array(
    'max_requests_per_day' => 10000,
    'retention_days' => 30,
  ),
);

wp_secret_set(
  json_encode( $llm_config ),
  'gemini_config_v1',
  'llm_compliance'
);

Questa metadata facilita la generazione automatica di Data Provenance Records e Model Cards, fondamentali per la compliance europea.

Strategie Avanzate: Key Rotation e Zero-Trust Architecture

In ambienti enterprise, la rotazione periodica delle chiavi è essenziale. WordPress 7.2 Secrets API supporta rotazione non-disruptive mediante versioning:

Implementazione di Key Rotation Granulare


// Classe per gestire rotazione delle chiavi
class Secret_Rotation_Manager {
  private $rotation_interval = 7776000; // 90 giorni in secondi
  
  public function should_rotate( $secret_identifier, $group ) {
    $last_rotation = get_option(
      "wp_secret_rotation_{$group}_{$secret_identifier}"
    );
    
    if ( ! $last_rotation ) {
      return true;
    }
    
    return ( current_time( 'timestamp' ) - $last_rotation ) > $this->rotation_interval;
  }
  
  public function rotate_key( $secret_identifier, $group, $new_secret ) {
    // Step 1: Archivia la nuova versione con suffix
    $version = wp_date( 'YmdHis' );
    wp_secret_set(
      "{$secret_identifier}_v{$version}",
      $new_secret,
      $group
    );
    
    // Step 2: Aggiorna il pointer all'ultima versione
    update_option(
      "wp_secret_active_{$group}_{$secret_identifier}",
      $version
    );
    
    // Step 3: Registra il timestamp di rotazione
    update_option(
      "wp_secret_rotation_{$group}_{$secret_identifier}",
      current_time( 'timestamp' )
    );
    
    // Step 4: Log per audit
    error_log(
      sprintf(
        'Secret rotated: %s/%s (version: %s)',
        $group,
        $secret_identifier,
        $version
      )
    );
  }
  
  public function get_active_secret( $secret_identifier, $group ) {
    $active_version = get_option(
      "wp_secret_active_{$group}_{$secret_identifier}"
    );
    
    if ( $active_version ) {
      return wp_secret_get(
        "{$secret_identifier}_v{$active_version}",
        $group
      );
    }
    
    // Fallback alla versione senza versioning
    return wp_secret_get( $secret_identifier, $group );
  }
}

Questo pattern consente rotazione zero-downtime delle credenziali, cruciale per servizi in produzione.

Zero-Trust Access Control per Secrets

Implementare capability-based access control per limitare quali ruoli e plugin possono accedere a specifici segreti:


// Registrazione di segreti con policy di accesso
function register_secret_with_policy( $identifier, $group, $secret, $access_policy ) {
  wp_secret_set( $identifier, $secret, $group );
  
  // Policy structure
  $policy = array(
    'allowed_roles' => array( 'administrator', 'editor' ),
    'allowed_plugins' => array( 'gemini-integration', 'claude-assistant' ),
    'allowed_files' => array( '/wp-content/plugins/gemini-integration/class-client.php' ),
    'ip_whitelist' => array( '10.0.0.0/8' ), // interno
  );
  
  update_option(
    "wp_secret_policy_{$group}_{$identifier}",
    $policy
  );
}

// Middleware per enforcing policy
function wp_secret_get_with_policy( $identifier, $group = '' ) {
  $policy = get_option( "wp_secret_policy_{$group}_{$identifier}" );
  
  if ( ! $policy ) {
    return wp_secret_get( $identifier, $group );
  }
  
  // Check ruolo utente
  $user = wp_get_current_user();
  if ( ! array_intersect( $user->roles, $policy['allowed_roles'] ) ) {
    do_action(
      'wp_secret_access_denied',
      $identifier,
      $group,
      'insufficient_role'
    );
    return null;
  }
  
  // Check IP origin (per zero-trust)
  $client_ip = sanitize_text_field( $_SERVER['REMOTE_ADDR'] ?? '' );
  if ( ! $this->ip_in_cidr( $client_ip, $policy['ip_whitelist'] ) ) {
    do_action(
      'wp_secret_access_denied',
      $identifier,
      $group,
      'ip_not_whitelisted'
    );
    return null;
  }
  
  return wp_secret_get( $identifier, $group );
}

Questa implementazione garantisce che le credenziali sensibili siano accessibili solo da attori autorizzati, allineandosi con il principio zero-trust della sicurezza moderna.

Integrazione con Strumenti di Gestione della Configurazione

Per ambienti multi-sito e deployment automatizzati, è consigliabile integrare Secrets API con strumenti di Infrastructure-as-Code:

Sincronizzazione con HashiCorp Vault

Per architetture enterprise, WordPress può sincronizzare segreti con HashiCorp Vault:


// Plugin adapter per HashiCorp Vault
class Vault_Secret_Provider {
  private $vault_addr;
  private $vault_token;
  
  public function __construct( $vault_addr, $vault_token ) {
    $this->vault_addr = $vault_addr;
    $this->vault_token = $vault_token;
  }
  
  public function sync_to_wordpress( $vault_path, $identifier, $group ) {
    $response = wp_remote_get(
      "{$this->vault_addr}/v1/{$vault_path}",
      array(
        'headers' => array(
          'X-Vault-Token' => $this->vault_token,
        ),
      )
    );
    
    if ( is_wp_error( $response ) ) {
      error_log( 'Vault sync failed: ' . $response->get_error_message() );
      return false;
    }
    
    $data = json_decode(
      wp_remote_retrieve_body( $response ),
      true
    );
    
    if ( isset( $data['data']['data']['value'] ) ) {
      wp_secret_set(
        $identifier,
        $data['data']['data']['value'],
        $group
      );
      return true;
    }
    
    return false;
  }
  
  public function monitor_expiration( $vault_path, $identifier, $group ) {
    // Controlla expiration metadata da Vault
    // e esegui rotazione automatica se necessario
  }
}

Questo pattern abilita una single source of truth per la gestione delle credenziali, con audit trail centralizzato.

Best Practices e Anti-Pattern Comuni

✓ Best Practices:

  • Sempre utilizzare wp_secret_set() per credenziali, mai variabili di configurazione esplicite
  • Implementare key rotation ogni 90 giorni come baseline
  • Registrare ogni accesso a segreti per audit trail completo
  • Separare credenziali per provider/ambiente (produzione vs staging)
  • Utilizzare least-privilege per policy di accesso
  • Monitorare anomalie (accessi massicci, orari inusuali)

✗ Anti-pattern da evitare:

  • Non memorizzare segreti in wp-config.php con Secrets API disponibile
  • Non loggare valori decifrati in debug log
  • Non condividere chiave master tra più siti WordPress
  • Non implementare policy di accesso troppo permissive (‘administrator’ a tutto)
  • Non tralasciare la documentazione di compliance per i segreti critici

FAQ

La Secrets API di WordPress 7.2 è compatibile con plugin legacy che usano costanti di configurazione?

Sì. WordPress 7.2 mantiene retrocompatibilità con costanti definite in wp-config.php. Tuttavia, si consiglia di eseguire una migrazione progressiva verso Secrets API per migliorare la postura di sicurezza. Un wrapper helper può astrarre l’origine della credenziale, permettendo fallback ordinato a costanti legacy se il segreto non è archiviato via Secrets API.

Come gestire la rotazione automatica di chiavi API di terze parti (es. Google Cloud, Anthropic) senza downtime?

Implementare un pattern versioning come descritto nella sezione Key Rotation: archiviare la nuova chiave con suffisso di versione, aggiornare il puntatore attivo, e fornire un periodo di grazia (24-48 ore) durante il quale il client tenta la versione attiva e fallback a quella precedente in caso di errore 401/403. Questo consente al provider di rotare la chiave in background senza interruzione di servizio.

La Secrets API di WordPress 7.2 soddisfa i requisiti di crittografia end-to-end dell’AI Act europeo per sistemi ad alto rischio?

La Secrets API fornisce crittografia a riposo (AES-256-GCM), che è robusta. Per conformità completa all’AI Act (Allegato I, Allegato III), è tuttavia necessario: (1) aggiungere crittografia applicativa ulteriore con libsodium, (2) implementare audit trail strutturato con metadati di conformità, (3) documentare Data Processing Agreements con provider LLM, e (4) implementare zero-trust access control come descritto. La Secrets API fornisce l’infrastruttura di base, ma la compliance è responsabilità dell’implementatore.

Posso usare Secrets API per archiviare credenziali di database e FTP oltre a chiavi API esterne?

Tecnicamente sì, ma non è consigliato. Secrets API è ottimizzata per credenziali di terze parti (API keys, token). Per credenziali di database e FTP, che sono critiche per la disponibilità del sito, è preferibile utilizzare wp-config.php con file-level permissions strict (600) e separazione logica di ambienti. La Secrets API è complementare a, non sostitutiva di, la configurazione di sistema tradizionale di WordPress.

Come integro la Secrets API con workflow CI/CD e deployment automatizzati?

Utilizzare webhook post-deployment per sincronizzare segreti da una fonte centralizzata (HashiCorp Vault, AWS Secrets Manager, Google Cloud Secret Manager) al WordPress target. Il deployment orchestrator (GitHub Actions, GitLab CI) dovrebbe iniettare segreti tramite API HTTP (non via database diretto). Questo consente immutabilità del codice deployato, con credenziali gestite separatamente da infrastruttura dedicata.

Conclusion

La Secrets API di WordPress 7.2 rappresenta un salto qualitativo nella gestione delle credenziali per piattaforme che integrano LLM e API di terze parti. Attraverso crittografia nativa (AES-256-GCM), audit trail strutturato e interfaccia programmatica pulita, questa API consente di implementare security best practices senza compromessione di usabilità.

Per editori e developer che operano in jurisdizioni europee, la Secrets API facilita la conformità normativa (GDPR Art. 32, AI Act Allegato I). Tuttavia, la sicurezza end-to-end richiede un approccio a strati: crittografia nativa + crittografia applicativa aggiuntiva (libsodium) + audit trail + zero-trust access control + key rotation automatizzata.

L’implementazione dovrebbe iniziare con una audit delle credenziali attuali, per identificare quali segreti sono esposti nel codice o in file di configurazione. Successivamente, implementare la migrazione progressiva verso Secrets API, partendo dalle credenziali più critiche (LLM, payment processor), con testing rigoroso in staging environment prima del roll-out in produzione.

Per scenari ad alta complessità (multi-sito, ambiente enterprise, compliance elevata), integrare Secrets API con sistemi di secret management centralizzati (Vault, AWS Secrets Manager) garantisce scalabilità e auditabilità completa dell’intera supply chain di credenziali.

Picture of Dario

Dario

All articles →

Related articles