Class: OpenSSL::PKey::DSA

Inherits:
PKey
  • Object
show all
Includes:
Marshal
Defined in:
ext/openssl/ossl_pkey_dsa.c,
lib/openssl/pkey.rb,
ext/openssl/ossl_pkey_dsa.c

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 collapse

Instance Method Summary collapse

Methods included from Marshal

#_dump, included

Constructor Details

#new ⇒ Object #new(string[, pass]) ⇒ Object #new(size) ⇒ Object

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 DSA.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>



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# 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, &blk) ⇒ Object

:call-seq:

DSA.generate(size) -> dsa

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

See also OpenSSL::PKey.generate_parameters and OpenSSL::PKey.generate_key.

size

The desired key size in bits.



169
170
171
172
173
174
 
# File 'lib/openssl/pkey.rb', line 169

def generate(size, &blk)
  dsaparams = OpenSSL::PKey.generate_parameters("DSA", {
    "dsa_paramgen_bits" => size,
  }, &blk)
  OpenSSL::PKey.generate_key(dsaparams)
end

.new(*args, &blk) ⇒ Object

Handle DSA.new(size) form here; new(str) and new() forms are handled by #initialize



178
179
180
181
182
183
184
 
# File 'lib/openssl/pkey.rb', line 178

def new(*args, &blk) # :nodoc:
  if args[0].is_a?(Integer)
    generate(*args, &blk)
  else
    super
  end
end

Instance Method Details

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

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

Overloads:

  • #export([cipher, password]) ⇒ aString

    Returns:

    • (aString)
  • #to_pem([cipher, password]) ⇒ aString

    Returns:

    • (aString)
  • #to_s([cipher, password]) ⇒ aString

    Returns:

    • (aString) 


225
226
227
228
229
230
231
232
233
234
235
 
# 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);
}

#initialize_copy(other) ⇒ Object 



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# 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)

Returns:

  • (Hash) 


265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# 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;
}

#private? ⇒ Boolean

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

Returns:

  • (Boolean) 


198
199
200
201
202
203
204
205
206
 
# 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

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

Returns:

  • (Boolean) 


179
180
181
182
183
184
185
186
187
188
189
 
# 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;
}

#public_key ⇒ Object

:call-seq:

dsa.public_key -> dsanew

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.



153
154
155
 
# File '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.

Returns:

  • (self)

#set_pqg(p, q, g) ⇒ self

Sets p, q, g to the DSA instance.

Returns:

  • (self)

#syssign(string) ⇒ Object

:call-seq:

dsa.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::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



212
213
214
215
216
217
218
219
220
 
# File 'lib/openssl/pkey.rb', line 212

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) ⇒ Object

:call-seq:

dsa.sysverify(digest, sig) -> true | false

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.



235
236
237
238
239
 
# File 'lib/openssl/pkey.rb', line 235

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

#to_der ⇒ aString

Encodes this DSA to its DER encoding.

Returns:

  • (aString) 


244
245
246
247
248
249
250
251
252
253
254
 
# 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);
}