2011 Grant Accomplishment Report

The following two projects have been completed, and their deliverables have been accepted by the grant committee and have been published at their own project sites.

• Ruby reference manual for you, me and everyone
• krypt

 The summary of their final reports is as follows:

Ruby reference manual for you, me and everyone

Yutaka Hara

The PrismDoc project aims to:

• make it easier to translate the Ruby Standard Library reference documentation
• provide a website which displays the translated documentation in English, Japanese and in other languages as an integrated whole
• like php.net!

Demo:
http://blazing-ice-2849.herokuapp.com/
Source code:
https://github.com/yhara/prismdoc/

How is the English documentation handled?

PrismDoc extracts the embedded documentation from Ruby’s source code into its database. Example:
http://blazing-ice-2849.herokuapp.com/en/1.9.3/Array
You can switch between Ruby versions and translation languages with the drop-down menu on the top right. PrismDoc also provides a search function on the top left side of the page.

How is the Japanese documentation handled?

PrismDoc extracts the Japanese documentation from RuReMa (the Japanese Ruby Reference Manual) on BitClust. BitClust is a tool that is used for writing the Japanese version of the Ruby documentation.
http://bugs.ruby-lang.org/projects/rurema

Translations to other languages

PrismDoc provides a web interface for translating the Ruby reference documentation.

Demo (Esperanto):
http://blazing-ice-2849.herokuapp.com/eo/1.9.3

Click on a paragraph to show its translation input form. Currently, anyone can edit the translations.
http://blazing-ice-2849.herokuapp.com/eo/1.9.3/Array

Paragraphs not yet translated are displayed in gray.
http://blazing-ice-2849.herokuapp.com/eo/1.9.3/BasicObject

These per-paragraph translations are shared between Ruby versions. So, for instance, if you already completed the translation of the docs for 1.9.3, then you only need to translate the differences between 1.9.3 and 2.0.0 when 2.0.0 is released.

Current status

I reserved prismdoc.herokuapp.com for project site, but there are few tasks left before starting translation.

https://github.com/yhara/prismdoc/issues

Please email me (yutaka.hara/at/gmail.com) if you are interested in translating the documentation into another language, I will add your language to the system and inform you when the site is ready.

krypt

Martin Boßlet

krypt[1] aims to be a platform- and library-independent extendable cryptography API for Ruby.

While current cryptography is tightly bound to the OpenSSL Toolkit, this has caused continuous headaches for developers where OpenSSL is not a
natural part of their environment.  krypt offers a small provider API for you to plug in whatever library you wish to use.  It no longer matters if you are using a C-based Ruby or JRuby - there’s also a provider API in Java that lets you plug in arbitrary Java cryptography libraries.  It no longer matters if you are on Windows or OS X or Linux, this plugin approach will provide unified access to OS-specific resources such as trusted certificates.

The goal of the grant period was to provide the backbone of the entire library, a modern, fast streaming ASN.1 parsing/encoding framework, that would offer functionality and features not offered elsewhere.  With ASN.1 being the workhorse of any cryptography library, performance and usability were a top priority.  A major goal for the grant period was to run krypt with no restrictions on compatibility or performance on Ruby, JRuby and Rubinius.  krypt runs with no restrictions equally well there. The ASN.1 “Template” DSL uses the powerful features of Ruby itself to provide a DSL that makes adding new, custom ASN.1 data types as simple as merely copy-pasting the ASN.1 definition, parsing and encoding come automatically included [2].

Other accomplishments during the grant period include a proof of concept for the provider API in both C and Java, as well as a proof of concept of a Ruby-only implementation of krypt that will only need to interface with the native provider code via FFI - this makes it even possible to use native C-based OpenSSL from JRuby.

In order to guarantee that krypt would seamlessly integrate on the Ruby platform of your choice, we considered it essential to have a solid, exhaustive set of tests that, in combination with continuous integration on TravisCI, gives us immediate feedback whenever we introduced something incompatible.  While this is good practice in any software project, we believe it’s mandatory for a project in a security context. By measuring the code coverage of our RSpec tests, we continuously aim at reaching the best possible coverage, not only for the sake of code quality in general, but also to detect security flaws such as buffer overflows or integer overflows as soon as possible.  This idea has also made us want to include as many official test vectors as possible[3] in our tests - you never know how some minor change might influence the overall outcome of an algorithm.  In this spirit, valgrind is used to check for memory errors of the C code, and it is planned to use FindBugs for the Java code.
Finally, we also believe the documentation to be a security-critical aspect for a project like krypt and try to give clear and precise examples of common tasks in it.  Mishandling of the API because there are no docs or the docs miss clarity is not only “not cool”, it often has immediate impact on the overall security.

[1] https://github.com/emboss/krypt
[2] https://github.com/emboss/krypt/blob/master/lib/krypt/x509/certificate.rb
[3] https://github.com/emboss/krypt/blob/master/spec/krypt-core/digest/digest_spec.rb