Module: PQCrypto

Defined in:
lib/pq_crypto.rb,
lib/pq_crypto/kem.rb,
lib/pq_crypto/errors.rb,
lib/pq_crypto/version.rb,
lib/pq_crypto/signature.rb,
lib/pq_crypto/hybrid_kem.rb,
lib/pq_crypto/serialization.rb,
ext/pqcrypto/pqcrypto_ruby_secure.c

Defined Under Namespace

Modules: HybridKEM, KEM, Serialization, Signature, Testing Classes: Error, InvalidCiphertextError, InvalidKeyError, SerializationError, UnsupportedAlgorithmError, VerificationError

Constant Summary collapse

SUITES = 
{
  kem: [:ml_kem_768].freeze,
  hybrid_kem: [:ml_kem_768_x25519_hkdf_sha256].freeze,
  signature: [:ml_dsa_65].freeze,
}.freeze
NATIVE_EXTENSION_LOADED = 
true
VERSION = 
"0.2.0"
ML_KEM_PUBLIC_KEY_BYTES = 
INT2NUM(PQ_MLKEM_PUBLICKEYBYTES)
ML_KEM_SECRET_KEY_BYTES = 
INT2NUM(PQ_MLKEM_SECRETKEYBYTES)
ML_KEM_CIPHERTEXT_BYTES = 
INT2NUM(PQ_MLKEM_CIPHERTEXTBYTES)
ML_KEM_SHARED_SECRET_BYTES = 
INT2NUM(PQ_MLKEM_SHAREDSECRETBYTES)
HYBRID_KEM_PUBLIC_KEY_BYTES = 
INT2NUM(PQ_HYBRID_PUBLICKEYBYTES)
HYBRID_KEM_SECRET_KEY_BYTES = 
INT2NUM(PQ_HYBRID_SECRETKEYBYTES)
HYBRID_KEM_CIPHERTEXT_BYTES = 
INT2NUM(PQ_HYBRID_CIPHERTEXTBYTES)
HYBRID_KEM_SHARED_SECRET_BYTES = 
INT2NUM(PQ_HYBRID_SHAREDSECRETBYTES)
SIGN_PUBLIC_KEY_BYTES = 
INT2NUM(PQ_MLDSA_PUBLICKEYBYTES)
SIGN_SECRET_KEY_BYTES = 
INT2NUM(PQ_MLDSA_SECRETKEYBYTES)
SIGN_BYTES = 
INT2NUM(PQ_MLDSA_BYTES)

Class Method Summary collapse

Class Method Details

.__test_ml_kem_encapsulate_from_seed(public_key, seed) ⇒ Object 



544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 544

static VALUE pqcrypto__test_ml_kem_encapsulate_from_seed(VALUE self, VALUE public_key, VALUE seed) {
    (void)self;
    pq_validate_bytes_argument(public_key, PQ_MLKEM_PUBLICKEYBYTES, "public key");
    StringValue(seed);

    if ((size_t)RSTRING_LEN(seed) != 32) {
        rb_raise(rb_eArgError, "Deterministic test seed must be 32 bytes");
    }

    kem_encapsulate_call_t call = {0};
    size_t public_key_len = 0;
    size_t seed_len = 0;
    call.public_key = pq_copy_ruby_string(public_key, &public_key_len);
    call.ciphertext = pq_alloc_buffer(PQ_MLKEM_CIPHERTEXTBYTES);
    call.shared_secret = pq_alloc_buffer(PQ_MLKEM_SHAREDSECRETBYTES);
    call.seed = pq_copy_ruby_string(seed, &seed_len);
    call.seed_len = seed_len;

    rb_thread_call_without_gvl(pq_testing_ml_kem_encapsulate_nogvl, &call, NULL, NULL);
    pq_wipe_and_free((uint8_t *)call.public_key, public_key_len);
    pq_wipe_and_free((uint8_t *)call.seed, call.seed_len);

    if (call.result != PQ_SUCCESS) {
        pq_wipe_and_free(call.shared_secret, PQ_MLKEM_SHAREDSECRETBYTES);
        free(call.ciphertext);
        pq_raise_general_error(call.result);
    }

    VALUE result = rb_ary_new2(2);
    rb_ary_push(result, pq_string_from_buffer(call.ciphertext, PQ_MLKEM_CIPHERTEXTBYTES));
    rb_ary_push(result, pq_string_from_buffer(call.shared_secret, PQ_MLKEM_SHAREDSECRETBYTES));

    free(call.ciphertext);
    pq_wipe_and_free(call.shared_secret, PQ_MLKEM_SHAREDSECRETBYTES);
    return result;
}

