This commit adds documentation for newly introduced helper commands, configuration variables and the certificate storage file `.git_tsa_store`. The documentation pages for `git tag` and git `verify-tag` are altered to describe the new command line options for time-stamping. Signed-off-by: Anton Würfel <anton.wuerfel@xxxxxx> Signed-off-by: Phillip Raffeck <phillip.raffeck@xxxxxx> --- Documentation/config.txt | 20 +++++++++++ Documentation/git-http-timestamp.txt | 32 +++++++++++++++++ Documentation/git-tag.txt | 30 +++++++++++----- Documentation/git-timestamp-util.txt | 52 +++++++++++++++++++++++++++ Documentation/git-tsa-store.txt | 68 ++++++++++++++++++++++++++++++++++++ Documentation/git-verify-tag.txt | 28 ++++++++++++--- 6 files changed, 218 insertions(+), 12 deletions(-) create mode 100644 Documentation/git-http-timestamp.txt create mode 100644 Documentation/git-timestamp-util.txt create mode 100644 Documentation/git-tsa-store.txt diff --git a/Documentation/config.txt b/Documentation/config.txt index 2cd6bdd..8be5fe6 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -2774,6 +2774,26 @@ transfer.unpackLimit:: not set, the value of this variable is used instead. The default value is 100. +ts.capath:: + This variable contains a path to a directory with trusted certificates. + This is necessary to verify the authenticity of RFC3161 time-stamps in + time-stamped tags with `git tag -v` or `git verify-tag`. There is no + default value. + +ts.failonverify:: + This variable controls the return value semantics of `git verify-tag`. + If set, both the return values of the gpg signature and the time-stamp + verification are reported. If the least significant bit is set, it + indicates a failure during the gpg signature verification, while the + second lowest bit reports the return value of the time-stamp verification. + Per default, only the return value of the gpg signature verification is + reported to remain consistent with legacy code. + +ts.tsaurl:: + This variable contains the URL of the Time Stamping Authority from which + RFC3161 time-stamps should be obtained when creating time-stamped tags + with `git tag`. There is no default value. + uploadarchive.allowUnreachable:: If true, allow clients to use `git archive --remote` to request any tree, whether reachable from the ref tips or not. See the diff --git a/Documentation/git-http-timestamp.txt b/Documentation/git-http-timestamp.txt new file mode 100644 index 0000000..1c7781e --- /dev/null +++ b/Documentation/git-http-timestamp.txt @@ -0,0 +1,32 @@ +git-http-timestamp(1) +===================== + +NAME +---- +git-http-timestamp - Helper program to communicate with a RFC3161 Time +Stamping Authority. + + +SYNOPSIS +-------- +[verse] +'git http-timestamp' + +DESCRIPTION +----------- +Offers an interface for the communication with a RFC3161 Time Stamping Authority +to obtain a trusted time-stamp signature for a Time Stamping Query. The Time +Stamping Query is read from stdin in DER format. +The response received from the Time Stamping Authority is written to stdout. +The URL of the Time Stamping Authority must be given using the configuration +variable `ts.tsaurl`. + +NOTES +----- +The main purpose of this command is to be called from the internal mechanism of +`git tag` or `git verify-tag`. Some commands are implemented in this separate +binary to allow the usage of libcurl without building all of git against it. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index abab481..940676e 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG SYNOPSIS -------- [verse] -'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] +'git tag' [-a | -s | -t | -u <keyid>] [-f] [-m <msg> | -F <file>] <tagname> [<commit> | <object>] 'git tag' -d <tagname>... 'git tag' [-n[<num>]] -l [--contains <commit>] [--points-at <object>] @@ -25,12 +25,12 @@ to delete, list or verify tags. Unless `-f` is given, the named tag must not yet exist. -If one of `-a`, `-s`, or `-u <keyid>` is passed, the command +If one of `-a`, `-s`, `-t`, or `-u <keyid>` is passed, the command creates a 'tag' object, and requires a tag message. Unless `-m <msg>` or `-F <file>` is given, an editor is started for the user to type in the tag message. -If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>` +If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, `-t`, and `-u <keyid>` are absent, `-a` is implied. Otherwise just a tag reference for the SHA-1 object name of the commit object is @@ -42,10 +42,14 @@ committer identity for the current user is used to find the GnuPG key for signing. The configuration variable `gpg.program` is used to specify custom GnuPG binary. -Tag objects (created with `-a`, `-s`, or `-u`) are called "annotated" +A tag containing a time-stamp according to RFC3161 will be created when `-t` is +used. The configuration variable `ts.tsaurl` is used to specify the URL of the +Time Stamping Authority from which the time-stamp should be obtained. + +Tag objects (created with `-a`, `-s`, `-t`, or `-u`) are called "annotated" tags; they contain a creation date, the tagger name and e-mail, a -tagging message, and an optional GnuPG signature. Whereas a -"lightweight" tag is simply a name for an object (usually a commit +tagging message, an optional GnuPG signature, and an optional RFC3161 time-stamp. +Whereas a "lightweight" tag is simply a name for an object (usually a commit object). Annotated tags are meant for release while lightweight tags are meant @@ -64,6 +68,10 @@ OPTIONS --sign:: Make a GPG-signed tag, using the default e-mail address's key. +-t:: +--time-stamp:: + Add a RFC3161 time-stamp to the tag. + -u <keyid>:: --local-user=<keyid>:: Make a GPG-signed tag, using the given key. @@ -78,7 +86,13 @@ OPTIONS -v:: --verify:: - Verify the gpg signature of the given tag names. + Verify, if present, the gpg signature and the RFC3161 time-stamp of the + given tag names. The configuration variable `ts.failonverify` specifies + if the return value of the time-stamp verification should be reported. + If set, the return values of both the gpg signature and the time-stamp + verfification are considered. Per default, only the return value of the + gpg signature verfification is reported to remain consistent with legacy + code. -n<num>:: <num> specifies how many lines from the annotation, if any, @@ -128,7 +142,7 @@ This option is only applicable when listing tags without annotation lines. Use the given tag message (instead of prompting). If multiple `-m` options are given, their values are concatenated as separate paragraphs. - Implies `-a` if none of `-a`, `-s`, or `-u <keyid>` + Implies `-a` if none of `-a`, `-s`, `-t`, or `-u <keyid>` is given. -F <file>:: diff --git a/Documentation/git-timestamp-util.txt b/Documentation/git-timestamp-util.txt new file mode 100644 index 0000000..4724e6f --- /dev/null +++ b/Documentation/git-timestamp-util.txt @@ -0,0 +1,52 @@ +git-timestamp-util(1) +===================== + +NAME +---- +git-timestamp-util - Helper tool to manage RFC3161 time-stamps. + + +SYNOPSIS +-------- +[verse] +'git timestamp-util' [-c <sha1>] [-v <sha1>] + +DESCRIPTION +----------- +Offers an interface to obtain a time-stamp signature for a given SHA1 hash or to +verify the time-stamp of a given SHA1 hash. The signing certificates of the +response sent by the Time Stamp Autority are stripped and stored in a separate +`git_tsa_store` file to avoid duplicates. + +OPTIONS +------- +-c sha1:: + Create a RFC3161 time-stamp over the given hash. The response from the + Time Stamping authority is stripped from the signing certificate and + then written to stdout as base64. + +-v sha1:: + Verify a time-stamp for the given hash. The corresponding TSR, encoded + in base64, is read from stdin and merged with its signing certificate + from a separate certificate store. To allow the verification of the + signing certificate, the configuration variable `ts.capath` must contain + a path to a directory with trusted certificates. The configuration + variable `ts.failonverify` controls the return value semantics. If set, + the return values of both the gpg signature and the time-stamp + verification are reported. The return value of the time-stamp + verification is reported using the second lowest bit, the return value + of the gpg signature verification using the least significant bit. Per + default, only the return value of the gpg signature verification is + reported to remain consistent with legacy code. + +NOTES +----- +The main purpose of this command is to be called from the internal +mechanism of `git tag` or `git verify-tag`. Some commands are implemented in +this separate binary to allow the usage of libcrypto without building all of git +against it. While it is possible to is it on its own, the interface is highly +tailored to the needs of the internal storage mechanisms. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-tsa-store.txt b/Documentation/git-tsa-store.txt new file mode 100644 index 0000000..2ce015e --- /dev/null +++ b/Documentation/git-tsa-store.txt @@ -0,0 +1,68 @@ +git-tsa-store(5) +================ + +NAME +---- +git-tsa-store - Stores certificates of RFC3161 Time Stamping Authorities + +DESCRIPTION +----------- +A `.git_tsa_store` file stores certificates of RFC3161 Time Stamping Authorities +from which time-stamps were obtained using `git tag` or `git timestamp-util`. To +avoid unnecessary pollution by large git objects, each RFC3161 time-stamp is +stripped from the signing certificate of the Time Stamping Authority before it +is stored in the tag object. These signing certificates are then managed in the +`.git_tsa_store` file for each repository. + +Each certificate is only stored once in a `.git_tsa_store` file. The comparison +criterion for equality is the pair of the serial number of the certificate and +the common name of the issuer. Therefore it is possible to manage multiple +certificates for one Time Stamping Authority if for some reason a certificate +should change. + +The certificates stored in a `.git_tsa_store` file are only used to correctly +identify the issuer of a time-stamp. They are not considered trustworthy. For +verification purposes it is therefore necesssary to specify trusted certificates +using the configuration variable `ts.capath`. + +All certificates in a `.git_tsa_store` file are stored using the pattern +described below. + +PATTERN FORMAT +-------------- + - The string '-----BEGIN ENTRY-----' marks the beginning of a certificate + entry. + + - The next line is of the format 'Version: <version>'. The current version + number is 1. + + - The next line is of the format 'Serial: <serial>', containing the serial + number of the certificate. Together with the common name of the issuer it + forms the identifying tuple. + + - The next line is of the format 'Issuer: <common name>', containing the common + name of the issuer of the time-stamp. Together with the serial number of the + certificate it forms the identifying tuple. + + - The next line contains only a new line to separate metadata from the + certificate itself. + + - The certificate itself follows in PEM format surrounded by the usual + delimiters '-----BEGIN CERTIFICATE-----' and '-----END CERTIFICATE-----'. + + - A closing '-----END ENTRY-----' marks the end of an entry. + +NOTES +----- +The main purpose of a `.git_tsa_store` file is to be managed exclusively by `git +timestamp-util`. Nevertheless it is possible to fill in certificates manually as +long as the above specified format is observed. Manually editing this file might +be necessary in the unlikely case of non-resolvable merge conflicts. + +SEE ALSO +-------- +linkgit:git-timestamp-util[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index d590edc..539e545 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -3,7 +3,7 @@ git-verify-tag(1) NAME ---- -git-verify-tag - Check the GPG signature of tags +git-verify-tag - Check the GPG signature and RFC3161 time-stamp of tags SYNOPSIS -------- @@ -12,13 +12,33 @@ SYNOPSIS DESCRIPTION ----------- -Validates the gpg signature created by 'git tag'. +Validates the gpg signature and RFC3161 time-stamp created by 'git tag'. To +validate the signing certificate of the Time Stamping Authority of a RFC3161 +time-stamp, a path to a directory of trusted certificates must be given using +the configuration variable `ts.capath`. The containing files must follow the +OpenSSL naming convention `<issuer-hash>.0`. The configuration variable +`ts.failonverify` specifies if the return value of the time-stamp verification +should be reported. If set, the return values of both the gpg signature and the +time-stamp verfification are considered. Per default, only the return value of +the gpg signature verfification is reported to remain consistent with legacy +code. Using the `-s` or `-t` options overrides the behaviour set by +`ts.failonverify`. OPTIONS ------- --raw:: - Print the raw gpg status output to standard error instead of the normal - human-readable output. + Print the raw gpg status output and time-stamp verification output to + standard error instead of the normal human-readable output. + +-s:: +--signature:: + Report the return value of the gpg signature verification. If the least + significant bit is set, an error occurred. + +-t:: +--timestamp:: + Report the return value of the time-stamp verification. If the second + lowest bit is set, an error occurred. -v:: --verbose:: -- 2.8.0.rc0.62.gfc8aefa.dirty -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html