<commit_before><!--
  ~ Copyright 2010 the original author or authors.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~      http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<chapter id='signing_plugin' xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>The Signing Plugin</title>

    <note>
        <para>This chapter is WIP.</para>
    </note>
    
    <para>
        The signing plugin adds the ability to digitally sign built files and artifacts.
        These digital signatures can then be used to prove who built the artifact the signature is attached to
        as well as other information such as when the signature was generated.
    </para>
    <para>
        The signing plugin currently only provides support for generating <ulink url='http://www.pgpi.org/'>PGP signatures</ulink> 
        (which is the signature format <ulink url="https://docs.sonatype.org/display/Repository/Central+Sync+Requirements">required for 
        publication to the Maven Central Repository</ulink>).
    </para>

    <section>
        <title>Usage</title>
        <para>To use the Signing plugin, include in your build script:</para>
        <sample id="useSigningPlugin" dir="signing/maven" title="Using the Signing plugin">
            <sourcefile file="build.gradle" snippet="use-plugin"/>
        </sample>
    </section>
    
    <section>
        <title>Signatory credentials</title>
        <para>
            In order to create PGP signatures, you will need a key pair (instructions on creating a key pair using the <ulink url="http://www.gnupg.org/">GnuPG tools</ulink> 
            can be found <ulink url="http://www.dewinter.com/gnupg_howto/english/GPGMiniHowto-3.html#ss3.1">here</ulink>). You need to provide the signing plugin
            with your key information, which means three things: 
        </para>
        <itemizedlist>
            <listitem><para>The public key ID (an 8 character hexadecimal string).</para></listitem>
            <listitem><para>The absolute path to the secret key ring file containing your private key.</para></listitem>
            <listitem><para>The passphrase used to protect your public key.</para></listitem>
        </itemizedlist>
        <para>
            These items must be supplied as the property projects <literal>signing.keyId</literal>, <literal>signing.password</literal> 
            and <literal>signing.secretKeyRingFile</literal> respectively. Given the personal and private nature of these values, a good practice
            is to store them in the user <literal>gradle.properties</literal> file (described in <xref linkend="sec:gradle_properties_and_system_properties"/>).
        </para>
        <programlisting>
            signing.keyId=24875D73
signing.password=<PASSWORD>
signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg
        </programlisting>
        <para>
            If specifying this information in the user <literal>gradle.properties</literal> file is not feasible for your environment, you can source the information
            however you need to and set the project properties manually.
        </para>
        <!--
            Unsure how to go about automatically testing this little snippet.
        -->
        <programlisting>
import org.gradle.plugins.signing.Sign

