1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/doc/cmsutil.xml Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,299 @@
1.4 +<?xml version="1.0" encoding="UTF-8"?>
1.5 +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
1.6 + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
1.7 +<!ENTITY date SYSTEM "date.xml">
1.8 +<!ENTITY version SYSTEM "version.xml">
1.9 +]>
1.10 +
1.11 +<refentry id="cmsutil">
1.12 +
1.13 + <refentryinfo>
1.14 + <date>&date;</date>
1.15 + <title>NSS Security Tools</title>
1.16 + <productname>nss-tools</productname>
1.17 + <productnumber>&version;</productnumber>
1.18 + </refentryinfo>
1.19 +
1.20 + <refmeta>
1.21 + <refentrytitle>CMSUTIL</refentrytitle>
1.22 + <manvolnum>1</manvolnum>
1.23 + </refmeta>
1.24 +
1.25 + <refnamediv>
1.26 + <refname>cmsutil</refname>
1.27 + <refpurpose>Performs basic cryptograpic operations, such as encryption and decryption, on Cryptographic Message Syntax (CMS) messages.</refpurpose>
1.28 + </refnamediv>
1.29 +
1.30 + <refsynopsisdiv>
1.31 + <cmdsynopsis>
1.32 + <command>cmsutil</command>
1.33 + <arg><replaceable>options</replaceable></arg>
1.34 + <arg>[<replaceable>arguments</replaceable>]</arg>
1.35 + </cmdsynopsis>
1.36 + </refsynopsisdiv>
1.37 +
1.38 + <refsection>
1.39 + <title>STATUS</title>
1.40 + <para>This documentation is still work in progress. Please contribute to the initial review in <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=836477">Mozilla NSS bug 836477</ulink>
1.41 + </para>
1.42 + </refsection>
1.43 +
1.44 + <refsection id="description">
1.45 + <title>Description</title>
1.46 +
1.47 + <para>The <command>cmsutil</command> command-line uses the S/MIME Toolkit to perform basic operations, such as encryption and decryption, on Cryptographic Message Syntax (CMS) messages.
1.48 + </para>
1.49 + <para>
1.50 +To run cmsutil, type the command cmsutil option [arguments] where option and arguments are combinations of the options and arguments listed in the following section.
1.51 +Each command takes one option. Each option may take zero or more arguments.
1.52 +To see a usage string, issue the command without options.
1.53 + </para>
1.54 +
1.55 + </refsection>
1.56 +
1.57 + <refsection id="options">
1.58 + <title>Options and Arguments</title>
1.59 + <para>
1.60 + </para>
1.61 + <para><command>Options</command></para>
1.62 + <para>
1.63 +Options specify an action. Option arguments modify an action.
1.64 +The options and arguments for the cmsutil command are defined as follows:
1.65 + </para>
1.66 + <variablelist>
1.67 + <varlistentry>
1.68 + <term>-C</term>
1.69 + <listitem><para>Encrypt a message.</para></listitem>
1.70 + </varlistentry>
1.71 +
1.72 + <varlistentry>
1.73 + <term>-D </term>
1.74 + <listitem><para>Decode a message.</para></listitem>
1.75 + </varlistentry>
1.76 +
1.77 + <varlistentry>
1.78 + <term>-E </term>
1.79 + <listitem><para>Envelope a message.</para></listitem>
1.80 + </varlistentry>
1.81 +
1.82 + <varlistentry>
1.83 + <term>-O </term>
1.84 + <listitem><para>Create a certificates-only message.</para></listitem>
1.85 + </varlistentry>
1.86 +
1.87 + <varlistentry>
1.88 + <term>-S </term>
1.89 + <listitem><para>Sign a message.</para></listitem>
1.90 + </varlistentry>
1.91 +
1.92 + </variablelist>
1.93 +
1.94 + <para><command>Arguments</command></para>
1.95 + <para>Option arguments modify an action.</para>
1.96 + <variablelist>
1.97 + <varlistentry>
1.98 + <term>-b </term>
1.99 + <listitem>
1.100 + <para>Decode a batch of files named in infile.</para>
1.101 + </listitem>
1.102 + </varlistentry>
1.103 +
1.104 + <varlistentry>
1.105 + <term>-c content </term>
1.106 + <listitem>
1.107 + <para>Use this detached content (decode only).</para>
1.108 + </listitem>
1.109 + </varlistentry>
1.110 +
1.111 + <varlistentry>
1.112 + <term>-d dbdir</term>
1.113 + <listitem>
1.114 + <para>Specify the key/certificate database directory (default is ".")</para>
1.115 + </listitem>
1.116 + </varlistentry>
1.117 +
1.118 + <varlistentry>
1.119 + <term>-e envfile</term>
1.120 + <listitem>
1.121 + <para>Specify a file containing an enveloped message for a set of recipients to which you would like to send an encrypted message. If this is the first encrypted message for that set of recipients, a new enveloped message will be created that you can then use for future messages (encrypt only).</para>
1.122 + </listitem>
1.123 + </varlistentry>
1.124 +
1.125 + <varlistentry>
1.126 + <term>-f pwfile</term>
1.127 + <listitem>
1.128 + <para>Use password file to set password on all PKCS#11 tokens.</para>
1.129 + </listitem>
1.130 + </varlistentry>
1.131 +
1.132 + <varlistentry>
1.133 + <term>-G</term>
1.134 + <listitem>
1.135 + <para>Include a signing time attribute (sign only).</para>
1.136 + </listitem>
1.137 + </varlistentry>
1.138 +
1.139 + <varlistentry>
1.140 + <term>-H hash</term>
1.141 + <listitem>
1.142 + <para>Use specified hash algorithm (default:SHA1).</para>
1.143 + </listitem>
1.144 + </varlistentry>
1.145 +
1.146 + <varlistentry>
1.147 + <term>-h num</term>
1.148 + <listitem>
1.149 + <para>Generate email headers with info about CMS message (decode only).</para>
1.150 + </listitem>
1.151 + </varlistentry>
1.152 +
1.153 + <varlistentry>
1.154 + <term>-i infile</term>
1.155 + <listitem>
1.156 + <para>Use infile as a source of data (default is stdin).</para>
1.157 + </listitem>
1.158 + </varlistentry>
1.159 +
1.160 + <varlistentry>
1.161 + <term>-k</term>
1.162 + <listitem>
1.163 + <para>Keep decoded encryption certs in permanent cert db.</para>
1.164 + </listitem>
1.165 + </varlistentry>
1.166 +
1.167 + <varlistentry>
1.168 + <term>-N nickname</term>
1.169 + <listitem>
1.170 + <para>Specify nickname of certificate to sign with (sign only).</para>
1.171 + </listitem>
1.172 + </varlistentry>
1.173 +
1.174 + <varlistentry>
1.175 + <term>-n </term>
1.176 + <listitem>
1.177 + <para>Suppress output of contents (decode only).</para>
1.178 + </listitem>
1.179 + </varlistentry>
1.180 +
1.181 + <varlistentry>
1.182 + <term>-o outfile</term>
1.183 + <listitem>
1.184 + <para>Use outfile as a destination of data (default is stdout).</para>
1.185 + </listitem>
1.186 + </varlistentry>
1.187 +
1.188 + <varlistentry>
1.189 + <term>-P</term>
1.190 + <listitem>
1.191 + <para>Include an S/MIME capabilities attribute.</para>
1.192 + </listitem>
1.193 + </varlistentry>
1.194 +
1.195 + <varlistentry>
1.196 + <term>-p password</term>
1.197 + <listitem>
1.198 + <para>Use password as key database password.</para>
1.199 + </listitem>
1.200 + </varlistentry>
1.201 +
1.202 + <varlistentry>
1.203 + <term>-r recipient1,recipient2, ...</term>
1.204 + <listitem>
1.205 + <para>
1.206 +Specify list of recipients (email addresses) for an encrypted or enveloped message.
1.207 +For certificates-only message, list of certificates to send.
1.208 + </para>
1.209 + </listitem>
1.210 + </varlistentry>
1.211 +
1.212 + <varlistentry>
1.213 + <term>-T</term>
1.214 + <listitem>
1.215 + <para>Suppress content in CMS message (sign only).</para>
1.216 + </listitem>
1.217 + </varlistentry>
1.218 +
1.219 + <varlistentry>
1.220 + <term>-u certusage</term>
1.221 + <listitem>
1.222 + <para>Set type of cert usage (default is certUsageEmailSigner).</para>
1.223 + </listitem>
1.224 + </varlistentry>
1.225 +
1.226 + <varlistentry>
1.227 + <term>-v</term>
1.228 + <listitem>
1.229 + <para>Print debugging information.</para>
1.230 + </listitem>
1.231 + </varlistentry>
1.232 +
1.233 + <varlistentry>
1.234 + <term>-Y ekprefnick</term>
1.235 + <listitem>
1.236 + <para>Specify an encryption key preference by nickname.</para>
1.237 + </listitem>
1.238 + </varlistentry>
1.239 +
1.240 + </variablelist>
1.241 +
1.242 + </refsection>
1.243 +
1.244 + <refsection id="usage">
1.245 + <title>Usage</title>
1.246 + <para>Encrypt Example</para>
1.247 + <programlisting>
1.248 +cmsutil -C [-i infile] [-o outfile] [-d dbdir] [-p password] -r "recipient1,recipient2, . . ." -e envfile
1.249 + </programlisting>
1.250 +
1.251 + <para>Decode Example</para>
1.252 + <programlisting>
1.253 +cmsutil -D [-i infile] [-o outfile] [-d dbdir] [-p password] [-c content] [-n] [-h num]
1.254 + </programlisting>
1.255 +
1.256 + <para>Envelope Example</para>
1.257 + <programlisting>
1.258 +cmsutil -E [-i infile] [-o outfile] [-d dbdir] [-p password] -r "recipient1,recipient2, ..."
1.259 + </programlisting>
1.260 +
1.261 + <para>Certificate-only Example</para>
1.262 + <programlisting>
1.263 +cmsutil -O [-i infile] [-o outfile] [-d dbdir] [-p password] -r "cert1,cert2, . . ."
1.264 + </programlisting>
1.265 +
1.266 + <para>Sign Message Example</para>
1.267 + <programlisting>
1.268 +cmsutil -S [-i infile] [-o outfile] [-d dbdir] [-p password] -N nickname[-TGP] [-Y ekprefnick]
1.269 + </programlisting>
1.270 +
1.271 + </refsection>
1.272 +
1.273 + <refsection id="seealso">
1.274 + <title>See also</title>
1.275 + <para>certutil(1)</para>
1.276 + </refsection>
1.277 +
1.278 +<!-- don't change -->
1.279 + <refsection id="resources">
1.280 + <title>Additional Resources</title>
1.281 + <para>For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at <ulink url="http://www.mozilla.org/projects/security/pki/nss/">http://www.mozilla.org/projects/security/pki/nss/</ulink>. The NSS site relates directly to NSS code changes and releases.</para>
1.282 + <para>Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto</para>
1.283 + <para>IRC: Freenode at #dogtag-pki</para>
1.284 + </refsection>
1.285 +
1.286 +<!-- fill in your name first; keep the other names for reference -->
1.287 + <refsection id="authors">
1.288 + <title>Authors</title>
1.289 + <para>The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google.</para>
1.290 + <para>
1.291 + Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey <dlackey@redhat.com>.
1.292 + </para>
1.293 + </refsection>
1.294 +
1.295 +<!-- don't change -->
1.296 + <refsection id="license">
1.297 + <title>LICENSE</title>
1.298 + <para>Licensed under the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
1.299 + </para>
1.300 + </refsection>
1.301 +
1.302 +</refentry>
