Improve with information provided by Joerg.

There are some formatting errors, someone with mandoc clue please correct.

Also, this man page assumes familiarity with the concepts uesd.
While fully describing these concepts is outside the scope of this
man page, a pointer to such a description should be included.
Someone who knows of such a description, please provide pointers.

Finally, we should have a companion tool to create the peaces needed
to use this tool: set up a CA, create a certificate chain and a
private key/certificate pair for signing.

usr.bin/nbsvtool/nbsvtool.1

@@ -1,6 +1,6 @@
-.\" $NetBSD: nbsvtool.1,v 1.2 2008/05/22 12:01:03 wiz Exp $
+.\" $NetBSD: nbsvtool.1,v 1.3 2008/07/15 11:17:44 dillo Exp $
 .\"
-.\" Copyright (c) 2004 The NetBSD Foundation, Inc.
+.\" Copyright (c) 2004-2008 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" This code is derived from software contributed to The NetBSD Foundation
@@ -26,7 +26,7 @@
 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
-.Dd May 11, 2008
+.Dd July 15, 2008
 .Dt NBSVTOOL 1
 .Os
 .Sh NAME
@@ -37,60 +37,112 @@
 .OP Fl v
 .Op Fl a Ar anchor-certificates
 .Op Fl c Ar certificate-chain
-.Op Fl f Ar certificate-chain
-.Op Fl k Ar keyfile
-.Op Fl u Ar required-keyusage
+.Op Fl f Ar certificate-file
+.Op Fl k Ar private-key-file
+.Op Fl u Ar required-key-usage
 .Ar command
-.Op Ar file ...
+.Ar args ...
 .Sh DESCRIPTION
 .Nm
-is used to create and verify detached signatures of files.
-.Nm
-has two modes, signature creation and verification.
+is used to create and verify detached X509 signatures of files.
+Private keys and certificates are expected to be PEM encoded,
+signatures are in PEM/SMIME format.
+.\" XXX: pointer to detailed description/documentation of these formats
+.\" XXX: pointer to concept explanation: key, certificate, signature,
+.\"      certificate chain
 .Pp
-The signature mode requires the options
-.Fl k
+Supported commands:
+.Bl -tag -width Xverify-codeXfileX[signature]XXX
+.It sign Ar file
+Sign
+.Ar file ,
+placing the signature in
+.Ar file
+.Pa .sp7 .
+The options
+.Fl f
 and
-.Fl c .
-.Pp
-The command
-.Ql verify-code
-is an alias for
-.Ql -u code verify .
+.Fl k
+are required for this command.
+.It verify Ar file Op Ar signature
+Verify signature for
+.Ar file .
+If 
+.Ar signature
+is not specified,
+.Ar file
+.Pa .sp7
+is used.
+.It verify-code Ar file Op Ar signature
+This is a short cut for verify with the option
+.Fl u 
+code.
+.El
 .Pp
 Supported options:
 .Bl -tag -width XfXcertificateXchainXfileXXX
-.It Fl a Ar trust anchor
-Trust anchor that will be used to verify the certificate signing the request.
-.It Fl c Ar certificate chain file
-Additional certificates that will be added to the signature
+.It Fl a Ar anchor-certificates
+A file containing one or more (concatenated) keys that are considered
+trusted.
+.It Fl c Ar certificate-chain
+A file containing additional certificates that will be added to the signature
 when creating one.
-For verification it is used to fill missing links in the trust chain.
-.It Fl f Ar certificate file
-The certicate file to use when creating signatures.
-The certicate needs to match the key given by
+They will be used to fill missing links in the trust chain when
+verifying the signature.
+.It Fl f Ar certificate-file
+A file containing the certificate to use for signing.
+The certificate must match the key given by
 .Fl k .
-This is enforced by the program.
-.It Fl k Ar private key
-The private key file to use when creating signatures.
-.It Fl u Ar key usage
+.It Fl k Ar private-key-file
+A file containing the private key to use for signing.
+.It Fl u Ar required-key-usage
+Verify that the extended key-usage attribute in the signing certificate
+matches
+.Ar required-key-usage .
+Otherwise, the signature is rejected.
 .Ar key usage
-is one of:
+can be one of:
 .Dq ssl-server ,
 .Dq ssl-client ,
 .Dq code ,
 or
 .Dq smime .
-This verifies the extended key-usage attribute in the signer certificate.
 .It Fl v
-Print verbose information of the signer.
+Print verbose information about the signing certificate.
 .El
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES
-.Dl nbsvtool -k key -c cert-chain sign hello hello.sp7
-.Dl nbsvtool verify-code hello hello.sp7
-.Dl nbsvtool -u code verify file file.sp7
-.Dl nbsvtool -a anchor-file verify file.sp7
+.Pp
+Create signature file
+.Pa hello.sp7
+for file 
+.Pa hello .
+The private key is found in file
+.Pa key ,
+the matching certificate is in 
+.Pa cert ,
+additional certificates from 
+.Pa cert-chain
+are included in the created signature.
+.Dl nbsvtool -k key -f cert -c cert-chain sign hello hello.sp7
+.Pp
+Verify that the signature
+.Pa hello.sp7
+is valid for file
+.Pa hello
+and that the signing certificate allows code signing.  Certificates
+in
+.Pa anchor-file
+are considered trusted, and there must be a certificate chain from one
+of those certificates to the signing certificate.
+.Dl nbsvtool -a anchor-file verify-code hello hello.sp7
 .Sh SEE ALSO
 .Xr openssl_smime 1
+.\" XXX: pointer to X509 documentation, CA setup
+.Sh CAVEATS
+.Pp
+As there is currently no default trust anchor, you must explicilty
+specify one with
+.Fl a ,
+otherwise no verification can succeed.