gradle.taskGraph.whenReady { taskGraph ->
    if (taskGraph.allTasks.any { it instanceof Sign }) {
        // Use Java 6's console to read from the console (no good for a CI environment)
        Console console = System.console()
        console.printf "\n\nWe have to sign some things in this build.\n\nPlease enter your signing details.\n\n"
        allprojects*.setProperty("signing.keyId", console.readLine("PGP Key Id: "))
        allprojects*.setProperty("signing.secretKeyRingFile", console.readLine("PGP Secret Key Ring File (absolute path): "))
        allprojects*.setProperty("signing.password", console.readPassword("PGP Private Key Password: "))
        console.printf "\nThanks.\n\n"
    }
}
        </programlisting>
    </section>

    <section>
        <title>Specifying what to sign</title>
        <para>
            As well as configuring how things are to be signed (i.e. the signatory configuration), you must also specify what is to be signed. 
            The Signing plugin provides a DSL that allows you to specify the tasks and/or configurations that should be signed.
        </para>
        <section>
            <title>Signing Configurations</title>
            <para>
                It is common to want to sign the artifacts of a configuration. For example, the <link linkend="java_plugin">Java plugin</link> 
                configures a jar to built and this jar artifact is added to the <literal>archives</literal> configuration. 
                Using the Signing DSL, you can specify that all of the artifacts of this configuration should be signed.
            </para>
            <sample id="signingArchives" dir="signing/maven" title="Signing a configuration">
                <sourcefile file="build.gradle" snippet="sign-archives"/>
            </sample>
            <para>
                This will create a task (of type <apilink class="org.gradle.plugins.signing.Sign"/>) in your project named “<literal>signArchives</literal>”, 
                that will build any <literal>archives</literal> artifacts (if needed) and then generate signatures for them. The signature files will be placed
                alongside the artifacts being signed.
            </para>
            <sample id="signingArchivesOutput" dir="signing/maven" title="Signing a configuration output">
                <output args="signArchives"/>
            </sample>
        </section>
        <section>
            <title>Signing Tasks</title>
            <para>
                In some cases the artifact that you need to sign may not be part of a configuration. In this case you can directly sign the task that
                produces the artifact to sign.
            </para>
            <sample id="signingTasks" dir="signing/tasks" title="Signing a task">
                <sourcefile file="build.gradle" snippet="sign-task"/>
            </sample>
            <para>
                This will create a task (of type <apilink class="org.gradle.plugins.signing.Sign"/>) in your project named “<literal>signStuffZip</literal>”, 
                that will build the input task's archive (if needed) and then sign it. The signature file will be placed
                alongside the artifact being signed.
            </para>
            <sample id="signingTaskOutput" dir="signing/tasks" title="Signing a task output">
                <output args="signStuffZip"/>
            </sample>
            <para>
                For a task to be “signable”, it must produce an archive of some type. Tasks that do this are the <apilink class="org.gradle.api.tasks.bundling.Tar"/>,
                <apilink class="org.gradle.api.tasks.bundling.Zip"/>, <apilink class="org.gradle.api.tasks.bundling.Jar"/>, 
                <apilink class="org.gradle.api.tasks.bundling.War"/> and <apilink class="org.gradle.api.tasks.bundling.Ear"/> tasks.
            </para>
        </section>
    </section>
    
    <section>
        <title>The “signatures” configuration</title>
        <note>
            <para>This chapter is assuming <ulink link="http://issues.gradle.org/browse/GRADLE-1651">GRADLE-1651</ulink> has been implemented (which may not happen).</para>
        </note>
        <para>
            When specifying what is to be signed via the Signing DSL, the resultant signature artifacts are automatically added to the “<literal>signatures</literal>”
            dependency configuration that the signing plugin adds. The signing plugin adds the “<literal>signatures</literal>” configuration to the set of configurations 
            that the “<literal>published</literal>” configuration extends, effectively making the signatures part of “<literal>published</literal>” configuration.
        </para>
    </section>
    <commit_msg>Corrected signing plugin userguide chapter on publishing the signatures.<commit_after><!--
  ~ Copyright 2010 the original author or authors.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~      http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<chapter id='signing_plugin' xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>The Signing Plugin</title>

    <para>
        The signing plugin adds the ability to digitally sign built files and artifacts.
        These digital signatures can then be used to prove who built the artifact the signature is attached to
        as well as other information such as when the signature was generated.
    </para>
    <para>
        The signing plugin currently only provides support for generating <ulink url='http://www.pgpi.org/'>PGP signatures</ulink> 
        (which is the signature format <ulink url="https://docs.sonatype.org/display/Repository/Central+Sync+Requirements">required for 
        publication to the Maven Central Repository</ulink>).
    </para>

    <section>
        <title>Usage</title>
        <para>To use the Signing plugin, include in your build script:</para>
        <sample id="useSigningPlugin" dir="signing/maven" title="Using the Signing plugin">
            <sourcefile file="build.gradle" snippet="use-plugin"/>
        </sample>
    </section>
    
    <section>
        <title>Signatory credentials</title>
        <para>
            In order to create PGP signatures, you will need a key pair (instructions on creating a key pair using the <ulink url="http://www.gnupg.org/">GnuPG tools</ulink> 
            can be found <ulink url="http://www.dewinter.com/gnupg_howto/english/GPGMiniHowto-3.html#ss3.1">here</ulink>). You need to provide the signing plugin
            with your key information, which means three things: 
        </para>
        <itemizedlist>
            <listitem><para>The public key ID (an 8 character hexadecimal string).</para></listitem>
            <listitem><para>The absolute path to the secret key ring file containing your private key.</para></listitem>
            <listitem><para>The passphrase used to protect your public key.</para></listitem>
        </itemizedlist>
        <para>
            These items must be supplied as the property projects <literal>signing.keyId</literal>, <literal>signing.password</literal> 
            and <literal>signing.secretKeyRingFile</literal> respectively. Given the personal and private nature of these values, a good practice
            is to store them in the user <literal>gradle.properties</literal> file (described in <xref linkend="sec:gradle_properties_and_system_properties"/>).
        </para>
        <programlisting>
            signing.keyId=24875D73
signing.password=<PASSWORD>
signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg
        </programlisting>
        <para>
            If specifying this information in the user <literal>gradle.properties</literal> file is not feasible for your environment, you can source the information
            however you need to and set the project properties manually.
        </para>
        <!--
            Unsure how to go about automatically testing this little snippet.
        -->
        <programlisting>
import org.gradle.plugins.signing.Sign

