From d4b924bdfb225e8a4b2cfe1ea21260fbd7f9ff89 Mon Sep 17 00:00:00 2001 From: Max Date: Sat, 2 Jun 2012 14:47:07 -0500 Subject: [PATCH] Readme is longer now --- README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 58 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 32cd98a..b313409 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,8 @@ Rationale --------- Conventional wisdom states that [session data belongs in server-side storage](http://wonko.com/post/why-you-probably-shouldnt-use-cookies-to-store-session-data) -and that single sign-on is best performed by [pushing bits of XML around with page forwarding](http://en.wikipedia.org/wiki/SAML_2.0#SAML_2.0_Bindings). Yet the -accepted approaches present problems that are sometimes hard to overcome: +and that [single sign-on](http://en.wikipedia.org/wiki/Single_sign-on) is best performed by [pushing bits of XML around with page +forwarding](http://en.wikipedia.org/wiki/SAML_2.0#SAML_2.0_Bindings). Yet the accepted approaches present problems that are sometimes hard to overcome: * Scalability: every instance of the application server requires access to session store. Unless sessions are sticky (instance-affine), _all_ instances of the application have to talk to the _same_ session store. This is a real bummer if the instances do not sit in the same data center. @@ -32,5 +32,61 @@ Prior art Conventions and interoperability -------------------------------- +### Encoding of cookie content + +* Session information contained in the cookie is a [BSON-encoded](http://bsonspec.org/) dictionary. BSON was selected over JSON in part for syntactic compactness but +mostly because it supports binary data and thus can store secure credentials without additional base-64 bloat. + +* There is exactly one field with predefined meaning: `"exp"` (expiration); if present, it should contain a 64-bit UTC timestamp (BSON type `0x09`) determining +expiration time of the cookie used in order to guard against a [replay attack](http://en.wikipedia.org/wiki/Replay_attack). + +* BSON-encoded binary string is encrypted (see below) and then base-64 encoded. + +### Cookie names and HTTP attributes + +* The cookies have two-part names separated by dot: the first part is a user-defined prefix (suggested defaults are `"session"` for session store cookies and `"creds"` +for session backup/single sign-on credentials); the second part identifies the encryption key used to create the cookie and its meaning depends on the _key manager_. + +* When used within single application, session store or backup cookies should use the default HTTP domain (equal to host). When used for single sign-on purposes within +a single higher-level DNS domain, the HTTP `Domain` attribute should be set explicitly. + +* By default, the `HttpOnly` attribute should be set to minimize the potential of replay attacks via cookie theft. It has to be left off in order to implement +cross-domain single sign-on with a browser script. + +* As cookies are encrypted, there is no particular benefit to setting the HTTP `Secure` attribute. + +* The `Expires` attribute should be set to the same time as the `"exp"` field in the cookie content. Note that while HTTP expiration should always be specified for a +cookie, the use of internal timestamp is unnecessary in some cases (e.g. if backup credentials are always verified via an external service before being used to +create the session anew). + +### Encryption and key management + +* Symmetric encryption is strongly suggested (current implementation uses AES-256-CBC). + +* As unencrypted content of the cookie is relatively predictable, encryption keys [should not be reused](http://en.wikipedia.org/wiki/Known-plaintext_attack). The +simple and robust approach is to create a new key for every encryption by combining a strong secret key with a [nonce](http://en.wikipedia.org/wiki/Cryptographic_nonce) +and including the nonce (or enough information to reconstruct it) in the key identifier part of the cookie name. When used for SSO purposes, the secret key must be +shared between all participating application instances. + +* This implementation provides a simple key manager that uses current UTC timestamp as a nonce. This does not guarantee key uniqueness but should be sufficient +in most cases; enterprise-level single sign-on requires significantly more sophisticated key management strategies that should be implemented by the users of the library. + +### Usage scenarios + +* Session store for a single application: the application itself handles the sign-on sequence and stores session info in the cookie. Re-encrypting and re-sending the +cookie on every request is relatively expensive even if new key is not generated every time (although it really ought to be) therefore if session data does not change +often, cookie only needs to be re-encrypted to avoid expiration of the active session which can be done relatively infrequently. Current implementation's default is +to refresh the cookie once half of the session lifetime has passed. + +* Session backup for a single application: the application uses traditional session data storage (for example, because session data is large or changes frequently) but +would like to be able to recreate the session in the event of failover to a different storage, making the switch transparent to the end user. In this case the application +stores some form of secure credentials (verifiable token is OK, but **not** a plaintext password -- this can come back and bite you in too many ways!) in the cookie and +will only unencrypt and use it if the session data are lost. The backup cookies should still expire but may have a relatively long lifetime. + +* Single sign-on: may come in many flavors, but normally one application (identity provider) would store credentials in the cookie and other applications (within the +same domain) would be able to access them and create sessions of their own transparently to the user by reconstructing the encryption key from the shared secret and +the nonce taken from the cookie name. Any of participating applications can then refresh the common session by re-encrypting the cookie with a new timestamp. +Enterprise-wide single sign on requires sophisticated key management to guard against leakage of shared secrets from compromised application servers. + API and usage examples ----------------------