.__test_ml_kem_keypair_from_seed(seed) ⇒ Object 



511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 511

static VALUE pqcrypto__test_ml_kem_keypair_from_seed(VALUE self, VALUE seed) {
    (void)self;
    StringValue(seed);

    if ((size_t)RSTRING_LEN(seed) != 32 && (size_t)RSTRING_LEN(seed) != 64) {
        rb_raise(rb_eArgError, "Deterministic ML-KEM test seed must be 32 or 64 bytes");
    }

    kem_keypair_call_t call = {0};
    size_t seed_len = 0;
    call.public_key = pq_alloc_buffer(PQ_MLKEM_PUBLICKEYBYTES);
    call.secret_key = pq_alloc_buffer(PQ_MLKEM_SECRETKEYBYTES);
    call.seed = pq_copy_ruby_string(seed, &seed_len);
    call.seed_len = seed_len;

    rb_thread_call_without_gvl(pq_testing_ml_kem_keypair_nogvl, &call, NULL, NULL);
    pq_wipe_and_free((uint8_t *)call.seed, call.seed_len);

    if (call.result != PQ_SUCCESS) {
        pq_wipe_and_free(call.secret_key, PQ_MLKEM_SECRETKEYBYTES);
        free(call.public_key);
        pq_raise_general_error(call.result);
    }

    VALUE result = rb_ary_new2(2);
    rb_ary_push(result, pq_string_from_buffer(call.public_key, PQ_MLKEM_PUBLICKEYBYTES));
    rb_ary_push(result, pq_string_from_buffer(call.secret_key, PQ_MLKEM_SECRETKEYBYTES));

    free(call.public_key);
    pq_wipe_and_free(call.secret_key, PQ_MLKEM_SECRETKEYBYTES);
    return result;
}

.__test_sign_from_seed(message, secret_key, seed) ⇒ Object 



614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 614

static VALUE pqcrypto__test_sign_from_seed(VALUE self, VALUE message, VALUE secret_key,
                                           VALUE seed) {
    (void)self;
    pq_validate_bytes_argument(secret_key, PQ_MLDSA_SECRETKEYBYTES, "secret key");
    StringValue(seed);

    if ((size_t)RSTRING_LEN(seed) != 32) {
        rb_raise(rb_eArgError, "Deterministic test seed must be 32 bytes");
    }

    sign_call_t call = {0};
    size_t secret_key_len = 0;
    size_t seed_len = 0;
    call.secret_key = pq_copy_ruby_string(secret_key, &secret_key_len);
    call.signature_len = PQ_MLDSA_BYTES;
    call.signature = pq_alloc_buffer(PQ_MLDSA_BYTES);
    call.message = pq_copy_ruby_string(message, &call.message_len);
    call.seed = pq_copy_ruby_string(seed, &seed_len);
    call.seed_len = seed_len;

    rb_thread_call_without_gvl(pq_testing_sign_nogvl, &call, NULL, NULL);

    pq_wipe_and_free(call.message, call.message_len);
    pq_wipe_and_free((uint8_t *)call.secret_key, secret_key_len);
    pq_wipe_and_free((uint8_t *)call.seed, call.seed_len);

    if (call.result != PQ_SUCCESS) {
        pq_wipe_and_free(call.signature, PQ_MLDSA_BYTES);
        pq_raise_general_error(call.result);
    }

    VALUE result = pq_string_from_buffer(call.signature, call.signature_len);
    pq_wipe_and_free(call.signature, PQ_MLDSA_BYTES);
    return result;
}