gradle.taskGraph.whenReady { taskGraph ->
    if (taskGraph.allTasks.any { it instanceof Sign }) {
        // Use Java 6's console to read from the console (no good for a CI environment)
        Console console = System.console()
        console.printf "\n\nWe have to sign some things in this build.\n\nPlease enter your signing details.\n\n"
        allprojects*.setProperty("signing.keyId", console.readLine("PGP Key Id: "))
        allprojects*.setProperty("signing.secretKeyRingFile", console.readLine("PGP Secret Key Ring File (absolute path): "))
        allprojects*.setProperty("signing.password", console.readPassword("PGP Private Key Password: "))
        console.printf "\nThanks.\n\n"
    }
}
        </programlisting>
    </section>

    <section>
        <title>Specifying what to sign</title>
        <para>
            As well as configuring how things are to be signed (i.e. the signatory configuration), you must also specify what is to be signed. 
            The Signing plugin provides a DSL that allows you to specify the tasks and/or configurations that should be signed.
        </para>
        <section>
            <title>Signing Configurations</title>
            <para>
                It is common to want to sign the artifacts of a configuration. For example, the <link linkend="java_plugin">Java plugin</link> 
                configures a jar to built and this jar artifact is added to the <literal>archives</literal> configuration. 
                Using the Signing DSL, you can specify that all of the artifacts of this configuration should be signed.
            </para>
            <sample id="signingArchives" dir="signing/maven" title="Signing a configuration">
                <sourcefile file="build.gradle" snippet="sign-archives"/>
            </sample>
            <para>
                This will create a task (of type <apilink class="org.gradle.plugins.signing.Sign"/>) in your project named “<literal>signArchives</literal>”, 
                that will build any <literal>archives</literal> artifacts (if needed) and then generate signatures for them. The signature files will be placed
                alongside the artifacts being signed.
            </para>
            <sample id="signingArchivesOutput" dir="signing/maven" title="Signing a configuration output">
                <output args="signArchives"/>
            </sample>
        </section>
        <section>
            <title>Signing Tasks</title>
            <para>
                In some cases the artifact that you need to sign may not be part of a configuration. In this case you can directly sign the task that
                produces the artifact to sign.
            </para>
            <sample id="signingTasks" dir="signing/tasks" title="Signing a task">
                <sourcefile file="build.gradle" snippet="sign-task"/>
            </sample>
            <para>
                This will create a task (of type <apilink class="org.gradle.plugins.signing.Sign"/>) in your project named “<literal>signStuffZip</literal>”, 
                that will build the input task's archive (if needed) and then sign it. The signature file will be placed
                alongside the artifact being signed.
            </para>
            <sample id="signingTaskOutput" dir="signing/tasks" title="Signing a task output">
                <output args="signStuffZip"/>
            </sample>
            <para>
                For a task to be “signable”, it must produce an archive of some type. Tasks that do this are the <apilink class="org.gradle.api.tasks.bundling.Tar"/>,
                <apilink class="org.gradle.api.tasks.bundling.Zip"/>, <apilink class="org.gradle.api.tasks.bundling.Jar"/>, 
                <apilink class="org.gradle.api.tasks.bundling.War"/> and <apilink class="org.gradle.api.tasks.bundling.Ear"/> tasks.
            </para>
        </section>
    </section>
    
    <section>
        <title>Publishing the signatures</title>
        <para>
            When specifying what is to be signed via the Signing DSL, the resultant signature artifacts are automatically added to the “<literal>signatures</literal>”
            dependency configuration that the signing plugin adds. This means that if you want to upload your signatures to your distribution repository along
            with the artifacts for which the signature is for you are going to have to create a new configuration that combines them. By default, created artifacts such
            as jars and the like are added to the “<literal>archives</literal>” configuration. You can create a new configuration that extends 
            “<literal>archives</literal>” and “<literal>signatures</literal>”.
        </para>
        <sample id="signingPublishedConfiguration" dir="signing/maven" title="Adding the published configuration">
            <sourcefile file="build.gradle" snippet="published-configuration"/>
        </sample>
        <para>
            This also means that instead of configuring and using the “<literal>uploadArchives</literal>” to distribute your artifacts, you would use the equivalent
            “<literal>uploadPublished</literal>” task. See <xref linkend="artifact_management"/> for more on artifacts and configurations.
        </para>
    </section>
    
{'fraction_non_alphanumeric': 0.09427609427609428, 'fraction_numerical': 0.003309935513325344, 'mean_word_length': 2.6319170984455957, 'pattern_counts': {'":': 0, '<': 289, '<?xml version=': 0, '>': 291, 'https://': 2, 'lorem ipsum': 0, 'www.': 10, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4550833', 'n_tokens_mistral': 4657, 'n_tokens_neox': 4412, 'n_words': 1672}