From b5fe7b485a78145564c0aa746b24815153bd35fe Mon Sep 17 00:00:00 2001
From: Justin Richer <jricher@mit.edu>
Date: Tue, 27 May 2014 16:04:05 -0400
Subject: [PATCH] added footer and instructions on key generation

---
 Key-generation.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++
 _Footer.md        |  3 ++
 2 files changed, 78 insertions(+)
 create mode 100644 Key-generation.md
 create mode 100644 _Footer.md

diff --git a/Key-generation.md b/Key-generation.md
new file mode 100644
index 0000000..b50575a
--- /dev/null
+++ b/Key-generation.md
@@ -0,0 +1,75 @@
+## Pepackaged keys
+
+Both the MITREid Connect server webapp and the Simple Web App client come pre-packaged with public/private RSA key pairs, found in the `keystore.jwks` file included in each project's `src/main/resources/` directory. Since these keys are the same for every clone of the repository, they are **not** suitable for use in a deployed system and **MUST** be replaced by newly generated keys.
+
+## Generating a public/private keypair
+
+You can use the [JSON Web Key Generator](https://github.com/mitreid-connect/json-web-key-generator) project to generate a JSON Web Key suitable for your installation.
+
+To generate a key, run `java -jar json-web-key-generator-0.1-SNAPSHOT-jar-with-dependencies.jar`. Several other arguments are defined which may be required depending on your key type:
+
+```
+ -a Algorithm (optional)
+ -c Key Curve, required for EC key type. Must be one of P-256, P-384, P-521
+ -i Key ID (optional) 
+ -p Display public key separately 
+ -s Key Size in bits, required for RSA and OCT key types. Must be an integer divisible by 8 
+ -S wrap output in a JWK Set
+ -t Key Type, one of: RSA, oct, EC 
+ -u Usage, one of: enc, sig (optional)
+```
+
+The most common settings are for an RSA key pair of size 1024 wrapped in a key set with a key identifier, such as `rsa1`:
+
+`java -jar json-web-key-generator-0.1-SNAPSHOT-jar-with-dependencies.jar -t RSA -s 1024 -S -i rsa1`
+
+This will output to the console a key like the following (but with a different key each time):
+
+```json
+{
+  "keys": [
+    {
+      "d": "bj_wcFHzrMVSTQJV0-DO7S7kR7z4nW3b0EyPsFrRVuzb4Vyb_G_tmcxgHG3l31V4IXH70DOYlB3FldNC0hKenNuCb4qoSZbgZxrfX9yixESIl0V5jErDXUsHau8nQN60CPivmnv535ySP8O8b1REba1gKJBx-sYhkm83jN-AFxE",
+      "e": "AQAB",
+      "n": "it4yc9J1iTP_FiOMF6ExWpqCcinQKJLm5K4nQeXh4zBJC6iBvU_b6hDdpYdH5O-bvedCA7T2OOX0yjjZu5Zqx7gYMxF2707_2McmPnLQu46oVQGJATaE-ZMe-hq1U4rnsB5CVeiGc2BG1FNEHDygDf-JhIJtn4jTNg3wO55jcxE",
+      "kty": "RSA",
+      "kid": "rsa1"
+    }
+  ]
+}
+```
+
+This JSON object is a JSON Web Key Set can be copied and pasted directly into a `keystore.jwks` file for use by the MITREid Connect `JWKSetKeyStore` class used in both the client and server.
+
+## Installing the key into a server
+The [server configuration](wiki/Server-configuration) uses the `crypto-config.xml` file to define the keys used by the server. The default configuration looks like this:
+
+```xml
+<beans xmlns="http://www.springframework.org/schema/beans"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
+
+	<bean id="defaultKeyStore" class="org.mitre.jose.keystore.JWKSetKeyStore">
+		<property name="location" value="classpath:keystore.jwks" />
+	</bean>
+	
+	<bean id="defaultsignerService" class="org.mitre.jwt.signer.service.impl.DefaultJwtSigningAndValidationService">
+		<constructor-arg name="keyStore" ref="defaultKeyStore" />
+		<property name="defaultSignerKeyId" value="rsa1" />
+ 		<property name="defaultSigningAlgorithmName" value="RS256" />
+	</bean>
+
+	<bean id="defaultEncryptionService" class="org.mitre.jwt.encryption.service.impl.DefaultJwtEncryptionAndDecryptionService">
+		<constructor-arg name="keyStore" ref="defaultKeyStore" />
+		<property name="defaultAlgorithm" value="RSA1_5" />
+		<property name="defaultDecryptionKeyId" value="rsa1" />
+		<property name="defaultEncryptionKeyId" value="rsa1" />
+	</bean>
+
+</beans>
+
+```
+
+The `defaultKeyStore` bean points to a file on disk that stores the public and private key pair in JWKS (JSON) format, such as the one generated above or included in the demo `keystore.jwks` file. This bean automatically loads the contents of the file at startup and creates a key set that can be plugged into other services. To replace the set of keys, either override the `keystore.jwks` file and replace its contents with a new key, or override the `crypto-config.xml` file and point this bean's `location` parameter to a different keystone file somewhere else on disk, such as `/etc/mitreid-connect/keystore.jwks`. 
+
+The `defaultsignerService` and `defaultEncryptionService` beans use the keys from the `defaultKeyStore` to create a set of signer/validator and encrypter/decrypter services based on those keys. These services are used in the creation of ID Tokens, access tokens, JWT-formatted outputs from the UserInfo endpoint, and processing of signed and encrypted Request Objects. The keys are also fed into the JWK publication endpoint, which publishes the public key portion of the server's JWK at `${issuer}/jwk`. 
\ No newline at end of file
diff --git a/_Footer.md b/_Footer.md
new file mode 100644
index 0000000..c799216
--- /dev/null
+++ b/_Footer.md
@@ -0,0 +1,3 @@
+---
+
+Copyright &copy;2014 [The MITRE Corporation](http://www.mitre.org/) and the [MIT Kerberos and Internet Trust Consortium](http://kit.mit.edu/). Software is available under the [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html) license. Documentation available under the [Creative Commons 3.0 By-NC](http://creativecommons.org/licenses/by-nc/3.0/) license.
\ No newline at end of file