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.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 



535
536
537
538
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
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 535

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 



502
503
504
505
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
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 502

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 



605
606
607
608
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
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 605

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 



572
573
574
575
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
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 572

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 



701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 701

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 



495
496
497
498
499
500
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 495

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 



488
489
490
491
492
493
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 488

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 



482
483
484
485
486
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 482

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 



476
477
478
479
480
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 476

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 



470
471
472
473
474
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 470

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 



464
465
466
467
468
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 464

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 



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

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 



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

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 



745
746
747
748
749
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 745

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 



751
752
753
754
755
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 751

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 



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

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 



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

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 



757
758
759
760
761
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 757

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 



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

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) 


717
718
719
720
721
722
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 717

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 



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

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 



641
642
643
644
645
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 641

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 



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

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 



725
726
727
 
# File 'ext/pqcrypto/pqcrypto_ruby_secure.c', line 725

def version
  native_version
end