Skip to end of metadata
Go to start of metadata

Icon

This initial basis for this document was the Grants.gov Interface documentation on the Coeus web site which was created based on information provided by Murray State University and had a Revision Date of 12/18/2007

Overview

This document describes the process of setting up S2S communication between a server running Kuali Coeus and the servers at grants.gov. Upon the completion of these instructions an institution should be able to query for opportunities and submit a proposal through Kuali Coeus to Grants.gov.

This document is geared towards users familiar with server administration and SSL security. Installing the required security to communicate between your institutions server and Grants.gov should be done by individuals with the required skill set.

Table of Contents

KRACOEUS:Paths and Files
KRACOEUS:Definitions and Acronyms
KRACOEUS:Procedure for GG-Compliant S2S Communication
KRACOEUS:Testing S2S Communication
KRACOEUS:Multi Organization Setup
KRACOEUS:Grants.gov error codes
KRACOEUS:Registering the Kuali Coeus application as an AOR
KRACOEUS:Related Links

Paths and Files used

Coeus configuration file
kra_project/src/main/resources/coeus.properties
SOAP properties file
kra_project/src/main/resources/soap_server.properties

#top

Definitions and Acronyms

Client

certificate grants.gov requires client authentication. A server running Kuali Coeus at a university must have a CA-signed client certificate (even for acceptance testing at the time of this writing).

Keystore

JKS-formatted file containing certificates for the local server; it is consulted to find the local server's cert in order to send to others during client authentication

Truststore

JKS-formatted file containing 3rd party trusted CAs; incoming certs are checked against entries in the truststore. This file will probably be named cacerts.

GG

grants.gov

Acceptance Testing vs. Production GG environment

grants.gov maintains an acceptance testing server in addition to their production server.

S2S

System-to-System

AOR

Authorized Organization Representative
Individuals who are responsible for submitting applications on behalf of the university

DUNS

Data Universal Number System

CCR

Central Contractor Registry

ORC

grants.gov credential service provider

POC

(Point-of-Contact) (used in 'E-Business POC')

Portecle

GUI application for creating, managing and examining keystores, keys, certificates, certificate requests, certificate revocation lists. link: http://portecle.sourceforge.net/

#top

Procedure for GG-Compliant S2S Communication

Summary

Portecle, a GUI front-end to keytool, can be used to generate the data needed for certification. This procedure is described in GG documentation.

  • 2048-bit certificates should be used
  • Certificates must be signed by "recognized" CA. This applies for the GG acceptance testing environment as well as the production environment.
  • client public certificate must be registered with GG, following GG's procedure

Creating and Preparing a Client Certificate for use with GG

The procedure to create a keystore, generate a CSR, import the CA reply, and register the cert with GG has to be done on both your testing and production servers, if using separate local environments for test/prod. The only differences are in the GG server that is contacted; i.e. atws.grants.gov for testing and ws.grants.gov for production.

  • create a keystore using Portecle (type: JKS)
  • generate a key pair ~ can use Portecle ~ 1024-bit RSA is fine ~ SHA1withRSA verified to work (as used in GG reference implementation example cert)
  • export certificate (this is your client certificate)
  • GG docs say to send public certificate to "GG Web Services Team" - this means to use GG's pdf form (found here NOTE: You will have to use Adobe Reader to fill it out properly [it may be necessary to email GG directly at support@grants.gov; the form did not work at the time of this writing]) ~ "certificate hex serial number" can be obtained in Portecle under certificate details -> serial number ~ "email address for AOR" ~ name of requesting organization ~ DUNS number (for acceptance testing, DUNS # 0000000000000 will be used; for production, your organization's DUNS # will be used))
  • Await response that the certificate is set up with GG
  • NOTE: grants.gov documentation is incorrect - GG no longer accepts self-signed certs, even for the acceptance testing environment (despite what it says in Appendix II, Q3: "You may use the self-signed certificate provided with the Reference Implementation for testing in the Grants.gov Acceptance Testing environment. However, applicants must purchase and test using a CA signed certificate before moving to production.") => before proceeding, it is necessary to get a CA-signed cert
  • Generate a CSR ~ Portecle may be used
  • Choose a CA
  • Send CSR to CA following the CA's process
  • Receive CA reply; import it into keystore
  • Back up the certificate data

Import the grants.gov SSL Cert Into 'cacerts' Truststore

  • Entrust is the current CA for GG, as can be seen using openssl s_client...

