iodine 0.8.4 → 0.8.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1049,7 +1049,14 @@ module Iodine
1049
1049
  # checksums, data deduplication, and other non-security applications.
1050
1050
  # The output is deterministic and consistent across platforms.
1051
1051
  #
1052
+ # When `key:` is given, the keyed variant is computed in a single pass
1053
+ # (about the cost of an unkeyed hash, cheaper than {risky256_hmac}). Use a
1054
+ # secret key with at least 128 bits of entropy when hashing
1055
+ # attacker-influenced data (e.g., to resist hash flooding) or for fast key
1056
+ # derivation where the output stays private.
1057
+ #
1052
1058
  # @param data [String] the data to hash
1059
+ # @param key [String, nil] optional secret key (keyed hashing)
1053
1060
  # @return [String] 32-byte binary hash digest
1054
1061
  #
1055
1062
  # @note This hash function is NOT cryptographically secure. Do not use
@@ -1058,7 +1065,10 @@ module Iodine
1058
1065
  # @example
1059
1066
  # hash = Iodine::Utils.risky256("hello world")
1060
1067
  # puts hash.bytesize # => 32
1061
- def self.risky256(data); end
1068
+ #
1069
+ # # Keyed
1070
+ # tag = Iodine::Utils.risky256("hello world", key: secret)
1071
+ def self.risky256(data, key: nil); end
1062
1072
 
1063
1073
  # Computes a 512-bit (64-byte) non-cryptographic hash using Risky Hash.
1064
1074
  #
@@ -1066,7 +1076,11 @@ module Iodine
1066
1076
  # the output are identical to risky256 (truncation-safe). The second
1067
1077
  # 256 bits extend the hash without increasing collision resistance.
1068
1078
  #
1079
+ # When `key:` is given, the keyed variant is computed; its first 256 bits
1080
+ # match {risky256} with the same `key:`.
1081
+ #
1069
1082
  # @param data [String] the data to hash
1083
+ # @param key [String, nil] optional secret key (keyed hashing)
1070
1084
  # @return [String] 64-byte binary hash digest
1071
1085
  #
1072
1086
  # @note This hash function is NOT cryptographically secure. Do not use
@@ -1078,7 +1092,7 @@ module Iodine
1078
1092
  #
1079
1093
  # # First 32 bytes match risky256
1080
1094
  # hash[0, 32] == Iodine::Utils.risky256("hello world") # => true
1081
- def self.risky512(data); end
1095
+ def self.risky512(data, key: nil); end
1082
1096
 
1083
1097
  # Computes a 256-bit (32-byte) keyed HMAC using Risky Hash.
1084
1098
  #
@@ -1564,14 +1578,41 @@ module Iodine
1564
1578
  # @param cookies [Hash] (HTTP/WebSocket only) Cookies to send.
1565
1579
  # @param body [String] (HTTP only) Request body.
1566
1580
  # @param method [String] (HTTP only) HTTP method (defaults to GET).
1581
+ # @param verify [Boolean] (TLS only) If `true`, the server's certificate is
1582
+ # verified (see below). Defaults to `false`.
1567
1583
  # @return [Iodine::Connection] The new connection object.
1568
1584
  #
