Dokumention - API

Allgemein

Wir haben eine Standard-REST-API für die Verwaltung von Geheimnissen. Alle Anfragen und Antworten verwenden die JSON format.

Sie können die API verwenden, um sowohl die Verschlüsselung als auch die Entschlüsselung des Geheimnisses außerhalb unseres Dienstes zu handhaben, ohne dass Sie irgendwelche Assets von uns laden müssen. Außerdem können Sie jede beliebige Übermittlungsmethode für den Teil des öffentlichen Kennworts (die Hälfte des Kennworts, aus dem der Verschlüsselungsschlüssel für das Geheimnis abgeleitet wird) verwenden und grundsätzlich jede beliebige benutzerdefinierte Konfiguration für die Anzeige des Geheimnisses erstellen.

Code-Beispiele

Bitte sehen Sie sich unsere API-Beispiele an, um zu erfahren, wie Sie die API verwenden können.

Authentifizierung

Wir verwenden zwei Arten von API-Schlüsseln für die Authentifizierung:

  • Öffentliche API-Schlüssel
  • Private API-Schlüssel

Öffentliche API-Schlüssel sind für die Erstellung einer benutzerdefinierten, selbst gehosteten Geheimansichtsseite gedacht. Alle anderen API-Aktionen erfordern einen privaten API-Schlüssel.

Öffentliche API-Schlüssel können in öffentlichen Skripten verwendet werden. Private API-Schlüssel müssen immer geheim gehalten werden.

Beide API-Schlüssel enthalten den Typ des Schlüssels im Schlüssel selbst, so dass sie leicht unterschieden werden können.

Der API-Schlüssel muss in der Datei Authorization: ApiKey <key> kopfzeile, wie:

Authorization: ApiKey public_key_abc...

Fehler

Im Falle einer erfolglosen Abfrage wird die Antwort mit einem error objekt.

Das Objekt enthält die folgenden Felder:

  • message: die vollständige Fehlermeldung, z. B. "Ciphertext can't be blank"
  • field: das Feld, auf das sich der Fehler bezieht, z. B. "ciphertext"

Der HTTP-Antwortstatuscode zeigt auch einen Fehler an, zum Beispiel:

  • 403 Forbidden: Die Anfrage war nicht erlaubt, zum Beispiel wegen eines ungültigen API-Schlüssels
  • 404 Not Found: das angeforderte Geheimnis wurde nicht gefunden

Ansicht Geheimnis

Art der Anfrage: GET

Pfad anfordern: https://password.link/api/secrets/<id>

Statuscode der erfolgreichen Abfrage: 200 OK


Holt den Chiffretext, den privaten Passwortteil und andere Details eines Geheimnisses. Erfordert die öffentlich API-Schlüssel.

Diese API-Abfrage kann verwendet werden, um eine benutzerdefinierte, selbst gehostete geheime Ansichtsseite zu erstellen, die keine Skripte oder andere Assets von unserem Dienst lädt.

Das erfolgreiche Abrufen eines Geheimnisses markiert es automatisch als angesehen und löscht somit den Geheimtext und den Teil des privaten Kennworts aus unserer Datenbank, so dass es unmöglich ist, das Geheimnis erneut einzusehen.

Erforderliche Parameter
  • id: die ID des Geheimnisses, zum Beispiel dT5g

Beispiel für eine Abfrage

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

Beispiel für eine Antwort

{
        "data": {
          "id": "die ID des Secrets",
          "ciphertext": "den Chiffretext des Geheimnisses",
          "password_part_private": "das private Passwort als Teil des Geheimnisses",
          "message": "die Nachricht für das Geheimnis, falls gesetzt"
        },
        "metadata": {
          "secrets_total": 1,
          "secrets_usage": 1,
          "secrets_allowance": 1
        }
      }

Code-Beispiel

Bitte beachten Sie unsere API-Beispiele.

Geheimnis erstellen

Art der Anfrage: POST

Pfad anfordern: https://password.link/api/secrets

Statuscode der erfolgreichen Abfrage: 201 Created

Dieser API-Aufruf unterstützt auch das Hinzufügen eines verschlüsselten Dateianhangs zum Geheimnis.


