com.sap.security.api.ticket

Class TicketVerifier

java.lang.Object
  com.sap.security.api.ticket.TicketVerifier

public abstract class TicketVerifier
extends Object

This abstract base class supplies an interface to handle and verify SAP Logon Tickets in standalone Java applications that do not use the UME or Enterprise portal integrated authentication services. Within SAP AS Java there is usually no need to use this class.

DISCLAIMER:

This class requires the "IAIK Java Cryptography Extension (IAIK-JCE)" by "Institute for Applied Information Processing and Communication" (IAIK) of the Technical University Graz.

The version delivered by SAP AG is RESTRICTED to usage inside of SAP software. If you plan to use this class in standalone applications outside of SAP software, you MUST make sure to have a respective license by IAIK. For details see http://jce.iaik.tugraz.at/products/01_jce/index.php .

In order to use it, you need the following:

• an SAP logon ticket to verify
• a valid sapum.properties for parametrization of the UMFactory
• one or more trusted certificates (either in a keystore or as files in the file system). Please check the java tools. E.g. with the keytool executable (located in /bin) you can create a keystore and import trusted certificates into it.

Here's the minimum set of properties from the sapum.properties file:

  ##################
  # configuration 
  ##################
  
  ##use the internal ume trace
  ume.trace.internal_trace=false
 
  ###################################################
  # new parameter. Valid as of SAP NetWeaver 2004 SP8
  ###################################################
  login.ticket_standalone=true
  
  ###############################################################################
  #    security parameters
  ###############################################################################
  # path of your IAIK keystore
  login.ticket_keystore = ticketKeyStore
  login.ticket_keystore_pw=<your keystore password>
  
  # Initialize Factory
  logonAuthenticationFactory  =empty
  authenticationFactory       =empty
  userMapping                 =empty
  groupFactory                =empty
  roleFactory                 =empty
  userAccountFactory          =empty
  objectFactory               =empty
  principalFactory            =empty
  userFactory                 =empty
  serviceUserFactory          =empty
  ume.acl.manager             =empty
  

Here's a small code snippet that demonstrates how to use this class:

      // Make sure the IAIK provider is ready
      IAIK.addAsProvider ();
      // Get a ticketverifier object
      // see information to UMFactory.getInstance() on about how to currectly
      // configure the UMFactory singleton
      TicketVerifier tv = UMFactory.getInstance ().getTicketVerifier ();
      // read ticket (this function is only a place holder...)
      // get the ticket from the http request in a servlet or something like
      // this. make sure it is unescaped (replace %XX sequences by the
      // corresponding ASCII character)
      String ticket = getTicketAndUnescapeIt ();
      // set ticket
      tv.setTicket (ticket);
      // use call tv.setCertificates () if you don't want
      // to trust certificates in the keystore. In this
      // case, you have to provide a list of certificate objects.
      
      // Get R/3 user
      String user     = tv.getUser ();
      // Get issuer
      String issuer   = tv.getSystemID ();
      // Get client
      String client   = tv.getSystemClient ();
      String portal_user=null;
      String issue_instant;
      int    iValHours=0;
      int    iValMin  =0;
      
      // Get portal user
      InfoUnit iu     = tv.getInfoUnit (0x20);
      
      if (iu!=null) {
          // portal user is in UTF8 encoding
          portal_user = iu.getString ("UTF8");
          if (0!=portal_user.indexOf ("portal:"))
              System.out.println ("Invalid info unit.");
          else {
              portal_user = portal_user.substring (7);
          }
      }
      
      // Get validity stuff
      iu = tv.getInfoUnit (InfoUnit.ID_CREATE_TIME);
      if (iu==null) {
          // This can really be handled as a serious error
          throw new IllegalStateException ("Ticket doesn't contain a time stamp!!");
      }
      issue_instant = iu.getString (tv.getCodepage());
      
      // Get validity
      iu = tv.getInfoUnit (InfoUnit.ID_VALID_TIME);
      if (iu!=null)
          iValHours = iu.getInt();

      // get minute validity ...
      iu = tv.getInfoUnit (InfoUnit.ID_VALID_TIME_MIN);
      // ... which might not be there!
      if (iu!=null)
          iValMin = iu.getInt();

      System.out.println ("Ticket issued for R/3 user:\t" + user);
      System.out.println ("       issued by:\t\t" + issuer + " (" + client + ")");
      if (portal_user!=null)
          System.out.println("       issued for portal user:\t" + portal_user);
      System.out.println ("       issued at:\t\t" + issue_instant);
      System.out.println ("  validity period ([H..]H:MM):\t"
          + iValHours + (iValMin/10==0?":0":":") + iValMin);
    

