usr.bin/nbsvtool/nbsvtool.1

   1 .\" $NetBSD: nbsvtool.1,v 1.4 2008/07/15 12:14:13 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2004-2008 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Love Hörnquist Åstrand <lha@it.su.se>
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .Dd March 11, 2009
  30 .Dt NBSVTOOL 1
  31 .Os
  32 .Sh NAME
  33 .Nm nbsvtool
  34 .Nd create and verify detached signatures of files
  35 .Sh SYNOPSIS
  36 .Nm nbsvtool
  37 .Op Fl v
  38 .Op Fl a Ar anchor-certificates
  39 .Op Fl c Ar certificate-chain
  40 .Op Fl f Ar certificate-file
  41 .Op Fl k Ar private-key-file
  42 .Op Fl u Ar required-key-usage
  43 .Ar command
  44 .Ar args ...
  45 .Sh DESCRIPTION
  46 .Nm
  47 is used to create and verify detached X509 signatures of files.
  48 Private keys and certificates are expected to be PEM encoded,
  49 signatures are in PEM/SMIME format.
  50 .\" XXX: pointer to detailed description/documentation of these formats
  51 .\" XXX: pointer to concept explanation: key, certificate, signature,
  52 .\"      certificate chain
  53 .Pp
  54 Supported commands:
  55 .Bl -tag -width Xverify-codeXfileX[signature]XXX
  56 .It sign Ar file
  57 Sign
  58 .Ar file ,
  59 placing the signature in
  60 .Ar file Ns Pa .sp7 .
  61 The options
  62 .Fl f
  63 and
  64 .Fl k
  65 are required for this command.
  66 .It verify Ar file Op Ar signature
  67 Verify signature for
  68 .Ar file .
  69 If
  70 .Ar signature
  71 is not specified,
  72 .Ar file Ns Pa .sp7
  73 is used.
  74 .It verify-code Ar file Op Ar signature
  75 This is a short cut for verify with the option
  76 .Fl u
  77 code.
  78 .El
  79 .Pp
  80 Supported options:
  81 .Bl -tag -width XfXcertificateXchainXfileXXX
  82 .It Fl a Ar anchor-certificates
  83 A file containing one or more (concatenated) keys that are considered
  84 trusted.
  85 .It Fl c Ar certificate-chain
  86 A file containing additional certificates that will be added to the signature
  87 when creating one.
  88 They will be used to fill missing links in the trust chain when
  89 verifying the signature.
  90 .It Fl f Ar certificate-file
  91 A file containing the certificate to use for signing.
  92 The certificate must match the key given by
  93 .Fl k .
  94 .It Fl k Ar private-key-file
  95 A file containing the private key to use for signing.
  96 .It Fl u Ar required-key-usage
  97 Verify that the extended key-usage attribute in the signing certificate
  98 matches
  99 .Ar required-key-usage .
 100 Otherwise, the signature is rejected.
 101 .Ar key usage
 102 can be one of:
 103 .Dq ssl-server ,
 104 .Dq ssl-client ,
 105 .Dq code ,
 106 or
 107 .Dq smime .
 108 .It Fl v
 109 Print verbose information about the signing certificate.
 110 .El
 111 .Sh EXIT STATUS
 112 .Ex -std
 113 .Sh EXAMPLES
 114 Create signature file
 115 .Pa hello.sp7
 116 for file
 117 .Pa hello .
 118 The private key is found in file
 119 .Pa key ,
 120 the matching certificate is in
 121 .Pa cert ,
 122 additional certificates from
 123 .Pa cert-chain
 124 are included in the created signature.
 125 .Dl nbsvtool -k key -f cert -c cert-chain sign hello hello.sp7
 126 .Pp
 127 Verify that the signature
 128 .Pa hello.sp7
 129 is valid for file
 130 .Pa hello
 131 and that the signing certificate allows code signing.  Certificates
 132 in
 133 .Pa anchor-file
 134 are considered trusted, and there must be a certificate chain from one
 135 of those certificates to the signing certificate.
 136 .Dl nbsvtool -a anchor-file verify-code hello hello.sp7
 137 .Sh SEE ALSO
 138 .Xr openssl_smime 1
 139 .\" XXX: pointer to X509 documentation, CA setup
 140 .Sh CAVEATS
 141 As there is currently no default trust anchor, you must explicilty
 142 specify one with
 143 .Fl a ,
 144 otherwise no verification can succeed.