hide-protocol 0.9.1-aarch64-linux → 0.10.0-aarch64-linux

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.
data/README.md CHANGED
@@ -2,9 +2,12 @@
2
2
 
3
3
  *Experimental and unaudited. HIDE is hybrid post-quantum (X25519 + ML-KEM-768, Ed25519 + ML-DSA-65). See the [security policy](https://github.com/hide-protocol/hide/blob/main/SECURITY.md).*
4
4
 
5
- Ruby binding, through stdlib `fiddle`, to the same Rust core (`crates/hide-ffi`)
5
+ Ruby binding, through `fiddle`, to the same Rust core (`crates/hide-ffi`)
6
6
  that the CLI and every other HIDE SDK use. This gem contains no cryptography of
7
- its own, no compiled extension and no runtime gem dependency.
7
+ its own and no compiled extension. Its one runtime dependency is `fiddle`
8
+ (1.0.6 or newer), which every supported Ruby already ships: as a default gem
9
+ up to Ruby 3.4, and as a bundled gem from Ruby 4.0, where Bundler only makes
10
+ it loadable because this gem declares it.
8
11
 
9
12
  ## Install
10
13
 
@@ -46,6 +49,11 @@ positional and returns a `Hide::Decrypted` with `plaintext`, `filename` and
46
49
  filename is attacker-controlled: never use it to choose an output path. Binary
47
50
  values in and out are ASCII-8BIT Strings; metadata comes back as UTF-8.
48
51
 
52
+ A `filename` must be one portable file name, and encryption refuses anything
53
+ else: at most 255 bytes, not `.` or `..`, no control characters, none of
54
+ `< > : " / \ | ? *`, no trailing dot or space, and not a Windows device name
55
+ such as `CON` or `COM1`.
56
+
49
57
  Keys on disk: `secret.protect(passphrase)` returns a sealed key file
50
58
  (`Hide::MIN_PASSPHRASE_LEN` is 8, and there is no escrow);
51
59
  `Hide::SecretKey.open(bytes, passphrase)` opens one; `Hide.inspect_key(bytes)`
@@ -57,8 +65,15 @@ Errors: everything raises a subclass of `Hide::Error` — `AuthenticationError`
57
65
  (altered, or not a container), its subclass `MalformedError` (did not decode at
58
66
  all), `WrongPassphraseError`, `NoMatchingRecipientError`, `NotAKeyError`,
59
67
  `TooLargeError`, `ClosedKeyError`, `ChallengeExpiredError`,
60
- `ChallengeReplayedError`, and `InvalidArgumentError` for arguments this binding
61
- rejects before calling the core.
68
+ `ChallengeReplayedError`, `ChallengeAudienceError`, and `InvalidArgumentError`
69
+ for arguments this binding rejects before calling the core.
70
+
71
+ Text arguments must not contain a NUL character. Passphrases, filenames,
72
+ media types, audiences, origins and armored keys cross into the core as C
73
+ strings, which end at the first NUL: `"longenough\0rest"` would otherwise seal
74
+ a key under `"longenough"`. Such text raises `Hide::InvalidArgumentError`
75
+ instead. Text is sent as UTF-8: a String in another encoding is transcoded,
76
+ and an ASCII-8BIT String is taken as the UTF-8 bytes it already holds.
62
77
 
63
78
  ## Signing and verification
64
79
 
@@ -78,20 +93,42 @@ Hide::SigningIdentity.open(sealed, "correct horse battery") do |signer|
78
93
  now = Time.now.to_i
79
94
  challenge = Hide.new_challenge("app.example", now, 60)
80
95
  answer = signer.answer(challenge)
81
- Hide::SpentNonces.open do |spent| # must outlive one request
96
+ Hide::SpentNonces.open("app.example") do |spent| # must outlive one request
82
97
  spent.accept(challenge, answer, signer.public_key, now)
83
98
  spent.accept(challenge, answer, signer.public_key, now) # Hide::ChallengeReplayedError
84
99
  end
85
100
  end
86
101
  ```
87
102
 
103
+ `Hide::SpentNonces.open(audience)` must be built with the name this verifier
104
+ answers to — the same string passed to `Hide.new_challenge`. An answer minted
105
+ for a different audience is refused with `Hide::ChallengeAudienceError`, so a
106
+ challenge relayed from another service cannot be answered here; a record built
107
+ with an empty audience accepts nothing.
108
+
88
109
  `context` separates uses of one identity so a signature made for one purpose
89
- cannot be replayed as another; never let a remote party choose it.
110
+ cannot be replayed as another; never let a remote party choose it. Contexts
111
+ beginning with `HIDE/` are reserved for the protocol: `sign` refuses them with
112
+ `Hide::InvalidArgumentError`, while `Hide.verify` accepts any context.
90
113
  `Hide.verify` returns `nil` and raises `Hide::AuthenticationError` on failure
91
114
  rather than returning a boolean a caller could forget to check. A key file
92
115
  written before signatures existed carries no signing seed and raises
93
116
  `Hide::NotAKeyError`.
94
117
 
118
+ ## Threads
119
+
120
+ - `Hide::SpentNonces` may be shared between threads. `accept` takes a
121
+ per-object lock around the native call, which changes the record; `fiddle`
122
+ releases the interpreter lock during that call, so without the lock two
123
+ threads could both accept the same answer. Keep one record per verifier,
124
+ not one per thread: a replay is only caught by the record that saw the
125
+ first answer. A forking server has one record per worker process, and
126
+ those do not see each other's answers.
127
+ - `Hide::SecretKey` and `Hide::SigningIdentity` may be used from several
128
+ threads at once; the native calls only read them. Do not `close` one while
129
+ another thread is still inside a call on it.
130
+ - Module-level methods hold no shared state.
131
+
95
132
  ## Identity logs, epoch chains, transparency proofs
96
133
 
97
134
  | Method | Returns |
@@ -119,13 +156,18 @@ trust out of band does.
119
156
 
120
157
  ## Native library
121
158
 
122
- The core is located in this order:
159
+ The core is loaded from one of two places, always by absolute path:
123
160
 
124
161
  1. `HIDE_LIBRARY`, if it names a file **and** `HIDE_ALLOW_LIBRARY_OVERRIDE=1`
125
- is also set;
126
- 2. beside the gem, in `lib/hide_protocol/`, where the platform gem puts it;
127
- 3. the system loader, by name (`hide_ffi.dll`, `libhide_ffi.dylib`,
128
- `libhide_ffi.so`).
162
+ is also set. Once opted in it is the only candidate: if it cannot be
163
+ loaded, `require` fails rather than falling back to another copy;
164
+ 2. otherwise beside the binding, in `lib/hide_protocol/`, where the platform
165
+ gem puts it (`hide_ffi.dll`, `libhide_ffi.dylib` or `libhide_ffi.so`).
166
+
167
+ The system loader is never asked to search by name, so a library placed in
168
+ the working directory, on `PATH` or on `LD_LIBRARY_PATH` is not picked up. If
169
+ neither place has the library, `require "hide_protocol"` raises
170
+ `Hide::Binding::LibraryNotFound` naming the platform and what to install.
129
171
 
130
172
  `HIDE_LIBRARY` is a development override: it replaces the entire cryptographic
131
173
  core, so a single settable environment variable must not be enough to redirect
@@ -138,6 +180,12 @@ export HIDE_ALLOW_LIBRARY_OVERRIDE=1
138
180
  ruby -Ilib -Itest test/test_hide.rb
139
181
  ```
140
182
 
183
+ The core and the binding must be the same release. When it is required the
184
+ binding compares the core's `major.minor.patch` with its own, read from the
185
+ gemspec shipped in the gem, and raises `Hide::Binding::VersionMismatch` on
186
+ any difference: the core enforces checks this binding only documents, so an
187
+ older core beside a newer binding would silently lose them.
188
+
141
189
  ## Key material
142
190
 
143
191
  `Hide::SecretKey`, `Hide::SigningIdentity` and `Hide::SpentNonces` are opaque
@@ -147,6 +195,13 @@ with `#close`, or use the block form of `.generate` / `.open`, which always
147
195
  closes — including when the block raises. A closed handle raises
148
196
  `Hide::ClosedKeyError` on use.
149
197
 
198
+ A handle cannot be copied: `dup`, `clone` and `Marshal.dump` raise
199
+ `TypeError`. A copy would share the native object, and closing either one
200
+ would free it under the other. To use a key in a second place, pass the same
201
+ object, or open the key file again. For the same reason
202
+ `Hide::SecretKey.new` and `Hide::SigningIdentity.new` are private: keys come
203
+ from `.generate`, `.open` and `.load` only.
204
+
150
205
  ## Limits
151
206
 
152
207
  - Unaudited. Do not protect data you cannot afford to lose or expose.
@@ -0,0 +1,49 @@
1
+ # frozen_string_literal: true
2
+
3
+ Gem::Specification.new do |spec|
4
+ spec.name = "hide-protocol"
5
+ spec.version = "0.10.0"
6
+ spec.summary = "Experimental hybrid post-quantum file and message encryption. Unaudited."
7
+ spec.description =
8
+ "Ruby bindings to the HIDE core (X25519 + ML-KEM-768). Experimental and " \
9
+ "unaudited: a successful decryption proves the data was not altered, not " \
10
+ "who created it."
11
+ spec.authors = ["HIDE contributors"]
12
+ spec.license = "Apache-2.0"
13
+ spec.homepage = "https://github.com/hide-protocol/hide"
14
+
15
+ spec.metadata = {
16
+ "homepage_uri" => spec.homepage,
17
+ "source_code_uri" => spec.homepage,
18
+ "bug_tracker_uri" => "#{spec.homepage}/issues",
19
+ "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md",
20
+ "documentation_uri" => "#{spec.homepage}/blob/main/sdk/ruby/README.md",
21
+ "rubygems_mfa_required" => "true"
22
+ }
23
+
24
+ # The publish workflow copies the compiled core in and sets
25
+ # HIDE_GEM_PLATFORM, so `gem install` fetches only this machine's binary and
26
+ # there is no native build step. Without it the gem still builds, as a
27
+ # source gem needing HIDE_LIBRARY.
28
+ platform = ENV["HIDE_GEM_PLATFORM"]
29
+ spec.platform = platform unless platform.nil? || platform.empty?
30
+
31
+ spec.required_ruby_version = ">= 3.0"
32
+
33
+ # The gemspec itself is shipped: the binding reads its own version from it
34
+ # at load time, to refuse a native library from a different release.
35
+ spec.files =
36
+ Dir["lib/**/*.rb"] +
37
+ Dir["lib/hide_protocol/*.{so,dylib,dll}"] +
38
+ Dir["{README.md,LICENSE,hide-protocol.gemspec}"]
39
+ spec.require_paths = ["lib"]
40
+
41
+ # fiddle is a default gem up to Ruby 3.4 and a bundled gem from Ruby 4.0,
42
+ # where a Bundler-managed application can only require what its bundle
43
+ # declares.
44
+ # 1.0.6 is the version Ruby 3.0.0 ships, and has everything the binding
45
+ # uses, so no supported Ruby has to compile a newer fiddle to satisfy this.
46
+ spec.add_dependency "fiddle", ">= 1.0.6"
47
+
48
+ spec.add_development_dependency "minitest", "~> 5.0"
49
+ end
@@ -6,9 +6,9 @@ require "rbconfig"
6
6
  module Hide
7
7
  # Raw access to the HIDE C core.
8
8
  #
9
- # fiddle rather than the ffi gem: fiddle ships with Ruby, so installing this
10
- # gem needs no compiler and adds no runtime dependency, and the ABI is
11
- # described in exactly one place.
9
+ # fiddle rather than the ffi gem: fiddle ships with Ruby (a default gem up
10
+ # to 3.4, a bundled gem from 4.0), so installing this gem needs no compiler,
11
+ # and the ABI is described in exactly one place.
12
12
  module Binding
13
13
  OK = 0
14
14
  ERR_INVALID_ARGUMENT = 1
@@ -20,6 +20,7 @@ module Hide
20
20
  ERR_MALFORMED = 6
21
21
  ERR_CHALLENGE_EXPIRED = 8
22
22
  ERR_CHALLENGE_REPLAYED = 9
23
+ ERR_CHALLENGE_AUDIENCE = 11
23
24
  ERR_PANIC = 98
24
25
  ERR_INTERNAL = 99
25
26
 
@@ -40,6 +41,9 @@ module Hide
40
41
 
41
42
  class LibraryNotFound < StandardError; end
42
43
 
44
+ # The native library and this binding are not the same release.
45
+ class VersionMismatch < StandardError; end
46
+
43
47
  def self.library_names
44
48
  case RbConfig::CONFIG["host_os"]
45
49
  when /mswin|mingw|cygwin/ then ["hide_ffi.dll"]
@@ -48,34 +52,82 @@ module Hide
48
52
  end
49
53
  end
50
54
 
51
- # Mirrors the Python binding: an explicit override, then the copy shipped
52
- # beside the gem, then whatever the system loader can find.
53
- def self.load_library
54
- here = File.dirname(__FILE__)
55
- candidates = library_names.map { |name| File.join(here, name) }
56
-
55
+ # Mirrors the Python binding: an explicit override, else the copy shipped
56
+ # beside this file, and nothing else.
57
+ #
58
+ # Only absolute paths are ever handed to the loader. A bare file name would
59
+ # let it search the current directory, PATH or LD_LIBRARY_PATH, which
60
+ # replaces the cryptographic core with no opt-in at all.
61
+ def self.locate_library
57
62
  override = ENV["HIDE_LIBRARY"]
58
63
  # HIDE_LIBRARY replaces the whole cryptographic core, so one settable env
59
64
  # var must not be enough: it is honoured only with an explicit second opt-in.
65
+ # Once opted in it is the answer, not one candidate among several: failing
66
+ # to load it is an error rather than a reason to quietly use another copy.
60
67
  allowed = ENV["HIDE_ALLOW_LIBRARY_OVERRIDE"] == "1"
61
- candidates.unshift(override) if allowed && override && !override.empty?
68
+ return File.expand_path(override) if allowed && override && !override.empty?
62
69
 
63
- candidates.each do |candidate|
64
- return Fiddle.dlopen(candidate) if File.exist?(candidate)
65
- end
70
+ here = File.expand_path(__dir__)
71
+ packaged = library_names.map { |name| File.join(here, name) }.find { |path| File.file?(path) }
72
+ return packaged if packaged
66
73
 
67
- begin
68
- Fiddle.dlopen(library_names.first)
69
- rescue Fiddle::DLError
70
- raise LibraryNotFound,
71
- "the HIDE native library was not found. Install a gem that " \
72
- "bundles it. Developers: set HIDE_LIBRARY to the path of " \
74
+ raise LibraryNotFound,
75
+ "the HIDE native library (#{library_names.first}) was not found for " \
76
+ "#{RUBY_PLATFORM}. Install the hide-protocol platform gem for this " \
77
+ "machine, which bundles it. Developers: set HIDE_LIBRARY to the path of " \
73
78
  "#{library_names.first} built by `cargo build -p hide-ffi` " \
74
79
  "AND HIDE_ALLOW_LIBRARY_OVERRIDE=1."
75
- end
76
80
  end
77
81
 
78
- LIB = load_library
82
+ def self.load_library(path)
83
+ Fiddle.dlopen(path)
84
+ rescue Fiddle::DLError => e
85
+ raise LibraryNotFound, "the HIDE native library at #{path} could not be loaded: #{e.message}"
86
+ end
87
+
88
+ # The version of this binding, from the gemspec it is built from: the one
89
+ # place a release writes it, shipped inside the gem for this purpose. The
90
+ # file beside lib answers first, because an older installed copy of the
91
+ # gem must not speak for this code.
92
+ def self.binding_version
93
+ gemspec = File.expand_path("../../hide-protocol.gemspec", __dir__)
94
+ declared = File.file?(gemspec) && File.read(gemspec, encoding: "UTF-8")[/spec\.version = "([^"]+)"/, 1]
95
+ return declared if declared
96
+
97
+ activated = defined?(Gem) && Gem.loaded_specs["hide-protocol"]
98
+ return activated.version.to_s if activated
99
+
100
+ raise VersionMismatch,
101
+ "cannot tell which version of hide-protocol this is, so the native " \
102
+ "library cannot be checked against it. Install the gem rather than " \
103
+ "copying its lib directory."
104
+ end
105
+
106
+ def self.version_triple(text, what)
107
+ match = /\A(\d+)\.(\d+)\.(\d+)/.match(text.to_s)
108
+ raise VersionMismatch, "the #{what} version #{text.inspect} is not major.minor.patch" unless match
109
+
110
+ match.captures.map(&:to_i)
111
+ end
112
+
113
+ # Refuses a core whose major.minor.patch differs from this binding's.
114
+ #
115
+ # Exact, not merely compatible: the core enforces checks this binding only
116
+ # documents (reserved contexts, metadata rules, limits), so a stale core
117
+ # beside a newer binding would silently lose them. Pre-release and build
118
+ # suffixes are not compared.
119
+ def self.check_version(core, binding = BINDING_VERSION)
120
+ return if version_triple(core, "core") == version_triple(binding, "binding")
121
+
122
+ raise VersionMismatch,
123
+ "the HIDE native library is version #{core} but this binding is " \
124
+ "#{binding}; install matching versions of both"
125
+ end
126
+
127
+ BINDING_VERSION = binding_version
128
+ # The absolute path the core was loaded from.
129
+ LIBRARY_PATH = locate_library.freeze
130
+ LIB = load_library(LIBRARY_PATH)
79
131
 
