.\"
.\" sn manual page.
.\" Copyright 2003 Motus Technologies
+.\" Copyright (C) 2004-2005 Novell, Inc (http://www.novell.com)
.\" Author:
-.\" Sebastien Pouliot (spouliot@motus.com)
+.\" Sebastien Pouliot <sebastien@ximian.com>
.\"
.TH Mono "sn"
.SH NAME
-sn \- Digitally sign/verify/compare strongname on CLR assemblies.
+sn \- Digitally sign/verify/compare strongnames on CLR assemblies.
.SH SYNOPSIS
.PP
.B sn [-q | -quiet] [options] [parameters]
.SH DESCRIPTION
-Digitally sign, verify or compare, CLR assemblies using strongnames.
+Digitally sign, verify or compare CLR assemblies using strongnames.
+.PP
+You can use the sn command to create "snk files" using the -k option
+described below.
.SH CONFIGURATION OPTIONS
+Configuration options are stored in the machine.config configuration file
+under /configuration/strongNames.
.TP
.I "-c provider"
-Change the default CSP (Crypto Service Provider).
+Change the default CSP (Crypto Service Provider). Currently not supported
+in Mono.
.TP
.I "-m [y|n]"
-Use a machine [y] key container or a user [n] key container.
+Use a machine [y] key container or a user [n] key container. Currently not
+supported in Mono.
.TP
.I "-Vl"
-List the verification options.
+List the verification options. The list is kept under /configuration/
+strongNames/verificationSettings in machine.config.
.TP
.I "-Vr assembly [userlist]"
Exempt the specified assembly from verification for the specified user list.
+Currently not supported by sn. You must edit machine.config manually if you
+require this.
.TP
.I "-Vu assembly"
-Remove the exemption entry for the specified assembly.
+Remove the exemption entry for the specified assembly. Currently not
+supported by sn, you must edit machine.config manually if you require this.
.TP
.I "-Vx"
-Remove all exemptions entries.
+Remove all exemptions entries. Currently not supported by sn, you must edit
+machine.config manually if you require this.
.SH CSP RELATED OPTIONS
.TP
.I "-d container"
.TP
.I "-pc container publickey"
Export the public key from the specified CSP container to the specified file.
-.SH CONVERTION OPTIONS
+.SH CONVERSION OPTIONS
.TP
.I "-e assembly output.pub"
Export the assembly public key to the specified output file.
.TP
.I "-p keypair.snk output.pub"
-Export the public key from the specified strongname key file (SNK) to the
-specified output file.
+Export the public key from the specified strongname key file (SNK) or from
+a PKCS#12/PFX password protected file to the specified output file.
.TP
.I "-o input output.txt"
Convert the input file to a CSV file (using decimal).
.SH STRONGNAME SIGNING OPTIONS
.TP
.I "-D assembly1 assembly2"
-Compare if assembly1 and assembly are the same exception for their signature.
-This is done by comparing the hash of the metadata of both assembly.
+Compare if assembly1 and assembly2 are the same except for their signature.
+This is done by comparing the hash of the metadata of both assemblies.
.TP
-.I "-k keypair.snk"
-Create a new strongname keypair in the specified file.
+.I "-k [size] keypair.snk"
+Create a new strongname keypair in the specified file. The default key
+length is 1024 bits and MUST ALWAYS be used when signing 1.x assemblies.
+Any value from 384 to 16384 bits (in increments of 8 bits) is a valid key
+length to sign 2.x assemblies. To ensure maximum compatibility you may
+want to continue using 1024 bits keys. Note that there's no good reason,
+even if it's possible, to use length lesser than 1024 bits.
.TP
.I "-R assembly keypair.snk"
-Resign the specified assembly using the specified strongname keypair file
-(SNK).
+Re-sign the specified assembly using the specified strongname keypair file
+(SNK) or a PKCS#12/PFX password protected file. You can only sign an
+assembly with the private key that matches the public key inside the assembly
+(unless it's public key token has been remapped in machine.config).
.TP
.I "-Rc assembly container"
-Resign the specified assembly using the specified strongname container.
+Re-sign the specified assembly using the specified strongname container.
.TP
.I "-t file"
-Show the public key from the specified file.
+Show the public key token from the specified file.
.TP
.I "-tp file"
Show the public key and the public key token from the specified file.
.TP
.I "-T assembly"
-Show the public key from the specified assembly.
+Show the public key token from the specified assembly.
.TP
.I "-Tp assembly"
Show the public key and the public key token from the specified assembly.
.TP
-.I "-V assembly"
+.I "-v assembly"
Verify the specified assembly signature.
.TP
-.I "-Vf assembly"
+.I "-vf assembly"
Verify the specified assembly signature (even if disabled).
.SH HELP OPTIONS
.TP
Display Cryptographic Service Provider related help about this tool.
.TP
.I "-h convert", "-? convert"
-Display convertion related help about this tool.
+Display conversion related help about this tool.
.TP
.I "-h sn", "-? sn"
Display strongname related help about this tool.
+.SH CONFIGURATION FILE
+.TP
+Strongnames configuration is kept in "machine.config" file. Currently two
+features can be configured.
+.TP
+.I "/configuration/strongNames/pubTokenMapping"
+This mechanism lets Mono remap a public key token, like the ECMA token, to
+another public key for verification. This is useful in two scenarios. First,
+assemblies signed with the "ECMA key" need to be verified by the "runtime"
+key (as the ECMA key isn't a public key). Second, many assemblies are signed
+with private keys that Mono can't use (e.g. System.Security.dll assembly).
+A new key cannot be used because it should change the strongname (a new key
+pair would have a new public key which would produce a new token). Public
+key token remapping is the solution for both problems. Each token must be
+configured in a "map" entry similar to this one: <map Token="b77a5c561934e089"
+PublicKey="00..." />
+.TP
+.I "/configuration/strongNames/verificationSettings"
+It is often useful during development to use delay signed assemblies.
+Normally* the runtime wouldn't allow delay-signed assemblies to be loaded.
+This feature allows some delay-signed assemblies (based on their public key
+token, optionally assembly name and user name) to be used like they were
+fully signed assemblies. [*] Note that Mono 1.0 "runtime" doesn't validate
+strongname signatures so this option shouldn't be required in most scenarios.
.SH AUTHOR
Written by Sebastien Pouliot
.SH COPYRIGHT
Copyright (C) 2003 Motus Technologies.
+Copyright (C) 2004 Novell.
Released under BSD license.
.SH MAILING LISTS
-Visit http://mail.ximian.com/mailman/mono-list for details.
+Visit http://lists.ximian.com/mailman/listinfo/mono-list for details.
.SH WEB SITE
-Visit: http://www.go-mono.com for details
+Visit http://www.mono-project.com for details
.SH SEE ALSO
.BR secutil(1)