Security library compatibilitySecurity library compatibility

The Java CoG Kit 1.1 contains a totally new security library. Since the new library uses different API this version of CoG is not backwards compatible with previous versions.

First, why the new library?
  1. The old security library was based on a commercial SSL library
  2. The old security library was socket-oriented (it was difficult to write non-socket based security modules e.g. for ftp, mds, etc.)
  3. The old security library API was not designed to work with multiple security protocols, represent different types of credentials, etc.
The new security library is based on GSS-API and is implemented entirely with open-source SSL and certificate processing libraries. With the GSS-API abstractions we can provide transport and security protocol independence. Also, the new library supports a few new features such as the new proxy certificate format and delegation-at-any-time API (see GSS Extensions document)

What has changed:
  • GSS abstractions are used through out the code instead of the old security API (e.g. before setCredential(org.globus.security.GlobusProxy) and now setCredential(org.ietf.jgss.GSSCredential))
  • All the security classes in the org.globus.security package and all sub-packages (except org.globus.security.gridmap package) are now deprecated.
  • grid-proxy-init by default generates GSI-3 style proxies that are not compatible with older GT and CoG versions. To generate the old style proxy add "-old" argument to the command line.
The functionality of the org.globus.security.GlobusProxy class is mostly replaced by org.globus.gsi.GlobusCredential class. However, we strongly recommend (if possible) not using org.globus.gsi.GlobusCredential class as it is security-protocol specific representation of (PKI) credentials. Instead, we recommend using the GSS abstractions as much as possible as shown here.

To get default (user proxy) credentials:

Before: 
GlobusProxy cred = GlobusProxy.getDefaultUserProxy();
Now (recommended): 
ExtendedGSSManager manager = (ExtendedGSSManager)ExtendedGSSManager.getInstance();
GSSCredential cred = manager.createCredential(GSSCredential.INITIATE_AND_ACCEPT);

Please note that by default if you don't set the credentials explicitly on a library (or pass null in place of GSSCredential) the default user credentials (proxy) will automatically be used.

To save credentials:

Before: 
GlobusProxy cred = ...

FileOutputStream out = new FileOutputStream("file");
cred.save(out);
out.close();
Now (recommended - using GSS Extensions API):
ExtendedGSSCredential cred = ...
byte [] data = cred.export(ExtendedGSSCredential.IMPEXP_OPAQUE);

FileOutputStream out = new FileOutputStream("file");
out.write(data);
out.close();
To load user proxy from a file:

Before 
FileInputStream in = new FileInputStream("file");
GlobusProxy cred = GlobusProxy.load(in, null);
in.close();
Now (recommended - using GSS Extensions API): 
File f = new File("file");
byte [] data = new byte[(int)f.length()];
FileInputStream in = new FileInputStream(f);
// read in the credential data
in.read(data);
in.close();
ExtendedGSSManager manager = (ExtendedGSSManager)ExtendedGSSManager.getInstance();
GSSCredential cred = 
		manager.createCredential(data,
		                         ExtendedGSSCredential.IMPEXP_OPAQUE,
                                         GSSCredential.DEFAULT_LIFETIME,
                                         null, // use default mechanism - GSI
                                         GSSCredential.INITIATE_AND_ACCEPT);
To get remaining lifetime of the credential:

Before: 
GlobusProxy cred = ...
int time = cred.getTimeLeft();
Now (recommended): 
GSSCredential cred = ...
int time = cred.getRemainingLifetime();

To get the identity of the credential (in Globus format):

Before:
GlobusProxy cred = ...
String identity = CertUtil.toGlobusID(cred.getSubject());
Now (recommended): 
GSSCredential cred = ...
String identity = cred.getName().toString();

GlobusCredential/GSSCredential conversion:

To convert org.globus.gsi.GlobusCredential to GSSCredential instance (in cases where you need to work with GlobusCredential object directly) you must first wrap it in org.globus.gsi.gssapi.GlobusGSSCredentialImpl class: 
GlobusCredential cred = ...
GSSCredential gssCred = new GlobusGSSCredentialImpl(cred, GSSCredential.INITIATE_AND_ACCEPT);
It is also possible to retrieve the org.globus.gsi.GlobusCredential object from the GSSCredential instance if it is of the right type: 
GSSCredential cred = ...
if (GSSCredential instanceof GlobusGSSCredentialImpl) {
  GlobusCredential globusCred = ((GlobusGSSCredentialImpl)cred).getGlobusCredential();
  ...
}