Privatnotiz Public API

Sichere, verschlüsselte Nachrichten programmgesteuert erstellen und abrufen

🔍 API Übersicht

Die Privatnotiz Public API ermöglicht es Entwicklern, verschlüsselte Nachrichten programmatisch zu erstellen und abzurufen. Alle Nachrichten werden client-seitig mit AES-256-CBC verschlüsselt, bevor sie an den Server gesendet werden.

🔒 Client-seitige Verschlüsselung

AES-256-CBC Verschlüsselung wird vollständig auf der Client-Seite durchgeführt

🔥 Einmal-Abruf

Nachrichten werden automatisch nach dem ersten Lesen gelöscht

⏰ Zeitbasierte Löschung

Nachrichten können mit einer Ablaufzeit von 1-168 Stunden versehen werden

🛡️ Passwort-Schutz

Optional können Nachrichten zusätzlich mit einem Passwort geschützt werden

Base URL

https://api.privatnotiz.de

🔐 Authentifizierung

Die öffentliche API erfordert keine Authentifizierung. Allerdings muss die API vom Administrator aktiviert werden.

API Status prüfen

Bevor Sie die API verwenden, sollten Sie prüfen, ob sie aktiviert ist:

GET https://api.privatnotiz.de/

📡 API Endpoints

GET/

Beschreibung: Überprüft den Status der öffentlichen API

Response

{
  "enabled": true
}

Status Codes

Code Beschreibung
200 API Status erfolgreich abgerufen
503 API ist deaktiviert

POST/

Beschreibung: Erstellt eine neue verschlüsselte Nachricht

Request Body

{
  "data": "base64_encrypted_message",
  "iv": "base64_initialization_vector",
  "expiresIn": 24,
  "password": "optional_sha256_hash"
}

Parameter

Parameter Typ Erforderlich Beschreibung
data string Base64-kodierte verschlüsselte Nachricht
iv string Base64-kodierter Initialisierungsvektor (16 Bytes)
expiresIn number Ablaufzeit in Stunden (1-168, Standard: 24)
password string SHA-256 Hash des Passworts

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://privatnotiz.de/secret/550e8400-e29b-41d4-a716-446655440000",
  "message": "Geheime Nachricht erfolgreich erstellt",
  "password_protected": false
}

Status Codes

Code Beschreibung
201 Nachricht erfolgreich erstellt
400 Ungültige Parameter oder Verschlüsselung
503 API ist deaktiviert

GET/:id

Beschreibung: Ruft eine verschlüsselte Nachricht ab und löscht sie automatisch

Parameter

Parameter Typ Beschreibung
id string UUID der Nachricht (URL-Parameter)
password string SHA-256 Hash des Passworts (Query-Parameter)

Response

{
  "data": "base64_encrypted_message",
  "iv": "base64_initialization_vector",
  "created_at": "2024-01-15T10:30:00Z",
  "password_protected": false,
  "deleted": true
}

Status Codes

Code Beschreibung
200 Nachricht erfolgreich abgerufen
403 Passwort erforderlich oder falsch
404 Nachricht nicht gefunden oder abgelaufen

HEAD/:id

Beschreibung: Prüft, ob eine Nachricht existiert und ob sie passwortgeschützt ist

Response Headers

X-Password-Protected: true|false

Status Codes

Code Beschreibung
200 Nachricht existiert
404 Nachricht nicht gefunden

⚡ CLI Tool

Das offizielle Privatnotiz CLI Tool bietet eine einfache Möglichkeit, die API über die Kommandozeile zu nutzen.

Installation

npm install -g privatnotiz-cli

Verfügbare Befehle

Nachricht senden

privatnotiz send -m "Meine geheime Nachricht" -e 48

Erstellt eine verschlüsselte Nachricht mit 48 Stunden Ablaufzeit.

Passwortgeschützte Nachricht

privatnotiz send -m "Streng geheim" -p

Erstellt eine passwortgeschützte Nachricht (Passwort wird interaktiv abgefragt).

Nachricht lesen

privatnotiz read -u "https://privatnotiz.de/secret/abc123#key=..."

Ruft eine Nachricht ab und entschlüsselt sie lokal.

Passwortgeschützte Nachricht lesen

privatnotiz read -u "https://privatnotiz.de/secret/abc123#key=..." -p "MeinPasswort"

API Status prüfen

privatnotiz status

GitHub Repository

