From 6ff80e4f25edfcc5dc9d19acbea453c2810c3177 Mon Sep 17 00:00:00 2001 From: Brad Hards Date: Sun, 26 Mar 2006 03:27:54 +0000 Subject: [PATCH] More API documentation. The main change in this lot is to ensure that every header file is documented. That avoids ugly results in the "files" tab in the HTML, and also identifies some undocumented functions - also fixed. svn path=/trunk/kdesupport/qca/; revision=522574 --- include/QtCrypto/qca.h | 10 ++++++++ include/QtCrypto/qca_basic.h | 10 ++++++++ include/QtCrypto/qca_cert.h | 12 ++++++++- include/QtCrypto/qca_core.h | 13 ++++++++++ include/QtCrypto/qca_export.h | 24 ++++++++++++++++++ include/QtCrypto/qca_keystore.h | 10 ++++++++ include/QtCrypto/qca_publickey.h | 10 ++++++++ include/QtCrypto/qca_securelayer.h | 24 ++++++++++++++++++ include/QtCrypto/qca_securemessage.h | 10 ++++++++ include/QtCrypto/qca_support.h | 13 ++++++++++ include/QtCrypto/qca_textfilter.h | 10 ++++++++ include/QtCrypto/qca_tools.h | 38 +++++++++++++++++++++++++++- include/QtCrypto/qpipe.h | 10 ++++++++ 13 files changed, 192 insertions(+), 2 deletions(-) diff --git a/include/QtCrypto/qca.h b/include/QtCrypto/qca.h index 9d5b730e..d7a0f97a 100644 --- a/include/QtCrypto/qca.h +++ b/include/QtCrypto/qca.h @@ -19,6 +19,16 @@ * */ +/** + \file qca.h + + Summary header file for %QCA. + + \note You should not use this header directly from an + application. You should just use \#include \ + instead. +*/ + #ifndef QCA_H #define QCA_H diff --git a/include/QtCrypto/qca_basic.h b/include/QtCrypto/qca_basic.h index a2609e78..b8813bc1 100644 --- a/include/QtCrypto/qca_basic.h +++ b/include/QtCrypto/qca_basic.h @@ -19,6 +19,16 @@ * */ +/** + \file qca_basic.h + + Header file for classes for cryptographic primitives (basic operations) + + \note You should not use this header directly from an + application. You should just use \#include \ + instead. +*/ + #ifndef QCA_BASIC_H #define QCA_BASIC_H diff --git a/include/QtCrypto/qca_cert.h b/include/QtCrypto/qca_cert.h index b4a25053..977ce60f 100644 --- a/include/QtCrypto/qca_cert.h +++ b/include/QtCrypto/qca_cert.h @@ -1,7 +1,7 @@ /* * qca_cert.h - Qt Cryptographic Architecture * Copyright (C) 2003-2005 Justin Karneges - * Copyright (C) 2004,2005 Brad Hards + * Copyright (C) 2004 - 2006 Brad Hards * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -19,6 +19,16 @@ * */ +/** + \file qca_cert.h + + Header file for PGP key and X.509 certificate related classes + + \note You should not use this header directly from an + application. You should just use \#include \ + instead. +*/ + #ifndef QCA_CERT_H #define QCA_CERT_H diff --git a/include/QtCrypto/qca_core.h b/include/QtCrypto/qca_core.h index 5de2ad7c..b3460544 100644 --- a/include/QtCrypto/qca_core.h +++ b/include/QtCrypto/qca_core.h @@ -19,9 +19,22 @@ * */ +/** + \file qca_core.h + + Header file for core %QCA infrastructure + + \note You should not use this header directly from an + application. You should just use \#include \ + instead. +*/ + #ifndef QCA_CORE_H #define QCA_CORE_H +/** + The current version of %QCA +*/ #define QCA_VERSION 0x020000 #include diff --git a/include/QtCrypto/qca_export.h b/include/QtCrypto/qca_export.h index 5c43ffef..cca7a579 100644 --- a/include/QtCrypto/qca_export.h +++ b/include/QtCrypto/qca_export.h @@ -18,11 +18,28 @@ * */ +/** + \file qca_export.h + + Preprocessor magic to allow export of library symbols. + + \note You should not use this header directly from an + application. You should just use \#include \ + instead. +*/ + #ifndef QCA_EXPORT_H #define QCA_EXPORT_H #include +/** + \def QCA_EXPORT + + \internal + + Makes this QCA symbol visible. +*/ #ifdef Q_OS_WIN32 # ifndef QCA_STATIC # ifdef QCA_MAKEDLL @@ -36,6 +53,13 @@ # define QCA_EXPORT #endif +/** + \def QCA_PLUGIN_EXPORT + + \internal + + Makes this symbol from a plugin visible. +*/ #ifdef Q_OS_WIN32 # ifdef QCA_PLUGIN_DLL # define QCA_PLUGIN_EXPORT extern "C" __declspec(dllexport) diff --git a/include/QtCrypto/qca_keystore.h b/include/QtCrypto/qca_keystore.h index b1bd8f22..ce9623aa 100644 --- a/include/QtCrypto/qca_keystore.h +++ b/include/QtCrypto/qca_keystore.h @@ -19,6 +19,16 @@ * */ +/** + \file qca_keystore.h + + Header file for classes that provide and manage keys + + \note You should not use this header directly from an + application. You should just use \#include \ + instead. +*/ + #ifndef QCA_KEYSTORE_H #define QCA_KEYSTORE_H diff --git a/include/QtCrypto/qca_publickey.h b/include/QtCrypto/qca_publickey.h index 1cf83d5f..5362313b 100644 --- a/include/QtCrypto/qca_publickey.h +++ b/include/QtCrypto/qca_publickey.h @@ -19,6 +19,16 @@ * */ +/** + \file qca_publickey.h + + Header file for PublicKey and PrivateKey related classes + + \note You should not use this header directly from an + application. You should just use \#include \ + instead. +*/ + #ifndef QCA_PUBLICKEY_H #define QCA_PUBLICKEY_H diff --git a/include/QtCrypto/qca_securelayer.h b/include/QtCrypto/qca_securelayer.h index e22ee0eb..a6517429 100644 --- a/include/QtCrypto/qca_securelayer.h +++ b/include/QtCrypto/qca_securelayer.h @@ -19,6 +19,15 @@ * */ +/** + \file qca_securelayer.h + + Header file for SecureLayer and its subclasses + + \note You should not use this header directly from an + application. You should just use \#include \ + instead. +*/ #ifndef QCA_SECURELAYER_H #define QCA_SECURELAYER_H @@ -203,6 +212,21 @@ namespace QCA \class TLS qca_securelayer.h QtCrypto Transport Layer Security / Secure Socket Layer + + Transport Layer Security (%TLS) is the current + state-of-the-art in secure transport mechanisms over the + internet. It can be used in a way where only one side of + the link needs to authenticate to the other. This makes it + very useful for servers to provide their identity to + clients. Note that is is possible to use %TLS to + authenticate both client and server. + + %TLS is a IETF standard (RFC2712 for + TLS version 1.0) based on earlier Netscape work on Secure + Socket Layer (SSL version 2 and SSL version 3). New + applications should use at least TLS 1.0, and SSL version 2 + should be avoided due to known security problems. */ class QCA_EXPORT TLS : public SecureLayer, public Algorithm { diff --git a/include/QtCrypto/qca_securemessage.h b/include/QtCrypto/qca_securemessage.h index ff117680..d371dc8f 100644 --- a/include/QtCrypto/qca_securemessage.h +++ b/include/QtCrypto/qca_securemessage.h @@ -19,6 +19,16 @@ * */ +/** + \file qca_securemessage.h + + Header file for secure message (PGP, CMS) classes + + \note You should not use this header directly from an + application. You should just use \#include \ + instead. +*/ + #ifndef QCA_SECUREMESSAGE_H #define QCA_SECUREMESSAGE_H diff --git a/include/QtCrypto/qca_support.h b/include/QtCrypto/qca_support.h index 30b172f3..ca7daa21 100644 --- a/include/QtCrypto/qca_support.h +++ b/include/QtCrypto/qca_support.h @@ -19,6 +19,19 @@ * */ +/** + \file qca_support.h + + Header file for "support" classes used in %QCA + + The classes in this header do not have any cryptographic + content - they are used in %QCA, and are included for convenience. + + \note You should not use this header directly from an + application. You should just use \#include \ + instead. +*/ + #ifndef QCA_SUPPORT_H #define QCA_SUPPORT_H diff --git a/include/QtCrypto/qca_textfilter.h b/include/QtCrypto/qca_textfilter.h index 861c2d0a..9d3522ee 100644 --- a/include/QtCrypto/qca_textfilter.h +++ b/include/QtCrypto/qca_textfilter.h @@ -19,6 +19,16 @@ * */ +/** + \file qca_textfilter.h + + Header file for text encoding/decoding classes + + \note You should not use this header directly from an + application. You should just use \#include \ + instead. +*/ + #ifndef QCA_TEXTFILTER_H #define QCA_TEXTFILTER_H diff --git a/include/QtCrypto/qca_tools.h b/include/QtCrypto/qca_tools.h index 62b26333..eabdd35e 100644 --- a/include/QtCrypto/qca_tools.h +++ b/include/QtCrypto/qca_tools.h @@ -19,6 +19,19 @@ * */ +/** + \file qca_tools.h + + Header file for "tool" classes used in %QCA + + These classes differ from those in qca_support.h, in that they have + some cryptographic relationship, and require secure memory. + + \Note You should not use this header directly from an + application. You should just use \#include \ + instead. +*/ + #ifndef QCA_TOOLS_H #define QCA_TOOLS_H @@ -30,9 +43,32 @@ class QString; class QByteArray; class QTextStream; -// Direct secure memory access. For interfacing with C libraries if needed. +/** + Allocate a block of memory from the secure memory pool. + + This is intended to be used when working with C libraries. + + \param bytes the number of bytes to allocate +*/ QCA_EXPORT void *qca_secure_alloc(int bytes); + +/** + Free (de-allocate) a block of memory that has been previously + allocated from the secure memory pool. + + This is intended to be used when working with C libraries. + + \param p pointer to the block of memory to be free'd +*/ QCA_EXPORT void qca_secure_free(void *p); + +/** + Resize (re-allocate) a block of memory that has been previously + allocated from the secure memory pool. + + \param p pointer to the block of memory to be resized. + \param bytes the new size that is required. +*/ QCA_EXPORT void *qca_secure_realloc(void *p, int bytes); /** diff --git a/include/QtCrypto/qpipe.h b/include/QtCrypto/qpipe.h index 84733129..33afbc15 100644 --- a/include/QtCrypto/qpipe.h +++ b/include/QtCrypto/qpipe.h @@ -17,6 +17,16 @@ * */ +/** + \file qpipe.h + + Header file for the QPipe FIFO class + + \note You should not use this header directly from an + application. You should just use \#include \ + instead. +*/ + #ifndef QPIPE_H #define QPIPE_H