[JENKINS-50242] Improved help text to correct a misunderstanding.

jenkinsci · Mar 19, 2018 · c7aff03 · c7aff03
1 parent aeda5de
commit c7aff03
Showing 1 changed file with 26 additions and 6 deletions.
diff --git a/src/main/resources/org/jenkinsci/plugins/credentialsbinding/impl/BindingStep/help.html b/src/main/resources/org/jenkinsci/plugins/credentialsbinding/impl/BindingStep/help.html
@@ -1,13 +1,16 @@
 <p>
     Allows various kinds of credentials (secrets) to be used in idiosyncratic ways.
+    (Some steps explicitly ask for credentials of a particular kind,
+    usually as a <code>credentialsId</code> parameter,
+    in which case this step is unnecessary.)
     Each binding will define an environment variable active within the scope of the step.
     You can then use them directly from any other steps that expect environment variables to be set:
 </p>
 <pre><code>node {
   withCredentials([usernameColonPassword(credentialsId: 'mylogin', variable: 'USERPASS')]) {
     sh '''
       set +x
-      curl -u $USERPASS https://private.server/ > output
+      curl -u "$USERPASS" https://private.server/ > output
     '''
   }
 }</code></pre>
@@ -23,13 +26,30 @@
   }
 }</code></pre>
 <p>
-    or retrieve values from Groovy code via the <code>env</code> magic variable:
+    Note the use of <em>single</em> quotes to define the <code>script</code>
+    (implicit parameter to <code>sh</code>) in Groovy above.
+    You want the secret to be expanded by the shell as an environment variable.
+    The following idiom is less secure, as the secret is interpolated by Groovy
+    and so (for example) the operating system process listing will show it:
 </p>
-<pre><code>def password = env.PASSWORD</code></pre>
+<pre><code>node {
+  withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
+    sh /* WRONG! */ """
+      set +x
+      curl -H 'Token: $TOKEN' https://some.api/
+    """
+  }
+}</code></pre>
 <p>
-    Note that some steps explicitly ask for credentials of a particular kind,
-    usually as a <code>credentialsId</code> parameter,
-    in which case this step is unnecessary.
+    The secret(s) will be masked (<code>****</code>) in case they are printed to the build log.
+    This prevents you from <em>accidentally</em> disclosing passwords and the like via the log.
+    (Bourne shell <code>set +x</code>, or Windows batch <code>@echo off</code>,
+    blocks secrets from being displayed in echoed commands;
+    but build tools in debug mode might dump all environment variables to standard output/error,
+    or poorly designed network clients might display authentication, etc.)
+    The masking could of course be trivially circumvented;
+    anyone permitted to configure a job or define Pipeline steps
+    is assumed to be trusted to use any credentials in scope however they like.
 </p>
 <p>
     For bindings which store a secret file, beware that