2004-06-09 Sebastien Pouliot <sebastien@ximian.com>

	* sn.1: Updated documentation to match the tool and to include more
	informations about the configuration kept in machine.config.

svn path=/trunk/mono/; revision=29110

diff --git a/man/sn.1 b/man/sn.1
index a0ef9f16bc834bea62324872413afee54d1a9349..3d777e27d09b2b1bbc8c6a753287a3b514f039ce 100755 (executable)
--- a/man/sn.1
+++ b/man/sn.1
@@ -1,8 +1,9 @@
 .\" 
 .\" sn manual page.
 .\" Copyright 2003 Motus Technologies
+.\" Copyright 2004 Novell
 .\" Author:
-.\"   Sebastien Pouliot (spouliot@motus.com)
+.\"   Sebastien Pouliot <sebastien@ximian.com>
 .\"
 .TH Mono "sn"
 .SH NAME
@@ -13,24 +14,33 @@ sn \- Digitally sign/verify/compare strongname on CLR assemblies.
 .SH DESCRIPTION
 Digitally sign, verify or compare, CLR assemblies using strongnames. 
 .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"
@@ -62,11 +72,14 @@ 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.
 .TP
 .I "-k keypair.snk"
-Create a new strongname keypair in the specified file.
+Create a new strongname keypair (a 1024 bits RSA keypair) in the specified 
+file.
 .TP
 .I "-R assembly keypair.snk"
 Resign the specified assembly using the specified strongname keypair file 
-(SNK).
+(SNK). You can only sign an assembly with the private key (SNK) that match 
+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.
@@ -83,10 +96,10 @@ Show the public key from the specified assembly.
 .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
@@ -104,10 +117,35 @@ Display convertion 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 let 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" needs 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 thr 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.