Per l'autenticazione utilizziamo due tipi di chiavi API:

• Chiavi API pubbliche
• Chiavi API private

Le chiavi API pubbliche sono destinate alla creazione di una pagina segreta personalizzata e autogestita. Tutte le altre azioni API richiedono una chiave API privata.

Le chiavi API pubbliche possono essere utilizzate in script pubblici. Le chiavi API private devono sempre essere mantenute private.

Entrambe le chiavi API contengono il tipo di chiave nella chiave stessa, in modo da poterle distinguere facilmente.

La chiave API deve essere inviata nell'intestazione Authorization: ApiKey <key>, come:

Authorization: ApiKey public_key_abc...

In caso di interrogazione non riuscita, la risposta conterrà un oggetto Errore.

L'oggetto contiene i seguenti campi:

• message: il messaggio di errore completo, ad esempio "Ciphertext can't be blank"
• field: il campo su cui verte l'errore, ad esempio "ciphertext"

Anche il codice di stato della risposta HTTP indica un errore, ad esempio

• 403 Forbidden: la richiesta non è stata consentita, ad esempio a causa di una chiave API non valida
• 404 Not Found: il segreto richiesto non è stato trovato

Tipo di richiesta: GET

Percorso della richiesta: https://password.link/api/secrets/<id>

Codice di stato della richiesta riuscita: 200 OK

Recupera il testo cifrato, la parte privata della password e altri dettagli di un segreto. Richiede la chiave API pubblica.

Questa query API può essere utilizzata per creare una pagina di visualizzazione del segreto personalizzata e autogestita, che non carica alcuno script o altre risorse dal nostro servizio.

Se il recupero di un segreto avviene con successo, esso viene automaticamente contrassegnato come visualizzato e quindi eliminato dal nostro database il testo cifrato e la parte relativa alla password privata, rendendo impossibile una nuova visualizzazione del segreto.

Parametri richiesti

• id: l'id del segreto, ad esempio dT5g

Esempio di query

curl -H "Authorization: ApiKey public_key_abcd" https://password.link/api/secrets/dT5g

Esempio di risposta

{
"data": {
  "id":"l'ID del segreto",
  "testo cifrato":"il testo cifrato del segreto",
  "password_parte_privata":"la parte privata della password del segreto",
  "messaggio":"il messaggio per il segreto, se impostato"
},
"metadati": {
  "secrets_total": 1,
  "secrets_use": 1,
  "secrets_allowance": 1
}
}

Esempio di codice

Si vedano i nostri esempi di API.

Tipo di richiesta: POST

Percorso della richiesta: https://password.link/api/secrets

Codice di stato della richiesta andata a buon fine: 201 Creato

Questa chiamata API supporta anche l'aggiunta di un allegato al segreto. Contattateci per maggiori dettagli.

Creare un segreto crittografato.

La crittografia del segreto lato client prima dell'invio alla nostra API richiede la creazione di una stringa JSON di testo cifrato compatibile con SJCL. Consultare la documentazione SJCL per il formato corretto della stringa JSON e vedere gli esempi della nostra API per gli esempi su come creare il testo cifrato.

Creazione della password per la crittografia del segreto

La password utilizzata per crittografare il segreto in AES deve essere composta da due stringhe di 18 caratteri. La chiave di crittografia vera e propria sarà la concatenazione di queste due stringhe ("parte privata" + "parte pubblica") ed è derivata dalla password da SJCL utilizzando PBKDF2.

Esempio di creazione delle parti private e pubbliche della password:

Password: fkgjbnvlakwiejgutnFIGKEOTIRUBNAKQJRL
=> Parte privata: fkgjbnvlakwiejgutn
=> Parte pubblica: FIGKEOTIRUBNAKQJRL

La parte privata deve essere codificata Base64 prima di essere inviata alla nostra API. Se si utilizza la pagina View Secret fornita da noi, è necessario codificare Base64 anche la parte pubblica. Se si utilizza una pagina segreta di visualizzazione autogestita, è possibile utilizzare lo stesso metodo o crearne una propria. Per le implementazioni di riferimento, consultare i nostri esempi di API.