80
132
  VOIDP = Fiddle::TYPE_VOIDP
81
133
  INT32 = Fiddle::TYPE_INT
@@ -86,10 +138,11 @@ module Hide
86
138
  SIGNATURES = {
87
139
  hide_error_message: [[INT32], VOIDP],
88
140
  hide_version: [[], VOIDP],
89
- # A 24-byte struct return is passed through a hidden out-pointer by both
90
- # the SysV and the Windows x64 ABI, so binding it this way is the
91
- # portable spelling; see empty_buffer for the fallback.
92
- hide_buffer_empty: [[VOIDP], VOID],
141
+ # hide_buffer_empty is deliberately not bound. It returns a 24-byte
142
+ # struct by value, which fiddle cannot describe; spelling it as a
143
+ # function taking a hidden out-pointer matches the x86-64 ABIs only
144
+ # (AAPCS64 passes that address in x8, not as the first argument).
145
+ # empty_buffer zero-fills the slot instead, which is all it does.
93
146
  hide_buffer_free: [[VOIDP], VOID],
94
147
  hide_keypair_generate: [[VOIDP, VOIDP], INT32],
95
148
  hide_inspect_key: [[VOIDP, SIZE_T, VOIDP], INT32],
@@ -109,7 +162,7 @@ module Hide
109
162
  hide_verify_message: [[VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP, SIZE_T], INT32],
110
163
  hide_challenge_new: [[VOIDP, UINT64, UINT64, VOIDP], INT32],
111
164
  hide_challenge_answer: [[VOIDP, VOIDP, SIZE_T, VOIDP], INT32],
112
- hide_spent_nonces_new: [[], VOIDP],
165
+ hide_spent_nonces_new: [[VOIDP], VOIDP],
113
166
  hide_spent_nonces_free: [[VOIDP], VOID],
114
167
  hide_challenge_accept: [[VOIDP, VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP, SIZE_T, UINT64], INT32],
115
168
  hide_identity_verify: [[VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP], INT32],
@@ -149,11 +202,13 @@ module Hide
149
202
  Fiddle::Pointer.new(pointer.to_i).to_s.force_encoding(Encoding::UTF_8)
150
203
  end
151
204
 
152
- # Scratch space for one HideBuffer, zeroed the way hide_buffer_empty zeroes it.
205
+ check_version(static_string(call(:hide_version)))
206
+
207
+ # Scratch space for one HideBuffer, zeroed: exactly what hide_buffer_empty
208
+ # returns, without a struct-by-value call fiddle cannot make portably.
153
209
  def self.empty_buffer
154
210
  slot = Fiddle::Pointer.malloc(BUFFER_SIZE, Fiddle::RUBY_FREE)
155
211
  slot[0, BUFFER_SIZE] = "\x00" * BUFFER_SIZE
156
- call(:hide_buffer_empty, slot)
157
212
  slot
158
213
  end
159
214
 
Binary file
data/lib/hide_protocol.rb CHANGED
@@ -57,6 +57,9 @@ module Hide
57
57
  # This challenge was already answered. Almost certainly a replay.
58
58
  class ChallengeReplayedError < Error; end
59
59
 
60
+ # The challenge names an audience this verifier does not answer to.
61
+ class ChallengeAudienceError < Error; end
62
+
60
63
  ERRORS = {
61
64
  Binding::ERR_INVALID_ARGUMENT => InvalidArgumentError,
62
65
  Binding::ERR_WRONG_PASSPHRASE => WrongPassphraseError,
@@ -66,7 +69,8 @@ module Hide
66
69
  Binding::ERR_MALFORMED => MalformedError,
67
70
  Binding::ERR_TOO_LARGE => TooLargeError,
68
71
  Binding::ERR_CHALLENGE_EXPIRED => ChallengeExpiredError,
69
- Binding::ERR_CHALLENGE_REPLAYED => ChallengeReplayedError
72
+ Binding::ERR_CHALLENGE_REPLAYED => ChallengeReplayedError,
73
+ Binding::ERR_CHALLENGE_AUDIENCE => ChallengeAudienceError
70
74
  }.freeze
71
75
 
72
76
  class << self
@@ -84,7 +88,7 @@ module Hide
84
88
  :hide_encrypt,
85
89
  buffer_arg(plain), plain.bytesize,
86
90
  joined, recipients.length,
87
- cstring(filename), cstring(media_type),
91
+ cstring(filename, "filename"), cstring(media_type, "media type"),
88
92
  out
89
93
  ))
