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 Anhangs zum Geheimnis. Bitte kontaktieren Sie uns für weitere Details.

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

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.

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