Class: OpenSSL::PKey::DSA

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `PKey`
Instance Chain: self, `::OpenSSL::Marshal`, `PKey`
Inherits:	OpenSSL::PKey::PKey `::Object` OpenSSL::PKey::PKey OpenSSL::PKey::DSA
Defined in:	ext/openssl/ossl_pkey_dsa.c, ext/openssl/lib/openssl/pkey.rb

Overview

DSA, the Digital Signature Algorithm, is specified in NIST’s FIPS 186-3. It is an asymmetric public key algorithm that may be used similar to e.g. RSA.

Class Method Summary

.generate(size) ⇒ DSA

Creates a new DSA instance by generating a private/public key pair from scratch.
.new ⇒ DSA constructor Internal use only

Creates a new DSA instance by reading an existing key from string.

`PKey` - Inherited

.new	Because PKey is an abstract class, actually calling this method explicitly will raise a NotImplementedError.

Instance Attribute Summary

#private? ⇒ Boolean readonly

Indicates whether this DSA instance has a private key associated with it or not.
#public? ⇒ Boolean readonly

Indicates whether this DSA instance has a public key associated with it or not.

Instance Method Summary

#export([cipher, password]) ⇒ String

Alias for #to_s.
#initialize_copy(other)
#params ⇒ Hash

Stores all parameters of key to the hash INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!! Don’t use :-)) (I’s up to you).
#public_key ⇒ DSA

Returns a new DSA instance that carries just the DSA parameters and the public key.
#set_key(pub_key, priv_key) ⇒ self

Sets pub_key and priv_key for the DSA instance.
#set_pqg(p, q, g) ⇒ self

Sets p, q, g to the DSA instance.
#syssign(string) ⇒ String

Computes and returns the DSA signature of string, where string is expected to be an already-computed message digest of the original input data.
#sysverify(digest, sig) ⇒ Boolean

Verifies whether the signature is valid given the message digest input.
#to_der ⇒ String

Encodes this DSA to its DER encoding.
#to_pem([cipher, password]) ⇒ String

Alias for #to_s.
#to_s([cipher, password]) ⇒ String (also: #export, #to_pem)

Encodes this DSA to its PEM encoding.

`::OpenSSL::Marshal` - Included

#_dump

`PKey` - Inherited

#compare?	Used primarily to check if an X509::Certificate#public_key compares to its private key.
#decrypt	Performs a public key decryption operation using `pkey`.
#derive	Derives a shared secret from pkey and peer_pkey.
#encrypt	Performs a public key encryption operation using `pkey`.
#initialize_copy,
#inspect	Returns a string describing the `PKey` object.
#oid	Returns the short name of the OID associated with pkey.
#private_to_der	Serializes the private key to DER-encoded PKCS #8 format.
#private_to_pem	Serializes the private key to PEM-encoded PKCS #8 format.
#public_to_der	Serializes the public key to DER-encoded X.509 SubjectPublicKeyInfo format.
#public_to_pem	Serializes the public key to PEM-encoded X.509 SubjectPublicKeyInfo format.
#sign	Hashes and signs the `data` using a message digest algorithm `digest` and a private key `pkey`.
#sign_raw	Signs `data` using a private key `pkey`.
#to_text	Dumps key parameters, public key, and private key components contained in the key into a human-readable text.
#verify	Verifies the `signature` for the `data` using a message digest algorithm `digest` and a public key `pkey`.
#verify_raw	Verifies the `signature` for the `data` using a public key `pkey`.
#verify_recover	Recovers the signed data from `signature` using a public key `pkey`.

Constructor Details

.new ⇒ `DSA` .new(string [, pass]) ⇒ `DSA` .new(size) ⇒ `DSA`

This method is for internal use only.

Creates a new DSA instance by reading an existing key from string.

If called without arguments, creates a new instance with no key components set. They can be set individually by #set_pqg and #set_key.

If called with a String, tries to parse as DER or PEM encoding of a DSA key. See also OpenSSL::PKey.read which can parse keys of any kinds.

If called with a number, generates random parameters and a key pair. This form works as an alias of .generate.

string: A String that contains a DER or PEM encoded key.
pass: A String that contains an optional password.
size: See DSA.generate.

Examples:

p OpenSSL::PKey::DSA.new(1024)
#=> #<OpenSSL::PKey::DSA:0x000055a8d6025bf0 oid=DSA>

p OpenSSL::PKey::DSA.new(File.read('dsa.pem'))
#=> #<OpenSSL::PKey::DSA:0x000055555d6b8110 oid=DSA>

