Vous êtes sur la page 1sur 59

CARDPEEK 0.

8 Reference Manual

Alain Pannetrat <L1L1@gmx.com> September 2013

Table of Contents
Chapter 1 Presentation..............................................................................................................5 Chapter 2 Installation................................................................................................................7 2.1 Co pilin! an" installin! un"er #inu$............................................................................7 2.2 Co pilin! an" installin! un"er Mac %& '....................................................................8 2.( Installin! un"er )in"o*s..............................................................................................8 2.+ Relate" files an" initial setup.........................................................................................8 2.+.1 Default installation..................................................................................................8 2.+.2 Chan!in! the "efault installation "irector,............................................................2.5 Choosin! a s art car" rea"er.........................................................................................Chapter ( .sin! Car"pee/.......................................................................................................11 (.1 0uic/ start.......................................................................................................................11 (.2 .ser interface.................................................................................................................12 (.( Car" 1ie*.......................................................................................................................12 (.+ 2he rea"er ta3................................................................................................................1( (.5 2he lo!s ta3....................................................................................................................1+ (.4 2he one5line co an" input fiel"...............................................................................1+ (.7 Car"5rea"er selection upon start5up.............................................................................1+ Chapter + Car" anal,sis tools..................................................................................................15 +.1 Atr...................................................................................................................................15 +.1.1 %1er1ie*..................................................................................................................15 +.1.2 6eneral notes..........................................................................................................14 +.2 7el!ian eID....................................................................................................................14 +.2.1 %1er1ie*.................................................................................................................14 +.2.2 6eneral notes.........................................................................................................14 +.( Cal,pso...........................................................................................................................14 +.(.1 %1er1ie*.................................................................................................................17 +.(.2 I ple entation notes............................................................................................17 +.+ e 1.................................................................................................................................17 +.+.1 %1er1ie*.................................................................................................................17 +.+.2 I ple entation notes...........................................................................................18 +.5 e5passport......................................................................................................................18 +.5.1 %1er1ie*.................................................................................................................18 +.5.2 I ple entation notes...........................................................................................18 +.4 6&M8&IM.......................................................................................................................1+.4.1 %1er1ie*.................................................................................................................1+.4.2 6eneral notes.........................................................................................................1+.7 oneo.............................................................................................................................1+.7.1 %1er1ie*.................................................................................................................1+.7.2 I ple entation notes............................................................................................1-