1585
+ # **Server verification is opt-in.** By default, TLS client connections
1586
+ # encrypt traffic but do **not** verify the server's certificate (a warning
1587
+ # is logged). This suits small (micro-service) networks where services don't
1588
+ # carry their own certificates. To verify the server, use any of:
1589
+ #
1590
+ # - `verify: true` - verifies against the system's trust store, unless the
1591
+ # TLS object already trusts specific certificates (these are kept);
1592
+ # - a `trust` URL query: `?trust=sys` (or `?trust=system`) for the system's
1593
+ # trust store, or `?trust=ca.pem` for a CA file (`.pem` is appended when
1594
+ # missing). For HTTP clients the URL query is also sent to the server as
1595
+ # the request query, so prefer `verify:` (or {Iodine::TLS#trust}) there;
1596
+ # - `tls: Iodine::TLS.new.trust` (system trust store) or
1597
+ # `tls: Iodine::TLS.new.trust("ca.pem")`.
1598
+ #
1599
+ # Once trust is set, the certificate must also match the URL's host. Note
1600
+ # that `verify: true` and `trust` URL hints update the {Iodine::TLS} object
1601
+ # passed as `tls:` (later connections using it verify too). `verify:` is
1602
+ # ignored for non-TLS connections.
1603
+ #
1604
+ # @example Verified HTTPS request (system trust store)
1605
+ # Iodine::Connection.new("https://example.com/", handler: MyHandler, verify: true)
1606
+ #
1607
+ # @example Verified with a private CA
1608
+ # Iodine::Connection.new("tls://service.internal:4000/?trust=./internal-ca.pem", handler: MyHandler)
1609
+ #
1569
1610
  # @example WebSocket client with embedded TLS
1570
1611
  # Iodine::Connection.new("wss://example.com/socket", handler: MyHandler, tls_io: :iodine)
1571
1612
  #
1572
1613
  # @example WebSocket client with OpenSSL
1573
1614
  # Iodine::Connection.new("wss://example.com/socket", handler: MyHandler, tls_io: :openssl)
1574
- def initialize(url, handler: nil, tls: nil, tls_io: nil, headers: nil, cookies: nil, body: nil, method: nil); end
1615
+ def initialize(url, handler: nil, tls: nil, tls_io: nil, headers: nil, cookies: nil, body: nil, method: nil, verify: false); end
1575
1616
 
1576
1617
  # Unless `env` is manually set, Iodine will attempt to create a default `env` object that will follow the Rack Server specification for HTTP connections.
1577
1618
  #
@@ -1986,10 +2027,21 @@ module Iodine
1986
2027
 
1987
2028
  # @!group Misc
1988
2029
 
1989
- # Returns the raw peer IP address.
1990
- # @return [String]
2030
+ # Returns the raw peer IP address (without a port), or the socket path for
2031
+ # named Unix sockets.
2032
+ # @return [String, nil]
1991
2033
  def peer_addr; end
1992
2034
 
2035
+ # Returns the local (this side's) IP address (without a port), or the
2036
+ # socket path for named Unix sockets.
2037
+ #
2038
+ # This is a socket-level value, available for HTTP, WebSocket, SSE and raw
2039
+ # connections alike. Behind a proxy or load balancer it reports the address
2040
+ # the proxy connected to, not the host the client requested (use the
2041
+ # `Host` header for that).
2042
+ # @return [String, nil]
2043
+ def local_addr; end
2044
+
1993
2045
  # Returns the published peer address (may differ with proxies).
1994
2046
  # @return [String]
1995
2047
  def from; end
@@ -2227,9 +2279,27 @@ module Iodine
2227
2279
 
2228
2280
  # Assigns the TLS context a public certificate, allowing remote parties to validate the connection's identity.
2229
2281
  #
2230
- # A self signed certificate is automatically created if the `name` argument is specified and either (or both) of the `cert` (public certificate) or `key` (private key) arguments are missing.
2282
+ # On servers, a self signed certificate (ECDSA P-256 on the `:iodine` backend)
2283
+ # is created for `name` if either (or both) of the `cert` (public certificate) or
2284
+ # `key` (private key) arguments are missing. This is fine for development, but
2285
+ # browsers will warn - use a CA issued certificate in production.
2286
+ #
2287
+ # Servers may hold several certificates; both TLS backends select one per
2288
+ # handshake using the client's SNI host name:
2289
+ #
2290
+ # 1. a case-insensitive exact match of `name`;
2291
+ # 2. else a single-label wildcard (`*.example.com` matches `www.example.com`,
2292
+ # but neither `example.com` nor `a.b.example.com`);
2293
+ # 3. else the default certificate: the one added with an empty `name`, else the
2294
+ # first one added.
2231
2295
  #