.__test_sign_keypair_from_seed(seed) ⇒ Object 



581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 581

static VALUE pqcrypto__test_sign_keypair_from_seed(VALUE self, VALUE seed) {
    (void)self;
    StringValue(seed);

    if ((size_t)RSTRING_LEN(seed) != 32) {
        rb_raise(rb_eArgError, "Deterministic test seed must be 32 bytes");
    }

    sign_keypair_call_t call = {0};
    size_t seed_len = 0;
    call.public_key = pq_alloc_buffer(PQ_MLDSA_PUBLICKEYBYTES);
    call.secret_key = pq_alloc_buffer(PQ_MLDSA_SECRETKEYBYTES);
    call.seed = pq_copy_ruby_string(seed, &seed_len);
    call.seed_len = seed_len;

    rb_thread_call_without_gvl(pq_testing_sign_keypair_nogvl, &call, NULL, NULL);
    pq_wipe_and_free((uint8_t *)call.seed, call.seed_len);

    if (call.result != PQ_SUCCESS) {
        pq_wipe_and_free(call.secret_key, PQ_MLDSA_SECRETKEYBYTES);
        free(call.public_key);
        pq_raise_general_error(call.result);
    }

    VALUE result = rb_ary_new2(2);
    rb_ary_push(result, pq_string_from_buffer(call.public_key, PQ_MLDSA_PUBLICKEYBYTES));
    rb_ary_push(result, pq_string_from_buffer(call.secret_key, PQ_MLDSA_SECRETKEYBYTES));

    free(call.public_key);
    pq_wipe_and_free(call.secret_key, PQ_MLDSA_SECRETKEYBYTES);
    return result;
}

.backend ⇒ Object 



120
121
122
 
# File 'lib/pq_crypto.rb', line 120

def backend
  :native_pqclean
end

.hybrid_kem_decapsulate(ciphertext, secret_key) ⇒ Object 



504
505
506
507
508
509
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 504

static VALUE pqcrypto_hybrid_kem_decapsulate(VALUE self, VALUE ciphertext, VALUE secret_key) {
    (void)self;
    return pq_run_kem_decapsulate(pq_hybrid_kem_decapsulate_nogvl, ciphertext,
                                  PQ_HYBRID_CIPHERTEXTBYTES, secret_key, PQ_HYBRID_SECRETKEYBYTES,
                                  PQ_HYBRID_SHAREDSECRETBYTES);
}

.hybrid_kem_encapsulate(public_key) ⇒ Object 



497
498
499
500
501
502
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 497

static VALUE pqcrypto_hybrid_kem_encapsulate(VALUE self, VALUE public_key) {
    (void)self;
    return pq_run_kem_encapsulate(pq_hybrid_kem_encapsulate_nogvl, public_key,
                                  PQ_HYBRID_PUBLICKEYBYTES, PQ_HYBRID_CIPHERTEXTBYTES,
                                  PQ_HYBRID_SHAREDSECRETBYTES);
}

.hybrid_kem_keypair ⇒ Object 



491
492
493
494
495
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 491

static VALUE pqcrypto_hybrid_kem_keypair(VALUE self) {
    (void)self;
    return pq_run_kem_keypair(pq_hybrid_kem_keypair_nogvl, PQ_HYBRID_PUBLICKEYBYTES,
                              PQ_HYBRID_SECRETKEYBYTES);
}

.ml_kem_decapsulate(ciphertext, secret_key) ⇒ Object 



485
486
487
488
489
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 485

