Source: ../libcamcard/camcard.h
|
|
|
|
/**
* libcamcard - Interface to the Cambride University Smartcard
*
* Copyright (C) 2001 Richard J Wareham
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2, or (at your option)
* any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software Foundation,
* Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
#ifndef CARDHELPER_H
#define CARDHELPER_H
#include
#include
#include
#include
/**
* @short Wrapper object to abstract the PC/SC API and access
* the filesystem on the card.
*
* This class takes care of communicating to the PC/SC middleware
* and accessing the features of the Cambridge University
* smartcard.
*
* @author Richard Wareham
* @version 0.1alpha
*/
class CamCard {
private:
bool m_isConnected;
bool m_isConnectedCard;
bool m_cardPresent;
int m_reader;
int m_cardVersion;
vector m_readers;
vector m_atr;
unsigned long m_prefProtocol;
unsigned long m_APDUReturn;
SCARDHANDLE hCard;
SCARDCONTEXT hContext;
public:
/**
* Some useful fileIDs
*/
static const vector MF;
static const vector CHUBB;
static const vector PLAYPEN;
static const vector DF_AUT;
static const vector MAIN_PUB_KEY;
static const vector MAIN_CERT;
static const vector SUMMARY;
static const vector CARD_INFO;
static const vector EF_LIST;
/**
* Default constructor.
*/
CamCard();
/**
* Default destructor.
*/
~CamCard();
/**
* Convert an error code to human-readable string.
*
* @return a string describing the error code passed.
*/
static string stringifyError(long errno);
/**
* Connect to the PC/SC middleware. You must call this method before
* doing anything else.
*
* @param host (optional) The hostname of the machine you wish to connect
* to. If
* not specified, the PC/SC middleware on the local machine is contacted.
* By default, the first reported smartcard reader is used.
*
* @see CamCard#disconnect
*
* @return SCARD_S_SUCCESS if successful, an error code otherwise.
*/
long connect(string host = "");
/**
* Disconnects from the PC/SC middleware peviously connected to
* with connect().
*
* @see CamCard#connect
*
* @return SCARD_S_SUCCESS if successful, an error code otherwise.
*/
long disconnect();
/**
* See if a connection has been established to the PC/SC middleware.
*
* @return true if a connection is present, false otherwise.
*/
bool isConnected();
/**
* @return A vector of strings containing a description of each smartcard
* reader connected to the PC/SC middleware. Indices into this vector are
* what you should pass to setReader() when changing readers.
*
* @see CamCard#setReader
*/
vector readers();
/**
* Set the smartcard reader which should be used. Disconnects from a card
* if you were connected.
*
* @param reader A number from 0 to the number of elements in vector returned
* by readers().
*
* @see CamCard#readers
*
* @return true if successful, false otherwise.
*/
bool setReader(int reader);
/**
* Query the name of the current reader.
*
* @return A string containing the smartcard reader which is being used.
*/
string reader();
/**
* Connects to the smartcard in the currently selected reader.
*
* @return SCARD_S_SUCCESS if successful, -1 if there is no card,
* an error code otherwise.
*
* @see CamCard#disconnectCard
*/
long connectCard();
/**
* Disconnects ftom a previously connected to card.
*
* @return SCARD_S_SUCCESS if successful, an error code otherwise.
*
* @see CamCard#connectCard
*/
long disconnectCard();
/**
* Query the connection state to the card.
*
* @return tru is connected to a card, false otherwise
*/
bool isConnectedCard();
/**
* Query the presence of a card in the currently selected reader.
*
* @return true if there is a card present, false otherwise.
*/
bool cardPresent();
/**
* Query the card version (only returns meaningful results after
* a call to connectCard().
*
* @return the version of the card currently connected to.
*/
int cardVersion();
/**
* Starts a transaction with the card. This must be called before
* doing anthing with the card after connectCard().
*
* @return SCARD_S_SUCCESS if successful, an error code otherwise.
*/
long beginTransaction();
/**
* Finishes a transaction with the card. This must be called after
* doing anthing with the card.
*
* @return SCARD_S_SUCCESS if successful, an error code otherwise.
*
* @see CamCard#beginTransaction
*/
long endTransaction();
/**
* Sends an APDU to the card, writing the result into the vector
* passed by reference.
*
* @param apdu The APDU to send.
*
* @param resp The vector to write the response into.
*
* @return SCARD_S_SUCCESS if successful, an error code otherwise.
*/
long sendAPDU(vector apdu, vector &resp);
/**
* Get the return code from last APDU.
*
* @return 16-bit return code.
*/
unsigned long APDUReturnCode();
/**
* Selects a file by the fileID passed.
*
* @param fileID A vector containing the two-byte file ID of the file
* to select.
* @param header A vector of undigned char's to write the file header into.
*
* @return SCARD_S_SUCCESS if successful, an error code otherwise.
*/
long selectFile(const vector fileID,
vector &header);
/**
* Reads a file previously selected with selectFile().
*
* @param header A vector containing the fileheader returned by selectFile().
*
* @param file A vector to write the file contents into.
*
* @return SCARD_S_SUCCESS if successful, an error code otherwise.
*/
long readFile(const vector header,
vector &file);
/**
* Presents the PIN specified.
*
* @param pin String containing PIN
*
* @return true if PIN accepted, false otherwise
*/
bool presentPIN(string pin);
/** Chenges the current PIN
*
* @param old_pin The original PIN.
* @param new_pin The new PIN.
*
* @return true if PIN accepted, false otherwise
*/
bool changePIN(string old_pin, string new_pin);
/**
* Digitally 'sign' some data using a specified key. The
* correct PIN must have been presented during the transaction using
* presentPIN();
*
* @param data The data to be signed.
*
* @param signature The vector to write the signature into.
*
* @param keyID keyID of key to use.
*
* @return SCARD_S_SUCCESS if successful, an error code otherwise.
*
* @see CamCard#presentPIN
* @see CamCard#keyIDs
*/
long sign(int keyID, const vector data,
vector &signature);
/**
* @return a vector of valid keyIDs
*/
vector keyIDs();
/**
* Write the certificate asssociated with the keyID specified into a
* vector.
*
* @param keyID the keyID of required key.
*
* @param cert the vector to write the certificate into.
*
* @return SCARD_S_SUCCESS if successful, an error code otherwise.
*
* @see CamCard#keyIDs
*/
long readCertificate(int keyID, vector &cert);
/**
* Write the public modulus of the specidied key into a vector.
*
* @param keyID the keyID of required key.
*
* @param modulus the vector to write the modulus into.
*
* @return SCARD_S_SUCCESS if successful, an error code otherwise.
*
* @see CamCard#keyIDs
*/
long readModulus(int keyID, vector &modulus);
/**
* Converts a vector into a string of two-character hex values.
*/
static string vec2str(const vector vec);
/**
* Converts a string of two-character hex values into a vector.
*/
static vector str2vec(string str);
};
#define DEF_FID(name, id) \
const vector CamCard::name(CamCard::str2vec(id))
DEF_FID(MF, "3F 00");
DEF_FID(CHUBB, "10 00");
DEF_FID(PLAYPEN, "10 01");
DEF_FID(DF_AUT, "20 00");
DEF_FID(MAIN_PUB_KEY, "FE 80");
DEF_FID(MAIN_CERT, "FD 04");
DEF_FID(SUMMARY, "FD 03");
DEF_FID(CARD_INFO, "FD 01");
DEF_FID(EF_LIST, "88 88");
#endif
| Generated by: rjw57 on malachite on Fri Aug 31 15:23:05 2001, using kdoc 2.0a53. |