$ openssl s_client -CApath </path/to/cacerts> -cert </path/to/PEM/formatted/private_key_and_cert> -state -showcerts -connect at07ws.grants.gov
line from s_client output indicating the CA used by GG:
Server certificate subject=/C=US/ST=VA/L=Ashburn/O=Department of Health and Human Services/OU=grants.gov/CN=atws.grants.gov issuer=/C=US/O=Entrust.net/OU=www.entrust.net/CPS incorp. by ref. (limits liab.)/OU=(c) 1999 Entrust.net Limited/CN=Entrust.net Secure Server Certification Authority

  • To list current trustore contents:

$ keytool -list -keystore </path/to/cacerts>

  • Locate and download the appropriate root CA cert, which is publicly available (currently entrust_ssl_ca.cer)
  • Import downloaded root CA cert using keytool:

$ keytool -import -keystore </path/to/cacerts> -file <entrust_ssl_ca.cer> -alias EntrustSSL

Application Configuration:

Properties:

 grants.gov.s2s.host(Test server/Prod server)
 grants.gov.s2s.port
 s2s.keystore.location
 s2s.keystore.password
 s2s.truststore.location
 s2s.truststore.password
Eg:
<param name="grants.gov.s2s.host.production">https://ws07.grants.gov:446/app-s2s-server/services</param>
<param name="grants.gov.s2s.host.development">https://at07ws.grants.gov:446/app-s2s-server/services</param>
<param name="grants.gov.s2s.host">${grants.gov.s2s.host.development}</param>
<param name="grants.gov.s2s.port">ApplicantIntegrationSoapPort</param>
<param name="s2s.keystore.password">ks-password</param>
 <param name="s2s.truststore.location”>/kra/s2s/keystore/cacerts.jks</param>
 <param name="s2s.truststore.password”>ts-password</param>
<param name="s2s.keystore.location”>/kra/s2s/keystore/kc_org.jks</param>

#top

Testing S2S Communication

Below are some methods that I have found very helpful while troubleshooting the SSL handshake process in general and Kuali Coeus <-> GG S2S in particular...

Testing from Kuali Coeus

Steps to take inside the Kuali Coeus application to make it contact GG's server. If your configuration is correct and GG's service is in order, this test should be proof that your certificate is being recognized by GG. Otherwise, these steps will cause some useful packets to fly; these can be seen using the tools described below...

  1. Open the Kuali Coeus web app
  2. Perform a Document Search for a Proposal Development Document...

NOTE: choose a proposal that hasn't previously been used to contact GG (e.g., if you were to install the reference implementation client cert, create a new proposal, then successfully contact GG using this proposal, and finally switch to your own cert and follow this procedure, cached data from the trial using the reference implementation cert may be used and this will not be a valid test of your new cert)

  1. Click Document Number to open proposal
  2. Click Grants.gov tab
  3. Click lookup opportunity
  4. Enter Opportunity ID and/or CFDA Number (00.000 for test)
  5. Click Search (Kuali Coeus should now contact GG, then display the results)

General SSL Testing Techniques & Notes

Two Linux-based command-line tools are extremely helpful in troubleshooting the SSL handshake process: the s_client tool from the OpenSSL toolkit and a utility called ssldump.

s_client is part of the standard openssl toolkit:
http://www.openssl.org/docs/apps/s_client.html#
ssldump is a tool to observe network traffic in the spirit of tcpdump.

* Jyri Virkki's site gives a good description:
http://blogs.sun.com/jyrivirkki/entry/using_ssldump

You may also be interested in ssltap, which is described there as well.
Note that both tools use the PEM format for options specifying certificate files, so you'll have to convert from JKS/DER formats as needed.

$ openssl s_client -CApath <truststore> -cert <path to .pem file - this is the client certificate that is requested by a server requiring client auth> -state -showcerts -connect at07ws.grants.gov

The string "Verify return code: 0 (ok)" indicates that the SSL handshake succeeded.

A "No trusted certificate found" error may indicate that the truststore, cacerts, does not include the CA cert for the server at GG.

ssldump output is particularly interesting. Run ssldump from the command line, telling it to report all activity on port 446 with grants.gov, then go into Kuali Coeus. When Kuali Coeus attempts to download grant information from grants.gov (which you initiate as described above), ssldump peeks at the traffic, printing it on the console.

$ sudo ssldump -i eth0 -Ad -k /path/to/keystore/in/OpenSSL/pem/format -p <keystore_passwd> port 446 and host atws.grants.gov