Impostazioni necessarie per SJCL AES

Per la crittografia del segreto è necessario utilizzare le seguenti impostazioni per AES:

• Modalità: AES-GCM (impostazione SJCL: "mode:gcm")
• Dimensione della chiave: 256 bit (impostazione SJCL: "ks:256")
• Funzione di derivazione della chiave: PBKDF2 (impostazione predefinita SJCL)
• Iterazioni PBKDF2: 10000 (impostazione SJCL: "iter:10000")

Carico utile della richiesta

{
"ciphertext":"ciphertext",
"password_part_private":"password_part_private",
"descrizione":"description",
"messaggio":"messaggio",
"scadenza":"scadenza",
"view_button":"view_button",
"captcha":"captcha",
"password":"password",
"max_views":"max_views"
}

Parametri della richiesta

• testo cifrato: Una stringa JSON del segreto compatibile con SJCL, codificata in Base64.
• password_part_private: la parte di password privata utilizzata per criptare il segreto, in formato Base64.
• description (opzionale): una descrizione del segreto. Non può essere vista quando si visualizza il segreto.
• message (opzionale): un messaggio per il segreto. Verrà mostrato insieme al segreto.
• expiration (opzionale): tempo di scadenza del segreto, in ore. Valori possibili: 0-350.
• view_button (opzionale): mostra un pulsante di visualizzazione del segreto invece di mostrarlo immediatamente dopo l'apertura del link. Per abilitare questa funzione, impostarla su true.
• captcha (opzionale): mostra un semplice CAPTCHA prima di mostrare il segreto, principalmente per bloccare gli scanner automatici. Per attivare questa funzione, impostarla su true.
• password (opzionale): una password per il segreto.
• max_views (opzionale): quante volte il segreto può essere visualizzato. Valori possibili: 1-100.

Esempio di codice

Consultate i nostri esempi di API.

Tipo di richiesta: GET

Percorso della richiesta: https://password.link/api/secrets

Codice di stato della richiesta riuscita: 200 OK

Recupera un elenco di segreti. Non contiene le parti di password private dei cifrari, ma solo ID, descrizioni e simili.

Limite e offset

La quantità massima di segreti restituiti per ogni interrogazione è limitata a 50. È possibile controllare l'offset con il parametro opzionale offset della query.

Ad esempio, per saltare i primi 50 record, utilizzare una query come: .../api/secrets?offset=50

Esempio di query

curl -H "Autorizzazione: ApiKey private_key_abcd" https://password.link/api/secrets

Esempio di risposta

{
"data": [
  {
    "id": l'ID del segreto,
    "created_at": quando è stato creato il segreto,
    "message": il messaggio del segreto,
    "description": la descrizione del segreto,
    "view_button": il pulsante di visualizzazione del segreto è abilitato,
    "captcha": è abilitato il CAPTCHA,
    "password": il segreto ha una password,
    "expiration": tempo di scadenza in ore,
    "expired": il segreto è scaduto,
    "view_times": quante volte il segreto è stato visualizzato,
    "max_views": il numero massimo di volte in cui il segreto può essere visualizzato,
    "views": [
      {
        "viewed_at": un timestamp di quando il segreto è stato visualizzato,
        "viewed_by_ip": Indirizzo IP del visualizzatore,
        "viewed_by_user_agent": agente utente del visualizzatore
      }
    ]
  }
],
"metadati": {
  "secrets_total": 1,
  "secrets_usage": 1,
  "secrets_allowance": 1
}
}

Tipo di richiesta: CANCELLARE

Percorso della richiesta: https://password.link/api/secrets/<id>

Codice di stato della richiesta riuscita: 200 OK

Cancellare un segreto.

Esempio di query

curl -H "Autorizzazione: ApiKey private_key_abcd" \
  -X DELETE https://password.link/api/secrets/dT5g

Esempio di risposta

{
"data": null,
"metadati": {
  "segreti_totali": 1,
  "segreti_utili": 1,
  "secrets_allowance": 1
}
}