90
94
  Binding.take(out)
@@ -133,7 +137,7 @@ module Hide
133
137
 
134
138
  def dearmor_public_key(text)
135
139
  out = Binding.empty_buffer
136
- check(Binding.call(:hide_public_key_dearmor, cstring(text.to_s), out))
140
+ check(Binding.call(:hide_public_key_dearmor, cstring(text.to_s, "armored text"), out))
137
141
  Binding.take(out)
138
142
  end
139
143
 
@@ -175,7 +179,7 @@ module Hide
175
179
  out = Binding.empty_buffer
176
180
  check(Binding.call(
177
181
  :hide_challenge_new,
178
- cstring(audience), Integer(now), Integer(valid_for), out
182
+ cstring(audience, "audience"), Integer(now), Integer(valid_for), out
179
183
  ))
180
184
  Binding.take(out)
181
185
  end
@@ -351,7 +355,7 @@ module Hide
351
355
  check(Binding.call(
352
356
  :hide_checkpoint_verify,
353
357
  buffer_arg(bytes), bytes.bytesize,
354
- cstring(origin.to_s),
358
+ cstring(origin.to_s, "origin"),
355
359
  buffer_arg(key), key.bytesize,
356
360
  size, out
357
361
  ))
@@ -370,6 +374,30 @@ module Hide
370
374
  raise ERRORS.fetch(code, Error), message
