Sblam!

Zabezpiecza formularze przed spamem

There is an English version of this document.

To jest dokumentacja API serwera przeznaczona dla twórców wtyczek. Jeśli chcesz dodać filtr do stron napisanych w PHP lub Perl, wystarczy, że skorzystasz z już istniejących wtyczek.

Automatyczne logowanie

Strona statystyk może być otworzona automatycznie za pomocą linku w postaci:

https://sblam.com/key.html?autologin=apikeyhash:time:sig

gdzie:

  • apikeyhash to hash MD5 (jako hex, 32 znaki) ciągu: „^&$@$2\n” + klucz API + „@@”. \n to znak przejścia do nowej linii (LF).
  • time to czas w formacie unix timestamp, kiedy link ma stracić ważność (użyj czegoś w rodzaju time()+3600)
  • sig to hash MD5 ciągu: time + klucz API

Na przykład link dla klucza „abc123abc123” ważny do 13.12.2007 14:19:27 ma mieć wartość autologin:

b7fc0a3373502b96f23c0cae099993d2:1197555567:e65ca523a9c8d687be2ebddbb86869f4

Automatyczne generowanie kluczy API

Pobierz zawartość spod adresu: https://sblam.com/keygen.html

API serwera

Znajomość API serwera jest potrzebna tylko do napisania wtyczki dla innych języków programowania, niż PHP i Perl (dla których są już oficjalne wtyczki).

Serwer używa własnego binarnego API oraz nietypowych nagłówków HTTP. Wtyczka musi mieć możliwość wysłania zapytania HTTP POST w specyficznym formacie (który jest umyślnie niekompatybilny z POST z formularzy).

Dane wysyłane do serwera to pola zapisane w parach klucz-wartość. Klucze i wartości są oddzielane od siebie znakiem NUL (bajt 0) i kodowane w UTF-8. Treść POST wysyłana do serwera wygląda mniej więcej tak:

klucz1\0wartosc1\0klucz2\0wartosc2\0

Informacje o nadawcy

Wymagane pola
Nazwa polaOpis zawartości
uidniezmienny identyfikator serwera, który jest niemożliwy do zgadnięcia. To może być dowolny ciąg znaków.
uriścieżka, pod którą zostało wysłane zapytanie (np. „/cgi-bin/form.cgi”. W CGI to zmienna REQUEST_URI)
hostdomena serwera (np. „example.com”, w CGI to HTTP_HOST lub SERVER_NAME)
ipIP nadawcy postu (jako tekst w formacie „123.123.123.123”)
timedata/czas wysłania postu jako unix timestamp (np. „1187543533”)
cookies„1” jeśli nadawca postu przyjmuje cookies, „0” jeśli nie
session„1” jeśli nadawca pobrał niedawno pliki z serwera (rozpoczynając sesję), „0” jeśli od razu wysłał formularz
sblamcookiezawartość cookie o nazwie „sblam_”
salttrudny do zgadnięcia, najlepiej niepowtarzalny ciąg znaków
Opcjonalne pola
Nazwa polaOpis zawartości
field_0nazwa pola formularza, które zawiera wiadomość (np. „comment”)
field_1nazwa pola formularza, które zawiera podpis autora (np. „author”)
field_2nazwa pola formularza, które zawiera adres e-mail autora (np. „e-mail”)
field_3nazwa pola formularza, które zawiera adres WWW podany przez autora (np. „website”)

Pola field_X mają zawierać nazwy pól formularza, a nie treść. Zamiast nazwy mogą zawierać pusty ciąg, co oznacza, że dane pole nie występuje w formularzu.

Jeśli pola field_X nie zostaną wysłane do serwera, to serwer będzie zgadywał nazwy pól formularza.

W przyszłości serwer będzie przyjmował dodatkowe opcje filtrowania (ustawiane przez użytkownika wtyczki) przekazywane za pomocą pól nazwanych wg schematu field_nazwa, więc ten element implementacji warto mieć elastyczny.

Przekazywanie nadesłanych danych

Należy przekazać do serwera wszystkie pola z formularza przysłane przez użytkownika metodą POST (oczywiście pomijając pola zawierające hasła i inne poufne dane).

Do nazw pól formularza należy dodać przedrostek POST_. Jeśli pole występuje kilkakrotnie, należy wszystkie połączyć w jeden ciąg.

<textarea name="tresc">hello</textarea>
POST_tresc\0hello\0

Podobnie należy przekazać wszystkie nagłówki HTTP (oprócz Cookie i Authorization, które zawierają poufne dane). Ich nazwy powinny być znormalizowane tak samo, jak w skryptach CGI — z predrostkiem HTTP_, dużymi literami i z „-” zamienionym na „_”.

User-Agent: spambot
HTTP_USER_AGENT\0spambot\0

Wysyłanie do serwera

Zapytanie musi być wykonane metodą POST. Musi mieć nagłówek HTTP:

Content-Type:application/x-sblam;sig=XXXYYY

lub

Content-Type:application/x-sblam;sig=XXXYYY;compress=gzip

jeśli dane zostały skompresowane przez gzip.

Gdzie XXX to hash MD5 (jako hex, 32 znaki) ciągu: „^&$@$2\n” + klucz API + „@@”. \n to znak przejścia do nowej linii (LF).

md5("^&$@$2\ndefault@@"); // dla klucza „default”

YYY to hash MD5 ciągu: klucz API + dane (jeśli są skompresowane, to hash z danych po kompresji)

Odpowiedź od serwera

Jeśli serwer odpowie innym statusem, niż 200, to opis błędu będzie w linii statusu HTTP.

Jeśli serwer odpowie statusem 200, to w ciele odpowiedzi będą pola oddzielone dwukropkiem:

-1:2a6d8fa0d:bb9c177510ba9219c75e0e02876c9c96
  • wynik filtrowania (wyjaśniony w opisie wtyczki PHP)
  • identyfikator postu do raportowania pomyłki wtyczki (może być pusty lub „0”, co oznacza, że post nie został przyjęty przez serwer). Pomyłki wtyczki użytkownik może raportować pod adresem: https://sblam.com/report/identyfikator postu
  • hash MD5 ciągu: klucz API + wynik + pole „salt” z wysłanych do serwera danych. Sprawdzenie tego ciągu z twoimi danymi daje gwarancję, że nikt nie podszywa się pod serwer.

Skrypt JavaScript

Bardzo ważny jest też skrypt JavaScript, który potwierdza, że przeglądarka użytkownika obsługuje JavaScript oraz przy okazji mierzy czas pisania postu. Wersja dla PHP dołączona do wtyczki powinna być na tyle prosta, że nie wymaga dokumentacji (większość nieczytelnego kodu w niej to JavaScript, który musi pozostać niezmieniony).