aboutsummaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorlloyd <lloyd@randombit.net>2008-10-13 03:55:47 +0000
committerlloyd <lloyd@randombit.net>2008-10-13 03:55:47 +0000
commitd32976c65c5cac0dafa83a132322a5a1152f03c5 (patch)
tree385243b0af3167ba116b989acc716d786b790b10 /src
parent190b5acbd48dd5af4529020010b9efd2a13bc0f5 (diff)
More Doxygen comments from InSiTo
Diffstat (limited to 'src')
-rw-r--r--src/cert/x509/crl_ent.h43
-rw-r--r--src/cert/x509/x509_crl.h48
-rw-r--r--src/cert/x509/x509_obj.h23
-rw-r--r--src/core/libstate/init.h88
-rw-r--r--src/pubkey/pk_lookup/look_pk.h69
5 files changed, 231 insertions, 40 deletions
diff --git a/src/cert/x509/crl_ent.h b/src/cert/x509/crl_ent.h
index 8aa567a2a..40d82a8d7 100644
--- a/src/cert/x509/crl_ent.h
+++ b/src/cert/x509/crl_ent.h
@@ -10,20 +10,43 @@
namespace Botan {
-/*************************************************
-* CRL Entry *
-*************************************************/
+/**
+* This class represents CRL entries
+*/
class BOTAN_DLL CRL_Entry : public ASN1_Object
{
public:
void encode_into(class DER_Encoder&) const;
void decode_from(class BER_Decoder&);
+ /**
+ * Get the serial number of the certificate associated with this entry.
+ * @return the certificate's serial number
+ */
MemoryVector<byte> serial_number() const { return serial; }
+
+ /**
+ * Get the revocation date of the certificate associated with this entry
+ * @return the certificate's revocation date
+ */
X509_Time expire_time() const { return time; }
+
+ /**
+ * Get the entries reason code
+ * @return the reason code
+ */
CRL_Code reason_code() const { return reason; }
+ /**
+ * Construct an empty CRL entry.
+ */
CRL_Entry(bool throw_on_unknown_critical_extension = false);
+
+ /**
+ * Construct an CRL entry.
+ * @param cert the certificate to revoke
+ * @param reason the reason code to set in the entry
+ */
CRL_Entry(const X509_Certificate&, CRL_Code = UNSPECIFIED);
private:
@@ -33,11 +56,19 @@ class BOTAN_DLL CRL_Entry : public ASN1_Object
CRL_Code reason;
};
-/*************************************************
-* Comparison Operations *
-*************************************************/
+/**
+* Test two CRL entries for equality in all fields.
+*/
BOTAN_DLL bool operator==(const CRL_Entry&, const CRL_Entry&);
+
+/**
+* Test two CRL entries for inequality in at least one field.
+*/
BOTAN_DLL bool operator!=(const CRL_Entry&, const CRL_Entry&);
+
+/**
+* Order two entries based on the revocation date.
+*/
BOTAN_DLL bool operator<(const CRL_Entry&, const CRL_Entry&);
}
diff --git a/src/cert/x509/x509_crl.h b/src/cert/x509/x509_crl.h
index ec73e9fdf..dd1ea372e 100644
--- a/src/cert/x509/x509_crl.h
+++ b/src/cert/x509/x509_crl.h
@@ -12,29 +12,69 @@
namespace Botan {
-/*************************************************
-* X.509 CRL *
-*************************************************/
+/**
+* This class represents X.509 Certificate Revocation Lists (CRLs).
+*/
class BOTAN_DLL X509_CRL : public X509_Object
{
public:
+ /**
+ * This class represents CRL related errors.
+ */
struct X509_CRL_Error : public Exception
{
X509_CRL_Error(const std::string& error) :
Exception("X509_CRL: " + error) {}
};
+ /**
+ * Get the entries of this CRL in the form of a vector.
+ * @return a vector containing the entries of this CRL.
+ */
std::vector<CRL_Entry> get_revoked() const;
+ /**
+ * Get the issuer DN of this CRL.
+ * @return the CRLs issuer DN
+ */
X509_DN issuer_dn() const;
+
+ /**
+ * Get the AuthorityKeyIdentifier of this CRL.
+ * @return this CRLs AuthorityKeyIdentifier
+ */
MemoryVector<byte> authority_key_id() const;
+ /**
+ * Get the serial number of this CRL.
+ * @return the CRLs serial number
+ */
u32bit crl_number() const;
+
+ /**
+ * Get the CRL's thisUpdate value.
+ * @return the CRLs thisUpdate
+ */
X509_Time this_update() const;
+
+ /**
+ * Get the CRL's nextUpdate value.
+ * @return the CRLs nextdUpdate
+ */
X509_Time next_update() const;
+ /**
+ * Construct a CRL from a data source.
+ * @param source the data source providing the DER or PEM encoded CRL.
+ */
X509_CRL(DataSource&, bool throw_on_unknown_critical = false);
- X509_CRL(const std::string&, bool throw_on_unknown_critical = false);
+
+ /**
+ * Construct a CRL from a file containing the DER or PEM encoded CRL.
+ * @param filename the name of the CRL file
+ */
+ X509_CRL(const std::string& filename,
+ bool throw_on_unknown_critical = false);
private:
void force_decode();
diff --git a/src/cert/x509/x509_obj.h b/src/cert/x509/x509_obj.h
index 8808fd686..baaf5a8a4 100644
--- a/src/cert/x509/x509_obj.h
+++ b/src/cert/x509/x509_obj.h
@@ -14,9 +14,10 @@
namespace Botan {
-/*************************************************
-* Generic X.509 SIGNED Object *
-*************************************************/
+/**
+* This class represents abstract X.509 signed objects as
+* in the X.500 SIGNED macro
+*/
class BOTAN_DLL X509_Object
{
public:
@@ -24,10 +25,18 @@ class BOTAN_DLL X509_Object
SecureVector<byte> signature() const;
AlgorithmIdentifier signature_algorithm() const;
- static MemoryVector<byte> make_signed(class PK_Signer*,
- RandomNumberGenerator&,
- const AlgorithmIdentifier&,
- const MemoryRegion<byte>&);
+ /**
+ * Create a signed X509 object.
+ * @param signer the signer used to sign the object
+ * @param rng the random number generator to use
+ * @param alg_id the algorithm identifier of the signature scheme
+ * @param tbs the tbs bits to be signed
+ * @return the signed X509 object
+ */
+ static MemoryVector<byte> make_signed(class PK_Signer* signer,
+ RandomNumberGenerator& rng,
+ const AlgorithmIdentifier& alg_id,
+ const MemoryRegion<byte>& tbs);
bool check_signature(class Public_Key&) const;
diff --git a/src/core/libstate/init.h b/src/core/libstate/init.h
index f4296a868..86ef09bac 100644
--- a/src/core/libstate/init.h
+++ b/src/core/libstate/init.h
@@ -12,26 +12,87 @@
namespace Botan {
-/*************************************************
-* Options for initializing the library *
-*************************************************/
+/**
+* This class represents options for initializing the library.
+*/
class BOTAN_DLL InitializerOptions
{
public:
+ /**
+ * Check whether this set of options has thread safety enabled.
+ * @return true if thread safety is enabled
+ */
bool thread_safe() const;
+
+ /**
+ * Check whether this set of options has the usage of alternative engines
+ * enabled.
+ * @return true if the usage of alternative engines
+ * is enabled
+ */
bool use_engines() const;
+
+ /**
+ * Check whether this set of options has enabled the seeding of the
+ * global RNG at startup.
+ * @return true if the seeding at startup is enabled
+ */
+ bool seed_rng() const;
+
+ /**
+ * Check whether this set of options has enabled the memory
+ * locking feature. This is implemented for Unix and Win32, but
+ * it only reliably works for Unix. There, all SecureVectors and
+ * SecureBuffers are kept from being ever swapped to disk. On
+ * Win32 plattforms, the corresponding pages are locked into the
+ * working set of the process, reducing the chance of being
+ * swapped to disk, but not strictly preventing it.
+ * @return true if the memory locking feature is enabled
+ */
bool secure_memory() const;
+
+ /**
+ * Check whether this set of options has the self-test-at-startup
+ * enabled. Same as self_test().
+ * @param return true if the self-test is enabled
+ */
bool fips_mode() const;
+
+ /**
+ * Check whether this set of options has the self-test-at-startup enabled.
+ * Same as fips_mode().
+ * @param return true if the self-test is enabled
+ */
bool self_test() const;
- InitializerOptions(const std::string&);
+ /**
+ * Get the full path of the configuration file to be used.
+ */
+ std::string config_file() const;
+
+ /**
+ * Create an initializer options object. The option are set based on the
+ * input string. The options can be set by building a white space separated
+ * list of elements out of the
+ * following set of strings:
+ * "config=<file name>",
+ * "selftest",
+ * "fips140",
+ * "seed_rng",
+ * "use_engines",
+ * "secure_memory",
+ * "thread_safe"
+ *
+ */
+ InitializerOptions(const std::string& options);
private:
std::map<std::string, std::string> args;
};
-/*************************************************
-* Library Initialization/Shutdown Object *
-*************************************************/
+/**
+* This class represents the Library Initialization/Shutdown Object. It has to
+* exceed the lifetime of any Botan object used in an application.
+*/
class BOTAN_DLL LibraryInitializer
{
public:
@@ -40,8 +101,21 @@ class BOTAN_DLL LibraryInitializer
static void initialize(const InitializerOptions&, class Modules&);
static void deinitialize();
+ /**
+ * Construct a library initializer from a string. Does exactly the same
+ * as if an InitializerOptions object created with that string was used as
+ * the argument.
+ * @param args the string determining the desired library configuration
+ */
LibraryInitializer(const std::string& args = "") { initialize(args); }
+
+ /**
+ * Construct a library initializer.
+ * @param args the initializer option object specifying the desired
+ * library configuration
+ */
LibraryInitializer(const InitializerOptions& args) { initialize(args); }
+
~LibraryInitializer() { deinitialize(); }
};
diff --git a/src/pubkey/pk_lookup/look_pk.h b/src/pubkey/pk_lookup/look_pk.h
index 28a56f2b3..926416a41 100644
--- a/src/pubkey/pk_lookup/look_pk.h
+++ b/src/pubkey/pk_lookup/look_pk.h
@@ -11,28 +11,65 @@
namespace Botan {
-/*************************************************
-* Get an PK algorithm object *
-*************************************************/
-BOTAN_DLL PK_Encryptor* get_pk_encryptor(const PK_Encrypting_Key&,
- const std::string&);
+/**
+* Public key encryptor factory method.
+* @param key the key that will work inside the encryptor
+* @param pad determines the algorithm and encoding
+* @return the public key encryptor object
+*/
+BOTAN_DLL PK_Encryptor* get_pk_encryptor(const PK_Encrypting_Key& key,
+ const std::string& pad);
-BOTAN_DLL PK_Decryptor* get_pk_decryptor(const PK_Decrypting_Key&,
- const std::string&);
+/**
+* Public key decryptor factory method.
+* @param key the key that will work inside the decryptor
+* @param pad determines the algorithm and encoding
+* @return the public key decryptor object
+*/
+BOTAN_DLL PK_Decryptor* get_pk_decryptor(const PK_Decrypting_Key& key,
+ const std::string& pad);
-BOTAN_DLL PK_Signer* get_pk_signer(const PK_Signing_Key&,
- const std::string&,
+/**
+* Public key signer factory method.
+* @param key the key that will work inside the signer
+* @param pad determines the algorithm, encoding and hash algorithm
+* @param sig_format the signature format to be used
+* @return the public key signer object
+*/
+BOTAN_DLL PK_Signer* get_pk_signer(const PK_Signing_Key& key,
+ const std::string& pad,
Signature_Format = IEEE_1363);
-BOTAN_DLL PK_Verifier* get_pk_verifier(const PK_Verifying_with_MR_Key&,
- const std::string&,
- Signature_Format = IEEE_1363);
-BOTAN_DLL PK_Verifier* get_pk_verifier(const PK_Verifying_wo_MR_Key&,
- const std::string&,
+/**
+* Public key verifier factory method.
+* @param key the key that will work inside the verifier
+* @param pad determines the algorithm, encoding and hash algorithm
+* @param sig_format the signature format to be used
+* @return the public key verifier object
+*/
+BOTAN_DLL PK_Verifier* get_pk_verifier(const PK_Verifying_with_MR_Key& key,
+ const std::string& pad,
Signature_Format = IEEE_1363);
-BOTAN_DLL PK_Key_Agreement* get_pk_kas(const PK_Key_Agreement_Key&,
- const std::string&);
+/**
+* Public key verifier factory method.
+* @param key the key that will work inside the verifier
+* @param pad determines the algorithm, encoding and hash algorithm
+* @param sig_form the signature format to be used
+* @return the public key verifier object
+*/
+BOTAN_DLL PK_Verifier* get_pk_verifier(const PK_Verifying_wo_MR_Key& key,
+ const std::string& pad,
+ Signature_Format sig_form = IEEE_1363);
+
+/**
+* Public key key agreement factory method.
+* @param key the key that will work inside the key agreement
+* @param pad determines the algorithm, encoding and hash algorithm
+* @return the public key verifier object
+*/
+BOTAN_DLL PK_Key_Agreement* get_pk_kas(const PK_Key_Agreement_Key& key,
+ const std::string& pad);
}