spec: adds transmit & receive apdu docs

[mikaelbr]

Proposal: APDU commands

Adds transmit/receive message specification for APDU commands. Can be used for reading and writing values to travel cards and other NFC entities.

Context and known limitations

Currently missing references to documentation on relevant APDU commands.

---

Checklist

• [x] Includes documentation file with description, topics and examples.
• [x] Includes JSON Schema
• [x] Includes passing and failing tests.

Required fields

• [x] traceId is unique ID (UUID v4) that is created when message is sent. Meaning traceId is unique per message.
• [x] eventTimestamp is in UTC (RFC3339 format), created when the actual event is triggered not when it is sent.

Confirmed and verified by parties

• [ ] MT Buss
• [ ] Consat
• [ ] Fara

[skjolber]

Se diverse klasser som brukes i denne pakken.

For hver adpu-kommando bør vi vel vurdere å ha

• valgfri håndtering av AF (additional frame / mer data)
• hva forventet svar er
• om svaret skal kommuniseres tilbake

I tillegg gjør vi i dag en greie der vi resetter kortet før en kommandoserie. Dette er mest for å forenkle tilstanden til kortet når vi gjør lokal lesning og deretter kobler på serverside.

[mikaelbr]

Jeg kan ikke mye om APDU her, så spør mest for å skjønne: Vil ikke håndtering av AF kunne håndteres av devices slik at det som sendes over er resultatet av kommandoen som om AF ikke skulle ha forekommet? Eller er det hensiktsmessig å faktisk sende det over til MT Buss?

[mikaelbr]

om svaret skal kommuniseres tilbake

Hvilke tilfeller er det det ikke skal kommuniseres tilbake? Er det performance grep eller sikkerhet?

[mikaelbr]

@skjolber Hva er forventet oppførsel dersom det ikke stemmer med expected result? Er poenget å sende det som round trip for stateless håndtering av klienten?

[skjolber]

AF håndteres på to måter for Desfire-EV1-kort, så det er ikke så godt å abstrahere det bort. Så AF kan være avhengig av konteksten med andre ord.

[skjolber]

om svaret skal kommuniseres tilbake

Hvilke tilfeller er det det ikke skal kommuniseres tilbake? Er det performance grep eller sikkerhet?

Tenkte mest at det er uinteressant i den forstand at man har sendt med forventet svar allerede, og hvis det samsvarer så er svaret kjent. Men kanskje det er enklere å si at svar alltid skal tilbake.

[mikaelbr]

Men kanskje det er enklere å si at svar alltid skal tilbake

Jeg ser på det som en fordel å ha simpelhet i modeller i alle fall. Kan være det ikke trengs, men da kan det ignoreres. Så lenge det ikke har en massiv impact på performance pga overføring (som jeg tviler sterkt på at det har) så tror jeg verdien av konsistens er viktigere

[skjolber]

@skjolber Hva er forventet oppførsel dersom det ikke stemmer med expected result?

Gode råd er gjerne dyre hvis man ikke får svarene man forventer, det vil da være applikasjonsspesifikt om man er i en ukjent tilstand eller ikke, eller om det har noe for seg å sende resten av kommandoene.

Eksempel: Les 3 filer fra kortet. Fil 1 finnes ikke, skal man da lese fil 2 og 3?

Er poenget å sende det som round trip for stateless håndtering av klienten? Litt usikker på spørsmålet, men man ønsker gjerne kunne kjøre så flere kommandoer som per meldingsutveksling.

[Topguy]

Slik vi implementerte det for AtB så håndterte vi 0xAF responsen ( som er veldig Desfire spesifik ) automatisk og i tillegg hadde vi en sjekk for unntaket ( Autentisering ).

I en generell løsning kan det være relevant å ha med en "apduType" i requesten som f.eks kan være "desfire-native" eller "iso7816". Logikken rundt håndtering av svar kan da splittes:

desfire-native: En byte "expected-status" sendes med hver APDU ( kan være tom ) men refererer kun til status byte som er første byte i responsen ifra Desfire kortet. Hvis expected-status = 0x00 (eller tom) så håndteres "0xAF" automatisk og det returneres et konkatinert array Hvis expected-status = 0xAF så håndteres ikke 0xAF automatisk og svaret returneres med 0xAF som status.

iso7816: To bytes "expected status". ( kan være tom ) Status bytene er da de to siste bytene i svaret ifra kortet. Og typisk er de 0x90 0x00 når alt er OK.

Generelle regler: Alle svar sendes. Et tomt repons-array vil indikere at vi har mistet kontakten med kortet. Hvis "expected-status" er tom så avbrytes ikke sekvensen uansett motatt status.

[mikaelbr]

@Topguy Send gjerne et forslag med eksempel på payload i hvordan det kan se ut

[Topguy]

{
    "traceId":"40012a1d-ca90-435b-9418-78416e873421",
    "apduType":"desfire"
    "commands":[
        {"commandId":1,"frame":"WgCAVw==","expStatus":"0x00"},
        {"commandId":2,"frame":"vQwAAAAQAAA=","expStatus":"0x00"},
        {"commandId":3,"frame":"WgGAVw==","expStatus":"0x00"},
        {"commandId":4,"frame":"Cgc=","expStatus":"0xAF"}
    ]
}

[mikaelbr]

Kommando frames i hex

[sijangurung]

MtBuss har ikke så mye input her, men følge med

[mikaelbr]

Ang continue-flagg, fra @skjolber :

Litt mer bakgrunn: Kombinasjonen leser og kort har en visst såkalt max transcieve length, som styrer lengden på command og response. Så en typisk situasjon der man vil lese en hel fil så må det noen ganger deles opp i flere kommandoer. Uten AF-håndtering må man vite om denne grensen, per kort / leser (denne kan mest trolig leses av, men har ikke prøvd ut dette i særlig grad). For desfirekort er det lagt opp til at antall response-meldinger ikke påvirker bruken av checksum/kryptering, så i praksis trenger man ikke vite om max transcieve length, evt forholde seg til en minimumsverdi for kompatiblitet på kryss av flere systemer, hvis man bare, i de fleste situasjoner, ber kortet om mer data når AF dukker opp.