Documentation   /   API

Generale

Disponiamo di un'API REST standard per la gestione dei segreti. Tutte le richieste e le risposte utilizzano il formato JSON.

È possibile utilizzare l'API per gestire sia la crittografia che la decrittografia del segreto al di fuori del nostro servizio, senza bisogno di di caricare qualsiasi risorsa da noi. Inoltre, è possibile utilizzare qualsiasi tipo di metodo di consegna per la parte della password pubblica (metà della password che viene utilizzata per ricavare la chiave di crittografia del segreto) e in pratica creare qualsiasi tipo di configurazione personalizzata per la visualizzazione del segreto.

Esempi di codice

Consultare gli esempi di utilizzo dell'API.

Autenticazione

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...

Errori

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

Visualizza il segreto

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.

Creare un segreto

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.

Elenco segreti

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
}
}

Cancellare il segreto

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
}
}

Creare una richiesta segreta

Tipo di richiesta: POST

Percorso di richiesta: https://password.link/api/secret_requests

Codice di stato dell'interrogazione riuscita: 201 Created


Creare una nuova richiesta segreta.

Parametri della richiesta

  • description: descrizione per la Richiesta segreta.
  • message: per il visualizzatore di richieste segrete.
  • expiration: tempo di scadenza della richiesta segreta, in ore.
  • limit: limite di utilizzo per la Richiesta segreta.
  • send_request_to_email: invia il link della richiesta segreta creata all'indirizzo e-mail indicato.
  • send_to_email: invia il link segreto creato con la Richiesta segreta all'indirizzo e-mail indicato.
  • secret_description: descrizione del segreto creato con la richiesta di segreto.
  • secret_message: per il segreto creato con la richiesta di segreto.
  • secret_expiration: tempo di scadenza del segreto creato con la richiesta di segreto, in ore.
  • secret_password: password per il segreto creato con la richiesta di segreto, in ore.
  • secret_max_views: limite di visualizzazione per il segreto creato con la richiesta di segreto.

Esempio di query

curl -H "Authorization: ApiKey private_key_abcd" \
-H "Content-Type: application/json" -X POST https://password.link/api/secret_requests

Esempio di risposta

{
  "data": {
    "id":"5e976e6e-d205-4f58-8df9-5ac0048bc702"
  },
  "metadata": {
    "secrets_total":70,
    "secrets_usage":25,
    "secrets_allowance":100,
    "secret_requests_total":10,
    "secret_requests_allowance":100
  }
}

Elenco Richieste segrete

Tipo di richiesta: GET

Percorso di richiesta: https://password.link/api/secret_requests

Codice di stato dell'interrogazione riuscita: 200 OK


Elenco Richieste segrete.

Limite e offset

La quantità massima di risultati restituiti per ogni query è 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/secret_requests?offset=50

Esempio di query

curl -H "Authorization: ApiKey private_key_abcd" https://password.link/api/secret_requests

Esempio di risposta

{
  "data":[
      {
         "id":"5e976e6e-d205-4f58-8df9-5ac0048bc702",
         "description":"example",
         "message":"example",
         "expiration":3,
         "limit":1,
         "send_to_email":"example@example.com",
         "secret_description":"example",
         "secret_message":"example",
         "secret_expiration":"example",
         "secret_max_views":4,
         "secret_password":false,
         "template_id":null
      }
  ],
  "metadata": {
    "secrets_total":70,
    "secrets_usage":25,
    "secrets_allowance":100,
    "secret_requests_total":10,
    "secret_requests_allowance":100
  }
}

Eliminazione della richiesta segreta

Tipo di richiesta: DELETE

Percorso di richiesta: https://password.link/api/secret_requests/<id>

Codice di stato dell'interrogazione riuscita: 200 OK


Cancellare una richiesta segreta.

Esempio di query

curl -H "Authorization: ApiKey private_key_abcd" \
-X DELETE https://password.link/api/secret_requests/5e976e6e-d205-4f58-8df9-5ac0048bc702

Esempio di risposta

{
  "data": null,
  "metadata": {
    "secrets_total":70,
    "secrets_usage":25,
    "secrets_allowance":100,
    "secret_requests_total":10,
    "secret_requests_allowance":100
  }
}