com.sap.security.api.ticket
Class TicketVerifier

java.lang.Object
  |
  +--com.sap.security.api.ticket.TicketVerifier

public abstract class TicketVerifier

extends java.lang.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 the SAP J2EE engine or the Enterprise Portal there is usually no need to use this class. 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 
  ##################
  
  #Disactivate secure store
  ume.secstore.active=false
  
  ##use the internal ume trace
  ume.trace.internal_trace=false
 
  ##########################################
  # new parameter. Valid as of J2EE 6.30 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.

Constructor Summary

TicketVerifier()

Method Summary

static iaik.x509.X509Certificate	findCert(iaik.x509.X509Certificate[] certs, iaik.asn1.structures.Name issuer, java.math.BigInteger serial) Utility method.
abstract java.lang.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 java.util.Enumeration	getInfoUnits() Get an Enumeration of all (unidentified) InfoUnits.
abstract iaik.x509.X509Certificate	getSignerCertificate() Get the Certificate used to verify the Signature.
abstract java.lang.String	getSystemClient() Get the client of the Ticket-issuing System.
abstract java.lang.String	getSystemID() Get the ID of the Ticket-issuing System.
abstract java.lang.String	getTicket() Returns the ticket string this object has been fed with.
abstract java.lang.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(java.security.cert.X509Certificate[])) and checks whether it is expired or not.
static iaik.asn1.structures.Name	newName(java.lang.String country, java.lang.String loc, java.lang.String org, java.lang.String orgUnit, java.lang.String commonName) Utility method
abstract void	setCertificates(java.lang.String keyStoreName, char[] pass) Set the Certificates used to verify the Signatures.
abstract void	setCertificates(java.security.cert.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(java.lang.String base64string) Initialize the Ticket with a base64 encoded String.
java.lang.String	toString() Returns a string representation of this ticket.
abstract void	verify() Verify the ticket.
static boolean	verifyCertificate(iaik.x509.X509Certificate[] certs, iaik.x509.X509Certificate test, boolean verifyChain) Utility method.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

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.

KEYTYPE_SUN

public static final int KEYTYPE_SUN

id for the standard SUN JKS keystore.

KEYTYPE_PSE

public static final int KEYTYPE_PSE

Currently not used.

KEYTYPE_P12

public static final int KEYTYPE_P12

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

KEYTYPE_DER

public static final int KEYTYPE_DER

id for a DER encoded certificate. Currently not used.

KEYTYPE_P7C

public static final int KEYTYPE_P7C

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

Constructor Detail

TicketVerifier

public TicketVerifier()

Method Detail

setTicket

public abstract void setTicket(java.lang.String base64string)
                        throws java.lang.Exception

Initialize the Ticket with a base64 encoded String.

Parameters:

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

Throws:

java.lang.Exception - in case of a parsing error.

setTicket

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

Set the raw ticket.

Parameters:

ticket - is the ticket after applying the base64 decode

Throws:

java.lang.Exception - in case a parsing error occurs.

getCodepage

public abstract java.lang.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 java.lang.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 java.lang.String getUser()
                                  throws TicketException

Get the name of the User.

Returns:

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

Throws:

throws - a 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 java.lang.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:

same - as in getTicket().

getSystemClient

public abstract java.lang.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:

same - 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:

same - as in getTicket().

getInfoUnits

public abstract java.util.Enumeration getInfoUnits()
                                            throws TicketException

Get an Enumeration of all (unidentified) InfoUnits.

Returns:

Enumeration of all info units within the ticket.

Throws:

same - as in getTicket().

toString

public java.lang.String toString()

Returns a string representation of this ticket.

Overrides:

toString in class java.lang.Object

Returns:

a string representation

setCertificates

public abstract void setCertificates(java.security.cert.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(java.lang.String keyStoreName,
                                     char[] pass)
                              throws java.lang.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.

getSignerCertificate

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

Get the Certificate used to verify the Signature.

Returns:

SignerCertificate or null.

Throws:

same - as in getTicket().

isValid

public boolean isValid()

Test if Ticket is valid This method verifies the ticket (using the certificates supplied by 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 java.security.cert.CertificateException,
                            java.security.NoSuchAlgorithmException,
                            java.security.InvalidKeyException,
                            java.security.NoSuchProviderException,
                            java.security.SignatureException,
                            java.security.cert.CertificateExpiredException,
                            java.security.cert.CertificateNotYetValidException,
                            iaik.pkcs.PKCSParsingException,
                            TicketException,
                            java.lang.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:

java.security.NoSuchAlgorithmException -

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

java.security.SignatureException - A problem with the signature

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

iaik.pkcs.PKCSParsingException - if the underlying security library couldn't parse the signature

TicketException - can be caused by various errors.

CertificateNotYetValid -

java.security.cert.CertificateExpiredException - Only there for backward compatibility reasons.

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()

findCert

public static iaik.x509.X509Certificate findCert(iaik.x509.X509Certificate[] certs,
                                                 iaik.asn1.structures.Name issuer,
                                                 java.math.BigInteger serial)

Utility method.

verifyCertificate

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

Utility method.

newName

public static iaik.asn1.structures.Name newName(java.lang.String country,
                                                java.lang.String loc,
                                                java.lang.String org,
                                                java.lang.String orgUnit,
                                                java.lang.String commonName)

Utility method