add step-by-step how-to encrypting multiline values

[kBite]

This PR adds documentation regarding #219.

Either it's a workaround or documents unexpected behavior of eyaml. In both cases it adds an example for encrypting multiline values.

[bastelfreak]

@alexjfisher @mmerfort I think you used eyaml in the past, can you review this?

[kBite]

I just noticed, the decrypted file does not have to be valid YAML.

Following my example the resulting file written by Puppet will be indented by 4 whitespaces.

----- BEGIN SSH2 ENCRYPTED PRIVATE KEY ----
-Comment: "dummy-key-hiera-eyaml-issue-rsa-key-20170123"
-P2/56wAAANwAAAA3aWYtbW9kbntzaWdue3JzYS1wa2NzMS1zaGExfSxlbmNyeXB0e3JzYS
-1wa2NzMXYyLW9hZXB9fQAAAARub25lAAAAjQAAAIkAAAAGJQAAAP93ZtrMIRZutZ/SZUyw
-JWwyI4YxNvr5tBt9UnSJ7K0+rQAAAQDohO1ykUahsogS+ymM6o9WEmdROJZpWShCqdv8Dj
-2roQAAAIDG1G8hY90Xlz/YiFhDZLLWAAAAgOzMWTfAlHbJ4AdEhG5uU/EAAACA+1/AlcSr
-QEPM5xLW0unCsQ==
----- END SSH2 ENCRYPTED PRIVATE KEY ----
+    ---- BEGIN SSH2 ENCRYPTED PRIVATE KEY ----
+    Comment: "dummy-key-hiera-eyaml-issue-rsa-key-20170123"
+    P2/56wAAANwAAAA3aWYtbW9kbntzaWdue3JzYS1wa2NzMS1zaGExfSxlbmNyeXB0e3JzYS
+    1wa2NzMXYyLW9hZXB9fQAAAARub25lAAAAjQAAAIkAAAAGJQAAAP93ZtrMIRZutZ/SZUyw
+    JWwyI4YxNvr5tBt9UnSJ7K0+rQAAAQDohO1ykUahsogS+ymM6o9WEmdROJZpWShCqdv8Dj
+    2roQAAAIDG1G8hY90Xlz/YiFhDZLLWAAAAgOzMWTfAlHbJ4AdEhG5uU/EAAACA+1/AlcSr
+    QEPM5xLW0unCsQ==
+    ---- END SSH2 ENCRYPTED PRIVATE KEY ----

When editing it must look like this:

---
accounts::key_sets:
  dummy:
    private: >
DEC(1)::PKCS7[---- BEGIN SSH2 ENCRYPTED PRIVATE KEY ----
Comment: "dummy-key-hiera-eyaml-issue-rsa-key-20170123"
P2/56wAAANwAAAA3aWYtbW9kbntzaWdue3JzYS1wa2NzMS1zaGExfSxlbmNyeXB0e3JzYS
1wa2NzMXYyLW9hZXB9fQAAAARub25lAAAAjQAAAIkAAAAGJQAAAP93ZtrMIRZutZ/SZUyw
JWwyI4YxNvr5tBt9UnSJ7K0+rQAAAQDohO1ykUahsogS+ymM6o9WEmdROJZpWShCqdv8Dj
2roQAAAIDG1G8hY90Xlz/YiFhDZLLWAAAAgOzMWTfAlHbJ4AdEhG5uU/EAAACA+1/AlcSr
QEPM5xLW0unCsQ==
---- END SSH2 ENCRYPTED PRIVATE KEY ----]!

Resulting encrypted file:

---
accounts::key_sets:
  dummy:
    private: >
ENC[PKCS7,MIIDLQYJKoZIhvcNAQcDoIIDHjCCAxoCAQAxggEhMIIBHQIBADAFMAACAQEw
DQYJKoZIhvcNAQEBBQAEggEANz80IZxLeHvj3C8zMSp1fnmL4lls5q1cEuXj
SmuD7/Hb0J33ac7dcBUpvouDtQ0Toez+R3T1OIfce1SCO4jatBxVuJ2fhOKw
wpaV0abhlmiCQu9+gQ6GQepHrGeJ636S6gUS2+f3essPxtyQVYzHh6Is6Ybi
pAneQPzyXWduw9m4rttsUjiSo7gjK0Y/4gt6Vq+QvNtf00VVH+h/QhHj0n4V
NxanFeTOntaSiCGaVYZ9tU4ULSlBzeJBjLtzAG4LGG6eFGyVbXdybHvqGESo
qeHzfqXe1DpRtl+9G6z8QMQsj7KcyaElgGhetRouclv59FVuePYPq29sYee4
TYfjijCCAe4GCSqGSIb3DQEHATAdBglghkgBZQMEASoEEMt1KGs2Sx4+Ty76
kVNM3MWAggHAVBWIXNfo5umnMBnTA20xdT95Ih7qP9y/lMsJ01h6uHE02rBf
VjLc2AfpgLacJ9k04BsSiUeTB3twt+SBKfH0tsDz4fbJMIDav+N7eS4y7Ugk
TWaZ1GP7+JnGzTTuhoZ0kqGmjsMdeDTEiaA5iaJvP9XPpn2f3ZKYrDy7zcsx
FsK6Djs+lIRPBxBv/DHKBYicmBId/pCkh55WHMRUqwqjTherj1lzPd2C4qpq
RWdljLzATJA5JGZyGXlJNoj7wcHgyWkHPFGtmuK8Drk97qpVseVF5KWTQoE5
0/npfNQv5k8mI3NHxCjXnLWPA4J2ffSF+hfjYhuVzZEdNaFYAcZgSCK3vONV
HDGYDYQcunut2CW4x/1t2K91/1FcI0JLTwqZKz/IiC5S9UBncqydggbFKoV1
YmkedrX5iICSLhgiz5Id/M45qejWbmUhCGmqtxv1FWLz8hK90pOx9K1mFhJu
wIJRCdEu5mMYFBLXrf6Oapxh6EyiX2vHR/AnEbvMmEAAYwi6wKmFPtD/IWyJ
J5OGG/gwCNJRWzfBHMNahBuCtOsb3/yfeOkcccgcTxNBsAhsMDGkXo4IJGVf
FJUDpYuSVg==]

