API-dokumentation
Allmänt
Vi har ett standard REST API för att hantera hemligheter. Alla förfrågningar och svar använder JSON format.
Du kan använda API:et för att hantera både kryptering och dekryptering av hemligheten utanför vår tjänst, utan att behöva ladda några tillgångar från oss. Det tillåter också dig att använda vilken typ av leveransmetod som helst för den publika lösenordsdelen (halva lösenordet som används för att härleda krypteringsnyckeln för hemligheten från) och i princip skapa vilken typ av anpassad konfiguration som helst för att visa hemligheten.
Kodexempel
Vänligen se våra API-exempel om hur man använder API:et.
Autentisering
Vi använder två typer av API-nycklar för autentisering:
- Publika API-nycklar
- Privata API-nycklar
Publika API-nycklar är avsedda för att skapa en anpassad själv-hostad sida för visning av hemlighet. Alla andra API-åtgärder kräver en privat API-nyckel.
Publika API-nycklar kan användas i offentliga skript. Privata API-nycklar måste alltid hållas privata.
Båda API-nycklarna innehåller typ av nyckel i själva nyckeln så att de lätt kan särskiljas.
API-nyckeln måste skickas i Authorization: ApiKey <key> header, såsom:
Authorization: ApiKey public_key_abc...
Fel
Vid misslyckad förfrågan kommer svaret att ha ett error objekt.
Objektet innehåller följande fält:
- message: det fullständiga felmeddelandet, t.ex. "Ciphertext kan inte vara tom"
- field: fältet som felet gäller, t.ex. "ciphertext"
HTTP-svarsstatuskoden kommer också att indikera ett fel, till exempel:
- 403 Förbjudet: förfrågan tilläts inte, till exempel på grund av ogiltig API-nyckel
- 404 Hittades inte: den begärda hemligheten hittades inte
Visa hemlighet
Förfrågningstyp: GET
Förfrågningssökväg: https://password.link/api/secrets/<id>
Statuskod för lyckad förfrågan: 200 OK
Hämta chiffertexten, privata lösenordsdelen och andra detaljer om en hemlighet. Kräver publik API-nyckel.
Denna API-förfrågan kan användas för att skapa en anpassad själv-hostad sida för visning av hemlighet som inte laddar några skript eller andra tillgångar från vår tjänst.
Att framgångsrikt hämta en hemlighet markerar den automatiskt som visad och raderar därmed chiffertexten och den privata lösenordsdelen från vår databas, vilket gör det omöjligt att visa hemligheten igen.
Obligatoriska parametrar- id: id för hemligheten, till exempel dT5g
Exempel på fråga
curl -H "Authorization: ApiKey public_key_abcd" https://password.link/api/secrets/dT5g
Exempel på svar
{
"data": {
"id": "iD för den hemliga informationen",
"ciphertext": "chiffertexten för hemligheten",
"password_part_private": "den privata lösenordsdelen av hemligheten",
"message": "meddelandet för hemligheten, om angivet"
},
"metadata": {
"secrets_total": 1,
"secrets_usage": 1,
"secrets_allowance": 1
}
}
Kodexempel
Vänligen se våra API-exempel.
Skapa hemlighet
Förfrågningstyp: POST
Förfrågningssökväg: https://password.link/api/secrets
Statuskod för lyckad förfrågan: 201 Created
Detta API-anrop stöder också att lägga till en krypterad filbilaga till hemligheten.
Skapa en krypterad hemlighet.
Att kryptera hemligheten på klientsidan innan den skickas till vårt API kräver att en SJCL-kompatibel chiffertext JSON-sträng skapas. Vänligen se <a href=\"https://github.com/bitwiseshiftleft/sjcl\">SJCL-dokumentation</a> för korrekt format av JSON-strängen, och se våra <a href=\"/p/docs/api/examples\">Exempel på API</a> för exempel på hur man skapar chiffertexten.
Skapa lösenordet för att kryptera hemligheten
Lösenordet som används för att kryptera hemligheten i AES måste bestå av två 18 tecken långa strängar. Den faktiska krypteringsnyckeln kommer att vara sammanfogningen av dessa två strängar ("privat del" + "publik del") och härleds från lösenordet av SJCL med PBKDF2.
Exempel på att skapa de privata och publika lösenordsdelarna:
Password: fkgjbnvlakwiejgutnFIGKEOTIRUBNAKQJRL
=> Private part: fkgjbnvlakwiejgutn
=> Public part: FIGKEOTIRUBNAKQJRL
Den privata delen måste vara Base64-kodad innan den skickas till vårt API. Om du använder sidan för visning av hemlighet som tillhandahålls av oss måste du också Base64-koda den publika delen. Om du använder en själv-hostad sida för visning av hemlighet kan du använda samma metod eller skapa din egen. Vänligen se våra <a href=\"/p/docs/api/examples\">Exempel på API</a> för referensimplementationer.
Obligatoriska SJCL AES-inställningar
Du måste använda följande inställningar för AES när du krypterar hemligheten:
- Läge: AES-GCM (SJCL-inställning: "mode:gcm")
- Nyckelstorlek: 256 bits (SJCL-inställning: "ks:256")
- Nyckel härledningsfunktion: PBKDF2 (SJCL standard)
- PBKDF2-iterationer: 10000 (SJCL-inställning: "iter:10000")
Förfrågningsdata
{
"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",
"attachment": {
"file_name": "file_name",
"file_type": "file_type",
"file_size": "file_size"
}
}
Parametrar för begäran
- ciphertext: En SJCL-kompatibel chiffertext JSON-sträng av hemligheten, kodad i Base64.
- password_part_private: den privata lösenordsdelen som användes för att kryptera hemligheten, i Base64.
- description (valfri): en beskrivning för hemligheten. Kan inte ses när hemligheten visas.
- message (valfri): ett meddelande för hemligheten. Visas tillsammans med hemligheten.
- expiration (valfri): en utgångstid för hemligheten, i timmar. Möjliga värden: 0-350.
- view_button (valfri): visa en knapp för att visa hemlighet istället för att visa hemligheten omedelbart efter att länken öppnats. För att aktivera denna funktion, ställ in detta till true.
- captcha (valfri): visa en enkel CAPTCHA innan hemligheten visas, huvudsakligen för att blockera automatiserade skannrar. För att aktivera denna funktion, ställ in detta till true.
- password (valfri): ett lösenord för hemligheten.
- max_views (valfri): hur många gånger hemligheten kan ses. Möjliga värden: 1-100.
- attachment (valfri): metadata för en krypterad filbilaga. Kräver en aktiv plan. Den krypterade filen laddas upp separat efter att hemligheten har skapats.
- attachment.file_name (krävs när bilaga anges): det ursprungliga filnamnet som visas för mottagaren.
- attachment.file_type (krävs när bilaga anges): den ursprungliga MIME-typen, till exempel text/plain eller application/pdf.
- attachment.file_size (krävs när bilaga anges): den ursprungliga okrypterade filstorleken i byte.
Ladda upp en bilaga
Att ladda upp en bilaga är en tvåstegsprocess: skapa först hemligheten med bilagans metadata, kryptera sedan och ladda upp den krypterade bilagelasten till den returnerade uppladdnings-URL:en.
Hemlighetens innehåll och bilagans innehåll krypteras separat. Hemlighetens chiffertext är SJCL-kompatibla AES-GCM-data, Base64-kodade. Bilagan krypteras med Web Crypto-kompatibla AES-GCM-data och Base64-kodas sedan.
Krypteringslösenordet för bilagan är den råa privata lösenordsdelen sammanfogad med den råa publika lösenordsdelen: <raw private password part> + <raw public password part>.
När en bilaga inkluderas innehåller svaret från skapandet av hemligheten ett uppladdningsmål i data.attachment.upload:
{
"data": {
"id": "dT5g",
"attachment": {
"file_name": "example.txt",
"upload": {
"url": "/api/secrets/dT5g/attachment",
"fields": {},
"metadata": {}
}
}
},
"metadata": {}
}
Uppladdnings-URL:er som hostas på Password.link inkluderar ett tomt fields-objekt. Direkta lagringsuppladdnings-URL:er, såsom förhandsignerade S3-URL:er, returnerar signeringsfält i metadata istället.
Före kryptering representerar du filen som en data-URL: data:<mime-type>;base64,<base64 file bytes>.
Kryptera den data-URL-strängen med AES-GCM med PBKDF2-SHA256, 10000 iterationer, en härledd 256-bitarsnyckel, ett slumpmässigt 16-byte salt och en slumpmässig 12-byte IV. Lagra den krypterade bilagans payload som ett JSON-objekt som innehåller cipher, iv och salt, och Base64-koda sedan JSON-strängen.
{
"cipher": "binary string",
"iv": "binary string",
"salt": "binary string"
}
Ladda upp den Base64-kodade krypterade JSON:en som text/plain med multipart/form-data till den returnerade upload.url. Lägg till alla returnerade upload.metadata eller upload.fields nyckel/värde-par i formulärdata innan du lägger till den krypterade filen. Fältet för den krypterade filen måste heta file.
För Password.link-uppladdnings-URL:er, inkludera samma privata API-nyckel i Authorization: ApiKey <key>-huvudet. Direkta uppladdnings-URL:er för lagring, till exempel försignerade S3-URL:er, ska endast ta emot de returnerade formulärfälten och det krypterade file-fältet.
API-svaret för att skapa hemlighet returnerar ett uppladdningsmål för bilagan för den enskilda attachment parametern. Storleksgränser för bilagor beror på konto- eller teamtilldelningen, och den krypterade uppladdningen är större än originalfilen eftersom filen konverteras till Base64 och krypteras.
Kodexempel
Vänligen se våra API-exempel.
Lista hemligheter
Förfrågningstyp: GET
Förfrågningssökväg: https://password.link/api/secrets
Statuskod för lyckad förfrågan: 200 OK
Hämta en lista över hemligheter. Innehåller inte chiffertexternas privata lösenordsdelar, endast ID:n, beskrivningar och liknande.
Limit och offset
Det maximala antalet returnerade hemligheter för varje förfrågan är begränsat till 50. Du kan kontrollera offset med den valfria offset frågeparameter.
Om du t.ex. vill hoppa över de första 50 posterna använder du en fråga som: .../api/secrets?offset=50
Exempel på fråga
curl -H "Authorization: ApiKey private_key_abcd" https://password.link/api/secrets
Exempel på svar
{
"data": [
{
"id": iD för den hemliga informationen,
"created_at": när hemligheten skapades,
"message": meddelandet för hemligheten,
"description": beskrivningen av hemligheten,
"view_button": är knappen visa hemlighet aktiverad,
"captcha": är CAPTCHA aktiverad,
"password": har hemligheten ett lösenord,
"expiration": utgångstid i timmar,
"expired": har hemligheten gått ut,
"view_times": hur många gånger hemligheten har visats,
"max_views": maximalt antal gånger hemligheten kan ses,
"views": [
{
"viewed_at": en tidsstämpel för när hemligheten visades,
"viewed_by_ip": IP-adress för visaren,
"viewed_by_user_agent": användar agent för visaren
}
]
}
],
"metadata": {
"secrets_total": 1,
"secrets_usage": 1,
"secrets_allowance": 1
}
}
Radera hemlighet
Förfrågningstyp: DELETE
Förfrågningssökväg: https://password.link/api/secrets/<id>
Statuskod för lyckad förfrågan: 200 OK
Radera en hemlighet.
Exempel på fråga
curl -H "Authorization: ApiKey private_key_abcd" \\
-X DELETE https://password.link/api/secrets/dT5g
Exempel på svar
{
"data": null,
"metadata": {
"secrets_total": 1,
"secrets_usage": 1,
"secrets_allowance": 1
}
}
Skapa hemlig begäran
Typ av begäran: POST
Sökväg för begäran: https://password.link/api/secret_requests
Statuskod för framgångsrik fråga: 201 Created
Skapa en ny hemlig begäran.
Parametrar för begäran
- description: beskrivning för den hemliga begäran.
- message: meddelande för Secret Request-tittaren.
- expiration: utgångstid för den hemliga begäran, i timmar.
- limit: användningsgräns för den hemliga begäran.
- send_request_to_email: skicka den skapade länken för hemlig begäran till den angivna e-postadressen.
- send_to_email: skicka den hemliga länken som skapats med hjälp av den hemliga begäran till den angivna e-postadressen.
- secret_description: beskrivning för den hemlighet som skapats med hjälp av hemlighetsbegäran.
- secret_message: meddelande för den hemlighet som skapats med hjälp av hemlighetsbegäran.
- secret_expiration: utgångstid för hemligheten som skapas med den hemliga förfrågan, i timmar.utgångstid i timmar för den hemlighet som skapats med hjälp av hemlighetsbegäran.
- secret_password: lösenord för hemligheten som skapas med den hemliga förfrågan, i timmar.lösenord för den hemlighet som skapats med hjälp av hemlighetsbegäran, i timmar.
- secret_max_views: visningsgräns för den hemlighet som skapats med hjälp av hemlighetsbegäran.
Exempel på fråga
curl -H "Authorization: ApiKey private_key_abcd" \
-H "Content-Type: application/json" -X POST https://password.link/api/secret_requests
Exempel på svar
{
"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
}
}
Lista hemliga förfrågningar
Typ av begäran: GET
Sökväg för begäran: https://password.link/api/secret_requests
Statuskod för framgångsrik fråga: 200 OK
Limit och offset
Det maximala antalet returnerade resultat för varje förfrågan är begränsat till 50. Du kan kontrollera offset med den valfria offset-frågeparametern.
Om du t.ex. vill hoppa över de första 50 posterna använder du en fråga som: .../api/secret_requests?offset=50
Exempel på fråga
curl -H "Authorization: ApiKey private_key_abcd" https://password.link/api/secret_requests
Exempel på svar
{
"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
}
}
Begäran om att ta bort hemlighet
Typ av begäran: DELETE
Sökväg för begäran: https://password.link/api/secret_requests/<id>
Statuskod för framgångsrik fråga: 200 OK
Ta bort en hemlig begäran.
Exempel på fråga
curl -H "Authorization: ApiKey private_key_abcd" \
-X DELETE https://password.link/api/secret_requests/5e976e6e-d205-4f58-8df9-5ac0048bc702
Exempel på svar
{
"data": null,
"metadata": {
"secrets_total":70,
"secrets_usage":25,
"secrets_allowance":100,
"secret_requests_total":10,
"secret_requests_allowance":100}
}