Nevis SecToken

The SecToken concept and security considerations are described in the chapter Concept Description. This chapter contains the technical specification of the SecToken (format, algorithms, libraries).

SecToken data format

The SecToken format consists of multiple semantic layers, each corresponding to the task of a software component. The design focusses on the following requirements:

• extensibility (possibility of adding new attributes without the need to change existing software)
• self-describing
• size (as small as possible)

The external XML representation of the SecToken is based on the default encoding ISO-8859-1 (if not stated otherwise in the XML header).

Generic SecToken format

The generic SecToken is a container that allows arbitrary (binary or character) data to be signed.

A sample SecToken looks as follows:

<secToken version='1.0' signTime='20030204133740+0100' ttl='60'>
 <attr>
  <field name='userid'>userid</field>
  <field name='sessid'>ABC3dca335f_3</field>
  <field name='name2'>value2</field><field name='name1'>value1</field>
 </attr>
 <signature format='1.0' alg='SHA256withRSA' fingerPrint='F1:A3:DF:D1:F5:0D:C0:25:10:E6:34:DF:17:80:D2:E6'> PiGv/v4vEWIAAgIR6mDybfSVGmDtTq7f8AFQ4O1IwKbXP2u9IEr7anSoYELhwRp8q+PlFn1dWHJrARHBvlZ+Uz3HbWe/
J0uk2CZDU5ptH0JzdHSfbLEijlVbvbbV0JfM+gVD7cnicrmNk64ZfA4Pi8R0xSmQ4mJ02gS3nJwu/1o
 </signature>
</secToken>

Elements and attributes are as follows:

Element or attribute	Explanation
secToken	This is the start element of a Nevis security token. The XML DOCTYPE element was omitted to avoid wasting precious space.
version	Version string of the SecToken in the form: [<prefix>]<major> "." <minor> where:*<major> reflects incompatible changes. * <minor> reflects optional new elements and attributes. * <prefix> reflects a typed token format. The prefix "CSSO-" is used to provide the most common fields as elements, instead of attributes. These are: sessid, userid, entryid, esauthid and authLevel. Supported versions are: 1.0 (generic format) CSSO-1.0 (typed format) * ASN1-1.1 (attribute certificate format)
signTime	This time string reflects the SecToken's generation time either as GMT or local time, depending on the postfix.Format: YYYYMMDDhhmmssZwhere: YYYY: Year (4 digits, range 0..9999]) MM: Month (2 digits, range) DD: Day (2 digits, range) hh: Hour (2 digits, range) mm: Minute (2 digits, range) ss: Second (2 digits, range) * Z: Constant character "Z", signaling "zero" timezone (GMT), or "(+
ttl	Period of validity of the SecToken measured in seconds.
attr	This element signals the beginning of the data section.
field	This element signals the beginning of generic named value. Multiple field elements are supported. The order of their appearance is relevant for signature verification.
name	The unique name of a generic named value.
enc	The (optional) encoding of the field's value. Supported options are: none: Plain string, no encoding (default, optional) base64: base64 encoding
signature	This element signals the beginning of the signature section.The value of this element is always base64-encoded because a signature consists of binary data.
format	The format element is part of the SecToken's signature section. The format element unambiguously identifies a signed token format. The available values of this element are the same as for the version attribute. For a description of the supported values and the formatting details, see the description of the version attribute further above in this table.
alg	The algorithm used for signing the data (fields), and the value of the attributes version, signTime, and ttl. The following algorithms are supported: SHA1withRSA SHA256withRSA MD2withRSA MD5withRSA. The notation is the standard notation in Java for signature algorithms. A signature algorithm consists of a hash function in conjunction with an encryption algorithm.
fingerPrint	An md5 hash value of the signer's DER-encoded X509 certificate.This attribute also reflects a reference to the signing entity (e.g., the nevisAuth instance that generated the security token) if not specified otherwise (see the authentication part of specification).

Authentication SecToken data format

