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)
- 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'>
<field name='name2'>value2</field><field name='name1'>value1</field>
<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/
Elements and attributes are as follows:
This is the start element of a Nevis security token. The XML DOCTYPE element was omitted to avoid wasting precious space.
Version string of the SecToken in the form:
[<prefix>]<major> "." <minor>
<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:
Supported versions are:
- 1.0 (generic format)
- CSSO-1.0 (typed format)
- ASN1-1.1 (attribute certificate format)
This time string reflects the SecToken's generation time either as GMT or local time, depending on the postfix.
- YYYY: Year (4 digits, range 0..9999])
- MM: Month (2 digits, range [1..12])
- DD: Day (2 digits, range [1..31])
- hh: Hour (2 digits, range [0..23])
- mm: Minute (2 digits, range [0..59])
- ss: Second (2 digits, range [0..59])
- Z: Constant character "Z", signaling "zero" timezone (GMT), or "(+|-)hhmm". E.g., "+0100" for MET in winter and "+0200" for MET in summer.
This format is common for PKI specifications and is derived from the ISO-9694-1. The corresponding XML schema type (xsd:dateTime, derived from ISO-8601) can easily be supported.
Period of validity of the SecToken measured in seconds.
This element signals the beginning of the data section.
This element signals the beginning of generic named value. Multiple field elements are supported. The order of their appearance is relevant for signature verification.
The unique name of a generic named value.
The (optional) encoding of the field's value. Supported options are:
none: Plain string, no encoding (default, optional)
base64: base64 encoding
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.
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 list.
The algorithm used for signing the data (fields), and the value of the attributes
ttl. The following algorithms are supported:
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.
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">
<signature format="1.0" alg="SHA256withRSA"
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">
<signature format="CSSO-1.0" alg="SHA256withRSA"
Version 1.0 supports the above listed attributes, therefore version-1.0-compatible code needs to support both approaches.
The following list explains the SecToken authentication attributes and elements:
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.
This attribute is a unique identifier for the global session that was created for the user identified by the attribute
The nevisAuth attribute sessid consists of:
- 132bit true random data
- 6bit nevisAuth instance identifier in case multiple redundant nevisAuth instances are used
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: Constant string
SSOdomain: The value of
InstanceId: A configurable optional constant defining the installation.
This attribute is optional and references the nevisAuth instance that generated the token. It is needed when the fingerPrint attribute (see the previous table) is not referencing a certificate used by only one nevisAuth. The fingerPrint or
esauthidattribute is required by components to find out which nevisAuth instance to contact for global session access.
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 be
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
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., John Doe).
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).
This attribute defines the application environment of the
Verifying a SecToken implies the following steps:
- Optional: Check if the SecToken is already valid:
signTime - local_clock_tolerance > now
- Check if the SecToken is still valid:
signTime + ttl + local_clock_tolerance > now
- Extract SecToken signature information, decode the signature (base64), decrypt it using the public key hinted by the
fingerPrintattribute and the signature algorithm specified by the
algattribute. You have now HASH(1).
- Extract SecToken data (
ttlattribute values and the
attrsection), append the
attrsection, and create an SHA256 hash (or whatever hash algorithm is specified in the
algattribute of the signature element). You get HASH(2).
- 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:
<secToken version="CSSO-1.0" signTime="20011114190059Z" ttl="600">
<signature format="CSSO-1.0" alg="SHA256withRSA" fingerPrint="F1:A3:DF:D1:F5:0D:C0:25:10:E6:34:DF:17:80:D2:E6"/>
Relevant data of the sample token for HASH(2):
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.
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:
- Check if the SecToken is still valid
- Check if the SecToken is in the cache; if so, the request can proceed, otherwise:
- Perform verification as documented above.
- 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
cacheSizeapproximately 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.
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 Nevis Support.