Commit f4f00d46 authored by Steven Fackler's avatar Steven Fackler Committed by GitHub
Browse files

Merge pull request #755 from AndyGauge/doc-dsa 

Documentation for DSA module
parents 44a000f3 80efaf72

openssl/src/dsa.rs

+60 −0
Original line number Diff line number Diff line 
//! Digital Signatures

//!

//! DSA ensures a message originated from a known sender, and was not modified.

//! DSA uses asymetrical keys and an algorithm to output a signature of the message

//! using the private key that can be validated with the public key but not be generated

//! without the private key.



use ffi;

use foreign_types::ForeignTypeRef;

use libc::{c_int, c_char, c_void};
@@ -14,7 +21,39 @@ foreign_type! { 
    type CType = ffi::DSA;

    fn drop = ffi::DSA_free;



    /// Object representing DSA keys.

    ///

    /// A DSA object contains the parameters p, q, and g.  There is a private

    /// and public key.  The values p, g, and q are:

    ///

    /// * `p`: DSA prime parameter

    /// * `q`: DSA sub-prime parameter

    /// * `g`: DSA base parameter

    ///

    /// These values are used to calculate a pair of asymetrical keys used for

    /// signing.

    ///

    /// OpenSSL documentation at [`DSA_new`]

    ///

    /// [`DSA_new`]: https://www.openssl.org/docs/man1.1.0/crypto/DSA_new.html

    ///

    /// # Examples

    ///

    /// ```

    /// use openssl::dsa::Dsa;

    /// use openssl::error::ErrorStack;

    /// fn create_dsa() -> Result< Dsa, ErrorStack > {

    ///     let sign = Dsa::generate(2048)?;

    ///     Ok(sign)

    /// }

    /// # fn main() {

    /// #    create_dsa();

    /// # }

    /// ```

    pub struct Dsa;

    /// Reference to [`Dsa`].

    ///

    /// [`Dsa`]: struct.Dsa.html

    pub struct DsaRef;

}
@@ -25,6 +64,12 @@ impl DsaRef { 
    private_key_to_der!(ffi::i2d_DSAPrivateKey);

    public_key_to_der!(ffi::i2d_DSAPublicKey);



    /// Returns the maximum size of the signature output by `self` in bytes.  Returns

    /// None if the keys are uninitialized.

    ///

    /// OpenSSL documentation at [`DSA_size`]

    ///

    /// [`DSA_size`]: https://www.openssl.org/docs/man1.1.0/crypto/DSA_size.html

    // FIXME should return u32

    pub fn size(&self) -> Option<u32> {

        if self.q().is_some() {
@@ -34,6 +79,7 @@ impl DsaRef { 
        }

    }



    /// Returns the DSA prime parameter of `self`.

    pub fn p(&self) -> Option<&BigNumRef> {

        unsafe {

            let p = compat::pqg(self.as_ptr())[0];
@@ -45,6 +91,7 @@ impl DsaRef { 
        }

    }



    /// Returns the DSA sub-prime parameter of `self`.

    pub fn q(&self) -> Option<&BigNumRef> {

        unsafe {

            let q = compat::pqg(self.as_ptr())[1];
@@ -56,6 +103,7 @@ impl DsaRef { 
        }

    }



    /// Returns the DSA base parameter of `self`.

    pub fn g(&self) -> Option<&BigNumRef> {

        unsafe {

            let g = compat::pqg(self.as_ptr())[2];
@@ -67,10 +115,14 @@ impl DsaRef { 
        }

    }



    /// Returns whether the DSA includes a public key, used to confirm the authenticity

    /// of the message.

    pub fn has_public_key(&self) -> bool {

        unsafe { !compat::keys(self.as_ptr())[0].is_null() }

    }



    /// Returns whether the DSA includes a private key, used to prove the authenticity

    /// of a message.

    pub fn has_private_key(&self) -> bool {

        unsafe { !compat::keys(self.as_ptr())[1].is_null() }

    }
@@ -78,6 +130,14 @@ impl DsaRef { 


impl Dsa {

    /// Generate a DSA key pair.

    ///

    /// Calls [`DSA_generate_parameters_ex`] to populate the `p`, `g`, and `q` values.

    /// These values are used to generate the key pair with [`DSA_generate_key`].

    ///

    /// The `bits` parameter coresponds to the length of the prime `p`.

    ///

    /// [`DSA_generate_parameters_ex`]: https://www.openssl.org/docs/man1.1.0/crypto/DSA_generate_parameters_ex.html

    /// [`DSA_generate_key`]: https://www.openssl.org/docs/man1.1.0/crypto/DSA_generate_key.html

    pub fn generate(bits: u32) -> Result<Dsa, ErrorStack> {

        ffi::init();

        unsafe {