static VALUE pqcrypto_ml_kem_decapsulate(VALUE self, VALUE ciphertext, VALUE secret_key) {
    (void)self;
    return pq_run_kem_decapsulate(pq_ml_kem_decapsulate_nogvl, ciphertext, PQ_MLKEM_CIPHERTEXTBYTES,
                                  secret_key, PQ_MLKEM_SECRETKEYBYTES, PQ_MLKEM_SHAREDSECRETBYTES);
}

.ml_kem_encapsulate(public_key) ⇒ Object 



479
480
481
482
483
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 479

static VALUE pqcrypto_ml_kem_encapsulate(VALUE self, VALUE public_key) {
    (void)self;
    return pq_run_kem_encapsulate(pq_ml_kem_encapsulate_nogvl, public_key, PQ_MLKEM_PUBLICKEYBYTES,
                                  PQ_MLKEM_CIPHERTEXTBYTES, PQ_MLKEM_SHAREDSECRETBYTES);
}

.ml_kem_keypair ⇒ Object 



473
474
475
476
477
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 473

static VALUE pqcrypto_ml_kem_keypair(VALUE self) {
    (void)self;
    return pq_run_kem_keypair(pq_ml_kem_keypair_nogvl, PQ_MLKEM_PUBLICKEYBYTES,
                              PQ_MLKEM_SECRETKEYBYTES);
}

.native_extension_loaded? ⇒ Boolean

Returns:

  • (Boolean) 


124
125
126
 
# File 'lib/pq_crypto.rb', line 124

def native_extension_loaded?
  true
end

.public_key_from_pqc_container_der(der) ⇒ Object 



760
761
762
763
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 760

static VALUE pqcrypto_public_key_from_pqc_container_der(VALUE self, VALUE der) {
    (void)self;
    return pq_import_container_der(der, pq_public_key_from_pqc_container_der);
}

.public_key_from_pqc_container_pem(pem) ⇒ Object 



765
766
767
768
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 765

static VALUE pqcrypto_public_key_from_pqc_container_pem(VALUE self, VALUE pem) {
    (void)self;
    return pq_import_container_pem(pem, pq_public_key_from_pqc_container_pem);
}

.public_key_to_pqc_container_der(algorithm, key_bytes) ⇒ Object 



736
737
738
739
740
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 736

static VALUE pqcrypto_public_key_to_pqc_container_der(VALUE self, VALUE algorithm,
                                                      VALUE key_bytes) {
    (void)self;
    return pq_export_container_der(algorithm, key_bytes, pq_public_key_to_pqc_container_der);
}

.public_key_to_pqc_container_pem(algorithm, key_bytes) ⇒ Object 



742
743
744
745
746
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 742

static VALUE pqcrypto_public_key_to_pqc_container_pem(VALUE self, VALUE algorithm,
                                                      VALUE key_bytes) {
    (void)self;
    return pq_export_container_pem(algorithm, key_bytes, pq_public_key_to_pqc_container_pem);
}

.secret_key_from_pqc_container_der(der) ⇒ Object 



770
771
772
773
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 770

static VALUE pqcrypto_secret_key_from_pqc_container_der(VALUE self, VALUE der) {
    (void)self;
    return pq_import_container_der(der, pq_secret_key_from_pqc_container_der);
}

.secret_key_from_pqc_container_pem(pem) ⇒ Object 



775
776
777
778
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 775

static VALUE pqcrypto_secret_key_from_pqc_container_pem(VALUE self, VALUE pem) {
    (void)self;
    return pq_import_container_pem(pem, pq_secret_key_from_pqc_container_pem);
}

.secret_key_to_pqc_container_der(algorithm, key_bytes) ⇒ Object 



748
749
750
751
752
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 748

static VALUE pqcrypto_secret_key_to_pqc_container_der(VALUE self, VALUE algorithm,
                                                      VALUE key_bytes) {
    (void)self;
    return pq_export_container_der(algorithm, key_bytes, pq_secret_key_to_pqc_container_der);
}

.secret_key_to_pqc_container_pem(algorithm, key_bytes) ⇒ Object 



754
755
756
757
758
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 754

