.\" $OpenBSD: sectok.3,v 1.10 2003/07/08 12:04:37 jmc Exp $ .\" .\" Jim Rees .\" CITI Smartcard development .\" .\" copyright 2000 .\" the regents of the university of michigan .\" all rights reserved .\" .\" permission is granted to use, copy, create derivative works .\" and redistribute this software and such derivative works .\" for any purpose, so long as the name of the university of .\" michigan is not used in any advertising or publicity .\" pertaining to the use or distribution of this software .\" without specific, written prior authorization. if the .\" above copyright notice or any other identification of the .\" university of michigan is included in any copy of any .\" portion of this software, then the disclaimer below must .\" also be included. .\" .\" this software is provided as is, without representation .\" from the university of michigan as to its fitness for any .\" purpose, and without warranty by the university of .\" michigan of any kind, either express or implied, including .\" without limitation the implied warranties of .\" merchantability and fitness for a particular purpose. the .\" regents of the university of michigan shall not be liable .\" for any damages, including special, indirect, incidental, or .\" consequential damages, with respect to any claim arising .\" out of or in connection with the use of the software, even .\" if it has been or is hereafter advised of the possibility of .\" such damages. .Dd August 3, 2001 .Dt SECTOK 3 .Os .Sh NAME .Nm sectok .Nd library for communicating with ISO 7816 smartcards .Sh SYNOPSIS .Fd #include .Ft int .Fn sectok_open "int rn" "int flags" "int *swp" .Ft int .Fn sectok_friendly_open "const char *rn" "int flags" "int *swp" .Ft int .Fn sectok_xopen "int rn" "int flags" "char *config_path" "char *driver_path" "int *swp" .Ft int .Fn sectok_reset "int fd" "int flags" "unsigned char *atr" "int *swp" .Ft int .Fo sectok_apdu .Fa "int fd" .Fa "int cla" .Fa "int ins" .Fa "int p1" .Fa "int p2" .Fa "int ilen" .Fa "unsigned char *ibuf" .Fa "int olen" .Fa "unsigned char *obuf" .Fa "int *swp" .Fc .Ft int .Fn sectok_cardpresent "int fd" .Ft int .Fn sectok_close "int fd" .Ft int .Fn sectok_selectfile "int fd" "int cla" "unsigned char *fid" "int *swp" .Ft void .Fn sectok_fmt_fid "char *fname" "size_t fnamelen" "unsigned char *fid" .Ft int .Fn sectok_parse_atr "int fd" "int flags" "unsigned char *atr" "int len" "struct scparam *param" .Ft void .Fn sectok_parse_fname "char *buf" "unsigned char *fid" .Ft int .Fn sectok_parse_input "char *ibuf" "unsigned char *obuf" "int olen" .Ft int .Fn sectok_get_input "FILE *f" "unsigned char *obuf" "int omin" "int olen" .Ft int .Fn sectok_fdump_reply "FILE *f" "unsigned char *p" "int n" "int sw" .Ft int .Fn sectok_dump_reply "unsigned char *p" "int n" "int sw" .Ft void .Fn sectok_print_sw "int sw" .Ft "char *" .Fn sectok_get_sw "int sw" .Ft "char *" .Fn sectok_get_ins "int ins" .Ft int .Fn sectok_swOK "int sw" .Sh DESCRIPTION .Nm sectok provides initialization, input, output, and other basic routines for ISO 7816 smart cards. Many of the routines return a status word. This will either be an error code as given in the include file, or an SW1/SW2 pair as specified in ISO 7816. .Pp .Fn sectok_open opens a connection to a smart card via serial port number .Fa rn . Ports are numbered from 0, which corresponds to /dev/tty00 on UNIX. If there is no card in the reader, .Fn sectok_open will either wait for card insertion, or if flag .Dv STONOWAIT is given, it will return immediately with error .Dv STENOCARD . .Fa swp points to a status word that will be set on return. .Pp .Fn sectok_friendly_open opens a connection to a smart card via a reader device name .Fa rn . Mapping from reader name to serial port number is the same as used in .Fn sectok_open . For other arguments and return values, see .Fn sectok_open . .Pp .Fn sectok_reset resets the card and returns the ATR in the buffer pointed to by .Fa atr if it is not .Dv NULL . If the .Dv STRFORCE flag is given, a connection to the card will be established using default protocol parameters even if the card ATR is illegal. .Pp .Fn sectok_apdu sends an APDU to the card with optional IN and OUT data. .Bl -tag -width Ds .It Fa cla application class .It Fa ins instruction code .It Fa p1 , Fa p2 per ISO 7816-3 or application dependent .It Fa ilen length of IN data .It Fa ibuf pointer to IN data .It Fa olen length of OUT data .It Fa obuf pointer to OUT data .It Fa swp pointer to return status word .El .Pp .Fn sectok_cardpresent returns whether a card is present in the reader. .Pp .Fn sectok_close closes a connection to a smart card. .Pp .Fn sectok_selectfile selects a file given its FID by sending a "select" apdu to the card. .Pp .Fn sectok_fmt_fid returns a printable name for a FID. .Pp .Fn sectok_parse_atr parses a card ATR and returns the protocol parameters. If the .Dv STRV flag is given it will print the parameters to standard out. .Pp .Fn sectok_parse_fname translates a printable name to a FID. .Pp .Fn sectok_print_sw looks up the error message string affiliated with a status word and writes it to standard out. .Pp .Fn sectok_swOK returns 1 if .Dv sw indicates success, or 0 if it indicates failure. .Sh SEE ALSO .Xr sectok 1 .Sh HISTORY .Nm first appeared in .Ox 3.0 . .Sh AUTHORS Jim Rees and others at University of Michigan Center for Information Technology Integration (CITI). .\"