ecfg 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0549b12acc4a5455eab8b0ea68f6842f60db304d
-  data.tar.gz: e801695b9fd88dd4c2067ccac42b13da7aa15b33
+  metadata.gz: b986cd82f884b0230545deaa4e4b0fbc218780d1
+  data.tar.gz: 65e45874b83331398fe014724d139e90486eac94
 SHA512:
-  metadata.gz: 43c148d8d42d3e540de16f4cc50d860e90c692cad41b7e10dd1a73873a005315ffdc11f0cbe4c5e659c467d835bf41bdab10e0714875465afc995d32242dd00a
-  data.tar.gz: 6b94f754af12c0457ef1fc690c8c4b97b639a0b17fa774575844f078343c378f536b153ee7c5e5d089b1a55dcb52bde0d6e2c641dff0e6aa35d34c66831d9311
+  metadata.gz: c136457c14a125920ba2c000155e055d26f8cff2c43cd6fe5787d3d805ae5b61709b8d520c993489ae80195cc660cb32e9837d6826c1729a3b0658bf650af498
+  data.tar.gz: 41fed745f643d5c11a65a94cc0b1681fcbd22196bc4761bf684080021771da82eb437efce456e34de54aea236d5570956a0750a3734a40ac87d1a7b5e1561f98

data/lib/ecfg/version.rb

@@ -1,3 +1,3 @@
 module Ecfg
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/man/man1/ecfg-decrypt.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "ECFG\-DECRYPT" "1" "July 2016" "Shopify" "Version 0.3.0"
+.TH "ECFG\-DECRYPT" "1" "July 2016" "Shopify" "Version 0.3.1"
 .
 .SH "NAME"
 \fBecfg\-decrypt\fR \- decrypt an ecfg file

data/man/man1/ecfg-encrypt.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "ECFG\-ENCRYPT" "1" "July 2016" "Shopify" "Version 0.3.0"
+.TH "ECFG\-ENCRYPT" "1" "July 2016" "Shopify" "Version 0.3.1"
 .
 .SH "NAME"
 \fBecfg\-encrypt\fR \- encrypt an ecfg file

data/man/man1/ecfg-keygen.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "ECFG\-KEYGEN" "1" "July 2016" "Shopify" "Version 0.3.0"
+.TH "ECFG\-KEYGEN" "1" "July 2016" "Shopify" "Version 0.3.1"
 .
 .SH "NAME"
 \fBecfg\-keygen\fR \- generate a new keypair for use with ecfg

data/man/man1/ecfg.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "ECFG" "1" "July 2016" "Shopify" "Version 0.3.0"
+.TH "ECFG" "1" "July 2016" "Shopify" "Version 0.3.1"
 .
 .SH "NAME"
 \fBecfg\fR \- manage application secrets via encrypted config

data/man/man5/ecfg.5

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "ECFG" "5" "July 2016" "Shopify" "Version 0.3.0"
+.TH "ECFG" "5" "August 2016" "Shopify" "Version 0.3.1"
 .
 .SH "NAME"
 \fBecfg\fR \- JSON, YAML, or TOML file with asymmetric\-key\-encrypted values
@@ -13,7 +13,7 @@ An \fBecfg\fR file is syntactically a \fBjson\fR, \fByaml\fR, or \fBtoml\fR file
 Each \fBecfg\fR file must have a key at the top level named \fB_public_key\fR\. This implies that the top\-level structure must be a hashmap, not an array\.
 .
 .P
-The \fB_public_key\fR key must have a string value, which is a hex\-encoded 32\-byte (totalling 64 ASCII bytes) public key as generated by \fIecfg\-keygen\fR(1)\.
+The \fB_public_key\fR key must have a string value, which is a hex\-encoded 32\-byte (totalling 64 ASCII bytes) public key as generated by ecfg\-keygen(1)\.
 .
 .P
 By convention, \fB_public_key\fR should be the first key in the file\.
@@ -25,7 +25,7 @@ A value is considered encryptable if:
 It is a string literal (numbers, true, false, null all remain unencrypted);
 .
 .IP "2." 4
-It is not an object key (ie\. not immediately followed by a ":");
+It is not an object key (ie\. not immediately followed by a ":" in JSON, etc\.);
 .
 .IP "3." 4
 Its corresponding object key did not begin with an underscore ("_")\.
