sixarm_ruby_xid 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4eb5fb0a077dc0f211a20f10c65c65b5f6a7745e
-  data.tar.gz: d2f7fb50c2a0363c308e31d054338ccfc696fdb6
+  metadata.gz: 7a6cd306d753aa53345165bc0fe03abdb5f32038
+  data.tar.gz: 2ddb1e1f1c2d577434669f2d2b1f5c77b36b018e
 SHA512:
-  metadata.gz: 63f43cd85cf5c7ae3a0a53dad2605494dece765a44bbaab1c0b5116d7dcf1a52360fa2d24c1ae20223a64962bafdde768cae64ab50b064ce80e5a0eb5a95437b
-  data.tar.gz: 7bbbf160d7499466bad2e12e4e52fc73a7be39184c884732a7c653797fd85263bb98126bef6a736723d60ea464f9b22fe7d268d5571bd7af5701b1fb32a89ac7
+  metadata.gz: 5d2072630d29de5205328f7e571a7f5dce56a47b85b001da782f8faaeaf75bca1bfe5366dbfe878b2dab033447f02c0326d0221f1aba8d2275231900b4825122
+  data.tar.gz: 04e1403dc19e8065b7dd6c237619cbed0ef7714f4db1aaaeed900a8b3cd7b72601aef4870bb4c4fb356038c35838738de34aca3fdff3994704e87a30fcef7064

data/README.md

