Avvio rapido: conservare il primo segreto e riferirvisi

Il percorso più breve da «il plugin è installato» a «un altro plugin lavora con un riferimento invece che con la password». Tre passi, circa dieci minuti.

Prerequisiti

wkvault, wkcore e wkstorage sono installati e attivati. La cassaforte si registra tramite il registro di wkcore e conserva le voci tramite wkstorage; entrambi sono obbligatori.
Siete autenticati come superuser — la schermata è riservata agli amministratori.
PHP 8.2 o successivo.

Passo 1: decidere l'origine della chiave — prima della prima voce

Amministrazione → Configurazione, sezione wkvault, impostazione keysource.

Valore	Dove sta la chiave
`salt` (predefinito)	Derivata dal salt dell'istanza in `data/meta/`. Una copia di sicurezza della directory dei dati contiene quindi la chiave e i valori cifrati.
`env`	In una variabile d'ambiente nominata in `keysource_ref` — fuori dalla directory dei dati e fuori dalla copia di sicurezza del wiki.
`file`	In un file di chiave il cui percorso sta in `keysource_ref`; ragionevolmente fuori dalla radice web. Deve viaggiare con l'installazione.

Cambiarlo in seguito è innocuo — ogni voce porta l'impronta della chiave con cui è stata cifrata, e la schermata offre allora la ricifratura. Scegliere ora consapevolmente vi risparmia quel giro.

Passo 2: creare la voce

Amministrazione → Cassaforte, direttamente /doku.php?do=admin&page=wkvault. Sezione Creare o sostituire:

Campo	Che cosa vi va
Id	La chiave a cui i riferimenti puntano. Sceglierne una stabile e parlante, per esempio `mail-smtp`.
Segreto	Il valore. Viene cifrato prima di essere conservato.
Descrizione	Per chi leggerà l'elenco in seguito. Facoltativa.
Scade il, Ruotare ogni … giorni	Facoltativi; governano lo stato mostrato nell'elenco.

Passo 3: riferirvisi da un altro plugin

Ovunque un altro plugin chieda una password, inserire al posto del valore:

vault:mail-smtp

Sono disponibili cinque tipi di riferimento:

Riferimento	Si risolve in
`vault:<id>`	Una voce di questa cassaforte.
`env:<NOME>`	Una variabile d'ambiente.
`file:<percorso>`	Il contenuto di un file, solo sotto la radice configurata.
`enc:<valore>`	Un valore cifrato sul posto, senza voce in cassaforte.
`plain:<valore>`	Esattamente quel che c'è scritto.

plain: esiste perché un riferimento sia sempre univoco. Senza di esso una password letterale che contenesse per caso due punti verrebbe letta come tipo di riferimento.

Verifica del risultato

La voce compare nell'elenco con stato a posto. Il valore stesso non è visibile da nessuna parte — nemmeno a voi.
Nella configurazione del plugin che la consuma c'è vault:mail-smtp e nessuna password.
Attivare la funzione che ha bisogno del segreto — in wkmail per esempio un messaggio di prova. Nel registro degli accessi sulla schermata della cassaforte compare poi una riga con l'esecutore, la voce, l'operazione e l'esito. Il registro non contiene mai valori; è proprio questo il suo senso.

Passo successivo

wkmail — il primo consumatore sensato.
wkresource — il catalogo degli endpoint, che porta solo il riferimento e mai il valore.
wkvault (in tedesco) — la pagina del pacchetto: tutti i tipi di riferimento, la rotazione per consegna, la scadenza.