OpenSC API reference


Table of Contents

1. Initialization
2. Card operations
3. File operations
4. Applications
5. ASN.1 functions
6. Miscellaneous utility functions
7. Data types

Chapter 1. Initialization

Table of Contents

sc_establish_context — Establish an OpenSC context
sc_release_context — Release an OpenSC context
sc_get_cache_dir — Get the OpenSC cache directory
sc_make_cache_dir — Create the OpenSC cache directory
sc_connect_card — Connect to smart card in reader
sc_disconnect_card — Disconnect from a smart card
sc_detect_card_presence — Detect presence of smart card in a reader
sc_card_valid — Check if a card is valid
sc_set_card_driver — Force the use of a specified smart card driver

Name

sc_establish_context — Establish an OpenSC context

Synopsis

#include <opensc.h>

int sc_establish_context(sc_context_t **ctx,
                         const char *appname);
		

Description

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.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_release_context — Release an OpenSC context

Synopsis

#include <opensc.h>

int sc_release_context(sc_context_t *ctx);
		

Description

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.

Return value

This function always return 0, indicating success.


Name

sc_get_cache_dir — Get the OpenSC cache directory

Synopsis

#include <opensc.h>

int sc_get_cache_dir(struct sc_context *ctx, char *buf, size_t bufsize);
		

Description

This function stores the OpenSC cache directory for the current user in the buffer pointed to by buf, which is bufsize bytes long.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_make_cache_dir — Create the OpenSC cache directory

Synopsis

#include <opensc.h>

int sc_make_cache_dir(struct sc_context *ctx);
		

Description

This function creates the OpenSC cache directory for the current user, and any directories leading up to it.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_connect_card — Connect to smart card in reader

Synopsis

#include <opensc.h>

int sc_connect_card(sc_reader_t *reader, int slot, sc_card_t **card);
		

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.

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.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_disconnect_card — Disconnect from a smart card

Synopsis

#include <opensc.h>

int sc_disconnect_card(sc_card_t *card, int action);
		

Description

This function disconnects from card, and frees the card structure. Any locks made by the application must be released before calling this function.

The action parameter is not used at the moment and should be set to 0.

The card is not reset nor powered down after the operation.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_detect_card_presence — Detect presence of smart card in a reader

Synopsis

#include <opensc.h>

int sc_detect_card_presence(sc_reader_t *reader, int slot_id);
		

Description

This function checks whether reader has a card present in slot_id.

Return value

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.


Name

sc_card_valid — Check if a card is valid

Synopsis

#include <opensc.h>

int sc_card_valid(const sc_card_t *card);
		

Description

Checks if card is a valid sc_card_t object. Mostly used internally by the library.

Return value

Returns 1 if card is a valid object.


Name

sc_set_card_driver — Force the use of a specified smart card driver

Synopsis

#include <opensc.h>

int sc_set_card_driver(struct sc_context *ctx, const char *short_name);
		

Description

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.

Return value

If an error occurred, a negative value is returned indicating the error. Otherwise, 0 is returned.

Chapter 2. Card operations

Table of Contents

sc_card_ctl — Send a control command to a 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
sc_format_apdu — Populate an APDU structure
sc_transmit_apdu — Transmit an APDU structure
sc_check_sw — Check return status from a card transaction
sc_get_challenge — Request a challenge from a card
sc_get_data — Get a primitive data object from a card
sc_put_data — Store a primitive data object on a card

Name

sc_card_ctl — Send a control command to a card

Synopsis

#include <opensc.h>

int sc_card_ctl(struct sc_card *card, unsigned long cmd, void *args);

		

Description

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.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_lock — Lock a card for exclusive use

Synopsis

#include <opensc.h>

int sc_lock(struct sc_card *card);
		

Description

This function locks the card against modification from other threads or processes. The function may be called several times; a counter will be increased, and the card will be unlocked only when this counter reaches zero.

Return value

Returns 0 on success, or a negative value in case of error.


Name

sc_unlock — Unlock a card

Synopsis

#include <opensc.h>

