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, NativeBindings, 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_xwing].freeze,
  signature: [:ml_dsa_65].freeze,
}.freeze
NATIVE_EXTENSION_LOADED = 
true
VERSION = 
"0.3.1"
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 



539
540
541
542
543
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
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 539

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 



506
507
508
509
510
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
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 506

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

    if ((size_t)RSTRING_LEN(seed) != 64) {
        rb_raise(rb_eArgError, "Deterministic ML-KEM test seed must be 64 bytes (FIPS 203 d||z)");
    }

    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 



609
610
611
612
613
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
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 609

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 



576
577
578
579
580
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
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 576

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 



89
90
91
 
# File 'lib/pq_crypto.rb', line 89

def backend
  :native_pqclean
end

.ct_equals(a, b) ⇒ Object 



705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 705

static VALUE pqcrypto_ct_equals(VALUE self, VALUE a, VALUE b) {
    (void)self;
    StringValue(a);
    StringValue(b);
    if (RSTRING_LEN(a) != RSTRING_LEN(b)) {
        return Qfalse;
    }
    if (RSTRING_LEN(a) == 0) {
        return Qtrue;
    }
    if (CRYPTO_memcmp(RSTRING_PTR(a), RSTRING_PTR(b), (size_t)RSTRING_LEN(a)) == 0) {
        return Qtrue;
    }
    return Qfalse;
}

.hybrid_kem_decapsulate(ciphertext, secret_key) ⇒ Object 



499
500
501
502
503
504
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 499

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 



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

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 



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

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 



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

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 



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

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 



468
469
470
471
472
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 468

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) 


93
94
95
 
# File 'lib/pq_crypto.rb', line 93

def native_extension_loaded?
  true
end

.public_key_from_pqc_container_der(der) ⇒ Object 



773
774
775
776
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 773

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 



778
779
780
781
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 778

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 



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

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 



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

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 



783
784
785
786
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 783

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 



788
789
790
791
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 788

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 



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

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 



767
768
769
770
771
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 767

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) 


721
722
723
724
725
726
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 721

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 



651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 651

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 



645
646
647
648
649
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 645

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 



101
102
103
 
# File 'lib/pq_crypto.rb', line 101

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

.supported_kems ⇒ Object 



97
98
99
 
# File 'lib/pq_crypto.rb', line 97

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

.supported_signatures ⇒ Object 



105
106
107
 
# File 'lib/pq_crypto.rb', line 105

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

.verify(message, signature, public_key) ⇒ Object 



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

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) {
        return Qtrue;
    }
    if (call.result == PQ_ERROR_VERIFY) {
        return Qfalse;
    }
    pq_raise_general_error(call.result);
}

.version ⇒ Object 



729
730
731
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 729

def version
  native_version
end