371
375
  end
372
376
 
377
+ # Text for a `const char *` parameter: NULL for absent, otherwise UTF-8
378
+ # plus a terminator.
379
+ #
380
+ # C strings end at the first NUL, so "longenough\0rest" would reach the
381
+ # core as "longenough" and a key would be sealed under a passphrase the
382
+ # caller never chose. Every text argument, passphrases included, goes
383
+ # through here.
384
+ def cstring(value, what = "text")
385
+ return nil if value.nil?
386
+
387
+ text = value.to_s
388
+ # Binary-tagged text is taken as the UTF-8 bytes it already is; the core
389
+ # refuses it if it is not.
390
+ text = text.encode(Encoding::UTF_8) unless text.encoding == Encoding::BINARY
391
+ bytes = text.b
392
+ if bytes.include?("\x00".b)
393
+ raise InvalidArgumentError, "#{what} must not contain a NUL character"
394
+ end
395
+
396
+ bytes << "\x00".b
397
+ rescue EncodingError
398
+ raise InvalidArgumentError, "#{what} must be text that converts to UTF-8"
399
+ end
400
+
373
401
  private
374
402
 
375
403
  def join_recipients(recipients)
@@ -401,17 +429,20 @@ module Hide
401
429
  def buffer_arg(bytes)
