From 34b5c87399a11d99c4bd41e06ce38082bfd54d7e Mon Sep 17 00:00:00 2001 From: okir Date: Thu, 3 Apr 2003 14:34:20 +0000 Subject: [PATCH] - wrote a bunch of manual pages git-svn-id: https://www.opensc-project.org/svnp/opensc/trunk@976 c6295689-39f2-0310-b995-f0e70906c6a9 --- docs/sc_connect_card.3 | 30 ++++++++++++++++ docs/sc_detect_card_presence.3 | 36 +++++++++++++++++++ docs/sc_disconnect_card.3 | 26 ++++++++++++++ docs/sc_establish_context.3 | 61 +++++++++++++++++++++++++++++++ docs/sc_file.3 | 65 ++++++++++++++++++++++++++++++++++ docs/sc_file_free.3 | 17 +++++++++ docs/sc_file_new.3 | 18 ++++++++++ docs/sc_list_files.3 | 33 +++++++++++++++++ docs/sc_lock.3 | 46 ++++++++++++++++++++++++ docs/sc_read_binary.3 | 54 ++++++++++++++++++++++++++++ docs/sc_read_record.3 | 56 +++++++++++++++++++++++++++++ docs/sc_release_context.3 | 19 ++++++++++ docs/sc_select_file.3 | 38 ++++++++++++++++++++ 13 files changed, 499 insertions(+) create mode 100644 docs/sc_connect_card.3 create mode 100644 docs/sc_detect_card_presence.3 create mode 100644 docs/sc_disconnect_card.3 create mode 100644 docs/sc_establish_context.3 create mode 100644 docs/sc_file.3 create mode 100644 docs/sc_file_free.3 create mode 100644 docs/sc_file_new.3 create mode 100644 docs/sc_list_files.3 create mode 100644 docs/sc_lock.3 create mode 100644 docs/sc_read_binary.3 create mode 100644 docs/sc_read_record.3 create mode 100644 docs/sc_release_context.3 create mode 100644 docs/sc_select_file.3 diff --git a/docs/sc_connect_card.3 b/docs/sc_connect_card.3 new file mode 100644 index 00000000..b31e0f3d --- /dev/null +++ b/docs/sc_connect_card.3 @@ -0,0 +1,30 @@ +.TH sc_connect_card 3 "April 2003" "OpenSC Programmer's Manual +.SH NAME +sc_connect_card \- connect to smart card in reader +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int sc_connect_card(sc_reader_t *" reader ", +.BI " int " slot ", sc_card_t **" card "); +.fi +.SH DESCRIPTION +This function connects to a card in a reader, resets the card +and retrieves the ATR (Answer To Reset). Based on the ATR, it +tries to auto-detect which card driver to use. +.PP +The \fIslot\fP parameter identifies the card reader's slot. +Slots are numbered consecutively, starting at \fB0\fP. +.PP +If OpenSC was able to connect to the card, a pointer to the +\fBsc_card_t\fP object is stored in the location pointer to +by the \fIcard\fP parameter. The card handle should be +released with \fBsc_disconnect_card\fP(3) when no longer in used. +.SH RETURN VALUE +If an error occurred, a negative error code is returned, as described +in \fbsc_error\fP(3). Otherwise, the function will return 0. +.SH SEE ALSO +.BR sc_establish_context (3), +.BR sc_disconnect_card (3). +.SH AUTHOR +This manual page was written by Olaf Kirch diff --git a/docs/sc_detect_card_presence.3 b/docs/sc_detect_card_presence.3 new file mode 100644 index 00000000..7e2e6794 --- /dev/null +++ b/docs/sc_detect_card_presence.3 @@ -0,0 +1,36 @@ +.TH sc_detect_card_presence 3 "April 2003" "OpenSC Programmer's Manual +.SH NAME +sc_detect_card_presence \- detect whether a card is present in a reader +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int sc_detect_card_presence(sc_reader_t *" reader ", +.BI " int " slot "); +.fi +.SH DESCRIPTION +This function is used to detect the presence of a smart card in +a card reader device. The \fIslot\fP parameter identifies the +card reader's slot. Slots are numbered consecutively, starting at +\fB0\fP. +.SH RETURN VALUE +If a card is present, a positive value is returned that is a combination +of the following flags: +.TP +.B SC_SLOT_CARD_PRESENT +A card was detected. +.TP +.B SC_SLOT_CARD_CHANGED +The card was inserted and/or removed since the last call. Note that +this flag is not entirely reliable depending on the OS platform and +middleware. CTAPI doesn't support it at all, for instance, while PCSC +on Windows occasionally returns false CHANGE events. +.PP +If an error occurred, a negative error code is returned, as described +in \fbsc_error\fP(3). +.SH SEE ALSO +.BR sc_establish_context (3), +.BR sc_wait_for_event (3), +.BR sc_connect_card (3). +.SH AUTHOR +This manual page was written by Olaf Kirch diff --git a/docs/sc_disconnect_card.3 b/docs/sc_disconnect_card.3 new file mode 100644 index 00000000..9d191e4b --- /dev/null +++ b/docs/sc_disconnect_card.3 @@ -0,0 +1,26 @@ +.TH sc_disconnect_card 3 "April 2003" "OpenSC Programmer's Manual +.SH NAME +sc_disconnect_card \- disconnect from smart card +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int sc_disconnect_card(sc_card_t *" card ", +.BI " int " action "); +.fi +.SH DESCRIPTION +This function disconnects from a card in a reader, and frees the card +structure. Any locks made by the application must be released before +calling this function. +.PP +The \fIaction\fP parameter is not used at the moment and +should be set to 0. +.PP +The card is not reset nor powered down after the operation. +.SH RETURN VALUE +If an error occurred, a negative error code is returned, as described +in \fbsc_error\fP(3). Otherwise, the function will return 0. +.SH SEE ALSO +.BR sc_connect_card (3). +.SH AUTHOR +This manual page was written by Olaf Kirch diff --git a/docs/sc_establish_context.3 b/docs/sc_establish_context.3 new file mode 100644 index 00000000..d1a8fefa --- /dev/null +++ b/docs/sc_establish_context.3 @@ -0,0 +1,61 @@ +.TH sc_establish_context 3 "April 2003" "OpenSC Programmer's Manual +.SH NAME +sc_establish_context \- establish OpenSC context +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int sc_establish_context(sc_context_t **" ctx ", +.BI " const char *" app_name "); +.fi +.SH DESCRIPTION +This function establishes an OpenSC context. This context is required +in all subsequent calls to OpenSC functions. +.PP +\fIctx\fP is a pointer to a pointer that will receive the allocated context. +.PP +\fIapp_name\fP is a string that identifies the application. This string will +be used to apply application-specific from the \fBopensc.conf\fP(5) configuration +file. If \fBNULL\fP is passed, just the settings specified in the \fBdefault\fP +section apply; otherwise, settings from the section identified by \fIapp_name\fP +will be applied as well. +.PP +The \fBsc_context\fP structure contains the following members, among +others: +.PP +.in +4 +.nf +.B "typedef struct sc_context { +.B " struct sc_reader *reader[SC_MAX_READERS]; +.B " int reader_count; +.B "} sc_context_t; +.fi +.in +.PP +The \fBreader_count\fP field contains the number of readers found by +OpenSC. Information on the individual card readers are stored in +\fBsc_reader\fP objects, which look like follows: +.PP +.in +4 +.nf +.B "typedef struct sc_reader { +.B " char *name; +.B " int slot_count; +.B "} sc_reader_t; +.fi +.in +.PP +Here, \fBname\fP contains a printable name of the reader, and \fBslot_count\fP +shows the number of slots supported by this device. +.PP +Of course, these structs contain other members as well, but applications +usually should not use these fields. +.SH RETURN VALUE +If a context could be established, 0 is returned. Otherwise, a negative +error code is returned, as described in \fbsc_error\fP(3). +.SH SEE ALSO +.BR sc_release_context (3), +.BR sc_detect_card_presence (3), +.BR sc_connect_card (3). +.SH AUTHOR +This manual page was written by Olaf Kirch diff --git a/docs/sc_file.3 b/docs/sc_file.3 new file mode 100644 index 00000000..80508ee6 --- /dev/null +++ b/docs/sc_file.3 @@ -0,0 +1,65 @@ +.TH sc_file 3 "April 2003" "OpenSC Programmer's Manual +.SH NAME +sc_file \- OpenSC file struct +.SH SYNOPSIS +.nf +.B #include +.sp +.B "typedef struct sc_file { +.B " struct sc_path path; +.B " int type, ef_structure; +.B " size_t size; +.B " int id; +.B " +.B " /* record structured files only */ +.B " int record_length; +.B " int record_count; +.B "} sc_file_t; +.fi +.SH DESCRIPTION +This structure describes a file object on a smart card. +It contains the following members: +.TP +.B path +This is the full path to the file, starting at the MF. +.TP +.B type +This is the file type. If can be one of +.BR SC_FILE_TYPE_DF , +.BR SC_FILE_TYPE_WORKING_EF ", or +.BR SC_FILE_TYPE_INTERNAL_EF . +The latter is used by some cards only, and you normally shouldn't +have to deal with these files. +.TP +.B ef_structure +For elementary files (EFs), this field describes the file's +structure. It can be one of +.IP +.nf +.BR SC_FILE_EF_TRANSPARENT +.BR SC_FILE_EF_LINEAR_FIXED +.BR SC_FILE_EF_LINEAR_FIXED_TLV +.BR SC_FILE_EF_LINEAR_VARIABLE +.BR SC_FILE_EF_LINEAR_VARIABLE_TLV +.BR SC_FILE_EF_CYCLIC +.BR SC_FILE_EF_CYCLIC_TLV +.BR SC_FILE_EF_UNKNOWN +.fi +.TP +.B size +gives the file's size in bytes. +.TP +.B id +gives the file's ID, as a 16bit number. +.TP +.BR record_count ", " record_length +For record structured files, \fBrecord_count\fP specifies the +number of records in the file. For files with fixed length +records, \fBrecord_length\fP contains the record length. +.SH SEE ALSO +.BR sc_path (3), +.BR sc_file_new (3), +.BR sc_file_free (3), +.BR sc_select_file (3). +.SH AUTHOR +This manual page was written by Olaf Kirch diff --git a/docs/sc_file_free.3 b/docs/sc_file_free.3 new file mode 100644 index 00000000..5ae758f3 --- /dev/null +++ b/docs/sc_file_free.3 @@ -0,0 +1,17 @@ +.TH sc_file_free 3 "April 2003" "OpenSC Programmer's Manual +.SH NAME +sc_file_free \- release an OpenSC file object +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void sc_file_free(sc_file_t *" file "); +.fi +.SH DESCRIPTION +This function releases a file object previously allocated by +\fBsc_select_file\fP. +.SH SEE ALSO +.BR sc_file (3), +.BR sc_select_file (3). +.SH AUTHOR +This manual page was written by Olaf Kirch diff --git a/docs/sc_file_new.3 b/docs/sc_file_new.3 new file mode 100644 index 00000000..6f3dd52b --- /dev/null +++ b/docs/sc_file_new.3 @@ -0,0 +1,18 @@ +.TH sc_file_new 3 "April 2003" "OpenSC Programmer's Manual +.SH NAME +sc_file_new \- create an OpenSC file object +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "sc_file_t *sc_file_new(void); +.fi +.SH DESCRIPTION +This function creates an empty OpenSC file object, which +can later be passed to \fBsc_create_file\fP(3). +.SH SEE ALSO +.BR sc_file (3), +.BR sc_file_free (3), +.BR sc_create_file (3). +.SH AUTHOR +This manual page was written by Olaf Kirch diff --git a/docs/sc_list_files.3 b/docs/sc_list_files.3 new file mode 100644 index 00000000..7aa55172 --- /dev/null +++ b/docs/sc_list_files.3 @@ -0,0 +1,33 @@ +.TH sc_list_files 3 "April 2003" "OpenSC Programmer's Manual +.SH NAME +sc_list_files \- list files on a smart card +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int sc_list_files(sc_card_t *" card ", +.BI " unsigned char *" buffer ", +.BI " size_t " buflen "); +.fi +.SH DESCRIPTION +This function lists all files in the currently selected DF, +and stores the the file IDs as big-endian 16bit words +in \fIbuffer\fP. If the supplied buffer is too small to +hold all file IDs, the listing is silently truncated. +.PP +.SH RETURN VALUE +If an error occurred, a negative error code is returned, as described +in \fbsc_error\fP(3). Otherwise, the function will return the +number of bytes stored in \fIbuffer\fP. +.SH SEE ALSO +.BR sc_file (3), +.BR sc_path (3), +.BR sc_establish_context (3), +.BR sc_select_file (3), +.BR sc_read_binary (3), +.BR sc_read_record (3), +.BR sc_delete_file (3), +.BR sc_create_file (3), +.BR sc_file_free (3). +.SH AUTHOR +This manual page was written by Olaf Kirch diff --git a/docs/sc_lock.3 b/docs/sc_lock.3 new file mode 100644 index 00000000..c858939c --- /dev/null +++ b/docs/sc_lock.3 @@ -0,0 +1,46 @@ +.TH sc_lock 3 "April 2003" "OpenSC Programmer's Manual +.SH NAME +sc_lock, sc_unlock \- lock or unlock smart card +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int sc_lock(sc_card_t *" card "); +.BI "int sc_unlock(sc_card_t *" card "); +.fi +.SH DESCRIPTION +These functions handle locking of smart cards, in order to prevent +concurrent access to the same card by different users. +.PP +Locking is important to prevent unauthorized access to the card +after presenting the PIN, for instance. +.PP +After a call to \fBsc_lock\fP, concurrent access by other application +to the same smart card reader is disallowed, provided the reader +middleware supports this (see below). A lock must later be released +by calling \fBsc_unlock\fP. When disconnecting from the card using +\fBsc_disconnect_card\fP, there must not be anymore locks on the +card. +.PP +Calls to \fBsc_lock\fP may be nested, i.e. if \fBsc_lock\fP is called +five times in a row, the lock will not be released until the fifth +call to \fBsc_unlock\fP. +.PP +Note that these functions do not offer mutual exclusion for different +threads within the same application process. Multithread locking is +the application's job (Note that the OpenSC PKCS11 module provides +MT locking facilities, as that's part of the standard). +.SH NOTES +Whether locking is effective depends a lot on the middleware +used to talk to the card reader. CTAPI based drivers for instance +perform no interprocess locking at all. +.PP +The only middleware implementation currently used by OpenSC that +does perform this type of locking is PCSC. +.SH RETURN VALUE +If an error occurred, a negative error code is returned, as described +in \fbsc_error\fP(3). Otherwise, the function will return 0. +.SH SEE ALSO +.BR sc_connect_card (3). +.SH AUTHOR +This manual page was written by Olaf Kirch diff --git a/docs/sc_read_binary.3 b/docs/sc_read_binary.3 new file mode 100644 index 00000000..e8fdb8df --- /dev/null +++ b/docs/sc_read_binary.3 @@ -0,0 +1,54 @@ +.TH sc_read_binary 3 "April 2003" "OpenSC Programmer's Manual +.SH NAME +sc_read_binary, sc_write_binary, sc_update_binary \- read and write files on a smart card +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int sc_read_binary(sc_card_t *" card ", +.BI " unsigned int " offset ", +.BI " unsigned char *" buffer ", +.BI " size_t " count ", +.BI " unsigned long " flags "); +.BI "int sc_write_binary(sc_card_t *" card ", +.BI " unsigned int " offset ", +.BI " const unsigned char *" buffer ", +.BI " size_t " count ", +.BI " unsigned long " flags "); +.BI "int sc_update_binary(sc_card_t *" card ", +.BI " unsigned int " offset ", +.BI " const unsigned char *" buffer ", +.BI " size_t " count ", +.BI " unsigned long " flags "); +.fi +.SH DESCRIPTION +This functions read and write transparent elementary files (EFs) +on a smart card. The correspond to the ISO 7816 functions +READ BINARY, WRITE BINARY and UPDATE BINARY, respectively. +(The difference between write and update is that the former +means writing to an uninitialized file, while the latter +is intended to update a file region previously written to - +some card have different access conditions for these operations). +.PP +The \fIoffset\fP argument specifies the file offset in bytes. +Note that some cards may not allow writing at arbitrary offsets. +Some versions of the GPK require that read/write operations on +transparent files are aligned on a 4-byte boundary. +.PP +The \fIflags\fP argument is currently not used, and should be set +to 0. +.SH RETURN VALUE +If an error occurred, a negative error code is returned, as described +in \fbsc_error\fP(3). Otherwise, the function will return the +number of bytes read or written. +.SH SEE ALSO +.BR sc_file (3), +.BR sc_path (3), +.BR sc_establish_context (3), +.BR sc_select_file (3), +.BR sc_read_record (3), +.BR sc_delete_file (3), +.BR sc_create_file (3), +.BR sc_file_free (3). +.SH AUTHOR +This manual page was written by Olaf Kirch diff --git a/docs/sc_read_record.3 b/docs/sc_read_record.3 new file mode 100644 index 00000000..7f29a7dc --- /dev/null +++ b/docs/sc_read_record.3 @@ -0,0 +1,56 @@ +.TH sc_read_record 3 "April 2003" "OpenSC Programmer's Manual +.SH NAME +sc_read_record, sc_write_record, sc_update_record \- read and write files on a smart card +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int sc_read_record(sc_card_t *" card ", +.BI " unsigned int " rec_nr ", +.BI " unsigned char *" buffer ", +.BI " size_t " count ", +.BI " unsigned long " flags "); +.BI "int sc_write_record(sc_card_t *" card ", +.BI " unsigned int " rec_nr ", +.BI " const unsigned char *" buffer ", +.BI " size_t " count ", +.BI " unsigned long " flags "); +.BI "int sc_update_record(sc_card_t *" card ", +.BI " unsigned int " rec_nr ", +.BI " const unsigned char *" buffer ", +.BI " size_t " count ", +.BI " unsigned long " flags "); +.BI "int sc_append_record(sc_card_t *" card ", +.BI " const unsigned char *" buffer ", +.BI " size_t " count ", +.BI " unsigned long " flags "); +.fi +.SH DESCRIPTION +This functions read and write record-structured elementary files +(EFs) on a smart card. The correspond to the ISO 7816 functions READ +RECORD, WRITE RECORD, APPEND RECORD and UPDATE RECORD, respectively. +(The difference between write and update is that the former means writing +to an uninitialized file, while the latter is intended to update a record +previously written to - some card have different access conditions for +these operations). +.PP +The \fIrec_nr\fP argument specifies the number of the record to be +written to, starting at 0. +.PP +The \fIflags\fP argument is currently not used, and should be set +to 0. +.SH RETURN VALUE +If an error occurred, a negative error code is returned, as described +in \fbsc_error\fP(3). Otherwise, the function will return the +number of bytes read or written. +.SH SEE ALSO +.BR sc_file (3), +.BR sc_path (3), +.BR sc_establish_context (3), +.BR sc_select_file (3), +.BR sc_read_binary (3), +.BR sc_delete_file (3), +.BR sc_create_file (3), +.BR sc_file_free (3). +.SH AUTHOR +This manual page was written by Olaf Kirch diff --git a/docs/sc_release_context.3 b/docs/sc_release_context.3 new file mode 100644 index 00000000..4949b7d3 --- /dev/null +++ b/docs/sc_release_context.3 @@ -0,0 +1,19 @@ +.TH sc_release_context 3 "April 2003" "OpenSC Programmer's Manual +.SH NAME +sc_release_context \- release OpenSC context +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int sc_release_context(struct sc_context **" ctx "); +.fi +.SH DESCRIPTION +This function releasees an OpenSC context previously obtain through +a call to \fBsc_establish_context\fP(3). No further calls to +OpenSC using this context are possible after this. +.PP +\fIctx\fP is the pointer to the context that should be released. +.SH SEE ALSO +.BR sc_establish_context (3). +.SH AUTHOR +This manual page was written by Olaf Kirch diff --git a/docs/sc_select_file.3 b/docs/sc_select_file.3 new file mode 100644 index 00000000..1768de0c --- /dev/null +++ b/docs/sc_select_file.3 @@ -0,0 +1,38 @@ +.TH sc_select_file 3 "April 2003" "OpenSC Programmer's Manual +.SH NAME +sc_select_file \- select a file on a smart card +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int sc_select_file(sc_card_t *" card ", +.BI " const sc_path_t *" path ", +.BI " sc_file_t ** "result "); +.fi +.SH DESCRIPTION +This function selects the file specified by \fIpath\fP. +If \fIpath\fP specifies a file within the currently selected +DF, \fBsc_select_file\fP will \fInot\fP select the MF first, +but interpret the path relative to the current DF. It does +this in order to prevent losing any authorizations previously +established with the card (e.g. by presenting a PIN). +.PP +If \fIresult\fP is not NULL, an \fBsc_file\fP(3) object is +created, and the pointer to this object is stored in the +location pointed to by \fIresult\fP. This handle should later +be released using \fBsc_file_free\fP(3). +.SH RETURN VALUE +If an error occurred, a negative error code is returned, as described +in \fbsc_error\fP(3). Otherwise, the function will return 0. +.SH SEE ALSO +.BR sc_file (3), +.BR sc_path (3), +.BR sc_establish_context (3), +.BR sc_file_free (3), +.BR sc_read_binary (3), +.BR sc_read_record (3), +.BR sc_delete_file (3), +.BR sc_list_files (3), +.BR sc_create_file (3). +.SH AUTHOR +This manual page was written by Olaf Kirch