From d32976c65c5cac0dafa83a132322a5a1152f03c5 Mon Sep 17 00:00:00 2001 From: lloyd Date: Mon, 13 Oct 2008 03:55:47 +0000 Subject: More Doxygen comments from InSiTo --- src/cert/x509/crl_ent.h | 43 ++++++++++++++++++--- src/cert/x509/x509_crl.h | 48 +++++++++++++++++++++-- src/cert/x509/x509_obj.h | 23 +++++++---- src/core/libstate/init.h | 88 ++++++++++++++++++++++++++++++++++++++---- src/pubkey/pk_lookup/look_pk.h | 69 +++++++++++++++++++++++++-------- 5 files changed, 231 insertions(+), 40 deletions(-) (limited to 'src') 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 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 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 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 signature() const; AlgorithmIdentifier signature_algorithm() const; - static MemoryVector make_signed(class PK_Signer*, - RandomNumberGenerator&, - const AlgorithmIdentifier&, - const MemoryRegion&); + /** + * 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 make_signed(class PK_Signer* signer, + RandomNumberGenerator& rng, + const AlgorithmIdentifier& alg_id, + const MemoryRegion& 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=", + * "selftest", + * "fips140", + * "seed_rng", + * "use_engines", + * "secure_memory", + * "thread_safe" + * + */ + InitializerOptions(const std::string& options); private: std::map 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); } -- cgit v1.2.3