We doen er alles aan om de rechten van onze gebruikers te beschermen en transparant te zijn over onze broncodes. Hierdoor kunnen geïnteresseerden de codes zelfstandig toetsen op veiligheid, integriteit en juistheid.
Broncode
MEGA SDK
Welkom bij de MEGA SDK! We hopen dat het nuttig zal zijn voor ontwikkelaars die geïnteresseerd zijn in het integreren van MEGA-ondersteuning in hun applicaties.
De MEGA SDK bestaat uit code en documentatie waarmee u op een aangenaam hoog abstractieniveau gebruik kunt maken van de API-functionaliteit van MEGA. De kerncomponent – een codemodule genaamd client-toegangsengine – bewaart een actuele kopie van de gebruikersaccount in het geheugen (die alle relevante bestanden, mappen, contacten en delingen bevat), accepteert opdrachten van de applicatie en stelt de applicatie op de hoogte van opdrachtresultaten en andere updates via callbacks.
De MEGA-engine voor clienttoegang wordt geleverd als een set C++-klassen en interfaces. Als u C ++ gebruikt, kunt u deze eenvoudig aan uw project toevoegen. Vervolgens concretiseert u de MegaKlant-klasse (die de sessiestatus vasthoudt) en geeft u deze een instantie door van uw implementatie van de HttpIO-interface (die netwerkverzoeken en blokkeringen afhandelt) en MegaApplicatie (waardoor u de callbacks van de engine ontvangt).
De kerncode is redelijk platformonafhankelijk (laat het ons weten als u problemen ondervindt met uw specifieke C++-compileromgeving). Om praktisch gebruik te illustreren, is een voorbeeldtoepassing (een interactieve consoleclient in ftp-stijl) inbegrepen.
De vereiste om te integreren met projecten die compileren naar native code sluit alle talen uit die afhankelijk zijn van specifieke tolken of runtime-omgevingen. C, dat de “lingua franca” is van bijna alle moderne systemen, zou de voor de hand liggende keuze zijn geweest, maar de voordelen van codecompactheid en leesbaarheid die worden geboden door de syntactische suiker- en sjabloonbibliotheek van C++ zijn de kleine extra integratie-overhead zeker waard. We zullen samenwerken met geïnteresseerde ontwikkelaars om MEGA-ondersteuning toe te voegen aan hun voorkeursomgevingen door middel van native codemodules/extensies (in plaats van de functionaliteit naar de doeltaal zelf te porten). Neem contact met ons op viadevelopers@mega.nz als u bereid en in staat bent om bij te dragen aan een bepaalde integratie-inspanning.
De applicatie dient verzoeken in bij de klanttoegangsengine via niet-blokkerende aanroepen naar methoden van het MegaKlant-object en signaleert gebeurtenissen aan de applicatie door methoden van een object aan te roepen van de implementatie van de MegaApplicatie-interface.
Bestanden en mappen worden weergegeven door Node-objecten en er wordt naar verwezen door node-handles. Nodes wijzen naar bovenliggende nodes en vormen bomen. Bomen hebben precies één wortelnode (cirkelvormige koppeling is niet toegestaan). Node-updates (veroorzaakt door de eigen acties van de sessie, andere sessies van hetzelfde account of andere accounts, bijvoorbeeld door activiteit in een gedeelde map) worden in realtime gemeld via een callback waarin de betrokken nodes worden gespecificeerd. Verwijderde nodes worden eerst op de hoogte gebracht met hun verwijderde vlag ingesteld voordat ze worden opgeschoond om de toepassing de kans te geven ze uit de UI-weergave te verwijderen.
Er zijn ten minste drie node trees per account: Root, inkomend en onzin. Extra trees kunnen afkomstig zijn van andere gebruikers als gedeelde mappen.
Gebruikers worden verwezen door hun gebruikersnaam en/of hun primaire e-mailadres. De engine onderhoudt een Gebruikersobject voor elk gebruikersaccount dat is verschenen in de context van de huidige sessie: als contactpersoon of alleen als eigenaar van een bestandssysteemknooppunt. Een zichtbaarheidsvlag verandert een gebruiker in een contactpersoon, indien ingesteld.
Gebruikersattributen kunnen worden gebruikt om inloggegevens zoals avatarafbeeldingen, adres, geboortedatum etc. op te slaan. Het wordt aanbevolen om applicatie-privé gebruikersreferenties AES-CBC gecodeerd op te slaan.
Alle engine-methoden zijn niet-blokkerend – wachten tot de netwerkcommunicatie is voltooid, is geen optie. In plaats daarvan initiëren ze alleen de gewenste actie, waarvan de uitkomst uiteindelijk wordt gesignaleerd door middel van een callback. De applicatie moet bestand zijn tegen dergelijke callbacks die na een lange tijd (d.w.z. vele seconden) aankomen. Mislukte verzoeken (bijvoorbeeld vanwege netwerkproblemen) worden automatisch opnieuw geprobeerd met exponentiële vertraging. De applicatie ontvangt hiervan een melding via een callback en zou de gebruiker dienovereenkomstig moeten informeren, samen met een UI-element om handmatig een nieuwe poging te starten.
Drie soorten bewerkingen zijn onderhevig aan versnelling door een mechanisme dat “speculatieve onmiddellijke voltooiing” wordt genoemd: Updates, verplaatsingen en verwijderingen van node-attributen. Aangezien deze slechts een zeer voorspelbaar “OK”- of “mislukt”-antwoord van de API ontvangen, heeft het enig voordeel om de lokale node onmiddellijk bij te werken en de sessiestatus opnieuw te laden in het zeldzame geval van een inconsistentie. De engine beschermt ze losjes met een toegangscontrole die dezelfde semantiek volgt als de gezaghebbende controle aan de kant van de API-server.
Gedeelde toegang tot een bron (beschrijfbare knooppunten die toegankelijk zijn voor het account van de gebruiker) op basis van een mogelijk verouderde weergave (vanwege netwerklatentie) is van nature vatbaar voor racecondities, wat leidt tot inconsistenties wanneer twee partijen tegenstrijdige updates maken binnen het latentievenster. De engine bevat heuristieken om deze conflicten te detecteren en zal de toepassing vragen om de weergave te verwijderen en opnieuw te laden indien nodig (de gebruiker moet hiervan op de hoogte worden gebracht).
Vanwege zijn niet-blokkerende aard kan de MEGA-engine voor klanttoegang buitengewoon goed worden geïntegreerd met applicaties met één thread (hoewel u op platforms zonder een niet-blokkerende DNS-lookup-faciliteit misschien niet om het gebruik van een werkthread voor naamomzetting heen kunt). Als u echter liever meerdere threads gebruikt, kunt u dat doen – zolang u ervoor zorgt dat er geen twee threads tegelijkertijd de engine binnenkomen of toegang krijgen tot de datastructuren.
Er zijn drie manieren om de engine met de applicatie te integreren. Het doel is om de engine snel de CPU te laten krijgen (via MegaKlants exec() methode) telkens wanneer een van zijn activeringstriggers wordt geactiveerd:
Applicaties moeten voorbereid zijn op het omgaan met botsingen tussen bestands- en mapnamen. In veel scenario’s is dit triviaal – de gebruiker ziet alle kopieën en neemt de beslissing in welk bestand hij geïnteresseerd is, meestal op basis van het tijdstempel. Sommige toepassingen wijzen echter een MEGA-node structuur toe aan een bron die bestandspaden gebruikt als unieke sleutels, b.v. bestandssystemen. In dit geval raden we aan om alleen de meest recente node te gebruiken.
Bestandsnaamtekens die niet zijn toegestaan op de host, moeten worden geurlend met %xx. Bij het terugschrijven van bestanden naar de server moeten geldige urlengecodeerde sequenties worden vervangen door het gecodeerde teken. Dit heeft het potentieel ongewenste neveneffect van het mangelen van bestandsnamen die oorspronkelijk geldige %xx-reeksen bevatten, maar dit zou zeldzaam moeten zijn en ze zullen worden ontward wanneer ze worden teruggelezen naar de lokale machine.
We vragen alle applicatieontwikkelaars die nieuwe node-, bestands- of gebruikersattributen willen introduceren vriendelijk om de nummering/naamgeving en formatteringsconventies met ons af te stemmen om de interoperabiliteit tussen applicaties te maximaliseren. Als u ervoor kiest om dit niet te doen, voorkom dan dat de naamruimten onoverzichtelijk worden en laat de nieuwe attribuutnamen voorafgaan door uw afgekorte bedrijfs- of toepassingsnaam.
De volgende interfaces moeten door de toepassing worden geïmplementeerd:
Bestandstoegang
– Bestanden openen/sluiten/lezen/schrijvenHttpIO
– HTTP-verzoeken met SSL-ondersteuningPrnGen
– Cryptografisch sterke pseudo-random number generatorSymmCipher
– AES cryptographyAsymmCipher
– RSA cryptographyMegaApplicatie
– callbacks naar de applicatieDe SDK biedt referentie-implementaties vanBestandstoegang
(met behulp van POSIX -oproepen), HttpIO
(met behulp van cURL) en van PrnGen SymmCipher
en AsymmCipher
(met behulp van Crypto++). Als u besluit om cURL in uw applicatie te gebruiken, zorg er dan voor dat deze is gebouwd met c-ares -ondersteuning voor asynchrone DNS-verzoeken. Sommige platforms (bijv. MacOS en Fedora) bundelen cURL-binaries die zijn gecompileerd met threaded-resolver-ondersteuning – deze zullenniet werken.
Om toegang te krijgen tot MEGA, moet een toepassing drie klassen instantiëren:
MegaApplicatie
-interfaceHttpIO
-interfaceMEGAProgramma
Vervolgens moet de toepassing MegaProgramma
‘swacht()
aanroepen, onmiddellijk vóór of in plaats van zelf gebeurtenissen te blokkeren. Als wacht()
wil blokkeren, roept het HttpIO
’s waitio ()
aan, wat een time-out oplevert. De toepassing kan ofwel zijn eigen ontwaakcriteria meeliften op de socketgebeurtenissen/time-out in waitio()
, of de criteria opnemen waardoor waitio()
wordt gewekt en deze opnemen in zijn eigen blokkeerlogica. Het meegeleverde SDK-voorbeeld (megaapp.cpp) gebruikt de vorige benadering, waarbij fileno(stdin)
wordt toegevoegd aan deselectie()
fd-set om gebruikersinvoer in realtime te verwerken.
De applicatie moet MegaProgramma’s exec()
minstens één keer na elke wake-up aanroepen volgens de waitio()
criteria (het kan geen kwaad om dit te vaak te doen).
Een MEGA sessie bestaat uit:
MegaClient::nodes
)MegaClient::users
)MegaClient::ft
)MegaClient::rootnodes
)MegaClient::me , MegaClient::myemail
)Een node heeft de volgende eigenschappen:
Raadpleeg de meegeleverde broncode voor details.
Een externe gebruiker maakt deel uit van de sessie omdat hij een contactrelatie heeft met de gebruiker van de sessie, of omdat hij eigenaar is van ten minste één van de node van de sessie. Er wordt ook een gebruikersrecord aangemaakt wanneer een deling wordt toegevoegd aan een eerder niet-geregistreerd e-mailadres. Er kan naar gebruikers worden verwezen via hun gebruikersnaam of via hun e-mailadres.
Gebruikers eigenschappen:
Meerdere gelijktijdige bestandsoverdrachten worden ondersteund. Het wordt sterk aangeraden om niet meer dan één grote upload en één grote download parallel uit te voeren om netwerkcongestie te voorkomen (er zal weinig of geen snelheidsvoordeel zijn). Een bestandsoverdracht kan meerdere TCP-kanalen samenvoegen (aanbevolen startpunt: 4) voor een grotere doorvoer. Bestandsoverdrachten kunnen op elk moment worden afgebroken door MegaClient::tclose()
aan te roepen. Aanzienlijke lokale netwerkcongestie tijdens uploads is gebruikelijk bij ADSL-uplinks en kan worden voorkomen door een automatische of vaste snelheidslimiet in te schakelen.
Toepassingen die batches bestanden overdragen, zouden de functionaliteit voor overdrachtswachtrijen van de engine moeten gebruiken. Het maakt gebruik van pipelining (nieuwe overdrachten worden ongeveer drie seconden voor het einde van de huidige overdracht verzonden) om de dode tijd tussen bestanden te verminderen of te elimineren. Mislukte overdrachten worden opnieuw geprobeerd met exponentiële uitstel.
Bestanden kunnen attributen hebben. Alleen de oorspronkelijke maker van een bestand kan de kenmerken ervan bijwerken. Alle nodes die naar hetzelfde gecodeerdebestand verwijzen, zien dezelfde attributen. Attributen hebben een 16-bits typeveld. De engine voor programmatoegang ondersteunt het toevoegen van bestandskenmerken tijdens of na het uploaden en het in bulk ophalen ervan.
Alle toepassingen die in staat zijn om afbeeldingsbestanden te uploaden, moeten tijdens het proces miniaturen toevoegen (onthoud dat we dit op geen enkele manier aan de serverzijde kunnen doen). Miniaturen worden opgeslagen als type 0 bestandskenmerken en zouden 120p*120p JPEG’s moeten zijn, gecomprimeerd tot ongeveer 3-4 KB. De voorbeeldtoepassing die bij de SDK wordt geleverd, laat zien hoe u dit kunt doen met behulp van de FreeImagebibliotheek. Aangezien het extraheren van een miniatuur uit een grote afbeelding veel tijd kan kosten, wordt ook aangeraden om dit in afzonderlijke werkthreads uit te voeren om te voorkomen dat de toepassing vastloopt.
Er zijn twee soorten tegoedbeperkingen die een toepassing kan tegenkomen tijdens de werking ervan: opslag en bandbreedte. MEGA is volgens het beleid vrij genereus voor beide, wat betekent dat slechts een klein deel van uw gebruikersbestand ooit zonder tegoed komt te zitten, maar het is van essentieel belang dat als dit gebeurt, de situatie correct wordt afgehandeld – de gebruiker moet worden geïnformeerd over de reden voor het mislukken van zijn upload of download in plaats van in het ongewisse te blijven met wat lijkt op een storing.
Een upload wordt geweigerd met de fout EOVERQUOTA
als er onvoldoende opslagruimte beschikbaar is om de upload te voltooien. Zodra de upload is gestart, wordt deze voltooid, zelfs als u in de tussentijd op een andere manier schijfruimte tekort komt (bijvoorbeeld doordat uw Pro-status verloopt). Deze fout treedt ook op als uw toepassing bestanden probeert te versturen naar een account van derden zonder voldoende tegoed.
Een downloadpoging wordt geweigerd met de fout EOVERQUOTA
als het bandbreedteverbruik gedurende de afgelopen vijf tot zes uur plus de resterende grootte van alle actieve downloads plus de grootte van het te downloaden bestand de huidige bandbreedtelimiet per IP zou overschrijden (indien van toepassing).
In tegenstelling tot uploads, kunnen actieve downloads onder bepaalde omstandigheden worden onderbroken met een geen-tegoed-fout, waardoor een quota_exceeded()
callback wordt geactiveerd en de download automatisch opnieuw wordt geprobeerd totdat bandbreedte-tegoed beschikbaar is.
U kunt onze andere bibliotheken vinden op onze algemene GitHubpagina. Als u onze code commercieel wilt gebruiken op een manier die buiten het bereik van deze licenties valt, neem dan contact met ons op om dit te bespreken.
De release van de C++ SDK is slechts een beginpunt en zal in de loop van de tijd evolueren. We horen graag van ontwikkelaars die het daadwerkelijk in hun applicaties gebruiken – als u bugs, ontwerpfouten of andere tekortkomingen vindt, neem dan contact op viadevelopers@mega.nz. MEGA neemt mensen aan, dus wees voorbereid op een aanbieding als uw feedback aangeeft dat u een slimme geest bent.
Een ontwikkelaarsforum en broncodeopslagplaats zullen binnenkort beschikbaar worden gesteld.
Het laden van grote MEGA-accounts kan behoorlijk lang duren. Dit komt door de enorme omvang van de statusinformatie die uit het API-cluster moet worden gelezen. Er zijn twee manieren om dit te omzeilen:
Momenteel kunnen bestanden niet worden gewijzigd nadat ze zijn gemaakt. Deze beperking wordt overwonnen door gecodeerde deltabestanden te gebruiken.
Momenteel wordt de integriteit van een bestand pas geverifieerd nadat het volledig is gedownload. Chunk MAC-verificatie stelt applicaties in staat om de integriteit van gedeeltelijke uitlezingen te waarborgen.
megaclient
Om succesvol megaclient
te bouwen, heeft u het volgende nodig:
Op dit moment wordt de SDK niet geleverd met een autoconf-script, dus het kan zijn dat u de Makefile handmatig aan uw systeem moet aanpassen.
megaclient
Net als bij de UNIX ftp
-opdracht geeft megaclient
een prompt weer en accepteert opdrachten om in te loggen op een MEGA-account of een geëxporteerde mapkoppeling, de inhoud van mappen weer te geven, mappen te maken, bestanden en mappen te kopiëren, te verplaatsen en te verwijderen, inkomende en uitgaande mapshares te bekijken, tot stand te brengen, te wijzigen en te verwijderen uitgaande mappen delen, bestanden uploaden en downloaden, links naar mappen en bestanden exporteren, bestandslinks importeren, de accountstatus bekijken en het wachtwoord wijzigen.
login
– log in op een account of maplinkOm u aan te melden bij een account, geeft u het e-mailadres van de account op en eventueel het wachtwoord (waar u anders om wordt gevraagd).
Om in te loggen op een geëxporteerde maplink, geeft u de volledige link op, inclusief de sleutel (het vragen om de sleutel is nog niet geïmplementeerd).
Merk op dat er niet naar geëxporteerde mappen kan worden geschreven.
mount
– beschikbare bestandssysteemstructuren weergevenDeze opdracht gebruikt geen parameters en toont de paden van uw beschikbare bestandssysteemstructuren (meestal / voor de hoofdstructuur, //in
for the inbox ,//bin
for the prullenbak en email:sharename
voor inkomende delingen van user email
.
ls
– lijst bestanden en mappenls
geeft de inhoud weer van de huidige map (indien gegeven met de kwalificatie -R, gebeurt dit recursief) of het opgegeven pad.
Paden kunnen relatief of absoluut zijn. Geldige absolute paden beginnen met een van de voorvoegsels die worden weergegeven door de opdracht mount.
Bestands- en mapeigenschappen worden weergegeven samen met hun namen: bestandsgrootte en beschikbare bestandskenmerken, of geëxporteerde maplinks en uitgaande mapdelingen.
cd
– verander de huidige werkmapcd
verandert de huidige werkmap naar het opgegeven mappad. Als er geen pad wordt opgegeven, verandert het in / .
pwd
– huidige map weergevenpwd
geeft de huidige map weer als een absoluut pad.
lcd
– verander de huidige lokale werkmaplcd
verandert de huidige lokale werkmap naar het opgegeven pad.
get
– voeg bestand(en) toe aan de downloadwachtrijget
zet het opgegeven bestand in de wachtrij om te downloaden. Als u een map opgeeft, worden alle bestanden in de map in de wachtrij geplaatst om te downloaden (maar niet de inhoud van de submappen).
put
– voeg bestand(en) toe aan de uploadwachtrijput
zet het opgegeven bestand in de wachtrij voor uploaden. Patronen worden ondersteund - put *.jpg
zal alle .jpg-bestanden in de huidige lokale map uploaden.
getq
en putq
– overdrachten in de wachtrij weergeven/verwijderen/afbrekenDe overdrachten in de wachtrij worden weergegeven met een index, doelpad (alleen uploads) en activiteitsstatus. Om een overdracht te annuleren, geeft u de index op.
mkdir
– mappen makenmkdir
maakt een lege submap aan in de opgegeven (of huidige) map. Hoewel MEGA identieke mapnamen toestaat, mislukt mkdir
als de map al bestaat.
cp
,mv
– kopiëren of verplaatsen, hernoemen van bestanden en mappenHet opgegeven bronpad of de opgegeven map wordt gekopieerd of verplaatst naar de doelmap. Als de bestemming een nieuwe naam aangeeft in een bestaande map, vindt onderweg een hernoeming plaats.
rm
– bestand of map verwijderenrm
verwijdert het opgegeven bestand of de opgegeven map. Als de map bestanden of submappen bevat, worden deze ook recursief verwijderd. Alle getroffen uitgaande delingen en geëxporteerde mapkoppelingen worden tijdens het proces geannuleerd.
De verwijdering is definitief. Gebruik in plaats daarvan mv path //bin
om te profiteren van de functionaliteit van de prullenbak.
share
– uitgaande mapdelingen beherenshare
lijst, maakt, werkt bij of verwijdert uitgaande delingen in de opgegeven map. De map mag zich niet in een inkomende deling bevinden.
Gebruik het share path
om de bestaande delingen in een map weer te geven.
Om het delen van een map met een gebruiker te annuleren, gebruikt ushare path email
.
Om een gedeelde map aan te maken of te wijzigen, gebruikt u share path email access
.
Ondersteunende toegangslevels zijn: Alleen-lezen( r
), lezen/schrijven ( rw
) en volledig ( full
).
export
– maak of annuleer een bestands- of maplinkexport
maakt een alleen-lezen bestands- of maplink die de gerelateerde coderingssleutel bevat. Voeg het trefwoord del
toe om een bestaande link te annuleren.
import
– importeer geëxporteerd bestandimport
voegt het bestand beschreven door de meegeleverde link toe (importeren van maplinks wordt momenteel niet ondersteund) aan de huidige map.
putbps
– upload snelheidslimiet instellenUploaden via een DSL-lijn kan aanzienlijk uitgaand pakketverlies veroorzaken. U kunt de verzendsnelheid beperken door een absoluut maximum in bytes per seconde op te geven,auto
om de server uw lijnsnelheid te laten bepalen en ongeveer 10% ervan inactief te laten, of geen
om op volle snelheid over te dragen.
Het is momenteel niet mogelijk om de verzendsnelheid van een actieve upload te wijzigen. De instelling heeft alleen invloed op volgende uploads.
whoami
– accountgegevens weergevenwhoami
geeft verschillende accounttegoeden, saldi en de sessiegeschiedenis weer.
passwd
– wijzig account wachtwoordpasswd
vraagt om het huidige wachtwoord en vraagt vervolgens om het nieuwe wachtwoord en de bevestiging daarvan. Er wordt geen controle op de wachtwoordkwaliteit uitgevoerd.
retry
– probeer onmiddellijk alle lopende bewerkingen opnieuwretry
reset alle exponentiële uitsteltimers.
recon
– opnieuw verbindenrecon
verbreekt alle bestaande serververbindingen. Dit heeft geen effect op lopende bewerkingen, behalve dat overdrachten langer duren omdat gedeeltelijk overgedragen brokken worden weggegooid en opnieuw moeten worden verzonden.
reload
– accountstatus wissen en opnieuw ladenreload
zuivert de lokale status en forceert een volledige herlaadbeurt van de server. Dit is handig als reactie op de detectie van een raceconditie-gerelateerde inconsistentie tussen de weergave van de client en de serverstatus.
logout
– huidige sessie beëindigenlogout
verwijdert alle lokale sessiestatussen.
debug
– schakel de foutopsporingsmodus inDe foutopsporingsmodus voert HTTP-verbindingsactiviteit en de onbewerkte JSON API-verzoeken en -antwoorden uit.
Hasht een UTF-8-gecodeerd wachtwoord en slaat het resultaat op in de meegeleverde buffer.
Methode: error hashpw_key(const char* password, char* hash)
Retourcodes: API_EARGS
in geval van ongeldige UTF-8-codering
Start een sessielogin op basis van het e-mailadres van de gebruiker (hoofdlettergevoelig) en de bijbehorende wachtwoord-hash.
Methode: void login(const char* email, const char* hash)
Callback: login_result(error e)
Foute codes: API_ENOENT
:Ongeldig e-mailadres of wachtwoord, API_EKEY
: Privésleutel kan niet worden gedecodeerd
Methode: void folderaccess(const char* node, const char* key)
Callback: geen (heeft geen interactie met de server, ga door met bellen fetchnodes() )
Method: void fetchnodes()
Callback: fetchnodes_result(client, error e)
Roept bij succesvolle afronding ook nodes_updated() aan.
Methode:void getaccountdetails(AccountDetails* result, int storage, int transfer, int pro, int transactions, int purchases, int sessions)
Werkt de geleverde AccountDetails-structuur bij met informatie over het huidige opslag- en overdrachtsgebruik en tegoed, Pro-status en de transactie- en sessiegeschiedenis. U kunt aangeven in welke soorten informatie u geïnteresseerd bent door de gerelateerde vlag in te stellen op een andere waarde dan nul.
Methode: error changepw(const char* currentpwhash, const char* newpwhash)
Callback: changepw_result(error e)
Teruggegeven code: API_EACCESS
als gebruikerssessie bestaat.
Methode: error setattr(Node* node, const char** newattr)
Teruggegeven waarde: API_EACCESS
als het knooppunt niet beschrijfbaar is.
Callback: setattr_result(handle nodehandle, error e)
De huidige attributen van de node worden naar de server gepusht. De optionele newattrparameter
specificeert attribuutdelta’s als NULL-beëindigde reeks van attribuutnaam/attribuut C-string pointerparen. In setattr_result(),nodehandle
is de handle
van het node.
Methode: error rename(Node* node, Node* newparent)
Teruggegeven waarde:API_EACCESS
als de parent of newparent van het knooppunt niet beschrijfbaar is (respectievelijk met volledige en lees-/schrijftoegang) of als de verplaatsing tussen verschillende gebruikersaccounts zou plaatsvinden, API_ECIRCULAR
als er een circulaire koppeling zou ontstaan.
Callback: rename_result(handle nodehandle, error e)
De node (samen met al zijn onderliggende nodes) wordt verplaatst naar de nieuwe bovenliggende node, dat deel moet uitmaken van hetzelfde gebruikersaccount als de node zelf. U kunt een modus niet naar zijn eigen substructuur verplaatsen.
Methode: error unlink(Node* node)
Terugkerende waarde: API_EACCESS
als de ouder van de node niet beschrijfbaar is (met volledige toegang).
Callback: unlink_result(handle nodehandle, error e)
De node en alle subnodes zijn verwijderd. De hoofdnode moet schrijfbaar blijven (met volledige toegang). Getroffen uitgaande delingen worden geannuleerd.
Uploads en downloads worden gestart mettopen()
, dat een overdrachtsbeschrijving retourneert die de overdracht identificeert. Meerdere overdrachten kunnen parallel worden uitgevoerd en elke overdracht kan meerdere parallelle TCP-verbindingen gebruiken. Efficiënte overdrachtswachtrijen met pipelining zijn beschikbaar. Uploads kunnen in snelheid worden beperkt met behulp van een absolute of dynamische limiet.
Voortgangsinformatie wordt overgebracht via de callback transfer_update (int td, m_off_t bytes, m_off_t size, dstime starttime)
, waarbij td de overdracht identificeert, bytes het aantal tot dusver overgedragen bytes aangeeft, size de totale overdrachtsgrootte aangeeft en starttime de tijd is waarop de overdracht gestart.
Een lopende overdracht kan op elk moment worden afgebroken door tclose(int td)
aan te roepen. Fout-indicerende callbacks voeren impliciet the tclose()
uit. De callback die een tijdelijke HTTP-fout aangeeft, transfer_error(int td, int httpcode, int count)
zal tclose()
aanroepen als de toepassing een waarde retourneert die niet gelijk is aan nul.
Methode:int topen(const char* lokale bestandsnaam, int snelheidslimiet, int verbindingen)
speedlimit
– maximale uploadsnelheid in bytes/seconde of -1 voor ca. 90% van de lijnsnelheid
connections
– aantal te gebruiken parallelle verbindingen (standaard: 3)
Retourwaarde: overdrachtsdescriptor of API_ETOOMANY
als alle overdrachtskanalen bezet zijn, API_ENOENT
als het bestand niet kan worden geopend.
Terugbellen na succesvolle afronding: transfer_complete(int td, handle uploadhandle, const byte* uploadtoken, const byte* filekey, SymmCipher* filekey)
Terugbellen bij falen: transfer_failed(int td, error e)
Methode: int topen(handle nodehandle, const byte* key, m_off_t start, m_off_t len, int c)
nodehandle
is de node van het te downloaden node (als de sleutel is ingesteld, het handvatgedeelte van de geëxporteerde bestandskoppeling)
key
is het base64-gedecodeerde sleutelgedeelte van de geëxporteerde bestandskoppeling indien ingesteld
start
en len kan worden ingesteld om alleen een deel van het bestand te downloaden (standaard: 0, -1 voor het volledige bestand)
c
geeft het aantal parallelle TCP-verbindingen aan dat deze download moet gebruiken.
Retourwaarde: overdrachtsdescriptor of API_ETOOMANY
als alle overdrachtskanalen bezet zijn, API_ENOENT
als het lokale bestand niet aanwezig is,API_EACCESS
als u probeert een niet-bestand te downloaden
Terugbellen na succesvol openen van het te downloaden bestand:topen_result(int td, string* filename, const char* fa, int pfa)
td
identificeert de overdracht
filename
is de naam van het bestand zoals gespecificeerd door het node kenmerk ‘n’
fa
zijn de bestandskenmerken beschikbaar voor dit bestand
pfa
is een vlag die aangeeft of de aanvragende gebruiker bestandskenmerken mag schrijven (d.w.z. of hij de eigenaar van het bestand is)
Terugbellen bij succesvolle afronding:transfer_complete(int td, chunkmac_map* macs, const char* fn)
td
identificeert de overdracht
macs
bevat de MAC-hash voor elk bestandsdeel
fn
is de bestandsnaam (UTF-8)
Terugbellen bij falen: transfer_failed(int td, string& filename, error e)
Terugbellen bij het bereiken van de overdrachtslimiet: transfer_limit(int td)
De engine onderhoudt afzonderlijke upload- en downloadwachtrijen, putq
en getq
. Overdrachten worden gestart door overdrachtsobjecten (classes FilePut
enFileGet
naar deze wachtrijen te duwen). U hoeft niet langer zelf te topen()
/ tclose()
op te roepen maar u moet nog wel de overdracht callbacks verwerken. Een overdracht wordt als mislukt beschouwd als er gedurende ten minste XFERTIMEOUT deciseconden geen bytes zijn verzonden, in welk geval de overdracht wordt afgebroken en voor onbepaalde tijd wordt herhaald met exponentiële vertraging.
Het belangrijkste voordeel van het gebruik van de door de engine geleverde overdrachtswachtrij is niet de verminderde toepassingscomplexiteit, maar de ingebouwde overlappende overdrachtspipelining die de impact van overgangen tussen bestanden op uw algehele doorvoer vermindert.
Nodes kunnen worden toegevoegd aan putnodes_result(error e, targettype t, NewNode* nn)
Methode: void putnodes(handle parenthandle, NewNode* newnodes, int numnodes)
parenthandle
is het handvat van de nieuwe node’s hoofd node.
newnodes
is een array van bevolkte NewNode-structuren. Onder bepaalde omstandigheden zal deze array worden benaderd na de aanroep van putnodes()
is al teruggekeerd. Daarom, always wijs deze array toe van de heap en maak deze vrij putnodes_result()
.
numnodes
is het aantal aanwezige NewNode-records.
Terugbellen: putnodes_result(client,error) als de bewerking
Methode: setshare(node,targetuser,accesslevel)
Callback: share_result(client,error)
Callback: share_result(client,int,error)
Method: loggedin()
Retourneert: 1 indien ingelogd, anders 0
Methode: checkaccess(node,level)
Retourneert: 1 als toegang is toegestaan, anders 0
Methode: checkmove(node,targetnode)
Retourneert: foutcode (API_OK, API_EACCESS of API_ECIRCULAR)
Methode: makeattr(cipher,targetstring,jsonstring,length)
Callback: newfile()
Retourneert: Applicatie-specifieke FileAccess object
Callback: users_updated(client,users,count) – gebruikers zijn toegevoegd of bijgewerkt (gebruikers worden nooit verwijderd)
Callback: node_updated(client,nodes,count) – nodes zijn toegevoegd, bijgewerkt of verwijderd
Callback: notify_retry(client,time) – specificeert de tijd in beslissingen tot de volgende nieuwe poging
Callback: reload(client,reason) – mogelijke inconsistentie, laad de accountstatus opnieuw
Kennis van de volgende details op laag niveau is niet vereist om MEGA-programmatoepassingen met succes te ontwikkelen. Het is bedoeld als naslagwerk voor diegenen die geïnteresseerd zijn om volledig te begrijpen hoe MEGA’s API werkt.
De MEGA API is gebaseerd op een eenvoudig HTTP/JSON-verzoek-antwoordschema. Verzoeken worden ingediend als arrays van opdrachtobjecten en kunnen worden geïnitieerd door zowel het programma als de server, wat in feite resulteert in bidirectionele RPC-mogelijkheden. Gebruik de opdracht debug om de onbewerkte aanvraagstroom in het megaprogramma-voorbeeldapplicatie van de SDK te zien.
Alle symmetrische cryptografische bewerkingen zijn gebaseerd op AES-128. Het werkt in coderingsblokketenmodus voor de bestands- en mapattribuutblokken en in tellermodus voor de daadwerkelijke bestandsgegevens. Elk bestand en elk mapnode gebruikt zijn eigen willekeurig gegenereerde 128-bits sleutel. Bestandsnodes gebruiken dezelfde sleutel voor het attribuutblok en de bestandsgegevens, plus een 64-bits willekeurige tellerstartwaarde en een 64-bits meta-MAC om de integriteit van het bestand te verifiëren.
Elke gebruikersaccount gebruikt een symmetrische hoofdsleutel om alle sleutels van de nodes die het in zijn eigen structuren bewaart, te coderen met de ECB. Deze hoofdsleutel wordt opgeslagen op de servers van MEGA, gecodeerd met een hash die is afgeleid van het inlogwachtwoord van de gebruiker.
Bestandsintegriteit wordt geverifieerd met behulp van chunked CBC-MAC. Chunk-groottes beginnen bij 128 KB en nemen toe tot 1 MB, wat een redelijk evenwicht is tussen de ruimte die nodig is om de chunk-MAC’s op te slaan en de gemiddelde overhead voor gedeeltelijke leesbewerkingen die de integriteit controleren.
Naast de symmetrische sleutel heeft elk gebruikersaccount een 2048-bits RSA-sleutelpaar om veilig gegevens zoals deelsleutels of bestands-/mapsleutels te ontvangen. Het privécomponent wordt gecodeerd opgeslagen met de symmetrische hoofdsleutel van de gebruiker.
De eigenaar van de map is als enige verantwoordelijk voor het beheer van de toegang; delingen zijn niet-transitief (delingen kunnen niet worden gemaakt op mappen in inkomende delingen). Alle deelnemers aan een gedeelde map krijgen cryptografische toegang via een gemeenschappelijke specifieke deelsleutel, die wordt doorgegeven door de eigenaar (theoretisch door iedereen die deelneemt aan de deling, maar dit zou een aanzienlijk beveiligingsrisico vormen in het geval van een inbreuk op de kern van de map). infrastructuur) aan nieuwe deelnemers via RSA. Alle sleutels van de nodes in een gedeelde map, inclusief de hoofdnode, zijn gecodeerd naar deze gedeelde sleutel. De partij die een nieuw node aan een gedeelde map toevoegt, is verantwoordelijk voor het leveren van de juiste node-/deel specifieke sleutel. Ontbrekende node-/deel-specifieke sleutels kunnen alleen worden geleverd door de delings-eigenaar.
MEGA ondersteunt veilige niet-geverifieerde gegevenslevering. Elke volledig geregistreerde gebruiker kan bestanden of mappen in zijn inbox ontvangen via zijn openbare RSA-sleutel.
Elke login start een nieuwe sessie. Voor gewone accounts houdt dit in dat de server een willekeurig sessietoken genereert en dit codeert met de persoonlijke sleutel van de gebruiker. Het gebruikerswachtwoord wordt als geverifieerd beschouwd als het met succes de privésleutel decodeert, die vervolgens het sessietoken decodeert.
Om offline woordenboekaanvallen op afstand op het wachtwoord van een gebruiker te voorkomen, wordt de gecodeerde privésleutel alleen aan het programma geleverd als een hash die is afgeleid van het wachtwoord aan de server wordt gepresenteerd.
API-verzoeken stromen in twee richtingen: client → server en server → client
Programma-server-verzoeken worden uitgegeven als HTTP POST met een onbewerkte JSON-payload. Een verzoek bestaat uit een of meerdere opdrachten en wordt uitgevoerd als een enkele atomaire, geïsoleerde en consistente transactie – in het geval van een foutreactie op verzoekniveau zijn er geen gegevens gewijzigd. Verzoeken zijn idempotent – het meerdere keren verzenden van hetzelfde verzoek staat gelijk aan het één keer verzenden, waardoor het veilig is om ze opnieuw te proberen, b.v. bij periodieke netwerkproblemen. Elk verzoek moet daarom worden getagd met een sessie-unieke identificatie (bijvoorbeeld een volgnummer) om onbedoelde cachetreffers te voorkomen die worden veroorzaakt door voorgaande identieke verzoeken.
Terwijl een verzoek wordt uitgevoerd, zijn alle gebruikers die er mogelijk door worden beïnvloed, vergrendeld. Dit omvat de aanvragende gebruiker en alle gebruikers die zich in een gedeelde maprelatie en/of in de contactenlijst bevinden. Een verzoek kan de foutcode EAGAIN retourneren in het geval van een mislukte vergrendelingspoging of een tijdelijke storing aan de serverzijde. Het verzoek is waarschijnlijk voltooid wanneer het opnieuw wordt geprobeerd. Programmatoepassingen moeten exponentiële back-off implementeren (met door de gebruiker te activeren onmiddellijke nieuwe poging) en moeten de gebruiker informeren over een mogelijk server- of netwerkprobleem als de EAGAIN-conditie aanhoudt of als er gedurende meer dan een paar seconden geen reactie wordt ontvangen.
Een met succes uitgevoerde aanvraag retourneert een reeks resultaatobjecten, waarbij elk resultaat in dezelfde matrixindexlocatie verschijnt als de overeenkomstige opdracht.
Doel URL: https://g.api.mega.co.nz/cs?id=sequence_number&ak=appkey&[&sid=sessionid|&n=node]
Het JSON-object wordt verzonden als de payload van een onbewerkt POST-verzoek. Er vindt geen aanvullende framing plaats. De Content-Type HTTP-header wordt niet verwerkt, maar moet worden ingesteld op application/json.
De structuur ervan is een reeks opdrachten: [cmd1,cmd2,…]
met cmd = {a: opdrachttype, [argument: waarde] * }.
Het antwoord op het verzoek is een onbewerkt JSON-object van content-type application/json.
Het is gestructureerd als een enkel getal (bijv. -3 voor EAGAIN) in het geval van een fout op verzoekniveau of als een reeks retourobjecten per opdracht: [res1,res2,…]
Om overbelasting van de infrastructuur te voorkomen, is dynamische snelheidsbeperking van kracht. Voordat een verzoek wordt uitgevoerd, wordt het totale “gewicht” van de opdrachten die het bevat berekend en vergeleken met het huidige saldo van het aanvragende IP-adres. Als het totaal een gedefinieerde drempel overschrijdt, wordt het verzoek als geheel afgewezen en moet het worden herhaald met exponentiële vertraging
Aangezien een server geen betrouwbare verbinding met een programma tot stand kan brengen, moeten server-programmaverzoeken door laatstgenoemde worden opgevraagd via een blokkerende leeslus.
Doel URL: https://g.api.mega.co.nz/sc?id=sequence_reference[&sid=sessionid|&n=node][ssl=1]
Een fout op verzoekniveau wordt ontvangen als een enkel getal (bijv. -3 voor EAGAIN) of een onbewerkt JSON-object met content-type applicatie/json. De structuur is als volgt:
{ a : [req1,req2,…], [ sn : sequence_reference | w : wait_url ] }
Omdat JSON niet binair schoon is, moeten alle niet-ASCII-gegevens worden gecodeerd. Voor binaire data gebruikt de MEGA API een variant van base64 met -_ in plaats van +/ en de trailing = gestript (indien nodig wordt de werkelijke payload-lengte heuristisch afgeleid na decodering, bijvoorbeeld door de trailing NUL’s te strippen). UNICODE-tekst moet worden gecodeerd als UTF-8.
De MEGA API gebruikt de volgende belangrijke gegevenstypen:
Node-handles zijn acht alfanumerieke tekens lang en hoofdlettergevoelig.
Gebruiker-handles die bestaan uit elf basis64-tekens
Coderingssleutels zijn altijd op base64-gecodeerd. De volgende sleuteltypen bestaan:
MEGA maakt gebruik van codering/decodering aan de programmazijde om bestandsoverdrachten en opslag end-to-end te beschermen. Van klanten ontvangen gegevens worden letterlijk opgeslagen en verzonden; servers decoderen niet, coderen niet opnieuw en verifiëren de codering van inkomende gebruikersbestanden niet. Alle cryptografische verwerking staat onder controle van de eindgebruiker.
Om gedeeltelijke leesbewerkingen met gecontroleerde integriteit mogelijk te maken, wordt een bestand behandeld als een reeks delen. Om verwerking aan de serverzijde te vereenvoudigen, kunnen gedeeltelijke uploads alleen beginnen en eindigen op een chunk-grens. Bovendien kunnen gedeeltelijke downloads alleen op integriteit worden gecontroleerd als ze aan hetzelfde criterium voldoen.
Chunk-grenzen bevinden zich op de volgende posities:
0 / 128K / 384K / 768K / 1280K / 1920K / 2688K / 3584K / 4608K / … (elke 1024 KB) / EOF
A-bestandssleutel is 256 bits lang en bestaat uit de volgende componenten:
Een chunk MAC wordt als volgt berekend (dit is in wezen CBC-MAC, die werd gekozen in plaats van de efficiëntere OCB vanwege zorgen over intellectueel eigendom):
h := (n << 64) + n
Voor elk AES-blok d: h : = AES(k,h XOR d)
Een chunk wordt gecodeerd met behulp van standaard tellermodus:
Voor elk AES-blok d op blokpositie p: d’ := d XOR AES(k,(n << 64)+p)
MAC berekening en codering kunnen in dezelfde lus worden uitgevoerd.
Decodering is analoog.
Om de meta-MAC m te verkrijgen, past u dezelfde CBC-MAC toe op de resulterende blok-MAC’s met een startwaarde van 0. De 64-bits meta-MAC m wordt berekend als ((bits 0-31 XOR bits 32-63) << 64) + (bits 64-95 XOR bits 96-127).
Uploads worden uitgevoerd door onbewerkte gegevens te POSTen naar de doel-URL die wordt geretourneerd door de API u-opdracht. Indien gewenst kan een upload in delen worden uitgevoerd. Chunks kunnen in elke volgorde worden verzonden en kunnen elke grootte hebben, maar ze moeten beginnen en eindigen op een chunkgrens. De byte-offset x van een blok binnen het bestand wordt aangegeven door /x toe te voegen aan de URL. Er kunnen meerdere chunks parallel worden verzonden. Nadat een blok is voltooid, reageert de server met een statusbericht, dat kan zijn:
De coderingssleutel per upload moet worden gegenereerd door een krachtige willekeurige nummergenerator. Het gebruik van een zwakke zal de vertrouwelijkheid en integriteit van uw gegevens ondermijnen.
De TCP-doorvoer op links met hoge latentie wordt nadelig beïnvloed door een langzame groei van het congestievenster, onvoldoende buffergrootte voor versturen of ontvangen en (zelfs licht) pakketverlies. Al deze factoren kunnen worden beperkt door meerdere parallelle overdrachtsverbindingen te gebruiken. Programmatoepassingen worden aangemoedigd om gebruikers de mogelijkheid te bieden tot zes parallelle verbindingen in elke richting te configureren. De aanbevolen standaardwaarde is vier.
Alle MEGA-servers ondersteunen HTTPS-toegang – dit komt doordat veel webbrowsers een beleid afdwingen waarbij HTTP-verzoeken helemaal niet kunnen worden gedaan vanaf een HTTPS-pagina (IE, Firefox 18+) of op zijn minst een visuele waarschuwing activeren (Chrome, Firefox tot 17) . Er zijn echter slechts twee soorten verzoeken die daadwerkelijk baat hebben bij en daarom HTTPS nodig hebben: het laden van https://mega.nz/index.html en de API-verzoekinterface. Noch het hash-beveiligd laden van statische .html- en .js-componenten, noch het wachten op nieuwe server-clientverzoeken, noch reeds versleutelde en MAC-gegevensoverdrachten van en naar het opslagcluster profiteren op enige zinvolle manier van HTTPS. Programmatoepassingen moeten daarom SSL gebruiken voor toegang tot de API-interface, maar dit wordt sterk afgeraden voor wachtverzoeken en bulkbestandsoverdrachten.
MEGA’s HTTPS-toegang ondersteunt de meeste cijfers/hashes en gebruikt sterke 2048-bits RSA waar SSL relevant is (d.w.z. op de root-HTML en de API-servers) en RC4/MD5 met CPU-besparende 1024-bits RSA waar dit niet relevant is (d.w.z. op statische HTML en opslagservers).
PFS (“perfect forward secrecy”) wordt alleen ondersteund op de API-servers, omdat geheimhouding niet vereist is voor openbare statische inhoud.
Laatst bijgewerkt op 18 december 2020, van kracht op 18 januari 2021.