402
430
  bytes.empty? ? Fiddle::Pointer.malloc(1, Fiddle::RUBY_FREE) : bytes
403
431
  end
432
+ end
404
433
 
405
- # NULL for absent, UTF-8 plus a terminator otherwise.
406
- def cstring(value)
407
- return nil if value.nil?
408
-
409
- text = value.to_s
410
- if text.include?("\x00")
411
- raise InvalidArgumentError, "text passed to the core must not contain NUL"
412
- end
434
+ # Refuses every way of making a second Ruby object around one native pointer.
435
+ #
436
+ # A copy would hold the same address, and whichever of the two was closed
437
+ # first would free it under the other: use after free, then a double free.
438
+ # Nothing about a copy can be made safe, so dup, clone and Marshal all raise.
439
+ module Uncopyable
440
+ def initialize_copy(_source)
441
+ raise TypeError, "#{self.class} cannot be copied: it owns a native handle"
442
+ end
413
443
 
414
- "#{text.encode(Encoding::UTF_8)}\x00".force_encoding(Encoding::BINARY)
444
+ def marshal_dump
445
+ raise TypeError, "#{self.class} cannot be serialized: it owns a native handle"
415
446
  end
416
447
  end
417
448
 
@@ -452,6 +483,7 @@ module Hide
452
483
  # exposed to Ruby; there is deliberately no accessor for it.
