Class: OpenSSL::Cipher

Inherits:
Object
  • Object
show all
Defined in:
lib/openssl/cipher.rb,
ossl_cipher.c

Direct Known Subclasses

Cipher

Defined Under Namespace

Classes: Cipher, CipherError

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#new(string) ⇒ Object

The string must contain a valid cipher name like “AES-128-CBC” or “3DES”.

A list of cipher names is available by calling OpenSSL::Cipher.ciphers.



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'ossl_cipher.c', line 94

static VALUE
ossl_cipher_initialize(VALUE self, VALUE str)
{
    EVP_CIPHER_CTX *ctx;
    const EVP_CIPHER *cipher;
    char *name;

    name = StringValuePtr(str);
    GetCipher(self, ctx);
    if (!(cipher = EVP_get_cipherbyname(name))) {
  ossl_raise(rb_eRuntimeError, "unsupported cipher algorithm (%s)", name);
    }
    if (EVP_CipherInit_ex(ctx, cipher, NULL, NULL, NULL, -1) != 1)
  ossl_raise(eCipherError, NULL);

    return self;
}

Class Method Details

.ciphers ⇒ Object

Returns the names of all available ciphers in an array.



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'ossl_cipher.c', line 140

static VALUE
ossl_s_ciphers(VALUE self)
{
#ifdef HAVE_OBJ_NAME_DO_ALL_SORTED
    VALUE ary;

    ary = rb_ary_new();
    OBJ_NAME_do_all_sorted(OBJ_NAME_TYPE_CIPHER_METH,
                    (void(*)(const OBJ_NAME*,void*))add_cipher_name_to_ary,
                    (void*)ary);

    return ary;
#else
    rb_notimplement();
#endif
}

Instance Method Details

#<<(data) ⇒ String

Parameters

data is a nonempty string.

This method is deprecated and not available in 1.9.x or later.

Returns:

  • (String) 


307
308
309
310
311
312
313
314
315
 
# File 'ossl_cipher.c', line 307

static VALUE
ossl_cipher_update_deprecated(VALUE self, VALUE data)
{
    char *cname;

    cname = rb_class2name(rb_obj_class(self));
    rb_warning("%s#<< is deprecated; use %s#update instead", cname, cname);
    return rb_funcall(self, rb_intern("update"), 1, data);
}

#block_size ⇒ Integer

Returns:



530
 
# File 'ossl_cipher.c', line 530

static VALUE ossl_cipher_block_size() { }

#decrypt ⇒ self

Make sure to call .encrypt or .decrypt before using any of the following methods:

  • key=, iv=, random_key, random_iv, pkcs5_keyivgen

Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, 0).

Returns:

  • (self) 


243
244
245
246
247
 
# File 'ossl_cipher.c', line 243

static VALUE
ossl_cipher_decrypt(int argc, VALUE *argv, VALUE self)
{
    return ossl_cipher_init(argc, argv, self, 0);
}

#encrypt ⇒ self

Make sure to call .encrypt or .decrypt before using any of the following methods:

  • key=, iv=, random_key, random_iv, pkcs5_keyivgen

Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, 1).

Returns:

  • (self) 


228
229
230
231
232
 
# File 'ossl_cipher.c', line 228

static VALUE
ossl_cipher_encrypt(int argc, VALUE *argv, VALUE self)
{
    return ossl_cipher_init(argc, argv, self, 1);
}

#final ⇒ aString

Returns the remaining data held in the cipher object. Further calls to update() or final() will return garbage.

See EVP_CipherFinal_ex for further information.

Returns:

  • (aString) 


366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
 
# File 'ossl_cipher.c', line 366

static VALUE 
ossl_cipher_final(VALUE self)
{
    EVP_CIPHER_CTX *ctx;
    int out_len;
    VALUE str;

    GetCipher(self, ctx);
    str = rb_str_new(0, EVP_CIPHER_CTX_block_size(ctx));
    if (!EVP_CipherFinal_ex(ctx, RSTRING_PTR(str), &out_len))
  ossl_raise(eCipherError, NULL);
    assert(out_len <= RSTRING_LEN(str));
    rb_str_set_len(str, out_len);

    return str;
}