Field Summary

static int	KEYTYPE_DER id for a DER encoded certificate.
static int	KEYTYPE_IKS id for IAIK keystore.
static int	KEYTYPE_P12 id for a P12 file storing certificates and keys.
static int	KEYTYPE_P7C id for a pkcs\#7 encoded list of certificates.
static int	KEYTYPE_PSE Currently not used.
static int	KEYTYPE_SUN id for the standard SUN JKS keystore.
protected int	state State of the Ticket.
protected static int	STATE_INITIALIZED
protected static int	STATE_START
protected static int	STATE_VERIFIED

Constructor Summary

TicketVerifier()

Method Summary

static X509Certificate	findCertificate(X509Certificate[] certs, String issuer, BigInteger serial) Deprecated. This method will be removed in the next release. Use findCertificates(java.security.cert.X509Certificate[], String, BigInteger) as replacement.
static X509Certificate[]	findCertificates(X509Certificate[] certificates, String issuer, BigInteger serial) Utility method.
protected X509Certificate[]	getCertsFromKeyStore(KeyStore store) For internal use only.
abstract String	getCodepage() Gets the SAP codepage used within this ticket.
abstract InfoUnit	getInfoUnit(int id) Get the content of the InfoUnit id (or null if no such Unit exists).
abstract Enumeration	getInfoUnits() Get an Enumeration of all (unidentified) InfoUnits.
abstract X509Certificate	getSignerCert() Get the Certificate used to verify the Signature.
abstract iaik.x509.X509Certificate	getSignerCertificate() Deprecated. This method will be removed in the next release. Use getSignerCert() instead.
abstract String	getSystemClient() Get the client of the Ticket-issuing System.
abstract String	getSystemID() Get the ID of the Ticket-issuing System.
abstract String	getTicket() Returns the ticket string this object has been fed with.
abstract String	getUser() Get the name of the User.
boolean	isEnforceVerify()
boolean	isValid() Test if Ticket is valid This method verifies the ticket (using the certificates supplied by setCertificates(String, char[]) or setCertificates(java.security.cert.X509Certificate[])) and checks whether it is expired or not.
abstract void	setCertificates(String keyStoreName, char[] pass) Set the Certificates used to verify the Signatures.
abstract void	setCertificates(X509Certificate[] certs) Set a list of X.509 certificates as trusted ticket issuers.
void	setEnforceVerify(boolean val) If set to true, the Ticket MUST be verfied before the attributes User, System and InfoUnits can be accessed (default=true).
abstract void	setTicket(byte[] ticket) Set the raw ticket.
abstract void	setTicket(String base64string) Initialize the Ticket with a base64 encoded String.
String	toString() Returns a string representation of this ticket.
abstract void	verify() Verify the ticket.
static boolean	verifyCertificate(X509Certificate[] certs, X509Certificate test, boolean verifyChain) Deprecated. The method is not used any more. The chain of the ticket signing certificate must not be verified.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

STATE_START

protected static final int STATE_START

See Also:

Constant Field Values

STATE_INITIALIZED

protected static final int STATE_INITIALIZED

See Also:

Constant Field Values

STATE_VERIFIED

protected static final int STATE_VERIFIED

See Also:

Constant Field Values

KEYTYPE_IKS

