Class: OpenSSL::PKey::EC
| Relationships & Source Files | |
| Namespace Children | |
|
Classes:
| |
| Super Chains via Extension / Inclusion / Inheritance | |
|
Class Chain:
self,
PKey
|
|
|
Instance Chain:
self,
::OpenSSL::Marshal,
PKey
|
|
| Inherits: |
OpenSSL::PKey::PKey
|
| 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 1613INT2NUM(OPENSSL_EC_EXPLICIT_CURVE)
-
NAMED_CURVE =
# File 'ext/openssl/ossl_pkey_ec.c', line 1611INT2NUM(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
ECinstance with a new random private and public key. -
.new
constructor
Creates a new
ECobject 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
Groupthat the key is associated with. -
#group=(group)
rw
Sets the
Groupfor the key. -
#private? ⇒ Boolean
(also: #private_key?)
readonly
Returns whether this
ECinstance has a private key. -
#private_key ⇒ OpenSSL::BN
rw
See the
::OpenSSLdocumentation for EC_KEY_get0_private_key(). -
#private_key=(openssl_bn)
rw
See the
::OpenSSLdocumentation for EC_KEY_set_private_key(). -
#public? ⇒ Boolean
(also: #public_key?)
readonly
Returns whether this
ECinstance has a public key. -
#public_key ⇒ EC
rw
See the
::OpenSSLdocumentation for EC_KEY_get0_public_key(). -
#public_key=(ec_point)
rw
See the
::OpenSSLdocumentation 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, password]) ⇒ String
(also: #to_pem)
Serializes a private or public key to a 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
Serializes a private or public key to a DER-encoding.
-
#to_pem([cipher, password]) ⇒ String
Alias for #export.
::OpenSSL::Marshal - Included
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 |
| #derive | Derives a shared secret from pkey and peer_pkey. |
| #encrypt | Performs a public key encryption operation using |
| #initialize_copy, | |
| #inspect | Returns a string describing the |
| #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. |
| #raw_private_key | See the |
| #raw_public_key | See the |
| #sign | Hashes and signs the |
| #sign_raw | Signs |
| #to_text | Dumps key parameters, public key, and private key components contained in the key into a human-readable text. |
| #verify | Verifies the |
| #verify_raw | Verifies the |
| #verify_recover | Recovers the signed data from |
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.
# 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(eECError, "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
# File 'ext/openssl/ossl_pkey_ec.c', line 875
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
EC
.generate(string) ⇒ EC
Creates a new EC instance with a new random private and public key.
# 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.
# File 'ext/openssl/ossl_pkey_ec.c', line 227
static VALUE
ossl_ec_key_get_group(VALUE self)
{
OSSL_3_const 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.
# 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.
# File 'ext/openssl/ossl_pkey_ec.c', line 392
static VALUE ossl_ec_key_is_private(VALUE self)
{
OSSL_3_const 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()
# File 'ext/openssl/ossl_pkey_ec.c', line 273
static VALUE ossl_ec_key_get_private_key(VALUE self)
{
OSSL_3_const 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()
# 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.
# File 'ext/openssl/ossl_pkey_ec.c', line 376
static VALUE ossl_ec_key_is_public(VALUE self)
{
OSSL_3_const 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()
# File 'ext/openssl/ossl_pkey_ec.c', line 324
static VALUE ossl_ec_key_get_public_key(VALUE self)
{
OSSL_3_const 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()
# 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).
# File 'ext/openssl/ossl_pkey_ec.c', line 537
static VALUE ossl_ec_key_check_key(VALUE self)
{
#ifdef HAVE_EVP_PKEY_CHECK
EVP_PKEY *pkey;
EVP_PKEY_CTX *pctx;
const EC_KEY *ec;
GetPKey(self, pkey);
GetEC(self, ec);
pctx = EVP_PKEY_CTX_new(pkey, /* engine */NULL);
if (!pctx)
ossl_raise(eECError, "EVP_PKEY_CTX_new");
if (EC_KEY_get0_private_key(ec) != NULL) {
if (EVP_PKEY_check(pctx) != 1) {
EVP_PKEY_CTX_free(pctx);
ossl_raise(eECError, "EVP_PKEY_check");
}
}
else {
if (EVP_PKEY_public_check(pctx) != 1) {
EVP_PKEY_CTX_free(pctx);
ossl_raise(eECError, "EVP_PKEY_public_check");
}
}
EVP_PKEY_CTX_free(pctx);
#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.
# 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.
#dsa_verify_asn1(data, sig) ⇒ Boolean
Deprecated in version 3.0. Consider using PKey#sign_raw and PKey#verify_raw instead.
#export([cipher, password]) ⇒ String
#to_pem([cipher, password]) ⇒ String
Also known as: #to_pem
String
#to_pem([cipher, password]) ⇒ String
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 SEC 1/RFC 5915 ECPrivateKey.
A PEM-encoded key will look like:
-----BEGIN EC PRIVATE KEY----- [...] -----END EC PRIVATE KEY----- - When the key contains private components, and cipher and password are given
-
Serializes it into a SEC 1/RFC 5915 ECPrivateKey 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 EC PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0 [...] -----END EC 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 SEC 1/RFC 5915 ECPrivateKey format is required.
Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
# File 'ext/openssl/ossl_pkey_ec.c', line 459
static VALUE
ossl_ec_key_export(int argc, VALUE *argv, VALUE self)
{
OSSL_3_const 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>
# File 'ext/openssl/ossl_pkey_ec.c', line 514
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
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
Boolean (rw)
#private_key? ⇒ Boolean
Alias for #private?.
#public? ⇒ Boolean (rw)
#public_key? ⇒ Boolean
Boolean (rw)
#public_key? ⇒ Boolean
Alias for #public?.
#to_der ⇒ String
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 SEC 1/RFC 5915 ECPrivateKey format is required.
Consider using #public_to_der or #private_to_der instead.
# File 'ext/openssl/ossl_pkey_ec.c', line 487
static VALUE
ossl_ec_key_to_der(VALUE self)
{
OSSL_3_const 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, password]) ⇒ String
#to_pem([cipher, password]) ⇒ String
String
#to_pem([cipher, password]) ⇒ String
Alias for #export.