#iv=(string) ⇒ String

Sets the cipher iv.

Only call this method after calling cipher.encrypt or cipher.decrypt.

Returns:

  • (String) 


432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
 
# File 'ossl_cipher.c', line 432

static VALUE
ossl_cipher_set_iv(VALUE self, VALUE iv)
{
    EVP_CIPHER_CTX *ctx;

    StringValue(iv);
    GetCipher(self, ctx);

    if (RSTRING_LEN(iv) < EVP_CIPHER_CTX_iv_length(ctx))
        ossl_raise(eCipherError, "iv length too short");

    if (EVP_CipherInit_ex(ctx, NULL, NULL, NULL, RSTRING_PTR(iv), -1) != 1)
  ossl_raise(eCipherError, NULL);

    return iv;
}

#iv_length ⇒ Integer

Returns:



524
 
# File 'ossl_cipher.c', line 524

static VALUE ossl_cipher_iv_length() { }

#key=(string) ⇒ String

Sets the cipher key.

Only call this method after calling cipher.encrypt or cipher.decrypt.

Returns:

  • (String) 


407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
 
# File 'ossl_cipher.c', line 407

static VALUE
ossl_cipher_set_key(VALUE self, VALUE key)
{
    EVP_CIPHER_CTX *ctx;

    StringValue(key);
    GetCipher(self, ctx);

    if (RSTRING_LEN(key) < EVP_CIPHER_CTX_key_length(ctx))
        ossl_raise(eCipherError, "key length too short");

    if (EVP_CipherInit_ex(ctx, NULL, NULL, RSTRING_PTR(key), NULL, -1) != 1)
        ossl_raise(eCipherError, NULL);

    return key;
}

#key_len ⇒ Object

#key_length=(integer) ⇒ Integer

Sets the key length of the cipher. If the cipher is a fixed length cipher then attempting to set the key length to any value other than the fixed value is an error.

Under normal circumstances you do not need to call this method (and probably shouldn’t).

See EVP_CIPHER_CTX_set_key_length for further information.

Returns:



461
462
463
464
465
466
467
468
469
470
471
472
 
# File 'ossl_cipher.c', line 461

static VALUE
ossl_cipher_set_key_length(VALUE self, VALUE key_length)
{
    int len = NUM2INT(key_length);
    EVP_CIPHER_CTX *ctx;
 
    GetCipher(self, ctx);
    if (EVP_CIPHER_CTX_set_key_length(ctx, len) != 1)
        ossl_raise(eCipherError, NULL);

    return key_length;
}

#name ⇒ String

Returns the name of the cipher which may differ slightly from the original name provided.

Returns:

  • (String) 


389
390
391
392
393
394
395
396
397
 
# File 'ossl_cipher.c', line 389

static VALUE
ossl_cipher_name(VALUE self)
{
    EVP_CIPHER_CTX *ctx;

    GetCipher(self, ctx);

    return rb_str_new2(EVP_CIPHER_name(EVP_CIPHER_CTX_cipher(ctx)));
}

#padding=(integer) ⇒ Integer

Enables or disables padding. By default encryption operations are padded using standard block padding and the padding is checked and removed when decrypting. If the pad parameter is zero then no padding is performed, the total amount of data encrypted or decrypted must then be a multiple of the block size or an error will occur.

See EVP_CIPHER_CTX_set_padding for further information.

Returns:



484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
 
# File 'ossl_cipher.c', line 484

static VALUE
ossl_cipher_set_padding(VALUE self, VALUE padding)
{
#if defined(HAVE_EVP_CIPHER_CTX_SET_PADDING)
    EVP_CIPHER_CTX *ctx;
    int pad = NUM2INT(padding);

    GetCipher(self, ctx);
    if (EVP_CIPHER_CTX_set_padding(ctx, pad) != 1)
  ossl_raise(eCipherError, NULL);
#else
    rb_notimplement();
#endif
    return padding;
}

#pkcs5_keyivgen(pass[, salt [, iterations [, digest]]]) ⇒ nil

Generates and sets the key/iv based on a password.

