Privatnotiz Public API
Sichere, verschlüsselte Nachrichten programmgesteuert erstellen und abrufen
Inhaltsverzeichnis
🔍 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
Verfügbare Befehle
Nachricht senden
Erstellt eine verschlüsselte Nachricht mit 48 Stunden Ablaufzeit.
Passwortgeschützte Nachricht
Erstellt eine passwortgeschützte Nachricht (Passwort wird interaktiv abgefragt).
Nachricht lesen
Ruft eine Nachricht ab und entschlüsselt sie lokal.
Passwortgeschützte Nachricht lesen
API Status prüfen
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.
Privatnotiz API