@@ -1,4 +1,4 @@
-# SixArm.com » Ruby » <br> SecureToken to generate a random string
+# SixArm.com » Ruby » <br> XID excellent identifier
 
 [![Code Climate](https://codeclimate.com/github/SixArm/xid.png)](https://codeclimate.com/github/SixArm/xid)
 [![Build Status](https://travis-ci.org/SixArm/xid.png)](https://travis-ci.org/SixArm/xid)
@@ -11,28 +11,20 @@
 
 ## Introduction
 
-XID is a secure identifier string. It is much like a UUID (Universally Unique Identifier). The XID has a more-specific specfication, faster creation algorithms, faster comparison algorithms, and is fully translatable to a UUID if necessary.
-
-XID specification:
-
-  * 128 bit.
-  * Completely random.
-  * Generated with a secure random generator.
-  * The string representation is entirely hexidecimal: digits 0-9 and lowercase a-f.
-
-Comparison with UUID:
-
-  * The XID and UUID are both 128 bit.
-  * The XID has one form. The UUID has multiple forms, called variants and versions.
-  * The XID is completely random. The UUID may have non-random pieces, such as a MAC sequence, and a fixed bit for the variant and version.
-  * The XID specification requires the use of a secure random generator. The UUID has no guarantee.
-  * The XID uses digits 0-9 and lowecase a-f. The UUID canoncical form uses dashes to separate sequencies, and can use uppercase or lowercase.
+XID is an excellent identifier. The XID much like a UUID (Universally Unique Identifier) or GUID (Globally Unique Identifer).
 
 Example:
 
     XID.new
     #=> "90f44e35a062479289ff75ab2abc0ed3"
 
+What makes the XID excellent: a streamlined specfication, stronger security, speedier algorithms, and simple string comparisons.
+
+XID specification:
+
+  * 128 bit.
+  * Completely random and generated with a secure random generator.
+  * The string representation is entirely hexidecimal: digits 0-9 and lowercase a-f.
 
 For docs go to <http://sixarm.com/sixarm_ruby_xid/doc>
 
@@ -69,9 +61,62 @@ To install with high security:
 
 ## Details
 
-This uses Ruby's SecureRandom methods for strong security.
+Methods:
+
+  * `XID.new`: generate a new XID string
+  * `XID#digest`: return a SHA256 digest as a 64-character string
+
+Notes:
+
+  * XID uses Ruby's SecureRandom methods for strong security.
+  * An XID is a Ruby string, so you can do any string methods on it.
+
+
+## UUID comparison
+
+The XID is much like a UUID:
+
+  * The XID and UUID are both 128 bit.
+  * The XID has one form. The UUID has multiple forms, known as variants and versions.
+  * The XID is completely random. The UUID may have non-random pieces, such as a MAC sequence, and a fixed bit for the variant and version.
+  * The XID specification requires the use of a secure random generator. The UUID has no guarantee, and some forms use predicatable sequences.
+  * The XID uses digits 0-9 and lowecase a-f. The UUID canoncical form uses dashes to separate sequencies, and may use uppercase or lowercase.
+
+To format an XID in the style of a UUID canonical representation:
+
+    xid = "90f44e35a062479289ff75ab2abc0ed3"
+    xid.sub(/(.{8})(.{4})(.{4})(.{16})/,"#$1-#$2-#$3-#$4")
+    #=> "90f44e35-a062-4792-89ff75ab2abc0ed3"
+
+Note: the result string is formatted like a UUID, but is not guaranteed to be valid UUID. This is because the XID is random, whereas the UUID specification requires a specific bit that indicates the UUID is random.
+
+To format a UUID in the style of an XID:
+
+    uuid = "14fFE137-2DB2-4A37-A2A4-A04DB1C756CA"
+    uuid.gsub(/-/,"").downcase
+    #=> ""14f7e1372db24a37a2a4a04db1c756ca"
+
+Note: the result string is formatted like a XID, but is not a valid XID. This is because there's no guarantee that the UUID was randomly generated using a secure random generator, and also because the UUID-4 specification requires a random UUID to set the third section's first digit to 4.
+
+
+## Unix tooling
+
+To generate an XID on a typical Unix system, one way is the hexdump command:
+
+    $ hexdump -n 16 -v -e '16/1 "%02x" "\n"' /dev/random
+    b29dd48b7040f788fd926ebf1f4eddd0
+
+To digest an XID by using SHA256:
+
+    $ echo -n "b29dd48b7040f788fd926ebf1f4eddd0" | shasum -a 256
+    afdfb0400e479285040e541ee87d9227d5731a7232ecfa5a07074ee0ad171c64
+
+
+## Database tooling
+
+To store an XID in a database, one way is using a string field that is 32 characters long.
 
-SecureToken is a string, so you can do any string methods on it.
+Some databases have specialize fields for 128 bit values, such as PostgreSQL and its UUID extensions. PostgreSQL states that a UUID field will accept a string that is lowercase and that omits dashes. PostgreSQL does not do any validity-checking on the UUID value. Thus it is viable to store an XID in a UUID field. Our team has a goal to create a PostgreSQL extension for the XID data type.
 
 
 ## Changes

data/lib/sixarm_ruby_xid.rb

@@ -4,6 +4,7 @@ Please see README
 =end
 
 require 'securerandom'
+require 'digest/sha2'
 
 class XID < String
 
@@ -11,4 +12,8 @@ class XID < String
     super(SecureRandom.hex(16))
   end
 
+  def digest
+    Digest::SHA256.new.update(self).to_s
+  end
+
 end

data/test/sixarm_ruby_xid_test.rb

@@ -3,7 +3,7 @@ require 'minitest/autorun'
 Minitest::Test ||= MiniTest::Unit::TestCase
 require 'simplecov'
 SimpleCov.start
-require 'xid'
+require 'sixarm_ruby_xid'
 
 describe XID do
 
@@ -11,12 +11,12 @@ describe XID do
 
     it "is a string with the correct length and characters" do
       xid = XID.new
-      xid.must_match /\A[0-9a-z]{32}\Z/
+      xid.must_match /\A[0-9a-f]{32}\z/
     end
 
     it "is always different" do
       seen = Set.new
-      999999.times.each{
+      99999.times.each{
         xid = XID.new
         seen.include?(xid).must_equal false
         seen.add(xid)
@@ -25,4 +25,13 @@ describe XID do
 
   end
 
+  describe "#digest" do
+
+    it "digests" do
+      xid  = XID.new
+      xid.digest.must_match /\A[0-9a-f]{64}\z/
+    end
+
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sixarm_ruby_xid
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - SixArm
@@ -30,10 +30,10 @@ cert_chain:
   sWRVEyjnjnNuAeLP9zv43IDXjS22L2efhap7IOinYjcecpfXJgQaU+6BFAY4sdkQ
   S1STYSfs3qySBxxAeEyZTw==
   -----END CERTIFICATE-----
-date: 2015-02-11 00:00:00.000000000 Z
+date: 2015-02-12 00:00:00.000000000 Z
 dependencies: []
-description: XID.new generates a new string suitable for security, authentication,
-  tracking, etc.
+description: XID generates a new string suitable for security, authentication, tracking,
+  etc.
 email: sixarm@sixarm.com
 executables: []
 extensions: []
@@ -73,7 +73,7 @@ rubyforge_project:
 rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
-summary: SixArm.com » Ruby » XID secure identifier
+summary: SixArm.com » Ruby » XID excellent identifier
 test_files:
 - test/sixarm_ruby_xid_test.rb
 has_rdoc: true