+.8 1itale 2............................................................................................................................1+.8.1 %1er1ie*.................................................................................................................1+.8.2 9otes.......................................................................................................................1+.- A""in! ,our o*n scripts...............................................................................................1Chapter 5 Pro!ra in! Car"pee/ scripts..............................................................................21 5.1 5.1 :ello *orl"...............................................................................................................21 5.2 7asic co unication *ith a s art car"......................................................................22 5.( Representin! car" "ata in a tree structure...................................................................2+ Chapter 4 De1elop ent li3rar,...............................................................................................24 4.1 2he 3it li3rar,................................................................................................................24 4.1.1 3it.A9D...................................................................................................................24 4.1.2 3it.%R.....................................................................................................................24 4.1.( 3it.'%R...................................................................................................................24 4.1.+ 3it.&:#....................................................................................................................27 4.1.5 3it.&:R...................................................................................................................27 4.2 2he 3,tes li3rar,............................................................................................................27 4.2.1 %perators on 3,testrin!s.......................................................................................28 4.2.2 3,tes.clone.............................................................................................................28 4.2.( 3,tes.concat...........................................................................................................24.2.+ 3,tes.con1ert..........................................................................................................24.2.5 3,tes.for at...........................................................................................................(0 4.2.4 3,tes.!et.................................................................................................................(0 4.2.7 3,tes.ipairs.............................................................................................................(1 4.2.8 3,tes.is;printa3le..................................................................................................(1 4.2.- 3,tes.ne*...............................................................................................................(2 4.2.10 3,tes.ne*;fro ;chars........................................................................................(2 4.2.11 3,tes.pa";left.......................................................................................................(( 4.2.12 3,tes.pa";ri!ht....................................................................................................(( 4.2.1( 3,tes.re1erse.........................................................................................................(( 4.2.1+ 3,tes.set................................................................................................................(+ 4.2.15 3,tes.su3...............................................................................................................(+ 4.2.14 3,tes.tonu 3er....................................................................................................(5 4.2.17 3,tes.*i"th...........................................................................................................(5 4.( 2he asn1 li3rar,.............................................................................................................(5 4.(.1 asn1.ena3le;sin!le;3,te;len!th...........................................................................(4 4.(.2 asn1.<oin.................................................................................................................(4 4.(.( asn1.split.................................................................................................................(7 4.(.+ asn1.split;len!th....................................................................................................(7 4.(.5 asn1.split;ta!.........................................................................................................(7 4.+ 2he car" li3rar,.............................................................................................................(8 4.+.1 car".connect...........................................................................................................(8 4.+.2 car"."isconnect......................................................................................................((

4.+.( car".!et;"ata.........................................................................................................(4.+.+ car".info.................................................................................................................(4.+.5 car".last;atr..........................................................................................................+0 4.+.4 car". a/e;file;path.............................................................................................+0 4.+.7 car".rea";3inar,....................................................................................................+1 4.+.8 car".rea";recor"...................................................................................................+2 4.+.- car".select..............................................................................................................+( 4.+.10 4.+.10 car".sen"...................................................................................................++ 4.+.11 4.+.11 car".*ar ;reset........................................................................................++ 4.5 2he cr,pto li3rar,..........................................................................................................++ 4.5.1 cr,pto.create;conte$t............................................................................................++ 4.5.2 cr,pto."ecr,pt........................................................................................................+4 4.5.( cr,pto."i!est..........................................................................................................+4 4.5.+ cr,pto.encr,pt........................................................................................................+4 4.5.5 cr,pto. ac..............................................................................................................+7 4.4 2he no"es li3rar,..........................................................................................................+7 4.4.1 no"es.appen".........................................................................................................+7 4.4.2 no"es.attri3utes.....................................................................................................+8 4.4.( no"es.chil"ren.......................................................................................................+4.4.+ no"es.fin"..............................................................................................................+4.4.5 no"es.fin";first.....................................................................................................50 4.4.4 no"es.fro ;$ l....................................................................................................50 4.4.7 no"es.!et;attri3ute................................................................................................51 4.4.8 no"es.parent...........................................................................................................51 4.4.- no"es.re o1e.........................................................................................................51 4.4.10 no"es.root............................................................................................................52 4.4.11 no"es.set;attri3ute..............................................................................................52 4.4.12 no"es.to;$ l........................................................................................................5( 4.7 2he ui li3rar,.................................................................................................................5( 4.7.1 ui.=uestion..............................................................................................................5( 4.7.2 ui.rea"line..............................................................................................................5+ 4.7.( 4.4.12 ui.loa";1ie*................................................................................................5+ 4.7.+ ui.sa1e;1ie*...........................................................................................................5+ 4.8 2he lo! li3rar,...............................................................................................................55 4.8.1 lo!.print..................................................................................................................55 4.- %ther li3raries...............................................................................................................55 4.-.1 2he treefle$ li3rar,.................................................................................................55 4.-.2 2he countr,;co"es an" currenc,;co"es li3raries...............................................55 4.-.( 2he en15+5 li3rar,.................................................................................................55 Chapter 7 >ile for at...............................................................................................................57 Chapter 8 #icense....................................................................................................................5-

Chapter 1
Presentation

CARDPEEK is a pro!ra that rea"s the contents of s art car"s. 2his open5source tool has a 62K 6.I an" can 3e e$ten"e" *ith the #.A pro!ra in! lan!ua!e. It re=uires a PC&C car" rea"er to co unicate *ith a s art car"? either in contact or contactless o"e. & art car"s are 3eco in! u3i=uitous in our e1er,"a, life. )e use the for pa, ent? transport? in o3ile telephones an" an, other applications. 2hese car"s often contain a lot of personal infor ation such as? for e$a ple? our last purchases or our last <ourne,s in pu3lic transport. CARDPEEK@s !oal is to allo* ,ou to access all this personal infor ation. As such? ,ou can 3e 3etter infor e" a3out the "ata that is collecte" a3out ,ou. CARDPEEK e$plores I&% 7814 co pliant s art car"s an" represents their content in an or!aniAe" tree for at that rou!hl, follo*s the structure it has insi"e the car"? *hich is also si ilar to a classical file5s,ste structure. As of 1ersion 0.8? this tool is capa3le of rea"in! the contents of the follo*in! t,pes of car"sB EMC Dchip an" PI9D 3an/ car"s? inclu"in!B CI&A? MasterCar"? C7 an" .K Post %ffice Account contact car"sE Pa,)a1e FCI&AG an" Pa,Pass FMasterCar"G contactless car"sE Electronic87io etric passports? *hich ha1e an e 3e""e" contactless chipE 2he 7el!ian eID car"E Calypso transport car"s inclu"in!B Na igo transport car"s use" in ParisE M%7I7 car"s use" in 7russelsE Ra1Ka1 car"s use" in IsraelE 6&M &IM car"s F*ithout .&IM "ata use" in recent car"sGE 5

Chapter 1 Presentation

Citale 2? the >rench health car". Moneo? the >rench electronic purseE &o e Mifare Classic co pati3le car"s Fsuch as the 2hal,s car"GE

It can also rea" the follo*in! car"s *ith li ite" interpretation of "ataB &o e i portant car" t,pes are issin! or nee" further "e1elop ent? ho*e1er? this application can 3e o"ifie" an" e$ten"e" easil, to ,our nee"s *ith the e 3e""e" #.A scriptin! lan!ua!e. >or ore infor ation on the #.A pro<ect see http://www.lua.org/. 2his soft*are has 3een teste" *ith tra"itional PC&C car" rea"ers Fsuch as the 6e altoH PC 2)I9G as *ell as contactless or "ual5interface PC&C rea"ers Fsuch as the % ni/e,H 5(21G.

Chapter 1 Presentation

Chapter 2 Installation

CARDPEEK is "esi!ne" to *or/ un"er 69.8#inu$ *ith 62KI an" has 3een successfull, porte" un"er )in"o*s. CARDPEEK can 3e co pile" fro source usin! configure a n " make. It is 3ein! "e1elope" un"er #inu$ De3ian an" has 3een reporte" to *or/ un"er .3untu? Centos? >e"ora? &use an" >ree7&D? as *ell as Rasp3ian on the Rasp3err, Pi. 2he )in"o*s 1ersion is "istri3ute" as a self installin! 3inar, pac/a!e. It can also 3e co pile" un"er Min6)8M&J& *ith the custo Ma/efile pro1i"e" in the source co"e FMakefile.win32G. %f course? a s art car" rea"er is nee"e" to ta/e full a"1anta!e of this soft*are.

2.1 Compiling and installing under Linux


InstructionsB 1. Ma/e sure ,ou ha1e the follo*in! "e1elop ent pac/a!es installe"B li3!t/I (.0? 1ersion (.5.+ or a3o1e Fhttp://www.gtk.orgG li3!li3 2.0? 1ersion 2.(2 or a3o1e. li3lua 5.2 Fhttp://www.lua.orgG li3pcsclite Fhttp://pcsclite.alioth.debian.org/G li3ssl Fhttp://www.openssl.org/G li3curl Fhttp://libcurl.orgG

2. .npac/ the source if nee"e" an" chan!e "irector, to the source "irector,. (. 2,pe K./configure@ +. 2,pe Kmake@ 5. 2,pe Kmake install@ Fusuall, as rootG to install install CARDPEEK in the proper

Chapter 2 Installation

s,ste 9otesB

"irectories.

1. %n a De3ian8.3untu s,ste ? these necessar, pac/a!es are all a1aila3le throu!h pac/a!e ana!e ent tools such as apt/aptitude. 2. 2he last step Fmake installG is optional? as ,ou can run CARDPEEK "irectl, fro the source "irector,.

2.2 Compiling and installing under Mac OS


&tartin! fro 1ersion 0.8? CARDPEEK shoul" co pile on Mac %& ' follo*in! the sa e steps outline" for #inu$. 9ote ho*e1er that this re=uires settin! up the correct "e1elop ent en1iron ent an" an '11 ser1er F'=uartAG. Car"pee/ has nota3l, 3een successfull, co pile" un"er Mac %& ' #ion F10.7.5G *ith the follo*in! tools8en1iron entB 1. 'co"e +.4.2 Co an" #ine 2ools. 2. :o e3re* Fhttp://mxcl.github.io/homebrew/G? use" to install li3!t/I? li3lua an" li3ssl. (. '0uartA Fhttp://xquartz.macosforge.org/G.

2.! Installing under "indo#s


CARDPEEK *or/s 3oth on *in"o*s (23its an" 4+3its platfor s? in (2 3it co pati3ilit, o"e. InstructionsB 1. Do*nloa" the self installin! 3inar, setup pro!ra 2. >ollo* the instructions. CARDPEEK can also 3e co pile" fro source *ith Min6)8M&J&? 3ut this is a ore co plicate" approach "ue to so e current shortco in!s of the *in"o*s port. Jou shoul" use the "e"icate" Ma/efile Fmake -f Makefile.win32) an" anuall, cop, the contents of the "irector, dot_cardpeek_dir/ fro %/.cardpeekG. the source into the "irector, %USE ! "#$%E F cardpeek-x.xx-win32setup.exe *here x.xx is the 1ersion nu 3er of CARDPEEKG.

2.$ %elated files and initial setup


2.$.1
&efault installation

In the follo*in! "iscussion? the ter s Lho e "irector,M *ill refer to the tra"itional ho e "irector, on a .ni$ s,ste Fas in"icate" 3, the &'"ME en1iron ent 1aria3leG or the %USE ! "#$%E% "irector, on a M&5)in"o*s s,ste s. 2he first ti e CARDPEEK is run it Chapter 2 Installation 8

*ill atte pt to create the .cardpeek/ "irector, in ,our ho e "irector,. 2his is nor al. >or )in"o*s users this "irector, *ill 3e create" "urin! installation. 2h e ./cardpeek "irector, *ill contain 5 ele entsB cardpeekrc.lua? config.lua? the scripts/ an" repla(/ "irectories an" a version file. 2he cardpeekrc.lua allo*s ,ou to run co an"s auto aticall, *hen the pro!ra starts an" the config.lua file is use" to store confi!uration infor ation. 2he scripts/ "irector, contains all the scripts nee"e" to e$plore s art car"s. 2hese scripts are #.A files Fsuch as L em).luaM or Lcal(pso.luaMG an" all sho* up in the Kanal,Aer@ the enu of CARDPEEK F*ithout their e$tension K.lua@G. If ,ou a"" an, #.A file to this "irector,? it *ill therefore also appear in enu. 2he scripts/ "irector, contains three su3"irectoriesB li*/, etc/ an" an"s or cal(pso/. li*/ an" etc/ hol" a fe* #.A files containin! fre=uentl, use" co

"ata ite s that are share" a on! the car" processin! scripts. 2he "irector, calypso/ hol"s countr, an" re!ion specific scripts for cal,pso car"s. 2he repla(/ "irector, is use" to sa1e "ata for car" e ulation purposes. Each ti e the pro!ra runs? it creates a file .cardpeek.log in ,our ho e "irector,. essa!es "ispla,e" in the Llo!M ta3 of the application Fsee 2his file contains a cop, of the ne$t chapterG.

2.$.2

Changing the default installation director'

.n"er .ni$5li/e s,ste s? if ,ou *ant to chan!e the "irector, use" 3, CARDPEEK to store an" rea" scripts fro &'"ME/.cardpeek to so ethin! else? ,ou a, "o so 3, settin! the en1iron ent 1aria3le +, -!EE._-$ to point to an e$istin! alternati1e "irector, of ,our choice.

2.( Choosing a smart card reader


2here are an, s art car" rea"ers a1aila3le on the ar/et? an" their co pati3ilit, *ith "ifferent contact or contactless car"s *ill "epen" on an, para eters? such asB 2he %& ,ou are usin! F#inu$? )in"o*s? (23it or 4+3it? etc.G 2he s art car" "ri1er on the %&. 2he fir *are of the s art car" rea"er. 2he s art car" itself.

As an e$a ple? the %M9IKEJ 5(21 .&7 "ual5interface rea"er co es into at least 2 fir *are 1ersions. .n"er M& )in"o*s? a rea"er *ith fir *are 5.10 fails to connect *ith so e Cal,pso e5tic/etin! car"s throu!h the contact interface? 3ut *or/s un"er #inu$ *ith "efault PC&C "ri1ers. :o*e1er? on #inu$? the contactless interface onl, see s to *or/ *ith the %M9IKEJ "ri1ers an" fail to operate *ith the PC&C stan"ar" "ri1ers. 7ecause of all these reasons? to our 3est /no*le"!e there is no perfect s art car" rea"er. Chapter 2 Installation -

2he follo*in! s art car" rea"ers ha1e 3een reporte" to *or/ *ith CARDPEEK an" are pro1i"e" here as an in"ication F*ithout an, !uarant,GB %eader
7R%ADC%M 7CM5880 6EMA#2% PC 2*in .&7 %M9IKEJ 5(21 .&7

T'pe
Contact Contact Contact N contactless

)otes
!nly on "in#o$s. % &or Na igo car#s' t(e !mni)ey proprietary #ri er #oesn*t $or). +o$e er t(e #e,a-lt PCSC #ri er seems to $or) on Lin-x. % !,,ere# ,or . e-ros in s-b$ay stations in Paris.

&PRI96CARD Pro$O9ORoll PC8&C Contactless )A2C:DA2A )1-81 Contact

Chapter 2 Installation

10

Chapter ! *sing C+%&P,,-

0ll-stration 11 2ain "in#o$ o, CA34P556

!.1 .uic/ start


2o e$peri ent *ith CARDPEEK? ,ou a, start *ith ,our EMC LPI9 an" chipM s art car" for e$a ple? 3, follo*in! these stepsB 1. &tart CARDPEEK. 2. &elect ,our PC&C car" rea"er in the first "ialo! 3o$. (. Insert ,our EMC LPI9 an" chipM car" in the car" rea"er. +. &elect em in the analy/er Chapter ( .sin! Car"pee/ enu. 2his *ill run the "efault EMC script. 11

5. Cie* the results in the Lcar" "ataM ta3. %n an, 3an/ car"s? ,ou *ill "isco1er a surprisin! a ount of transaction lo! "ata Fscroll "o*n to the Llo! "ataM in the car" 1ie*G.

!.2 *ser interface


2he user interface is "i1i"e" in four fiel". ain partsB ( ta3s an" a one5line co an" input

Each one of the ( ta3s proposes a "ifferent 1ie* of car" relate" infor ationB Card 0ie#1 sho*s car" "ata e$tracte" fro a car" in a structure" tree for . %eader1 sho*s ra* 3inar, "ata e$chan!e" 3et*een the host PC an" the car" rea"er. Lo gs 1 "ispla,s a <ournal of application e1ents? purposes. ainl, useful for "e3u!!in!

!.! Card 0ie#


2he card 0ie# ta3 is the central user interface co ponent of CARDPEEK. It represents the "ata e$tracte" fro a car" in a structure" tree fro . 2his tree structure is initiall, 3lan/ an" is entirel, constructe" 3, the #.A scripts that are e$ecute" Fsee C(apter 7G. 2his tree can 3e sa1e" an" loa"e" in 'M# for at F see C(apter .G usin! the 3uttons in the tool3ar. 2he card 0ie# ta3 offers the follo*in! tool3ar 3uttonsB Anal,Ae Clear %pen &a1e As A3out 0uit Clic/in! on this 3utton spa*ns a enu fro *hich a car" anal,sis script can 3e chosen Fsee next c(apter8. 2his 3utton clears the car" 1ie*. 2his 3utton allo*s to loa" a pre1iousl, sa1e" car" 1ie* fro 'M# file. an

2his 3utton allo*s to sa1e the current car" 1ie* into an 'M# file. 2his 3utton "ispla,s a 1er, 3rief 2his 3utton =uits the application. essa!e a3out CARDPEEK.

2he card 0ie# "ata is represente" in ( colu ns. 2he first colu n "ispla,s the no"es of the car" tree 1ie* in a hierarchical structure si ilar to a t,pical file "irector, tree 3ro*ser? *here each no"e has a na e? co pose" of a la3el an" an ID. 2he secon" colu n "ispla,s the siAe of the no"e "ata? ost fre=uentl, e$presse" in 3,tes. >inall,? the thir" colu n "ispla,s the no"e "ata itself. 2he no"e "ata can either 3e represente" in Lra*M Chapter ( .sin! Car"pee/ 12

Fhe$a"eci alG for or in a ore user frien"l, interprete" Lalternati1eM for ? such as a te$t? or a "ate for e$a ple. 7, "efault? the car" 1ie* *ill "ispla, no"e "ata in an interprete" Lalternati1eM for at if it e$ists. 7, clic/in! on the thir" colu n title? it is possi3le to s*itch 3et*een 3oth Lra*M an" interprete" Lalternati1eM "ata representations. 2he card 0ie# ta3 has a ri!ht5clic/ acti1ate" conte$t e$pan" all sho* ra* 1alue or sho* interprete" 1alue enu featurin! t*o co an"sB

2his e$pan"s the contents of the tree structure startin! fro the currentl, hi!hli!hte" no"e. 2his is e=ui1alent to clic/in! on on the thir" colu n title to s*itch 3et*een 3oth Lra*M an" interprete"M "ata representations.

!.$ The reader tab


2he rea"er ta3 "ispla,s the ra* 3inar, "ata e$chan!es 3et*een the car" rea"er an" the car" itself. 2his "ata is co pose" of car" co an" APD.s 1? car" response APD.s an" car" reset in"icators. Co an" APD.s are represente" 3, a sin!le 3loc/ of "ata? *hile car" responses contain t*o ele entsB a car" status *or" an" car" response "ata. %ne interestin! feature of the car" rea"er ta3 is the a3ilit, to sa1e the APD. e$chan!es 3et*een the car" rea"er an" the s art car" in a file that can later 3e use" to e ulate the car". %nce this "ata is sa1e" in a file F*ith the .clf e$tensionG an" place" in the .cardpeek/repla(/ fol"er? it *ill appear as a choice in the s art car" rea"er selection *in"o* that appears *hen CARDPEEK is launche". 2he na e of the file *ill 3e prefi$e" 3, Lreplay://M in the car" selection *in"o*. &electin! such a car" "ata file allo*s to re5run the script on the pre1iousl, recor"e" APD.8response "ata instea" of a real s art car" inserte" in the rea"er. 2his is 1er, useful for testin! an" "e3u!!in! car" scripts *ithout rel,in! on a real s art car" inserte" in the rea"er. 2he reader ta3 offers the follo*in! tool3ar 3uttonsB Connect Reset Disconnect Clear 2his 3utton esta3lishes a conne$ion 3et*een the car" an" the car" rea"er. 2his 3utton perfor s a *ar reset of the car".

2his 3utton closes the conne$ion 3et*een the car" an" the car" rea"er. 2his 3utton clears the APD.8response "ata "ispla,e" in the *in"o*.
essa!e e$chan!e" 3et*een the

1 APD.B Application Protocol Data .nit? a se=uence of 3,tes "escri3in! a s art car" an" the rea"er.

Chapter ( .sin! Car"pee/

1(

&a1e as

2his 3utton allo*s to sa1e the "ispla,e" APD.8response "ata? either &a1e as for future e$a ination or to 3e repla,e" as an e ulation of a real car".

LConnectM? LResetM an" LDisconnectM operations are usuall, auto aticall, "one 3, the car" scripts. :o*e1er? it is occasionall, useful to anuall, force the e$ecution of these co an"s.

!.( The logs tab


2he logs ta3 /eeps trac/ of essa!es e itte" 3, the application or the script 3ein! run. 2hese essa!es are useful for onitorin! an" for "e3u!!in! purposes. 2he last essa!e also appears at the 3otto of the screen in the status 3ar.

!.2 The one3line command input field


2he one5line command input fiel" at the 3otto of the *in"o* allo*s to t,pe #.A co an"s that *ill 3e "irectl, e$ecute" 3, the application. 2his is useful for testin! so e i"eas =uic/l, or for "e3u!!in! purposes.

!.4 Card3reader selection upon start3up


)hen the pro!ra choices B starts? ,ou@ll 3e as/e" to choose a car" rea"er. 2his *ill !i1e ,ou ( ain

1. Select a PCSC car# rea#er to -se1 Jou a, ha1e se1eral of PC&C car" rea"ers attache" to ,our co puter. Car"5rea"ers are usuall, i"entifie" 3, their na e? prece"e" 3, pcsc://. 2. Select a ,ile containing pre io-sly recor#e# smart car# AP49:response #ata1 2his allo*s to repla, a s art car" transaction that *as pre1iousl, recor"e" 3, CARDPEEK? an" is =uite con1enient for script "e3u!!in! purposes. Each ti e an APD. is sent to the car"? CARDPEEK *ill ans*er *ith the pre1iousl, recor"e" response "ata For return an error if the =uer, is ne*G. >iles containin! pre1iousl, recor"e" APD.8response "ata are i"entifie" 3, a file na e? prece"e" 3, replay://. (. Select ;none<1 &electin! none is useful if ,ou "o not *ish to use a car" rea"er at all? for e$a ple if ,ou onl, *ant to loa" an" e$a ine car" "ata that *as pre1iousl, sa1e" in 'M# for at.

Chapter ( .sin! Car"pee/

1+

Chapter $ Card anal'sis tools

0ll-stration 21 =(e Analy/er menAs sho*n on Illustration 2? CARDPEEK pro1i"es se1eral car" anal,sis tools? *hich all appear in the DAnal,AerD enu. 2hese tools are actuall, LscriptsM *ritten in the #.A lan!ua!e? an" CARDPEEK allo*s ,ou to a"" ,our o*n scripts easil,. 2hou!h ,ou are unli/el, to "a a!e a s art car" *ith these tools? these scripts are pro1i"e" )I2:%.2 A9J )ARRA92J.

$.1 +tr
$.1.1 O0er0ie#

2his script si pl, prints the A2R FAns*er 2o ResetG of the car". Chapter + Car" anal,sis tools 15

$.1.2

5eneral notes

2his is a 1er, 3asic script that shoul" al*a,s *or/. It atte pts to i"entif, the car" *ith an internal A2R "ata3ase Fs artcar";list.t$tG? *hich is auto aticall, up"ate" online on a re!ular 3asis. In the future this script *ill 3e enhance" *ith a ore "etaile" anal,sis of the A2R.

$.2 6elgian eI&


$.2.1 O0er0ie#

2his script anal,ses the contents of the 7el!ian eID car".

$.2.2

5eneral notes

2he car"hol"erOs picture is sho*n if a1aila3le.

$.! Cal'pso

0ll-stration 31 3ea#ing a Na igo car# >Paris8

Chapter + Car" anal,sis tools

14

$.!.1

O0er0ie#
an, cities.

2his script pro1i"es an anal,sis of Cal,pso pu3lic transport car"s use" in

$.!.2

Implementation notes

2he follo*in! cal,pso car"s ha1e 3een reporte" to *or/ *ith this scriptB 9a1i!o8Paris? M%7I787russels? Ra1Ka18Israel an" Korri!o8Rennes Fpartial supportG. Jou *ill notice that these transport car"s /eep an e ent log "escri3in! at least ( of the last stations8stops ,ou ha1e 3een throu!h. 2his e ent log? *hich coul" pose a pri1ac, ris/? is not protecte" 3, an, access control eans an" is freel, rea"a3le. >or 9a1i!o car"s? this script pro1i"es enhance" Le1ent lo!M anal,sis nota3l, *ith su3*a,8train station na es? as illustrate" in >i!ure +. It has 3een successfull, teste" on Na igo 4?co- erte' Na igo an" Na igo 0nt?grale car"s. Jou ust use the contact interface to rea" a 9a1i!o car"? 3ecause the, cannot 3e rea" *ith a nor al contactless car" rea"er Fthese car"s use a specific protocol that is not full, co pati3le *ith I&% 1+++( 7G. 2he script also rea"s M%7I7 car"s use" in 7russels? *ith enhance" Le1ent lo!M anal,sis. %ne unusual feature of the M%7I7 car" is the possi3ilit, to access the na e an" "ate of 3irth of the car" hol"er. M%7I7 car"s are full, co pati3le *ith I&% 1+++( car" rea"ers. 2he cal,pso script rea"s all the files it can fin" on the car" an" e$tracts the ra* 3inar, "ata it fin"s. 2he interpretation of that 3inar, "ata 1aries fro countr, to countr,? an" e1en fro re!ion to re!ion. %nce the "ata is loa"e"? the script atte pts to auto aticall, "etect the countr, an" re!ion the car" co es fro . 2he countr, is i"entifie" 3, a nu 3er follo*in! I&% (14451? 3ut *ithout lea"in! Aeros. 2he re!ion co"e is also a nu erical 1alue. 2he script *ill then loo/ into the calypso "irector, for a script calle" LcXXX.luaM *here XXX represents the countr, co"e. If foun"? this e$tra script *ill 3e e$ecute". 9e$t the ain script *ill loo/ a!ain in the calypso "irector, for a script calle" L cXXXnYYY.luaM *here XXX represents the countr, co"e an" YYY the re!ion co"e. If foun"? this script *ill also 3e e$ecute". Currentl, countr,8re!ion "etection is 3ase" on so e si ple heuristics an" does not #or/ for all cal'pso cards. Pro!ra ers *ishin! to tailor the 3eha1ior of the cal,pso script to their o*n countr, or re!ion can thus a"" their o*n file in the cal(pso "irector,.

$.$ em0
$.$.1 O0er0ie#

2his script pro1i"es an anal,sis of EMC 3an/in! car"s use" across the *orl".

Chapter + Car" anal,sis tools

17

$.$.2

Implementation notes

2his script *ill as/ ,ou if ,ou *ant to issue a L6et Processin! %ption< F6P%G co an" for each application on the car". &ince so e car"s ha1e se1eral applications Fe.!. a national an" an international applicationG? this =uestion a, 3e as/e" t*ice or ore. 2his co an" is nee"e" to allo* full access to all freel, rea"a3le infor ation in the car". As a si"e effect? issuin! this co an" *ill increase an internal counter insi"e the car" calle" A2C FApplication 2ransaction CounterG. Jou *ill notice that an, of these 3an/ car"s /eep a Ltransaction lo!M of the last transactions ,ou ha1e a"e *ith ,our car". &o e 3an/s car"s /eep *a, o1er a hun"re" transactions that are freel, rea"a3le? *hich 3rin!s up so e pri1ac, issues.

$.( e3passport
$.(.1 O0er0ie#

2his script pro1i"es an anal,sis of "ata in an electronic83io etric passport? throu!h a contactless interface. Jou *ill nee" to enter the secon" lo*er line of the MRP FMachine Rea"a3le PoneG "ata on the passport.

0ll-stration 71 =(e 23@ o, a passport >so-rce1 "i)ipe#ia8

$.(.2

Implementation notes

2his script i ple ents the 7AC F7asic Access ControlG secure access al!orith to access "ata in the passport. It *ill not 3e a3le to access "ata protecte" *ith the EAC FEnhances Access ControlG al!orith . )hen the script starts? ,ou *ill 3e re=uire" to input a ini u of 28 characters fro the 3e!innin! of the secon" lo*er line of the MRP FMachine Rea"a3le PoneG "ata on the passport. 2his "ata is nee"e" to co pute the cr,pto!raphic /e,s use" in the 7AC al!orith . 2his scripts atte pts to parse 3io etric facial an" fin!erprint i a!e "ata. 9or all, ho*e1er? fin!erprint "ata is not accessi3le throu!h 7AC an" re=uires EAC.

Chapter + Car" anal,sis tools

18

$.2 5SM7SIM
$.2.1 O0er0ie#

2his script anal,ses the contents of 6&M &IM car"s? inclu"in! &M& an" phone3oo/ contacts.

$.2.2

5eneral notes

2his script is li ite" to classic 6&M8&IM car" content. Most a""itional "ata containe" on ne*er .&IM8(6 car"s is not anal,Ae".

$.4 moneo
$.4.1 O0er0ie#

2his scripts pro1i"e an anal,sis of M%9E% electronic purse car"s use" in >rance.

$.4.2

Implementation notes

2he pro1i"e" output is onl, partiall, interprete".

$.8 0itale 2
$.8.1 O0er0ie#

2his script pro1i"es an anal,sis of the secon" !eneration >rench health car" calle" LCitale 2M.

$.8.2

)otes

2his anal,sis is 3ase" on a lot of !uess*or/ an" nee"s further testin!. &o e Aones? nota3l, the one containin! the car"hol"er@s photo!raph,? see protecte"B this is a !oo" "esi!n choice in ter s of pri1ac, protection.

$.9 +dding 'our o#n scripts


A""in! or o"if,in! a script in CARDPEEK is eas,B si pl, a"" or o"if, a script inB the &'"ME/.cardpeek/scripts/ "irector, for #inu$8Mac %& '? or the %USE ! "#$%E%/.cardpeek/scripts/ for )in"o*s users.

%n #inu$ s,ste s an" Mac %& '? if ,ou *ant to !o further an" a/e a script per anentl, part of the source co"e of CARDPEEK for further "istri3ution? ,ou shoul" follo* these a""itional stepsB 1. 6o to the "irector, containin! the source co"e of CARDPEEK. Chapter + Car" anal,sis tools 1-

2. E$ecute the update_dot_cardpeek_dir.s/ scriptB Fe.!. t,pe L./update_dot_cardpeek.s/ update MG (. Run make to re3uil" CARDPEEK. +. 2he ne* create" 3inar, LCARDPEEKM *ill no* contain ,our ne* scripts an" can 3e "istri3ute". %n M& )in"o*s s,ste s? ,ou *ill nee" to reco pilin! CARDPEEK. Jou a, pro1i"e so e a""itional infor ation in the #.A source co"e of ,our script 3, a""in! so e specific /e,*or"s in co ents that appear in the first (0 lines of ,our script. 2hese /e,*or"s are i"entifie" 3, 3ein! prefi$e" *ith the 0 character an" 3ein! follo*e" 3, a space. 2he follo*in! /e,*or"s are reco!niAe"B 0name 2his chan!es the "efault na e of the script "ispla,e" in the enu. anuall, cop, ,our scripts for %USE ! "#$%E %/.cardpeek/scripts/ to the dot_cardpeek_dir "irector, in the source co"e? 3efore

0description 2his pro1i"es a hu an rea"a3le "escription of the script 0targets 2his pro1i"e an in"ication of the 1ersion of CARDPEEK this script *as "e1elope" for.

E$a pleB -- in %U, comments are marked wit/ a dou*le das/ 1--1 --- 0name EM2 -- 0description 3ank cards 1!$4 and c/ip1 -- 0targets 5.6 --

Chapter + Car" anal,sis tools

20

Chapter ( Programming C+%&P,,- scripts

2he in"i1i"ual scripts that allo* to process "ifferent t,pes of s art car"s are locate" in ,our &'"ME/.cardpeek/scripts/ "irector, or %USE ! "#$%E%/.cardpeek/scripts/ for M& )in"o*s. 2hese scripts are *ritten in #.A? a pro!ra in! lan!ua!e that shares so e si ilarities *ith Pascal an" Qa1ascript. 2o allo* #.A scripts to co unicate *ith s art car"s an" to anipulate car" "ata? the #.A lan!ua!e *as e$ten"e" *ith custo li3raries. 2his section pro1i"es an intro"uction to the CARDPEEK scriptin! facilities.

(.1 (.1 :ello #orld


2he si plest CARDPEEK script is pro3a3l, this oneB nodes.append7nodes.root789 :la*el;<'ello world<=8 Jou can "irectl, t,pe it in the LCo an"BM input Aone at the 3otto of the CARDPEEK 6.I. Alternati1el, ,ou can create a file calle" hello world.lua in the script "irector, Fin"icate" a3o1eG? an" cop, that one line of script in that file. %nce the file is sa1e"? if ,ou start CARDPEEK? Lhello *orl"M shoul" appear in the LAnal,AerM enu. %ne clic/ on Lhello *orl"M in the enu *ill e$ecute the script? pro1i"in! the result sho*n in Illustration 5. 2he a3o1e script is 1er, si ple an" "oes not interact *ith an, /in" of s art car"B it si pl, creates a no"e in the tree 1ie* area of CARDPEEK an" assi!ns the la3el L:ello *orl"M to it. 2he first para eter of the append co an" "escri3es the parent no"e to *hich *e a"" a ne* no"e. &ince *e are actuall, creatin! the first no"e in the tree? *e use the special function nodes.root78 *hich returns a reference to the "efault root no"e of the tree. 2he secon" 1alue :la*el;<'ello world<= that is passe" to the nodes.append78 function "escri3es the attri3utes of the no"e. In this e$a ple? the no"e has onl, one attri3ute specifie"B a la3el? *hich is set to L:ello *orl"M. 9o"e attri3utes can 3e accesse" an" o"ifie" at an, ti e? *ith the nodes.set_attri*ute78 an" nodes.get_attri*ute78 functions respecti1el,. 2he a3o1e Chapter 5 Pro!ra in! Car"pee/ scripts 21

script coul" ha1e 3een *ritten in t*o lines *ith the sa e result as follo*sB new_node ; nodes.append7nodes.root788 nodes.set_attri*ute7new_node9 <la*el<9 <'ello world<8 >inall,? it is *orth notin! that the function in the no"es li3rar, can use the #ua %3<ect %riente" F%%G notation? pro1i"in! a thir" an" ore concise *a, to *rite the L:ello *orl"M script as follo*sB nodes.root78>append7:la*el;<'ello world<=8 2he choice of usin! the #ua %% notation instea" of the tra"itional one is purel, a taste. atter of

0ll-stration A1 +ello $orl#

(.2 6asic communication #ith a smart card


:ere@s a short #.A script that "e onstrates ho* to !et an" print the A2R FAns*er 2o ResetG of a car" in the car" 1ie*. card.connect78 atr ; card.last_atr78 if atr?;nil t/en root ; nodes.root78

Chapter 5 Pro!ra

in! Car"pee/ scripts

22

m(card ; root>append7: classname;<card<9 la*el;<M( card< =8 m(card>append7: classname;<*lock<9 la*el;<+old ,@ <9 siAe;Batr9 )al;atr =8 end card.disconnect78 2he fist co an" card.connect78 po*ers5up the car" in the car" rea"er an" unication. 9e$t card.last_atr78 returns the A2R of the

prepares the car" for co

car". If the 1alue of the A2R is non5nil? the script creates a no"e calle" LA2RM? *ith a call to nodes.append78. 2his no"e *ill appear at the root of the car" "ata tree51ie* an" is constructe" *ith t*o attri3utesB A classnameB this "escri3es the icon use" to "ispla, the no"e Fhere a Lcar"M iconG. A labelB the te$t "ispla,e" *ith the no"e. A classnameB the icon use" to "ispla, the no"e Fhere a L3loc/M iconG. A labelB the te$t "ispla,e" *ith the no"e Fi.e. LCol" A2RMG. A si/eB the te$t "ispla,e" in the secon" colu n of the tree 1ie*. A alB the 3,testrin! 1alue "ispla,e" in the thir" colu n of the tree 1ie* Fi.e. the he$a"eci al 1alue of the A2RG.

A chil" no"e calle" Lcol" A2RM is then a""e" to the parent LA2RM no"e? *ith + attri3utesB

>inall,? the car" is po*ere" "o*n *ith the card.disconnect78 function. 2he final output of the script shoul" ha1e rou!hl, the follo*in! structure Fthou!h the 1alue of the A2R *ill li/el, 3e "ifferentGB

Chapter 5 Pro!ra

in! Car"pee/ scripts

2(

0ll-stration B1 4isplaying t(e A=3 2he e$a ple a3o1e is e=ui1alent to the LatrM script pro1i"e" *ith CARDPEEK. 2he #.A lan!ua!e is eas, to learn an" *e refer the rea"er to http://www.lua.org/ for ore infor ation.

(.! %epresenting card data in a tree structure


2he "ata "ispla,e" in the car" 1ie* of CARDPEEK follo*s a tree structure? as s/etche" in Illustration 7.

0ll-stration .1 =ree str-ct-re

Chapter 5 Pro!ra

in! Car"pee/ scripts

2+

Each no"e of the tree has the follo*in! attri3utes that influence the "ispla, of "ata in the car" 1ie*B + classname1 "escri3es the icon that *ill 3e associate" *ith the no"e in the first colu n of the car" 1ie*. + label1 "escri3es the na e of the no"e? sho*n in 3ol" in the first colu n of the car" 1ie*. +n id1 "escri3es the I" associate" *ith the no"e? follo*in! the la3el? in the first colu n of the car" 1ie*. + si;e1 the siAe of the "ata associate" to the no"e? "ispla,e" in the secon" colu n of the car" 1ie*. + 0alue <0al=1 the "ata associate" to the no"e in ra* 3inar, for at? "ispla,e" in the thir" colu n of the car" 1ie*. +n alternati0e 0alue <alt=1 the "ata associate" to the no"e in an interprete" for at? "ispla,e" in the thir" colu n of the car" 1ie*. + mime3t'peB this !i1es CARDPEEK a hint on ho* to ren"er the 1alue F1alG on the screen? *hen an alternati1e 1alue FaltG is not specifie". Currentl, onl, i a!es are supporte".

All these attri3utes are optional. Moreo1er? script pro!ra ers can create ne* attri3utes as the, *ish for their o*n use? thou!h onl, the ones a3o1e influence the "ispla, of CARDPEEK. Attri3utes are set throu!h functions such as nodes.set_attri*ute78 an" nodes.set_)alue78 as "escri3e" in section 4.4. 2he tree itself is 3uilt *ith functions such as nodes.append78 alrea", "escri3e" in the pre1ious e$a ples in this chapter. CARDPEEK pro1i"es an, other functions to create? re o1e? alter an" fin" no"es in a tree? all "escri3e" in section 4.4.

Chapter 5 Pro!ra

in! Car"pee/ scripts

25

Chapter 2 &e0elopment librar'

2his chapter "escri3es the #.A li3raries of functions that are use" in CARDPEEK scripts.

2.1 The bit librar'


&ince #.A 5.1 "oes not ha1e nati1e 3it anipulation functions? the follo*in! functions ha1e 3een a""e". 2he, all operate on inte!er nu 3ers.

2.1.1 bit.+)&
&J9%P&I&

*it.,4-7,938 DE&CRIP2I%9 Co pute the 3inar, operation , an# 3.

2.1.2
&J9%P&I&

bit.O%

*it." 7,938 DE&CRIP2I%9 Co pute the 3inar, operation A or B.

2.1.!
&J9%P&I&

bit. O%

bit.XOR(A,B)

Chapter 4 De1elop ent li3rar,

24

DE&CRIP2I%9 Co pute the 3inar, operation A xor B.

2.1.$
&J9%P&I&

bit.S:L

bit.SHL(A,B)

DE&CRIP2I%9

&hift the 3its of A 3, 7 positions to the left. 2his is e=ui1alent to co putin! AR2 7.

2.1.(
&J9%P&I&

bit.S:%

bit.SHR(A,B)

DE&CRIP2I%9

&hift the 3its of A 3, 7 positions to the ri!ht. 2his is e=ui1alent to co putin! A82 7.

2.2 The bytes librar'


2he *(tes li3rar, pro1i"es a ne* opa=ue t,pe to #.AB a bytestring' *hich is use" to represent an arra, of 3inar, ele ents. A 3,testrin! is the application. ainl, use" to represent 3inar, "ata e$chan!e" *ith the car" rea"er in

2he ele ents in a bytestring arra, are ost co onl, 3,tes F8 3itsG? 3ut it is also possi3le to construct arra,s of ni33les F+ 3itG or arra,s of in"i1i"ual 3its. All ele ents in a bytestring ha1e the sa e siAe F8? + or 1G? *hich is referre" as the L*i"thM of the bytestring. 2he *i"th of each ele ent is specifie" *hen the arra, is create" *ith the function *(tes.new78 "escri3e" in this section. A function to con1ert 3et*een bytestrings of "ifferent *i"ths is also pro1i"e". In"i1i"ual ele ents in a bytestring arra, can 3e accesse" or o"ifie" *ith the *(tes.get an" *(tes.set functions respecti1el,. Contrar, to the #.A tra"ition? the first in"e$ in a 3,testrin! is 5 instea" of C. 2he nu 3er of ele ents in a 3,testrin! is in"icate" 3, prefi$in! the 3,testrin! *ith the L BM operator? <ust as *ith an arra, Fe.!. B3S). It is also possi3le to access ele ents in 3,testrin! usin! arra, notation Fe.!. 3SDCE;FGG. #i/e #.A arra,s? if ,ou create a 3,testrin! , then the assi!n ent 3;, "oes not a/e 3

Chapter 4 De1elop ent li3rar,

27

a full cop, of , 3ut onl, an alias of ,B an, or the *(tes.new78 function instea".

o"ification of , applies to 3 an" 1ice51ersa. If

,ou *ant to create a real cop, of a 3,testrin!? ,ou shoul" use the *(tes.clone78 function 2he functions of the *(tes li3rar, are "escri3e" hereafter.

2.2.1

Operators on b'testrings

2he operators that can 3e use" on 3,testrin!s are L ..M? L;;M? L?;M an" LBM
&J9%P&I&

,..3 ,;;3 ,?;3 B,


DE&CRIP2I%9

2he L..M operator creates a ne* 3,testrin! 3, concatenatin! t*o 3,testrin!s to!ether. 2he concatenation operator also *or/s if one of the operan"s is a strin! or a nu 3er? 3, con1ertin! it to a 3,testrin! first? follo*in! the rules "escri3e" in the *(tes.assign78 function. )ritin! ,..3 is e=ui1alent to callin! the function *(tes.concat7,938. 2he L;;M an" L?;M operators allo* to co pare t*o 3,testrin!s for e=ualit, or non5 e=ualit, respecti1el,. 2o 3e e=ual? t*o 3,testrin!s ele ents in the sa e or"er. ust ha1e the sa e *i"th an" the sa e

>inall, the LBM operator returns the nu 3er of ele ents in a 3,testrin!.

2.2.2
&J9%P&I&

b'tes.clone

*(tes.clone73S8 3S>clone78 DE&CRIP2I%9 Creates an" returns a cop, of 3S. RE2.R9 CA#.E 2his function returns a 3,testrin! upon success or nil if it fails.

Chapter 4 De1elop ent li3rar,

28

2.2.!
&J9%P&I&

b'tes.concat

*(tes.concat7 al-e0' al-e1' ...' al-eN8


DE&CRIP2I%9

Returns the concatenation of al-e0' al-e1' ...' al-eN Ffro left to ri!htG. >or the rules !o1ernin! the processin! of al-e0' al-e1' ...' al-eN' see the bytes.new() function. RE2.R9 CA#.E 2his function returns a 3,testrin! upon success an" nil other*ise.

2.2.$
&J9%P&I&

b'tes.con0ert

*(tes.con)ert73S9 w8 3S>con)ert7w8
DE&CRIP2I%9

Con1erts BS to a ne* 3,testrin! *here each ele ent has a *i"th w. Depen"in! on the 1alue of w, the ele ents in the con1erte" 3,testrin! are o3taine" 3, either splittin! ele ents of BS into se1eral s aller ele ents in the ne* 3,testrin! or 3, !roupin! se1eral ele ents of BS into a sin!le ele ent in the ne* 3,testrin!. If the con1ersion re=uires splittin! ele ents of 3S, then the ori!inal ele ents *ill 3e split *ith the ost si!nificant 3itFsG firstB the ost si!nificant 3its of each ori!inal ele ent of BS *ill ha1e a lo*er in"e$ than the least si!nificant 3its. If the con1ersion re=uires !roupin! ele ents to!ether? BS is *ill first 3e ri!ht5pa""e" *ith Aeros to a siAe that is a ultiple of w. 9e$t? ne* ele ents are for e" 3, consi"erin! ele ents of 3S *ith a lo*er in"e$ as RE2.R9 CA#.E 2his function returns a ne* 3,testrin! upon success an" nil other*ise. ore si!nificant than ele ents *ith a hi!her in"e$.

Chapter 4 De1elop ent li3rar,

2-

2.2.(
&J9%P&I&

b'tes.format

*(tes.format73S9 format_string8 3S>format7format_string8


DE&CRIP2I%9

Con1erts the 3,testrin! BS to 1arious printa3le for ats accor"in! to the format_string character strin!. 2his format_string can 3e co pose" of plain characters? *hich are si pl, copie" to the resultin! strin!? an" for at specifications *hich are replace" 3, the "esi!nate" representation of 3S. A s i n printf78 functions foun" in an, pro!ra in! lan!ua!es? each for at eanin!B specification starts *ith the character L %M an" has the follo*in! %$ represent 3S as an unsi!ne" "eci al inte!er. %- represent 3S as the concatenation of each of its ele ents represente" in he$a"eci al or 3inar,? startin! fro %S is e=ui1alent to L%w>%-M. %! represent 3S *here each ele ent is con1erte" to a printa3le character Fin . bit ascii ,ormat8. .nprinta3le characters are escape" to octal notation Fe.!. ascii 1( or carria!e return 3eco es S015G. %+ represents 3S as a #.A strin!? con1ertin! each ele ent into a character of a strin!. 2his can nota3l, 3e use" to print a 3,testrin! representin! .2>8 "ata. %w represents the *i"th of 3S, that is 8? + or 1. %l represents the nu 3er of ele ents in 3S? in "eci al for %% represent the L%M character itself.
RE2.R9 CA#.E

3SD5E to 3SD4-CE.

Fthe len!th of 3S).

2his function returns the resultin! character strin!.

2.2.2
&J9%P&I&

b'tes.get

*(tes.get73S9i D9HE8 3S>get7i D9HE8 Chapter 4 De1elop ent li3rar, (0

DE&CRIP2I%9 Returns the list of 1alues of ele ents of 7& *ith in"e$ i to H inclusi1e. )hen H is not specifie"? this function si pl, returns the ith ele ent of 7& Fi.e it is e=ui1alent to *(tes.get73S9i9i8 or RE2.R9 CA#.E 2his function returns a list of inte!er 1alues upon success or nil other*ise. ore si pl, 3SDiEG.

2.2.4
&J9%P&I&

b'tes.ipairs

for i9) in *(tes.ipairs73S8 do ... end for i9) in 3S>ipairs78 do ... end DE&CRIP2I%9 2he *(tes.ipairs73S8 function returns an iterator on the ele ents of a 3,testrin! 3S. 2his iterator returns 3oth the in"e$ an" the 1alue of each ele ent? iterator use" for ta3les in #.A. RE2.R9 CA#.E 2his function returns an iterator Fa #.A functionG upon success or nil other*ise. uch li/e the ipairs78

2.2.8
&J9%P&I&

b'tes.is>printable

*(tes.is_printa*le73S8 3S>is_printa*le78 DE&CRIP2I%9 Returns true if all ele ents in 3S can 3e con1erte" to printa3le 7 3it ascii characters? an" false other*ise.

Chapter 4 De1elop ent li3rar,

(1

RE2.R9 CA#.E 2his function al*a,s returns false if the *i"th of BS is not 8 Fele ents of *i"th + or 1 are not printa3le ascii 1aluesG.

2.2.9
&J9%P&I&

b'tes.ne#

*(tes.new7widt/ T? al-e1' ...' al-eNU8 DE&CRIP2I%9 Creates a ne* bytestring' *here each ele ent is widt/ 3its. widt/ can 3e either 8? + or 1. A 1alue can optionall, 3e assi!ne" to the bytestring 3, specif,in! one or se1eral 1alues al-e1' ...' al-eN that *ill 3e concatenate" to!ether to for the content of the bytestring. 2he optional assi!ne" 1alue is 3uilt as the concatenation of al-e1' ...' al-eN Ffro left to ri!htG. Each al-ei can 3e either a 3,testrin!? a strin! or a nu 3er. If al-ei is a 3,testrin!? each ele ent of al-ei is appen"e" to BS, *ithout an, con1ersion. If al-ei is a strin!? it is interprete" as a te$t representation of the "i!its of a 3,testrin! Fas returne" 3, t h e tostring78 operatorG. 2his strin! representation is interprete" 3, ta/in! into consi"eration the *i"th of ele ents of BS an" is appen"e" to 3S. If al-ei is a nu 3er? it is con1erte" into a sin!le 3,testrin! ele ent an" appen"e" to 3S. RE2.R9 CA#.E 2his function returns a bytestring upon success an" nil other*ise.

2.2.1?
&J9%P&I&

b'tes.ne#>from>chars

*(tes.new_from_c/ars7string8
DE&CRIP2I%9

Creates a ne* 8 3it *i"th 3,testrin! fro string. Each ascii character in string is con1erte" "irectl, to an ele ent of the resultin! 3,testrin! Fe.!. LAM is con1erte" to 45G. RE2.R9 CA#.E 2his function returns a 3,testrin! upon success an" nil other*ise.

Chapter 4 De1elop ent li3rar,

(2

2.2.11
&J9%P&I&

b'tes.pad>left

*(tes.pad_left73S9 *lock_lengt/9 )alue8 3S>pad_left7*lock_lengt/9 )alue8


DE&CRIP2I%9

2his function returns a cop, of 3S pa""e" on the left *ith the ele ent )alue until the len!th of the resultin! 3,testrin! reaches a If the siAe of 3S is alrea", a applie". RE2.R9 CA#.E 2his function returns a 3,testrin! upon success an" nil other*ise. ultiple of *lock_lengt/. ultiple of *lock_lengt/? no a""itional pa""in! is

2.2.12
&J9%P&I&

b'tes.pad>right

*(tes.pad_rig/t73S9 lengt/9 )alue8 3S>pad_rig/t73S9 lengt/9 )alue8 DE&CRIP2I%9 2his function returns a cop, of 3S pa""e" on the ri!ht *ith the ele ent )alue until the len!th of the resultin! 3,testrin! reaches a If the siAe of 3S is alrea", a applie". RE2.R9 CA#.E 2his function returns a 3,testrin! upon success an" nil other*ise. ultiple of *lock_lengt/. ultiple of *lock_lengt/? no a""itional pa""in! is

2.2.1!
&J9%P&I&

b'tes.re0erse

*(tes.re)erse73S8 3S>re)erse78

Chapter 4 De1elop ent li3rar,

((

DE&CRIP2I%9

Returns a 3,testrin! containin! the ele ents of 3S in re1erse or"er. RE2.R9 CA#.E 2his function returns a 3,testrin! upon success an" nil other*ise.

2.2.1$
&J9%P&I&

b'tes.set

*(tes.set73S9 i9 e5 D9 eC9 e29 ...9 e4E8 3S>set7i9 e5 D9 eC9 e29 ...9 e4E8
DE&CRIP2I%9

2his function replaces the ith ele ent of 7& *ith e5. If a""itional ele ents eC9e29...9e4 are specifie" in the call then the F iIC8th ele ent of 3S is replace" 3, eC? the FiI28th ele ent of 3S is replace" 3, e2? etc. RE2.R9 CA#.E 2his function o"ifies its ain ar!u ent 3S an" returns it.

2.2.1(
&J9%P&I&

b'tes.sub

*(tes.su*73S9 start D9 endE8


DE&CRIP2I%9

Returns a cop, of a su3strin! fro

3S containin! all ele ents 3et*een start an" end.

2he returne" 1alue represents a 3,testrin! containin! a cop, of all the ele ents of BS that ha1e an in"e$ that 1erifies in#ex C start an" in#ex D end. If end is not specifie" it *ill "efault to the last in"e$ of 3S. I f start For end) is ne!ati1e? it *ill 3e replace" 3, B3SIstart For B3SIend respecti1el,G. RE2.R9 CA#.E 2his function returns a 3,testrin! upon success an" nil other*ise.

Chapter 4 De1elop ent li3rar,

(+

2.2.12
&J9%P&I&

b'tes.tonumber

*(tes.tonum*er73S8 3S>tonum*er78
DE&CRIP2I%9

Con1erts the 3,testrin! 3S to a the unsi!ne" "eci al 1alue of 3S. 2his con1ersion consi"ers 3SD5E as the RE2.R9 CA#.E 2his function returns a nu 3er. ost si!nificant ele ent of 3S? an" 3SDB3S-CE as the least si!nificant.

2.2.14
&J9%P&I&

b'tes.#idth

*(tes.widt/73S8 3S>widt/78 DE&CRIP2I%9 Return the *i"th of the ele ents in 3S. RE2.R9 CA#.E 2his function a, return the nu 3er 1? + or 8.

2.! The asn1 librar'


2he A&91 li3rar,2 allo*s to anipulate 3,testrin!s containin! A&91 2#C ( "ata enco"e" in DER87ER+ for at. 2hese 3,testrin!s ust 3e 8 3it *i"e. )hen CARDPEEK rea"s 2#C "ata fro a car"? it co es as a 3,testrin! *here the ta! is enco"e"? follo*e" 3, the len!th? an" finall, the 1alue itself. >or e$a ple CARDPEEK a, recei1e the follo*in! strin!B J#5K,555555553C5C5, *here J# is actuall, the ta!? 5K the len!th? an" ,555555553C5C5 is the 1alue. In so e cases? the ta! or the len!th follo* co ple$ enco"in!s? an" so e 2#Cs pro1i"es facilities to "eco"e an" enco"e 2#C "ata.
2 ' For a quick tutorial on ASN1 see A Layman's Guide to a Subset of ASN.1, !", and #!"$ by . S. %aliski &r. (L) * (a+,Len+t,,)alue #!". !" * #istin+uis,ed. asic !ncodin+ "ules

ore

a, 3e containe" *ithin other 2#Cs. 2he asnC li3rar,

Chapter 4 De1elop ent li3rar,

(5

9or all,? 2#C 1alues are co pose" of ( ele entsB a ta! nu 3er? a len!th? an" the 1alue itself. In #.A? *e onl, nee" 2 ite s to represent a 2#CB a ta! nu 3er an" a 1alue represente" as a 3,testrin!. 2he len!th of the 1alue is i plicit an" can co pute" 3, appl,in! the V operator on the 1alue. 2he li3rar, pro1i"es the follo*in! functions.

2.!.1
&J9%P&I&

asn1.enable>single>b'te>length

asnC.ena*le_single_*(te_lengt/7ena*le8
DE&CRIP2I%9

2his function is onl, use" in rare cases *ith erroneous car" i ple entations. If ena*le;true the 3eha1ior of 2#C "eco"in! functions Fsuch as *(tes.tl)_split78G are o"ifie" 3, forcin! the A&91 len!th to 3e 1 3,te lon!. 2his eans that e1en if the first 3,te of the enco"e" len!th is !reater than 5x65 it *ill 3e interprete" as the len!th of the 2#C 1alue. RE2.R9 CA#.E 9one.

2.!.2
&J9%P&I&

asn1.@oin

asnC.Hoin7tag9 )al D9 extraE8


DE&CRIP2I%9

2his function perfor s the opposite of asnC.split78 F"escri3e" in 4.(.(GB it creates a 3,testrin! representin! the A&91 DER enco"in! of the 2#C W tag? l e n ' )al} *here lenE#)al an" appen"s extra to the result. tag is positi1e inte!er nu 3er? )al is a 3,testrin! an" extra is a 3,testrin! or nil. RE2.R9 CA#.E 2his function returns a 3,testrin!.

Chapter 4 De1elop ent li3rar,

(4

2.!.!
&J9%P&I&

asn1.split

asnC.split7str8 DE&CRIP2I%9 Parses the 3e!innin! of the 3,testrin! str accor"in! to A&91 7ER 2#C enco"in! rules? an" e$tracts a ta! nu 3er @ an" a 3,testrin! 1alue 2. RE2.R9 CA#.E 2he function returns ( ele ents W@? 2? extraX? *here extra is an optional 3,testrin! representin! the re ainin! part of str that *as not parse" or nil if no "ata re ains. If this function fails it returns a triplet of nil 1alues.

2.!.$
&J9%P&I&

asn1.split>length

asnC.split_lengt/7str8 DE&CRIP2I%9 Parses the 3e!innin! of the 3,testrin! str accor"in! to A&91 7ER an" e$tracts a len!th L. RE2.R9 CA#.E 2he function returns W%? extraF' *here extra is an optional 3,testrin! representin! the re ainin! part of str that *as not parse" or nil if no "ata re ains. If this function fails it returns a pair of nil 1alues.

2.!.(
&J9%P&I&

asn1.split>tag

asnC.split_tag7str8 DE&CRIP2I%9 Parses the 3e!innin! of the 3,testrin! str accor"in! to A&91 7ER an" e$tracts a ta! T. RE2.R9 CA#.E 2he function returns W@? extraX? *here extra is an optional 3,testrin! representin! the Chapter 4 De1elop ent li3rar, (7

re ainin! part of str that *as not parse" or nil if no "ata re ains. If this function fails it returns a pair of nil 1alues.

2.$ The card librar'


2 h e car li3rar, is use" to co unicate *ith a s art car" in a car" rea"er. CARDPEEK internall, "efines a ini al set of car" functions in the card li3rar,. &o e a""itional e$tensions to the car li3rar, are *ritten in #.A an" can 3e foun" in the file !"#$%/.cardpeek/scripts/lib/apdu.lua, *hich shoul" 3e loa"e" auto aticall, *hen CARDPEEK starts. Accor"in! to I&% 78145+? s art car" co 3,tes !enerall, or!aniAe" as follo*sB Code C#A I9& P1 P2 #c Data #e Length 1 1 1 1 1 For (G Caria3le 1 For (G an" APD.s are co pose" as a series of

)ame Class Instruction Para eter 1 Para eter 2 #en!th of follo*in! "ata Data Ma$i u e$pecte" len!th of response ost car"

2he car" li3rar, "efines a !lo3al 1alue card.+%,, *hich is the 1alue that

co an"s *ill use as C#A *hen the, e$chan!e "ata *ith the car"5rea"er Funless ,ou use card.send78 "irectl,G. 2his li3rar, contains the follo*in! functions.

2.$.1
&J9%P&I&

card.connect

card.connect78
DE&CRIP2I%9

Connect to the car" currentl, inserte" in the selecte" s art car" rea"er or in pro$i it, of a contactless s art car" rea"er. 2his function *ill 3loc/ until car" is connecte". 2his co RE2.R9 CA#.E 2his function returns true upon success? an" false other*ise. Chapter 4 De1elop ent li3rar, (8 an" is use" at the start of ost s art car" scripts.

2.$.2
&J9%P&I&

card.disconnect

card.disconnect78
DE&CRIP2I%9

Disconnect the car" currentl, inserte" in the selecte" s art car" rea"er. 2his co conclu"es ost s art car" scripts. RE2.R9 CA#.E 2his function returns true upon success? an" false other*ise.

an"

2.$.!
&J9%P&I&

card.get>data

card.get_data7id D9 lengt/_expectedE8 DE&CRIP2I%9 E$ecute the LE@_-,@, co an" fro I&% 78145+ *hereB the car".

id is the ta! nu 3er of the 1alue to rea" fro e$pecte" result F"efaults to 0? *hich

lengt/_expected is an optional 1alue specif,in! the len!th of the resultin! eans 254 3,tesG. an" sent to the car" is "efine" 3, the 1aria3le card.+%,.

2he 1alue of LC#AM in the co

2his function is i ple ente" in apdu.lua. RE2.R9 CA#.E 2he car" status *or" an" response "ata? as "escri3e" in card.send Fsection 4.+.10 G.

2.$.$
&J9%P&I&

card.info

card.info78 DE&CRIP2I%9 Return "etaile" infor ation a3out the state of the car" rea"er.

Chapter 4 De1elop ent li3rar,

(-

RE2.R9 CA#.E 2his function returns an associati1e arra, of Fname al-e8 pairs.

2.$.(
&J9%P&I&

card.last>atr

card.last_atr78 DE&CRIP2I%9 Returns a 3,testrin! representin! the last A2R FAns*er 2o ResetG returne" 3, the car". RE2.R9 CA#.E 2his function returns a 3,testrin!.

2.$.2
&J9%P&I&

card.ma/e>file>path

card.make_file_pat/7pat/8
DE&CRIP2I%9

2his function is "esi!ne" to 3e a helper function for the i ple entation of card.select. It con1erts a hu an rea"a3le path strin! Frepresentin! a file location in a s art car"G into a for at that is co pati3le *ith the S!L!"T#$%L! co an" fro I&% 78145+. 2his function parses the strin! pat/ an" returns a pair of 1alues Wpat/_*inar(?
pat&#type} *hereB

pat/_*inar( is a 3,testrin! representin! the enco"e" 3inar, 1alue of pat&, an" pat/_t(pe is a nu 3er "escri3in! the path t,pe Fi.e. a relati1e path? an AID? ...G a path strin! can 3e su ariAe" as follo*sB A file ID is represente" 3, + he$a"eci al "i!its Fho*e1er? there is an e$ception for AD>s that can also 3e represente" 3, their AID? *hich re=uires 10 to (2 he$a"eci al "i!its? or in other *or"s 5 to 14 3,tesG. If pat/ starts *ith the KB@ character? the file is selecte" "irectl, 3, its uni=ue ID or AID. If pat/ starts *ith the K.@ character? the file is selecte" relati1el, to the current D> or E>. >iles can also 3e selecte" 3, specif,in! a relati1e or a3solute path? *here each ele ent in the path is represente" 3, a + "i!it file ID separate" 3, the K8@ characterB +0

2he !eneral rules nee"e" to for

Chapter 4 De1elop ent li3rar,

If pat& starts *ith K8@ the file is selecte" 3, its full path Fe$clu"in! the M>G. I f pat& starts *ith K.8@ the file is selecte" 3, its relati1e path Fe$clu"in! the current D>G. 2he ne$t ta3le "escri3es the for at of the strin! pat& an" ho* it is interprete" ore precisel,. In this ta3le? as a con1ention? he$a"eci al characters are represente" *ith the character Kh@ an" repeate" ele ents are su ariAe" 3, *ritin! LT...UM. path format B B//// B//////D...E// .//// .///// .. interpretation
Directl, select the M> Fe=ui1alent to B3#55) Directl, select the file *ith IDY//// Directl, select AIDY//////D...E// the D> *ith

path>t'pe 0 0 + 1 2 ( -

.n"er the current D>? select the file *ith IDY//// .n"er the current D>? select the D> *ith IDY//// &elect the parent of the current E> or D>.

&elect a file usin! a relati1e path fro the current ./////////////D...E D>. All inter e"iar, D>@s are represente" 3, their file ID separate" 3, the K8@ character. &elect a file *ith an a3solute path fro the M> Fthe M> is o itte"G All inter e"iar, D>@s are represente" 3, their file ID separate" 3, the K8@ character.

/////////////D...E

2he resultin! 3,testrin! pat/_*inar( is si pl, pro"uce" fro

the concatenation of

the he$a"eci al 1alues in pat/ Frepresente" 3, K/@ in the ta3le a3o1e.G RE2.R9 CA#.E .pon success this function returns a pair of 1alues consistin! of a 3,testrin! an" a nu 3er. .pon failure? this functions returns a pair of nil 1alues.

2.$.4
&J9%P&I&

card.read>binar'

card.read_*inar(7sfi D9 address D9 lengt/_expectedEE8

Chapter 4 De1elop ent li3rar,

+1

DE&CRIP2I%9 E$ecute the E,-_3$4, M co an" fro I&% 78145+ *hereB

sfi is a nu 3er representin! a short file i"entifier F1 sfi (0G or the strin! K.@ to refer to the currentl, selecte" file. address is an optional start a""ress to rea" "ata F"efaults to 0G. lengt/_expected is an optional 1alue specif,in! the len!th of the resultin! e$pecte" result F"efaults to 0? *hich 2he 1alue of LC#AM in the co
car ."LA.

eans 254 3,tesG.

an" sent to the car" is "efine" 3, the #.A 1aria3le

2his function is i ple ente" in apdu.lua.


RE2.R9 CA#.E

2he car" status *or" an" response "ata? as "escri3e" in card.send Fsection 4.+.10 G.

2.$.8
&J9%P&I&

card.read>record

card.read_record7sfi9 r9 D9 lengt/_expectedE8 DE&CRIP2I%9 E$ecute the E,-_ E+" - co an" fro I&% 78145+ *hereB

sfi is a nu 3er representin! a short file i"entifier F1 sfi (0G or the strin! K.@ to refer to the currentl, selecte" file. r is the recor" nu 3er to rea". lengt/_expected is an optional 1alue specif,in! the len!th of the resultin! e$pecte" result F"efaults to 0? *hich 2he 1alue of LC#AM in the co
car ."LA.

eans 254 3,tesG.

an" sent to the car" is "efine" 3, the #.A 1aria3le

2his function is i ple ente" in apdu.lua. RE2.R9 CA#.E 2he car" status *or" an" response "ata? as "escri3e" in car .sen Fsection 4.+.10 G.

Chapter 4 De1elop ent li3rar,

+2

2.$.9
&J9%P&I&

card.select

card.select7file_pat/ D9 return_w/at D9 lengt/EE8 DE&CRIP2I%9 E $ e c u t e t h e SE%E+@_#$%E in card.make_file_pat/78. return_w/at is an optional 1alue "escri3in! the e$pecte" result? as "escri3e" in the ta3le 3elo* F"efaults to 0G. lengt/ is an optional 1alue specif,in! the len!th of the resultin! e$pecte" result F"efaults to nilG. 2he follo*in! constants ha1e 3een "efine" for return_w/at Fso e can 3e co 3ine" to!ether 3, a""itionGB Constant card.SE%E+@_ E@U 4_#$ S@ card.SE%E+@_ E@U 4_%,S@ card.SE%E+@_ E@U 4_4EN@ card.SE%E+@_ E@U 4_! E2$"US card.SE%E+@_ E@U 4_#+$ card.SE%E+@_ E@U 4_#+! card.SE%E+@_ E@U 4_#MAalue 0 1 2 ( 0 + 8 co an" fro I&% 78145+ *hereB

file_pat/ is strin! "escri3in! the file to select? accor"in! to the for at "escri3e"

2he 1alue of LC#AM in the co an" sent to the car" is "efine" 3, 3, the 1aria3le card.+%,. 2he 1alue of LP1M in the co an" sent to the car" correspon"s to the file t,pe co pute" 3, card.make_file_pat/. 2he 1alue of LP2M in the co correspon"s to return_w/at. 2his function is i ple ente" in apdu.lua. RE2.R9 CA#.E 2he car" status *or" an" response "ata? as "escri3e" in car .sen Fsection 4.+.10G. an" sent to the car"

Chapter 4 De1elop ent li3rar,

+(

2.$.1?
&J9%P&I&

card.send

card.send7,!-U8 DE&CRIP2I%9 &en"s the co RE2.R9 CA#.E 2he function returns a pair of 1aluesB a nu 3er representin! the status *or" returne" 3, the car" Fe$. 5xO555G an" the response "ata returne" 3, the car". 7oth the co an" A'() an" the response "ata are 3,testrin!s Fsee the bytes li3rar,G. an" ,!-U to the car".

2.$.11
&J9%P&I&

card.#arm>reset

card.warm_reset78
DE&CRIP2I%9

Perfor s a *ar reset of the car" Freconnects the car" currentl, inserte" in the selecte" s art car" rea"erG. RE2.R9 CA#.E 9one

2.( The crypto librar'


2his li3rar, proposes a li ite" nu 3er of cr,pto!raphic functions. Currentl, these functions offer ainl, DE&? 2riple5DE&? an" &:A1 3ase" transfor ations.

2.(.1
&J9%P&I&

cr'pto.create>context

cr(pto.create_context7algorit/m D9ke(E8 DE&CRIP2I%9 2his function creates a cr,pto!raphic Lconte$tM that hol"s a "escription of a cr,pto!raphic al!orith ? alon! *ith a FoptionalG /e,. 2he create" conte$t is later use" as a para eter to other !eneric functions in the crypto li 3 r a r , ? s uc h a s cr(pto.encr(pt78, Chapter 4 De1elop ent li3rar, ++

cr(pto.mac78, cr(pto.digest78, Z 2he first para eter algorit/m allo*s to "escri3e the cr,pto!raphic al!orith use". It can currentl, ta/e the follo*in! 1aluesB +lgorithm cr(pto.,%L_-ES_E+3 cr(pto.,%L_-ES_+3+ cr(pto.,%L_-ES2_E-E_E+3 cr(pto.,%L_-ES2_E-E_+3+ &escription &i ple DE& in EC7 &i ple DE& is C7C o"e Fso no ICG. o"e. to 3e

2riple DE& *ith a "ou3le len!th 112 3it /e, in EC7 o"e Fno ICG. 2riple DE& *ith a "ou3le len!th 112 3it /e, in C7C o"e. I&% -7-7 MAC etho" ( *ith a 112 3it /e,B a si ple DE& C7C MAC iteration *ith triple DE& on the final 3loc/. 2he &:A1 "i!est al!orith .

cr(pto.,%L_$S"OKOK_M3 cr(pto.,%L_S',C

&o e of the pre1ious al!orith s onl, operate on "ata that has 3een pa""e" to a reach a proper siAe? *hich is usuall, a ultiple of a "efine" L3loc/ siAeM. 2he 1alue of algorit&* can 3e use" to specif, the pa""in! etho" that is use"? 3, co 3inin! F*ith the KI@ operatorG one of the follo*in! 1alues to the al!orith pre1iousl, specifie"B Padding method cr(pto.!,-_PE " cr(pto.!,-_"!@_65_PE " &escription A"" 0@s if nee"e" to reach 3loc/ siAe. If the siAe of clearte$t is not alrea", a ultiple of 3loc/ siAe then a"" one 3,te +,-+ an" then 0@s? if nee"e"? to reach 3loc/ siAe. I&% -7-7 pa""in! etho" 2 Fa"" a an"ator, 3,te +,-+ an" pa" *ith optional 0@s to reach 3loc/ siAeG.

cr(pto.!,-_$S"OKOK_!2

2he optional 3,testrin! .ey ust 3e use" to specif, the 1alue of the cr,pto!raphic /e, use" for encr,ption or MAC al!orith s F3ut is i!nore" for hash al!orith sG. RE2.R9 CA#.E 2his function returns a 3,testrin! representin! the create" conte$t. Pro!ra consi"er the result as an opa=ue 1alue an" shoul" not o"if, its content. ers shoul"

Chapter 4 De1elop ent li3rar,

+5

2.(.2
&J9%P&I&

cr'pto.decr'pt

cr(pto.decr(pt7context9 data D9 i)E8


DE&CRIP2I%9

Decr,pt the 3,testrin! data, usin! the /e, an" al!orith )hen the "ecr,ption al!orith re=uires an initial 1ector? it para eters an" the return 1alue are 8 3it *i"e 3,testrin!s. RE2.R9 CA#.E 2his function returns the "ecr,pte" "ata as a 3,testrin!.

pro1i"e" in conte,t.

ust 3e specifie" in i). All

2.(.!
&J9%P&I&

cr'pto.digest

cr(pto.digest7context9 data8
DE&CRIP2I%9

Co pute the "i!est Falso often calle" a hashG of data, usin! the al!orith context. All para eters an" the return 1alue are 8 3it *i"e 3,testrin!s. RE2.R9 CA#.E 2his function returns the "i!est 1alue as a 3,testrin!.

pro1i"e" in

2.(.$
&J9%P&I&

cr'pto.encr'pt

cr(pto.encr(pt7context9 data D9 i)E8


DE&CRIP2I%9

Encr,pt the 3,testrin! data, usin! the /e, an" al!orith )hen the encr,ption al!orith re=uires an initial 1ector? it para eters an" the return 1alue are 8 3it *i"e 3,testrin!s. RE2.R9 CA#.E 2his function returns the encr,pte" "ata as a 3,testrin!. Chapter 4 De1elop ent li3rar,

pro1i"e" in context.

ust 3e specifie" in i/. All

+4

2.(.(
&J9%P&I&

cr'pto.mac

cr(pto.mac7context9 data8
DE&CRIP2I%9

Co putes the MAC FMessa!e Authentication Co"eG of ata, usin! the /e, an" al!orith pro1i"e" in context. All para eters an" the return 1alue are 8 3it *i"e 3,testrin!s. RE2.R9 CA#.E 2his function returns the MAC as a 3,testrin!. 2he resultin! MAC is not truncate".

2.2 The nodes librar'


2he no"es li3rar, allo*s to a""? "elete? representation of the car" content. o"if, an" fin" no"es in the car" 1ie*

2.2.1
&J9%P&I&

nodes.append

nodes.append7parent D9 attr_arra(E8 parent>append7Dattr_arra(E8


DE&CRIP2I%9

2his function a""s a no"e in the car" tree structure. 2he ne* no"e *ill 3e appen"e" to the chil"ren of the no"e i"entifie" 3, the no#e re,erence parent. If parent is nodes.root78 the ne* no"e *ill 3e a""e" at the top le1el Fsee 4.4.10G. 2he content of the ne* no"e can optionall, 3e specifie" throu!h attr_arra(? a #.A associati1e arra, of F/e,?1alueG pairs "escri3in! the content of the ne* no"e. >or e$a ple? to create a no"e *ith the la3el LfooM *ith a LfileM icon? ,ou *oul" pass the 1alue :classname;<file<9 la*el;<foo<= a s attr_arra(. )hile ,ou a, specif, an, F/e,?1alueG pairs? the nodes li3rar, !i1es a specific eanin! to the follo*in! /e,sB classname> a strin! that pro1i"es a""itional infor ation "escri3in! the t,pe of "ata represente" 3, the no"e. 2his 1alue *ill affect the choice of the icon that is associate" *ith the no"e in the "ispla,e" car" tree structure. 2he follo*in! Chapter 4 De1elop ent li3rar, +7

classname 1alues are associate" *ith a "istinct iconB LapplicationM? L3loc/M? Lcar"M? LfileM? Lrecor"M an" Lite M. If classname is nil or unreco!niAe"? it *ill 3e set to the "efault 1alue Lite M. la*el> a strin! that "escri3es the "ata that is represente" 3, the no"e in hu an rea"a3le for Fsuch as a LfileM or a L"ate of 3irthM for e$a pleG. id> a strin! that i"entifies the no"e uni=uel, *ithin a conte$t Fsuch as a nu 3er or a uni=ue na eG. siAe> is a nu 3er "escri3in! the len!th of the "ata ele ent associate" to the no"e. If set? it *ill 3e "ispla,e" in the secon" colu n of the car" 1ie* in the .I. 2al> a 3,testrin! that "escri3es the ra* "ata presente" in the thir" colu n of the car" 1ie* in the .I. alt is an optional strin! that "escri3es the interprete" "ata presente" in the thir" colu n of the car" 1ie* in the .I. mime-t(pe is a strin! that is use" to optionall, in"icate ho* to ren"er 1isuall, the 1alue specifie" 3, the )al attri3ute F"escri3e" a3o1eG *hen the alt attri3ute is a3sent. Currentl, this is onl, use" to ren"er i a!es 3, specif,in! i a!e "ata in the 1al attri3ute an" settin! i e5t,pe to Limage/&pegM for e$a ple. 2hese attri3utes can 3e also a""e" or function Fsee 4.4.11G. RE2.R9 CA#.E .pon success the function returns a no#e re,erence to the ne*l, create" no"e. If the function fails? it returns nil. o"ifie" in a no"e *ith the node.set_attri*ute78

2.2.2
&J9%P&I&

nodes.attributes

for k9) in nodes.attri*utes7node_ref8 do ... end for k9) in node_ref>attri*utes78 do ... end
DE&CRIP2I%9

2his function pro1i"es an iterator for the attri3utes of node_ref? a no"e reference. 2he attri3utes are represente" as /e,81alue pairs Fin the e$a ple here k9)G. Chapter 4 De1elop ent li3rar, +8

RE2.R9 CA#.E

Returns an iterator for use in a for loop.

2.2.!
&J9%P&I&

nodes.children

for c/ild in nodes.c/ildren7parent8 do ... end for c/ild in parent>c/ildren78 do ... end
DE&CRIP2I%9

2his function pro1i"es an iterator for the chil" no"es of parent? a no"e reference. 2he iterator returns a reference to each chil" of the parent no"e Fin the e$a ple here c/ildG.
RE2.R9 CA#.E

Returns an iterator for use in a for loop.

2.2.$
&J9%P&I&

nodes.find

for node_ref in nodes.find7root9 attr_arra(8 do ... end for node_ref in root>find7attr_arra(8 do ... end
DE&CRIP2I%9

2his function pro1i"es an iterator that *ill return all no"es in the car" tree 1ie* roote" at root? *hich atch the attri3utes "efine" in attr_arra(. 2he attri3ute arra, attr_arra( is a #.A associati1e arra, of /e,81alue pairs as "efine" for the function nodes.append78 Fsee 4.4.1G. A no"e is consi"ere" as atchin! attr_arra( if all /e, 1alue8pairs "efine" in attr_arra( e$ist in the no"e an" ha1e the sa e 1alue. >or e$a ple if *e use :la*el;<file<= as attr_arra(? the iterator *ill !o throu!h all no"es that ha1e the la3el Chapter 4 De1elop ent li3rar, +-

LfileM? re!ar"less of other attri3utes the no"es


RE2.R9 CA#.E

a, ha1e.

Returns an iterator for use in a for loop.

2.2.(
&J9%P&I&

nodes.find>first

nodes.find_first7root9 attr_arra(8 root>find_first7attr_arra(8


DE&CRIP2I%9

2his function returns the first no"e in the car" tree 1ie* roote" at root? *hich arra, of /e,81alue pairs that is use" for node.find78 Fsee 4.4.+G.
RE2.R9 CA#.E

atches the

attri3utes "efine" in attr_arra(. 2he attri3ute arra, attr_arra( is a #.A associati1e atchin! follo*in! the sa e rules use" for

A no"e reference or nil if no no"e is foun".

2.2.2
&J9%P&I&

nodes.from>xml

nodes.from_xml7parent9xml_string8 parent>from_xml7xml_string8
DE&CRIP2I%9

2his function appen"s no"es "escri3e" in the 'M# e$pression xml_string to parent. 2he e$pression xml_string "escri3es a su3tree of no"es? Chapter 7 .
RE2.R9 CA#.E

follo*in! the s,nta$ "efine" in

2his function returns true in case of success an" false other*ise.

Chapter 4 De1elop ent li3rar,

50

2.2.4
&J9%P&I&

nodes.get>attribute

nodes.get_attri*ute7node_ref9 attr_name8 node_ref>get_attri*ute7attr_name8


DE&CRIP2I%9

6ets the 1alue of an attri3ute in the no"e i"entifie" 3, node_ref. 2he na e of the attri3ute to retrie1e is i"entifie" 3, the strin! attr_name. 2he attri3utes na e" LclassnameM? Lla*elM? LidM? LaltM? L)alM? Lmime-t(peM an" LsiAeM refer to the para eters passe" to the function nodes.append78 as "escri3e" in section 4.4.1. RE2.R9 CA#.E 2his function returns a strin! upon success an" nil other*ise.

2.2.8
&J9%P&I&

nodes.parent

nodes.parent7node_ref8 node_ref>parent78
DE&CRIP2I%9

Returns the parent no"e of the no"e reference" 3, node_ref. If the no"e reference" 3, node_ref has no parent the function return nil. RE2.R9 CA#.E Return a no"e reference upon success or nil other*ise.

2.2.9
&J9%P&I&

nodes.remo0e

nodes.remo)e7node_ref8 node_ref>remo)e78

Chapter 4 De1elop ent li3rar,

51

DE&CRIP2I%9 Deletes the no"e i"entifie" 3, node_ref as *ell as all its chil"ren. RE2.R9 CA#.E 2he function returns true upon success an" false other*ise.

2.2.1?
&J9%P&I&

nodes.root

nodes.root78
DE&CRIP2I%9

2his function si pl, return the a3solute root of the car" 1ie* tree? *hich is in1isi3le. 2his is t,picall, use" to create the first no"e in the tree in co 3ination *ith node.append78 Fe.!. Lnode.root78>append7...8 MG
RE2.R9 CA#.E

A no"e reference.

2.2.11
&J9%P&I&

nodes.set>attribute

nodes.set_attri*ute7node9 attr_name9 attr_)alue8 node>set_attri*ute7attr_name9 attr_)alue8


DE&CRIP2I%9

&ets an attri3ute in the no"e i"entifie" 3, node_ref. 2he attri3ute to set is i"entifie" 3, the strin! attr_name an" ta/es the 1alue in"icate" 3, the strin! attr_)alue. 2he attri3utes na e" LclassnameM? Lla*elM? LidM? LaltM? L)alM? Lmime-t(peM an" LsiAeM refer to the para eters passe" to the function nodes.append78 as "escri3e" in section 4.4.1. 2he pro!ra RE2.R9 CA#.E 2his function returns true upon success an" false other*ise. er can associate an, ar3itrar, attri3ute *ith a no"e.

Chapter 4 De1elop ent li3rar,

52

2.2.12
&J9%P&I&

nodes.to>xml

nodes.to_xml7node8 node>to_xml78 DE&CRIP2I%9 Returns an 'M# representation of the su35tree that has node as a root. If node is nodes.root78 the representation of the *hole tree is returne". RE2.R9 CA#.E 2his function returns a strin! upon success. If the function fails? it returns nil.

2.4 The ui librar'


2he ui li3rar, allo*s to control so e ele ents of the user interface of CARDPEEK? an" in particular the tree structure representin! the "ata e$tracte" fro the car". 2he tree structure representin! car" "ata is co pose" of no"es? each represente" on one ro* in the car" tree 1ie*. &o e function in the ui li3rar, are use" to anipulate these no"es For ro*sG? allo*in! to a""? re o1e or e"it the . 2hese functions i"entif, each no"e 3, a no"e reference? *hich is an internal opa=ue t,pe. 2he ui li3rar, functions are "escri3e" in the follo*in! para!raphs.

2.4.1
&J9%P&I&

ui.Buestion

ui.Question7text9 *uttons8
DE&CRIP2I%9

As/s the user a =uestion re=uestin! hi to ans*er 3, selectin! a response. 2he =uestion is "escri3e" in the strin! te,t, *hile the set of possi3le ans*ers "escri3e" in the #.A arra, b0ttons. Each ele ent in the arra, b0ttons is strin! representin! a possi3le ans*er. RE2.R9 CA#.E .pon success? the function returns the in"e$ of the ans*er selecte" 3, the user in the ta3le b0ttons F#.A ta3le in"ices are usuall, nu 3ers !reater or e=ual to 1G. .pon failure the function returns 0. Chapter 4 De1elop ent li3rar, 5(

E'AMP#E

ui.Question7<Ruit t/e scriptS<9 : <(es<9 <no< = 8

2.4.2
&J9%P&I&

ui.readline

ui.readline7text D9len D9default_)alueEE8


DE&CRIP2I%9

Re=uest the user to enter a te$t strin!. 2he user@s input can optionall, 3e li ite" to len characters an" can also optionall, hol" a pre"efine" 1alue default_)alue. RE2.R9 CA#.E 2he function returns the user@s input upon success an" false other*ise.
E'AMP#E

ui.readline7<Enter !$4 code><9 J9 <5555<8

2.4.!
&J9%P&I&

ui.load>0ie#

ui.load_)iew7file_name8
DE&CRIP2I%9

#oa"s the tree fro the file for at. RE2.R9 CA#.E

the 'M# file na e" file_name. &ee Chapter 7 for a "escription of

2he function returns true upon success an" false other*ise.

2.4.$
&J9%P&I&

ui.sa0e>0ie#

ui.sa)e_)iew7file_name8
DE&CRIP2I%9

&a1es the tree in 'M# for at insi"e the file na e" file_name. &ee Chapter 7 for a "escription of the file for at.

Chapter 4 De1elop ent li3rar,

5+

RE2.R9 CA#.E 2he function returns tr0e upon success an" false other*ise.

2.8 The log librar'


2he log li3rar, contains <ust one function "escri3e" 3elo*? *hich allo*s to print essa!es in the Llo!M ta3 of the application.

2.8.1
&J9%P&I&

log.print

log.print7le)el9 text8
DE&CRIP2I%9

Prints a

essa!e text in the console *in"o*. essa!e that is printe". le)el can ta/e the follo*in! " .

le/el "escri3es the t,pe of

1aluesB log.$4#"? log.-E3UL? log.T, 4$4L? or log.E

All essa!es printe" on the screen *ith this function are also sa1e" in the file L!"#$%/.cardpeek.logM. RE2.R9 CA#.E 9one.

2.9 Other libraries


2.9.1 The treeflex librar'

As of 1ersion 0.8? the tree'ex li3rar, is "eprecate". All functions pre1iousl, pro1i"e" 3, this li3rar, are no* a1aila3le throu!h the nodes li3rar,.

2.9.2

The country_codes and currency_codes libraries

2hese li3rar, pro1i"e con1enience functions to translate currenc, an" countr, co"es in hu an rea"a3le na es.

2.9.!

The en1545 librar'


anipulate "ata use" in Cal,pso car"s that follo*

2his li3rar, pro1i"es tools to CE98I&% 15+5.

Chapter 4 De1elop ent li3rar,

55

2.8.$ The strict librar'


2his li3rar, forces #.A 1aria3les to 3e e$plicitl, "eclare"? an" thus re"uces pro!ra errors. in!

2.8.( The tlv librar'


2his li3rar, is 3uilt upon the asn1 li3rar, an" pro1i"es auto ate" tools to anal,Ae an" "ispla, co ple$ A&91 2#C "ata o3<ects in CARDPEEK.

Chapter 4 De1elop ent li3rar,

54

Chapter 4 Cile format

2he car" 1ie* presente" in CARDPEEK can 3e sa1e or i porte" in 'M# for at. 2his for at is =uite strai!htfor*ar"? as sho*n in the follo*in! e$a ple? *hich *as create" *ith the atr scriptB USxml )ersion;<C.5<SV UcardpeekV UversionV5.6U/versionV UnodeV Uattr name;<classname<VcardU/attrV Uattr name;<la*el<V,@ U/attrV UnodeV Uattr name;<classname<V*lockU/attrV Uattr name;<la*el<Vcold ,@ U/attrV Uattr name;<siAe<VC5U/attrV Uattr name;<)al< t(pe;<*(tes<V6>33KGC35555JJ5OE,O555U/ attrV U/nodeV U/nodeV U/cardpeekV 2he for at of the 'M# car" 1ie* file is constructe" accor"in! to the follo*in! rulesB 2he root ele ent of the 'M# structure is UcardpeekV, *hich contains one [versionV ele ent follo*e" 3, one or ore UnodeV ele ents. 2he UversionV ele ent contains the file for at 1ersion nu 3er Fcurrentl, 0.8G. A UnodeV ele ent a, contain 3oth UnodeV an" UattrV ele ents. an"ator, 'M# attri3ute Lna eM *hich "escri3es the

A UattrV ele ent has one

na e of a Lno"e attri3uteM associate" *ith a no"e in the tree 1ie*? *hile the te$t insi"e the UattrV ele ent "escri3es the 1alue associate" *ith that Lno"e attri3uteM. 2he UattrV ele ent has one optional 'M# attri3utes L t(peM that is use" to specif, Chapter 7 >ile for at 57

the for at of the content "ata? *hen it is not a stan"ar" strin!. Currentl,? the attri3ute t(pe can onl, ta/e one 1alue L *(tesM to in"icate that the content "ata is an enco"e" 3,testrin!. A no"e can ha1e an, nu 3er of Lno"e attri3utesM "efine" 3, an UattrV ele ent. :o*e1er? so e Lno"e attri3utesM ha1e a specific eanin! for CARDPEEK Fsee 4.4.1GB Uattr name;<classname<V "escri3es the t,pe of no"e Fa file? an application? a "ata 3loc/? a "ata ite ? etc.G an" its 1alue *ill "eter ine the icon use" to represent the no"e on the screen in the application. Uattr name;<la*el<V "escri3es the la3el !i1en to the no"e on the screen Ffirst colu nG. Uattr name;<id<V "escri3es the i" of the no"e "ispla,e" on the screen Ffirst colu nG. Uattr name;<siAeWV "escri3es the siAe that is "ispla,e" on the screen Fsecon" colu nG. Uattr name;<)al< t(pe;<*(tes<V "escri3es the 1alue of the 3,testrin! associate" *ith a no"e Fan" represente" in the thir" colu n on the screenG. 2his 3,testrin! is represente" as a *i"th 1alue follo*e" 3, LBM an" the "i!its representin! the 3,testrin! Fthis is e=ui1alent to the 2S output for at of the *(tes.format78 functionG. Uattr name;<alt<V "escri3es an alternati1e representation of the 1alue associate" *ith a no"e an" represente" in si ple te$t for at. Uattr name;Wmime-t(peWV is an in"icator of ho* to ren"er the "ata "escri3e" 3, the )al attri3ute in the a3sence of the alt attri3ute Fsee 4.4.1G. 9o"e attri3ute na es statin! *ith a inus si!n Fe$a pleB L -makup-)alMG are consi"ere" as te porar, attri3utes an" are not e$porte" or sa1e" in 'M# for at. 2he, are use" internall, 3, CARDPEEK or script pro!ra s. )ote1 t h e CARDPEEK 'M# for at has chan!e" in CARDPEEK 1ersion 0.8 an" is not co pati3le *ith pre1ious 1ersions.

Chapter 7 >ile for at

58

Chapter 8 License

CARDPEEK is free soft*areB ,ou can re"istri3ute it an"8or o"if, it un"er the ter s of the 69. 6eneral Pu3lic #icense as pu3lishe" 3, the >ree &oft*are >oun"ation? either 1ersion ( of the #icense? or Fat ,our optionG an, later 1ersion.

As an e$e ption to the 69. 6eneral Pu3lic #icense? co pilin!? lin/in!? an"8or usin! %pen&&# is allo*e". CARDPEEK is "istri3ute" in the hope that it *ill 3e useful? 3ut )I2:%.2 A9J )ARRA92JE *ithout e1en the i plie" *arrant, of MERC:A92A7I#I2J or >I29E&& >%R A PAR2IC.#AR P.RP%&E. &ee the 69. 6eneral Pu3lic #icense for ore "etails. Jou shoul" ha1e recei1e" a cop, of the 69. 6eneral Pu3lic #icense alon! *ith this pro!ra . If not? see http://www.gnu.org/licenses/.

Chapter 8 #icense

5-