Edit with vim to make it valid YAML

---
accounts::key_sets:
  dummy:
    private: >
      ENC[PKCS7,MIIDLQYJKoZIhvcNAQcDoIIDHjCCAxoCAQAxggEhMIIBHQIBADAFMAACAQEw
      DQYJKoZIhvcNAQEBBQAEggEANz80IZxLeHvj3C8zMSp1fnmL4lls5q1cEuXj
      SmuD7/Hb0J33ac7dcBUpvouDtQ0Toez+R3T1OIfce1SCO4jatBxVuJ2fhOKw
      wpaV0abhlmiCQu9+gQ6GQepHrGeJ636S6gUS2+f3essPxtyQVYzHh6Is6Ybi
      pAneQPzyXWduw9m4rttsUjiSo7gjK0Y/4gt6Vq+QvNtf00VVH+h/QhHj0n4V
      NxanFeTOntaSiCGaVYZ9tU4ULSlBzeJBjLtzAG4LGG6eFGyVbXdybHvqGESo
      qeHzfqXe1DpRtl+9G6z8QMQsj7KcyaElgGhetRouclv59FVuePYPq29sYee4
      TYfjijCCAe4GCSqGSIb3DQEHATAdBglghkgBZQMEASoEEMt1KGs2Sx4+Ty76
      kVNM3MWAggHAVBWIXNfo5umnMBnTA20xdT95Ih7qP9y/lMsJ01h6uHE02rBf
      VjLc2AfpgLacJ9k04BsSiUeTB3twt+SBKfH0tsDz4fbJMIDav+N7eS4y7Ugk
      TWaZ1GP7+JnGzTTuhoZ0kqGmjsMdeDTEiaA5iaJvP9XPpn2f3ZKYrDy7zcsx
      FsK6Djs+lIRPBxBv/DHKBYicmBId/pCkh55WHMRUqwqjTherj1lzPd2C4qpq
      RWdljLzATJA5JGZyGXlJNoj7wcHgyWkHPFGtmuK8Drk97qpVseVF5KWTQoE5
      0/npfNQv5k8mI3NHxCjXnLWPA4J2ffSF+hfjYhuVzZEdNaFYAcZgSCK3vONV
      HDGYDYQcunut2CW4x/1t2K91/1FcI0JLTwqZKz/IiC5S9UBncqydggbFKoV1
      YmkedrX5iICSLhgiz5Id/M45qejWbmUhCGmqtxv1FWLz8hK90pOx9K1mFhJu
      wIJRCdEu5mMYFBLXrf6Oapxh6EyiX2vHR/AnEbvMmEAAYwi6wKmFPtD/IWyJ
      J5OGG/gwCNJRWzfBHMNahBuCtOsb3/yfeOkcccgcTxNBsAhsMDGkXo4IJGVf
      FJUDpYuSVg==]

Decrypts to ...

---
accounts::key_sets:
  dummy:
    private: |
  ---- BEGIN SSH2 ENCRYPTED PRIVATE KEY ----
  Comment: "dummy-key-hiera-eyaml-issue-rsa-key-20170123"
  P2/56wAAANwAAAA3aWYtbW9kbntzaWdue3JzYS1wa2NzMS1zaGExfSxlbmNyeXB0e3JzYS
  1wa2NzMXYyLW9hZXB9fQAAAARub25lAAAAjQAAAIkAAAAGJQAAAP93ZtrMIRZutZ/SZUyw
  JWwyI4YxNvr5tBt9UnSJ7K0+rQAAAQDohO1ykUahsogS+ymM6o9WEmdROJZpWShCqdv8Dj
  2roQAAAIDG1G8hY90Xlz/YiFhDZLLWAAAAgOzMWTfAlHbJ4AdEhG5uU/EAAACA+1/AlcSr
  QEPM5xLW0unCsQ==
  ---- END SSH2 ENCRYPTED PRIVATE KEY ----

... which does not result in an indented file written by Puppet.

When editing the now valid YAML file again it will look like