static VALUE pqcrypto_secret_key_to_pqc_container_pem(VALUE self, VALUE algorithm,
                                                      VALUE key_bytes) {
    (void)self;
    return pq_export_container_pem(algorithm, key_bytes, pq_secret_key_to_pqc_container_pem);
}

.secure_wipe(str) ⇒ Object

Raises:

  • (ArgumentError) 


708
709
710
711
712
713
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 708

def secure_wipe(string)
  string = String(string)
  raise ArgumentError, "secure_wipe requires a mutable String" if string.frozen?

  native_secure_wipe(string)
end

.sign(message, secret_key) ⇒ Object 



656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 656

static VALUE pqcrypto_sign(VALUE self, VALUE message, VALUE secret_key) {
    (void)self;
    pq_validate_bytes_argument(secret_key, PQ_MLDSA_SECRETKEYBYTES, "secret key");

    sign_call_t call = {0};
    size_t secret_key_len = 0;
    call.secret_key = pq_copy_ruby_string(secret_key, &secret_key_len);
    call.signature_len = PQ_MLDSA_BYTES;
    call.signature = pq_alloc_buffer(PQ_MLDSA_BYTES);
    call.message = pq_copy_ruby_string(message, &call.message_len);

    rb_nogvl(pq_sign_nogvl, &call, NULL, NULL, RB_NOGVL_OFFLOAD_SAFE);

    pq_wipe_and_free(call.message, call.message_len);
    pq_wipe_and_free((uint8_t *)call.secret_key, secret_key_len);

    if (call.result != PQ_SUCCESS) {
        pq_wipe_and_free(call.signature, PQ_MLDSA_BYTES);
        pq_raise_general_error(call.result);
    }

    VALUE result = pq_string_from_buffer(call.signature, call.signature_len);
    free(call.signature);
    return result;
}

.sign_keypair ⇒ Object 



650
651
652
653
654
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 650

static VALUE pqcrypto_sign_keypair(VALUE self) {
    (void)self;
    return pq_run_sign_keypair(pq_sign_keypair_nogvl, PQ_MLDSA_PUBLICKEYBYTES,
                               PQ_MLDSA_SECRETKEYBYTES);
}

.supported_hybrid_kems ⇒ Object 



132
133
134
 
# File 'lib/pq_crypto.rb', line 132

def supported_hybrid_kems
  SUITES.fetch(:hybrid_kem).dup
end

.supported_kems ⇒ Object 



128
129
130
 
# File 'lib/pq_crypto.rb', line 128

def supported_kems
  SUITES.fetch(:kem).dup
end

.supported_signatures ⇒ Object 



136
137
138
 
# File 'lib/pq_crypto.rb', line 136

def supported_signatures
  SUITES.fetch(:signature).dup
end

.verify(message, signature, public_key) ⇒ Object 



682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 682

static VALUE pqcrypto_verify(VALUE self, VALUE message, VALUE signature, VALUE public_key) {
    (void)self;
    StringValue(signature);
    pq_validate_bytes_argument(public_key, PQ_MLDSA_PUBLICKEYBYTES, "public key");

    verify_call_t call = {0};
    size_t public_key_len = 0;
    size_t signature_len = 0;
    call.public_key = pq_copy_ruby_string(public_key, &public_key_len);
    call.signature = pq_copy_ruby_string(signature, &signature_len);
    call.signature_len = signature_len;
    call.message = pq_copy_ruby_string(message, &call.message_len);

    rb_nogvl(pq_verify_nogvl, &call, NULL, NULL, RB_NOGVL_OFFLOAD_SAFE);

    pq_wipe_and_free(call.message, call.message_len);
    pq_wipe_and_free((uint8_t *)call.public_key, public_key_len);
    pq_wipe_and_free((uint8_t *)call.signature, signature_len);

    if (call.result != PQ_SUCCESS) {
        pq_raise_verification_error(call.result);
    }

    return Qtrue;
}

.version ⇒ Object 



716
717
718
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 716

def version
  native_version
end