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.
- checksums.yaml +4 -4
- data/LICENSE +187 -2
- data/LICENSE-THIRD-PARTY.txt +2511 -0
- data/README.md +66 -11
- data/hide-protocol.gemspec +49 -0
- data/lib/hide_protocol/binding.rb +83 -28
- data/lib/hide_protocol/libhide_ffi.so +0 -0
- data/lib/hide_protocol.rb +99 -37
- metadata +18 -2
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
|
|
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
|
|
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`
|
|
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|
|
|
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
|
|
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
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
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
|
|
10
|
-
#
|
|
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,
|
|
52
|
-
# beside
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
|
|
68
|
+
return File.expand_path(override) if allowed && override && !override.empty?
|
|
62
69
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
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
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
90
|
-
#
|
|
91
|
-
#
|
|
92
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
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
|
-
|
|
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,
|
|
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
|
|
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
|
-
|
|
586
|
-
|
|
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,
|
|
594
|
-
#
|
|
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
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
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
|
-
|
|
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
|
-
|
|
616
|
-
|
|
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
|
|
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,
|
|
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
|
|