Erstellen Sie ein verschlüsseltes Geheimnis.

Um das Geheimnis clientseitig zu verschlüsseln, bevor es an unsere API gesendet wird, muss ein SJCL-kompatibler JSON-String für den Chiffretext erstellt werden. Das richtige Format der JSON-Zeichenfolge finden Sie in <a href=\"https://github.com/bitwiseshiftleft/sjcl\">SJCL-Dokumentation</a>, Beispiele für die Erstellung des Chiffriertextes finden Sie in <a href=\"/p/docs/api/examples\">API-Beispiele</a>.

Erstellung des Passworts für die Verschlüsselung des Geheimnisses

Das Passwort, das zur Verschlüsselung des Geheimnisses in AES verwendet wird, muss aus zwei 18 Zeichen langen Zeichenketten bestehen. Der eigentliche Verschlüsselungsschlüssel ist die Verkettung dieser beiden Zeichenfolgen ("privater Teil" + "öffentlicher Teil") und wird von SJCL unter Verwendung von PBKDF2 aus dem Passwort abgeleitet.

Beispiel für die Erstellung eines privaten und eines öffentlichen Kennworts:

Password: fkgjbnvlakwiejgutnFIGKEOTIRUBNAKQJRL
        => Private part: fkgjbnvlakwiejgutn
        => Public part: FIGKEOTIRUBNAKQJRL

Der private Teil muss vor der Übermittlung an unsere API mit Base64 kodiert werden. Wenn Sie die von uns bereitgestellte geheime Seite verwenden, müssen Sie auch den öffentlichen Teil mit Base64 kodieren. Wenn Sie eine selbst gehostete geheime Ansichtsseite verwenden, können Sie dieselbe Methode anwenden oder Ihre eigene erstellen. Bitte sehen Sie sich unsere <a href=\"/p/docs/api/examples\">API-Beispiele</a> für Referenzimplementierungen an.

Erforderliche SJCL-AES-Einstellungen

Für die Verschlüsselung des Geheimnisses müssen Sie die folgenden Einstellungen für AES verwenden:

  • Modus: AES-GCM (SJCL-Einstellung: "mode:gcm")
  • Schlüsselgröße: 256 bits (SJCL-Einstellung: "ks:256")
  • Funktion der Schlüsselableitung: PBKDF2 (SJCL-Standard)
  • PBKDF2-Iterationen: 10000 (SJCL-Einstellung: "iter:10000")

Nutzlast anfordern

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

Parameter anfordern

  • ciphertext: Eine SJCL-kompatible JSON-Zeichenkette des Geheimnisses, verschlüsselt in Base64.
  • password_part_private: den Teil des privaten Passworts, der zur Verschlüsselung des Geheimnisses verwendet wurde, in Base64.
  • description (optional): eine Beschreibung für das Geheimnis. Kann beim Betrachten des Geheimnisses nicht gesehen werden.
  • message (optional): eine Nachricht für das Geheimnis. Wird entlang des Geheimnisses gezeigt werden.
  • expiration (optional): eine Verfallszeit für das Geheimnis in Stunden. Mögliche Werte: 0-350.
  • view_button (optional): eine Schaltfläche "Geheimnis anzeigen" anzeigen, anstatt das Geheimnis sofort nach dem Öffnen des Links anzuzeigen. Um diese Funktion zu aktivieren, setzen Sie dies auf true.
  • captcha (optional): vor der Anzeige des Geheimnisses ein einfaches CAPTCHA anzeigen, hauptsächlich um automatische Scanner zu blockieren. Um diese Funktion zu aktivieren, setzen Sie dies auf true.
  • password (optional): ein Passwort für das Geheimnis.
  • max_views (optional): wie oft das Geheimnis eingesehen werden kann. Mögliche Werte: 1-100.
  • attachment (optional): Metadaten für einen verschlüsselten Dateianhang. Erfordert einen aktiven Plan. Die verschlüsselte Datei wird separat hochgeladen, nachdem das Geheimnis erstellt wurde.
  • attachment.file_name (erforderlich, wenn ein Anhang angegeben wird): der ursprüngliche Dateiname, der dem Empfänger angezeigt wird.
  • attachment.file_type (erforderlich, wenn ein Anhang angegeben wird): der ursprüngliche MIME-Typ, zum Beispiel text/plain oder application/pdf.
  • attachment.file_size (erforderlich, wenn ein Anhang angegeben wird): die ursprüngliche unverschlüsselte Dateigröße in Bytes.