Den vollständigen Quellcode und weitere Dokumentation finden Sie auf GitHub:

💻 Code Beispiele

JavaScript/Node.js

const crypto = require('crypto');
const axios = require('axios');

// Nachricht verschlüsseln und senden
async function createSecretMessage(message, expiresIn = 24) {
  const key = crypto.randomBytes(32); // 256-bit AES key
  const iv = crypto.randomBytes(16);  // 128-bit IV
  
  const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
  let encrypted = cipher.update(message, 'utf8', 'base64');
  encrypted += cipher.final('base64');
  
  const response = await axios.post('https://api.privatnotiz.de/', {
    data: encrypted,
    iv: iv.toString('base64'),
    expiresIn: expiresIn
  });
  
  const keyBase64 = key.toString('base64');
  const secretUrl = `${response.data.url}#key=${encodeURIComponent(keyBase64)}`;
  
  return secretUrl;
}

Python

import base64
import json
import requests
from Crypto.Cipher import AES
from Crypto.Random import get_random_bytes

def create_secret_message(message, expires_in=24):
    key = get_random_bytes(32)  # 256-bit AES key
    iv = get_random_bytes(16)   # 128-bit IV
    
    cipher = AES.new(key, AES.MODE_CBC, iv)
    
    # Padding für AES
    pad_len = 16 - len(message.encode()) % 16
    padded_message = message + chr(pad_len) * pad_len
    
    encrypted = cipher.encrypt(padded_message.encode())
    
    data = {
        'data': base64.b64encode(encrypted).decode(),
        'iv': base64.b64encode(iv).decode(),
        'expiresIn': expires_in
    }
    
    response = requests.post('https://api.privatnotiz.de/', json=data)
    result = response.json()
    
    key_base64 = base64.b64encode(key).decode()
    secret_url = f"{result['url']}#key={key_base64}"
    
    return secret_url

cURL

# Nachricht erstellen
curl -X POST https://api.privatnotiz.de/ \
  -H "Content-Type: application/json" \
  -d '{
    "data": "base64_encrypted_data",
    "iv": "base64_iv",
    "expiresIn": 24
  }'

# Nachricht abrufen
curl -X GET https://api.privatnotiz.de/550e8400-e29b-41d4-a716-446655440000

# API Status prüfen
curl -X GET https://api.privatnotiz.de/

🛡️ Sicherheitsmerkmale

🔐 AES-256-CBC Verschlüsselung

Industriestandard-Verschlüsselung mit 256-bit Schlüsseln

🖥️ Client-seitige Verschlüsselung

Nachrichten werden lokal verschlüsselt, bevor sie gesendet werden

🔑 Sichere Schlüsselübertragung

Entschlüsselungsschlüssel wird nur im URL-Fragment übertragen

🔥 Auto-Löschung

Nachrichten werden nach dem ersten Lesen automatisch gelöscht

Wichtige Sicherheitshinweise

  • Der Entschlüsselungsschlüssel wird niemals an den Server übertragen
  • Nachrichten werden auf dem Server nur verschlüsselt gespeichert
  • Jede Nachricht kann nur einmal abgerufen werden
  • Abgelaufene Nachrichten werden automatisch gelöscht
  • Passwörter werden als SHA-256 Hash übertragen und gespeichert

⚠️ Fehlerbehandlung

Standard Fehlercodes

Code Grund Beschreibung
400 MISSING_PARAMS Erforderliche Parameter fehlen
400 INVALID_ENCRYPTION Ungültige Verschlüsselung oder IV
400 INVALID_EXPIRY Ablaufzeit außerhalb gültiger Grenzen (1-168h)
403 PASSWORD_REQUIRED Nachricht ist passwortgeschützt
403 INVALID_PASSWORD Falsches Passwort angegeben
404 NOT_FOUND Nachricht nicht gefunden oder bereits gelesen
503 API_DISABLED Öffentliche API ist deaktiviert

Beispiel Fehlerantwort

{
  "error": "Diese Nachricht ist passwortgeschützt",
  "code": "PASSWORD_REQUIRED",
  "password_protected": true
}

Rate Limiting

Die API implementiert Rate Limiting zum Schutz vor Missbrauch:

  • Erstellen: 2 Anfragen pro Minute
  • Lesen: 3 Anfragen pro Minute
  • Status: 5 Anfragen pro Minute

Bei Überschreitung wird ein 429 Status Code mit einem Retry-After Header zurückgegeben.