000024253 - Why can't I use a private key object with some Keon Certificate Authority API function calls?

Document created by RSA Customer Support Employee on Jun 14, 2016Last modified by RSA Customer Support Employee on Apr 22, 2017
Version 2Show Document
  • View in full screen mode

Article Content

Article Number000024253
Applies ToKeon Certificate Authority 4.x API
TechNote 0280
IssueWhy can't I use a private key object with some Keon Certificate Authority API function calls?
Some XDK functions do not work as expected with some private key objects but work fine with other private keys.
CauseThere are two types of private keys used in XDK:

- A private key conforming to OpenSSL format, let's call it an 'OpenSSL-Key'.  An example of an OpenSSL-Key is:
   <install-dir>\WebServer\ssl\private\admin.key

- A private key structure designed by RSA, let's call it a 'Xuda-Key'.  An example of a Xuda-Key is the key generated and
   saved in a file by the XDK sample program 'CASignCertificate'

'Xuda-Key' is a structure that wraps a private key along with some additional information about it.  This enables RSA products to use handles/references to private keys stored on a Hardware Security Module (HSM), which is not possible for 'OpenSSL-Key'.

When saved as PEM encoded in a file, both of these types of private keys have headers-footers (as in OpenSSL); and when present in a memory buffer, in most cases, these objects do not have header-footer.
ResolutionThe XDK functions requiring a private key object work with either one or both of the above types of private keys.  Table 'A' shows which type of private key can be used to set an applicable resource.  Table 'B' shows which type of private key can be used with what XDK function.

TABLE 'A':
 RESOURCES                          OpenSSL-Key       Xuda-Key
 -------------------------------  ---------------  ---------------
 XresPRIVATEKEY                        No                Yes
 XresSSLKEY                            Yes               Yes
 -----------------------------------------------------------------

TABLE 'B':
 XUDA FUNCTIONS                                       OpenSSL-Key         Xuda-Key
 -----------------------------------------------  --------------------  --------------
 XudaGenerateKeypair() -out                               No                Yes
 XudaKeyAndCertificateDecode() -out                       No                Yes
 XudaKeyAndCertificateEncode() -in                        No                Yes
 XudaKeyAndCertificateReadFromFile() -out                 No                Yes
 XudaKeyAndCertificateWriteToFile() -in                   No                Yes
 XudaKeyFromDER() -in                                     Yes               No
 XudaKeyFromDER() -out                                    No                Yes
 XudaKeyFromPEM() -in [with header-footer]                Yes               No
 XudaKeyFromPEM() -out                                    No                Yes
 XudaKeyReadFromFile() -in [with header-footer]           Yes               No
 XudaKeyReadFromFile() -out                               No                Yes
 XudaKeyToDER() -in                                       No                Yes
 XudaKeyToDER() -out                                      Yes               No
 XudaKeyToPEM() -in                                       No                Yes
 XudaKeyToPEM() -out [with header-footer]                 Yes               No
 XudaKeyWriteToFile() -in                                 No                Yes
 XudaKeyWriteToFile() -out                                Yes               No
 -------------------------------------------------------------------------------------

Legend for the above tables:

        Yes = Supported
        No  = Not supported
        in  = Private key as input
        out = Private key generated and returned as output

How to Convert an OpenSSL-Key to Xuda-Key:

The XDK functions XudaKeyFromDER(), XudaKeyFromPEM(), and XudaKeyReadFromFile() can be used to convert an OpenSSL-Key to Xuda-Key.

How to Convert a Xuda-Key to OpenSSL-Key:

The XDK functions XudaKeyToDER(), XudaKeyToPEM(), and XudaKeyWriteToFile() can be used to convert a Xuda-Key to OpenSSL-Key.
Legacy Article IDa5250

Attachments

    Outcomes