Jesteśmy zobowiązani do ochrony praw naszych użytkowników i bycia transparentnym w kwestii naszych kodów źródłowych. Dzięki temu zainteresowane strony mogą niezależnie badać kody pod kątem bezpieczeństwa, integralności i poprawności.
Kod źródłowy
MEGA SDK
Witamy w MEGA SDK! Mamy nadzieję, że okaże się ono przydatne dla programistów, którzy są zainteresowani integracją obsługi MEGA w swoich aplikacjach.
MEGA SDK składa się z kodu i dokumentacji, które umożliwiają wykorzystanie funkcjonalności API firmy MEGA na komfortowo wysokim poziomie abstrakcji. Jego podstawowy komponent – moduł kodu zwany client access engine – utrzymuje w pamięci aktualną kopię konta użytkownika (która obejmuje wszystkie istotne pliki, foldery, kontakty i udziały), przyjmuje polecenia od aplikacji i powiadamia aplikację o wynikach poleceń i innych aktualizacjach poprzez wywołania zwrotne.
Silnik dostępu do klienta MEGA jest dostarczany jako zestaw klas i interfejsów C++. Jeśli używasz C++, możesz po prostu dodać je do swojego projektu. Następnie instancjonujesz klasę MegaClient (która przechowuje stan sesji) i przekazujesz jej instancję swojej implementacji interfejsu HttpIO (który obsługuje żądania sieciowe i blokowanie) oraz MegaApp (przez którą odbierasz wywołania zwrotne silnika).
Główny kod jest w miarę niezależny od platformy (jeśli napotkasz jakieś problemy z konkretnym środowiskiem kompilatora C++, daj nam znać). Aby zilustrować praktyczne zastosowanie, dołączona jest przykładowa aplikacja (podstawowy interaktywny klient konsoli w stylu ftp).
Wymóg integracji z projektami, które kompilują kod natywny, wyklucza wszystkie języki, które opierają się na specyficznych interpreterach lub środowiskach uruchomieniowych. C, będąc „lingua franca” prawie wszystkich nowoczesnych systemów, byłby oczywistym wyborem, ale zwartość kodu i korzyści z czytelności zapewnione przez cukier syntaktyczny C++ i bibliotekę szablonów są warte niewielkiego dodatkowego kosztu integracji. Będziemy współpracować z zainteresowanymi programistami, aby dodać obsługę MEGA do ich preferowanych środowisk za pomocą modułów/rozszerzeń kodu natywnego (a nie przez przeniesienie funkcjonalności do samego języka docelowego). Prosimy o kontakt z nami pod adresem developers@mega.nz, jeśli chcesz i możesz przyczynić się do konkretnego wysiłku integracyjnego.
Aplikacja przekazuje żądania do silnika dostępu do klienta poprzez nieblokujące wywołania metod obiektu MegaClient, a zdarzenia sygnalizuje aplikacji poprzez wywołanie metod obiektu jej implementacji interfejsu MegaApp.
Pliki i foldery są reprezentowane przez obiekty Node i przywoływane przez uchwyty węzłów. Węzły wskazują na węzły nadrzędne, tworząc drzewa. Drzewa mają dokładnie jeden węzeł główny (nie jest dozwolone powiązanie kołowe). Aktualizacje węzłów (spowodowane przez własne działania sesji, inne sesje tego samego konta lub inne konta, np. przez aktywność w folderze współdzielonym) są zgłaszane w czasie rzeczywistym poprzez wywołanie zwrotne określające węzły, których dotyczą. Węzły usunięte są najpierw powiadamiane z ustawioną flagą usuniętą przed oczyszczeniem, aby dać aplikacji możliwość usunięcia ich z widoku UI.
Na każdym koncie znajdują się co najmniej trzy drzewa węzłowe: Root, przychodzące i śmieci. Dodatkowe drzewa mogą pochodzić od innych użytkowników jako foldery współdzielone.
Użytkownicy są przywoływani przez swój link użytkownika i/lub podstawowy adres e-mail. Silnik utrzymuje obiekt User dla każdego konta użytkownika, które pojawiło się w kontekście bieżącej sesji: Jako kontakt lub jedynie jako właściciel węzła systemu plików. Flaga widoczności zmienia użytkownika w kontakt, jeśli jest ustawiona.
Atrybuty użytkownika mogą być używane do przechowywania danych uwierzytelniających, takich jak zdjęcia awatarów, adres, data urodzenia itp. Zalecane jest przechowywanie prywatnych danych uwierzytelniających użytkownika w postaci zaszyfrowanej AES-CBC.
Wszystkie metody silnika są nieblokujące – oczekiwanie na zakończenie komunikacji sieciowej nie jest opcją. Zamiast tego, inicjują one jedynie pożądaną akcję, której wynik jest ostatecznie sygnalizowany poprzez wywołanie zwrotne. Aplikacja powinna być odporna na takie callbacki przychodzące po długim czasie (tj. wielu sekundach). Nieudane żądania (np. z powodu problemów z siecią) są ponownie próbowane automatycznie z wykładniczym backoffem. Aplikacja otrzymuje powiadomienie o tym poprzez callback i powinna poinformować o tym użytkownika, wraz z elementem UI do ręcznego zainicjowania retry.
Trzy rodzaje operacji podlegają przyspieszeniu przez mechanizm zwany „spekulatywnym natychmiastowym uzupełnieniem”: Aktualizacje atrybutów węzłów, przeniesienia i usunięcia. Ponieważ te jedynie otrzymują wysoce przewidywalną odpowiedź „OK” lub „niepowodzenie” z API, istnieje pewna korzyść z natychmiastowego aktualizowania lokalnych węzłów i przeładowywania stanu sesji w rzadkim przypadku niespójności. Silnik luźno chroni je za pomocą kontroli dostępu, która jest zgodna z tą samą semantyką, co kontrola autorytatywna po stronie serwera API.
Współdzielony dostęp do zasobu (zapisywalne węzły dostępne dla konta użytkownika) oparty na potencjalnie nieaktualnym (z powodu opóźnień sieciowych) widoku jest naturalnie podatny na warunki wyścigu, co prowadzi do niespójności, gdy dwie strony dokonują sprzecznych aktualizacji w ramach okna opóźnień. Silnik zawiera heurystykę do wykrywania tych konfliktów i poprosi aplikację o odrzucenie i ponowne załadowanie jej widoku, jeśli to konieczne (użytkownik powinien zostać o tym poinformowany).
Ze względu na swoją nieblokującą naturę, silnik dostępu klienta MEGA integruje się wyjątkowo dobrze z aplikacjami jednowątkowymi (chociaż na platformach bez nieblokującej funkcji DNS lookup, możesz nie obejść się bez użycia wątku roboczego do rozwiązywania nazw). Jeśli jednak wolisz używać wielu wątków, możesz to zrobić – pod warunkiem, że zapewnisz, że żadne dwa wątki nie wejdą do silnika lub nie uzyskają dostępu do jego struktur danych w tym samym czasie.
Istnieją trzy podejścia do integracji silnika z aplikacją. Celem jest, aby silnik dostał procesor (poprzez metodę exec() MegaClienta) szybko, gdy tylko jeden z jego wyzwalaczy wakeup wystrzeli:
Aplikacje muszą być przygotowane do radzenia sobie z kolizjami nazw plików i folderów. W wielu scenariuszach jest to banalne – użytkownik widzi wszystkie kopie i podejmuje decyzję, który plik go interesuje, najczęściej na podstawie jego znacznika czasu. Niektóre aplikacje mapują jednak drzewo węzłowe MEGA do zasobu, który używa ścieżek plików jako unikalnych kluczy, np. systemy plików. W takim przypadku zalecamy, aby używać tylko najnowszego węzła.
Znaki nazw plików, które nie są dozwolone na hoście, muszą być urlencodowane przy użyciu %xx. Podczas zapisywania plików z powrotem na serwer, prawidłowe sekwencje urlencoded muszą być zastąpione zakodowanym znakiem. Ma to potencjalnie niepożądany efekt uboczny w postaci zniekształcenia nazw plików, które pierwotnie zawierały prawidłowe sekwencje %xx, ale powinno to być rzadkie i zostaną one zniekształcone podczas odczytu z powrotem na lokalną maszynę.
Uprzejmie prosimy wszystkich twórców aplikacji, którzy chcą wprowadzić nowe atrybuty węzłów, plików lub użytkowników, aby skoordynowali z nami konwencje numerowania/nazywania i formatowania w celu zmaksymalizowania interoperacyjności między aplikacjami. Jeśli nie chcesz tego zrobić, prosimy o unikanie zagracania przestrzeni nazw i poprzedzanie nazw nowych atrybutów skróconą nazwą firmy lub aplikacji.
Następujące interfejsy muszą być zaimplementowane przez aplikację:
FileAccess
– Otwieranie/zamykanie/odczytywanie/zapisywanie plikówHttpIO
– Żądania HTTP z obsługą SSLPrnGen
– Silny kryptograficznie generator liczb pseudolosowychSymmCipher
– Kryptografia AESAsymmCipher
– Kryptografia RSAMegaApp
– wywołania zwrotne do aplikacjiSDK dostarcza referencyjne implementacje FileAccess
(używające wywołań POSIX), HttpIO
(używające cURL) oraz PrnGen SymmCipher
i AsymmCipher
(używające Crypto++). Jeśli zdecydujesz się na użycie cURL w swojej aplikacji, upewnij się, że została ona zbudowana z obsługą c-ares dla asynchronicznych żądań DNS. Niektóre platformy (np. MacOS i Fedora) dołączają binaria cURL, które zostały skompilowane ze wsparciem dla threaded-resolver – te nie będą działać.
Aby uzyskać dostęp do MEGA, aplikacja musi zainicjować trzy klasy:
MegaApp
HttpIO
MegaClient
Następnie aplikacja musi wywołać MegaClient
wait()
bezpośrednio przed lub zamiast blokowania dla zdarzeń samemu. Jeśli wait()
chce blokować, to wywołuje HttpIO
's waitio()
, podając timeout. Aplikacja może albo wykorzystać swoje własne kryteria budzenia na zdarzeniach gniazda/czasie w waitio()
, albo nagrać kryteria waitio()
i włączyć je do swojej własnej logiki blokowania. Dostarczony przykład SDK (megaapp.cpp) używa tego pierwszego podejścia, dodając fileno(stdin)
do zestawu select()
fd, aby przetwarzać dane wejściowe użytkownika w czasie rzeczywistym.
Aplikacja musi wywołać exec()
MegaClienta przynajmniej raz po każdym obudzeniu przez kryteria waitio()
(nie zaszkodzi wywołać go zbyt często).
Na sesję MEGA składają się:
MegaClient::nodes
)MegaClient::users
)MegaClient::ft
)MegaClient::rootnodes
)MegaClient::me , MegaClient::myemail
)Węzeł ma następujące wartości:
Szczegółowe informacje można znaleźć w dostarczonym kodzie źródłowym.
Użytkownik zewnętrzny jest częścią sesji albo dlatego, że jest w relacji kontaktowej z użytkownikiem sesji, albo dlatego, że jest właścicielem co najmniej jednego węzła sesji. Rekord użytkownika jest również tworzony, gdy udział jest dodawany do wcześniej niezarejestrowanego adresu e-mail. Do użytkowników można odwoływać się przez ich uchwyt lub adres e-mail.
Struktura użytkownika:
Obsługiwane jest równoległe przesyłanie wielu plików. Zaleca się, aby nie uruchamiać więcej niż jeden duży upload i jeden duży download równolegle, aby uniknąć przeciążenia sieci (korzyści z prędkości będą niewielkie, jeśli w ogóle). Transfer plików może łączyć wiele kanałów TCP (zalecany punkt startowy: 4) dla większej przepustowości. Transfer plików może być przerwany w dowolnym momencie przez wywołanie MegaClient::tclose()
. Znaczne przeciążenie sieci lokalnej podczas wysyłania jest powszechne w przypadku uplointów ADSL i można temu zapobiec poprzez włączenie automatycznego lub stałego limitu prędkości.
Aplikacje, które przesyłają partie plików powinny korzystać z funkcji kolejkowania transferu silnika. Używa ona pipeliningu (nowe transfery są wysyłane około trzy sekundy przed końcem bieżącego transferu), aby zredukować lub wyeliminować martwy czas pomiędzy plikami. Nieudane transfery są próbowane ponownie z wykładniczym backoffem.
Pliki mogą mieć atrybut. Tylko oryginalny twórca pliku może aktualizować jego atrybuty. Wszystkie węzły odwołujące się do tego samego pliku zaszyfrowanego widzą te same atrybuty. Atrybuty niosą 16-bitowe pole typu. Silnik dostępu klienta obsługuje dołączanie atrybutów plików w trakcie lub po przesłaniu oraz ich masowe pobieranie.
Wszystkie aplikacje zdolne do wysyłania plików graficznych powinny dodawać miniatury w procesie (pamiętaj, że nie ma możliwości zrobienia tego po stronie serwera). Miniatury są przechowywane jako atrybuty plików typu 0 i powinny być plikami JPEG o wymiarach 120p*120p skompresowanymi do około 3-4 KB. Przykładowa aplikacja dostarczona z SDK demonstruje jak to zrobić przy użyciu biblioteki FreeImage. Ponieważ wyodrębnienie miniatury z dużego obrazu może zająć sporo czasu, sugeruje się również wykonanie tego w oddzielnych wątkach roboczych, aby uniknąć przeciągnięcia aplikacji.
Istnieją dwa rodzaje ograniczeń kwotowych, które aplikacja może napotkać podczas swojego działania: Przechowywanie i przepustowość. MEGA, zgodnie z polityką, jest dość hojna w obu tych kwestiach, co oznacza, że tylko niewielki ułamek Twojej bazy użytkowników kiedykolwiek wyczerpie limit, ale ważne jest, aby w przypadku, gdy to się stanie, sytuacja była obsługiwana prawidłowo – użytkownik musi być poinformowany o przyczynie niepowodzenia jego wysyłania lub pobierania, a nie pozostawiony w ciemności z tym, co wygląda na awarię.
Przesyłanie zostanie odrzucone z błędem EOVERQUOTA
, jeśli nie ma wystarczającej ilości miejsca na dysku, aby je ukończyć. Po rozpoczęciu wysyłania, zostanie ono zakończone, nawet jeśli w międzyczasie zabraknie miejsca na dysku w inny sposób (np. przez wygaśnięcie statusu Pro). Ten błąd pojawi się również, jeśli Twoja aplikacja spróbuje wysłać pliki na konto strony trzeciej bez wystarczającej kwoty.
Próba pobrania zostanie odrzucona z błędem EOVERQUOTA
, jeśli zużycie pasma w ciągu ostatnich pięciu do sześciu godzin plus pozostały rozmiar wszystkich trwających pobrań plus rozmiar pliku do pobrania przekroczyłby aktualny limit pasma per-IP (jeśli istnieje).
W przeciwieństwie do wysyłania, pobieranie może być w pewnych okolicznościach przerwane z błędem przekroczenia kwoty, co spowoduje wywołanie zwrotne quota_exceeded()
, a pobieranie będzie automatycznie ponawiane do momentu, aż kwota przepustowości stanie się dostępna.
Możesz znaleźć nasze inne biblioteki na naszej ogólnej stronie GitHub. Jeśli chciałbyś wykorzystać nasz kod komercyjnie w sposób, który jest poza zakresem tych licencji, prosimy o kontakt z nami w celu omówienia.
Wydanie C++ SDK jest tylko punktem wyjścia i będzie ewoluować w czasie. Chcielibyśmy usłyszeć od programistów, którzy rzeczywiście używają go w swoich aplikacjach – jeśli znajdziesz błędy, wady projektowe lub inne niedociągnięcia, skontaktuj się z nami pod adresem developers@mega.nz. MEGA zatrudnia, więc bądź przygotowany na otrzymanie oferty, jeśli Twoje opinie wskazują, że jesteś bystrym umysłem.
Wkrótce udostępnione zostanie forum dla deweloperów oraz repozytorium kodu źródłowego.
Ładowanie dużych kont MEGA może zająć znaczną ilość czasu. Wynika to z samego rozmiaru informacji o stanie, które muszą być odczytane z klastra API. Są dwa sposoby na obejście tego problemu:
Obecnie pliki nie mogą być modyfikowane po utworzeniu. Ograniczenie to zostanie zniwelowane dzięki zastosowaniu zaszyfrowanych plików delta.
Obecnie integralność pliku jest weryfikowana dopiero po pobraniu go w całości. Weryfikacja Chunk MAC umożliwi aplikacjom zapewnienie integralności częściowych odczytów.
megaclient
Aby pomyślnie zbudować megaclient
, potrzebujesz następujących elementów:
W tym momencie SDK nie jest dostarczany ze skryptem autoconf, więc może być konieczne ręczne dostosowanie pliku Makefile do swojego systemu.
megaclient
Podobnie jak UNIX-owe polecenie ftp
, megaclient
wyświetla znak zachęty i akceptuje polecenia logowania do konta MEGA lub wyeksportowanego łącza folderu, listowania zawartości folderów, tworzenia folderów, kopiowania, przenoszenia i usuwania plików i folderów, przeglądania przychodzących i wychodzących udziałów folderu, ustanawiania, modyfikowania i usuwania wychodzących udziałów folderu, wysyłania i pobierania plików, eksportowania łączy do folderów i plików, importowania łączy plików, przeglądania stanu konta i zmiany hasła.
login
– zalogować się na konto lub link do folderuAby zalogować się na konto, należy podać adres e-mail konta oraz opcjonalnie hasło (o które zostaniesz poproszony w innym przypadku).
Aby zalogować się do wyeksportowanego łącza folderu, należy podać pełne łącze, w tym klucz (monit o klucz nie został jeszcze zaimplementowany).
Należy pamiętać, że do wyeksportowanych folderów nie można pisać.
mount
– wyświetlanie dostępnych drzew systemu plikówTo polecenie nie przyjmuje żadnych parametrów i wyświetla ścieżki dostępnych drzew systemu plików (typowo / dla głównego drzewa, //in
dla skrzynki odbiorczej, //bin
dla kosza na śmieci i email:sharename
dla akcji przychodzących od użytkownika email
.
ls
– lista plików i folderówls
wymienia zawartość bieżącego folderu (jeśli podano z kwalifikatorem -R , robi to rekurencyjnie) lub podanej ścieżki.
Ścieżki mogą być względne lub bezwzględne. Prawidłowe ścieżki bezwzględne zaczynają się od jednego z prefiksów wyświetlanych przez polecenie mount.
Właściwości plików i folderów są wyświetlane wraz z ich nazwami: Rozmiar pliku i dostępne atrybuty pliku lub Eksportowane łącza folderów i wychodzące udziały folderów.
cd
– zmień bieżący katalog roboczycd
zmienia bieżący katalog roboczy na podaną ścieżkę do folderu. Jeśli nie podano ścieżki, zmienia się na / .
pwd
– wyświetlanie bieżącego folderupwd
wyświetla bieżący folder jako ścieżkę bezwzględną.
lcd
– zmiana bieżącego lokalnego katalogu roboczegolcd
zmienia bieżący lokalny katalog roboczy na podaną ścieżkę.
get
– dodać plik(i) do kolejki pobieraniaget
ustawia w kolejce do pobrania określony plik. Jeśli określisz folder, wszystkie pliki zawarte w tym folderze zostaną ustawione w kolejce do pobrania (ale nie zawartość jego podfolderów).
put
– dodać plik(i) do kolejki wysyłaniaput
ustawia w kolejce do wysłania określony plik. Obsługiwane są wzorce – put *.jpg
prześle wszystkie pliki .jpg znajdujące się w bieżącym katalogu lokalnym.
getq
i putq
– lista/usunięcie/przerwa w kolejce transferówTransfery w kolejce są wymienione z indeksem, ścieżką docelową (tylko wgrywanie) i statusem aktywności. Aby anulować transfer, należy podać jego indeks.
mkdir
– tworzenie katalogówmkdir
tworzy pusty podkatalog w określonym (lub bieżącym) katalogu. Chociaż MEGA dopuszcza identyczne nazwy katalogów, to mkdir
kończy się niepowodzeniem, jeśli katalog już istnieje.
cp
, mv
– kopiowanie lub przenoszenie, zmiana nazwy plików i folderówOkreślona ścieżka źródłowa lub folder są kopiowane lub przenoszone do folderu docelowego. Jeśli miejsce docelowe wskazuje nową nazwę w istniejącym folderze, po drodze następuje zmiana nazwy.
rm
– usuwanie pliku lub folderurm
usuwa podany plik lub katalog. Jeśli katalog zawiera pliki lub podkatalogi, są one również usuwane rekursywnie. Wszystkie dotknięte akcje wychodzące i wyeksportowane łącza katalogow są anulowane w tym procesie.
Usunięcie jest ostateczne. Aby skorzystać z funkcjonalności kosza na śmieci, użyj zamiast tego mv path //bin
.
share
– zarządzać udostępnieniami w katalogach wychodzącychshare
listuje, tworzy, aktualizuje lub usuwa udostępnienia wychodzące w określonym katalogu. Katalog nie może znajdować się w udostępnieniu przychodzącym.
Aby wyświetlić listę istniejących udziałów w folderze, użyj share path
Aby odwołać udział w folderze do użytkownika, użyj share path email
.
Aby utworzyć lub zmodyfikować udział w folderze, użyj share path email access
.
Obsługiwane poziomy dostępu to: Read-only ( r
), read/write ( rw
) i full ( full
).
export
– tworzenie lub anulowanie linku do pliku lub folderuexport
tworzy łącze do pliku lub katalogu tylko do odczytu, które zawiera powiązany klucz szyfrowania. Aby anulować istniejące łącze, dodaj słowo kluczowe del
.
import
– importowanie wyeksportowanego plikuimport
dodaje plik opisany przez podany link (importowanie linków do katalogów jest obecnie nieobsługiwane) do bieżącego katalogu.
putbps
– ustawienie limitu prędkości wysyłaniaPrzesyłanie przez linię DSL może spowodować znaczne straty pakietów wychodzących. Możesz ograniczyć szybkość wysyłania, określając absolutne maksimum w bajtach na sekundę, auto
, aby serwer obliczył prędkość linii i pozostawił około 10% jej bezczynności, lub none
, aby przesyłać z pełną prędkością.
Obecnie nie ma możliwości zmiany szybkości wysyłania aktywnego uploadu. Ustawienie będzie miało wpływ tylko na kolejne wysyłki.
whoami
– wyświetlanie szczegółów kontawhoami
wyświetla różne limity kont, transferow i historię sesji.
passwd
– zmiana hasła do kontapasswd
wyświetla prośbę o podanie bieżącego hasła, a następnie prosi o podanie nowego hasła i jego potwierdzenie. Nie jest przeprowadzane sprawdzanie jakości hasła.
retry
– natychmiast ponawia próby wszystkich oczekujących operacjiretry
resetuje wszystkie liczniki.
recon
– ponawia połączenierecon
rozbija wszystkie istniejące połączenia z serwerem. Nie ma to żadnego wpływu na bieżące operacje, poza tym, że transfery trwają dłużej z powodu częściowo przeniesionych kawałków, które są odrzucane i muszą być ponownie wysłane.
reload
– wyczyść i przeładuj stan kontareload
usuwa stan lokalny i wymusza pełne przeładowanie z serwera. Jest to przydatne w odpowiedzi na wykrycie niespójności związanej z warunkiem wyścigu między widokiem klienta a stanem serwera.
logout
– zakończa bieżącą sesjęlogout
usuwa cały stan sesji lokalnej.
debug
– przełączanie trybu debugowaniaTryb debugowania wyświetla aktywność połączenia HTTP oraz surowe żądania i odpowiedzi API JSON.
Szyfrowane hasło zakodowane w UTF-8 i zapisuje wynik w dostarczonym buforze.
Metoda: error hashpw_key(const char* password, char* hash)
Zwraca kody: API_EARGS
w przypadku nieprawidłowego kodowania UTF-8
Inicjuje logowanie sesji na podstawie adresu e-mail użytkownika (wielkość liter nie ma znaczenia) i odpowiedniego hasła.
Metoda: void login(const char* email, const char* hash)
Callback: login_result(error e)
Kody błędów: API_ENOENT
: Nieprawidłowy adres e-mail lub hasło, API_EKEY
: Klucz prywatny nie może być odszyfrowany
Metoda: void folderaccess(const char* node, const char* key)
Callback: brak (nie współdziała z serwerem, przejdź do wywołania fetchnodes() )
Metoda: void fetchnodes()
Callback: fetchnodes_result(client, error e)
Po pomyślnym zakończeniu, wywołuje również nodes_updated().
Metoda: void getaccountdetails(AccountDetails* result, int storage, int transfer, int pro, int transactions, int purchases, int sessions)
Aktualizuje dostarczoną strukturę AccountDetails z informacjami o bieżącym wykorzystaniu pamięci i transferu oraz kwoty, statusie Pro oraz historii transakcji i sesji. Możesz określić, które typy informacji Cię interesują, ustawiając powiązaną flagę na niezerową wartość.
Metoda: error changepw(const char* currentpwhash, const char* newpwhash)
Callback: changepw_result(error e)
Kod powrotu: API_EACCESS
jeśli nie istnieje sesja użytkownika.
Metoda: error setattr(Node* node, const char** newattr)
Zwraca wartość: API_EACCESS
jeśli węzeł nie jest zapisywalny.
Callback: setattr_result(handle nodehandle, error e)
Aktualne atrybuty węzła są przesyłane do serwera. Opcjonalny parametr newattr
określa delty atrybutów jako zakończone znakiem NULL ciągi par wskaźników atrybutów nazwa_atrybutu C-string. W setattr_result()
, nodehandle
jest uchwytem węzła.
Metoda: error rename(Node* node, Node* newparent)
Wartość zwracana: API_EACCESS
jeśli rodzic węzła lub nowy rodzic nie są zapisywalne (odpowiednio z pełnym lub odczytanym/zapisanym dostępem) lub przeniesienie nastąpiłoby pomiędzy różnymi kontami użytkowników, API_ECIRCULAR
jeśli nastąpiłoby kołowe powiązanie.
Callback: rename_result(handle nodehandle, error e)
Węzeł (wraz ze wszystkimi jego dziećmi) jest przenoszony do nowego węzła nadrzędnego, który musi być częścią tego samego konta użytkownika co węzeł. Nie można przenieść węzła do jego własnego poddrzewa.
Metoda: error unlink(Node* node)
Wartość zwracana: API_EACCESS
jeśli rodzic węzła nie jest zapisywalny (z pełnym dostępem).
Callback: unlink_result(handle nodehandle, error e)
Węzeł i wszystkie jego węzły podrzędne są usuwane. Rodzic węzła musi być zapisywalny (z pełnym dostępem). Dotknięte akcje wychodzące są anulowane.
Wysyłanie i pobieranie rozpoczyna się od topen()
, który zwraca deskryptor transferu identyfikujący transfer. Wiele transferów może działać równolegle, a każdy transfer może używać wielu połączeń TCP równolegle. Dostępna jest wydajna kolejka transferów z pipeliningiem. Przesyłanie może być ograniczone prędkością przy użyciu absolutnego lub dynamicznego limitu.
Informacje o postępie przekazywane są za pomocą wywołania zwrotnego transfer_update(int td, m_off_t bytes, m_off_t size, dstime starttime)
, przy czym td identyfikuje transfer, bytes oznacza liczbę przekazanych do tej pory bajtów, size oznacza całkowity rozmiar transferu, a starttime to czas rozpoczęcia transferu.
Działający transfer może być przerwany w dowolnym momencie przez wywołanie tclose(int td)
. Callbacki wskazujące na niepowodzenie wykonują niejawnie tclose()
. Callback wskazujący przejściowy błąd HTTP, transfer_error(int td, int httpcode, int count)
wywoła tclose()
jeśli aplikacja zwróci niezerową wartość.
Metoda: int topen(const char* localfilename, int speedlimit, int connections)
speedlimit
– maksymalna prędkość wysyłania w bajtach/sekundę lub -1 dla ok. 90% prędkości łącza
connections
– liczba równoległych połączeń do wykorzystania (domyślnie: 3)
Wartość zwracana: deskryptor transferu lub API_ETOOMANY
jeśli wszystkie kanały transferu są zajęte, API_ENOENT
jeśli nie udało się otworzyć pliku.
Wywołanie zwrotne po pomyślnym zakończeniu: transfer_complete(int td, handle uploadhandle, const byte* uploadtoken, const byte* filekey, SymmCipher* filekey)
Callback upon failure: transfer_failed(int td, error e)
Metoda: int topen(handle nodehandle, const byte* key, m_off_t start, m_off_t len, int c)
nodehandle
jest uchwytem węzła do pobrania (jeśli ustawiony jest klucz, częścią uchwytu jest link do eksportowanego pliku)
key
jest odkodowaną w base64 częścią kluczową eksportowanego linku do pliku, jeśli jest ustawiony
start
i len mogą być ustawione, aby pobrać tylko wycinek pliku (domyślnie: 0, -1 dla pełnego pliku)
c
oznacza liczbę równoległych połączeń TCP, które powinny zostać użyte podczas pobierania.
Wartość zwrotna: deskryptor transferu lub API_ETOOMANY
jeśli wszystkie kanały transferu są zajęte, API_ENOENT
jeśli lokalny plik nie jest obecny, API_EACCESS
jeśli próba pobrania nie-pliku
Callback po pomyślnym otwarciu pliku do pobrania: topen_result(int td, string* filename, const char* fa, int pfa)
td
identyfikuje transfer
filename
jest nazwą pliku określoną przez atrybut węzła „n”.
fa
są atrybutami pliku dostępnymi dla tego pliku
pfa
jest flagą wskazującą, czy żądający użytkownik ma prawo pisać atrybuty pliku (tj. jest właścicielem pliku)
Wywołanie zwrotne po pomyślnym zakończeniu: transfer_complete(int td, chunkmac_map* macs, const char* fn)
td
identyfikuje transfer
macs
zawiera MAC hash dla każdego kawałka pliku
fn
est nazwą pliku (UTF-8)
Callback po niepowodzeniu: transfer_failed(int td, string& filename, error e)
Callback po osiągnięciu limitu transferu: transfer_limit(int td)
Silnik utrzymuje oddzielne kolejki wysyłania i pobierania, putq
i getq
. Transfery są uruchamiane poprzez wepchnięcie obiektów transferu (klasy FilePut
i FileGet
na te kolejki). Nie musisz już samodzielnie wywoływać topen()
/ tclose()
, ale nadal musisz przetwarzać wywołania zwrotne transferu. Transfer jest uważany za nieudany, jeśli żadne bajty nie zostały przesłane przez co najmniej XFERTIMEOUT decybeli, w którym to przypadku zostanie przerwany i powtarzany w nieskończoność z wykładniczym backoffem.
Główną korzyścią z używania dostarczanej przez silnik kolejki transferu nie jest zmniejszenie złożoności aplikacji, ale wbudowane nakładanie się transferów, które zmniejsza wpływ przejść między plikami na ogólną przepustowość.
Węzły można dodać do putnodes_result(error e, targettype t, NewNode* nn)
Metoda: void putnodes(handle parenthandle, NewNode* newnodes, int numnodes)
parenthandle
jest uchwytem węzła macierzystego nowego węzła.
newnodes
jest tablicą wypełnionych struktur NewNode. W pewnych okolicznościach, tablica ta będzie dostępna po tym, jak wywołanie putnodes()
już powróciło. Dlatego też, always alokuje tę tablicę ze sterty i zwalnia ją w putnodes_result()
.
numnodes
jest liczbą obecnych rekordów NewNode.
Callback: putnodes_result(client,error) if the operation
Metoda: setshare(node,targetuser,accesslevel)
Callback: share_result(client,error)
Callback: share_result(client,int,error)
Metoda: loggedin()
Zwraca: 1 jeśli zalogowany, 0 w przeciwnym wypadku
Metoda: checkaccess(node,level)
Zwraca: 1 jeśli dostęp dozwolony, 0 w przeciwnym wypadku
Metoda: checkmove(node,targetnode)
Zwraca: kod błędu (API_OK, API_EACCESS lub API_ECIRCULAR)
Metoda: makeattr(cipher,targetstring,jsonstring,length)
Callback: newfile()
Zwraca: Specyficzny dla aplikacji obiekt FileAccess
Callback: users_updated(client,users,count) – dodano lub zaktualizowano użytkowników (użytkownicy nigdy nie są usuwani)
Callback: node_updated(client,nodes,count) – węzły zostały dodane, zaktualizowane lub usunięte
Callback: notify_retry(client,time) – określa czas w decybelach do następnego retry
Callback: reload(client,reason) – możliwa niespójność, przeładuj stan konta
Znajomość poniższych niskopoziomowych szczegółów nie jest wymagana do pomyślnego rozwoju aplikacji klienckich MEGA. Jest ona podana jako odniesienie dla tych, którzy są zainteresowani pełnym zrozumieniem działania API firmy MEGA.
MEGA API jest oparte na prostym schemacie żądanie-odpowiedź HTTP/JSON. Żądania są przekazywane jako tablice obiektów poleceń i mogą być inicjowane zarówno przez klienta, jak i serwer, co efektywnie skutkuje dwukierunkową zdolnością RPC. Aby zobaczyć surowy przepływ żądań w przykładowej aplikacji megaclient SDK, należy użyć polecenia debug.
Wszystkie symetryczne operacje kryptograficzne oparte są na AES-128. Działa on w trybie łańcuchowania bloków szyfrów dla bloków atrybutów plików i folderów oraz w trybie licznika dla rzeczywistych danych plików. Każdy plik i każdy węzeł folderu używa własnego, losowo wygenerowanego 128-bitowego klucza. Węzły plików używają tego samego klucza dla bloku atrybutów i danych pliku, plus 64-bitowa losowa wartość początkowa licznika i 64-bitowy meta MAC do weryfikacji integralności pliku.
Każde konto użytkownika używa symetrycznego klucza głównego do szyfrowania EBC wszystkich kluczy węzłów, które utrzymuje w swoich drzewach. Ten klucz główny jest przechowywany na serwerach firmy MEGA, zaszyfrowany hashem pochodzącym z hasła logowania użytkownika.
Integralność pliku jest weryfikowana za pomocą CBC-MAC z kawałkami. Rozmiary kawałków zaczynają się od 128 KB i rosną do 1 MB, co jest rozsądną równowagą pomiędzy przestrzenią wymaganą do przechowywania MAC kawałków i średnim narzutem dla sprawdzania integralności częściowych odczytów.
Oprócz klucza symetrycznego, każde konto użytkownika posiada 2048 bitową parę kluczy RSA do bezpiecznego otrzymywania danych, takich jak klucze udostępniania lub klucze plików/folderów. Jego prywatny komponent jest przechowywany zaszyfrowany symetrycznym kluczem głównym użytkownika.
Właściciel folderu jest wyłącznie odpowiedzialny za zarządzanie dostępem; udziały są nieprzechodnie (udziały nie mogą być tworzone na folderach w przychodzących udziałach). Wszyscy uczestnicy folderu współdzielonego uzyskują dostęp kryptograficzny poprzez wspólny klucz specyficzny dla folderu, który jest przekazywany od właściciela (teoretycznie od każdego uczestnika folderu współdzielonego, ale stworzyłoby to znaczne ryzyko bezpieczeństwa w przypadku kompromitacji infrastruktury rdzeniowej) do nowych uczestników poprzez RSA. Wszystkie klucze węzłów w folderze współdzielonym, w tym jego węzeł główny, są szyfrowane do tego klucza współdzielonego. Strona dodająca nowy węzeł do folderu współdzielonego jest odpowiedzialna za dostarczenie odpowiedniego klucza węzła/udziału. Brakujące klucze węzłów/udziałów mogą być dostarczone tylko przez właściciela udziału.
MEGA wspiera bezpieczne, nieuwierzytelnione dostarczanie danych. Każdy w pełni zarejestrowany użytkownik może otrzymywać pliki lub foldery w swojej skrzynce odbiorczej poprzez swój klucz publiczny RSA.
Każde logowanie rozpoczyna nową sesję. W przypadku zwykłych kont polega to na tym, że serwer generuje losowy token sesji i szyfruje go do klucza prywatnego użytkownika. Hasło użytkownika jest uważane za zweryfikowane, jeśli pomyślnie odszyfruje klucz prywatny, który następnie odszyfruje token sesji.
Aby zapobiec zdalnym atakom słownikowym offline na hasło użytkownika, zaszyfrowany klucz prywatny jest dostarczany klientowi tylko wtedy, gdy hash uzyskany z hasła zostanie przedstawiony serwerowi.
Żądania API przepływają w dwóch kierunkach: klient → serwer oraz serwer → klient
Żądania klient-serwer są wydawane jako HTTP POST z surowym ładunkiem JSON. Żądanie składa się z jednego lub wielu poleceń i jest wykonywane jako pojedyncza atomowa, izolowana i spójna transakcja – w przypadku odpowiedzi na błąd na poziomie żądania, żadne dane nie zostały zmienione. Żądania są idempotentne – wielokrotne wysłanie tego samego żądania jest równoważne z wysłaniem go raz, co sprawia, że ponowne ich wysłanie jest bezpieczne, np. w przypadku przerywanych problemów sieciowych. Każde żądanie musi być zatem oznaczone unikalnym dla danej sesji identyfikatorem (np. numerem sekwencyjnym), aby zapobiec przypadkowym trafieniom do pamięci podręcznej spowodowanym przez poprzedzające je identyczne żądania.
Podczas wykonywania żądania wszyscy użytkownicy, których może ono dotyczyć, są zablokowani. Obejmuje to użytkownika żądającego i wszystkich użytkowników, którzy są w relacji folderu współdzielonego i/lub na liście kontaktów. Żądanie może zwrócić kod błędu EAGAIN w przypadku nieudanej próby zablokowania lub tymczasowej awarii po stronie serwera. Żądanie prawdopodobnie zostanie ukończone po ponownym spróbowaniu. Aplikacje klienckie muszą implementować wykładniczy backkoff (z natychmiastowym ponawianiem próby przez użytkownika) i powinny informować użytkownika o możliwym problemie z serwerem lub siecią, jeśli stan EAGAIN utrzymuje się lub nie ma odpowiedzi przez więcej niż kilka sekund.
Poprawnie wykonane żądanie zwraca tablicę obiektów wyników, przy czym każdy wynik pojawia się w tej samej lokalizacji indeksu tablicy, co odpowiadające mu polecenie.
Docelowy URL: https://g.api.mega.co.nz/cs?id=sequence_number&ak=appkey&[&sid=sessionid|&n=node]
Obiekt JSON jest wysyłany jako ładunek surowego żądania POST. Nie odbywa się żadne dodatkowe kadrowanie. Nagłówek HTTP Content-Type nie jest przetwarzany, ale powinien być ustawiony na application/json.
Jego struktura to tablica poleceń: [cmd1,cmd2,…]
z cmd = { a : typ polecenia, [argument : wartość]* }.
Odpowiedzią na żądanie jest obiekt JSON o typie zawartości application/json.
Jest on skonstruowany jako pojedyncza liczba (np. -3 dla EAGAIN) w przypadku błędu na poziomie żądania lub jako tablica obiektów zwracanych przez poszczególne polecenia: [res1,res2,…]
Aby zapobiec przeciążeniu infrastruktury, stosowane jest dynamiczne ograniczanie szybkości. Zanim żądanie zostanie wykonane, całkowita „waga” poleceń, które zawiera jest obliczana i sprawdzana w stosunku do aktualnego salda żądającego adresu IP. Jeśli suma przekracza zdefiniowany próg, żądanie jest odrzucane jako całość i musi być powtórzone z wykładniczym backoffem.
Ponieważ serwer nie może w sposób niezawodny nawiązać połączenia z klientem, żądania serwera-klienta muszą być zgłaszane przez tego ostatniego poprzez blokującą pętlę odczytu.
URL: https://g.api.mega.co.nz/sc?id=sequence_reference[&sid=sessionid|&n=node][ssl=1]
Błąd poziomu żądania jest odbierany jako pojedyncza liczba (np. -3 dla EAGAIN) lub surowy obiekt JSON z content-type application/json. Jego struktura jest następująca:
{ a : [req1,req2,…], [ sn : sequence_reference | w : wait_url ] }
Ponieważ JSON nie jest czysty binarnie, wszystkie dane inne niż ASCII muszą być zakodowane. Dla danych binarnych, MEGA API używa odmiany base64 z -_ zamiast +/ i usuniętym znacznikiem = (tam gdzie to konieczne, rzeczywista długość ładunku jest heurystycznie wnioskowana po dekodowaniu, np. przez usunięcie końcowych NUL). Tekst UNICODE musi być zakodowany jako UTF-8.
MEGA API wykorzystuje następujące główne typy danych:
Uchwyty węzłów mają długość ośmiu znaków alfanumerycznych i rozróżniają wielkość liter.
Uchwyty użytkownika składają się z jedenastu znaków base64.
Klucze szyfrujące są zawsze zakodowane w formacie base64. Istnieją następujące typy kluczy:
MEGA wykorzystuje szyfrowanie/deszyfrowanie po stronie klienta, aby zabezpieczyć transfer plików i przechowywanie. Dane otrzymane od klientów są przechowywane i przesyłane w dosłownym brzmieniu; serwery nie odszyfrowują, nie szyfrują ponownie, ani nie weryfikują szyfrowania przychodzących plików użytkownika. Całe przetwarzanie kryptograficzne jest pod kontrolą użytkownika końcowego.
Aby umożliwić częściowe odczyty sprawdzające integralność, plik jest traktowany jako seria kawałków. Aby uprościć przetwarzanie po stronie serwera, częściowe wysyłanie może zaczynać się i kończyć tylko na granicy kawałków. Ponadto częściowe pobrania mogą być sprawdzane pod względem integralności tylko wtedy, gdy spełniają to samo kryterium.
Granice fragmentów znajdują się w następujących miejscach:
0 / 128K / 384K / 768K / 1280K / 1920K / 2688K / 3584K / 4608K / … (co 1024 KB) / EOF
Klucz do pliku ma długość 256 bitów i składa się z następujących elementów:
Fragment MAC jest obliczany w następujący sposób (jest to zasadniczo CBC-MAC, który został wybrany zamiast bardziej wydajnego OCB z powodu obaw o własność intelektualną):
h := (n Dla każdego bloku AES d: h : = AES(k,h XOR d)
A chunk jest szyfrowany przy użyciu standardowego trybu licznikowego:
Dla każdego bloku AES d w pozycji bloku p: d’ := d XOR AES(k,(n Obliczanie i szyfrowanie MAC może być wykonywane w tej samej pętli.
Deszyfrowanie jest analogiczne.
Aby uzyskać meta-MAC m, zastosuj ten sam CBC-MAC do wynikowych blokowych MAC z wartością początkową 0. 64-bitowy meta-MAC m jest obliczany jako ((bity 0-31 XOR bity 32-63)
Przesyłanie odbywa się poprzez wysyłanie surowych danych do docelowego adresu URL zwróconego przez polecenie API u. Jeśli jest to pożądane, ładowanie może być wykonane w kawałkach. Kawałki mogą być wysyłane w dowolnej kolejności i mogą mieć dowolny rozmiar, ale muszą zaczynać się i kończyć na granicy kawałka. Przesunięcie bajtowe x fragmentu w pliku jest wskazywane przez dodanie /x do adresu URL. Wiele fragmentów może być wysyłanych równolegle. Po zakończeniu kawałka, serwer odpowiada komunikatem o stanie, którym może być:
Klucz szyfrowania per-upload musi być generowany przez silny generator liczb losowych. Użycie słabego podważy poufność i integralność Twoich danych.
Na przepustowość TCP na łączach o dużych opóźnieniach negatywnie wpływa powolny wzrost okna kongestii, niewystarczający rozmiar bufora wysyłania lub odbierania oraz (nawet łagodna) utrata pakietów. Wszystkie te czynniki mogą być złagodzone przez użycie wielu połączeń transferowych równolegle. Aplikacje klienckie są zachęcane do oferowania użytkownikom możliwości skonfigurowania do sześciu równoległych połączeń w każdym kierunku. Zalecana wartość domyślna to cztery.
Wszystkie serwery MEGA obsługują dostęp HTTPS – jest to spowodowane tym, że wiele przeglądarek internetowych wymusza politykę, w której żądania HTTP nie mogą być wykonane ze strony HTTPS w ogóle (IE, Firefox 18+) lub przynajmniej wywołują wizualne ostrzeżenie (Chrome, Firefox do 17). Jednak tylko dwa rodzaje żądań faktycznie korzystają z HTTPS, a zatem wymagają HTTPS: ładowanie strony https://mega.nz/index.html i interfejs żądań API. Ani zabezpieczone hashami ładowanie statycznych komponentów .html i .js, ani oczekiwanie na nowe żądania serwer-klient, ani już zaszyfrowane i MAC’ed transfery danych z i do klastra pamięci masowej nie korzystają z HTTPS w żaden znaczący sposób. Aplikacje klienckie są zatem zobowiązane do korzystania z protokołu SSL w celu uzyskania dostępu do interfejsu API, ale zdecydowanie odradza się im to w przypadku żądań oczekiwania i masowego przesyłania plików.
Dostęp HTTPS w MEGA obsługuje większość szyfrów/haszy i używa silnego 2048 bitowego RSA tam, gdzie SSL jest istotny (tj. Na głównym serwerze HTML i serwerach API) i RC4/MD5 z oszczędzającym procesor 1024 bitowym RSA tam, gdzie nie jest (tj. Na statycznych serwerach HTML i serwerach pamięci masowej).
PFS („perfect forward secrecy”) jest obsługiwany tylko na serwerach API, ponieważ nie jest wymagany dla publicznych treści statycznych.
Ostatnia aktualizacja 18 grudnia 2020 r., obowiązuje od 18 stycznia 2021 r.