453
484
  class SigningIdentity
454
485
  include Bytes
486
+ include Uncopyable
455
487
 
456
488
  class << self
457
489
  # Creates an identity and returns the sealed key file to store. One seed
@@ -464,7 +496,7 @@ module Hide
464
496
  end
465
497
 
466
498
  out = Binding.empty_buffer
467
- Hide.check(Binding.call(:hide_identity_generate, "#{text}\x00".b, out))
499
+ Hide.check(Binding.call(:hide_identity_generate, Hide.cstring(text, "passphrase"), out))
468
500
  Binding.take(out)
469
501
  end
470
502
 
@@ -479,7 +511,7 @@ module Hide
479
511
  :hide_signing_identity_open,
480
512
  bytes.empty? ? Fiddle::Pointer.malloc(1, Fiddle::RUBY_FREE) : bytes,
481
513
  bytes.bytesize,
482
- passphrase.nil? ? nil : "#{passphrase}\x00".b,
514
+ Hide.cstring(passphrase, "passphrase"),
483
515
  handle
484
516
  ))
485
517
  identity = new(handle[0, Binding::WORD].unpack1(Binding::WORD_PACK))
@@ -493,6 +525,10 @@ module Hide
493
525
  end
494
526
 
495
527
  alias load open
528
+
529
+ # An identity exists only around a pointer the core handed out; wrapping
530
+ # a caller's integer would make a second owner of someone else's memory.
531
+ private :new
496
532
  end