2232
- # Some implementations allow servers to have more than a single certificate, which will be selected using the SNI extension. I believe the existing OpenSSL implementation supports this option (untested).
2296
+ # Re-adding a `name` replaces its certificate. An omitted `name` defaults to
2297
+ # `"localhost"`.
2298
+ #
2299
+ # On clients, the (default) certificate is presented when the server requests
2300
+ # one (mutual TLS / client certificate authentication), with its whole chain.
2301
+ # Use client certificates with PEM files: a name-only client entry presents no
2302
+ # certificate on the `:iodine` backend.
2233
2303
  #
2234
2304
  # Iodine::TLS#add_cert(name = nil,
2235
2305
  # cert = nil,
@@ -2638,6 +2708,7 @@ module Iodine
2638
2708
  # - {ChaCha20Poly1305} - AEAD symmetric encryption (12-byte nonce)
2639
2709
  # - {XChaCha20Poly1305} - AEAD symmetric encryption (24-byte nonce, safe for random)
2640
2710
  # - {Ed25519} - Digital signatures (with key conversion to X25519)
2711
+ # - {P256} / {P384} - ECDSA digital signatures (ES256 / ES384, OpenSSL compatible)
2641
2712
  # - {X25519} - Key exchange and public-key encryption (ECIES with ChaCha20, AES-128, or AES-256)
2642
2713
  # - {HKDF} - Key derivation (RFC 5869)
2643
2714
  # - {X25519MLKEM768} - Post-quantum hybrid key encapsulation (X25519 + ML-KEM-768)
@@ -2877,6 +2948,97 @@ module Iodine
2877
2948
  def self.to_x25519_public(ed_public_key:); end
2878
2949
  end
2879
2950
 