int sc_unlock(struct sc_card *card);
		

Description

This function unlocks card. That is, the lock count is decreased, and the card unlocked if it reaches zero.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_wait_for_event — Wait for an event on a smart card reader

Synopsis

#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);
		

Description

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:

SC_EVENT_CARD_REMOVED

A card was removed from the reader/slot.

SC_EVENT_CARD_INSERTED

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.

Return value

Returns 0 if successful, 1 if a timeout occurred, or a negative value in case of error.


Name

sc_format_apdu — Populate an APDU structure

Synopsis

#include <opensc.h>

void sc_format_apdu(struct sc_card *card, sc_apdu_t *apdu,
                    int cse, int ins, int p1, int p2);
		

Description

This function populates the sc_apdu_t structure pointed to by apdu on card. It does not allocate memory. The cse, ins, p1 and p2 parameters correspond to the respective APDU parameters as described in the ISO 7816 standard.


Name

sc_transmit_apdu — Transmit an APDU structure

Synopsis

#include <opensc.h>

int sc_transmit_apdu(struct sc_card *card, sc_apdu_t *apdu);
		

Description

This function transmits the APDU in apdu to card.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_check_sw — Check return status from a card transaction

Synopsis

#include <opensc.h>

int sc_check_sw(struct sc_card *card, int sw1, int sw2);
		

Description

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.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_get_challenge — Request a challenge from a card

Synopsis

#include <opensc.h>

int sc_get_challenge(struct sc_card *card, unsigned char *rnd, size_t len);
		

Description

This function requests a challenge (i.e. random bytes) from card. The returned data will be stored in rnd, and will be len bytes long.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_get_data — Get a primitive data object from a card

Synopsis

#include <opensc.h>

int sc_get_data(sc_card_t *card, unsigned int tag,
                unsigned char *buf, size_t buflen);
		

Description

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.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_put_data — Store a primitive data object on a card

Synopsis

#include <opensc.h>

int sc_put_data(sc_card_t *card, unsigned int tag,
                const unsigned char *buf, size_t len);
		

Description

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.

Return value

Returns 0 if successful, or a negative value in case of error.

Chapter 3. File operations

Table of Contents

sc_file_new — Create a file object
sc_file_dup — Duplicate a file object
sc_create_file — Create a file object
sc_select_file — Select a file on a smart card
sc_file_free — Free file object
sc_list_files — List files
sc_delete_file — Delete a file
sc_read_binary — Read a file
sc_update_binary — Write to an existing file
sc_write_binary — Write to a new file
sc_read_record — Read a record from a file
sc_write_record — Write a record to a file
sc_update_record — Write a record to an existing file
sc_append_record — Append a record to a file
sc_delete_record — Delete a record from a file

Name

sc_file_new — Create a file object

Synopsis

#include <opensc.h>

sc_file_t *sc_file_new(void);
		

Description

This function creates an empty OpenSC file object, which can later be passed to sc_create_file().


Name

sc_file_dup — Duplicate a file object

Synopsis

#include <opensc.h>

void sc_file_dup(sc_file_t **dest, const sc_file_t *src)
		

Description

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.


Name

sc_create_file — Create a file object

Synopsis

#include <opensc.h>

int sc_create_file(sc_card_t *card, sc_file_t *file);
		

Description

This function creates a file on card. The file must have been created with a call to sc_file_new() beforehand.


Name

sc_select_file — Select a file on a smart card

Synopsis

#include <opensc.h>

int sc_select_file(sc_card_t *card,
                   const sc_path_t *path,
                   sc_file_t **result);

		

Description

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().

Return value

If an error occurred, a negative error code is returned. Otherwise, the function will return 0.


Name

sc_file_free — Free file object

Synopsis

#include <opensc.h>

void sc_file_free(sc_file_t *file);
		

Description

This function releases a file object previously allocated by sc_select_file().


Name

sc_list_files — List files

Synopsis

#include <opensc.h>

int sc_list_files(struct sc_card *card, unsigned char *buf, size_t buflen);
		

Description