To check CAs returned (CAs trusted by server), the following command will print a list of certificates under "Acceptable client certificate CA names":
$ openssl s_client -CApath </path/to/cacerts> -cert </path/to/PEM/formatted/private_key_and_cert> -state -showcerts -connect at07ws.grants.gov

Try to contact atws.grants.gov with s_client...

(First export the private key for use w/openssl tools: use Portecle to export private key and certificate (in PEM format).)
$ openssl s_client -CApath </path/to/cacerts> -cert <path/to/private_key_and_cert.pem> -state -showcerts -connect at07ws.grants.gov

The output of the above can be compared with the output of the same command when the reference implementation keystore (after being exported to PEM format) is specified for the -cert option.

  • s_client will print the ``Acceptable client CA names'' - these, it appears, are the official CA certs that the server recognizes as valid CAs => clients who wish to communicate with the server must have their certificates signed by one of these CAs => your chosen CA should be in this list.

If, upon attempting to establish contact with GG using s_client, messages such as ssl handshake failure or No trusted certificate found appear, some likely problems are:

  1. GG has not installed the cert
  2. GG does not trust the cert because the cert is not CA-approved (even if GG has installed it)
  3. Your truststore (cacerts file) does not contain an entry for the root CA that has signed GG's server certificate.

#top

Multi Organization Setup

Kuali Coeus can be configured to submit proposals under more than one DUNS number. This situation may occur if you are using one Kuali Coeus instance to submit proposals for multiple campuses which use their own DUNS number or if you have a medical center as well as an acedemic division within your organization, each of which use a different DUNS number to submit applications to Grants.gov.

Procedure:

  1. For each of organizations create a certificate as outlined in the single organization setup.
  2. With key and returned (Valid CA or self-signed) crt in PEM format, convert PEM encoded files to pkcs12
  3. Use Portecle to create an empty keystore file
  4. Import the crt files into the new keystore file.
    • Important - The Alias for the certificate will be the DUNS number for your organization
  5. Repeat step 4 for each DUNS/ organization
  6. Use Portecle to export certs in PEM format for mailing to grants.gov.
    • Open Portecle.
    • Right-click on a certificate (Alias) and select 'Export'
    • Check 'Head Certficate' under Export Type.
    • Check 'PEM Encoded' for Export Format.
    • This will create an x509 certificate.
    • Attach this to an email to grants.gov along with the modified Certificate_Requests pdf file
  7. Repeat for each certificate (Alias)
  8. For the Certificate_Requests file, grants.gov is expecting an attached PDF file, so choose 'print' and save the modified pfd file as another pdf.
  9. Copy the .jks file to a directory that is accessible form your application server via the soap_server.properties file.
  10. Specify the locations of the files in the /WEB-INF/classes/soap_server.properties file (see instructions above)

#top

Grants.gov error codes

01 No session
02 No user certificate
03 No user ID serial # in certificate
04 Invalid certificate
05 Missing agency tracking number
06 Missing Grants.gov number
07 Missing user id
08 Unable to retrieve application
09 Unsupported Filter
10 User lacks Role necessary to perform this function
11 User not authorized to modify this application
12 Authorization Failure
13 Unrecognized Grants.gov Tracking Number
14 Unable to determine user's organization

#top

Registering the Kuali Coeus application as an AOR

If you receive an error code 10 - User lacks Role necessary to perform this function

You need to register Kuali Coeus as an AOR at Grants.gov

code 10 means the certificate you have registered with grants.gov
does not have sufficient privileges to do a submission. You should be
able to grant submission privilege to your certificate. This is what you
should do.

The E-Business contact person for your institution
should login into grants.gov test site with your DUNS number and MPIN.

Click on Manage Applicants, this will list all authorized
applicants at your institution.
Along with real users, an S2S certificate will be listed as a user.
Select this user and grant applicant privileges to it.

Once you complete this, you should be able to submit proposals through Grants.gov

#top

#top

  • No labels

2 Comments

  1. The Grants.gov documentation FAQ has been updated:Can I use a self-signed certificate? 
    "No, only certificates from a recognized certificate authority can be used. Self-signed certificates are too difficult to set up and maintain"

  2. Anonymous

    Can someone tell me what percentage of Grants.Gov opportunities are supported in Kuali Coeus?  Will this number change with the release of 2.0?

    Thanks,

    elise Waldron