The authentication SecToken adds authentication and session information. The format defined in the chapter Generic SecToken format is enhanced to reflect well-known SecToken attributes. These well-known authentication attributes are:

Note that the attribute names are case-sensitive.*userid: The authenticated (internal) primary key, representing a unique session owner.

• authLevel: The authentication strength used to identify the user (e.g., STRONG, WEAK, PROSPECT).
• sessid: The key for a unique global session.
• entryid: The ID of a unique entry point into the Nevis Web SSO environment.
• esauthid (optional): name of the issuing authentication service.

They can be represented in two ways:

• By using the generic field mechanism of the generic SecToken:

<secToken version="1.0" signTime="20011114190059Z" ttl="600">
 <attr>
  <field name="userid">some</field>
  <field name="sessid">7iSqaesgnp39Cy9Mlnc3Iz6</field
  <field name="entryid">isiweb:SSO1:instance1</field>
  <field name="esauthid">EsAuthInst1</field>
  <field name="authLevel">STRONG</field>
 </attr>
 <signature format="1.0" alg="SHA256withRSA"
 fingerPrint="F1:A3:DF:D1:F5:0D:C0:25:10:E6:34:DF:17:80:D2:E6"/>
</secToken>

• By using the enhanced authentication type SecToken (and local time MET in winter, instead of GMT):

<secToken version="CSSO-1.0" signTime="20011114200059+0100" ttl="600">
 <attr>
  <userid>some</userid>
  <sessid>7iSqaesgnp39Cy9Mlnc3Iz6</sessid
  <entryid>isiweb:classic:SSO1</entryid>
  <esauthid>EsAuthInst1</esauthid>
  <authLevel>STRONG</authLevel>
  <mappings>
   <accountid domain="ApplDomain">other</accountid>
  </mapping>
 </attr>
 <signature format="CSSO-1.0" alg="SHA256withRSA"
 fingerPrint="F1:A3:DF:D1:F5:0D:C0:25:10:E6:34:DF:17:80:D2:E6"/>
</secToken>

Version 1.0 supports the above listed attributes, therefore version-1.0-compatible code needs to support both approaches.

The following table explains the SecToken authentication attributes and elements:

Element or Attribute	Explanation
userid	This attribute is a unique identifier for the authenticated user. It may differ from the login information a user provided on authentication. The userid attribute reflects the unique (primary) key in the SSO user authentication database.
sessid	This attribute is a unique identifier for the global session that was created for the user identified by the attribute userid. The nevisAuth attribute sessid consists of:132bit true random data 6bit nevisAuth instance identifier in case multiple redundant nevisAuth instances are used (esAuth 1.4.13.0 or later).
entryid	This attribute is an identifier for the entry point into the SSO environment.Sample usage: In the Nevis environment, this ID is generated by nevisProxy, added to the SecToken on global session creation by nevisAuth, and is verified again by nevisProxy (for being unchanged). A content provider is now able to enforce authorization restrictions on the entry point.If nevisProxy is used as an entry point, the value of this field has the following format: isiweb:SSOdomain:InstanceId where: *isiweb: Constant string * SSOdomain: The value of ClntSessAppid * InstanceId: A configurable optional constant defining the installation.
esauthid	This attribute is optional and references the nevisAuth instance that generated the token. It is needed when the fingerPrint attribute (see the is not referencing a certificate used by only one nevisAuth. The fingerPrint or esauthid attribute is required by components to find out which nevisAuth instance to contact for global session access.
authLevel	This attribute reflects the authentication strength. The following levels are currently defined: PROSPECT: Unverified (self-registered) user. WEAK: Weak authentication, e.g., userid/password. STRONG: Strong authentication, e.g., with additional one-time password or certificate (challenge). The corresponding security roles on nevisProxy might beauth.prospect,auth.weakandauth.strong*, respectively.
mappings	This attribute defines application-domain-specific mappings of the user ID into an application environment context. The application domain is defined by the domain attribute and the domain-specific identity by the accountid attribute (for an explanation of these attributes, see below).
accountid	This attribute is used to specify a mapping of the authenticated user principal into an application environment.So the user may have the following IDs: *loginid: Known by the user for login (e.g., Mickey Mouse). * userid: The global primary key of the user's identity (e.g., CN of an LDAP person). * accountid: The primary key of the user's identity within an application domain (e.g., contract number of a contract management system).
domain	This attribute defines the application environment of the accountid element.

SecToken verification

Verifying a SecToken implies the following steps:

1. Optional: Check if the SecToken is already valid: signTime - local_clock_tolerance > now
2. Check if the SecToken is still valid: signTime + ttl + local_clock_tolerance > now
3. Extract SecToken signature information, decode the signature (base64), decrypt it using the public key hinted by the fingerPrint attribute and the signature algorithm specified by the alg attribute. You have now HASH(1).
4. Extract SecToken data (signTime and ttl attribute values and the attr section), append the signTime and ttl to the attr section, and create an SHA256 hash (or whatever hash algorithm is specified in the alg attribute of the signature element). You get HASH(2).
5. Compare the two hash values HASH(1) and HASH(2).

To also allow signature verification in case of an unknown encoding type, the atttribute values are not decoded. Decoding must be done upon use, which allows to ignore SecToken information that is not needed. The SecToken generated by nevisAuth does not contain any newlines to support delegation without URL encoding via HTTP protocols. The following sample token shows which parts need to be extracted for verification (bold):

<secToken version="CSSO-1.0" signTime="**20011114190059Z**" ttl="**600**">*
***<attr><userid>some</userid><sessid>7iSqaesgnp39Cy9Mlnc3Iz6</sessid<entryid>isiweb:classic:instance1</entryid><esauthid>EsAuthInst1</esauthid><authLevel>STRONG</authLevel></attr>***
*<signature format="CSSO-1.0" alg="SHA256withRSA" fingerPrint="F1:A3:DF:D1:F5:0D:C0:25:10:E6:34:DF:17:80:D2:E6"/>*
*</secToken>

Relevant data of the sample token for HASH(2):

*<attr><userid>some</userid><sessid>7iSqaesgnp39Cy9Mlnc3Iz6</sessid<entryid>isiweb:classic:instance1</entryid><esauthid>EsAuthInst1</esauthid><authLevel>STRONG</authLevel></attr>20011114190059Z600*

Global Session Join

To further enhance security, the nevisAuth that generated the SecToken and started the global session (see the attribute esauthid) may be contacted to check if the corresponding session really exists. By joining the global session, the verifier is notified when the global session terminates. This mechanism provides additional security, as local sessions are terminated, as soon as the user logs out and therefore may not be accessed by malicious clients from the intranet anymore.

SecToken Caching

To boost SecToken performance verification, a SecToken cache may be used. In this case, successfully verified SecTokens may be stored in a cache. This omits expensive calls to the crypto library. The verification in this case consists of the following steps:

1. Check if the SecToken is still valid
2. Check if the SecToken is in the cache; if so, the request can proceed, otherwise:
3. Perform verification as documented above.
4. Cache the verified token (depending on the cache algorithms used).

The Nevis session manager, the IPlanet plug-in, and Ninja are using such a cache mechanism. Their specific implementation properties are:

• The cache is initialized with a "cacheSize" and a "cacheTimeout".
• The "cacheSize" approximately indicates how many SecTokens are maximally stored in the cache (the actual size can temporarily grow larger than "cacheSize", but the "cache cleaner", invoked depending on the "cacheTimeout", removes entries to downsize the cache).
• A "cache cleaner" thread removes expired SecTokens and downsizes the cache if it is too large.

APIs

Token verification libraries are available for

• Java: 1.7 or higher (any supported platform, but PKCS#  11 support is currently only available on Linux)
• C+: Sun WS6, Linux gcc-3 and Microsoft .NET. For C+ libraries compiled for different platforms contact AdNovum.