Quick Guide - API

Access DualShield server via API needs authentication, currently we only allow client certificate authentication, which means you have to present the client certificate in your code during connection.

Here is the JAVA sample code, 

.....

JsonFormatter JSON_FORMATTER = new PrettyJsonFormatter();
 String jsonText = JSON_FORMATTER.format(json);
 
 // initialize the POST method
 HttpPost httppost = new HttpPost(szPrimaryServerURL + "/das5/rest/register/queryAgent");
 httppost.setEntity(new StringEntity(jsonText));

// execute the POST
 HttpClient httpclient = prepareHttpClient(szPrimaryServerURL);
 HttpResponse response = httpclient.execute(httppost);
 InputStream is = response.getEntity().getContent();

.....
 private static HttpClient prepareHttpClient(String szPrimaryServerURL)
 {
 try
 {
 URL url = new URL(szPrimaryServerURL);
 if(url.getProtocol().toLowerCase().equals("https"))
 {
 KeyStore keystore = KeyStore.getInstance("pkcs12");
 InputStream keystoreInput = dshelper.class.getResourceAsStream("/res/regagentpass.pfx");
 // TODO get the keystore as an InputStream from somewhere
 keystore.load(keystoreInput, "changeit".toCharArray());
 
 KeyManagerFactory keyManagerFactory = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
 keyManagerFactory.init(keystore, "changeit".toCharArray());
 
 SSLContext sslContext = SSLContext.getInstance("SSL");

// set up a TrustManager that trusts everything
 sslContext.init(keyManagerFactory.getKeyManagers(), new TrustManager[] { new X509TrustManager() {
 public X509Certificate[] getAcceptedIssuers() {
// System.out.println("getAcceptedIssuers =============");
 return null;
 }

public void checkClientTrusted(X509Certificate[] certs,
 String authType) {
// System.out.println("checkClientTrusted =============");
 }

public void checkServerTrusted(X509Certificate[] certs,
 String authType) {
// System.out.println("checkServerTrusted =============");
 }
 } }, new SecureRandom());

SSLSocketFactory sf = new SSLSocketFactory(sslContext);
// SSLSocketFactory sf = new SSLSocketFactory(keystore, "changeit");
 
 Scheme httpsScheme = new Scheme("https", url.getPort(), sf);
 SchemeRegistry schemeRegistry = new SchemeRegistry();
 schemeRegistry.register(httpsScheme);

HttpParams params = new BasicHttpParams();
 ClientConnectionManager cm = new SingleClientConnManager(schemeRegistry);
 HttpClient httpclient = new DefaultHttpClient(cm, params); 
 return httpclient;
 }
 else
 {
 HttpClient httpclient = new DefaultHttpClient();
 return httpclient;
 }
 
 } catch (Exception e)
 {
 return null;
 }
 
 }

If you use HttpsURLConnection, don't forget to set content type as application/json.

URL url = new URL(urlPath);
HttpsURLConnection connect = (HttpsURLConnection)url.openConnection();
connect.setDoInput(true);
connect.setDoOutput(true);
connect.setUseCaches(false);

connect.setRequestMethod("POST");
connect.setRequestProperty("Connection", "Keep-Alive");
connect.setRequestProperty("Content-Type","application/json"); //which is important

JSONObject payload; //compose it in advance
DataOutputStream stream = new DataOutputStream(connect.getOutputStream());
stream.write(payload.toString().getBytes("UTF-8"));
stream.flush();
stream.close();

You may ask where to get the right client certificate? Well, you need to register an API agent in DualShield Management Console,

Then download its Agent SSL Certificate (PFX, or JKS format)

If you use JKS, then change the key store instance with KeyStore keystore = KeyStore.getInstance("JKS");

The downloaded certificate has the default password “changeit”, so you don’t need to change the password in the code.

For the actual parameter to HttpPost and post data, please see the details in our DualShield REST API Programming Guide.pdf and DualShield REST API Reference.pdf