p OpenSSL::PKey::DSA.new(File.read('dsa.pem'), 'mypassword')
#=> #<OpenSSL::PKey::DSA:0x0000556f973c40b8 oid=DSA>

[ GitHub ]

# File 'ext/openssl/ossl_pkey_dsa.c', line 83


static VALUE
ossl_dsa_initialize(int argc, VALUE *argv, VALUE self)
{
    EVP_PKEY *pkey;
    DSA *dsa;
    BIO *in = NULL;
    VALUE arg, pass;
    int type;

    TypedData_Get_Struct(self, EVP_PKEY, &ossl_evp_pkey_type, pkey);
    if (pkey)
        rb_raise(rb_eTypeError, "pkey already initialized");

    /* The DSA.new(size, generator) form is handled by lib/openssl/pkey.rb */
    rb_scan_args(argc, argv, "02", &arg, &pass);
    if (argc == 0) {
        dsa = DSA_new();
        if (!dsa)
            ossl_raise(eDSAError, "DSA_new");
        goto legacy;
    }

    pass = ossl_pem_passwd_value(pass);
    arg = ossl_to_der_if_possible(arg);
    in = ossl_obj2bio(&arg);

    /* DER-encoded DSAPublicKey format isn't supported by the generic routine */
    dsa = (DSA *)PEM_ASN1_read_bio((d2i_of_void *)d2i_DSAPublicKey,
                                   PEM_STRING_DSA_PUBLIC,
                                   in, NULL, NULL, NULL);
    if (dsa)
        goto legacy;
    OSSL_BIO_reset(in);

    pkey = ossl_pkey_read_generic(in, pass);
    BIO_free(in);
    if (!pkey)
        ossl_raise(eDSAError, "Neither PUB key nor PRIV key");

    type = EVP_PKEY_base_id(pkey);
    if (type != EVP_PKEY_DSA) {
        EVP_PKEY_free(pkey);
        rb_raise(eDSAError, "incorrect pkey type: %s", OBJ_nid2sn(type));
    }
    RTYPEDDATA_DATA(self) = pkey;
    return self;

  legacy:
    BIO_free(in);
    pkey = EVP_PKEY_new();
    if (!pkey || EVP_PKEY_assign_DSA(pkey, dsa) != 1) {
        EVP_PKEY_free(pkey);
        DSA_free(dsa);
        ossl_raise(eDSAError, "EVP_PKEY_assign_DSA");
    }
    RTYPEDDATA_DATA(self) = pkey;
    return self;
}

Class Method Details

.generate(size) ⇒ `DSA`

Creates a new DSA instance by generating a private/public key pair from scratch.

size: The desired key size in bits.

[ GitHub ]

# File 'ext/openssl/lib/openssl/pkey.rb', line 169


def generate(size, &blk)
  # FIPS 186-4 specifies four (L,N) pairs: (1024,160), (2048,224),
  # (2048,256), and (3072,256).
  #
  # q size is derived here with compatibility with
  # DSA_generator_parameters_ex() which previous versions of ruby/openssl
  # used to call.
  qsize = size >= 2048 ? 256 : 160
  dsaparams = OpenSSL::PKey.generate_parameters("DSA", {
    "dsa_paramgen_bits" => size,
    "dsa_paramgen_q_bits" => qsize,
  }, &blk)
  OpenSSL::PKey.generate_key(dsaparams)
end

Instance Attribute Details

#private? ⇒ `Boolean` (readonly)

Indicates whether this DSA instance has a private key associated with it or not. The private key may be retrieved with DSA#private_key.

[ GitHub ]

# File 'ext/openssl/ossl_pkey_dsa.c', line 198


static VALUE
ossl_dsa_is_private(VALUE self)
{
    DSA *dsa;

    GetDSA(self, dsa);

    return DSA_PRIVATE(self, dsa) ? Qtrue : Qfalse;
}

#public? ⇒ `Boolean` (readonly)

Indicates whether this DSA instance has a public key associated with it or not. The public key may be retrieved with #public_key.

[ GitHub ]

# File 'ext/openssl/ossl_pkey_dsa.c', line 179


static VALUE
ossl_dsa_is_public(VALUE self)
{
    DSA *dsa;
    const BIGNUM *bn;

    GetDSA(self, dsa);
    DSA_get0_key(dsa, &bn, NULL);

    return bn ? Qtrue : Qfalse;
}

Instance Method Details

#export([cipher, password]) ⇒ `String` #to_pem([cipher, password]) ⇒ `String` #to_s([cipher, password]) ⇒ `String`

