OpenSSL::PKey::DSA

Class

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 Methods

DSA.generate(size) → dsa

ext/openssl/lib/openssl/pkey.rb View on GitHub

          
            # File tmp/rubies/ruby-3.4.0-preview1/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

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

size: The desired key size in bits.

DSA.new(string [, pass]) → dsa

dsa.export([cipher, password]) → aString

ext/openssl/ossl_pkey_dsa.c View on GitHub

          
            static VALUE
ossl_dsa_export(int argc, VALUE *argv, VALUE self)
{
    OSSL_3_const 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);
}

Serializes a private or public key to a PEM-encoding.

When the key contains public components only

Serializes it into an X.509 SubjectPublicKeyInfo. The parameters cipher and password are ignored.

A PEM-encoded key will look like:

-----BEGIN PUBLIC KEY-----
[...]
-----END PUBLIC KEY-----

Consider using public_to_pem instead. This serializes the key into an X.509 SubjectPublicKeyInfo regardless of whether it is a public key or a private key.

When the key contains private components, and no parameters are given

Serializes it into a traditional OpenSSL DSAPrivateKey.

A PEM-encoded key will look like:

-----BEGIN DSA PRIVATE KEY-----
[...]
-----END DSA PRIVATE KEY-----

When the key contains private components, and cipher and password are given

Serializes it into a traditional OpenSSL DSAPrivateKey and encrypts it in OpenSSL’s traditional PEM encryption format. cipher must be a cipher name understood by OpenSSL::Cipher.new or an instance of OpenSSL::Cipher.

An encrypted PEM-encoded key will look like:

-----BEGIN DSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0

[...]
-----END DSA PRIVATE KEY-----

Note that this format uses MD5 to derive the encryption key, and hence will not be available on FIPS-compliant systems.

This method is kept for compatibility. This should only be used when the traditional, non-standard OpenSSL format is required.

Consider using public_to_pem (X.509 SubjectPublicKeyInfo) or private_to_pem (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.

initialize_copy(p1)

ext/openssl/ossl_pkey_dsa.c View on GitHub

          
            HAVE_EVP_PKEY_DUP
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;
}

No documentation available

dsa.params → hash

ext/openssl/ossl_pkey_dsa.c View on GitHub

          
            static VALUE
ossl_dsa_get_params(VALUE self)
{
    OSSL_3_const 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;
}

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

dsa.private? → true | false

ext/openssl/ossl_pkey_dsa.c View on GitHub

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

    GetDSA(self, dsa);

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

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

dsa.public? → true | false

ext/openssl/ossl_pkey_dsa.c View on GitHub

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

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

    return bn ? Qtrue : Qfalse;
}

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

dsa.public_key → dsanew

ext/openssl/lib/openssl/pkey.rb View on GitHub

          
            # File tmp/rubies/ruby-3.4.0-preview1/ext/openssl/lib/openssl/pkey.rb, line 153
def public_key
  OpenSSL::PKey.read(public_to_der)
end

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.

dsa.set_key(pub_key, priv_key) → self

ext/openssl/ossl_pkey_dsa.c View on GitHub

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

dsa.set_pqg(p, q, g) → self

ext/openssl/ossl_pkey_dsa.c View on GitHub

Sets p, q, g to the DSA instance.

dsa.syssign(string) → string

ext/openssl/lib/openssl/pkey.rb View on GitHub

          
            # File tmp/rubies/ruby-3.4.0-preview1/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

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::PKey#sign_raw and PKey::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

dsa.sysverify(digest, sig) → true | false

ext/openssl/lib/openssl/pkey.rb View on GitHub

          
            # File tmp/rubies/ruby-3.4.0-preview1/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

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::PKey#sign_raw and PKey::PKey#verify_raw instead.

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

dsa.to_der → aString

ext/openssl/ossl_pkey_dsa.c View on GitHub

          
            static VALUE
ossl_dsa_to_der(VALUE self)
{
    OSSL_3_const 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);
}

Serializes a private or public key to a DER-encoding.

See to_pem for details.

This method is kept for compatibility. This should only be used when the traditional, non-standard OpenSSL format is required.

Consider using public_to_der or private_to_der instead.

dsa.to_pem([cipher, password]) → aString

ext/openssl/ossl_pkey_dsa.c View on GitHub

An alias for export

dsa.to_s([cipher, password]) → aString

ext/openssl/ossl_pkey_dsa.c View on GitHub

An alias for export

OpenSSL::PKey::DSA

DSA.generate(size) → dsa

DSA.new → dsa

DSA.new(string [, pass]) → dsa

DSA.new(size) → dsa

dsa.export([cipher, password]) → aString

initialize_copy(p1)

dsa.params → hash

dsa.private? → true | false

dsa.public? → true | false

dsa.public_key → dsanew

dsa.set_key(pub_key, priv_key) → self

dsa.set_pqg(p, q, g) → self

dsa.syssign(string) → string

dsa.sysverify(digest, sig) → true | false

dsa.to_der → aString

dsa.to_pem([cipher, password]) → aString

dsa.to_s([cipher, password]) → aString