This function lists all files in the currently selected DF, and stores the file IDs as big-endian 16-bit words in buffer, which is buflen bytes long. If the supplied buffer is too small to hold all file IDs, the listing is silently truncated.

Return value

Returns the number of bytes stored in buffer, or a negative value in case of error.


Name

sc_delete_file — Delete a file

Synopsis

#include <opensc.h>

int sc_delete_file(struct sc_card *card, const struct sc_path *path);
		

Description

This function deletes a file specified by path on card.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_read_binary — Read a file

Synopsis

#include <opensc.h>

int sc_read_binary(struct sc_card *card, unsigned int offset,
                   unsigned char *buf, size_t count,
                   unsigned long flags);
		

Description

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.

Return value

If successful, the number of bytes read is returned. Otherwise, a negative value is returned.


Name

sc_update_binary — Write to an existing file

Synopsis

#include <opensc.h>

int sc_update_binary(struct sc_card *card, unsigned int offset,
                     const unsigned char *buf, size_t count,
                     unsigned long flags);
		

Description

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.

Return value

If successful, the number of bytes written is returned. Otherwise, a negative value is returned.


Name

sc_write_binary — Write to a new file

Synopsis

#include <opensc.h>

int sc_write_binary(struct sc_card *card, unsigned int offset,
                    const unsigned char *buf, size_t count,
                    unsigned long flags);
		

Description

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.

Return value

If successful, the number of bytes written is returned. Otherwise, a negative value is returned.


Name

sc_read_record — Read a record from a file

Synopsis

#include <opensc.h>

int sc_read_record(struct sc_card *card, unsigned int record,
                   unsigned char *buf, size_t buflen,
                   unsigned long flags);
		

Description

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.

Return value

Returns the number of bytes read if successful, or a negative value in case of error.


Name

sc_write_record — Write a record to a file

Synopsis

#include <opensc.h>

int sc_write_record(struct sc_card *card, unsigned int record,
                    const unsigned char *buf, size_t buflen,
                    unsigned long flags);
		

Description

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.

Return value

Returns the number of bytes written if successful, or a negative value in case of error.


Name

sc_update_record — Write a record to an existing file

Synopsis

#include <opensc.h>

int sc_update_record(struct sc_card *card, unsigned int record,
                     const unsigned char *buf, size_t buflen,
                     unsigned long flags);
		

Description

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.

Return value

Returns the number of bytes written if successful, or a negative value in case of error.


Name

sc_append_record — Append a record to a file

Synopsis

#include <opensc.h>

int sc_append_record(struct sc_card *card,
                     const unsigned char *buf, size_t buflen,
                     unsigned long flags);
		

Description

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.

Return value

Returns the number of bytes written if successful, or a negative value in case of error.


Name

sc_delete_record — Delete a record from a file

Synopsis

#include <opensc.h>

int sc_delete_record(struct sc_card *card, unsigned int rec_nr);
		

Description

This function deletes a record specified by rec_nr on card. This is not a standard ISO 7816 operation, and is currently only supported on the Oberthur smart cards.

Return value

Returns 0 if successful, or a negative value in case of error.

Chapter 4. Applications

Table of Contents

sc_enum_apps — Enumerate the applications on a card
sc_find_app_by_aid — Find an application on a card
sc_find_pkcs15_app — Find a PKCS#15 application on a card
sc_update_dir — Update application directory on a card
sc_free_apps — Free application list

Name

sc_enum_apps — Enumerate the applications on a card

Synopsis

#include <opensc.h>

int sc_enum_apps(struct sc_card *card);
		

Description

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().

Return value

Returns the number of applications on the card, or a negative value in case of error.


Name

sc_find_app_by_aid — Find an application on a card

Synopsis

#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);
		

Description

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.

Return value

Returns a sc_app_info_t structure describing the application corresponding to aid, or NULL if none was found.


Name

sc_find_pkcs15_app — Find a PKCS#15 application on a card

Synopsis

#include <opensc.h>

const sc_app_info_t *sc_find_pkcs15_app(sc_card_t *card);
		

