Programming Guides › Programming Guide for the Federation Java SDK › CA SiteMinder Federation Java SDK Programming Interfaces

CA SiteMinder Federation Java SDK Programming Interfaces

This section contains the following topics:

IFederationOpenIdentity Interface

FedSdkLogger Interface

IFederationOpenIdentity Interface

The IFederationOpenIdentity interface defines methods for manipulating the federation open format cookie. The interface supports the following tasks:

• Initialize the SDK logger specific to an application.
• Extract user identity information from the cookie in an HTTP request, in a Java Cookie object, or in String format.
• Initialize values for the cookie name, domain, and security zone.
• Set a shared secret used to derive a key for cookie encryption and decryption.
• Create the open format cookie.
• Pass identity attributes to an application.
• Get and set URIs for AuthnContext and UserConsent.

To obtain an implementation of the IFederationOpenIdentity interface, call one of the implementation methods defined in the IdentityFactory. These methods require specifying a string for the cryptographic transformation of the cookie.

The following password-based encryption combinations are available for standard installations:

• PBE/SHA1/AES/CBC/PKCS12PBE-1000-128
• PBE/SHA1/AES/CBC/PKCS12PBE-1000-192
• PBE/SHA1/AES/CBC/PKCS12PBE-1000-256
• PBE/SHA256/AES/CBC/PKCS12PBE-1000-128
• PBE/SHA256/AES/CBC/PKCS12PBE-1000-192
• PBE/SHA256/AES/CBC/PKCS12PBE-1000-256
• PBE/SHA1/3DES_EDE/CBC/PKCS12PBE-1000-3
• PBE/SHA256/3DES_EDE/CBC/PKCS12PBE-1000-3

Password-based encryption (PBE) combinations are not FIPS-compatible. Any of the FIPS-mode encryption combinations listed following requires using the Java SDK to operate properly.

The following encryption combinations are FIPS-compliant and also available for standard installations:

• AES128/CBC/PKCS5Padding
• AES192/CBC/PKCS5Padding
• AES256/CBC/PKCS5Padding
• 3DESEDE/CBC/PKCS5Padding

Note: All cryptographic strings and their corresponding constant names are listed in IdentityCrypto.java.

Open Format Cookie

The federation open format cookie lets applications assert user attributes to CA SiteMinder® and consume user attributes encapsulated by CA SiteMinder®. The open format cookie has the following general characteristics:

• The cookie is accessible by applications written in any programming language.
• The cookie content consists of a string of UTF-8 bytes, which supports international character sets.
• The combined size in UTF-8 bytes of each name/value pair precedes the name/value pair.
• Space characters are added for legibility.
• The cookie is simple to parse and easily extensible.

Important! If the cookie contains any unsafe characters such as '=', enclose the value in double quotes. You can specify this option through the user interface, or through the SDK.

The open format cookie contains the following property information:

• Cookie Version
• Name ID
• Name ID Format
• Session ID
• AuthnContext
• UserDN (same as User ID)

The following diagram shows the open format:

Key:

• Ver — the cookie format version; for CA SiteMinder Federation r12.1, this value is 1.
• Sp — an ASCII space character, used only to improve readability
• Properties — information about the principal
• Attributes — SAML attributes from the Assertion
• Cnt — the number of name value pairs that follow, represented in ASCII
• Sz — the length of the name or value that follows
• ValCnt — the number of attribute values that follow. For CA SiteMinder Federation r12.1, multiple values for an attribute are not supported. This value must be set to 1.

The Backus-Naur Form (BNF) for this format is following (0* means 0 or more; 1* means at least 1).

• DIGIT = ASCII digit (0 through 9)
• CHAR = UTF-8 character
• Sp = ASCII space (character 32)
• Token = 1*CHAR
• Cookie = Version Sp Properties Attributes
• Version = 1*DIGIT
• Cnt = 1*DIGIT
• Properties = Cnt 1*PPair
• Attributes = Cnt 0*APair
• ValCnt = 1*DIGIT
• PPair = Sz Sp Name Sp Sz Sp Value
• APair = Sz Sp Name Sp ValCnt Sp Sz Sp Value
• Sz = 1*DIGIT
• Name = Token
• Value = Token

FedSdkLogger Interface

The FedSdkLogger interface provides the following methods for specifying custom logging messages:

void logTrace (string fileName, string methodName, string msg)

Logs a trace message.

void logError (string fileName, string methodName, string msg)

Logs an error message.