nuckle 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00a442ba9e5d4c70e543b9f2ec156248c283881fcf2bb774dc592534bc0a79dc
-  data.tar.gz: 478ebf814c22348331fcbbb5692f302425bca6cb4c48365c4508c8c4426f30ed
+  metadata.gz: b6a034f12d9a0dd8326bfbc7595b593cd7a0089ab7fe0c8563c7d7eecce791e9
+  data.tar.gz: 6161d94c79b134ffe0dd014dba44c65345910bde408ab5c618fccba456cc5356
 SHA512:
-  metadata.gz: a291010aeaa3fce0a12479f2a8b40e0fd089125d295f1890801683350a3ffb7ea34c03ca527ed6e63738d539e305d7d46dce5294adc58b1c0494e26bf5e19835
-  data.tar.gz: '0886502547f3628973eab880936d6bec563bb48807f39b959e7bf390433acffa67d63d30e456ed8f51a5ccb547eb1c1c3739f43f23f098581d241444d003c263'
+  metadata.gz: e513c94f45a9bf21e6a432c419868e8c5817bd82c7727debf402394dfd09d28fa488f8622ba69182e44d30e7262caa8b5ac6263e06ccddb6f7e96864da535063
+  data.tar.gz: dc9dbc2a4f101c1bc842037b88f3db9dd765020c5e3d855f6ad4c45c26847aa79e278ebcb0a410f4a4a216fd551d063b37ea5cf432996b867c031e478e9b5a00

data/lib/nuckle/box.rb

@@ -12,6 +12,9 @@ module Nuckle
     BEFORENMBYTES  = 32
     MACBYTES       = 16
 
+
+    # @param public_key [PublicKey, String] peer's 32-byte public key
+    # @param private_key [PrivateKey, String] own 32-byte private key
     def initialize(public_key, private_key)
       pk = extract_bytes(public_key, PUBLICKEYBYTES, "public key")
       sk = extract_bytes(private_key, PRIVATEKEYBYTES, "private key")
@@ -25,6 +28,8 @@ module Nuckle
       @secret_box = SecretBox.new(key)
     end
 
+
+    # @return [Integer] required nonce length in bytes
     def nonce_bytes = NONCEBYTES
 
     # Encrypt plaintext with 24-byte nonce.
@@ -32,6 +37,7 @@ module Nuckle
       @secret_box.encrypt(nonce, plaintext)
     end
 
+
     # Decrypt ciphertext with 24-byte nonce.
     def decrypt(nonce, ciphertext)
       @secret_box.decrypt(nonce, ciphertext)
@@ -44,9 +50,12 @@ module Nuckle
 
     def extract_bytes(key, expected_size, name)
       bytes = case key
-              when PublicKey, PrivateKey then key.to_s
-              when String               then key.b
-              else raise ArgumentError, "#{name} must be a Key or String"
+              when PublicKey, PrivateKey
+                key.to_s
+              when String
+                key.b
+              else
+                raise ArgumentError, "#{name} must be a Key or String"
               end
       raise ArgumentError, "#{name} must be #{expected_size} bytes (got #{bytes.bytesize})" unless bytes.bytesize == expected_size
 

data/lib/nuckle/crypto_error.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module Nuckle
-  class CryptoError < StandardError; end
+  # Raised when authenticated decryption fails (MAC verification failure).
+  class CryptoError < StandardError
+  end
 end

data/lib/nuckle/private_key.rb

@@ -1,13 +1,21 @@
 # frozen_string_literal: true
 
 module Nuckle
+  # An X25519 (Curve25519) private key for Diffie-Hellman key agreement.
   class PrivateKey
+    # Key length in bytes.
     BYTES = 32
 
+
+    # Generates a new random private key.
+    #
+    # @return [PrivateKey]
     def self.generate
       new(Random.random_bytes(BYTES))
     end
 
+
+    # @param key [String] 32-byte raw private key (binary)
     def initialize(key)
       key = key.to_s if key.respond_to?(:to_s) && !key.is_a?(String)
       key = key.b
@@ -16,11 +24,42 @@ module Nuckle
       @key = key
     end
 
+
+    # Derives the corresponding public key via Curve25519 scalar base multiplication.
+    #
+    # @return [PublicKey]
     def public_key
       PublicKey.new(Internals::Curve25519.scalarmult_base(@key))
     end
 
