1<<if: ZXIDBOOK>> 2<<else: >>ZXID Signed and Encrypted Logging Facility 3########################################## 4<<author: Sampo Kellom�ki (sampo@iki.fi)>> 5<<cvsid: $Id: zxid-log.pd,v 1.11 2010-01-08 02:10:09 sampo Exp $>> 6<<class: article!a4paper!!ZXID-LOG 01>> 7<<define: ZXDOC=ZXID Signed and Encrypted Logging Facility>> 8 9<<abstract: 10 11ZXID.org Identity Management toolkit implements standalone SAML 2.0 and 12Liberty ID-WSF 2.0 stacks. The logging module described in this 13document allows various degrees of digital signing and encryption 14to be configured to ensure tamperproofness and confidentiality 15of the logs. Of course such operations come at a cost. 16 17>> 18 19<<maketoc: 1>> 20 211 Introduction 22============== 23 24All ZXID logging is filesystem based and consists mainly of text files 25to which lines are appended. This document describes the filesystem 26layout for other purposes as well (to keep it all in one place, but 27see also zxid-idp.pd). The logging system has also some tactical uses, 28such as detecting duplicate messages and assertions - within validity 29period, they are detected by checking if corresponding blob log 30already exists. 31 321.1 Other documents 33------------------- 34 35<<doc-inc.pd>> 36 371.2 Logging API 38--------------- 39 40The logging API is further described in the 41full <<link:ref/html/index.html: ZXID API Reference>>, which see. 42In summary, the logging functions are 43 44 int zxlog_dup_check(struct zxid_conf* cf, struct zx_str* path, char* logkey); 45 46 int zxlog_blob(struct zxid_conf* cf, int logflag, struct zx_str* path, struct zx_str* blob, char* lk); 47 48 int zxlog(struct zxid_conf* cf, struct timeval* ourts, struct timeval* srcts, char* ipport, struct zx_str* entid, struct zx_str* msgid, struct zx_str* a7nid, struct zx_str* nid, char* sigval, char* res, char* op, char* arg, char* fmt, ...); 49 50of which zxlog() is by far the most used. A typical invocantion could be 51 52 // 1 2 3 4 5 6 7 8 9 10 11 12 13 14 53 zxlog(cf, 0, 0, 0, 0, 0, 0, 0, "N", "B", "ERR", cgi->eid, "Desc %s", foo); 54 55Where 56 57cf (1):: ZXID configuration object, used for configuration options 58 and memory allocation 59ourts (2):: Timestamp as observed by localhost. Typically the wall clock 60 time. See gettimeofday(3) 61srcts (3):: Timestamp claimed by the message to which the log entry pertains 62ipport (4):: IP address and port number from which the message appears 63 to have originated 64entid (5):: Entity ID to which the message pertains, usually the issuer. 65 Null ok. 66msgid (6):: Message ID, can be used for correlation to establish audit 67 trail continuity from request to response. Null ok. 68a7nid (7):: Assertion ID, if message contained assertion (outermost and first 69 assertion if there are multiple relevant assertions). Null ok. 70nid (8):: Name ID pertaining to the message 71sigval (9):: Signature validation letters 72res (10):: Result letters 73op (11):: Operation code for the message 74arg (12):: Operation specific argument 75fmt, ... :: Free format message conveying additional information 76 77 784 Logging and Audit 79=================== 80<<fi: >> 81 82N.B. zxidconf.h contains a wealth of logging related config options, see 83<<link:html/zxid-conf.html: ZXID Configuration Reference>> 84 85> Tip: Your web server also has logging options. You may want 86> to correlate the web server logs with zxid audit logs. 87 88In serious use of SSO and web services it is fundamental that the 89relying party, the SP, WSC, or WSP, archives the digitally signed 90evidence that justifies its actions. Generally this means that, at 91least, the SSO or credential assertions have to be archived. Quite 92often, especially in the WSC world, the entire SOAP response (which 93may be partially signed) needs to be preserved as a proof of an 94authorized action or attested attributes. 95 96To lesser extent, it is also important that the issuing party, the IdP 97(or sometimes the DS, PS, WSC, or WSP), keeps records so that it can 98confirm or refute the claims of the relying party -- in the minimum it 99should be able to refute any obviously false claim and it should be 100able to detect breaches of its own security arrangements, 101e.g. situations where somebody is signing messages in its name 102although internal audit trail demonstrates this to be impossible (it 103is important to be able to compare independent audit trails). The IdP 104audit trail consists of preserving any (signed) request made by anyone 105as well as preserving every (signed) response it makes. 106 107Generally every assertion, request, and response will have its unique 108ID that can be used as the primary key, or filename, for storing it in 109a database. Unfortunately these namespaces<<footnote: Namespace, as 110used here, has nothing to do with XML namespaces.>> are not disjoint 111(it is not very well specified in any of the standards how they 112interact or how wide their uniqueness properties are).<<footnote: Many 113rational implementations use 128 bit random identifiers, which 114statistically guarantees that there will not be collisions, but 115unfortunately we can not rely on other parties to adopt this 116reasonable behaviour.>> The only safe assumption is the pessimistic one: each 117type of object observes a unique namespace only towards its issuer and 118type and hence we need to map such namespaces to subdirectories. 119 1204.1 Filesystem Layout for Logs 121------------------------------ 122 123Please consider following layout of the log directory at SP (or IdP, 124but see zxid-idp.pd for more detail): 125 126 /var/zxid/ 127 | 128 +-- zxid.conf Main configuration file 129 +-- pem/ Our certificates 130 +-- cot/ Metadata of CoT partners (metadata cache) 131 +-- ses/ Sessions (see refinement in Sesstion Storage section) 132 `-- log/ Log files, pid files, and the like 133 | 134 +-- issue/ 135 | | 136 | +-- SHA1NAME/ Evidence issued to entity is kept in directory named after entity ID 137 | | | 138 | | +-- a7n/ Assertions issued to the given 3rd party, named by AssertionID 139 | | +-- msg/ Messages of any type issued to the given 3rd party, named by MessageID 140 | | `-- wir/ Wire messages, such as redirects, and posts (e.g. POST SimpleSign) 141 | ... 142 | `-- SHA1NAME2/ Evidence issued to another entity ID 143 | 144 +-- rely/ 145 | | 146 | +-- SHA1NAME/ Evidence from entity is kept in directory named after entity ID 147 | | | 148 | | +-- a7n/ Assertions from 3rd parties, named by AssertionID 149 | | +-- msg/ Messages of any type from 3rd parties, named by MessageID or sha1 150 | | `-- wir/ Wire messages, such as redirects, and posts (e.g. POST SimpleSign) 151 | ... 152 | `-- SHA1NAME2/ Evidence from another entity ID 153 | 154 +-- tmp/ Subdirectory used for atomic operations � la Maildir 155 +-- act Global activity log 156 +-- err Global error log 157 `-- debug Global debugging log 158 159The Audit Bus will log its messages and acknowledgements in its own hierarchy, 160typically under /var/zxid/bus. See Audit Bus documentation (and source) for 161further documentation. 162 1634.2 ZXID Log Format 164------------------- 165 166The log file is line oriented, one record per line irrespective of 167line length, and plain text: binary data is generally omitted (perhaps 168the blob file name will be referenced) or represented as (safe) 169base64. Fields are separated by exactly one space character (0x20), 170except for the last free format field. Records are separated by 171exactly one new line (0x0a) character (never by CRLF sequence, but 172analysis tools should tolerate the CRLF as well due to braindamaged 173OSs that perform conversions unknown to the user). 174 175The log file format supports 176 1771. Plain text logging 1782. Signed plain text logging using either RSA-SHA1 or DSA-SHA1 (more algos?) 1793. Symmetrically encrypted logging using either 3DES or AES (more algos?) 1804. Asymmetrically encrypted logging using RSA (or DSA?) 1815. Signed and symmetrically encrypted logging 1826. Signed and Asymmetrically encrypted logging 183 184All activity and error log file lines have the following format (any one of the 4): 185 186 # comment 187 SE HH CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC 188 SE HH SIG OURTS SRCTS IP:PORT SUCCEID MID A7NID NID MM VVV RES OP PPP FMT 189 SE HH SSS OURTS SRCTS IP:PORT SUCCEID MID A7NID NID MM VVV RES OP PPP FMT 190 191<<ignore: 192 193PP - 20070929-041314.599 20070929-121312.501 0.0.0.0:0 zIDxx57qGA-qwnsymUf4JD0Er2A - A7NHKJdRVk8P_WNEV-RFqB4 PT7cP8WWiZy3g3jCTDciT G K FEDSSO - - 194 195PP - 20070929-041314.599 - 0.0.0.0:0 - - - - N K GETMD https://s-xtra.liberty-iop.org:8443/zxidgsa?o=B time 237ms 196 197 SE SSS OURTS SRCTS IP:PORT VVV RES OP SUCCENTID MSGID A7NID NID PPP FMT 198 199PP - 20070929-041314.599 20070929-121312.501 0.0.0.0:0 G K FEDSSO zIDxx57qGA-qwnsymUf4JD0Er2A - A7NHKJdRVk8P_WNEV-RFqB4 PT7cP8WWiZy3g3jCTDciT - - 200 201PP - 20070929-041314.599 - 0.0.0.0:0 N K GETMD https://s-xtra.liberty-iop.org:8443/zxidgsa?o=B time 237ms 202 203>> 204 205where 206 207SE:: Log signing and encryption designator. In all cases 208 the actual signing or encryption key is not identified on the log line. 209 This will need to be determined out-of-band, typically using SAML2 metadata. 210 211 PP:: PlainPlain: not signed and not encrypted 212 Rx:: RSA-SHA1 signed (x = any encryption) 213 Dx:: DSA-SHA1 signed 214 Sx:: SHA1 check-summed, but not signed (SSS is the checksum) 215 xA:: Asymmetrically AES encrypted (x = any signing method, same meth for assymmetrical-enc) 216 xT:: Asymmetrically 3DES encrypted 217 xB:: Symmetrically AES encrypted (theoretical: how to safeguard the key?) 218 xU:: Symmetrically 3DES encrypted (theoretical: how to safeguard the key?) 219 xZ:: [RFC1951] zipped (not really encryption) 220 Xxx:: Experimental arrangements. 221 222HH:: HMAC chaining code to previous message, to protect against log line 223 deletion. If not used, this will be "-". 224 225CCCC:: Safe base64 encoded log encryption blob. In case of encryption blob, 226 the rest of the log fields will not appear. Decrypted logline will contain 227 fields starting from SSS. 228 229SIG:: Safe base64 encoded log line signature blob. If no signature, this is 230 a dash ("-"). 231 232OURTS:: Our time stamp, format YYYYMMDD-HHMMSS.TTT where TTT are the 233 milliseconds. The time is always in GMT (UTC, Zulutime). 234 235SRCTS:: Source time stamp, format YYYYMMDD-HHMMSS.TTT. If TTT was not 236 originally specified it is represented as "501". The time is always 237 in GMT (UTC, Zulu-time). 238 239IP:PORT:: The IP address and the port number of the other end point (usually 240 client, but could be spoofed, caveat emptor). 241 242SUCCEID:: The SHA1 name of the entity (succinct entity ID without the 243 equals sign). 244 245MID:: Message ID relating to the log line. Allows message to be fetched from 246 the database or the file system. Any relates-to or similar ID is only 247 available by fetching the original message. Dash ("-") if none. 248 249A7NID:: Assertion ID relating to the log line. Allows assertion to be fetched 250 from the database or the file system. If message benefits from multiple 251 assertions, this is the one relating to the outermost one. Other A7NIDs 252 are only available by fetching the original assertion. Dash ("-") if none. 253 If the assertion is encrypted and can not be decrypted, then 254 placehoder "-enca7n-" is used. 255 256NID:: IdP assigned NameID relating to the message, if any. If the NameID is 257 encrypted and can not be decrypted, then placeholder "-encnid-" is used. 258 259MM:: Module or subsystem indicator (e.g. discriminate between SP and IdP 260 that log to same file) 261 262VVV:: Signature validation codes (*** among VVV and RES still avail HJLQYZ) 263 U:: Signature issued ("Underwritten" - getit?). 264 O:: Capital Oh (not zero). All relevant signatures validate (generally assertion) 265 A:: Unsupported or bad signature or message digest algorithm 266 G:: Checksum of XML DSIG does not validate 267 R:: The RSA layer of the signature does not validate 268 N:: No signature detected (or issued) or expected or not applicable. 269 M:: Malformed signature, e.g. SignedInfo or Reference missing 270 I:: Issuer metadata not found (or not in CoT, or corrupt metadata). 271 V:: Assertion validity error (e.g. not in time range or wrong audience) 272 F:: Operation failed or faulted by error code (low level protocol ok) 273 Exx:: Extended signature validation code (generally error or failure) 274 Xxx:: Experimental signature validation code (generally failure) 275 276RES:: Result of the operation. 277 K:: Operation was success 278 C:: Operation failed because client did not provide valid input 279 S:: Operation failed due to server side error 280 P:: Operation failed due to policy or permissions issue 281 T:: Temporary error, client was encouraged to retry 282 B:: Metadata related error (no metadata or parse error in metadata) 283 D:: Redirect or recredential. Client was encouraged to retry. 284 W:: Way point message. Neither success nor failure. 285 Exx:: Extended result (generally error or failure) 286 Xxx:: Experimental result (generally failure) 287 288OP:: The documented operation 289 290 FEDNEW:: New federation was created (usually due to SSO or discovery). 291 FEDSSO:: SP SSO using federated ID was performed 292 TMPSSO:: SP SSO using transient NameID was performed 293 IFSSO:: IdP SSO using federated ID was issued 294 ITSSO:: IdP SSO using transient NameID was issued 295 NEWSES:: SP new session 296 INEWSES:: IdP new session 297 PNEWSES:: WSP new session 298 SLO:: Single Logout was completed (SP) 299 ISLO:: Single Logout completed (IdP) 300 DEFED:: Defederation was performed 301 BADCF:: Server configuration (/var/zxid/zxid.conf) is bad 302 NOMD:: No metadata found after options exhausted (cache, fetch from net) 303 BADMD:: Metadata parsing error 304 BADXML:: XML parsing error in protocol 305 SAMLFAIL:: SAML call failed (often SOAP call) 306 EMISS:: Missing element (in otherwise correct XML) 307 EFILE:: File missing, wrong permissions, corrupt content. Install errors. 308 ECRYPT:: Crypto or signature error, usually due to corrupt or wrong key. 309 EDUP:: Duplicate message. Suspect replay attack. 310 ERR:: Other error 311 312 For WSP the OP is the command verb that was exercised. 313 314 FEDDI:: Discovery: Issue of EPR with assertion using federated NameID 315 TMPDI:: Discovery: Issue of EPR with assertion using transient NameID 316 DIOK:: Summary status of successful discovery on server side 317 VALID:: Message was validated OK and accepted for processing. See zxid_wsp_validate() 318 DECOR:: Message was decorated and issued, see zxid_wsp_decorate() 319 CGIRESP:: Notification of issued message written in local audit trail 320 321 For WSC the OP is the command verb preceded by capital C, e.g. "CQuery". 322 323 Additional OP verbs may need to be specified for protocol substeps like 324 artifact resolution (ART) and direct authentication (AUTH). 325 326 ART:: Artifact resolution request sent with SOAP (1) 327 ANREDIR:: Redirection with Authentication Request 328 LOCLO:: Local Logout (1) 329 330 SLOREDIR:: Redirection with Single Logout Request 331 SLORESREDIR:: Redirection with Single Logout Response 332 MNIREDIR:: Redirection with Manage NameID Request for changing NameID 333 DEFEDREDIR:: Redirection with Manage NameID Request for defederation 334 335 SLOSOAP:: Single Logout Request SOAP call made 336 MNISOAP:: Manage NameID Request for changing NameID SOAP call 337 DEFEDSOAP:: Manage NameID Request for defederation SOAP call 338 SAMLOK:: SAML call OK (often SOAP call) 339 340 Additional OP verbs may need to be specified for other logging operations 341 like regular web access logs (HEAD, GET, POST). 342 343 IDPSEL:: IdP Selection screen is shown (2) 344 MGMT:: Management screen is shown (2) 345 SHOWPC:: Logged in (by SSO or session). Show protected content. arg is sid. (1) 346 SPDISP:: SP Command Dispatch (received POST or redir) (2) 347 IDPDISP:: IdP Command Dispatch (received POST or redir) (2) 348 MYMD:: My metadata was served to requester on the net (1) 349 GETMD:: Getting metadata from net (2) 350 GOTMD:: Got metadata from net (1) 351 BADCGI:: Unknown CGI options (0, but not implemented yet) 352 REDIRDEC:: Redirect or POST Bindong decoding 353 ANREDIR:: Authentication redirect 354 AUTHN:: Authentication 355 SSOA7N:: Issuance of SSO Assertion 356 SSORESP:: Issuance of SSO response 357 DIA7N:: Issuance of Discovery Assertion 358 DIRESP:: Issuance of Discovery response 359 360 KEYGEN:: Auto-Cert generation of a self-signed certificate 361 NEWUSR:: New user creation 362 363 OAUTH2 and UMA related 364 365 DCR:: Dynamic Client Registration 366 367PPP:: Operation dependent one most relevant parameter. Dash ("-") if none. 368 369FMT:: Operation dependent free-form data. May contain spaces. Dash ("-") if 370 none. 371 3724.3 Log Signing and Encryption 373------------------------------ 374 375Logs are enabled in the config file zxidconf.h (compile time) by ZXLOG 376macros which provide default values for the log flags in ~struct 377zxid_conf~. Each log flag is a bitmask of signing and encryption 378options. Zero value means no logging. "1" can be used to enable 379plain text logging. 380 381Log signing may help you to argue that log evidence was (not) tampered 382with. You can configure the signing level in the config file 383zxidconf.h (compile time): 384 3850:: no signing (Px) 3862:: sha1 MD only (Sx) 3874:: RSA-SHA1 (Rx) 3886:: DSA-SHA1 (Dx) 389 390For actual signing (options 4 and 6), the private key for signing must 391be available in /var/zxid/pem/logsign-nopw-cert.pem. Note that this 392file need not contain the actual certificate (but it may, it just will 393be ignored). 394 395The weak point of log signing is that if the private key is stolen, 396then someone can create falsified logs and the private key needs 397to be available on the point where the logs are generated - thus 398it is actually quite vulnerable as these might be very forward 399positioned servers. 400 401Log encryption may help to keep the logs confidential. You can 402configure the configuration level in the config file zxidconf.h 403(compile time): 404 4050x00:: no encryption (xP) 4060x10:: [RFC1951] zip - safe-base64 [RFC3548] (xZ) 4070x20:: RSA-AES (xA) 4080x30:: RSA-3DES (xT) 4090x40:: Symmetric AES (xB) 4100x50:: Symmetric 3DES (xU) 411 412For RSA modes the public key for encryption must be available 413in /var/zxid/pem/logenc-nopw-cert.pem. Note that the +private 414key+ should *NOT* be kept in this file: the whole point of 415public key encryption is that even if your server machine 416is stolen, the bad guys can't access the logs - if the 417private key was anywhere in the stolen machine, they will 418find it. 419 420For symmetric encryption the key is the SHA1 hash of file 421/var/zxid/pem/logenc.key. Obviously this key must be kept secret, 422but see the caveat about stolen machine in the previous paragraph. 423 424All encryption modes, except for 0, [RFC1951] zip compress the log line 425before encryption and safe-base64 encode the result of the 426encryption. All encryption modes, except 0 and 1, prefix the zipped log 427line with 128 bit nonce before encrypting. 428 429The algorithm is roughly (see source for detail): 430 4311. If encrypt, zip the raw log line 4322. If sign, compute the signature (over zipped version if applicable) 4333. Prepend signature blob to log line. If encrypting, the signature 434 is embedded in binary form, otherwise it is embedded in safe-base64 form. 4354. If encrypt, perform the encryption. 4365. If encrypt, apply safe-base64. 437 438The supplied tool zxlogview(1) allows the logs to be decrypted and the 439signatures verified. 440 441 ./zxlogview logsign-nopw-cert.pem logenc-nopw-cert.pem <some-log-lines 442 443Note that for zxlogview(1) to work the logsign-nopw-cert.pem needs to 444contain the public key (and need not contain the privatekey) which is 445the opposite of the situation what zxid(1) needs to see in order to 446sign. Similarly logenc-nopw-cert.pem needs to contain the private key 447(and may contain the certificate, though this will not be used). 448 449> N.B. While encrypted logs are cool, you should evaluate the 450> gain against the incovenience: if you encrypt them, the lesser 451> mortal sysadmins may not be able to debug your installation 452> because they do not know how to decrypt logs or you are not 453> willing to trust them with the keys. For this reason, you 454> can configure the encryption of error log separately. 455 4564.4 Internal Crypto Formats 457--------------------------- 458 459For [RFC1951] zipped safe-base64 [RFC3548] output the input to base64 encoding is 460 461 LLSSSSZZZZZZZZZZZZZZ -- RFC1951 zipped safe-base64 462 463For encrypted modes the input to AES (or other symmetric cipher) is 464 465 NNNNLLSSSSZZZZZZZZZZ -- Note how nonce is prepended 466 467The NNNN is used as initialization vector and actual encryption 468encompasses LL, SSSS, and ZZZZ. 469 470In RSA-AES the session key is encrypted using RSA and prepended 471to the input for base64 encoding. 472 473 KKEEEECCCCCCCCCCCCCC -- RSA-AES: note prepended session key 474 475NNNN:: 16 bytes of nonce. This is used as initialization vector 476 for AES or 3DES cipher operated in CBC mode. 477LL:: Bigendian integer representing signature length in bytes. 478 0 means none. Negative values reserved for future use. 479SSSS:: The signature in binary 480ZZZZ:: [RFC1951] zipped safe-base64 [RFC3548] of the payload 481KK:: Bigendian integer representing encrypted session key 482 length in bytes. Negative values are reserved for future use. 483EEEE:: RSA encrypted session key in binary 484CCCC:: Ciphertext from the symmetric cipher, including nonce. 485 486In RSA operations RSA_PKCS1_OAEP_PADDING padding is used (PKCS #1 v2.0). 487 4884.5 Logging Assertions 489---------------------- 490 491Logging of assertions is controlled by configuration options 492ZXLOG_ISSUE_A7N and ZXLOG_RELY_A7N. At least ZXLOG_RELY_A7N should be 493turned on for ID-WSF web services to work correctly. Logging relied 494assertions also allows detection of duplicate assertion IDs. Logging, 495or not, of issued assertions does not have any operational effect and 496is only for audit trail purposes. 497 498Assertions are logged in directories depending on issuer's sha1 name. 499 500 /var/zxid/log/rely/ISSUER-SHA1-NAME/a7n/A7N-ID-AS-SHA1 501 502Sha1 names are used to avoid any attack through issuer entity ID or 503the assertion ID being evilly crafted to contain shell metacharacters 504or filesystem significant characters. 505 506Assertions issued by ourselves follow the pattern 507 508 /var/zxid/log/issue/DEST-SHA1-NAME/a7n/A7N-ID-AS-SHA1 509 510If the logfile starts by less-than character ("<" - from XML opening 511tag) then it is in plain text. Encrypted or signed formats will start 512in another way, but are not specified at this time. 513 514N.B. The relied-on assertions may be referenced from session objects 515and used in construction of credentials for ID-WSF based web services 516calls. Therefore the rely directory should not be cleaned too 517aggressively: the assertions must remain there until the referencing 518session expires. 519 5204.6 Logging Requests and Responses 521---------------------------------- 522 523Logging of requests and responses is controlled by ZXLOG_ISSUE_MSG and 524ZXLOG_RELY_MSG. Logging, or not, messages has no operational effect 525and is only for audit trail purposes. If logging of relied messages is 526turned on, then it is possible to detect duplicate message IDs. 527 528Request messages are logged in directories depending on issuer's sha1 name. 529 530 /var/zxid/log/rely/ISSUER-SHA1-NAME/msg/REQ-ID-AS-SHA1 531 532Sha1 names are used to avoid any attack through issuer entity ID or 533the assertion ID being evilly crafted to contain shell metacharacters 534or filesystem significant characters. 535 536Responses issued by ourselves follow similar pattern 537 538 /var/zxid/log/issue/DEST-SHA1-NAME/msg/RESP-ID-AS-SHA1 539 540If the logfile starts by less-than character ("<") then it is in 541plain text. Encrypted or signed formats will start in another way, 542but are not specified at this time. 543 5444.7 Session Storage and Bootstraps 545---------------------------------- 546 547The ZXID session system serves three purposes: 548 5491. Remember whether user has logged in. The session ID is carried 550 either in a cookie or as part of the URL. 551 5522. Make it possible to perform Single Logout (SLO) and 553 certain federation management tasks. 554 5553. Remember the service end points (EPRs) that were either 556 557 a. supplied as bootstrap attributes in the SSO assertion, or 558 559 b. later discovered 560 561The biggest complication is the requirement to remember the EPRs and 562the solution currently used is to keep them as files in a per session 563directory under the /var/zxid/ses tree. 564 565 /var/zxid/ 566 | 567 +-- zxid.conf Main configuration file 568 +-- pem/ Our certificates 569 +-- cot/ Metadata of CoT partners (metadata cache) 570 +-- ses/ Sessions 571 | | 572 | +-- SESID/ Each session has its own directory 573 | | 574 | +-- .ses The session file 575 | `-- SVC,SHA1 Each bootstrap is kept in its own file 576 | 577 +-- user/ Local user accounts (if enabled) 578 | | 579 | +-- SHA1/ Each local user has a directory whose name is SHA1 580 | | | of the user's NameID (idpnid) and IdP Entity ID 581 | | +-- .mni Information needed by Name ID management 582 | | +-- PS,SHA1 Long term People Service EPR, kept in its own file 583 | | +-- .deleg/ Delegations (invitations) user has issued 584 | | | | 585 | | | +-- DELEG 586 | | | `-- DELEG 587 | | | 588 | | +-- .access/ Invitations user has received (delegations to access other's resources) 589 | | | | 590 | | | +-- ACCESS 591 | | | `-- ACCESS 592 | | | 593 | | +-- .bs/ Local user attribute directory 594 | | | | 595 | | | `-- .at Local user attributes as LDIF (see zxid_ses_to_pool()) 596 | | | 597 | | `-- .pw User's local password if any (usually none) 598 | | 599 | `-- SHA1b -> ../uid/Sue SHA1 can also be symlink to local account 600 | 601 +-- uid/ Local user ID (local login name) to SHA1 mapping 602 | | 603 | +-- joe -> ../user/SHA1 Symlink points to the real user directory 604 | +-- Sue/ Local user can have directory whose name is the uid 605 | | 606 | +-- .mni Information needed by Name ID management 607 | `-- .pw User's local password if any (usually none) 608 | 609 | 610 `-- log/ Log files, pid files, and the like 611 6124.7.1 Session directory 613~~~~~~~~~~~~~~~~~~~~~~~ 614 615The session ID is an unguessable (but see ID_BITS configuration 616options) safe base64 encoded pseudorandom number. Unguessability 617ensures that the session can only be crated via SSO. 618 619The service EPRs are XML documents whose name is composed from 620two components 621 622 SVC,SHA1 623 624SVC:: The service type URI, with file system unsafe characters 625 (e.g. "/" and ",") folded to underscore ("_"). Purpose of 626 the SVC is to allow quick identification, without opening, 627 of the files that contain EPRs for a given service type. 628 Only first 200 bytes of the service type are used. 629SHA1:: safe base64 encoded SHA1 hash of the content of the EPR. The 630 purpose of the SHA1 hash is to produce a unique identifier 631 so that two distinct EPRs for same service will have 632 different file names. 633 634The session directory also contains .ses file. The first line 635is as follows (still subject to change, Oct 2007): 636 637 NameID|a7n-ref 638 639The pipey symbol (|) is a field separator. Future versions 640may define further fields beyound these original two. All other 641lines are reserved for future expansion. Fields: 642 643NameID:: NameID, extracted during SSO 644a7n-ref:: Filesystem path to the SSO assertion. 645 6464.7.2 User directory (user/) 647~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 648 649User directories are used for storage of +local account+ information. 650Since many web applications, to which ZXID may be integrated, already 651have their own local user storage, the ZXID user directory is optional, 652see USER_LOCAL configuration option. 653 654IdP initiated ManageNameID requests depend on local user accounts, so 655if you want this to work you need to enable them. Local user account 656management may be useful on its own right if your application does not 657yet have such system. If it has, you probably want to continue to use the 658application's own system. 659 660Another functionality that needs the local user accounts is delegation 661using people service. In this case the invitations / delegations and 662PS-EPR of the user are remembered. 663 664Each user is represented by a directory whose filename is safe base64 665of the SHA1 hash of the user's NameID and the IdP's Entity ID. The directory can actually 666be a symlink to some other place, such as uid/ directory, see below. 667 668Inside the directory, a file called .mni captures the information 669needed for NameID Management. It is expected that other files 670about the user may be populated to capture other aspects. Your own 671applications could even create files here. 672 673The first line of the .mni file is as follows 674 675 FMT|IDPEnt|SPqual|NameID|MNIptr 676 677The pipey symbol (|) is a field separator. Future versions 678may define further fields beyound these original two. All other 679lines are reserved for future expansion. Fields: 680 681FMT:: NameID Format 682IDPent:: IdP entity ID that qualifies the NameID (namespace if you like). 683 This usually corresponds to the NameQualifier of <NameID> 684SPqual:: SP entity or affilitation ID (optionally) sent by IdP. This 685 further qualifies the namespace of the Name ID. 686NameID:: NameID of the account 687MNIptr:: If NameID Management has been used to change the 688 IdP assigned NameID, then the new NameID. There will be 689 a local user account directory for the new NameID. Consider 690 this as a sort of symlink functionality. 691 6924.7.3 Local UID Directory (uid/) 693~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 694 695The main purpose of the local uid/ directory is to support local 696logins. Since the main objective of ZXID is to support Single Sign On, 697there should be little need to support local logins. Hence uid/ 698directory is optional. 699 700Often uid/ directory is implemented by providing symlinks to the 701user/ directory. In this case uid/ only acts as an index or 702mapping from local UID to the safe base64 encoded SHA1 of the IdP 703assigned Name ID, see above. 704 7054.7.4 IdP Use of Local UID Directory (uid/) 706~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 707 708zxididp uses local uid/ directory to implement the IdP logins and 709to store users federations, bootstraps, and attributes. 710 711 /var/zxid/ 712 | 713 +-- idpzxid.conf Main configuration file 714 +-- idppem/ Our certificates 715 +-- idpcot/ Metadata of CoT partners (metadata cache) 716 +-- idpses/ Sessions 717 | | 718 | +-- SESID/ Each session has its own directory 719 | | 720 | +-- .ses The session file 721 | `-- SVC,SHA1 Each bootstrap is kept in its own file 722 | 723 +-- idpuid/ Local user ID (local login name) to SHA1 mapping 724 | | 725 | +-- JOE/ Local user has directory whose name is the login uid 726 | | | 727 | | +-- .log Log of operations regarding the user 728 | | +-- .pw User's local password 729 | | +-- .yk User's yubikey shared aes128 secret in hex 730 | | +-- .ykspent/ Cache of already used One TIme Passwords 731 | | | | 732 | | | `-- OTP File name is the spent Yubikey ticket (w/o uid) 733 | | | 734 | | +-- .bs/ Directory of bootstraps to be included 735 | | | | 736 | | | +-- .at Attributes to be included in each SSO 737 | | | `-- SVC,SHA1 Bootstrap for a service 738 | | | 739 | | `-- SP,SHA1/ One directory for each SP user is federated with 740 | | | 741 | | +-- .mni Federated name id to be used with this SP 742 | | +-- .at Attributes to be included for this SP 743 | | `-- SVC,SHA1 Bootstrap to be included for this SP 744 | | 745 | `-- .all/ Template used for all users 746 | | 747 | +-- .bs/ Directory of default bootstraps to be included 748 | | | 749 | | +-- .at Attributes to be included in each SSO 750 | | `-- SVC,SHA1 Bootstrap for a service 751 | | 752 | `-- SP,SHA1/ One directory for each SP 753 | | 754 | +-- .at Attributes to be included for this SP 755 | `-- SVC,SHA1 Bootstrap to be included for this SP 756 | 757 +-- idpnid/ Index of federated NameIDs, to map to uid 758 | | 759 | `-- SVC,SHA1 Bootstrap to be included for this SP 760 | | 761 | `-- NID Content of the file is uid 762 | 763 +-- idpdimd/ 764 | | 765 | `-- SVC,SHA1 Discovery MD registration for a service 766 | 767 `-- idplog/ Log files, pid files, and the like 768 769When generating SSO assertion, the attributes are collected as follows: 770 7711. LDIF at /var/zxid/uid/JOE/.bs/.at 7722. LDIF at /var/zxid/uid/JOE/SP,SHA/.at 7733. LDIF at /var/zxid/uid/.all/.bs/.at 7744. LDIF at /var/zxid/uid/.all/SP,SHA/.at 775 776As of version 0.33 (20090904) the attributes are rendered 777singlevalued. If multiple occurrances of an attribute happen, 778the first instance is used and others ignored. However, in 779a future version, we expect to support multivalued attributes. 780 781The order for attaching bootstrap attributes is similar. 782 783Yubikey support works by using the initial part of the ticket (passed 784in as user field) as uid and the latter as the ticket proper. The uid 785part is used to locate correct directory. Mapping from yubikey modhex 786to real UID is done by creating a symlink. The AES128 shared (between 787yubikey token and IdP) key is kept in the .yk file. As this is not a 788password has, but rather directly the shared secret, it requires 789rigorous approach to the filesystem security. The fact that .pw and 790.yk are separate files caters for the possibility of user 791authenticating either by yubikey or by password. By default yubikey 792is one factor authentication (in fairly secure and very convenient 793form). If two factor authentication is desired, the password component 794should be prefixed to the UID component, i.e. first user types PIN 795and then presses yubikey to add UID and ticket. 796 797TLS Client Certificate authentication of users has not been 798implemented yet, but in any case would be mainly implemented by 799configuration of web server to request such certificate and verify 800it. By the time zxid gets called, the client cert authentication will 801already have happened. HTTP Basic authentication works in similar way 802and we make no attempt to cater for it, although it can be used of 803configured separately (in the traditional way). 804 805zxpasswd(8) is a user provisioning tool that allows creation of 806new accounts as well as manipulation of .pw and .yk files. 807 808<<if: ZXIDBOOK>> 809<<else: >> 810 81196 License 812========== 813 814Copyright (c) 2010-2011 Sampo Kellom�ki (sampo@iki.fi), All Rights Reserved. 815Copyright (c) 2006-2009 Symlabs (symlabs@symlabs.com), All Rights Reserved. 816Author: Sampo Kellom�ki (sampo@iki.fi) 817 818Licensed under the Apache License, Version 2.0 (the "License"); 819you may not use this file except in compliance with the License. 820You may obtain a copy of the License at 821http://www.apache.org/licenses/LICENSE-2.0 822 823Unless required by applicable law or agreed to in writing, software 824distributed under the License is distributed on an "AS IS" BASIS, 825WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 826See the License for the specific language governing permissions and 827limitations under the License. 828 829<<zxid-ref.pd>> 830 831<<doc-end.pd>> 832<<notapath: TCP/IP a.k.a xBSD/Unix n/a Perl/mod_perl PHP/mod_php Java/Tomcat>> 833<<EOF: >> 834test13 toimii OK 835<<fi: >> 836