Komentorivikäyttöliittymä ja automatisoitu avainten hallinta

SD Connectin komentorivityökalu sd-lock-util sekä komennot a-put ja a-get tukevat SD Connect -yhteensopivaa datan lataamista palveluun ja lataamista palvelusta automaattisella salauksella ja salauksen purulla. Palveluun lataamisen jälkeen dataa voidaan muokata tai analysoida, kun se on tuotu SD Desktopiin. Pieniä tiedostoja (alle 50 GB) voidaan myös ladata selainkäyttöliittymän kautta, joka tarjoaa myös automaattisen salauksen purun.

Huomaa, että tiedostot, jotka on ladattu palveluun ennen helmikuuta 2025, salattiin manuaalisesti omalla salausavainparillasi, ja niiden salaus täytyy edelleen purkaa manuaalisesti lataamisen jälkeen.

Note

Kaikilla saman CSC-projektin jäsenillä on oikeus ladata palveluun ja ladata palvelusta SD Connectin kautta tallennettuja tiedostoja. Tätä voidaan rajoittaa jakamalla tiedostoja käyttöoikeudella Read to SD Desktop toiseen Academic-tyyppiseen CSC-projektiin. Ota yhteyttä osoitteeseen servicedesk@csc.fi (aihe: SD Connect), jos tarvitset apua.

1. Taustatiedot
2. Suunnittele tarvittavien kansioiden määrä
3. Suunnittele kansioiden nimet
Komentorivityökalut ja automatisoitu avainten hallinta
Komentorivityökalut ja manuaalinen salauksen purku
Ohjeet

1. Taustatiedot

SD Connect on osa CSC:n sensitiivisen datan palveluita tutkimukselle, ja se tarjoaa maksuttoman ja turvallisen datankäsittely-ympäristön suomalaisten yliopistojen ja tutkimuslaitosten akateemisille tutkimushankkeille. SD Connect laajentaa Allas-objektitallennusjärjestelmää lisäämällä siihen automaattisen salauskerroksen, mikä mahdollistaa sensitiivisen datan turvallisen tallennuksen. SD Connectiin tallennettua dataa voidaan käyttää myös SD Desktop -palvelun kautta. Vaikka SD Connectia käytetään yleensä SD Connectin selainkäyttöliittymän kautta, komentorivityökalut voivat joissakin tilanteissa tarjota tehokkaamman tavan hallita dataa.

Tässä dokumentissa annetaan ohjeet siihen, miten voit asentaa SD Connectin komentorivityökalut paikalliseen ympäristöösi (Linux, Mac) ja miten voit käyttää niitä datan lataamiseen palveluun ja lataamiseen palvelusta SD Connectissa.

Note

Allas ei itsessään erottele SD Connectin kautta (käyttöliittymä tai komentorivityökalut) palveluun ladattua dataa ja muilla menetelmillä Altaaseen ladattua dataa toisistaan. Dataämpärit voivat sisältää sekoituksen SD Connect -dataa, muuta salattua dataa ja tavallista dataa. Käyttäjän vastuulla on hallita datatyyppejä ämpäreissä. On kuitenkin suositeltavaa tallentaa SD Connect -data erillisiin ämpäreihin ja kansioihin, jotta eri datatyypit eivät sekoitu.

2. Suunnittele tarvittavien kansioiden määrä

SD Connect perustuu pilvipohjaiseen objektitallennusinfrastruktuuriin. Tiedostoja voidaan ladata palveluun vain SD Connectilla luotuihin ylätason eli pääkansioihin: ylätason "säiliöön tai ämpäriin", jota käytetään tiedostojen tai kansioiden tallentamiseen. Tällä on useita vaikutuksia siihen, miten datasi tulisi järjestää ja hallita:

Kun tiedostot on ladattu palveluun SD Connectiin, niitä ei voi enää muokata tai muuttaa. Siksi kansiorakenne on tärkeää suunnitella etukäteen. Datanhallinnan yksinkertaistamiseksi ja ongelmien välttämiseksi on suositeltavaa luoda erillinen kansio jokaiselle aineistolle tai kokeelle. Vältä sijoittamasta liian monta tiedostoa yhteen kansioon; kukin kansio voi sisältää enintään 500.000 segmentoituja tiedostoja.
Alikansioita ei tueta: Tiedostojen lataamista palveluun alikansioihin ei tueta.
Palveluun lataamisen kesto: Suurten aineistojen tai suurten erien lataaminen palveluun voi kestää useita tunteja. Palveluun lataaminen keskeytetään automaattisesti 8 tunnin jälkeen.
Tiedostojen segmentointi: Palveluun ladatut tiedostot jaetaan automaattisesti segmentteihin tallennuksen ja suorituskyvyn optimoimiseksi. Tämä segmentointi ei näy käyttöliittymässä, mutta se voi vaikuttaa suorituskykyyn.

