closes #11

openssl-act-engine/src/SlotList.h

@@ -33,7 +33,7 @@ private:
 	act::IToken* m_token;
 };
 
-/*
+/*!
  * Holds a list of the present slots in the system
  * TODO: Slot addition/removal detection
  */

openssl-act-engine/src/engine_front.cpp

@@ -1,3 +1,4 @@
+/*! @file OpenSSL HAndler/Callbacks */
 
 #include <memory>
 #include <cstring>

openssl-act-engine/src/engine_sct.cpp

@@ -123,15 +123,15 @@ int SecureTokenEngine::finish()
 
 int SecureTokenEngine::rsa_finish(RSA *rsa)
 {
-	// This function is only called on freeing of 'our' own RSA keys which have been generated
-	// by encapsule_CardKey
+	/*! This function is only called on freeing of 'our' own RSA keys which have
+      been generated by encapsule_CardKey
+
+      NB: If you use something like
+	    EVP_PKEY* pk_pub = ENGINE_load_public_key(e, key_id, NULL, NULL);
+	    RSA* pubkey = EVP_PKEY_get1_RSA(pk_pub);
 	
-	// NB: If you use something like
-	//
-	// EVP_PKEY* pk_pub = ENGINE_load_public_key(e, key_id, NULL, NULL);
-	// RSA* pubkey = EVP_PKEY_get1_RSA(pk_pub);
-	//
-	// in the user code, you have to use both EVP_PKEY_free() and RSA_free() until the last traces are gone.
+	    in the user code, you have to use both EVP_PKEY_free() and RSA_free()
+	    until the last traces are gone. */
 
 	CardKey* ck(EXTRACT_CARD_KEY(rsa));
 

openssl-act-engine/src/engine_sct_internal.h

@@ -43,37 +43,58 @@ public:
 	SecureTokenEngine() { }
 	~SecureTokenEngine() { }
 	
-	// NOTE: contents of source string will be overwritten for security reasons
+	/*! Stores pin in internal buffer.
+   * @note contents of source string will be overwritten for security reasons
+   */
 	int setPin(char *pin);
-	
-	int incVerbosity();
-	int setInitArgs(const char *args);
-	
-	int init();
-	int finish();
-	
-	int rsa_finish(RSA *rsa);
-	
-	int loadCertCtrl(ENGINE *e, load_cert_params *p);
-	EVP_PKEY *load_pubkey(const char *s_key_id, UI_METHOD *ui_method, void *callback_data);
-	EVP_PKEY *load_privkey(const char *s_key_id, UI_METHOD *ui_method, void *callback_data);
-	
-	// Caller is required to provide an output buffer of sufficient size, depending on input data's length
-	// and used key material. Improper usage may cause buffer overruns. OpenSSL API's weakness.
 
-	// Encrypt/Decrypt return size of output data on success, -1 on failure.
+  //! debug
+	int incVerbosity();
+  //! not used
+	int setInitArgs(const char *args);
+
+  //! Initialize PCSC, read slots
+	int init();
+  //! cleanup memory
+	int finish();
+
+  //! Deletes OpenSSL rsa structure
+	int rsa_finish(RSA *rsa);
+
+  //! Read certificate from token
+	int loadCertCtrl(ENGINE *e, load_cert_params *p);
+
+  //! Get Public Key
+	EVP_PKEY *load_pubkey(const char *s_key_id, UI_METHOD *ui_method, void *callback_data);
+
+  //! Get Private Key
+	EVP_PKEY *load_privkey(const char *s_key_id, UI_METHOD *ui_method, void *callback_data);
+
+  /*! @defgroup engSign Crypto Operations
+   *
+   * Caller is required to provide an output buffer of sufficient size,
+   * depending on input data's length
+   *     and used key material. Improper usage may cause buffer overruns. OpenSSL API's weakness. */
+  //@{
+    
+  //! Encrypt/Decrypt return size of output data on success, -1 on failure.
 	int rsa_encrypt(int flen, const unsigned char *from, unsigned char *to, const CardKey* ck, int padding);
 	int rsa_decrypt(int flen, const unsigned char *from, unsigned char *to, CardKey* ck, int padding);
 	
-	// Sign/Verify return 1 on success, 0 on failure.
+	//! Sign/Verify return 1 on success, 0 on failure.
 	int rsa_sign(int type, const unsigned char *msg, unsigned int msglen, unsigned char *sigret, unsigned int *siglen, CardKey* ck);
 	int rsa_verify(int type, const unsigned char *msg, unsigned int msglen, unsigned char *signature, unsigned int siglen, const CardKey* ck);	
-	
-	// Return a list of all certificates and the necessary IDs to use them
-	// !! frees up the memory of the previosly returned structure in subsequent calls !!
+
+  //@}
+  
+	/*! Return a list of all certificates and the necessary IDs to use them
+	    @note frees up the memory of the previosly returned structure in
+	    subsequent calls */
 	int enumerate_certs(ENGINE *e, enum_certs_s **p);
 
 private:
+
+  //! Converts CardKey to OpenSSL EVP_PKEY
 	EVP_PKEY *encapsule_CardKey(CardKey *ck);
 	
 	act::Blob						m_pin;
@@ -81,10 +102,8 @@ private:
 	std::auto_ptr<CertificateList>	m_cert_list;
 };
 
-// Needed in SecureTokenEngine for creation of new RSA key (stubs) as well
+//! Needed in SecureTokenEngine for creation of new RSA key (stubs) as well
 RSA_METHOD* RSA_get_sct_method();
 
-
-
 #endif