public static final int KEYTYPE_IKS

id for IAIK keystore. In order to get this you need to install the IAIK cryptography provider.

See Also:

Constant Field Values

KEYTYPE_SUN

public static final int KEYTYPE_SUN

id for the standard SUN JKS keystore.

See Also:

Constant Field Values

KEYTYPE_PSE

public static final int KEYTYPE_PSE

Currently not used.

See Also:

Constant Field Values

KEYTYPE_P12

public static final int KEYTYPE_P12

id for a P12 file storing certificates and keys. Currently not used.

See Also:

Constant Field Values

KEYTYPE_DER

public static final int KEYTYPE_DER

id for a DER encoded certificate. Currently not used.

See Also:

Constant Field Values

KEYTYPE_P7C

public static final int KEYTYPE_P7C

id for a pkcs\#7 encoded list of certificates. Currently not used.

See Also:

Constant Field Values

state

protected int state

State of the Ticket.

The TicketVerifier has three possible states:

• It starts in STATE_START
• After setting a new Ticket with setTicket(byte[]) or setTicket(String), the state changes to STATE_INITIALIZED
• If the current Ticket has been successfully verified, the state is STATE_VERIFIED.

Constructor Detail

TicketVerifier

public TicketVerifier()

Method Detail

setTicket

public abstract void setTicket(String base64string)
                        throws Exception

Initialize the Ticket with a base64 encoded String.

Parameters:

base64string - Ticket string. Can be retrieved from a servlet request, for instance.

Throws:

Exception - in case of a parsing error.

setTicket

public abstract void setTicket(byte[] ticket)
                        throws Exception

Set the raw ticket.

Parameters:

ticket - is the ticket after applying the base64 decode

Throws:

Exception - in case a parsing error occurs.

getCodepage

public abstract String getCodepage()

Gets the SAP codepage used within this ticket.

Returns:

SAP codepage used for content of type CHAR (see type of content and codepages)

getTicket

public abstract String getTicket()
                          throws TicketException

Returns the ticket string this object has been fed with.

Returns:

base64 encoded ticket string.

Throws:

TicketException - thrown in case the state is not at least initialized (by a call to setTicket(String), for instance).

getUser

public abstract String getUser()
                        throws TicketException

Get the name of the User.

Returns:

user name of the R/3 user name in the ticket

Throws:

TicketException - in one of the two cases:

• The ticket not initialized (e.g. setTicket(String) has not been called before).
• The state is initialized but not verified (no or no successful call to verify()) and setEnforceVerify(boolean) has been called before (this requires successful verification prior to this call)

Note that the second bullet is true when you call t.setEnforceVerify(true); and t.verify() throws an exception.

getSystemID

public abstract String getSystemID()
                            throws TicketException

Get the ID of the Ticket-issuing System.

Returns:

the system id of the issuing system as a string. If the ticket was issued by a UME, this will be the value of the parameter login.ticket_issuer.

Throws:

TicketException - - as in getTicket().

getSystemClient

public abstract String getSystemClient()
                                throws TicketException

Get the client of the Ticket-issuing System.

Returns:

the client of the issuing system as a string. If the ticket was issued by a UME, this will be the value of the parameter login.ticket_client.

Throws:

TicketException - - as in getTicket().

getInfoUnit

public abstract InfoUnit getInfoUnit(int id)
                              throws TicketException

Get the content of the InfoUnit id (or null if no such Unit exists). A list of possible ids is available at InfoUnit

Returns:

the info unit identified by id or null if this info unit does not exist in the ticket.

Throws:

TicketException - - as in getTicket().

getInfoUnits

public abstract Enumeration getInfoUnits()
                                  throws TicketException

Get an Enumeration of all (unidentified) InfoUnits.

Returns:

Enumeration of all info units within the ticket.

Throws:

TicketException - - as in getTicket().

toString

public String toString()

Returns a string representation of this ticket.

Overrides:

toString in class Object

Returns:

a string representation

setCertificates