+
+    # Raw X25519 Diffie-Hellman: scalar multiply this secret key by a peer's
+    # public key to produce a 32-byte shared secret.
+    #
+    # Unlike {Box}, this returns the raw DH output without further key
+    # derivation (no HSalsa20). Callers are responsible for deriving
+    # symmetric keys from the result (e.g. via HKDF or BLAKE3-derive-key).
+    #
+    # @param peer_public_key [PublicKey, String] peer's 32-byte public key
+    # @return [String] 32-byte shared secret (binary)
+    def diffie_hellman(peer_public_key)
+      pk = case peer_public_key
+           when PublicKey
+             peer_public_key.to_s
+           when String
+             peer_public_key.b
+           else
+             raise ArgumentError, "peer_public_key must be a PublicKey or String"
+           end
+      raise ArgumentError, "peer public key must be 32 bytes" unless pk.bytesize == BYTES
+
+      Internals::Curve25519.scalarmult(@key, pk)
+    end
+
+
+    # @return [String] raw 32-byte key (binary)
     def to_bytes = @key
+    # @return [String] raw 32-byte key (binary)
     def to_s     = @key
   end
 end

data/lib/nuckle/public_key.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
 module Nuckle
+  # An X25519 (Curve25519) public key.
   class PublicKey
+    # Key length in bytes.
     BYTES = 32
 
+
+    # @param key [String] 32-byte raw public key (binary)
     def initialize(key)
       key = key.to_s if key.respond_to?(:to_s) && !key.is_a?(String)
       key = key.b
@@ -12,9 +16,16 @@ module Nuckle
       @key = key
     end
 
+
+    # @return [String] raw 32-byte key (binary)
     def to_bytes = @key
+    # @return [String] raw 32-byte key (binary)
     def to_s     = @key
 
+    # Constant-time equality comparison.
+    #
+    # @param other [PublicKey] key to compare
+    # @return [Boolean]
     def ==(other)
       other.is_a?(PublicKey) && Util.verify32(@key, other.to_s)
     end

data/lib/nuckle/random.rb

@@ -3,7 +3,12 @@
 require "securerandom"
 
 module Nuckle
+  # Cryptographically secure random byte generation.
   module Random
+    # Generates +n+ cryptographically secure random bytes.
+    #
+    # @param n [Integer] number of bytes
+    # @return [String] random bytes (binary)
     def self.random_bytes(n)
       SecureRandom.random_bytes(n)
     end

data/lib/nuckle/secret_box.rb

@@ -12,6 +12,8 @@ module Nuckle
     BOXZEROBYTES = 16
     MACBYTES     = 16
 
+
+    # @param key [String] 32-byte symmetric key (binary)
     def initialize(key)
       key = key.b
       raise ArgumentError, "key must be #{KEYBYTES} bytes (got #{key.bytesize})" unless key.bytesize == KEYBYTES
@@ -19,7 +21,10 @@ module Nuckle
       @key = key
     end
 
+
+    # @return [Integer] required nonce length in bytes
     def nonce_bytes = NONCEBYTES
+    # @return [Integer] required key length in bytes
     def key_bytes   = KEYBYTES
 
     # Encrypt plaintext with 24-byte nonce.
@@ -47,6 +52,7 @@ module Nuckle
       mac + c.byteslice(ZEROBYTES..)
     end
 
+
     # Decrypt ciphertext with 24-byte nonce.
     #
     # @param nonce [String] 24-byte nonce
@@ -76,6 +82,7 @@ module Nuckle
       m.byteslice(ZEROBYTES..)
     end
 
+
     # Aliases matching rbnacl API
     alias box encrypt
     alias open decrypt

data/lib/nuckle/util.rb

@@ -1,22 +1,32 @@
 # frozen_string_literal: true
 
 module Nuckle
+  # Constant-time comparison utilities for cryptographic data.
   module Util
     # Compare two 16-byte strings.
     def self.verify16(a, b)
       verify(a, b, 16)
     end
 
+
     # Compare two 32-byte strings.
     def self.verify32(a, b)
       verify(a, b, 32)
     end
 
+
     # Compare two 64-byte strings.
     def self.verify64(a, b)
       verify(a, b, 64)
     end
 
+
+    # Compares two binary strings for equality.
+    #
+    # @param a [String] first string
+    # @param b [String] second string
+    # @param expected_size [Integer, nil] required byte length, or nil to skip check
+    # @return [Boolean]
     def self.verify(a, b, expected_size = nil)
       a = a.b if a.encoding != Encoding::BINARY
       b = b.b if b.encoding != Encoding::BINARY

data/lib/nuckle/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nuckle
-  VERSION = "0.1.1"
+  VERSION = "0.2.1"
 end

data/lib/nuckle.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Pure Ruby NaCl-compatible cryptography library.
+# Provides Curve25519 key agreement, XSalsa20-Poly1305 authenticated
+# encryption (SecretBox), and public-key authenticated encryption (Box).
+
 require_relative "nuckle/version"
 require_relative "nuckle/crypto_error"
 require_relative "nuckle/random"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nuckle
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Patrik Wenger