1.\" $OpenBSD: sectok.3,v 1.10 2003/07/08 12:04:37 jmc Exp $ 2.\" 3.\" Jim Rees <rees@umich.edu> 4.\" CITI Smartcard development <smartcards@umich.edu> 5.\" 6.\" copyright 2000 7.\" the regents of the university of michigan 8.\" all rights reserved 9.\" 10.\" permission is granted to use, copy, create derivative works 11.\" and redistribute this software and such derivative works 12.\" for any purpose, so long as the name of the university of 13.\" michigan is not used in any advertising or publicity 14.\" pertaining to the use or distribution of this software 15.\" without specific, written prior authorization. if the 16.\" above copyright notice or any other identification of the 17.\" university of michigan is included in any copy of any 18.\" portion of this software, then the disclaimer below must 19.\" also be included. 20.\" 21.\" this software is provided as is, without representation 22.\" from the university of michigan as to its fitness for any 23.\" purpose, and without warranty by the university of 24.\" michigan of any kind, either express or implied, including 25.\" without limitation the implied warranties of 26.\" merchantability and fitness for a particular purpose. the 27.\" regents of the university of michigan shall not be liable 28.\" for any damages, including special, indirect, incidental, or 29.\" consequential damages, with respect to any claim arising 30.\" out of or in connection with the use of the software, even 31.\" if it has been or is hereafter advised of the possibility of 32.\" such damages. 33.Dd August 3, 2001 34.Dt SECTOK 3 35.Os 36.Sh NAME 37.Nm sectok 38.Nd library for communicating with ISO 7816 smartcards 39.Sh SYNOPSIS 40.Fd #include <sectok.h> 41.Ft int 42.Fn sectok_open "int rn" "int flags" "int *swp" 43.Ft int 44.Fn sectok_friendly_open "const char *rn" "int flags" "int *swp" 45.Ft int 46.Fn sectok_xopen "int rn" "int flags" "char *config_path" "char *driver_path" "int *swp" 47.Ft int 48.Fn sectok_reset "int fd" "int flags" "unsigned char *atr" "int *swp" 49.Ft int 50.Fo sectok_apdu 51.Fa "int fd" 52.Fa "int cla" 53.Fa "int ins" 54.Fa "int p1" 55.Fa "int p2" 56.Fa "int ilen" 57.Fa "unsigned char *ibuf" 58.Fa "int olen" 59.Fa "unsigned char *obuf" 60.Fa "int *swp" 61.Fc 62.Ft int 63.Fn sectok_cardpresent "int fd" 64.Ft int 65.Fn sectok_close "int fd" 66.Ft int 67.Fn sectok_selectfile "int fd" "int cla" "unsigned char *fid" "int *swp" 68.Ft void 69.Fn sectok_fmt_fid "char *fname" "size_t fnamelen" "unsigned char *fid" 70.Ft int 71.Fn sectok_parse_atr "int fd" "int flags" "unsigned char *atr" "int len" "struct scparam *param" 72.Ft void 73.Fn sectok_parse_fname "char *buf" "unsigned char *fid" 74.Ft int 75.Fn sectok_parse_input "char *ibuf" "unsigned char *obuf" "int olen" 76.Ft int 77.Fn sectok_get_input "FILE *f" "unsigned char *obuf" "int omin" "int olen" 78.Ft int 79.Fn sectok_fdump_reply "FILE *f" "unsigned char *p" "int n" "int sw" 80.Ft int 81.Fn sectok_dump_reply "unsigned char *p" "int n" "int sw" 82.Ft void 83.Fn sectok_print_sw "int sw" 84.Ft "char *" 85.Fn sectok_get_sw "int sw" 86.Ft "char *" 87.Fn sectok_get_ins "int ins" 88.Ft int 89.Fn sectok_swOK "int sw" 90.Sh DESCRIPTION 91.Nm sectok 92provides initialization, input, output, and other basic routines for ISO 937816 smart cards. 94Many of the routines return a status word. 95This will either be an error code as given in the include file, 96or an SW1/SW2 pair as specified in ISO 7816. 97.Pp 98.Fn sectok_open 99opens a connection to a smart card via serial port number 100.Fa rn . 101Ports are 102numbered from 0, which corresponds to /dev/tty00 on UNIX. 103If there is no card in the reader, 104.Fn sectok_open 105will either wait for card insertion, or if flag 106.Dv STONOWAIT 107is given, it will return immediately with error 108.Dv STENOCARD . 109.Fa swp 110points to a status word that will be set on return. 111.Pp 112.Fn sectok_friendly_open 113opens a connection to a smart card via a reader device name 114.Fa rn . 115Mapping from reader name to serial port number is the same as used in 116.Fn sectok_open . 117For other arguments and return values, see 118.Fn sectok_open . 119.Pp 120.Fn sectok_reset 121resets the card and returns the ATR in the buffer pointed to by 122.Fa atr 123if it is not 124.Dv NULL . 125If the 126.Dv STRFORCE 127flag is given, a connection to the card will be established 128using default protocol parameters even if the card ATR is illegal. 129.Pp 130.Fn sectok_apdu 131sends an APDU to the card with optional IN and OUT data. 132.Bl -tag -width Ds 133.It Fa cla 134application class 135.It Fa ins 136instruction code 137.It Fa p1 , Fa p2 138per ISO 7816-3 or application dependent 139.It Fa ilen 140length of IN data 141.It Fa ibuf 142pointer to IN data 143.It Fa olen 144length of OUT data 145.It Fa obuf 146pointer to OUT data 147.It Fa swp 148pointer to return status word 149.El 150.Pp 151.Fn sectok_cardpresent 152returns whether a card is present in the reader. 153.Pp 154.Fn sectok_close 155closes a connection to a smart card. 156.Pp 157.Fn sectok_selectfile 158selects a file given its FID by sending a "select" apdu to the card. 159.Pp 160.Fn sectok_fmt_fid 161returns a printable name for a FID. 162.Pp 163.Fn sectok_parse_atr 164parses a card ATR and returns the protocol parameters. 165If the 166.Dv STRV 167flag is given it will print the parameters to standard out. 168.Pp 169.Fn sectok_parse_fname 170translates a printable name to a FID. 171.Pp 172.Fn sectok_print_sw 173looks up the error message string affiliated with a status word 174and writes it to standard out. 175.Pp 176.Fn sectok_swOK 177returns 1 if 178.Dv sw 179indicates success, or 0 if it indicates failure. 180.Sh SEE ALSO 181.Xr sectok 1 182.Sh HISTORY 183.Nm 184first appeared in 185.Ox 3.0 . 186.Sh AUTHORS 187Jim Rees and others at University of Michigan 188Center for Information Technology Integration (CITI). 189.\" 190