3. Suunnittele kansioiden nimet

Kun luot kansioita SD Connectissa, yhteensopivuuden varmistamiseksi on noudatettava tiettyjä nimeämissääntöjä, mikä vaatii hieman suunnittelua.

Note

Ylätason kansion nimeä ei voi muuttaa sen jälkeen, kun se on luotu SD Connectissa. Nämä säännöt koskevat vain palvelussa luotuja ylätason kansioita, eivät paikalliselta tietokoneelta ladattuja alikansioita.

Kansion nimien täytyy:

alkaa pienellä kirjaimella tai numerolla.
olla 3–63 merkkiä pitkiä.
käyttää latinalaisia kirjaimia (a-z), numeroita (0-9) ja yhdysmerkkiä (-).
olla yksilöllisiä kaikkien SD Connectin ja Allaksen kaikkien projektien olemassa olevien kansioiden joukossa. Jos et voi luoda uutta kansiota, toinen projekti saattaa jo käyttää valitsemaasi nimeä. Tämän tilanteen välttämiseksi on hyvä käytäntö sisällyttää kansion nimeen projektikohtaisia tunnisteita (esim. projektin tunnusnumero tai lyhenne).

Kansion nimet eivät saa sisältää:

Isoja kirjaimia, alaviivaa (_) eikä aksenttimerkkejä, diakriittisiä merkkejä tai erikoismerkkejä sisältäviä kirjaimia (åäöe') ei sallita.
kaikki kansioiden nimet ovat julkisia; älä sisällytä niihin luottamuksellisia tietoja.
Kansion nimiä ei voi muuttaa jälkikäteen.

Komentorivityökalut ja automatisoitu avainten hallinta

Vaihe 1: Asenna a-tools ja sd-lock-util paikalliseen ympäristöösi

Jotta voit ladata sensitiivistä dataa palveluun SD Connectiin komentoriviltä ja salata sen automaattisesti, sinun täytyy asentaa allas-cli-utils ja sd-lock-util kannettavallesi tai paikalliseen ympäristöösi (Mac tai Linux). Asennus voi vaatia root-oikeuksia, ja tästä syystä saatat tarvita tukea organisaatiosi IT-yksiköltä.

Täältä löydät vaiheittaiset ohjeet komentojen a-commands ja sd-lock-util asentamiseen.

Note

Jos sinun täytyy ladata palveluun ei-sensitiivistä dataa (kuten skriptejä, kontteja tai ohjelmistoja käytettäväksi SD Desktopissa), huomaa, että nämä työkalut ovat saatavilla myös CSC:n supertietokoneilla (Puhti, Mahti ja LUMI). Nämä järjestelmät on kuitenkin tarkoitettu vain ei-sensitiiviselle datalle. Sensitiivinen data täytyy ladata palveluun SD Connectiin asianmukaisia kanavia pitkin.

Vaihe 2: Yhteyden avaaminen SD Connectiin

Jotta voit avata SD Connect -yhteensopivan Allas-yhteyden, sinun täytyy lisätä määrityskomennolle valinta --sdc. CSC:n supertietokoneilla yhteys avataan komennoilla:

module load allas
allas-conf --sdc

Paikallisissa asennuksissa yhteys avataan yleensä seuraavan kaltaisilla komennoilla

export PATH=/some-local-path/allas-cli-utils:$PATH
source /some-local-path/allas-cli-utils/allas_conf -u your-csc-account --sdc

Määritysprosessi kysyy ensin CSC-salasanasi (Haka- tai Virtu-salasanoja ei voi käyttää tässä). Sen jälkeen valitset käytettävän CSC-projektin. Tämä on sama kuin tavallinen Allaksen kirjautumisprosessi.
SD Connectin tapauksessa prosessissa on ylimääräinen vaihe, jossa sinua pyydetään antamaan SD Connect API -token.

Väliaikaisen SD Connect API -tokenin hakeminen:

Kirjaudu SD Connectin selainkäyttöliittymään. Jos sinulla on useita CSC-projekteja, varmista, että olet valinnut saman SD Connect -projektin sekä komentorivillä että selainkäyttöliittymässä (vasen yläkulma).
Napsauta selainkäyttöliittymän oikeasta yläkulmasta Support ja valitse sitten pudotusvalikosta Create API Token.
Anna uudessa valintaikkunassa nimi väliaikaiselle tokenillesi. Vältä erikoismerkkien käyttöä tokenin nimessä.
Napsauta Create Token. Token näytetään vain kerran. Kun näet tokenin, kopioi se (napsauta tokenin vasemmalla puolella olevaa kuvaketta). Tärkeää: varmista, että säilytät sen turvallisesti, sillä sitä ei voi hakea myöhemmin uudelleen.
Token on voimassa 24 tuntia, ja se poistetaan automaattisesti tämän ajan jälkeen. Liitä token komentoriville ja paina Enter käyttääksesi sitä.

SD Connect -yhteensopiva Allas-yhteys on nyt voimassa seuraavat kahdeksan tuntia. Voit käyttää komentoja kuten a-list ja a-delete sekä tavallisten Allas-objektien että SD Connect -objektien hallintaan.

Vaihe 3: Datan lataaminen palveluun ja automaattinen salaus

Dataa voidaan ladata palveluun SD Connectiin komennolla a-put käyttäen valintaa --sdc. Esimerkiksi tiedoston my-secret-table.csv lataamiseen palveluun sijaintiin 2000123-sens/dataset2 Altaassa käytä komentoa:

a-put --sdc my-secret-table.csv -b 2000123-sens/dataset2

Tämä tuottaa SD Connect -objektin: 2000123-sens/dataset2/my-secret-table.csv.c4gh

Myös kaikkia muita a-put-komennon valintoja ja ominaisuuksia voidaan käyttää. Esimerkiksi hakemistot tallennetaan tar-tiedostoina, jos valintaa --asis ei käytetä.

Komento:

a-put --sdc my-secret-directory -b 2000123-sens/dataset2

tuottaa SD Connect -objektin: 2000123-sens/dataset2/my-secret-directory.tar.c4gh

Massiivisiin datan palveluun latauksiin voit käyttää komentoa sd-lock-util lock. Esimerkiksi voit ladata paikallisen hakemiston dataset3 palveluun ämpäriin 2000123-sens komennolla:

sd-lock-util lock dataset3 --container 2000123-sens --progress

sd-lock-util ei tallenna hakemistoa tar-arkistotiedostona. Sen sijaan kaikki hakemiston tiedostot tallennetaan yksittäisinä objekteina, jotka nimetään hakemiston sijainnin mukaan.

Voit käyttää valintaa --prefix määrittääksesi tietyn sijainnin kohdeämpärin sisällä:

sd-lock-util lock dataset3 --container 2000123-sens --prefix case-study2 --progress

Note

Älä käytä erikoismerkkejä tai välilyöntejä ämpärin nimessä.

Note

Sen jälkeen kun SD Connect päivitettiin lokakuussa 2024, Allakseen/SD Connectiin tallennetun salatun .c4gh-tiedoston käyttämän salausmenetelmän määrittäminen ei ole enää suoraviivaista. Jos käytät nyt uutta salausmenetelmää tiedostojen lataamiseen palveluun olemassa olevaan CSC-projektiin, varmista, että lisäät kansioihisi huomautuksen siitä, että salausprotokolla on muuttunut. Voit joko jakaa tämän tiedon kollegoillesi tai sisällyttää sen selkeästi kansion nimeen. Hyvänä käytäntönä suosittelemme uuden kansion luomista ja eri menetelmillä salattujen tiedostojen sekoittamisen välttämistä.

Vaihe 4: Datan lataaminen palvelusta ja automaattinen salauksen purku

Dataa voidaan ladata palvelusta SD Connectista komennolla a-get. Jos SD Connect -yhteys on käytössä, a-get yrittää automaattisesti purkaa niiden objektien salauksen, joiden pääte on .c4gh.

Esimerkiksi komento:

a-get 2000123-sens/dataset2/my-secret-table.csv.c4gh

tuottaa paikallisen tiedoston: my-secret-table.csv

Ja vastaavasti komento:

a-get 2000123-sens/dataset2/my-secret-directory.tar.c4gh

tuottaa paikallisen hakemiston: my-secret-directory

Suuria latauksia palvelusta varten voit käyttää komentoa sd-lock-util unlock. Koko ämpärin lataamiseen palvelusta voit käyttää komentoa:

sd-lock-util unlock --container bucket-name --progress

Kuten palveluun lataamisen tapauksessa, valintaa --prefix voidaan käyttää valitsemaan osa ämpärin sisällöstä. Esimerkiksi jos haluat ladata palvelusta ämpäristä 2000123-sens vain objektit, joiden nimet alkavat merkkijonolla case-study2, voit käyttää komentoa:

sd-lock-util unlock --container 2000123-sens --prefix case-study2 --progress

Huomaa, että automaattinen salauksen purku a-get- tai sd-lock-util-komennolla toimii vain tiedostoille, jotka on tallennettu uudella SD Connectilla, joka otettiin käyttöön lokakuussa 2024.

Vanhojen SD Connect -tiedostojen ja muiden Crypt4gh-salattujen tiedostojen kohdalla sinun täytyy edelleen käyttää a-get-komentoa ja antaa vastaava salainen avain valinnalla --sk

a-get --sk my-key.sec  2000123-sens/old-data/sample1.txt.c4gh

Valitettavasti ei ole helppoa tapaa tietää, mitä salausmenetelmää SD Connectiin tallennetussa .c4gh-tiedostossa on käytetty.

Komentorivityökalut ja manuaalinen salauksen purku

Tässä luvussa käsitellään niiden Crypt4GH-salattujen tiedostojen salauksen purkamista, jotka eivät ole yhteensopivia nykyisen SD Connect -version kanssa. Näissä tapauksissa automaattinen salauksen purku ei toimi. Sen sijaan data täytyy ensin ladata palvelusta paikalliselle tietokoneellesi, minkä jälkeen salaus puretaan komennolla crypt4gh tai Crypt4GH:n graafisella käyttöliittymällä.

Tyypillisiä tilanteita, joissa tätä manuaalista salauksen purkua tarvitaan, ovat tiedostot, jotka on tallennettu SD Connectiin vanhalla protokollalla, sekä tiedostot, jotka on viety SD Desktopista.

Näissä tapauksissa on pakollista, että sinulla on pääsy salaiseen avaimeen (jota kutsutaan usein yksityiseksi avaimeksi), joka vastaa datan salaamiseen käytettyä julkista avainta.

Tässä osiossa käsitellään vain niiden tiedostojen lataamista palvelusta ja salauksen purkua, jotka on ladattu palveluun komentoriviltä omalla salausavainparilla. Jos haluat salata ja ladata tiedostoja palveluun komentoriviltä, katso tämä ohje, jossa havainnollistetaan crypt4gh-työkalun käyttöä tiedostojen lataamiseen palveluun Allakseen (näkyy SD Connectissa).

2.1 Valmistelu

Voit käyttää mitä tahansa Allas-yhteensopivaa työkalua salattujen tiedostojen lataamiseen palvelusta Allaksesta. Yleisesti käytettyjä komentorivityökaluja ovat:

Allas-yhteensopivan työkalun lisäksi tarvitset Crypt4GH Encryption Utilityn. Crypt4GH on kirjoitettu Pythonilla. Python 3.6+ vaaditaan. Jos tarvitset apua Pythonin asentamisessa, seuraa näitä ohjeita.

Asenna Crypt4GH-salauksen komentorivityökalu. Voit asentaa Crypt4GH:n suoraan pip-työkalulla:
```
pip install crypt4gh
```
tai, jos haluat käyttää uusimpia lähdekoodeja GitHubista:
```
pip install -r crypt4gh/requirements.txt pip install ./crypt4gh
```
tai jopa:
```
pip install git+https://github.com/EGA-archive/crypt4gh.git
```

Tavallinen -h-valinta näyttää työkalun hyväksymät eri vaihtoehdot:

$ crypt4gh -h
Utility for the cryptographic GA4GH standard, reading from stdin and outputting to stdout.

Usage:
   crypt4gh [-hv] [--log <file>] encrypt [--sk <path>] --recipient_pk <path> [--recipient_pk <path>]... [--range <start-end>] [--header <path>]
   crypt4gh [-hv] [--log <file>] decrypt [--sk <path>] [--sender_pk <path>] [--range <start-end>]
   crypt4gh [-hv] [--log <file>] rearrange [--sk <path>] --range <start-end>
   crypt4gh [-hv] [--log <file>] reencrypt [--sk <path>] --recipient_pk <path> [--recipient_pk <path>]... [--trim] [--header-only]

Options:
   -h, --help             Prints this help and exit
   -v, --version          Prints the version and exits
   --log <file>           Path to the logger file (in YML format)
   --sk <keyfile>         Curve25519-based Private key
                        When encrypting, if neither the private key nor C4GH_SECRET_KEY are specified, we generate a new key 
   --recipient_pk <path>  Recipient's Curve25519-based Public key
   --sender_pk <path>     Peer's Curve25519-based Public key to verify provenance (akin to signature)
   --range <start-end>    Byte-range either as  <start-end> or just <start> (Start included, End excluded)
   -t, --trim             Keep only header packets that you can decrypt
   --header <path>        Where to write the header (default: stdout)
   --header-only          Whether the input data consists only of a header (default: false)

Environment variables:
   C4GH_LOG         If defined, it will be used as the default logger
   C4GH_SECRET_KEY  If defined, it will be used as the default secret key (ie --sk ${C4GH_SECRET_KEY})

Saatat huomata, että crypt4gh käyttää yksityisestä avaimesta valintaa --sk. Tämä voi tuntua oudolta, mutta ilmeisesti crypt4gh käyttää termiä secure key yksityisestä avaimesta, mistä tulee sk, ja vastaavasti pk viittaa julkiseen avaimeen yksityisen avaimen sijaan.

2.2 Lataa tiedosto palvelusta ja pura sen salaus

Tiedoston salauksen purkamiseen tarvitset salaisen avaimen, joka vastaa yhtä salausvaiheessa käytetyistä julkisista avaimista. Oletetaan esimerkissämme, että olet purkamassa tiedoston dog.jpg salausta, jonka olet salannut SD Desktopissa avaimella groupA-pub ja vienyt sen jälkeen ämpäriin 2000123-export. Tiedoston hakemiseksi paikalliselle tietokoneellesi voit tehdä sekä lataamisen palvelusta että salauksen purun komennolla a-put.

a-get --sk groupA.sec 2000123-export/dog.jpg.c4gh

Yllä oleva komento kysyy avaintiedoston salasanan, minkä jälkeen se lataa datan palvelusta ja purkaa sen salauksen.

Vaihtoehtoisesti voit käyttää esimerkiksi rclonea datan lataamiseen palvelusta:

rclone copy allas:2000123-export/dog.jpg.c4gh ./dog.jpg.c4gh

Sen jälkeen käytä komentoa crypt4gh decrypt salauksen purkamiseen:

crypt4gh decrypt --sk groupA.sec <dog.jpg.c4gh >dog.jpg

Komento crypt4gh käyttää vain vakiotuloa (stdin) ja vakiotulostetta (stdout), joten sinun täytyy käyttää komentotulkin uudelleenohjauksia: < tarkoittaa syötetiedostoa ja > tulostiedostoa, joten <dog.jpg.c4gh lukee salatun tiedoston nimeltä dog.jpg.c4gh ja >dog.jpg kirjoittaa puretun tiedoston nimeltä dog.jpg.

Komento pyytää käyttäjää syöttämään salaisen avaimesi salasanan (passphrase). Turvallisuussyistä salasanaa ei näytetä, kun kirjoitat sitä.

Jos sinun täytyy purkaa suuren määrän Crypt4GH-salattuja tiedostoja, voit katsoa ohjeen, jossa kuvataan, miten kaikki hakemiston tiedostot voidaan purkaa

Note

Jos purat tiedoston salauksen SD Desktopissa ja salauksessa on käytetty CSC Sensitive Data -julkista avainta, salauksen purku tehdään automaattisesti eikä sinun tarvitse määrittää salauksen purkuavaimia. Jos sinun täytyy purkaa suuri määrä tiedostoja, katso ohje Kaikkien hakemiston tiedostojen salauksen purkaminen.

Lisätietoja datan salauksesta.

Komentorivikäyttöliittymä ja automatisoitu avainten hallinta

1. Taustatiedot

2. Suunnittele tarvittavien kansioiden määrä

3. Suunnittele kansioiden nimet

Komentorivityökalut ja automatisoitu avainten hallinta

Vaihe 1: Asenna a-tools ja sd-lock-util paikalliseen ympäristöösi

Vaihe 2: Yhteyden avaaminen SD Connectiin

Vaihe 3: Datan lataaminen palveluun ja automaattinen salaus

Vaihe 4: Datan lataaminen palvelusta ja automaattinen salauksen purku

Komentorivityökalut ja manuaalinen salauksen purku

2.1 Valmistelu

2.2 Lataa tiedosto palvelusta ja pura sen salaus

Ohjeet

SD Connectin ominaisuudet