@@ -83,5 +83,111 @@ When a value is encrypted, it will be replaced by a relatively long string of th
 .
 .IP "" 0
 .
+.SH "ENCRYPTION ALGORITHMS"
+\fBecfg\fR values are encrypted using a Curve25519 x Salsa20 x Poly1305\-AES public\-key scheme\. This normally implies use of \fBNaCl\fR or \fBlibsodium\fR\.
+.
+.P
+NaCl libraries generally take keys as a sequence of raw bytes, but they\'re embedded in ecfg files as hex\-encoded strings, so we need a routine to convert them:
+.
+.IP "" 4
+.
+.nf
+
+base16_to_raw(key : string) \-> []byte =
+  # convert e\.g\. "1234beef" into [0x12, 0x34, 0xBE, 0xEF] or whatever
+  # the particular NaCl implementation/binding wants\.
+.
+.fi
+.
+.IP "" 0
+.
+.P
+When we write the final encrypted message according to the \fBSECRET SCHEMA\fR section, we need to encode several sequences of raw bytes to base64, with newlines removed:
+.
+.IP "" 4
+.
+.nf
+
+encode(raw : []byte) \-> string =
+  sub("\en", "", base64_encode(raw))
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Building the message given the ciphertext and other input parameters is just string concatenation:
+.
+.IP "" 4
+.
+.nf
+
+format(pub : []byte, nonce : []byte, ct : []byte) \-> string =
+  "EJ[1:" + encode(pub) + ":" + encode(nonce) + ":" + encode(ct) + "]"
+.
+.fi
+.
+.IP "" 0
+.
+.P
+During encryption, an ephemeral keypair is generated and the public key is embedded in the encrypted message\.
+.
+.P
+The final encryption routine combines accepts a plaintext string and a hex\-encoded public key extracted from the input document, returning a formatted \fBecfg\fR message\. The NaCl API calls here are loosely paraphrased\.
+.
+.IP "" 4
+.
+.nf
+
+encrypt(plaintext : string, peer_pub_hex : string) \-> string =
+  peer_pub = base16_to_raw(peer_pub_hex)
+
+  (ephemeral_pub, ephemeral_priv) = NACL\.crypto_box_keypair()
+
+  # 24 random bytes
+  nonce = NACL\.randombytes(NACL\.NONCE_BYTES)
+
+  # API here varies a lot depending on binding\.
+  ciphertext = NACL\.crypto_box(
+    plaintext,
+    ephemeral_priv, peer_pub, nonce
+  )
+
+  format(ephemeral_pub, nonce, ciphertext)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+If multiple values are being encrypted at once, a single ephemeral keypair may be reused\. It may make sense but is by no means necessary to use box precomputation if it\'s available\.
+.
+.SH "DECRYPTION ALGORITHMS"
+To decrypt messages from a document, the caller must first retrieve the private key associated to the public key embedded in the document, then the message must be decomposed into the three encoded values\. This is just the inverse of the process from the encryption section above: remove the "EJ[]" enclosure; split the message on ":", check that the version is 1, then base64\-decode the remaining three components\.
+.
+.P
+Given those three components (\fBpeer_pubkey\fR, \fBnonce\fR, and \fBciphertext\fR), the decryption routine looks like:
+.
+.IP "" 4
+.
+.nf
+
+decrypt(
+  target_privkey : string,
+  peer_pubkey    : []byte,
+  nonce          : []byte,
+  ciphertext     : []byte,
+) \-> string =
+  priv = base16_to_raw(target_privkey)
+
+  # like above, this API varies a lot by binding implementation\.
+  NACL\.crypto_box_open(
+    priv, peer_pubkey, nonce, ciphertext
+  )
+.
+.fi
+.
+.IP "" 0
+.
 .SH "SEE ALSO"
 ecfg(1), ecfg\-encrypt(1), ecfg\-decrypt(1), ecfg\-keygen(1)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecfg
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Burke Libbey
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-19 00:00:00.000000000 Z
+date: 2016-10-07 00:00:00.000000000 Z
 dependencies: []
 description: Secret management by encrypting values in a JSON or YAML file with a
   public/private keypair