497
533
 
498
534
  def initialize(address)
@@ -568,11 +604,17 @@ module Hide
568
604
  # Replay can only be detected by the verifier: a replayed answer is a genuine
569
605
  # signature and nothing about it is invalid on its own. This must therefore
570
606
  # outlive a single request.
607
+ #
608
+ # One record may be shared between threads: accept holds a per-object lock
609
+ # around the native call, which mutates the record and is not synchronised
610
+ # on the native side. fiddle releases the interpreter lock during the call,
611
+ # so without the lock two threads could both accept the same answer.
571
612
  class SpentNonces
572
613
  include Bytes
614
+ include Uncopyable
573
615
 
574
- def self.open
575
- record = new
616
+ def self.open(audience)
617
+ record = new(audience)
576
618
  return record unless block_given?
577
619
 
578
620
  begin
@@ -582,38 +624,52 @@ module Hide
582
624
  end
583
625
  end
584
626
 
585
- def initialize
586
- pointer = Binding.call(:hide_spent_nonces_new)
627
+ # `audience` is the name this verifier answers to: the same string passed
628
+ # to Hide.new_challenge. An answer minted for a different audience is
629
+ # refused with ChallengeAudienceError, so a challenge relayed from another
630
+ # service cannot be answered here. A record built with an empty audience
631
+ # accepts nothing.
632
+ def initialize(audience)
633
+ pointer = Binding.call(:hide_spent_nonces_new, Hide.cstring(audience, "audience"))
587
634
  raise Error, "could not allocate the nonce record" if pointer.null?
