Class: OpenSSL::PKey::EC

Relationships & Source Files
Namespace Children
Classes: `Group`, `Point`
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::EC
Defined in:	ext/openssl/ossl_pkey_ec.c, ext/openssl/lib/openssl/pkey.rb

Overview

EC provides access to Elliptic Curve Digital Signature Algorithm (ECDSA) and Elliptic Curve Diffie-Hellman (ECDH).

Key exchange

ec1 = OpenSSL::PKey::EC.generate("prime256v1")
ec2 = OpenSSL::PKey::EC.generate("prime256v1")
# ec1 and ec2 have own private key respectively
shared_key1 = ec1.dh_compute_key(ec2.public_key)
shared_key2 = ec2.dh_compute_key(ec1.public_key)

p shared_key1 == shared_key2 #=> true

Constant Summary

EXPLICIT_CURVE =
# File 'ext/openssl/ossl_pkey_ec.c', line 1541
```
INT2NUM(OPENSSL_EC_EXPLICIT_CURVE)
```
NAMED_CURVE =
# File 'ext/openssl/ossl_pkey_ec.c', line 1539
```
INT2NUM(OPENSSL_EC_NAMED_CURVE)
```

Class Method Summary

.builtin_curves ⇒ Array, comment

Obtains a list of all predefined curves by the ::OpenSSL.
.generate(ec_group) ⇒ EC

Creates a new EC instance with a new random private and public key.
.new constructor

Creates a new EC object from given arguments.

`PKey` - Inherited

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

Instance Attribute Summary

#group ⇒ group rw

Returns the Group that the key is associated with.
#group=(group) rw

Sets the Group for the key.
#private? ⇒ Boolean (also: #private_key?) readonly

Returns whether this EC instance has a private key.
#private_key ⇒ OpenSSL::BN rw

See the ::OpenSSL documentation for EC_KEY_get0_private_key().
#private_key=(openssl_bn) rw

See the ::OpenSSL documentation for EC_KEY_set_private_key().
#public? ⇒ Boolean (also: #public_key?) readonly

Returns whether this EC instance has a public key.
#public_key ⇒ EC rw

See the ::OpenSSL documentation for EC_KEY_get0_public_key().
#public_key=(ec_point) rw

See the ::OpenSSL documentation for EC_KEY_set_public_key().

Instance Method Summary

#check_key ⇒ true

Raises an exception if the key is invalid.
#dh_compute_key(pubkey) ⇒ String

Derives a shared secret by ECDH.
#dsa_sign_asn1(data) ⇒ String

Deprecated in version 3.0.
#dsa_verify_asn1(data, sig) ⇒ Boolean

Deprecated in version 3.0.
#export([cipher, pass_phrase]) ⇒ String (also: #to_pem)

Outputs the EC key in PEM encoding.
#generate_key ⇒ self (also: #generate_key!)

Generates a new random private and public key.
#generate_key! ⇒ self

Alias for #generate_key.
#initialize_copy(other)
#private_key? ⇒ Boolean rw

Alias for #private?.
#public_key? ⇒ Boolean rw

Alias for #public?.
#to_der ⇒ String

See the ::OpenSSL documentation for i2d_ECPrivateKey_bio().
#to_pem([cipher, pass_phrase]) ⇒ String

Alias for #export.