Anhang hochladen

Das Hochladen eines Anhangs ist ein zweistufiger Prozess: Erstellen Sie zuerst das Geheimnis mit Anhangsmetadaten, verschlüsseln Sie dann die verschlüsselte Anhang-Nutzlast und laden Sie sie an die zurückgegebene Upload-URL hoch.

Der Inhalt des Geheimnisses und der Inhalt des Anhangs werden separat verschlüsselt. Der Geheimnis-Chiffretext ist SJCL-kompatible AES-GCM-Daten, Base64-codiert. Der Anhang wird mit Web-Crypto-kompatiblen AES-GCM-Daten verschlüsselt und anschließend Base64-codiert.

Das Passwort für die Anhangsverschlüsselung ist der rohe private Passwortteil, verkettet mit dem rohen öffentlichen Passwortteil: <raw private password part> + <raw public password part>.

Wenn ein Anhang enthalten ist, enthält die Antwort zum Erstellen des Geheimnisses ein Upload-Ziel in data.attachment.upload:

{
        "data": {
          "id": "dT5g",
          "attachment": {
            "file_name": "example.txt",
            "upload": {
              "url": "/api/secrets/dT5g/attachment",
              "fields": {},
              "metadata": {}
            }
          }
        },
        "metadata": {}
      }

Bei Password.link-gehosteten Upload-URLs ist das fields-Objekt leer. Bei direkten Speicher-Upload-URLs, z. B. vorab signierten S3-URLs, werden die Signierfelder stattdessen in metadata zurückgegeben.

Stellen Sie die Datei vor der Verschlüsselung als Daten-URL dar: data:<mime-type>;base64,<base64 file bytes>.

Verschlüsseln Sie diese Daten-URL-Zeichenfolge mit AES-GCM unter Verwendung von PBKDF2-SHA256, 10000 Iterationen, einem abgeleiteten 256-Bit-Schlüssel, einem zufälligen 16-Byte-Salt und einem zufälligen 12-Byte-IV. Speichern Sie die verschlüsselte Anhangsnutzlast als JSON-Objekt mit cipher, iv und salt, und codieren Sie dann die JSON-Zeichenfolge mit Base64.

{
        "cipher": "binary string",
        "iv": "binary string",
        "salt": "binary string"
      }

Laden Sie das Base64-codierte verschlüsselte JSON hoch als text/plain mit multipart/form-data an die zurückgegebene upload.url. Fügen Sie alle zurückgegebenen upload.metadata oder upload.fields Schlüssel/Wert-Paare zu den Formulardaten hinzu, bevor Sie die verschlüsselte Datei hinzufügen. Das Feld für die verschlüsselte Datei muss file.

Fügen Sie bei Password.link-Upload-URLs denselben privaten API-Schlüssel im Header Authorization: ApiKey <key> hinzu. Direkte Speicher-Upload-URLs, wie vorab signierte S3-URLs, sollten nur die zurückgegebenen Formularfelder und das verschlüsselte Feld file erhalten.

Die Antwort der API zum Erstellen eines Geheimnisses gibt ein Anhang-Upload-Ziel für den einzelnen attachment Parameter zurück. Die Größenlimits für Anhänge hängen vom Konto- oder Teamkontingent ab, und der verschlüsselte Upload ist größer als die Originaldatei, da die Datei in Base64 konvertiert und verschlüsselt wird.

Code-Beispiel

Bitte beachten Sie unsere API-Beispiele.

Liste Geheimnisse

Art der Anfrage: GET

Pfad anfordern: https://password.link/api/secrets

Statuscode der erfolgreichen Abfrage: 200 OK


Holt eine Liste von Geheimnissen. Enthält nicht die privaten Kennwortteile der Chiffretexte, sondern nur IDs, Beschreibungen und Ähnliches.

Limit und Offset