public abstract void setCertificates(X509Certificate[] certs)

Set a list of X.509 certificates as trusted ticket issuers.

Parameters:

certs - list of certificates that is trusted for the verification. For an example how to get such a list, see the example.

setCertificates

public abstract void setCertificates(String keyStoreName,
                                     char[] pass)
                              throws Exception

Set the Certificates used to verify the Signatures. This method loads all Certificates from a KeyStore.

Parameters:

keyStoreName - The Name of the KeyStore file.

pass - The Password used to access the Keystore.

Throws:

Exception

getSignerCertificate

public abstract iaik.x509.X509Certificate getSignerCertificate()
                                                        throws TicketException

Deprecated. This method will be removed in the next release. Use getSignerCert() instead.

Get the Certificate used to verify the Signature.

Returns:

SignerCertificate or null.

Throws:

TicketException - - same as in getTicket().

getSignerCert

public abstract X509Certificate getSignerCert()
                                       throws TicketException

Get the Certificate used to verify the Signature.

Returns:

SignerCertificate or null.

Throws:

TicketException - - same as in getTicket().

getCertsFromKeyStore

protected X509Certificate[] getCertsFromKeyStore(KeyStore store)
                                          throws KeyStoreException

For internal use only.

Throws:

KeyStoreException

isValid

public boolean isValid()

Test if Ticket is valid This method verifies the ticket (using the certificates supplied by setCertificates(String, char[]) or setCertificates(java.security.cert.X509Certificate[])) and checks whether it is expired or not. To get more specific information in the case of failure, call verify().

Returns:

true if all checks are ok.

See Also:

verify()

verify

public abstract void verify()
                     throws CertificateException,
                            NoSuchAlgorithmException,
                            InvalidKeyException,
                            NoSuchProviderException,
                            SignatureException,
                            CertificateExpiredException,
                            CertificateNotYetValidException,
                            TicketException,
                            Exception

Verify the ticket. This function performs a cryptographic cerification of the ticket signature and checks whether the ticket is expired or not. If the verify is successful, this method sets state = STATE_VERIFIED.

Throws:

NoSuchAlgorithmException

NoSuchProviderException - Improper Provider configuration. All used algorithms (per default SHA1 and DSA) need to be available.

SignatureException - A problem with the signature

InvalidKeyException - The keys are not ok, wrong algorithm, for instance.

TicketException - can be caused by various errors.

CertificateNotYetValid

CertificateExpiredException - Only there for backward compatibility reasons.

CertificateException

CertificateNotYetValidException

Exception

setEnforceVerify

public void setEnforceVerify(boolean val)

If set to true, the Ticket MUST be verfied before the attributes User, System and InfoUnits can be accessed (default=true).

isEnforceVerify

public boolean isEnforceVerify()

findCertificate

public static X509Certificate findCertificate(X509Certificate[] certs,
                                              String issuer,
                                              BigInteger serial)

Deprecated. This method will be removed in the next release. Use findCertificates(java.security.cert.X509Certificate[], String, BigInteger) as replacement.

Utility method.

findCertificates

public static X509Certificate[] findCertificates(X509Certificate[] certificates,
                                                 String issuer,
                                                 BigInteger serial)

Utility method.

verifyCertificate

public static boolean verifyCertificate(X509Certificate[] certs,
                                        X509Certificate test,
                                        boolean verifyChain)

Deprecated. The method is not used any more. The chain of the ticket signing certificate must not be verified.

Utility method to verifiy a certificate.

Parameters:

certs - Array of trusted certificates.

test - Certificate to be verified.

verifyChain - If this parameter is true the method continues verifing until a self-signed Certificate is found as root.

Returns:

true if verification is successful.

Access Rights

This class can be accessed from:

SC	DC
[sap.com] ENGINEAPI	[sap.com] com.sap.security.api.sda
[sap.com] ENGFACADE	[sap.com] tc/je/usermanagement/api
[sap.com] CORE-TOOLS	[sap.com] com.sap.engine.client.lib