`::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 .new(ec_key) .new(ec_group) .new("secp112r1") .new(pem_string [, pwd]) .new(der_string)

Creates a new EC object from given arguments.

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 139


static VALUE ossl_ec_key_initialize(int argc, VALUE *argv, VALUE self)
{
    EVP_PKEY *pkey;
    EC_KEY *ec;
    BIO *in;
    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");

    rb_scan_args(argc, argv, "02", &arg, &pass);
    if (NIL_P(arg)) {
        if (!(ec = EC_KEY_new()))
            ossl_raise(eECError, "EC_KEY_new");
        goto legacy;
    }
    else if (rb_obj_is_kind_of(arg, cEC_GROUP)) {
        ec = ec_key_new_from_group(arg);
        goto legacy;
    }

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

    pkey = ossl_pkey_read_generic(in, pass);
    BIO_free(in);
    if (!pkey) {
        ossl_clear_error();
        ec = ec_key_new_from_group(arg);
        goto legacy;
    }

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

  legacy:
    pkey = EVP_PKEY_new();
    if (!pkey || EVP_PKEY_assign_EC_KEY(pkey, ec) != 1) {
        EVP_PKEY_free(pkey);
        EC_KEY_free(ec);
        ossl_raise(eECError, "EVP_PKEY_assign_EC_KEY");
    }
    RTYPEDDATA_DATA(self) = pkey;
    return self;
}

Class Method Details

.builtin_curves ⇒ `Array`, `comment`

Obtains a list of all predefined curves by the ::OpenSSL. Curve names are returned as sn.

See the ::OpenSSL documentation for EC_get_builtin_curves().

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 806


static VALUE ossl_s_builtin_curves(VALUE self)
{
    EC_builtin_curve *curves = NULL;
    int n;
    int crv_len = rb_long2int(EC_get_builtin_curves(NULL, 0));
    VALUE ary, ret;

    curves = ALLOCA_N(EC_builtin_curve, crv_len);
    if (curves == NULL)
        return Qnil;
    if (!EC_get_builtin_curves(curves, crv_len))
        ossl_raise(rb_eRuntimeError, "EC_get_builtin_curves");

    ret = rb_ary_new2(crv_len);

    for (n = 0; n < crv_len; n++) {
        const char *sname = OBJ_nid2sn(curves[n].nid);
        const char *comment = curves[n].comment;

        ary = rb_ary_new2(2);
        rb_ary_push(ary, rb_str_new2(sname));
        rb_ary_push(ary, comment ? rb_str_new2(comment) : Qnil);
        rb_ary_push(ret, ary);
    }

    return ret;
}

.generate(ec_group) ⇒ `EC` .generate(string) ⇒ `EC`

Creates a new EC instance with a new random private and public key.

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 104


static VALUE
ossl_ec_key_s_generate(VALUE klass, VALUE arg)
{
    EVP_PKEY *pkey;
    EC_KEY *ec;
    VALUE obj;

    obj = rb_obj_alloc(klass);

    ec = ec_key_new_from_group(arg);
    pkey = EVP_PKEY_new();
    if (!pkey || EVP_PKEY_assign_EC_KEY(pkey, ec) != 1) {
        EVP_PKEY_free(pkey);
        EC_KEY_free(ec);
        ossl_raise(eECError, "EVP_PKEY_assign_EC_KEY");
    }
    RTYPEDDATA_DATA(obj) = pkey;

    if (!EC_KEY_generate_key(ec))
	ossl_raise(eECError, "EC_KEY_generate_key");

    return obj;
}

Instance Attribute Details

#group ⇒ group (rw)

Returns the EC::Group that the key is associated with. Modifying the returned group does not affect key.

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 227


static VALUE
ossl_ec_key_get_group(VALUE self)
{
    EC_KEY *ec;
    const EC_GROUP *group;

    GetEC(self, ec);
    group = EC_KEY_get0_group(ec);
    if (!group)
	return Qnil;

    return ec_group_new(group);
}

#group=(group) (rw)

Sets the EC::Group for the key. The group structure is internally copied so modification to group after assigning to a key has no effect on the key.

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 248


static VALUE
ossl_ec_key_set_group(VALUE self, VALUE group_v)
{
#if OSSL_OPENSSL_PREREQ(3, 0, 0)
    rb_raise(ePKeyError, "pkeys are immutable on OpenSSL 3.0");
#else
    EC_KEY *ec;
    EC_GROUP *group;

    GetEC(self, ec);
    GetECGroup(group_v, group);

    if (EC_KEY_set_group(ec, group) != 1)
        ossl_raise(eECError, "EC_KEY_set_group");

    return group_v;
#endif
}

#private? ⇒ `Boolean` (rw) Also known as: #private_key?

Returns whether this EC instance has a private key. The private key (BN) can be retrieved with #private_key.

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 392


static VALUE ossl_ec_key_is_private(VALUE self)
{
    EC_KEY *ec;

    GetEC(self, ec);

    return EC_KEY_get0_private_key(ec) ? Qtrue : Qfalse;
}

#private_key ⇒ OpenSSL::BN (rw)

See the ::OpenSSL documentation for EC_KEY_get0_private_key()

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 273


static VALUE ossl_ec_key_get_private_key(VALUE self)
{
    EC_KEY *ec;
    const BIGNUM *bn;

    GetEC(self, ec);
    if ((bn = EC_KEY_get0_private_key(ec)) == NULL)
        return Qnil;

    return ossl_bn_new(bn);
}

#private_key=(openssl_bn) (rw)

See the ::OpenSSL documentation for EC_KEY_set_private_key()

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 291


static VALUE ossl_ec_key_set_private_key(VALUE self, VALUE private_key)
{
#if OSSL_OPENSSL_PREREQ(3, 0, 0)
    rb_raise(ePKeyError, "pkeys are immutable on OpenSSL 3.0");
#else
    EC_KEY *ec;
    BIGNUM *bn = NULL;

    GetEC(self, ec);
    if (!NIL_P(private_key))
        bn = GetBNPtr(private_key);

    switch (EC_KEY_set_private_key(ec, bn)) {
    case 1:
        break;
    case 0:
        if (bn == NULL)
            break;
	/* fallthrough */
    default:
        ossl_raise(eECError, "EC_KEY_set_private_key");
    }

    return private_key;
#endif
}

#public? ⇒ `Boolean` (rw) Also known as: #public_key?

Returns whether this EC instance has a public key. The public key (EC::Point) can be retrieved with #public_key.

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 376


static VALUE ossl_ec_key_is_public(VALUE self)
{
    EC_KEY *ec;

    GetEC(self, ec);

    return EC_KEY_get0_public_key(ec) ? Qtrue : Qfalse;
}

#public_key ⇒ `EC` (rw)

See the ::OpenSSL documentation for EC_KEY_get0_public_key()

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 324


static VALUE ossl_ec_key_get_public_key(VALUE self)
{
    EC_KEY *ec;
    const EC_POINT *point;

    GetEC(self, ec);
    if ((point = EC_KEY_get0_public_key(ec)) == NULL)
        return Qnil;

    return ec_point_new(point, EC_KEY_get0_group(ec));
}

#public_key=(ec_point) (rw)

See the ::OpenSSL documentation for EC_KEY_set_public_key()

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 342


static VALUE ossl_ec_key_set_public_key(VALUE self, VALUE public_key)
{
#if OSSL_OPENSSL_PREREQ(3, 0, 0)
    rb_raise(ePKeyError, "pkeys are immutable on OpenSSL 3.0");
#else
    EC_KEY *ec;
    EC_POINT *point = NULL;

    GetEC(self, ec);
    if (!NIL_P(public_key))
        GetECPoint(public_key, point);

    switch (EC_KEY_set_public_key(ec, point)) {
    case 1:
        break;
    case 0:
        if (point == NULL)
            break;
	/* fallthrough */
    default:
        ossl_raise(eECError, "EC_KEY_set_public_key");
    }

    return public_key;
#endif
}

Instance Method Details

#check_key ⇒ `true`

Raises an exception if the key is invalid.

See also the man page EVP_PKEY_public_check(3).

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 481


static VALUE ossl_ec_key_check_key(VALUE self)
{
#ifdef HAVE_EVP_PKEY_CHECK
    EVP_PKEY *pkey;
    EVP_PKEY_CTX *pctx;
    int ret;

    GetPKey(self, pkey);
    pctx = EVP_PKEY_CTX_new(pkey, /* engine */NULL);
    if (!pctx)
        ossl_raise(eDHError, "EVP_PKEY_CTX_new");
    ret = EVP_PKEY_public_check(pctx);
    EVP_PKEY_CTX_free(pctx);
    if (ret != 1)
        ossl_raise(eECError, "EVP_PKEY_public_check");
#else
    EC_KEY *ec;

    GetEC(self, ec);
    if (EC_KEY_check_key(ec) != 1)
	ossl_raise(eECError, "EC_KEY_check_key");
#endif

    return Qtrue;
}

#dh_compute_key(pubkey) ⇒ `String`

Derives a shared secret by ECDH. pubkey must be an instance of EC::Point and must belong to the same group.

This method is provided for backwards compatibility, and calls #derive internally.

[ GitHub ]

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


def dh_compute_key(pubkey)
  obj = OpenSSL::ASN1.Sequence([
    OpenSSL::ASN1.Sequence([
      OpenSSL::ASN1.ObjectId("id-ecPublicKey"),
      group.to_der,
    ]),
    OpenSSL::ASN1.BitString(pubkey.to_octet_string(:uncompressed)),
  ])
  derive(OpenSSL::PKey.read(obj.to_der))
end

#dsa_sign_asn1(data) ⇒ `String`

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

[ GitHub ]

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


def dsa_sign_asn1(data)
  sign_raw(nil, data)
rescue OpenSSL::PKey::PKeyError
  raise OpenSSL::PKey::ECError, $!.message
end

#dsa_verify_asn1(data, sig) ⇒ `Boolean`

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

[ GitHub ]

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


def dsa_verify_asn1(data, sig)
  verify_raw(nil, sig, data)
rescue OpenSSL::PKey::PKeyError
  raise OpenSSL::PKey::ECError, $!.message
end

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

Outputs the EC key in PEM encoding. If cipher and pass_phrase are given they will be used to encrypt the key. cipher must be an ::OpenSSL::Cipher instance. Note that encryption will only be effective for a private key, public keys will always be encoded in plain text.

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 411


static VALUE
ossl_ec_key_export(int argc, VALUE *argv, VALUE self)
{
    EC_KEY *ec;

    GetEC(self, ec);
    if (EC_KEY_get0_public_key(ec) == NULL)
        ossl_raise(eECError, "can't export - no public key set");
    if (EC_KEY_get0_private_key(ec))
        return ossl_pkey_export_traditional(argc, argv, self, 0);
    else
        return ossl_pkey_export_spki(self, 0);
}

#generate_key ⇒ `self` Also known as: #generate_key!

Generates a new random private and public key.

See also the ::OpenSSL documentation for EC_KEY_generate_key()

Example

ec = OpenSSL::PKey::EC.new("prime256v1")
p ec.private_key # => nil
ec.generate_key!
p ec.private_key # => #<OpenSSL::BN XXXXXX>

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 458


static VALUE ossl_ec_key_generate_key(VALUE self)
{
#if OSSL_OPENSSL_PREREQ(3, 0, 0)
    rb_raise(ePKeyError, "pkeys are immutable on OpenSSL 3.0");
#else
    EC_KEY *ec;

    GetEC(self, ec);
    if (EC_KEY_generate_key(ec) != 1)
	ossl_raise(eECError, "EC_KEY_generate_key");

    return self;
#endif
}

#generate_key ⇒ `self` #generate_key! ⇒ `self`

Alias for #generate_key.

#initialize_copy(other)

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 194


static VALUE
ossl_ec_key_initialize_copy(VALUE self, VALUE other)
{
    EVP_PKEY *pkey;
    EC_KEY *ec, *ec_new;

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

    ec_new = EC_KEY_dup(ec);
    if (!ec_new)
	ossl_raise(eECError, "EC_KEY_dup");

    pkey = EVP_PKEY_new();
    if (!pkey || EVP_PKEY_assign_EC_KEY(pkey, ec_new) != 1) {
        EC_KEY_free(ec_new);
        ossl_raise(eECError, "EVP_PKEY_assign_EC_KEY");
    }
    RTYPEDDATA_DATA(self) = pkey;

    return self;
}

#private? ⇒ `Boolean` (rw) #private_key? ⇒ `Boolean`

Alias for #private?.

#public? ⇒ `Boolean` (rw) #public_key? ⇒ `Boolean`

Alias for #public?.

#to_der ⇒ `String`

See the ::OpenSSL documentation for i2d_ECPrivateKey_bio()

[ GitHub ]

# File 'ext/openssl/ossl_pkey_ec.c', line 431


static VALUE
ossl_ec_key_to_der(VALUE self)
{
    EC_KEY *ec;

    GetEC(self, ec);
    if (EC_KEY_get0_public_key(ec) == NULL)
        ossl_raise(eECError, "can't export - no public key set");
    if (EC_KEY_get0_private_key(ec))
        return ossl_pkey_export_traditional(0, NULL, self, 1);
    else
        return ossl_pkey_export_spki(self, 1);
}

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

Alias for #export.

Class: OpenSSL::PKey::EC

Overview

Key exchange

Constant Summary

Class Method Summary

PKey - Inherited

Instance Attribute Summary

Instance Method Summary

::OpenSSL::Marshal - Included

PKey - Inherited

Constructor Details

.new .new(ec_key) .new(ec_group) .new("secp112r1") .new(pem_string [, pwd]) .new(der_string)

Class Method Details

.builtin_curves ⇒ Array, comment

.generate(ec_group) ⇒ EC .generate(string) ⇒ EC

Instance Attribute Details

#group ⇒ group (rw)

#group=(group) (rw)

#private? ⇒ Boolean (rw) Also known as: #private_key?

#private_key ⇒ OpenSSL::BN (rw)

#private_key=(openssl_bn) (rw)

#public? ⇒ Boolean (rw) Also known as: #public_key?

#public_key ⇒ EC (rw)

#public_key=(ec_point) (rw)

Instance Method Details

#check_key ⇒ true

#dh_compute_key(pubkey) ⇒ String

#dsa_sign_asn1(data) ⇒ String

#dsa_verify_asn1(data, sig) ⇒ Boolean

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

#generate_key ⇒ self Also known as: #generate_key!

Example

#generate_key ⇒ self #generate_key! ⇒ self

#initialize_copy(other)

#private? ⇒ Boolean (rw) #private_key? ⇒ Boolean

#public? ⇒ Boolean (rw) #public_key? ⇒ Boolean

#to_der ⇒ String

#export([cipher, pass_phrase]) ⇒ String #to_pem([cipher, pass_phrase]) ⇒ String

`PKey` - Inherited

`::OpenSSL::Marshal` - Included

`PKey` - Inherited

.builtin_curves ⇒ `Array`, `comment`

.generate(ec_group) ⇒ `EC` .generate(string) ⇒ `EC`

#private? ⇒ `Boolean` (rw) Also known as: #private_key?

#public? ⇒ `Boolean` (rw) Also known as: #public_key?

#public_key ⇒ `EC` (rw)

#check_key ⇒ `true`

#dh_compute_key(pubkey) ⇒ `String`

#dsa_sign_asn1(data) ⇒ `String`

#dsa_verify_asn1(data, sig) ⇒ `Boolean`

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

#generate_key ⇒ `self` Also known as: #generate_key!

#generate_key ⇒ `self` #generate_key! ⇒ `self`

#private? ⇒ `Boolean` (rw) #private_key? ⇒ `Boolean`

#public? ⇒ `Boolean` (rw) #public_key? ⇒ `Boolean`

#to_der ⇒ `String`

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