WARNING: This method is only PKCS5 v1.5 compliant when using RC2, RC4-40, or DES with MD5 or SHA1. Using anything else (like AES) will generate the key/iv using an OpenSSL specific method. Use a PKCS5 v2 key generation method instead.

Parameters

salt must be an 8 byte string if provided. iterations is a integer with a default of 2048. digest is a Digest object that defaults to ‘MD5’

A minimum of 1000 iterations is recommended.

Returns:

  • (nil) 


267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'ossl_cipher.c', line 267

static VALUE
ossl_cipher_pkcs5_keyivgen(int argc, VALUE *argv, VALUE self)
{
    EVP_CIPHER_CTX *ctx;
    const EVP_MD *digest;
    VALUE vpass, vsalt, viter, vdigest;
    unsigned char key[EVP_MAX_KEY_LENGTH], iv[EVP_MAX_IV_LENGTH], *salt = NULL;
    int iter;

    rb_scan_args(argc, argv, "13", &vpass, &vsalt, &viter, &vdigest);
    StringValue(vpass);
    if(!NIL_P(vsalt)){
  StringValue(vsalt);
  if(RSTRING_LEN(vsalt) != PKCS5_SALT_LEN)
      rb_raise(eCipherError, "salt must be an 8-octet string");
  salt = RSTRING_PTR(vsalt);
    }
    iter = NIL_P(viter) ? 2048 : NUM2INT(viter);
    digest = NIL_P(vdigest) ? EVP_md5() : GetDigestPtr(vdigest);
    GetCipher(self, ctx);
    EVP_BytesToKey(EVP_CIPHER_CTX_cipher(ctx), digest, salt,
       RSTRING_PTR(vpass), RSTRING_LEN(vpass), iter, key, iv); 
    if (EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, -1) != 1)
  ossl_raise(eCipherError, NULL);
    OPENSSL_cleanse(key, sizeof key);
    OPENSSL_cleanse(iv, sizeof iv);

    return Qnil;
}

#random_iv ⇒ Object

Generate, set, and return a random iv. You must call cipher.encrypt or cipher.decrypt before calling this method.



54
55
56
57
58
 
# File 'lib/openssl/cipher.rb', line 54

def random_iv
  str = OpenSSL::Random.random_bytes(self.iv_len)
  self.iv = str
  return str
end

#random_key ⇒ Object

Generate, set, and return a random key. You must call cipher.encrypt or cipher.decrypt before calling this method.



46
47
48
49
50
 
# File 'lib/openssl/cipher.rb', line 46

def random_key
  str = OpenSSL::Random.random_bytes(self.key_len)
  self.key = str
  return str
end

#reset ⇒ self

Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, -1).

Returns:

  • (self) 


163
164
165
166
167
168
169
170
171
172
173
 
# File 'ossl_cipher.c', line 163

static VALUE
ossl_cipher_reset(VALUE self)
{
    EVP_CIPHER_CTX *ctx;

    GetCipher(self, ctx);
    if (EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, -1) != 1)
  ossl_raise(eCipherError, NULL);
    
    return self;
}

#update(data[, buffer]) ⇒ String

Parameters

data is a nonempty string. buffer is an optional string to store the result.

Returns:

  • (String) 


326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
 
# File 'ossl_cipher.c', line 326

static VALUE 
ossl_cipher_update(int argc, VALUE *argv, VALUE self)
{
    EVP_CIPHER_CTX *ctx;
    char *in;
    int in_len, out_len;
    VALUE data, str;

    rb_scan_args(argc, argv, "11", &data, &str);

    StringValue(data);
    in = RSTRING_PTR(data);
    if ((in_len = RSTRING_LEN(data)) == 0)
        rb_raise(rb_eArgError, "data must not be empty");
    GetCipher(self, ctx);
    out_len = in_len+EVP_CIPHER_CTX_block_size(ctx);

    if (NIL_P(str)) {
        str = rb_str_new(0, out_len);
    } else {
        StringValue(str);
        rb_str_resize(str, out_len);
    }

    if (!EVP_CipherUpdate(ctx, RSTRING_PTR(str), &out_len, in, in_len))
  ossl_raise(eCipherError, NULL);
    assert(out_len < RSTRING_LEN(str));
    rb_str_set_len(str, out_len);

    return str;
}