The document service is a web service that serves Registry data in XML format. Access to this service is restricted to X.509 client certificates signed by MaIS (Registry Certificate Authority). You will need to generate a public and private key and submit your Certificate Signing Request (CSR) to Registry Certificate Authority Request.
If you will be using a Java client to access the document service, Sun Microsystems has a Java implementation of SSL called JSSE. In addition, you can use the "keytool" executable shipped with the JDK to generate a private key and CSR.
To obtain a certificate for your application signed by Registry Certificate Authority:
(Note: For certificate re-signing simply perform steps 2 and 4.)
- Generate a new private and public key (just replace the alias and CN below with one for your application) in your keystore:
keytool -genkey -alias myapp -keystore mykeystore -dname "CN=myapplication, OU=Registry, O=Stanford University, L=Stanford, S=California, C=US"
Note: Do not use an "_" in your CN. - Generate and Submit CSR:
keytool -certreq -alias myapp -keystore mykeystore -file myapp.csr - Once you've received your signed certificate, import the Registry Certificate Authority certificate into your keystore so that a proper certificate chain can be established when you import your signed certificate in Step 4 below:
keytool -import -alias registryca -keystore mykeystore -file registryca.cer - Import the signed certificate into your keystore:
keytool -import -alias myapp -keystore mykeystore -file myapp.cer
Once you have the certificate, connect to the test instance of the document service.
The following types of XML documents are available:
| Document Type | URL | Recognized Identifiers |
|---|---|---|
| Account | https://registry-test.stanford.edu/doc/account/[Identifier] | SUNetID |
| Class (Course) | https://registry-test.stanford.edu/doc/courseclass/[Identifier] | {term}-{subject}-{number} {term}-{courseid} |
| Person | https://registry-test.stanford.edu/doc/person/[Identifier] | SUNetID UnivID RegistryID Card Proximity Card Magstripe Source IDs |
| Privileges (Authority assignments) | https://registry-test.stanford.edu/doc/privileges/person/[Identifier] | SUNetID UnivID RegistryID |
For development purposes, these XML documents can be viewed through a web browser with authentication being controlled by WebAuth. Use the same URL as above substituting "/view" in place of "/doc".
Additional information
What is JSSE?
Java Secure Socket Extensions (JSSE) is a Java implementation of SSL v3 (Secure Sockets Layer) and TLS (Transport Layer Security) protocols and includes functionality for data encryption, server authentication, message integrity, and client authentication. Using JSSE, developers can provide for the secure passage of data between a client and a server running any application protocol (such as HTTP, Telnet, or FTP) over TCP/IP. More information about JSSE is available on the Oracle website.
Keystores and Truststores
JSSE differentiates between regular keystores and truststores:
- Keystores are databases of key pairs and certificates that are used to set up SSL authentication.
- Truststores are keystores that are used to verify the identities of other clients and servers.
When a client or server is setting up an SSL session, it will retrieve its certificates and keys from its keystore. When it verifies the identities of other clients or servers, it will retrieve trusted certification authority (CA) certificates from its truststores.
JSSE looks for truststores in the following order:
- If the system property is defined, then the value of this property is used as the truststore's location.
- If the file is defined off of the directory, then the jssecacerts file is used as the truststore.
- If the file is defined off of the directory, then the cacerts file is used as the truststore.
Troubleshooting
My integration to the Document Service is not working. What should I do?
If your integration with Document Service is not working, you should review the following:
- Verify that you are using a valid certificate (See Registry Integration x509 Certificates How-to for more information.)
- Verify that you are using the correct URL:
- Person XML (https://registry.stanford.edu/doc/person)
- Privilege XML(https://registry.stanford.edu/doc/privileges)
