1<<if: ZXIDBOOK>> 2<<else: >>Building a Circle-of-Trust Using ZXID 3##################################### 4<<author: Sampo Kellom�ki (sampo@iki.fi)>> 5<<cvsid: $Id: zxid-cot.pd,v 1.6 2010-01-08 02:10:09 sampo Exp $>> 6<<class: article!a4paper!!ZXID-COT 01>> 7<<define: ZXDOC=Building Circles-of-Trust using ZXID>> 8 9<<abstract: 10 11ZXID.org Identity Management toolkit implements standalone SAML 2.0 and 12Liberty ID-WSF 2.0 stacks. This document explains creating CoT. 13 14>> 15 16<<maketoc: 1>> 17 181 Introduction 19============== 20 21ZXID, out of box, starts with default URL (Entity ID), metadata for 22couple of test servers, and demo certificates already configured. The 23Auto-CoT feature that automatically adds IdPs to the Circle-of-Trust 24is enabled. 25 26These are good settings for a demo, but if you want to run any serious 27operation, you will need to address the certificates, trust, and 28admission of partners to the circle of trust yourself. You will also 29need to get others to add your site to their configuration. 30 31When done for high value or liability services, all of this becomes 32rather serious business and you may want to hire a consultant to 33help getting it all right. 34 35(One day I hope this documentation is so good that no consultant 36is needed. Right now this is just a place holder.) 37 38If you are setting up zxididp, see zxid-idp.pd for more specific 39instructions. 40 411.1 Other documents 42------------------- 43 44<<doc-inc.pd>> 45 462 Metadata of Your Own Site 47=========================== 48 49Others can obtain the metadata of your site by accessing 50a URL that is the entity ID of your site, for example: 51 52 https://sp1.zxid.org/zxidhlo?o=B 53 54If they want a file, you can capture the output of the http 55operation in a file, for example 56 57 curl https://sp1.zxid.org/zxidhlo?o=B >mymeta.xml 58 wget -O mymeta.xml https://sp1.zxid.org/zxidhlo?o=B 59 60or just access the URL with web browser and save the page. 61 622 zxcot - tool 63============== 64 65 Usage: zxcot [options] [dir] 66 zxcot -a [options] [dir] <meta.xml 67 curl https://site.com/metadata.xml | zxcot -a [options] [dir] 68 zxcot -g https://site.com/metadata.xml [options] [dir] 69 zxcot -p https://site.com/metadata.xml 70 [dir] CoT directory. Default /var/zxid/cot 71 -a Add metadata from stdin 72 -g URL Do HTTP(S) GET to URL and add as metadata (if compiled w/libcurl) 73 -n Dryrun. Do not actually add the metadata. Instead print it to stdout. 74 -s Swap columns, for easier sorting by URL 75 -p ENTID Print sha1 name corresponding to an entity ID. 76 -v Verbose messages. 77 -q Be extra quiet. 78 -d Turn on debugging. 79 -h This help message 80 -- End of options 81 82 833 Auto-CoT Feature and Well Known Location Method 84================================================= 85 86Automatic Circle-of-Trust (Auto-CoT) feature allows other parties 87metadata to be automatically fetched on the fly as needed. The 88fetch is made by using the entity ID of the other party as 89a URL. This is known as the Well Known Location (WKL) method, 90see [SAML2meta] section 4.1 "Publication and Resolution via Well-Known Location", 91p.29, for normative description of this method. Auto-CoT 92makes setting up the Circle-of-Trust very easy, but has its 93drawbacks: anyone can join, connectivity between entities 94is needed, and WKL method needs to be supported and enabled in the 95partner's server. 96 97When ZXID ships, it has Auto-CoT enabled. To disable Auto-CoT, 98you need to set in your configuration string or file 99 100 MD_FETCH=0 101 1029 Circle-of-Trust: Create a Federation with Other Partners 103========================================================== 104 105<<fi: >> 106 107TBD - This chapter to be written 108 10910 Certificates and PKI Trust 110============================= 111 112*** TBD - This chapter should be elaborated to be a certificate tutorial with 113following contents: 114 115* Intro to certs and private keys 116* Generating self signed cert 117* Generating certificate signing request and using it to obtain 118 commercially issued cert 119* Installing root certs so you can recognize other people's certs 120* Client TLS considerations 121 122For the time being, the short answer is that ZXID uses OpenSSL and 123PEM format certificates. You can use same techniques as you would use for 124Apache / mod_ssl for acquiring certificates. 125 126You should NEVER password protect your private key. There will not 127be any opportunity to supply the password. You should instead protect 128your private key using Unix filesystem permissions. See OpenSSL.org 129or modssl.org FAQs for further information, including how to remove 130a password if you accidentally enabled it. 131 132<<if: ZXIDBOOK>> 133<<else: >> 134 13597 FAQ extract 136============== 137 138See zxid-faq.pd for full story. 139 140(*** These answers also appear in main FAQ in README.zxid) 141 14297.9.2 Quick command for looking at certificate 143~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 144 145Sometimes you get warning messages (in browser) or signature 146validation errors (in IdP end) because the Subject field of the 147certificate does not match your actual domain name. You can 148check this with 149 150 openssl x509 -text </var/zxid/pem/ssl-nopw-cert.pem | grep Subject: 151 152If the domain name is different, then you need to obtain a certificate 153with correct domain name, see next question. 154 15597.9.3 Self signed certificate 156~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 157 158ZXID ships with zxid.pem which gets by default copied to /var/zxid/pem 159under various different names. This is fine for testing, but disastrous 160for production or security sentitive use as the private key corresponding 161to zxid.pem certificate is of public knowledge (it is distributed with 162every copy of ZXID) - it offers no security and no non-repudiation 163what-so-ever. 164 165For production or security sensitive install you need to either 166 1671. Obtain certificates from an official certification authority, 168 usually a commercial one. ZXID uses same certificate format as 169 Apache (i.e. the pem format), so aquiring certificates is easi. Or, 170 1712. Generate your own certificate. The simplest case is a self signed 172 certificate: 173 174 openssl req -new -x509 -nodes -keyout pkey.pem -out cert.pem 175 cat cert.pem pkey.pem >/var/zxid/pem/ssl-nopw-cert.pem 176 177The cat step is there because you need to supply both certificate 178and the private key in same file for ZXID to understand it. 179 180> Warning: Although ZXID wants to see the private key in the same 181> file as the certificate, you MUST NOT give this concatenated 182> file to any outsider. Others have legitimate need to know your 183> certificate, but they MUST NOT know your private key. If they 184> ask, you should take special care to delete the private key from 185> the file prior to giving it to them. Often those who need to 186> get your certificate, actually need your metadata: just tell them 187> to fetch it from the Well Known Location URL (i.e. the Entity ID 188> of your SP). ZXID will never leak the private key to the metadata. 189 190 19196 License 192========== 193 194Copyright (c) 2006-2009 Symlabs (symlabs@symlabs.com), All Rights Reserved. 195Copyright (c) 2010-2011 Sampo Kellom�ki (sampo@iki.fi), All Rights Reserved. 196Copyright (c) 2012-2015 Synergetics (sampo@synergetics.be), All Rights Reserved. 197Author: Sampo Kellom�ki (sampo@iki.fi) 198 199Licensed under the Apache License, Version 2.0 (the "License"); 200you may not use this file except in compliance with the License. 201You may obtain a copy of the License at 202http://www.apache.org/licenses/LICENSE-2.0 203 204Unless required by applicable law or agreed to in writing, software 205distributed under the License is distributed on an "AS IS" BASIS, 206WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 207See the License for the specific language governing permissions and 208limitations under the License. 209 210<<zxid-ref.pd>> 211 212<<doc-end.pd>> 213<<notapath: TCP/IP a.k.a xBSD/Unix n/a Perl/mod_perl PHP/mod_php Java/Tomcat>> 214<<EOF: >> 215<<fi: >> 216