Die maximale Anzahl der zurückgegebenen Geheimnisse für jede Abfrage ist auf 50 begrenzt. Sie können den Offset mit dem optionalen offset abfrageparameter.

Um zum Beispiel die ersten 50 Datensätze zu überspringen, verwenden Sie eine Abfrage wie diese: .../api/secrets?offset=50

Beispiel für eine Abfrage

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

Beispiel für eine Antwort

{
        "data": [
          {
            "id": die ID des Secrets,
            "created_at": wann das Geheimnis geschaffen wurde,
            "message": die Nachricht für das Geheimnis,
            "description": die Beschreibung des Geheimnisses,
            "view_button": ist die Schaltfläche "Geheimnis anzeigen" aktiviert,
            "captcha": ist das CAPTCHA aktiviert,
            "password": hat das Geheimnis ein Passwort?,
            "expiration": verfallszeit in Stunden,
            "expired": das Geheimnis abgelaufen ist,
            "view_times": wie oft das Geheimnis bereits angesehen wurde,
            "max_views": wie oft das Geheimnis maximal eingesehen werden kann,
            "views": [
              {
                "viewed_at": einen Zeitstempel, wann das Geheimnis eingesehen wurde,
                "viewed_by_ip": IP-Adresse des Betrachters,
                "viewed_by_user_agent": user Agent des Betrachters
              }
            ]
          }
        ],
        "metadata": {
          "secrets_total": 1,
          "secrets_usage": 1,
          "secrets_allowance": 1
        }
      }

Geheimnis löschen

Art der Anfrage: DELETE

Pfad anfordern: https://password.link/api/secrets/<id>

Statuscode der erfolgreichen Abfrage: 200 OK


Löschen Sie ein Geheimnis.

Beispiel für eine Abfrage

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

Beispiel für eine Antwort

{
        "data": null,
        "metadata": {
          "secrets_total": 1,
          "secrets_usage": 1,
          "secrets_allowance": 1
        }
      }

Geheime Anfrage erstellen

Art der Anfrage: POST

Pfad anfordern: https://password.link/api/secret_requests

Statuscode der erfolgreichen Abfrage: 201 Created


Erstellen Sie einen neuen Geheimantrag.

Parameter anfordern

  • description: beschreibung für den Geheimen Antrag.
  • message: nachricht für den Secret Request Viewer.
  • expiration: verfallszeit für die Geheime Anfrage in Stunden.
  • limit: nutzungslimit für die Geheime Anfrage.
  • send_request_to_email: sendet den erstellten Link für die geheime Anfrage an die angegebene E-Mail-Adresse.
  • send_to_email: den mit dem Secret Request erstellten Secret Link an die angegebene E-Mail-Adresse senden.
  • secret_description: beschreibung des Geheimnisses, das mit der Geheimanfrage erstellt wurde.
  • secret_message: nachricht für das mit der Secret Request erstellte Secret.
  • secret_expiration: ablaufzeit für das mit der Secret Request erstellte Secret in Stunden.
  • secret_password: passwort für das mit der Secret Request erstellte Secret, in Stunden.
  • secret_max_views: ansichtsgrenze für das mit der Secret Request erstellte Secret.

Beispiel für eine Abfrage

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

Beispiel für eine Antwort

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

Liste der geheimen Ersuchen

Art der Anfrage: GET

Pfad anfordern: https://password.link/api/secret_requests

Statuscode der erfolgreichen Abfrage: 200 OK


Limit und Offset

Die maximale Anzahl der zurückgegebenen Ergebnisse für jede Abfrage ist auf 50 begrenzt. Sie können den Versatz mit dem optionalen Abfrageparameter offset steuern.

Um zum Beispiel die ersten 50 Datensätze zu überspringen, verwenden Sie eine Abfrage wie diese: .../api/secret_requests?offset=50

Beispiel für eine Abfrage

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

Beispiel für eine Antwort

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

Geheime Anfrage löschen

Art der Anfrage: DELETE

Pfad anfordern: https://password.link/api/secret_requests/<id>

Statuscode der erfolgreichen Abfrage: 200 OK


Eine geheime Anfrage löschen.

Beispiel für eine Abfrage

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

Beispiel für eine Antwort

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