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 im Authorization: ApiKey <key> Header gesendet werden, wie:

Authorization: ApiKey public_key_abc...

Bei einer erfolglosen Abfrage enthält die Antwort ein Fehlerobjekt.

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 ebenfalls einen Fehler an, z. B:

• 403 Forbidden: die Anfrage war nicht zulässig, z. B. wegen eines ungültigen API-Schlüssels
• 404 Not Found: das angeforderte Geheimnis wurde nicht gefunden

Art der Anfrage: GET

Abfragepfad: https://password.link/api/secrets/<id>

Statuscode der erfolgreichen Abfrage: 200 OK

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

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

Der erfolgreiche Abruf eines Geheimnisses markiert es automatisch als angesehen und löscht somit den Chiffretext und den privaten Kennwortteil aus unserer Datenbank, so dass es unmöglich ist, das Geheimnis erneut anzuzeigen.

Erforderliche Parameter

• id: die ID des Geheimnisses, zum Beispiel dT5g

Abfrage-Beispiel

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

Antwort-Beispiel

{
"data": {
  "id":"die ID des Geheimnisses",
  "ciphertext": "der Chiffretext des Geheimnisses",
  "password_part_private": "der private Passwortteil des Geheimnisses",
  "message":"die Nachricht für das Geheimnis, falls festgelegt"
},
"metadata": {
  "secrets_total": 1,
  "secrets_usage": 1,
  "secrets_allowance": 1
  }
}

Code-Beispiel

Bitte sehen Sie sich unsere API-Beispiele an.

Typ der Anfrage: POST

Abfragepfad: https://password.link/api/secrets

Statuscode der erfolgreichen Abfrage: 201 Erstellt

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 client-seitig zu verschlüsseln, bevor es an unsere API gesendet wird, muss ein SJCL-kompatibler JSON-String mit Chiffretext erstellt werden. Das korrekte Format des JSON-Strings entnehmen Sie bitte der SJCL-Dokumentation, und in unseren API-Beispielen finden Sie Beispiele für die Erstellung des Chiffriertextes.

Erstellen des Kennworts 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 Chiffrierschlüssel ist die Verkettung dieser beiden Zeichenfolgen ("privater Teil" + "öffentlicher Teil") und wird von SJCL mithilfe von PBKDF2 aus dem Kennwort abgeleitet.

Beispiel für die Erstellung des privaten und öffentlichen Teils des Passworts:

Passwort: fkgjbnvlakwiejgutnFIGKEOTIRUBNAKQJRL
=> Privater Teil: fkgjbnvlakwiejgutn
=> Öffentlicher Teil: FIGKEOTIRUBNAKQJRL

Der private Teil muss vor der Übermittlung an unsere API in Base64 kodiert werden. Wenn Sie die von uns zur Verfügung gestellte Seite view secret verwenden, müssen Sie auch den öffentlichen Teil Base64-kodieren. Wenn Sie eine selbst gehostete geheime Ansichtsseite verwenden, können Sie dieselbe Methode verwenden oder eine eigene erstellen. Bitte sehen Sie sich unsere API-Beispiele für Referenzimplementierungen an.

Erforderliche SJCL-AES-Einstellungen

Bei der 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 Bit (SJCL-Einstellung: "ks:256")
• Schlüsselableitungsfunktion: PBKDF2 (SJCL-Voreinstellung)
• PBKDF2-Iterationen: 10000 (SJCL-Einstellung: "iter:10000")

Nutzdaten der Anfrage

{
"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 der Anfrage

• ciphertext: Ein SJCL-kompatibler JSON-Chiffretext-String des Geheimnisses, kodiert in Base64.
• password_part_private: der private Passwortteil, der zur Verschlüsselung des Geheimnisses verwendet wurde, im Base64-Format.
• description (optional): eine Beschreibung für das Geheimnis. Kann bei der Anzeige des Geheimnisses nicht gesehen werden.
• message (optional): eine Nachricht für das Geheimnis. Wird zusammen mit dem Geheimnis angezeigt.
• expiration (optional): eine Ablaufzeit für das Geheimnis, in Stunden. Mögliche Werte: 0-350.
• view_button (optional): Zeigt eine Schaltfläche zum Anzeigen des Geheimnisses an, anstatt das Geheimnis sofort nach dem Öffnen des Links anzuzeigen. Um diese Funktion zu aktivieren, setzen Sie diesen Wert auf true.
• captcha (optional): zeigt ein einfaches CAPTCHA an, bevor das Geheimnis angezeigt wird, hauptsächlich um automatische Scanner zu blockieren. Um diese Funktion zu aktivieren, setzen Sie diesen Wert auf true.
• password (optional): ein Passwort für das Geheimnis.
• max_views (optional): wie oft das Geheimnis angesehen werden kann. Mögliche Werte: 1-100.

Code-Beispiel

Bitte sehen Sie sich unsere API-Beispiele an.

Typ der Anfrage: GET

Abfragepfad: https://password.link/api/secrets

Statuscode der erfolgreichen Abfrage: 200 OK

Abrufen einer Liste von Geheimnissen. Enthält nicht die Teile der Chiffretexte für private Passwörter, 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 Abfrageparameter offset steuern.

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

Abfrage-Beispiel

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

Beispiel für eine Antwort

{
"data": [
  {
    "id": die ID des Geheimnisses,
    "created_at": wann das Geheimnis erstellt 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": Verfügt das Geheimnis über ein Passwort,
    "expiration": Verfallszeit in Stunden,
    "expired": ist das Geheimnis abgelaufen,
    "view_times": wie oft wurde das Geheimnis bereits angesehen,
    "max_views": die maximale Anzahl der Aufrufe des Geheimnisses,
    "views": [
      {
        "viewed_at": ein Zeitstempel, wann das Geheimnis angesehen wurde,
        "viewed_by_ip": IP-Adresse des Betrachters,
        "viewed_by_user_agent": Benutzer-Agent des Betrachters
      }
    ]
  }
],
"metadata": {
  "secrets_total": 1,
  "secrets_usage": 1,
  "secrets_allowance": 1
}
}

Typ der Anfrage: DELETE

Abfragepfad: https://password.link/api/secrets/<id>

Statuscode der erfolgreichen Abfrage: 200 OK

Löschen eines Geheimnisses.

Beispiel für eine Abfrage

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

Antwort-Beispiel

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