2951
+ # ECDSA P-256 digital signatures (ES256: SHA-256, 128-bit security level).
2952
+ #
2953
+ # Interoperable with OpenSSL / JOSE tooling: secret keys are 32-byte
2954
+ # big-endian scalars, public keys are uncompressed SEC 1 points
2955
+ # (`0x04 || x || y`, 65 bytes; {verify} also accepts 33-byte compressed
2956
+ # points) and signatures are DER encoded (at most 72 bytes; JWS ES256
2957
+ # uses raw `r || s` instead). Messages are hashed with SHA-256 internally.
2958
+ #
2959
+ # Signatures are randomized (a fresh nonce per signature), so signing the
2960
+ # same data twice produces different, equally valid signatures.
2961
+ #
2962
+ # @note facil.io's P-256 / P-384 implementation has not been independently
2963
+ # audited. Prefer {Ed25519} when you control both sides.
2964
+ module P256
2965
+ # Generates a new P-256 key pair.
2966
+ #
2967
+ # @return [Array<String, String>] [secret_key (32 bytes), public_key (65 bytes)]
2968
+ #
2969
+ # @example
2970
+ # secret_key, public_key = Iodine::Base::Crypto::P256.keypair
2971
+ def self.keypair; end
2972
+
2973
+ # Derives the (uncompressed) public key from a P-256 secret key.
2974
+ #
2975
+ # @param secret_key [String] 32-byte secret key
2976
+ # @return [String] 65-byte public key
2977
+ # @raise [ArgumentError] if secret_key is not 32 bytes or out of range
2978
+ def self.public_key(secret_key:); end
2979
+
2980
+ # Signs a message (hashed with SHA-256) using ECDSA P-256.
2981
+ #
2982
+ # @param data [String] Message to sign
2983
+ # @param secret_key [String] 32-byte secret key
2984
+ # @return [String] DER encoded signature
2985
+ # @raise [ArgumentError] if secret_key is not 32 bytes or invalid
2986
+ #
2987
+ # @example
2988
+ # signature = Iodine::Base::Crypto::P256.sign("data", secret_key: sk)
2989
+ def self.sign(data, secret_key:); end
2990
+
2991
+ # Verifies a DER encoded ECDSA P-256 signature.
2992
+ #
2993
+ # @param data [String] Original message
2994
+ # @param signature [String] DER encoded signature
2995
+ # @param public_key [String] 65-byte (or 33-byte compressed) public key
2996
+ # @return [Boolean] `true` if valid, `false` otherwise (including
2997
+ # malformed signatures or keys)
2998
+ #
2999
+ # @example
3000
+ # valid = Iodine::Base::Crypto::P256.verify("data", signature, public_key: pk)
3001
+ def self.verify(data, signature, public_key:); end
3002
+ end
3003
+
3004
+ # ECDSA P-384 digital signatures (ES384: SHA-384, 192-bit security level).
3005
+ #
3006
+ # Same API and encodings as {P256}, with 48-byte secret keys, 97-byte
3007
+ # uncompressed public keys (49-byte compressed accepted by {verify}),
3008
+ # DER signatures of at most 104 bytes, and SHA-384 message hashing.
3009
+ #
3010
+ # @note facil.io's P-256 / P-384 implementation has not been independently
3011
+ # audited. Prefer {Ed25519} when you control both sides.
3012
+ module P384
3013
+ # Generates a new P-384 key pair.
3014
+ #
3015
+ # @return [Array<String, String>] [secret_key (48 bytes), public_key (97 bytes)]
3016
+ def self.keypair; end
3017
+
3018
+ # Derives the (uncompressed) public key from a P-384 secret key.
3019
+ #
3020
+ # @param secret_key [String] 48-byte secret key
3021
+ # @return [String] 97-byte public key
3022
+ # @raise [ArgumentError] if secret_key is not 48 bytes or out of range
3023
+ def self.public_key(secret_key:); end
3024
+
3025
+ # Signs a message (hashed with SHA-384) using ECDSA P-384.
3026
+ #
3027
+ # @param data [String] Message to sign
3028
+ # @param secret_key [String] 48-byte secret key
3029
+ # @return [String] DER encoded signature
3030
+ # @raise [ArgumentError] if secret_key is not 48 bytes or invalid
3031
+ def self.sign(data, secret_key:); end
3032
+
3033
+ # Verifies a DER encoded ECDSA P-384 signature.
3034
+ #
3035
+ # @param data [String] Original message
3036
+ # @param signature [String] DER encoded signature
3037
+ # @param public_key [String] 97-byte (or 49-byte compressed) public key
3038
+ # @return [Boolean] `true` if valid, `false` otherwise
3039
+ def self.verify(data, signature, public_key:); end
3040
+ end
3041
+
2880
3042
  # X25519 key exchange (ECDH) and public-key encryption (ECIES).
2881
3043
  #
2882
3044
  # X25519 provides secure key agreement and can be combined with
@@ -2,7 +2,7 @@
2
2
 
3
3
  module Iodine
4
4
  # The Iodine gem version number
5
- VERSION = "0.8.4"
5
+ VERSION = "0.8.5"
6
6
  # NeoRack supported extensions.
7
7
  def self.extensions
8
8
  return (@extensions ||= { iodine: (VERSION.split(?.).map() {|i| i.to_i.to_s == i ? i.to_i : i }),
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: iodine
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.8.4
4
+ version: 0.8.5
5
5
  platform: ruby
6
6
  authors:
7
7
  - Boaz Segev
@@ -134,7 +134,7 @@ metadata:
134
134
  homepage_uri: https://github.com/boazsegev/iodine
135
135
  source_code_uri: https://github.com/boazsegev/iodine
136
136
  changelog_uri: https://github.com/boazsegev/iodine/blob/master/CHANGELOG.md
137
- post_install_message: Thank you for installing Iodine 0.8.4.
137
+ post_install_message: Thank you for installing Iodine 0.8.5.
138
138
  rdoc_options: []
139
139
  require_paths:
140
140
  - lib