Alias for #to_s.

#initialize_copy(other)

[ GitHub ]

# File 'ext/openssl/ossl_pkey_dsa.c', line 143


static VALUE
ossl_dsa_initialize_copy(VALUE self, VALUE other)
{
    EVP_PKEY *pkey;
    DSA *dsa, *dsa_new;

    TypedData_Get_Struct(self, EVP_PKEY, &ossl_evp_pkey_type, pkey);
    if (pkey)
        rb_raise(rb_eTypeError, "pkey already initialized");
    GetDSA(other, dsa);

    dsa_new = (DSA *)ASN1_dup((i2d_of_void *)i2d_DSAPrivateKey,
                              (d2i_of_void *)d2i_DSAPrivateKey,
                              (char *)dsa);
    if (!dsa_new)
	ossl_raise(eDSAError, "ASN1_dup");

    pkey = EVP_PKEY_new();
    if (!pkey || EVP_PKEY_assign_DSA(pkey, dsa_new) != 1) {
        EVP_PKEY_free(pkey);
        DSA_free(dsa_new);
        ossl_raise(eDSAError, "EVP_PKEY_assign_DSA");
    }
    RTYPEDDATA_DATA(self) = pkey;

    return self;
}

#params ⇒ `Hash`

Stores all parameters of key to the hash INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!! Don’t use :-)) (I’s up to you)

[ GitHub ]

# File 'ext/openssl/ossl_pkey_dsa.c', line 265


static VALUE
ossl_dsa_get_params(VALUE self)
{
    DSA *dsa;
    VALUE hash;
    const BIGNUM *p, *q, *g, *pub_key, *priv_key;

    GetDSA(self, dsa);
    DSA_get0_pqg(dsa, &p, &q, &g);
    DSA_get0_key(dsa, &pub_key, &priv_key);

    hash = rb_hash_new();
    rb_hash_aset(hash, rb_str_new2("p"), ossl_bn_new(p));
    rb_hash_aset(hash, rb_str_new2("q"), ossl_bn_new(q));
    rb_hash_aset(hash, rb_str_new2("g"), ossl_bn_new(g));
    rb_hash_aset(hash, rb_str_new2("pub_key"), ossl_bn_new(pub_key));
    rb_hash_aset(hash, rb_str_new2("priv_key"), ossl_bn_new(priv_key));

    return hash;
}

#public_key ⇒ `DSA`

Returns a new DSA instance that carries just the DSA parameters and the public key.

This method is provided for backwards compatibility. In most cases, there is no need to call this method.

For the purpose of serializing the public key, to PEM or DER encoding of X.509 SubjectPublicKeyInfo format, check PKey#public_to_pem and PKey#public_to_der.

[ GitHub ]

# File 'ext/openssl/lib/openssl/pkey.rb', line 153


def public_key
  OpenSSL::PKey.read(public_to_der)
end

#set_key(pub_key, priv_key) ⇒ `self`

Sets pub_key and priv_key for the DSA instance. priv_key may be nil.

[ GitHub ]

#set_pqg(p, q, g) ⇒ `self`

Sets p, q, g to the DSA instance.

[ GitHub ]

#syssign(string) ⇒ `String`

Computes and returns the DSA signature of string, where string is expected to be an already-computed message digest of the original input data. The signature is issued using the private key of this DSA instance.

Deprecated in version 3.0. Consider using PKey#sign_raw and PKey#verify_raw instead.

string: A message digest of the original input data to be signed.

Example:

dsa = OpenSSL::PKey::DSA.new(2048)
doc = "Sign me"
digest = OpenSSL::Digest.digest('SHA1', doc)

# With legacy #syssign and #sysverify:
sig = dsa.syssign(digest)
p dsa.sysverify(digest, sig) #=> true

# With #sign_raw and #verify_raw:
sig = dsa.sign_raw(nil, digest)
p dsa.verify_raw(nil, sig, digest) #=> true

[ GitHub ]

# File 'ext/openssl/lib/openssl/pkey.rb', line 220


def syssign(string)
  q or raise OpenSSL::PKey::DSAError, "incomplete DSA"
  private? or raise OpenSSL::PKey::DSAError, "Private DSA key needed!"
  begin
    sign_raw(nil, string)
  rescue OpenSSL::PKey::PKeyError
    raise OpenSSL::PKey::DSAError, $!.message
  end
end

#sysverify(digest, sig) ⇒ `Boolean`

