4.1.3 Certificate Management for Certificate-based Authentication Using SOAP

The Utilities API significantly includes a set of methods that allow you to manage certificate generation and registration within Oracle VM Manager. This is important as the WS-API also allows for certificate-based authentication, allowing you to further secure how custom-developed applications authenticate and interact with Oracle VM Manager. This section explores some of these methods briefly in the context of the SOAP API.

Certificate management within Oracle VM Manager is discussed in a variety of contexts throughout the documentation. For more information on authenticating using an SSL certificate using SOAP, please see Section 3.5.1, “Authenticating”. Please also refer to Setting up SSL on Oracle VM Manager in the Oracle VM Administrator's Guide for more information on SSL certificate management.

How to Obtain the CA Certificate Using SOAP

Once authenticated, either using an existing SSL certificate, or by using the API login method, it is possible to query the Utility API endpoint to obtain the internal Oracle VM Manager CA certificate. This is achieved using the certificateGetCaCertificate() method. This method simply returns the CA certificate as a string.

It is useful to obtain the CA certificate and to add it to your trusted certificates or to your keystore, so that it can be used to validate SSL interactions with Oracle VM Manager.

How to Sign and Register a Certificate Using SOAP

The API provides options to sign and register an SSL certificate using the internal Oracle VM Manager CA certificate. There are equally options to only sign a certificate, or to register an already signed certificate. This can be useful if you have added a trusted third-party CA certificate to Oracle VM Manager's own truststore, and wish to use a certificate issued by that third-party. These additional API methods are discussed in the API documentation. In this case, we assume that you need to sign and register a certificate with the internal CA.

The Utilities API provides a certificateSignAndRegister() method that can be used for this purpose. The method can either take a certificate that you have generated locally and sign and register it for use with Oracle VM Manager; or if called without any argument, can automatically generate the certificate with a passphraseless key before signing and registering it for use with Oracle VM Manager. For security reasons, it is usually more sensible to generate your certificate locally and set a passphrase for the key, before calling this method. If using Java, you can do this by setting up a keystore using the keytool:

$ keytool -genkey

Once you have set up a keystore and certificate, you can use the keytool to export your certificate in PEM format, so that you have it available for signing:

$ keytool -export -rfc

In your web services client, you must create a new LoginCertificate object and place your new certificate into the certificate field. For example:

LoginCertificate cert = new LoginCertificate();
cert.setCertificate("-----BEGIN CERTIFICATE-----" +
    "MIIDTzCCAw2gAwIBAgIEIIUUWjALBgcqhkjOOAQDBQAweTELMAkGA1UEBhMCVVMxCzAJBgNVBAgT" +
    "AkNBMRUwEwYDVQQHEwxSZWR3b29kIENpdHkxDzANBgNVBAoTBk9yYWNsZTEaMBgGA1UECxMRT3Jh" +
    "Y2xlIFZNIE1hbmFnZXIxGTAXBgNVBAMTEENlcnRpZmljYXRlIERlbW8wHhcNMTMwODIxMTYzOTUz" +
    "WhcNMTMxMTE5MTYzOTUzWjB5MQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExFTATBgNVBAcTDFJl" +
    "ZHdvb2QgQ2l0eTEPMA0GA1UEChMGT3JhY2xlMRowGAYDVQQLExFPcmFjbGUgVk0gTWFuYWdlcjEZ" +
    "MBcGA1UEAxMQQ2VydGlmaWNhdGUgRGVtbzCCAbgwggEsBgcqhkjOOAQBMIIBHwKBgQD9f1OBHXUS" +
    "KVLfSpwu7OTn9hG3UjzvRADDHj+AtlEmaUVdQCJR+1k9jVj6v8X1ujD2y5tVbNeBO4AdNG/yZmC3" +
    "a5lQpaSfn+gEexAiwk+7qdf+t8Yb+DtX58aophUPBPuD9tPFHsMCNVQTWhaRMvZ1864rYdcq7/Ii" +
    "Axmd0UgBxwIVAJdgUI8VIwvMspK5gqLrhAvwWBz1AoGBAPfhoIXWmz3ey7yrXDa4V7l5lK+7+jrq" +
    "gvlXTAs9B4JnUVlXjrrUWU/mcQcQgYC0SRZxI+hMKBYTt88JMozIpuE8FnqLVHyNKOCjrh4rs6Z1" +
    "k$ keytool -import -file newcertW6jfwv6ITVi8ftiegEkO8yk8b6oUZCJqIPf4VrlnwaSi" +
    "6bc9ozDyK1cgNyZWl4kq1efzjsyolIr1i4CiM/MqnEZO43hVVtXex3V+VWd9i/CLn0I/ZC9Lfi5X" +
    "HlQOEzWKK/esvf64Mv96DbZna/XRj6JhTEPGoStizNhXrVJCF4DaiIP+l53qYKJEtrNoR+tToRt8" +
    "OimE3PzLCXILvwwaCaMhMB8wHQYDVR0OBBYEFAtyjCpfkznpsUf2Lj8iBmRS3/0oMAsGByqGSM44" +
    "BAMFAAMvADAsAhRTm5NW8HDcM8jG5a7QIowNLN+fEQIUZXMogTvKbcXu6NN6fh0KY09hokI=" +
    "-----END CERTIFICATE-----");

Now you can invoke the method to sign and register your certificate, this returns the signed version of the certificate:

LoginCertificate signed = ovmUtil.certificateSignAndRegister(cert);
System.out.println(signed.getCertificate());

The output returned contains the newly signed certificate. You can dump this output to file, so that you can use it to import the newly signed certificate into your keystore:

$ keytool -import -file newcert

Note that you should also import the CA certificate into your keystore, so that your certificates can be validated. Be sure to use a different alias when importing the CA certificate into your keystore, to avoid overwriting your newly signed certificate and key.