Description

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.

Return value

Returns a sc_app_info_t structure describing the PKCS#15 application, or NULL if none was found.


Name

sc_update_dir — Update application directory on a card

Synopsis

#include <opensc.h>

int sc_update_dir(sc_card_t *card, sc_app_info_t *app);
		

Description

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.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_free_apps — Free application list

Synopsis

#include <opensc.h>

void sc_free_apps(struct sc_card *card);
		

Description

This functions releases all memory associated with the list of applications on card, as obtained by a call to sc_enum_apps().

Chapter 5. ASN.1 functions

Table of Contents

sc_asn1_encode — Encode ASN.1 entries into a stream
sc_asn1_decode — Extract entries from an ASN.1 stream
sc_format_asn1_entry — Fill in an ASN.1 entry structure
sc_copy_asn1_entry — Copy an ASN.1 entry
sc_asn1_print_tags — Print an ASN.1 stream to stdout
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
sc_asn1_find_tag — Find a tag in an ASN.1 stream
sc_asn1_put_tag — Construct an ASN.1 entry in a buffer

Name

sc_asn1_encode — Encode ASN.1 entries into a stream

Synopsis

#include <opensc.h>

int sc_asn1_encode(struct sc_context *ctx, const struct sc_asn1_entry *asn1,
                   unsigned char **newbuf, size_t *size);
		

Description

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.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_asn1_decode — Extract entries from an ASN.1 stream

Synopsis

#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);
		

Description

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.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_format_asn1_entry — Fill in an ASN.1 entry structure

Synopsis

#include <opensc.h>

void sc_format_asn1_entry(struct sc_asn1_entry *entry, void *parm, void *arg, int set_present);
		

Description

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.


Name

sc_copy_asn1_entry — Copy an ASN.1 entry

Synopsis

#include <opensc.h>

void sc_copy_asn1_entry(const struct sc_asn1_entry *src, struct sc_asn1_entry *dest);
		

Description

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.


Name

sc_asn1_print_tags — Print an ASN.1 stream to stdout

Synopsis

#include <opensc.h>

void sc_asn1_print_tags(const unsigned char *buf, size_t buflen);
		

Description

This function prints the ASN.1 stream pointed to by buf, which is of size buflen, to stdout. This is useful for debugging.


Name

sc_asn1_skip_tag

Synopsis

#include <opensc.h>

const unsigned char *sc_asn1_skip_tag(struct sc_context *ctx,
                                      const unsigned char **buf, size_t *buflen,
                                      unsigned int tag_in, size_t *taglen_out);
		

Description

Return value


Name

sc_asn1_verify_tag — Verify validity of an ASN.1 tag

Synopsis

#include <opensc.h>

const unsigned char *sc_asn1_verify_tag(struct sc_context *ctx,
                                        const unsigned char *buf, size_t buflen,
                                        unsigned int tag_in, size_t *taglen_out);
		

Description

This is an alias for the sc_asn1_skip_tag() function.


Name

sc_asn1_read_tag — Extract a tag from an ASN.1 entry

Synopsis

#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);
		

Description

This function extracts a tag from an ASN.1 entry at the buffer pointed to by the pointer in buf. The buffer is buflen bytes long. The tag class will be stored in cla_out, the tag itself in tag_out, and the length of the extracted tag in tag_len.

Return value

Returns 1 if successful, or -1 in case of error.


Name

sc_asn1_find_tag — Find a tag in an ASN.1 stream

Synopsis

#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);
		

Description

This function tries to find an ASN.1 tag matching tag_in in the buffer pointed to by buf, which is of size buflen. The buffer should contain a series of ASN.1 entries.

Return value

If the specified tag was not found, NULL is returned. If found, the address where it was found is returned, and taglen_in is set to the length of the found tag.


Name

sc_asn1_put_tag — Construct an ASN.1 entry in a buffer

Synopsis

#include <opensc.h>

int sc_asn1_put_tag(int tag, const unsigned char *data, int datalen,
                    unsigned char *out, int outlen, unsigned char **nextbuf);
		