---
accounts::key_sets:
  dummy:
    private: >
      DEC(1)::PKCS7[---- BEGIN SSH2 ENCRYPTED PRIVATE KEY ----
Comment: "dummy-key-hiera-eyaml-issue-rsa-key-20170123"
P2/56wAAANwAAAA3aWYtbW9kbntzaWdue3JzYS1wa2NzMS1zaGExfSxlbmNyeXB0e3JzYS
1wa2NzMXYyLW9hZXB9fQAAAARub25lAAAAjQAAAIkAAAAGJQAAAP93ZtrMIRZutZ/SZUyw
JWwyI4YxNvr5tBt9UnSJ7K0+rQAAAQDohO1ykUahsogS+ymM6o9WEmdROJZpWShCqdv8Dj
2roQAAAIDG1G8hY90Xlz/YiFhDZLLWAAAAgOzMWTfAlHbJ4AdEhG5uU/EAAACA+1/AlcSr
QEPM5xLW0unCsQ==
---- END SSH2 ENCRYPTED PRIVATE KEY ----]!

[kBite]

Following the auto-indentation of vim I saved from edit with indented `DEC::PKCS7[' ...

---
accounts::key_sets:
  dummy:
    private: >
      DEC(1)::PKCS7[---- BEGIN SSH2 ENCRYPTED PRIVATE KEY ----
Comment: "dummy-key-hiera-eyaml-issue-rsa-key-20170123"
P2/56wAAANwAAAA3aWYtbW9kbntzaWdue3JzYS1wa2NzMS1zaGExfSxlbmNyeXB0e3JzYS
1wa2NzMXYyLW9hZXB9fQAAAARub25lAAAAjQAAAIkAAAAGJQAAAP93ZtrMIRZutZ/SZUyw
JWwyI4YxNvr5tBt9UnSJ7K0+rQAAAQDohO1ykUahsogS+ymM6o9WEmdROJZpWShCqdv8Dj
2roQAAAIDG1G8hY90Xlz/YiFhDZLLWAAAAgOzMWTfAlHbJ4AdEhG5uU/EAAACA+1/AlcSr
QEPM5xLW0unCsQ==
---- END SSH2 ENCRYPTED PRIVATE KEY ----]!

... which resulted in

---
accounts::key_sets:
  dummy:
    private: >
      ENC[PKCS7,MIIDLQYJKoZIhvcNAQcDoIIDHjCCAxoCAQAxggEhMIIBHQIBADAFMAACAQEw
      DQYJKoZIhvcNAQEBBQAEggEAU9mJdFW8sjxGKzn52YKCKSwdWAsUckyBa53u
      5HfaCaXldBZzgXDfLgODGYcs2tsdoMu04Bu4kiUG80ZFuQzsmA74O3mby8ne
      q+9cmPxoXAr9rwp7ok8+OMyjCWBfPnY7Xu/IO0Fskm3E1DL0yCF9pCcmXkC8
      j3VM0z2+cqOMq1BLMWEpvLX8Hqf2ZCEyl9G5FyUd2QisvUpj6/gKQBhskL5+
      JGCJEsnmEmuj2NStuVmGmuzs+iNFcCNU6OGEBuxLQZu6t652uWef3a1GlvKl
      i2QKKsx60V9eCuuzIvdbLTfpuRfseUplcMRrVLLGwdF5NuC6PkaRYwmyR2MR
      iL+OQjCCAe4GCSqGSIb3DQEHATAdBglghkgBZQMEASoEEHpHk1ukYmWQ5bR7
      kSv70A6AggHAHXvLDSG8CzJ/L+COdrH9ZM8l66g3eor4EMQZYUdmy9rnpI2g
      voOTvNiQB1APhWv9a9TqB5OLYmCTBOlIRm5PLcYY1FK7DAxV2lBZU6ad9gwi
      r4Fui9xR3+dVqzZrT3jLq1roXNzRP6VHlBe1PjyVpPh+s3m5DNteOkVkBZkv
      vxG0egvSJbwtIQqZeTmAM1MyC6gz0l6D8PVV/UoXxTMri6qdea0XvBSwY4fA
      DgxDVNp22jETh80F3q38A0Ib4YtKeXxvEeMFcBku1IfSxs6SwBOMDSJb947I
      1JX7wRo4zIhWya4+K0ZSBw6EcXTfC/Y4Lvf+1htQC1sCSOxE9CradP590Bmb
      YH8ZDuqFF3L/kZ4AsOlJMFl+CZz6Pdw2yP01dVYVKC3i+uFZDAFTkK8y234r
      QXy9BGY8y1L8TMXHzUdz+efO8IyLecbI9yxyDXIjzDuyMPGqEPSSw6be2XEv
      /Q3gcUZECj4OT2QA/PgIy5MOLbU81Iz/BgNrwpp91XwgDzPHRWdAcvwQQ8Nj
      hQdVybpaYcwswmpZ7Sh5SPVBra1z7+EvFs1RMZbXbWuUxm/0zFLZiRyebtnv
      MPDKr9DJHw==]

Thus obsoleting the vim step for adding whitespaces.