Documentazione API
Generale
Abbiamo un'API REST standard per la gestione dei segreti. Tutte le richieste e le risposte utilizzano il metodo JSON formato.
È possibile utilizzare l'API per gestire sia la crittografia che la decrittografia del segreto al di fuori del nostro servizio, senza dover caricare alcuna 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
Per sapere come utilizzare l'API, consultare i nostri esempi di 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 nel campo Authorization: ApiKey <key> intestazione, come:
Authorization: ApiKey public_key_abc...
Errori
In caso di interrogazione non andata a buon fine, la risposta avrà un valore di error oggetto.
L'oggetto contiene i seguenti campi:
- message: il messaggio di errore completo, ad esempio "Ciphertext can't be blank"
- campo: il campo su cui verte l'errore, ad esempio "ciphertext"
Il codice di stato della risposta HTTP indicherà anche un errore, ad esempio:
- 403 Forbidden: la richiesta non è stata consentita, ad esempio a causa di una chiave API non valida
- 404 Non trovato: 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 dell'interrogazione riuscita: 200 OK
Recupera il testo cifrato, la parte di password privata e altri dettagli di un segreto. Richiede il pubblico Chiave API.
Questa query API può essere utilizzata per creare una pagina segreta personalizzata 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 della 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",
"ciphertext": "il testo cifrato del segreto",
"password_part_private": "la parte della password privata del segreto",
"message": "il messaggio per il segreto, se impostato"
},
"metadata": {
"secrets_total": 1,
"secrets_usage": 1,
"secrets_allowance": 1
}
}
Esempio di codice
Consultate i nostri esempi di API.
Creare un segreto
Tipo di richiesta: POST
Percorso della richiesta: https://password.link/api/secrets
Codice di stato dell'interrogazione riuscita: 201 Created
Questa chiamata API supporta anche l'aggiunta di un allegato al segreto. Contattateci per maggiori dettagli.
Creare un segreto criptato.
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. Fare riferimento a <a href=\"https://github.com/bitwiseshiftleft/sjcl\">Documentazione SJCL</a> per il formato corretto della stringa JSON e vedere il nostro <a href=\"/p/docs/api/examples\">Esempi di API</a> per gli esempi su come creare il testo cifrato.
Creazione della password per la crittografia del segreto
La password utilizzata per criptare 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
=> Private part: fkgjbnvlakwiejgutn
=> Public part: FIGKEOTIRUBNAKQJRL
La parte privata deve essere codificata Base64 prima di essere inviata alla nostra API. Se si utilizza la pagina del segreto di visualizzazione fornita da noi, è necessario codificare Base64 anche la parte pubblica. Se si utilizza una pagina di segreto di visualizzazione autogestita, è possibile utilizzare lo stesso metodo o crearne una propria. Consultare il nostro <a href=\"/p/docs/api/examples\">Esempi di API</a> per le implementazioni di riferimento.
Impostazioni necessarie di 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 bits (impostazione SJCL: "ks:256")
- Funzione di derivazione della chiave: PBKDF2 (impostazione predefinita SJCL)
- Iterazioni di PBKDF2: 10000 (Impostazione SJCL: "iter:10000")
Carico utile della richiesta
{
"ciphertext": "ciphertext",
"password_part_private": "password_part_private",
"description": "description",
"message": "message",
"expiration": "expiration",
"view_button": "view_button",
"captcha": "captcha",
"password": "password",
"max_views": "max_views"
}
Parametri della richiesta
- ciphertext: Una stringa JSON di testo cifrato compatibile con SJCL del segreto, codificata in Base64.
- password_part_private: la parte della password privata che è stata utilizzata per criptare il segreto, in Base64.
- description (opzionale): una descrizione del segreto. Non può essere visto quando si visualizza il segreto.
- message (opzionale): un messaggio per il segreto. Verrà mostrato lungo il segreto.
- expiration (opzionale): un tempo di scadenza per il segreto, in ore. Valori possibili: 0-350.
- view_button (opzionale): mostra un pulsante di visualizzazione del segreto invece di mostrare il segreto immediatamente dopo l'apertura del collegamento. Per abilitare questa funzione, impostare questo valore su true.
- captcha (opzionale): mostra un semplice CAPTCHA prima di mostrare il segreto, soprattutto per bloccare gli scanner automatici. Per abilitare questa funzione, impostare questo parametro 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 dell'interrogazione 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 ciascuna query è limitata a 50. È possibile controllare l'offset con l'opzione offset parametro della query.
Ad esempio, per saltare i primi 50 record, utilizzare una query come: .../api/secrets?offset=50
Esempio di query
curl -H "Authorization: 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 per il segreto,
"description": la descrizione del segreto,
"view_button": è abilitato il pulsante di visualizzazione del segreto,
"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 visto,
"max_views": la quantità massima di volte in cui il segreto può essere visualizzato,
"views": [
{
"viewed_at": un timestamp di quando è stato visualizzato il segreto,
"viewed_by_ip": Indirizzo IP del visualizzatore,
"viewed_by_user_agent": agente utente del visualizzatore
}
]
}
],
"metadata": {
"secrets_total": 1,
"secrets_usage": 1,
"secrets_allowance": 1
}
}
Cancellare il segreto
Tipo di richiesta: DELETE
Percorso della richiesta: https://password.link/api/secrets/<id>
Codice di stato dell'interrogazione riuscita: 200 OK
Cancellare un segreto.
Esempio di query
curl -H "Authorization: ApiKey private_key_abcd" \\
-X DELETE https://password.link/api/secrets/dT5g
Esempio di risposta
{
"data": null,
"metadata": {
"secrets_total": 1,
"secrets_usage": 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
Limite e offset
Il numero massimo di risultati restituiti per ogni query è limitato 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}
}