rnp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c9980cde675c031e01f580be9d5873274daea7a2
-  data.tar.gz: dfab38eccd4f2b3ef136642274e38a080a659c85
+  metadata.gz: 5d997fdd65d50e439f931a6afc105659dd9bfbbd
+  data.tar.gz: ab48ba3cc08fc0602681c2a4a984e0268ce86470
 SHA512:
-  metadata.gz: 7c7eb7dd5b2609e2ede4b18ec79391a1044c88c4ab21cb06927a2328da5f5a71094072e033bae1e85a0e9bcfa5fafd5206451c3cb76d2f15d93ac6144702da84
-  data.tar.gz: 1bb2d71b397e274239ec693c4991e16bb5fc92a4ffb60e287273b3ee9d146122731701d1ec03fa194d227d3a1583c2513fb6e4439e0fb5c026b488843528c85e
+  metadata.gz: d8dd13a749c5a8a198237b190162152b82adad829dd84543999fef314243feb40a15a551ad215bc6919ff87affc48b165f7783df93d9a28d4d00d6128b897d5c
+  data.tar.gz: 5d9638146fe1a5b9966cdec3bc6fa0c5f3870526c3bff347aa0c07f62fdec63b5419de06a01dcb44f774e19a04e7fffbded61d332b365375fc7e3019fc04a8f2

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.3
+before_install: gem install bundler -v 1.14.6

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at ronald.tse@ribose.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rnp.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,26 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.3)
+    rspec (3.5.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+    rspec-core (3.5.4)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-mocks (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rspec
+
+BUNDLED WITH
+   1.13.7

data/README.adoc

@@ -0,0 +1,208 @@
+= Ruby RNP bindings
+
+The `rnp` gem provides Ruby bindings to the
+https://github.com/riboseinc/rnp[librnp OpenPGP library].
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'rnp'
+----
+
+[source,ruby]
+----
+bundle
+----
+
+Or install it yourself as:
+
+[source,ruby]
+----
+gem install rnp
+----
+
+
+== Overview
+
+The code is split in to two main modules.
+
+* low-level binding code is in the module `LibRNP` (`lib/rnp/lowlevel/`).
+
+* high-level wrapper is in the module `RNP` (`lib/rnp/highlevel/`).
+
+
+== Usage
+
+=== Loading Keys
+
+[source,ruby]
+----
+require 'rnp'
+keyring = RNP::Keyring.load(File.read('spec/keys/seckey_sign_only.asc'))
+# load some more keys in to this keyring
+keyring.add(File.read('spec/keys/pubkey_sign_only.asc'))
+# access public keys
+keyring.public_keys
+# access secret keys
+keyring.secret_keys
+----
+
+=== Generating Keys
+
+[source,ruby]
+----
+key = RNP::SecretKey.generate('mypassphrase', {
+  key_length: 1024,
+  public_key_algorithm: RNP::PublicKeyAlgorithm::RSA,
+  algorithm_params: {e: 65537},
+  hash_algorithm: RNP::HashAlgorithm::SHA1,
+  symmetric_key_algorithm: RNP::SymmetricKeyAlgorithm::CAST5
+})
+
+# Note that the passphrase of the parent key will be used, so pass an
+# empty string here.
+
+# Also note that we are only providing the key_Length option here, so
+# defaults will be used.
+subkey = RNP::SecretKey.generate('', { key_length: 1024 })
+key.add_subkey(subkey)
+----
+
+=== Unlocking Secret Keys
+
+Most secret keys are encrypted and require a passphrase for certain
+operations. This can be provided during keyring loading by providing a
+block, like so:
+
+[source,ruby]
+----
+keyring = RNP::Keyring.load(File.read('spec/keys/seckey_sign_only.asc')) {|seckey|
+    # This block will be called for each encrypted key that is found
+    # during parsing.
+    # An instance of SecretKey is passed.
+    print "Enter passphrase for key #{seckey.key_id_hex}: "
+    $stdin.gets.chomp
+}
+----
+
+The above method will result in fully unlocked SecretKey instances that
+have `@passphrase` set correctly (and have decrypted key material in
+`@mpi`).
+
+Alternatively, you can manually set `@passphrase` on a secret key to
+enable operations that require a passphrase. In this case, the key
+material in `@mpi` will have nil values, but the encrypted key material
+will be available in `@raw_subpackets` and used for operations requiring
+it.
+
+[source,ruby]
+----
+secret_key = keyring.secret_keys[0]
+secret_key.passphrase = 'password'
+# decrypt, sign, etc.
+----
+
+=== Encryption and Decryption
+
+Encryption is done with a `PublicKey`.
+
+[source,ruby]
+----
+public_key = keyring.public_keys[0]
+encrypted_message = public_key.encrypt('Test')
+----
+
+Decryption is done with the corresponding `SecretKey`.
+
+[source,ruby]
+----
+# find the secret key that corresponds with the above public key
+secret_key = keyring.secret_keys.find { |key|
+  key.key_id_hex == public_key.key_id_hex
+}
+
+# decrypt (note that secret_key.passphrase must be correctly set, if
+# required)
+secret_key.decrypt(encrypted_message)
+----
+
+=== Signing and Verifying
+
+Signing is done with a SecretKey, like so:
+
+[source,ruby]
+----
+signed_message = secret_key.sign('My Data')
+----
+
+Verification is done with a Keyring.
+
+[source,ruby]
+----
+# returns true or false
+keyring.verify(signed_message)
+----
+
+=== Exporting
+
+Keys can be exported by using the Keyring::export function.
+
+[source,ruby]
+----
+# this will output an ASCII-armored private key
+puts keyring.export(secret_key)
+
+# a secret key also has a public key inside
+puts keyring.export(secret_key.public_key)
+----
+
+== Documentation
+
+Run "yardoc" to generate documentation in the `doc/` directory.
+
+[source,sh]
+----
+$ yardoc
+----
+
+
+== Tests
+
+Run "rake" or "rspec" to run all tests in the `spec/` directory.
+
+[source,sh]
+----
+$ rake
+----
+
+**Note**: Some of the tests generate keys and thus will consume entropy.
+
+== Examples
+
+There are examples demonstrating the use of both the low-level and
+high-level interfaces in `examples/`.
+
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake spec` to run the tests. You can also run `bin/console`
+for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake
+install`. To release a new version, update the version number in
+`version.rb`, and then run `bundle exec rake release`, which will create
+a git tag for the version, push git commits and tags, and push the
+`.gem` file to https://rubygems.org(rubygems.org).
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/riboseinc/ruby-rnp. This project is intended to be a
+safe, welcoming space for collaboration, and contributors are expected
+to adhere to the http://contributor-covenant.org[Contributor Covenant]
+code of conduct.
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/Use_Cases.adoc

@@ -0,0 +1,119 @@
+= Use Cases
+
+1. Generate or import a secret key, and read its properties:
+
+[source,ruby]
+----
+key = Rnp::SecretKey.new
+key.generate(
+  key_length: Integer,
+  public_key_algorithm: PublicKeyAlgorithm::RSA,
+  algorithm_params: { e: Integer }, # content is public_key_algorithm specific
+  userid: String || Userid,
+  hash_algorithm: HashAlgorithm,
+  symmetric_key_algorithm: SymmetricKeyAlgorithm
+)
+
+key.version # must be 4
+key.userids # => [] with its User ID packets
+key.userid_signatures # => [] of Signature Packets of its User ID packets
+key.passphrase # sets the passphrase if non-blank
+key.key_id # => key id of key
+key.fingerprint # => fingerprint of key
+key.key_length # length of key
+----
+
+
+2. (Generate and) Add a Subkey to a secret key:
+
+[source,ruby]
+----
+subkey = SecretSubkeyPacketV4.new
+subkey.generate(
+  key_length: Integer,
+  public_key_algorithm: PublicKeyAlgorithm,
+  algorithm_params: { e: Integer }, # content is public_key_algorithm specific
+  userid: String || Userid,
+  hash_algorithm: HashAlgorithm,
+  symmetric_key_algorithm: SymmetricKeyAlgorithm
+)
+
+# Adds subkey to key
+key.add_subkey(subkey)
+
+# Or
+subkey_self_sig = Signature.new
+subkey_self_sig.type = SignatureType::SubkeyBinding
+subkey_self_sig.userid = userid
+subkey_self_sig.key_flags = [:encrypt_data, :encrypt_comm, :cert]
+subkey_self_sig.key_expiration_time = DateTime
+subkey_self_sig.creation_time = DateTime
+
+----
+
+3. Sign and verify a PGP message
+
+[source,ruby]
+----
+# Plaintext OpenPGP message
+plaintext_data = File.read("plaintext.txt")
+# automatically creates a LiteralDataPacket inside
+literal_message = LiteralMessage.new(plaintext_data)
+
+# Signed OpenPGP message
+message = SignedMessage.new(literal_message)
+message.content = literal_message # alternative to above
+message.key = SecretKey
+message.sign # => SignedMessage [SignaturePacket, LiteralMessage]
+
+# Or
+message = OnePassSignedMessage.new(
+  signature_type: PositiveCertification,
+  hash_algorithm: HashAlgorithm,
+  public_key_algorithm: PublicKeyAlgorithm,
+  key: SecretKey || PublicKey,
+  content: literal_message
+) # => OnePassSignedMessage is an OpenPgpMessage
+
+message.to_s # ASCII armored message
+
+# Verifying a PGP message
+public_key.verify(message.signature, message.content)
+secret_key.verify(message.signature, message.content)
+----
+
+4. Encrypt and decrypt a PGP message
+
+[source,ruby]
+----
+# Encrypted OpenPGP message
+message = EncryptedMessage.new
+message.key = YourPublicKey
+message.public_key_algorithm = PublicKeyAlgorithm
+message.content = plaintext_data
+
+# Decrypt OpenPGP message
+message = Rnp::OpenPgpMessage.new
+
+# Importing from ASCII armored PGP message
+message.import_ascii(File.read("ascii_armored_pgp_message.txt"))
+
+# Importing unarmored content
+message.import_raw(File.read("base64_portion_of_multipart_email.eml"))
+
+message.signature # => signature of message in Rnp::Signature
+message.signer_userid # => signer in Rnp::Userid
+message.signed? # => is message signed?
+message.encrypted? # => is message encrypted?
+message.decrypt(key) # => decrypt content of message
+message.content # => decrypted content of message
+----
+
+5. Packet and Keychain functionalities.
+
+While these are not crucial, the Packet stuff will aid a higher level
+implementation.
+
+The `rnp_*` functions do support signing / verifying / encrypting /
+decrypting, but for generate key (Case 1) especially for subkeys we need
+to implement the remaining stuff in Ruby.

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rnp"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here