README.md in sixarm_ruby_xid-3.0.0 vs README.md in sixarm_ruby_xid-3.1.0
- old
+ new
@@ -1,6 +1,6 @@
-# SixArm.com » Ruby » <br> SecureToken to generate a random string
+# SixArm.com » Ruby » <br> XID excellent identifier
[](https://codeclimate.com/github/SixArm/xid)
[](https://travis-ci.org/SixArm/xid)
* Doc: <http://sixarm.com/sixarm_ruby_xid/doc>
@@ -9,33 +9,25 @@
* Email: Joel Parker Henderson, <joel@sixarm.com>
## 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 is an excellent identifier. The XID much like a UUID (Universally Unique Identifier) or GUID (Globally Unique Identifer).
-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.
-
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>
Want to help? We're happy to get pull requests.
@@ -67,12 +59,65 @@
gem install sixarm_ruby_xid --trust-policy HighSecurity
## Details
-This uses Ruby's SecureRandom methods for strong security.
+Methods:
-SecureToken is a string, so you can do any string methods on it.
+ * `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.
+
+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
* 2015-02-11 3.0.0 Upgrade to XID