rnp 0.1.0 → 0.2.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (47) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +12 -0
  3. data/.rspec +2 -0
  4. data/.travis.yml +5 -0
  5. data/CODE_OF_CONDUCT.md +74 -0
  6. data/Gemfile +4 -0
  7. data/Gemfile.lock +26 -0
  8. data/README.adoc +208 -0
  9. data/Rakefile +6 -0
  10. data/Use_Cases.adoc +119 -0
  11. data/bin/console +14 -0
  12. data/bin/setup +8 -0
  13. data/example-usage.rb +766 -0
  14. data/examples/highlevel/decrypt_mem.rb +44 -0
  15. data/examples/highlevel/encrypt_mem.rb +46 -0
  16. data/examples/lowlevel/decrypt_file.rb +76 -0
  17. data/examples/lowlevel/decrypt_mem.rb +80 -0
  18. data/examples/lowlevel/encrypt_file.rb +68 -0
  19. data/examples/lowlevel/encrypt_mem.rb +75 -0
  20. data/examples/lowlevel/load_pubkey.rb +118 -0
  21. data/examples/lowlevel/print_keyring_file.rb +68 -0
  22. data/examples/lowlevel/print_keyring_mem.rb +96 -0
  23. data/examples/lowlevel/sign_file.rb +104 -0
  24. data/examples/lowlevel/sign_mem.rb +96 -0
  25. data/examples/lowlevel/verify_file.rb +55 -0
  26. data/examples/lowlevel/verify_mem.rb +61 -0
  27. data/lib/rnp/highlevel/constants.rb +96 -0
  28. data/lib/rnp/highlevel/keyring.rb +259 -0
  29. data/lib/rnp/highlevel/publickey.rb +150 -0
  30. data/lib/rnp/highlevel/secretkey.rb +318 -0
  31. data/lib/rnp/highlevel/utils.rb +119 -0
  32. data/lib/rnp/highlevel.rb +5 -0
  33. data/lib/rnp/lowlevel/constants.rb +11 -0
  34. data/lib/rnp/lowlevel/dynarray.rb +129 -0
  35. data/lib/rnp/lowlevel/enums.rb +243 -0
  36. data/lib/rnp/lowlevel/libc.rb +28 -0
  37. data/lib/rnp/lowlevel/libopenssl.rb +15 -0
  38. data/lib/rnp/lowlevel/librnp.rb +213 -0
  39. data/lib/rnp/lowlevel/structs.rb +541 -0
  40. data/lib/rnp/lowlevel/utils.rb +25 -0
  41. data/lib/rnp/lowlevel.rb +6 -0
  42. data/lib/rnp/version.rb +3 -0
  43. data/lib/rnp.rb +5 -0
  44. data/rnp/lib/rnp.rb +5 -0
  45. data/rnp/spec/rnp_spec.rb +11 -0
  46. data/rnp.gemspec +35 -0
  47. metadata +82 -9
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: c9980cde675c031e01f580be9d5873274daea7a2
4
- data.tar.gz: dfab38eccd4f2b3ef136642274e38a080a659c85
3
+ metadata.gz: 5d997fdd65d50e439f931a6afc105659dd9bfbbd
4
+ data.tar.gz: ab48ba3cc08fc0602681c2a4a984e0268ce86470
5
5
  SHA512:
6
- metadata.gz: 7c7eb7dd5b2609e2ede4b18ec79391a1044c88c4ab21cb06927a2328da5f5a71094072e033bae1e85a0e9bcfa5fafd5206451c3cb76d2f15d93ac6144702da84
7
- data.tar.gz: 1bb2d71b397e274239ec693c4991e16bb5fc92a4ffb60e287273b3ee9d146122731701d1ec03fa194d227d3a1583c2513fb6e4439e0fb5c026b488843528c85e
6
+ metadata.gz: d8dd13a749c5a8a198237b190162152b82adad829dd84543999fef314243feb40a15a551ad215bc6919ff87affc48b165f7783df93d9a28d4d00d6128b897d5c
7
+ data.tar.gz: 5d9638146fe1a5b9966cdec3bc6fa0c5f3870526c3bff347aa0c07f62fdec63b5419de06a01dcb44f774e19a04e7fffbded61d332b365375fc7e3019fc04a8f2
data/.gitignore ADDED
@@ -0,0 +1,12 @@
1
+ /.bundle/
2
+ /.yardoc
3
+ /Gemfile.lock
4
+ /_yardoc/
5
+ /coverage/
6
+ /doc/
7
+ /pkg/
8
+ /spec/reports/
9
+ /tmp/
10
+
11
+ # rspec failure tracking
12
+ .rspec_status
data/.rspec ADDED
@@ -0,0 +1,2 @@
1
+ --format documentation
2
+ --color
data/.travis.yml ADDED
@@ -0,0 +1,5 @@
1
+ sudo: false
2
+ language: ruby
3
+ rvm:
4
+ - 2.3.3
5
+ before_install: gem install bundler -v 1.14.6
@@ -0,0 +1,74 @@
1
+ # Contributor Covenant Code of Conduct
2
+
3
+ ## Our Pledge
4
+
5
+ In the interest of fostering an open and welcoming environment, we as
6
+ contributors and maintainers pledge to making participation in our project and
7
+ our community a harassment-free experience for everyone, regardless of age, body
8
+ size, disability, ethnicity, gender identity and expression, level of experience,
9
+ nationality, personal appearance, race, religion, or sexual identity and
10
+ orientation.
11
+
12
+ ## Our Standards
13
+
14
+ Examples of behavior that contributes to creating a positive environment
15
+ include:
16
+
17
+ * Using welcoming and inclusive language
18
+ * Being respectful of differing viewpoints and experiences
19
+ * Gracefully accepting constructive criticism
20
+ * Focusing on what is best for the community
21
+ * Showing empathy towards other community members
22
+
23
+ Examples of unacceptable behavior by participants include:
24
+
25
+ * The use of sexualized language or imagery and unwelcome sexual attention or
26
+ advances
27
+ * Trolling, insulting/derogatory comments, and personal or political attacks
28
+ * Public or private harassment
29
+ * Publishing others' private information, such as a physical or electronic
30
+ address, without explicit permission
31
+ * Other conduct which could reasonably be considered inappropriate in a
32
+ professional setting
33
+
34
+ ## Our Responsibilities
35
+
36
+ Project maintainers are responsible for clarifying the standards of acceptable
37
+ behavior and are expected to take appropriate and fair corrective action in
38
+ response to any instances of unacceptable behavior.
39
+
40
+ Project maintainers have the right and responsibility to remove, edit, or
41
+ reject comments, commits, code, wiki edits, issues, and other contributions
42
+ that are not aligned to this Code of Conduct, or to ban temporarily or
43
+ permanently any contributor for other behaviors that they deem inappropriate,
44
+ threatening, offensive, or harmful.
45
+
46
+ ## Scope
47
+
48
+ This Code of Conduct applies both within project spaces and in public spaces
49
+ when an individual is representing the project or its community. Examples of
50
+ representing a project or community include using an official project e-mail
51
+ address, posting via an official social media account, or acting as an appointed
52
+ representative at an online or offline event. Representation of a project may be
53
+ further defined and clarified by project maintainers.
54
+
55
+ ## Enforcement
56
+
57
+ Instances of abusive, harassing, or otherwise unacceptable behavior may be
58
+ reported by contacting the project team at ronald.tse@ribose.com. All
59
+ complaints will be reviewed and investigated and will result in a response that
60
+ is deemed necessary and appropriate to the circumstances. The project team is
61
+ obligated to maintain confidentiality with regard to the reporter of an incident.
62
+ Further details of specific enforcement policies may be posted separately.
63
+
64
+ Project maintainers who do not follow or enforce the Code of Conduct in good
65
+ faith may face temporary or permanent repercussions as determined by other
66
+ members of the project's leadership.
67
+
68
+ ## Attribution
69
+
70
+ This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71
+ available at [http://contributor-covenant.org/version/1/4][version]
72
+
73
+ [homepage]: http://contributor-covenant.org
74
+ [version]: http://contributor-covenant.org/version/1/4/
data/Gemfile ADDED
@@ -0,0 +1,4 @@
1
+ source 'https://rubygems.org'
2
+
3
+ # Specify your gem's dependencies in rnp.gemspec
4
+ gemspec
data/Gemfile.lock ADDED
@@ -0,0 +1,26 @@
1
+ GEM
2
+ remote: https://rubygems.org/
3
+ specs:
4
+ diff-lcs (1.3)
5
+ rspec (3.5.0)
6
+ rspec-core (~> 3.5.0)
7
+ rspec-expectations (~> 3.5.0)
8
+ rspec-mocks (~> 3.5.0)
9
+ rspec-core (3.5.4)
10
+ rspec-support (~> 3.5.0)
11
+ rspec-expectations (3.5.0)
12
+ diff-lcs (>= 1.2.0, < 2.0)
13
+ rspec-support (~> 3.5.0)
14
+ rspec-mocks (3.5.0)
15
+ diff-lcs (>= 1.2.0, < 2.0)
16
+ rspec-support (~> 3.5.0)
17
+ rspec-support (3.5.0)
18
+
19
+ PLATFORMS
20
+ ruby
21
+
22
+ DEPENDENCIES
23
+ rspec
24
+
25
+ BUNDLED WITH
26
+ 1.13.7
data/README.adoc ADDED
@@ -0,0 +1,208 @@
1
+ = Ruby RNP bindings
2
+
3
+ The `rnp` gem provides Ruby bindings to the
4
+ https://github.com/riboseinc/rnp[librnp OpenPGP library].
5
+
6
+ == Installation
7
+
8
+ Add this line to your application's Gemfile:
9
+
10
+ [source,ruby]
11
+ ----
12
+ gem 'rnp'
13
+ ----
14
+
15
+ [source,ruby]
16
+ ----
17
+ bundle
18
+ ----
19
+
20
+ Or install it yourself as:
21
+
22
+ [source,ruby]
23
+ ----
24
+ gem install rnp
25
+ ----
26
+
27
+
28
+ == Overview
29
+
30
+ The code is split in to two main modules.
31
+
32
+ * low-level binding code is in the module `LibRNP` (`lib/rnp/lowlevel/`).
33
+
34
+ * high-level wrapper is in the module `RNP` (`lib/rnp/highlevel/`).
35
+
36
+
37
+ == Usage
38
+
39
+ === Loading Keys
40
+
41
+ [source,ruby]
42
+ ----
43
+ require 'rnp'
44
+ keyring = RNP::Keyring.load(File.read('spec/keys/seckey_sign_only.asc'))
45
+ # load some more keys in to this keyring
46
+ keyring.add(File.read('spec/keys/pubkey_sign_only.asc'))
47
+ # access public keys
48
+ keyring.public_keys
49
+ # access secret keys
50
+ keyring.secret_keys
51
+ ----
52
+
53
+ === Generating Keys
54
+
55
+ [source,ruby]
56
+ ----
57
+ key = RNP::SecretKey.generate('mypassphrase', {
58
+ key_length: 1024,
59
+ public_key_algorithm: RNP::PublicKeyAlgorithm::RSA,
60
+ algorithm_params: {e: 65537},
61
+ hash_algorithm: RNP::HashAlgorithm::SHA1,
62
+ symmetric_key_algorithm: RNP::SymmetricKeyAlgorithm::CAST5
63
+ })
64
+
65
+ # Note that the passphrase of the parent key will be used, so pass an
66
+ # empty string here.
67
+
68
+ # Also note that we are only providing the key_Length option here, so
69
+ # defaults will be used.
70
+ subkey = RNP::SecretKey.generate('', { key_length: 1024 })
71
+ key.add_subkey(subkey)
72
+ ----
73
+
74
+ === Unlocking Secret Keys
75
+
76
+ Most secret keys are encrypted and require a passphrase for certain
77
+ operations. This can be provided during keyring loading by providing a
78
+ block, like so:
79
+
80
+ [source,ruby]
81
+ ----
82
+ keyring = RNP::Keyring.load(File.read('spec/keys/seckey_sign_only.asc')) {|seckey|
83
+ # This block will be called for each encrypted key that is found
84
+ # during parsing.
85
+ # An instance of SecretKey is passed.
86
+ print "Enter passphrase for key #{seckey.key_id_hex}: "
87
+ $stdin.gets.chomp
88
+ }
89
+ ----
90
+
91
+ The above method will result in fully unlocked SecretKey instances that
92
+ have `@passphrase` set correctly (and have decrypted key material in
93
+ `@mpi`).
94
+
95
+ Alternatively, you can manually set `@passphrase` on a secret key to
96
+ enable operations that require a passphrase. In this case, the key
97
+ material in `@mpi` will have nil values, but the encrypted key material
98
+ will be available in `@raw_subpackets` and used for operations requiring
99
+ it.
100
+
101
+ [source,ruby]
102
+ ----
103
+ secret_key = keyring.secret_keys[0]
104
+ secret_key.passphrase = 'password'
105
+ # decrypt, sign, etc.
106
+ ----
107
+
108
+ === Encryption and Decryption
109
+
110
+ Encryption is done with a `PublicKey`.
111
+
112
+ [source,ruby]
113
+ ----
114
+ public_key = keyring.public_keys[0]
115
+ encrypted_message = public_key.encrypt('Test')
116
+ ----
117
+
118
+ Decryption is done with the corresponding `SecretKey`.
119
+
120
+ [source,ruby]
121
+ ----
122
+ # find the secret key that corresponds with the above public key
123
+ secret_key = keyring.secret_keys.find { |key|
124
+ key.key_id_hex == public_key.key_id_hex
125
+ }
126
+
127
+ # decrypt (note that secret_key.passphrase must be correctly set, if
128
+ # required)
129
+ secret_key.decrypt(encrypted_message)
130
+ ----
131
+
132
+ === Signing and Verifying
133
+
134
+ Signing is done with a SecretKey, like so:
135
+
136
+ [source,ruby]
137
+ ----
138
+ signed_message = secret_key.sign('My Data')
139
+ ----
140
+
141
+ Verification is done with a Keyring.
142
+
143
+ [source,ruby]
144
+ ----
145
+ # returns true or false
146
+ keyring.verify(signed_message)
147
+ ----
148
+
149
+ === Exporting
150
+
151
+ Keys can be exported by using the Keyring::export function.
152
+
153
+ [source,ruby]
154
+ ----
155
+ # this will output an ASCII-armored private key
156
+ puts keyring.export(secret_key)
157
+
158
+ # a secret key also has a public key inside
159
+ puts keyring.export(secret_key.public_key)
160
+ ----
161
+
162
+ == Documentation
163
+
164
+ Run "yardoc" to generate documentation in the `doc/` directory.
165
+
166
+ [source,sh]
167
+ ----
168
+ $ yardoc
169
+ ----
170
+
171
+
172
+ == Tests
173
+
174
+ Run "rake" or "rspec" to run all tests in the `spec/` directory.
175
+
176
+ [source,sh]
177
+ ----
178
+ $ rake
179
+ ----
180
+
181
+ **Note**: Some of the tests generate keys and thus will consume entropy.
182
+
183
+ == Examples
184
+
185
+ There are examples demonstrating the use of both the low-level and
186
+ high-level interfaces in `examples/`.
187
+
188
+
189
+ == Development
190
+
191
+ After checking out the repo, run `bin/setup` to install dependencies.
192
+ Then, run `rake spec` to run the tests. You can also run `bin/console`
193
+ for an interactive prompt that will allow you to experiment.
194
+
195
+ To install this gem onto your local machine, run `bundle exec rake
196
+ install`. To release a new version, update the version number in
197
+ `version.rb`, and then run `bundle exec rake release`, which will create
198
+ a git tag for the version, push git commits and tags, and push the
199
+ `.gem` file to https://rubygems.org(rubygems.org).
200
+
201
+ == Contributing
202
+
203
+ Bug reports and pull requests are welcome on GitHub at
204
+ https://github.com/riboseinc/ruby-rnp. This project is intended to be a
205
+ safe, welcoming space for collaboration, and contributors are expected
206
+ to adhere to the http://contributor-covenant.org[Contributor Covenant]
207
+ code of conduct.
208
+
data/Rakefile ADDED
@@ -0,0 +1,6 @@
1
+ require "bundler/gem_tasks"
2
+ require "rspec/core/rake_task"
3
+
4
+ RSpec::Core::RakeTask.new(:spec)
5
+
6
+ task :default => :spec
data/Use_Cases.adoc ADDED
@@ -0,0 +1,119 @@
1
+ = Use Cases
2
+
3
+ 1. Generate or import a secret key, and read its properties:
4
+
5
+ [source,ruby]
6
+ ----
7
+ key = Rnp::SecretKey.new
8
+ key.generate(
9
+ key_length: Integer,
10
+ public_key_algorithm: PublicKeyAlgorithm::RSA,
11
+ algorithm_params: { e: Integer }, # content is public_key_algorithm specific
12
+ userid: String || Userid,
13
+ hash_algorithm: HashAlgorithm,
14
+ symmetric_key_algorithm: SymmetricKeyAlgorithm
15
+ )
16
+
17
+ key.version # must be 4
18
+ key.userids # => [] with its User ID packets
19
+ key.userid_signatures # => [] of Signature Packets of its User ID packets
20
+ key.passphrase # sets the passphrase if non-blank
21
+ key.key_id # => key id of key
22
+ key.fingerprint # => fingerprint of key
23
+ key.key_length # length of key
24
+ ----
25
+
26
+
27
+ 2. (Generate and) Add a Subkey to a secret key:
28
+
29
+ [source,ruby]
30
+ ----
31
+ subkey = SecretSubkeyPacketV4.new
32
+ subkey.generate(
33
+ key_length: Integer,
34
+ public_key_algorithm: PublicKeyAlgorithm,
35
+ algorithm_params: { e: Integer }, # content is public_key_algorithm specific
36
+ userid: String || Userid,
37
+ hash_algorithm: HashAlgorithm,
38
+ symmetric_key_algorithm: SymmetricKeyAlgorithm
39
+ )
40
+
41
+ # Adds subkey to key
42
+ key.add_subkey(subkey)
43
+
44
+ # Or
45
+ subkey_self_sig = Signature.new
46
+ subkey_self_sig.type = SignatureType::SubkeyBinding
47
+ subkey_self_sig.userid = userid
48
+ subkey_self_sig.key_flags = [:encrypt_data, :encrypt_comm, :cert]
49
+ subkey_self_sig.key_expiration_time = DateTime
50
+ subkey_self_sig.creation_time = DateTime
51
+
52
+ ----
53
+
54
+ 3. Sign and verify a PGP message
55
+
56
+ [source,ruby]
57
+ ----
58
+ # Plaintext OpenPGP message
59
+ plaintext_data = File.read("plaintext.txt")
60
+ # automatically creates a LiteralDataPacket inside
61
+ literal_message = LiteralMessage.new(plaintext_data)
62
+
63
+ # Signed OpenPGP message
64
+ message = SignedMessage.new(literal_message)
65
+ message.content = literal_message # alternative to above
66
+ message.key = SecretKey
67
+ message.sign # => SignedMessage [SignaturePacket, LiteralMessage]
68
+
69
+ # Or
70
+ message = OnePassSignedMessage.new(
71
+ signature_type: PositiveCertification,
72
+ hash_algorithm: HashAlgorithm,
73
+ public_key_algorithm: PublicKeyAlgorithm,
74
+ key: SecretKey || PublicKey,
75
+ content: literal_message
76
+ ) # => OnePassSignedMessage is an OpenPgpMessage
77
+
78
+ message.to_s # ASCII armored message
79
+
80
+ # Verifying a PGP message
81
+ public_key.verify(message.signature, message.content)
82
+ secret_key.verify(message.signature, message.content)
83
+ ----
84
+
85
+ 4. Encrypt and decrypt a PGP message
86
+
87
+ [source,ruby]
88
+ ----
89
+ # Encrypted OpenPGP message
90
+ message = EncryptedMessage.new
91
+ message.key = YourPublicKey
92
+ message.public_key_algorithm = PublicKeyAlgorithm
93
+ message.content = plaintext_data
94
+
95
+ # Decrypt OpenPGP message
96
+ message = Rnp::OpenPgpMessage.new
97
+
98
+ # Importing from ASCII armored PGP message
99
+ message.import_ascii(File.read("ascii_armored_pgp_message.txt"))
100
+
101
+ # Importing unarmored content
102
+ message.import_raw(File.read("base64_portion_of_multipart_email.eml"))
103
+
104
+ message.signature # => signature of message in Rnp::Signature
105
+ message.signer_userid # => signer in Rnp::Userid
106
+ message.signed? # => is message signed?
107
+ message.encrypted? # => is message encrypted?
108
+ message.decrypt(key) # => decrypt content of message
109
+ message.content # => decrypted content of message
110
+ ----
111
+
112
+ 5. Packet and Keychain functionalities.
113
+
114
+ While these are not crucial, the Packet stuff will aid a higher level
115
+ implementation.
116
+
117
+ The `rnp_*` functions do support signing / verifying / encrypting /
118
+ decrypting, but for generate key (Case 1) especially for subkeys we need
119
+ to implement the remaining stuff in Ruby.
data/bin/console ADDED
@@ -0,0 +1,14 @@
1
+ #!/usr/bin/env ruby
2
+
3
+ require "bundler/setup"
4
+ require "rnp"
5
+
6
+ # You can add fixtures and/or initialization code here to make experimenting
7
+ # with your gem easier. You can also use a different console, if you like.
8
+
9
+ # (If you use this, don't forget to add pry to your Gemfile!)
10
+ # require "pry"
11
+ # Pry.start
12
+
13
+ require "irb"
14
+ IRB.start(__FILE__)
data/bin/setup ADDED
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+ IFS=$'\n\t'
4
+ set -vx
5
+
6
+ bundle install
7
+
8
+ # Do any other automated setup that you need to do here