Table of Contents
Table of Contents
sc_establish_context — Establish an OpenSC context
This function establishes an OpenSC context. This context is required in all subsequent calls to OpenSC functions.
ctx is a pointer to a pointer that will receive the allocated context.
appname is a string that identifies the application. This string will be used to apply application-specific settings from the opensc.conf configuration file. If NULL is passed, only the settings specified in the default section apply; otherwise, settings from the section identified by appname will be applied as well.
The sc_context structure contains the following members:
#define SC_MAX_READERS 16
typedef struct sc_context {
struct sc_reader *reader[SC_MAX_READERS];
int reader_count;
} sc_context_t;
The reader_count field contains the number of readers found. Information on the individual card readers is stored in sc_reader objects, defined as follows:
typedef struct sc_reader {
char *name;
int slot_count;
}; sc_reader_t;
In this structure, name contains a printable name of the reader, and slot_count has the number of slots supported by this device.
sc_release_context — Release an OpenSC context
This function releases OpenSC context ctx previously obtained through a call to sc_establish_context(). No further calls to OpenSC using this context are possible after this.
sc_get_cache_dir — Get the OpenSC cache directory
#include <opensc.h> int sc_get_cache_dir(struct sc_context *ctx, char *buf, size_t bufsize);
sc_make_cache_dir — Create the OpenSC cache directory
sc_connect_card — Connect to smart card in reader
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.
The slot parameter identifies the card reader's slot. Slots are numbered consecutively, starting at 0.
If OpenSC was able to connect to the card, a pointer to the sc_card_t object is stored in the location pointer to by the card parameter. The card handle should be released with sc_disconnect_card when no longer in use.
sc_disconnect_card — Disconnect from a smart card
sc_detect_card_presence — Detect presence of smart card in a reader
If an error occurred, the return value is a a negative OpenSC error code. If no card is present, 0 is returned. Otherwise, a positive value is returned, which is a combination of flags. The flag SC_SLOT_CARD_PRESENT is always set. In addition, if the card was exchanged, the SC_SLOT_CARD_CHANGED flag is set.
sc_set_card_driver — Force the use of a specified smart card driver
#include <opensc.h> int sc_set_card_driver(struct sc_context *ctx, const char *short_name);
This function forces the use of a a specific card driver to be used in context ctx. The name of the driver is specified in short_name. Possible options are:
| etoken |
| flex |
| cyberflex |
| gpk |
| miocos |
| mcrd |
| setcos |
| starcos |
| tcos |
| openpgp |
| jcop |
| oberthur |
| belpic |
| emv |
This function only needs to be called if OpenSC fails to auto-detect your card. If used, it should be called immediately after establishing a new context with sc_establish_context(), but before doing anything else with the context.
Table of Contents
sc_card_ctl — Send a control command to a card
This function is used to send various control commands to the smart card associated with card. The command is specified in cmd, and any command-specific arguments are pointed to by args.
Commands are specific to cards. For more details on which cards accept which commands, check the documentation for your card.
sc_lock — Lock a card for exclusive use
sc_unlock — Unlock a card
sc_wait_for_event — Wait for an event on a smart card reader
#include <opensc.h>
int sc_wait_for_event(sc_reader_t *readers[], int slots[], size_t numslots,
unsigned int event_mask,
int *reader, unsigned int *event, int timeout);
This function blocks until an event occurs on any of the readers/slots specified. The readers and slots fields list the readers and respective slots to be watched. num_slots holds the total number of slots passed. The event_mask parameter specifies the types of events to wait for. This may be a combination of the following flags:
A card was removed from the reader/slot.
A card was inserted into the reader/slot.
On returning, the reader parameter holds the reader which generated an event, and event holds the event flag, as in event_mask.
The timeout parameter may be used to specify the maximum amount of time to wait for an event, in milliseconds. This may be set to -1 to wait forever.
sc_format_apdu — Populate an APDU structure
sc_check_sw — Check return status from a card transaction
This function checks the return status as given in sw1
and sw2 against the card-specific errors of
card. These are set by sc_transmit_apdu() in the
apdu.sw1 and apdu.sw2
fields, respectively.
The function should be called after every APDU transmission, to convert the card's status code to an OpenSC error code.
sc_get_challenge — Request a challenge from a card
#include <opensc.h> int sc_get_challenge(struct sc_card *card, unsigned char *rnd, size_t len);
sc_get_data — Get a primitive data object from a card
#include <opensc.h>
int sc_get_data(sc_card_t *card, unsigned int tag,
unsigned char *buf, size_t buflen);
This function is used to retrieve a primitive data object from card. It corresponds to the GET DATA command in the ISO 7816 standard. The data is stored in buf, which is buflen bytes long.
The tag parameter specifies the object to be retrieved. Refer to the standard for the correct values to use.
sc_put_data — Store a primitive data object on a card
#include <opensc.h>
int sc_put_data(sc_card_t *card, unsigned int tag,
const unsigned char *buf, size_t len);
This function is used to store a primitive data object on card. It corresponds to the PUT DATA command in the ISO 7816 standard. The data to be sent to the card is stored in buf, which is buflen bytes long.
The tag parameter specifies the object to be stored. Refer to the standard for the correct values to use.
Table of Contents
sc_file_new — Create a file object
This function creates an empty OpenSC file object, which can later be passed to sc_create_file().
sc_file_dup — Duplicate a file object
This function creates a new file object, duplicates all file information from src into it, and stores it in the pointer pointed to by dest. This object must be released with sc_file_free() after use.
sc_create_file — Create a file object
This function creates a file on card. The file must have been created with a call to sc_file_new() beforehand.
sc_select_file — Select a file on a smart card
#include <opensc.h> int sc_select_file(sc_card_t *card, const sc_path_t *path, sc_file_t **result);
This function selects the file specified by path. If path specifies a file within the currently selected DF, sc_select_file() will not 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).
If result is not NULL, an sc_file_t object is created, and the pointer to this object is stored in the location pointed to by result. This handle should later be released using sc_file_free().
sc_list_files — List files
#include <opensc.h> int sc_list_files(struct sc_card *card, unsigned char *buf, size_t buflen);
sc_read_binary — Read a file
#include <opensc.h>
int sc_read_binary(struct sc_card *card, unsigned int offset,
unsigned char *buf, size_t count,
unsigned long flags);
This function reads from a transparent elementary file (EF) on card. It corresponds to the ISO 7816 READ BINARY function. Call sc_select_file() first to select the file to read from.
The data read from the file is stored in buf, which is count bytes long.
The offset argument specifies the file offset in bytes. The flags argument is currently not used, and should be set to 0.
sc_update_binary — Write to an existing file
#include <opensc.h>
int sc_update_binary(struct sc_card *card, unsigned int offset,
const unsigned char *buf, size_t count,
unsigned long flags);
This function writes count bytes from the buffer pointed to by buf to a transparent elementary file (EF) on card. It corresponds to the ISO 7816 UPDATE BINARY function. Call sc_select_file() first to select the file to write to.
This function can only be used to write to a file region previously written to. For writing to a newly created file, or a new region of an existing file, use sc_write_binary().
The offset argument specifies the file offset in bytes. The flags argument is currently not used, and should be set to 0.
sc_write_binary — Write to a new file
#include <opensc.h>
int sc_write_binary(struct sc_card *card, unsigned int offset,
const unsigned char *buf, size_t count,
unsigned long flags);
This function writes count bytes from the buffer pointed to by buf to a transparent elementary file (EF) on card. It corresponds to the ISO 7816 WRITE BINARY function. Call sc_select_file() first to select the file to write to.
This function is used to write to a newly created file, or to a a previously unused portion of a file. For updating an existing file, use the sc_update_binary() function.
The offset argument specifies the file offset in bytes. The flags argument is currently not used, and should be set to 0.
sc_read_record — Read a record from a file
#include <opensc.h>
int sc_read_record(struct sc_card *card, unsigned int record,
unsigned char *buf, size_t buflen,
unsigned long flags);
This function reads a record-structured elementary file (EF) from card. The function corresponds to the ISO 7816 READ RECORD function. Call sc_select_file() first to select the file to read from.
record specifies the ID of the record to be read, or, if flags is set to SC_RECORD_BY_REC_NR, the record number. If record is set to zero, the current record will be read.
The read data is stored in buf, which is buflen bytes long.
sc_write_record — Write a record to a file
#include <opensc.h>
int sc_write_record(struct sc_card *card, unsigned int record,
const unsigned char *buf, size_t buflen,
unsigned long flags);
This function writes a record that is buflen bytes long from the buffer pointed to by buf to a record-structured elementary file (EF) on card. The function corresponds to the ISO 7816 WRITE RECORD function. Call sc_select_file() first to select the file to write to.
record specifies the ID of the record to be written, or, if flags is set to SC_RECORD_BY_REC_NR, the record number. If record is set to zero, the current record will be read.
This function is used for newly created files only; for updating or appending to existing files, see the sc_update_record() and sc_append_record() functions, respectively.
sc_update_record — Write a record to an existing file
#include <opensc.h>
int sc_update_record(struct sc_card *card, unsigned int record,
const unsigned char *buf, size_t buflen,
unsigned long flags);
This function writes a record that is buflen bytes long from the buffer pointed to by buf to a record-structured elementary file (EF) on card. The function corresponds to the ISO 7816 UPDATE RECORD function. Call sc_select_file() first to select the file to write to.
record specifies the ID of the record to be written, or, if flags is set to SC_RECORD_BY_REC_NR, the record number. If record is set to zero, the current record will be read.
This function can be used for overwriting existing records only; for appending to files, see the sc_append_record() function.
sc_append_record — Append a record to a file
#include <opensc.h>
int sc_append_record(struct sc_card *card,
const unsigned char *buf, size_t buflen,
unsigned long flags);
This function appends a record that is buflen bytes long from the buffer pointed to by buf to a record-structured elementary file (EF) on card. The function corresponds to the ISO 7816 APPEND RECORD function. Call sc_select_file() first to select the file to write to.
Table of Contents
sc_enum_apps — Enumerate the applications on a card
This function enumerates the applications on card, and stores them in the structure. The list of applications can then later be searched with sc_find_app_by_aid() or sc_find_pkcs15_app().
sc_find_app_by_aid — Find an application on a card
#include <opensc.h>
const sc_app_info_t *sc_find_app_by_aid(sc_card_t *card,
const unsigned char *aid,
size_t aid_len);
This function finds an application on card by its aid. The AID's length is specified in aid_len.
Before calling this function, you MUST call sc_enum_apps() first.
Returns a sc_app_info_t structure describing the application corresponding to aid, or NULL if none was found.
sc_find_pkcs15_app — Find a PKCS#15 application on a card
This function attempts to find a PKCS#15 application on card. Currently, this means either a standard PKCS#15 implementation or a Belgian eID.
Before calling this function, you MUST call sc_enum_apps() first.
Returns a sc_app_info_t structure describing the PKCS#15 application, or NULL if none was found.
sc_update_dir — Update application directory on a card
This function updates the application directory on card. If the card has a record-structured directory file, app may contain the application to update. Otherwise, the entire directory file is updated.
Before calling this function, you MUST call sc_enum_apps() first.
sc_free_apps — Free application list
This functions releases all memory associated with the list of applications on card, as obtained by a call to sc_enum_apps().
Table of Contents
sc_asn1_encode — Encode ASN.1 entries into a stream
#include <opensc.h>
int sc_asn1_encode(struct sc_context *ctx, const struct sc_asn1_entry *asn1,
unsigned char **newbuf, size_t *size);
This function encodes an array of entries pointed to by asn1 and terminated
by a NULL entry (i.e. where the name field of the entry is NULL) into
a newly allocated buffer.
The new buffer containing the ASN.1 stream will be stored in newbuf, and the size of this buffer is stored in size. The application must free this buffer after use.
sc_asn1_decode — Extract entries from an ASN.1 stream
#include <opensc.h>
int sc_asn1_decode(struct sc_context *ctx, struct sc_asn1_entry *asn1,
const unsigned char *inbuf, size_t len,
const unsigned char **newbuf, size_t *len_left);
This function extracts information from the ASN.1 stream pointed to by inbuf
(which is len bytes in size) and stores it into the array of
struct sc_asn_1 entries pointed to by
asn1. The array must be big enough to contain all the entries that will be
found, or an error will be flagged. The last entry in the array must be a NULL entry, i.e. the
name field must be set to NULL.
The structure of the expected data must be encoded in the entries in asn1
before calling this function; specifically the name,
type, tag and
flags fields must be filled in.
The function will then scan the stream and fill in the remaining fields. newbuf will point to the byte immediately following the extracted record, and len_left will contain the number of bytes left in the buffer. Thus, the newbuf and len_left fields may be passed in to sc_asn1_decode() again, as the inbuf and len parameters, until len reaches 0.
sc_format_asn1_entry — Fill in an ASN.1 entry structure
#include <opensc.h> void sc_format_asn1_entry(struct sc_asn1_entry *entry, void *parm, void *arg, int set_present);
This function stores the parm and arg pointers in the struct sc_asn1_entry entry. No checking is done. Since the pointers are copied directly, the storage they point to must not be freed by the calling application until the entry itself is destroyed.
sc_copy_asn1_entry — Copy an ASN.1 entry
#include <opensc.h> void sc_copy_asn1_entry(const struct sc_asn1_entry *src, struct sc_asn1_entry *dest);
This function copies an array of struct
sc_asn1_entry entries pointed to be src to
dest. The array must be NULL-terminated (that is, the last entry must have
its name field set to NULL). There must be enough space available in
dest.
sc_asn1_skip_tag
sc_asn1_verify_tag — Verify validity of an ASN.1 tag
sc_asn1_read_tag — Extract a tag from an ASN.1 entry
#include <opensc.h>
int sc_asn1_read_tag(const unsigned char **buf, size_t buflen,
unsigned int *cla_out, unsigned int *tag_out, size_t *taglen);
sc_asn1_find_tag — Find a tag in an ASN.1 stream
#include <opensc.h>
const unsigned char *sc_asn1_find_tag(struct sc_context *ctx,
const unsigned char *buf, size_t buflen,
unsigned int tag_in, size_t *taglen_in);
sc_asn1_put_tag — Construct an ASN.1 entry in a buffer
#include <opensc.h>
int sc_asn1_put_tag(int tag, const unsigned char *data, int datalen,
unsigned char *out, int outlen, unsigned char **nextbuf);
This function constructs a single entry in an ASN.1 stream, at the buffer pointed to by out (which is outlen bytes long). The tag to be used is in tag, and the entry payload is pointed to by data, which is datalen bytes long.
If nextbuf is not NULL, it will be filled in with a pointer to the buffer address immediately following the newly copied entry.
Table of Contents
sc_base64_encode — Encode a stream to base64
#include <opensc.h>
int sc_base64_encode(const unsigned char *inbuf, size_t inlen,
unsigned char *outbuf, size_t outlen,
size_t linelength);
This function encodes the buffer pointed to by inbuf of size inlen as base64, and stores the result in outbuf, which is outlen bytes long. A linefeed (\n) will be inserted every linelength bytes in the output buffer.
You must ensure outbuf has enough space to store the base64-encoded version of inbuf.
sc_base64_decode — Decode a base64 stream
#include <opensc.h>
int sc_base64_decode(const char *inbuf,
unsigned char *outbuf, size_t outlen);
Table of Contents
This chapter defines the structures OpenSC uses to store information. Fields internal to OpenSC are not shown.
sc_card_t — OpenSC card structure
#include <opensc.h>
#define SC_MAX_ATR_SIZE 33
#define SC_MAX_CARD_APPS 8
typedef struct sc_card {
struct sc_context *ctx;
struct sc_reader *reader;
struct sc_slot_info *slot;
struct sc_app_info *app[SC_MAX_CARD_APPS];
unsigned char atr[SC_MAX_ATR_SIZE];
size_t atr_len;
} sc_card_t;
This structure describes a smart card object. It contains the following members:
ctxThe context this card is associated with.
readerThe reader this card is inserted into.
slotThe slot on the reader this card is inserted into.
atrThe ATR (Answer To Reset) of the card.
atr_lenThe length of the atr field
sc_file_t — OpenSC path structure
#include <opensc.h>
#define SC_MAX_PATH_SIZE 16
typedef struct sc_path {
unsigned char value[SC_MAX_PATH_SIZE];
size_t len;
int index;
int count;
int type;
} sc_path_t;
This structure describes a path object on a smart card. It contains the following members:
valueThis is the full path to the file, starting at the MF.
lengthThe length of the path.
indexUsed only in PKCS15, this indicates the offset into the file.
countUsed only in PKCS15, this indicates the number of octets in the
record, starting from index above.
typeThe path type. This can be one of:
| SC_PATH_TYPE_FILE_ID |
| SC_PATH_TYPE_DF_NAME |
| SC_PATH_TYPE_PATH |
| SC_PATH_TYPE_PATH_PROT |
sc_file_t — OpenSC file structure
#include <opensc.h>
typedef struct sc_file {
struct sc_path path;
int type, ef_structure;
size_t size;
int id;
/* record structured files only */
int record_length;
int record_count;
} sc_file_t;
This structure describes a file object on a smart card. It contains the following members:
pathThis is full the path to the file, starting at the MF.
typeThis is the file type. It can be one of SC_FILE_TYPE_DF, SC_FILE_TYPE_WORKING_EF, or SC_FILE_TYPE_INTERNAL_EF. The latter is used by some cards only, and you normally shouldn't have to deal with these files.
ef_structureFor elementary files (EFs), this field describes the file's structure. It can be one of:
| SC_FILE_EF_TRANSPARENT |
| SC_FILE_EF_LINEAR_FIXED |
| SC_FILE_EF_LINEAR_FIXED_TLV |
| SC_FILE_EF_LINEAR_VARIABLE |
| SC_FILE_EF_LINEAR_VARIABLE_TLV |
| SC_FILE_EF_CYCLIC |
| SC_FILE_EF_CYCLIC_TLV |
| SC_FILE_EF_UNKNOWN |
sizegives the file's size in bytes.
idgives the file's ID, as a 16-bit number.
record_count, record_lengthFor record structured files, record_sount
specifies the number of records in the file. For files with fixed length records,
record_length contains the record length.
sc_app_info_t — OpenSC application structure
#include <opensc.h>
#define SC_MAX_AID_SIZE 16
typedef struct sc_app_info {
unsigned char aid[SC_MAX_AID_SIZE];
size_t aid_len;
char *label;
sc_path_t path;
unsigned char *ddo;
size_t ddo_len;
const char *desc;
int rec_nr;
} sc_app_info_t;
This structure describes a smart card application. It contains the following members:
aidThe applications's AID. An AID uniquely identifies an application, and consists of an RID (a 5-byte "Registered Application Provider Identifier") and a PIX, which identifies an application by that provider. For example, the RID for PKCS#15 consists of the bytes A0 00 00 00 63, and the PIX is the string "PKCS-15". Thus, the AID of a PKCS#15 application on a smart card is A0 00 00 00 63 50 4B 43 53 2D 31.
aid_lenThe length of the AID in bytes.
labelA UTF-8 string describing the application.
pathThe application's full path on the card, starting at the MF.
ddoddo_lendescA description of the application, if available.
rec_nrIf the EF(DIR) file is record-structured, this has the record number in which this application is stored. Otherwise, this is -1.