588
635
 
589
636
  @address = pointer.to_i
637
+ @lock = Mutex.new
590
638
  end
591
639
 
592
640
  # Accepts an answer exactly once: raises ChallengeReplayedError the second
593
- # time, ChallengeExpiredError after the window, AuthenticationError if it
594
- # does not verify.
641
+ # time, ChallengeExpiredError after the window, ChallengeAudienceError when
642
+ # the challenge names another audience or this record's audience is empty,
643
+ # and AuthenticationError if it does not verify.
595
644
  def accept(challenge, signature, public_key, now)
596
- raise ClosedKeyError, "this record has been closed" if closed?
597
-
598
645
  chal = binary(challenge, "challenge")
599
646
  sig = binary(signature, "signature")
600
647
  key = binary(public_key, "public key")
601
- Hide.check(Binding.call(
602
- :hide_challenge_accept,
603
- Fiddle::Pointer.new(@address),
604
- arg(chal), chal.bytesize,
605
- arg(sig), sig.bytesize,
606
- arg(key), key.bytesize,
607
- Integer(now)
608
- ))
648
+ at = Integer(now)
649
+ @lock.synchronize do
650
+ raise ClosedKeyError, "this record has been closed" if closed?
651
+
652
+ Hide.check(Binding.call(
653
+ :hide_challenge_accept,
654
+ Fiddle::Pointer.new(@address),
655
+ arg(chal), chal.bytesize,
656
+ arg(sig), sig.bytesize,
657
+ arg(key), key.bytesize,
658
+ at
659
+ ))
660
+ end
609
661
  nil
610
662
  end
611
663
 
612
664
  def close
613
- return if closed?
665
+ # Under the lock, so the record is never freed beneath an accept that
666
+ # another thread is still inside.
667
+ @lock.synchronize do
668
+ next if closed?
614
669
 
615
- Binding.call(:hide_spent_nonces_free, Fiddle::Pointer.new(@address))
616
- @address = nil
670
+ Binding.call(:hide_spent_nonces_free, Fiddle::Pointer.new(@address))
671
+ @address = nil
672
+ end
617
673
  nil
618
674
  end
619
675
 
@@ -625,6 +681,8 @@ module Hide
625
681
  # A secret key. The bytes stay inside the native library and are never
626
682
  # exposed to Ruby; there is deliberately no accessor for them.
627
683
  class SecretKey
684
+ include Uncopyable
685
+
628
686
  class << self
629
687
  def generate(&block)
630
688
  handle = Binding.pointer_slot
@@ -646,7 +704,7 @@ module Hide
646
704
  :hide_secret_key_open,
647
705
  bytes.empty? ? Fiddle::Pointer.malloc(1, Fiddle::RUBY_FREE) : bytes,
648
706
  bytes.bytesize,
649
- passphrase.nil? ? nil : "#{passphrase}\x00".b,
707
+ Hide.cstring(passphrase, "passphrase"),
650
708
  handle
651
709
  ))
652
710
  wrap(handle, &block)
@@ -656,6 +714,10 @@ module Hide
656
714
 
657
715
  private
658
716
 
717
+ # A key exists only around a pointer the core handed out; wrapping a
718
+ # caller's integer would make a second owner of someone else's memory.
719
+ private :new
720
+
659
721
  # With a block the key is always closed, even if the block raises.
660
722
  def wrap(handle, &block)
661
723
  key = new(handle[0, Binding::WORD].unpack1(Binding::WORD_PACK))
@@ -691,7 +753,7 @@ module Hide
691
753
  end
692
754
 
693
755
  out = Binding.empty_buffer
694
- Hide.check(Binding.call(:hide_secret_key_protect, handle, "#{text}\x00".b, out))
756
+ Hide.check(Binding.call(:hide_secret_key_protect, handle, Hide.cstring(text, "passphrase"), out))
695
757
  Binding.take(out)
696
758
  end
697
759