Description

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.

Return value

Returns 0 if successful, or a negative value in case of error.

Chapter 6. Miscellaneous utility functions

Table of Contents

sc_strerror — Return string describing error code
sc_base64_encode — Encode a stream to base64
sc_base64_decode — Decode a base64 stream
sc_der_copy — Copy a DER structure
sc_der_clear — Clear DER structure

Name

sc_strerror — Return string describing error code

Synopsis

#include <opensc.h>

const char *sc_strerror(int error);
		

Description

This function returns a string describing error. It may be used with a negative errorcode returned by any OpenSC function call.


Name

sc_base64_encode — Encode a stream to base64

Synopsis

#include <opensc.h>

int sc_base64_encode(const unsigned char *inbuf, size_t inlen,
                     unsigned char *outbuf, size_t outlen,
                     size_t linelength);
		

Description

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.

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_base64_decode — Decode a base64 stream

Synopsis

#include <opensc.h>

int sc_base64_decode(const char *inbuf,
                     unsigned char *outbuf, size_t outlen);
		

Description

This function decodes the base64 stream in inbuf, which is NULL-terminated, to the buffer pointed to by outbuf (which is outlen bytes long);

Return value

Returns 0 if successful, or a negative value in case of error.


Name

sc_der_copy — Copy a DER structure

Synopsis

#include <opensc.h>

void sc_der_copy(sc_pkcs15_der_t *dst, const sc_pkcs15_der_t *src);
		

Description

This function copies the OpenSC DER structure pointed to by src to dst, which must point to enough space to hold this structure.


Name

sc_der_clear — Clear DER structure

Synopsis

#include <opensc.h>

void sc_der_clear(sc_pkcs15_der_t *der);
		

Description

This function clears the OpenSC DER structure pointed to by der.

Chapter 7. Data types

Table of Contents

sc_card_t — OpenSC card structure
sc_path_t — OpenSC path structure
sc_file_t — OpenSC file structure
sc_app_info_t — OpenSC application structure
sc_asn1_entry — OpenSC ASN1 entry structure

This chapter defines the structures OpenSC uses to store information. Fields internal to OpenSC are not shown.

Name

sc_card_t — OpenSC card structure

Synopsis

#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;

            

Description

This structure describes a smart card object. It contains the following members:

ctx

The context this card is associated with.

reader

The reader this card is inserted into.

slot

The slot on the reader this card is inserted into.

atr

The ATR (Answer To Reset) of the card.

atr_len

The length of the atr field


Name

sc_file_t — OpenSC path structure

Synopsis

#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;

            

Description

This structure describes a path object on a smart card. It contains the following members:

value

This is the full path to the file, starting at the MF.

length

The length of the path.

index

Used only in PKCS15, this indicates the offset into the file.

count

Used only in PKCS15, this indicates the number of octets in the record, starting from index above.

type

The 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


Name

sc_file_t — OpenSC file structure

Synopsis

#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;
            

Description

This structure describes a file object on a smart card. It contains the following members:

path

This is full the path to the file, starting at the MF.

type

This 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_structure

For 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

size

gives the file's size in bytes.

id

gives the file's ID, as a 16-bit number.

record_count, record_length

For 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.


Name

sc_app_info_t — OpenSC application structure

Synopsis

#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;
			

Description

This structure describes a smart card application. It contains the following members:

aid

The 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_len

The length of the AID in bytes.

label

A UTF-8 string describing the application.

path

The application's full path on the card, starting at the MF.

ddo

ddo_len

desc

A description of the application, if available.

rec_nr

If the EF(DIR) file is record-structured, this has the record number in which this application is stored. Otherwise, this is -1.


Name

sc_asn1_entry — OpenSC ASN1 entry structure

Synopsis

#include <opensc.h>

struct sc_asn1_entry {
	const char *name;
	unsigned int type;
	unsigned int tag;
	unsigned int flags;
	void *parm;
	void *arg;
};
			

Description

This structure describes an ASN1 entry structure. It contains the following members:

name

type

tag

flags

parm

arg