Verifies whether the signature is valid given the message digest input. It does so by validating sig using the public key of this DSA instance.

Deprecated in version 3.0. Consider using PKey#sign_raw and PKey#verify_raw instead.

digest: A message digest of the original input data to be signed.
sig: A DSA signature value.

[ GitHub ]

# File 'ext/openssl/lib/openssl/pkey.rb', line 243


def sysverify(digest, sig)
  verify_raw(nil, sig, digest)
rescue OpenSSL::PKey::PKeyError
  raise OpenSSL::PKey::DSAError, $!.message
end

#to_der ⇒ `String`

Encodes this DSA to its DER encoding.

[ GitHub ]

# File 'ext/openssl/ossl_pkey_dsa.c', line 244


static VALUE
ossl_dsa_to_der(VALUE self)
{
    DSA *dsa;

    GetDSA(self, dsa);
    if (DSA_HAS_PRIVATE(dsa))
        return ossl_pkey_export_traditional(0, NULL, self, 1);
    else
        return ossl_pkey_export_spki(self, 1);
}

#export([cipher, password]) ⇒ `String` #to_pem([cipher, password]) ⇒ `String` #to_s([cipher, password]) ⇒ `String`

Alias for #to_s.

#export([cipher, password]) ⇒ `String` #to_pem([cipher, password]) ⇒ `String` #to_s([cipher, password]) ⇒ `String`
Also known as: #export, #to_pem

Encodes this DSA to its PEM encoding.

Parameters

cipher is an ::OpenSSL::Cipher.
password is a string containing your password.

Examples

DSA.to_pem -> aString
DSA.to_pem(cipher, 'mypassword') -> aString

[ GitHub ]

# File 'ext/openssl/ossl_pkey_dsa.c', line 225


static VALUE
ossl_dsa_export(int argc, VALUE *argv, VALUE self)
{
    DSA *dsa;

    GetDSA(self, dsa);
    if (DSA_HAS_PRIVATE(dsa))
        return ossl_pkey_export_traditional(argc, argv, self, 0);
    else
        return ossl_pkey_export_spki(self, 0);
}

Class: OpenSSL::PKey::DSA

Overview

Class Method Summary

PKey - Inherited

Instance Attribute Summary

Instance Method Summary

::OpenSSL::Marshal - Included

PKey - Inherited

Constructor Details

.new ⇒ DSA .new(string [, pass]) ⇒ DSA .new(size) ⇒ DSA

Class Method Details

.generate(size) ⇒ DSA

Instance Attribute Details

#private? ⇒ Boolean (readonly)

#public? ⇒ Boolean (readonly)

Instance Method Details

#export([cipher, password]) ⇒ String #to_pem([cipher, password]) ⇒ String #to_s([cipher, password]) ⇒ String

#initialize_copy(other)

#params ⇒ Hash

#public_key ⇒ DSA

#set_key(pub_key, priv_key) ⇒ self

#set_pqg(p, q, g) ⇒ self

#syssign(string) ⇒ String

#sysverify(digest, sig) ⇒ Boolean

#to_der ⇒ String

#export([cipher, password]) ⇒ String #to_pem([cipher, password]) ⇒ String #to_s([cipher, password]) ⇒ String

#export([cipher, password]) ⇒ String #to_pem([cipher, password]) ⇒ String #to_s([cipher, password]) ⇒ String Also known as: #export, #to_pem

Parameters

Examples

`PKey` - Inherited

`::OpenSSL::Marshal` - Included

`PKey` - Inherited

.new ⇒ `DSA` .new(string [, pass]) ⇒ `DSA` .new(size) ⇒ `DSA`

.generate(size) ⇒ `DSA`

#private? ⇒ `Boolean` (readonly)

#public? ⇒ `Boolean` (readonly)

#export([cipher, password]) ⇒ `String` #to_pem([cipher, password]) ⇒ `String` #to_s([cipher, password]) ⇒ `String`

#params ⇒ `Hash`

#public_key ⇒ `DSA`

#set_key(pub_key, priv_key) ⇒ `self`

#set_pqg(p, q, g) ⇒ `self`

#syssign(string) ⇒ `String`

#sysverify(digest, sig) ⇒ `Boolean`

#to_der ⇒ `String`

#export([cipher, password]) ⇒ `String` #to_pem([cipher, password]) ⇒ `String` #to_s([cipher, password]) ⇒ `String`

#export([cipher, password]) ⇒ `String` #to_pem([cipher, password]) ⇒ `String` #to_s([cipher, password]) ⇒ `String`
Also known as: #export, #to_pem