aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--src/cert/x509/x509_ca.h48
-rw-r--r--src/pubkey/dl_algo/dl_algo.h67
-rw-r--r--src/pubkey/dl_group/dl_group.h120
-rw-r--r--src/pubkey/pubkey/x509_key.h72
4 files changed, 268 insertions, 39 deletions
diff --git a/src/cert/x509/x509_ca.h b/src/cert/x509/x509_ca.h
index 969e62558..9f7cb9515 100644
--- a/src/cert/x509/x509_ca.h
+++ b/src/cert/x509/x509_ca.h
@@ -15,24 +15,53 @@
namespace Botan {
-/*************************************************
-* X.509 Certificate Authority *
-*************************************************/
+/**
+* This class represents X.509 Certificate Authorities (CAs).
+*/
class BOTAN_DLL X509_CA
{
public:
+
+ /**
+ * Sign a PKCS#10 Request.
+ * @param req the request to sign
+ * @param rng the rng to use
+ * @param not_before the starting time for the certificate
+ * @param not_after the expiration time for the certificate
+ * @return the resulting certificate
+ */
X509_Certificate sign_request(const PKCS10_Request& req,
RandomNumberGenerator& rng,
const X509_Time& not_before,
const X509_Time& not_after);
+ /**
+ * Get the certificate of this CA.
+ * @return the CA certificate
+ */
X509_Certificate ca_certificate() const;
+ /**
+ * Create a new and empty CRL for this CA.
+ * @param rng the random number generator to use
+ * @param next_update the time to set in next update in seconds as the offset from
+ * the current time
+ * @return the new CRL
+ */
X509_CRL new_crl(RandomNumberGenerator& rng, u32bit = 0) const;
- X509_CRL update_crl(const X509_CRL&,
- const std::vector<CRL_Entry>&,
+
+ /**
+ * Create a new CRL by with additional entries.
+ * @param last_crl the last CRL of this CA to add the new entries to
+ * @param new_entries contains the new CRL entries to be added to the CRL
+ * @param rng the random number generator to use
+ * @param next_update the time to set in next update in seconds
+ * as the offset from the current time
+ */
+ X509_CRL update_crl(const X509_CRL& last_crl,
+ const std::vector<CRL_Entry>& new_entries,
RandomNumberGenerator& rng,
- u32bit = 0) const;
+ u32bit next_update = 0) const;
static X509_Certificate make_cert(PK_Signer*,
RandomNumberGenerator&,
@@ -42,7 +71,12 @@ class BOTAN_DLL X509_CA
const X509_DN&, const X509_DN&,
const Extensions&);
- X509_CA(const X509_Certificate&, const Private_Key&);
+ /**
+ * Create a new CA object.
+ * @param ca_certificate the certificate of the CA
+ * @param key the private key of the CA
+ */
+ X509_CA(const X509_Certificate& ca_certificate, const Private_Key& key);
~X509_CA();
private:
X509_CA(const X509_CA&) {}
diff --git a/src/pubkey/dl_algo/dl_algo.h b/src/pubkey/dl_algo/dl_algo.h
index a8d8d1d51..ff543d0b4 100644
--- a/src/pubkey/dl_algo/dl_algo.h
+++ b/src/pubkey/dl_algo/dl_algo.h
@@ -13,22 +13,60 @@
namespace Botan {
-/*************************************************
-* DL Public Key *
-*************************************************/
+/**
+* This class represents discrete logarithm (DL) public keys.
+*/
class BOTAN_DLL DL_Scheme_PublicKey : public virtual Public_Key
{
public:
bool check_key(RandomNumberGenerator& rng, bool) const;
+ /**
+ * Get the DL domain parameters of this key.
+ * @return the DL domain parameters of this key
+ */
const DL_Group& get_domain() const { return group; }
+
+ /**
+ * Get the public value y with y = g^x mod p where x is the secret key.
+ */
const BigInt& get_y() const { return y; }
+
+ /**
+ * Get the prime p of the underlying DL group.
+ * @return the prime p
+ */
const BigInt& group_p() const { return group.get_p(); }
+
+ /**
+ * Get the prime q of the underlying DL group.
+ * @return the prime q
+ */
const BigInt& group_q() const { return group.get_q(); }
+
+ /**
+ * Get the generator g of the underlying DL group.
+ * @return the generator g
+ */
const BigInt& group_g() const { return group.get_g(); }
+
+ /**
+ * Get the underlying groups encoding format.
+ * @return the encoding format
+ */
virtual DL_Group::Format group_format() const = 0;
+ /**
+ * Get an X509 encoder for this key.
+ * @return an encoder usable to encode this key.
+ */
X509_Encoder* x509_encoder() const;
+
+ /**
+ * Get an X509 decoder for this key.
+ * @return an decoder usable to decode a DL key and store the
+ * values in this instance.
+ */
X509_Decoder* x509_decoder();
protected:
BigInt y;
@@ -37,19 +75,34 @@ class BOTAN_DLL DL_Scheme_PublicKey : public virtual Public_Key
virtual void X509_load_hook() {}
};
-/*************************************************
-* DL Private Key *
-*************************************************/
+/**
+* This class represents discrete logarithm (DL) private keys.
+*/
class BOTAN_DLL DL_Scheme_PrivateKey : public virtual DL_Scheme_PublicKey,
public virtual Private_Key
{
public:
bool check_key(RandomNumberGenerator& rng, bool) const;
+ /**
+ * Get the secret key x.
+ * @return the secret key
+ */
const BigInt& get_x() const { return x; }
+ /**
+ * Get an PKCS#8 encoder for this key.
+ * @return an encoder usable to encode this key.
+ */
PKCS8_Encoder* pkcs8_encoder() const;
- PKCS8_Decoder* pkcs8_decoder(RandomNumberGenerator&);
+
+ /**
+ * Get an PKCS#8 decoder for this key.
+ * @param rng the rng to use
+ * @return an decoder usable to decode a DL key and store the
+ * values in this instance.
+ */
+ PKCS8_Decoder* pkcs8_decoder(RandomNumberGenerator& rng);
protected:
BigInt x;
private:
diff --git a/src/pubkey/dl_group/dl_group.h b/src/pubkey/dl_group/dl_group.h
index 7d631433e..b999a8c04 100644
--- a/src/pubkey/dl_group/dl_group.h
+++ b/src/pubkey/dl_group/dl_group.h
@@ -11,16 +11,34 @@
namespace Botan {
-/*************************************************
-* Discrete Logarithm Group *
-*************************************************/
+/**
+* This class represents discrete logarithm groups. It holds a prime p,
+* a prime q = (p-1)/2 and g = x^((p-1)/q) mod p.
+*/
class BOTAN_DLL DL_Group
{
public:
+ /**
+ * Get the prime p.
+ * @return the prime p
+ */
const BigInt& get_p() const;
+
+ /**
+ * Get the prime q.
+ * @return the prime q
+ */
const BigInt& get_q() const;
+
+ /**
+ * Get the base g.
+ * @return the base g
+ */
const BigInt& get_g() const;
+ /**
+ * The DL group encoding format variants.
+ */
enum Format {
ANSI_X9_42,
ANSI_X9_57,
@@ -32,23 +50,101 @@ class BOTAN_DLL DL_Group
PKCS3_DH_PARAMETERS = PKCS_3
};
+ /**
+ * Determine the prime creation for DL groups.
+ */
enum PrimeType { Strong, Prime_Subgroup, DSA_Kosherizer };
- bool verify_group(RandomNumberGenerator& rng, bool) const;
+ /**
+ * Perform validity checks on the group.
+ * @param rng the rng to use
+ * @param strong whether to perform stronger by lengthier tests
+ * @return true if the object is consistent, false otherwise
+ */
+ bool verify_group(RandomNumberGenerator& rng, bool strong) const;
+
+ /**
+ * Encode this group into a string using PEM encoding.
+ * @param format the encoding format
+ * @return the string holding the PEM encoded group
+ */
+ std::string PEM_encode(Format format) const;
- std::string PEM_encode(Format) const;
- SecureVector<byte> DER_encode(Format) const;
- void BER_decode(DataSource&, Format);
- void PEM_decode(DataSource&);
+ /**
+ * Encode this group into a string using DER encoding.
+ * @param format the encoding format
+ * @return the string holding the DER encoded group
+ */
+ SecureVector<byte> DER_encode(Format format) const;
+ /**
+ * Decode a DER/BER encoded group into this instance.
+ * @param src a DataSource providing the encoded group
+ * @param format the format of the encoded group
+ */
+ void BER_decode(DataSource& src, Format format);
+
+ /**
+ * Decode a PEM encoded group into this instance.
+ * @param src a DataSource providing the encoded group
+ */
+ void PEM_decode(DataSource& src);
+
+ /**
+ * Construct a DL group with uninitialized internal value.
+ * Use this constructor is you wish to set the groups values
+ * from a DER or PEM encoded group.
+ */
DL_Group();
- DL_Group(const std::string&);
- DL_Group(RandomNumberGenerator& rng, PrimeType, u32bit, u32bit = 0);
- DL_Group(RandomNumberGenerator& rng, const MemoryRegion<byte>&,
- u32bit = 1024, u32bit = 0);
+ /**
+ * Construct a DL group that is registered in the configuration.
+ * @param name the name that is configured in the global configuration
+ * for the desired group. If no configuration file is specified,
+ * the default values from the file policy.cpp will be used. For instance,
+ * use "modp/ietf/768" as name.
+ */
+ DL_Group(const std::string& name);
+
+ /**
+ * Create a new group randomly.
+ * @param rng the random number generator to use
+ * @param type specifies how the creation of primes p and q shall
+ * be performed. If type=Strong, then p will be determined as a
+ * safe prime, and q will be chosen as (p-1)/2. If
+ * type=Prime_Subgroup and qbits = 0, then the size of q will be
+ * determined according to the estimated difficulty of the DL
+ * problem. If type=DSA_Kosherizer, DSA primes will be created.
+ * @param pbits the number of bits of p
+ * @param qbits the number of bits of q. Leave it as 0 to have
+ * the value determined according to pbits.
+ */
+ DL_Group(RandomNumberGenerator& rng, PrimeType type,
+ u32bit pbits, u32bit qbits = 0);
+ /**
+ * Create a DSA group with a given seed.
+ * @param rng the random number generator to use
+ * @param seed the seed to use to create the random primes
+ * @param pbits the desired bit size of the prime p
+ * @param qbits the desired bit size of the prime q.
+ */
+ DL_Group(RandomNumberGenerator& rng, const MemoryRegion<byte>& seed,
+ u32bit pbits = 1024, u32bit qbits = 0);
+
+ /**
+ * Create a DL group. The prime q will be determined according to p.
+ * @param p the prime p
+ * @param g the base g
+ */
DL_Group(const BigInt& p, const BigInt& g);
+
+ /**
+ * Create a DL group.
+ * @param p the prime p
+ * @param q the prime q
+ * @param g the base g
+ */
DL_Group(const BigInt& p, const BigInt& g, const BigInt& q);
private:
static BigInt make_dsa_generator(const BigInt&, const BigInt&);
diff --git a/src/pubkey/pubkey/x509_key.h b/src/pubkey/pubkey/x509_key.h
index abaeaaced..9cf6d5d67 100644
--- a/src/pubkey/pubkey/x509_key.h
+++ b/src/pubkey/pubkey/x509_key.h
@@ -13,9 +13,9 @@
namespace Botan {
-/*************************************************
-* X.509 Public Key Encoder *
-*************************************************/
+/**
+* This class represents abstract X.509 public key encoders.
+*/
class BOTAN_DLL X509_Encoder
{
public:
@@ -24,9 +24,9 @@ class BOTAN_DLL X509_Encoder
virtual ~X509_Encoder() {}
};
-/*************************************************
-* X.509 Public Key Decoder *
-*************************************************/
+/**
+* This class represents abstract X.509 public key decoders.
+*/
class BOTAN_DLL X509_Decoder
{
public:
@@ -35,21 +35,67 @@ class BOTAN_DLL X509_Decoder
virtual ~X509_Decoder() {}
};
+/**
+* This namespace contains functions for handling X509 objects.
+*/
namespace X509 {
/*************************************************
* X.509 Public Key Encoding/Decoding *
*************************************************/
-BOTAN_DLL void encode(const Public_Key&, Pipe&, X509_Encoding = PEM);
-BOTAN_DLL std::string PEM_encode(const Public_Key&);
-BOTAN_DLL Public_Key* load_key(DataSource&);
-BOTAN_DLL Public_Key* load_key(const std::string&);
-BOTAN_DLL Public_Key* load_key(const MemoryRegion<byte>&);
+/**
+* Encode a key into a pipe.
+* @param key the public key to encode
+* @param pipe the pipe to feed the encoded key into
+* @param enc the encoding type to use
+*/
+BOTAN_DLL void encode(const Public_Key& key, Pipe& pipe, X509_Encoding enc = PEM);
+
+/**
+* PEM encode a public key into a string.
+* @param key the key to encode
+* @return the PEM encoded key
+*/
+BOTAN_DLL std::string PEM_encode(const Public_Key& key);
+
+/**
+* Create a public key from a data source.
+* @param source the source providing the DER or PEM encoded key
+* @return the new public key object
+*/
+BOTAN_DLL Public_Key* load_key(DataSource& source);
+
+/**
+* Create a public key from a string.
+* @param enc the string containing the PEM encoded key
+* @return the new public key object
+*/
+BOTAN_DLL Public_Key* load_key(const std::string& enc);
+
+/**
+* Create a public key from a memory region.
+* @param enc the memory region containing the DER or PEM encoded key
+* @return the new public key object
+*/
+BOTAN_DLL Public_Key* load_key(const MemoryRegion<byte>& enc);
-BOTAN_DLL Public_Key* copy_key(const Public_Key&);
+/**
+* Copy a key.
+* @param key the public key to copy
+* @return the new public key object
+*/
+BOTAN_DLL Public_Key* copy_key(const Public_Key& key);
-BOTAN_DLL Key_Constraints find_constraints(const Public_Key&, Key_Constraints);
+/**
+* Create the key constraints for a specific public key.
+* @param pub_key the public key from which the basic set of constraints
+* to be placed in the return value is
+* derived
+* @param limits additional limits that will be incorporated into the return value
+* @return the combination of key type specific constraints and additional limits
+*/
+BOTAN_DLL Key_Constraints find_constraints(const Public_Key& pub_key, Key_Constraints limits);
}
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-04 18:47:53 +0000