Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

NAE-XML Interface Development

Certificate and CA Requests

search

Please Note:

Certificate and CA Requests

The XML Interface enables you to:

SSL certificates signed through the XML interface can also be viewed in the console. See Certificate Authority for information on viewing certificates signed by a local CA.

CertificateExportRequest

Exports a certificate. This element has the following structure:

<CertificateExportRequest>
   <ID>...</ID>
   <CertificateName>...</CertificateName>
</CertificateExportRequest>
ElementDescription
IDContains the user-specified request ID.
CertificateNameContains the Certificate ID/Name of the certificate to be exported.

This API is only applied to Device SSL certificates.

CertificateExportResponse

Server response to <CertificateExportRequest>.

<CertificateExportResponse>
   <ID>...</ID>
   <Success>true</Success>
   <CertificateName>...</CertificateName>
   <CertificateData>-----BEGIN CERTIFICATE-----
   ...  # Certificate
   -----END CERTIFICATE-----
   </CertificateData>
</CertificateExportResponse>
ElementDescription
IDContains the user-specified request ID.
SuccessIndicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the CertificateName, and CertificateData elements described below. When the operation fails, the response element contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages.
CertificateNameContains the Certificate ID/Name of the certificate.
CertificateDataContains the ASCII-encoded certificate.

Export a Certificate

Request

<CertificateExportRequest>
  <ID>XMLID317</ID>
  <CertificateName>...</CertificateName>
</CertificateExportRequest>

Response

<CertificateExportResponse>
  <ID>XMLID317</ID>
  <Success>true</Success>
  <CertificateName>...</CertificateName>
  <CertificateData>-----BEGIN CERTIFICATE-----
    MIIDGjCCAgKgAwIBAgICCzgwDQYJKoZIhvcNAQELBQAwfzELMAkGA1UEBhMCVVMx
    CzAJBgNVBAgTAkN---------6VyIhp9MTWBLEhmwv
    -----END CERTIFICATE-----
  </CertificateData>
</CertificateExportResponse>

KeyCertificateExportRequest

Exports a key certificate.

<KeyCertificateExportRequest>
<ID>...</ID><KeyName>...</KeyName>
</KeyCertificateExportRequest>
ElementDescription
IDContains the user-specified request ID.
KeyNameName of the key certificate.

KeyCertificateExportResponse

Server response to KeyCertificateExportRequest.

<KeyCertificateExportResponse>
<ID>...</ID>
<Success>...</Success>
<KeyName>...</KeyName>
<CertificateData>...</CertificateData>
</KeyCertificateExportResponse>
ElementDescription
IDContains the user-specified request ID.
SuccessIndicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the elements described below. When the operation fails, the response element contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages.
KeyNameName of the key certificate.
CertificateDataThe certificate.

Export a Key Certificate

Request

<KeyCertificateExportRequest>
  <ID>XMLID317</ID>
  <KeyName>cert_key_1</KeyName>
</KeyCertificateExportRequest>

Response

<KeyCertificateExportResponse>
  <ID>XMLID317</ID>
  <Success>true</Success>
  <KeyName>cert_key_1</KeyName>
  <CertificateData>-----BEGIN CERTIFICATE-----
    MIIDGjCCAgKgAwIBAgICC0swDQYJKoZIhvcNAQELBQAwfzELMAkGA1UEBhMCVVMx
    CzAJBgNVBAgTAkNBMREwDwYDVQQHEwhSZWR3b29kQzEMMAoGA1UEChMDRGV2MQsw
    C-----tBEBXwcVndSfF0mllp8yM2VQh05p+YXlgVz3eqcO
    -----END CERTIFICATE-----
  </CertificateData>
</KeyCertificateExportResponse>

CAExportRequest

Exports a certificate authority.

<CAExportRequest>
<ID>...</ID>
<CAName>...</CAName>
</CAExportRequest>

Note

To run the CAExportRequest request, the user must be part of either admin or CA Admins group.

ElementDescription
IDContains the user-specified request ID.
CANameID/Name of the certificate authority.

CAExportResponse

Server response to CAExportRequest.

<CAExportResponse>
<ID>...</ID>
<Success>...</Success>
<CAName>...</CAName>
<CertificateData>...</CertificateData>
</CAExportResponse>
ElementDescription
IDContains the user-specified request ID.
SuccessIndicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the elements described below. When the operation fails, the response element contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages.
CANameID/Name of the certificate authority.
CertificateDataThe certificate.

Export a Certificate Authority

Request

<CAExportRequest>
  <ID>XMLID477</ID>
  <CAName>CA1</CAName>
</CAExportRequest>

Response

<CAExportResponse>
  <ID>XMLID477</ID>
  <Success>true</Success>
  <CAName>CA1</CAName>
  <CertificateData>-----BEGIN CERTIFICATE----      -
    MIIEVTCCAz2gAwIBAgIBADANBgkqhkiG9w0BAQsFADB+MQswCQYDVQQGEwJVUzEL
    MAkGA1UECBMCQ0ExDDAKBgNVBAcTA1JXQzEMMAoGA1UEChMDREVWMRAwDgYDVQQL
    LmNvbYIBADAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQB88W4dC8kE
    rBV6V----6Ya+oFQ8zPNB
-----END CERTIFICATE-----
  </CertificateData>
</CAExportResponse>

CSRCreateRequest

Creates an SSL Certificate Signing Request (CSR). This element has the following structure.

<CSRCreateRequest>
<ID>...</ID>
<KeyName>...</KeyName>
<CommonName>...</CommonName>
<OrganizationName>...</OrganizationName>       #optional
<OrganizationalUnitName>...</OrganizationalUnitName>        #optional
<Locality>...</Locality>                  #optional
<StateProvinceName>...</StateProvinceName>                 #optional
<CountryName>...</CountryName>              #optional
<EmailAddr>...</EmailAddr>         #optional
<SignatureAlgorithm>...</SignatureAlgorithm>        #optional
<ExtensionList>                          #optional
<SubjectAlternativeName>     #optional
    <DNS>...</DNS>             #optional
    <IpAddr>...</IpAddr>                #optional
</SubjectAlternativeName>                 #optional
<KeyUsages> #optional
    <Usage>...</Usage>           #optional
</KeyUsages> #optional
<ExtendedKeyUsages>      #optional
    <Usage>...</Usage>             #optional
</ExtendedKeyUsages>    #optional
<SubjectKeyIdentifierHash/>                  #optional
<BasicConstraintsCA>...</BasicConstraintsCA>            #optional
<BasicConstraintsMaxPathLength>...</BasicConstraintsMaxPathLength>      #optional
</ExtensionList>
</CSRCreateRequest>
ElementDescription
IDContains the user-specified request ID.
KeyNameContains the key name for an existing asymmetric key.
CommonNameContains the common name for the certificate. This value is exported when the certificate is exported. This value must be between 1 and 128 characters inclusive.
OrganizationNameContains the name of your organization.
OrganizationalUnitNameContains the name of your organizational unit.
LocalityContains your city or town.
StateProvinceNameContains your state or province.
CountryNameContains your country. This value must be two characters long.
EmailAddrContains your email address. This value must be 128 or fewer characters. This element is optional.
SignatureAlgorithmContains the Signature algorithm to create a CSR.
Permitted values for RSA Keys:
• sha512WithRSA
• sha384WithRSA
• sha256WithRSA (default)
• sha1WithRSA.
Permitted values for EC keys:
• ecdsaWithSHA512
• ecdsaWithSHA384
• ecdsaWithSHA256 (default)
• and ecdsaWithSHA1
ExtensionListContains extensions. This tag is optional.
SubjectAlternativeNameContains alternative common names for the certificate.This tag is mandatory if you input an tag. This tag can contain one or both and tags. This tag can contain multiple and elements.
KeyUsagesContains Usage tags with key usages.
ExtendedKeyUsagesContains Usage tags with key usages.
UsageContains the KeyUsages or ExtendedKeyUsages elements.
Permitted key usages:
• digitalSignature
• contentCommitment
• keyEncipherment
• dataEncipherment
• keyAgreement
• keyCertSign
• crlSign
• encipherOnly
• decipherOnly
Permitted extended key usages:
• serverAuth
• clientAuth
• codeSigning
• emailProtection
• ipsecEndSystem
• ipsecTunnel
• ipsecUser
• timeStamping
• ocspSigning
• microsoftServerGatedCrypto
• netscapeServerGatedCrypto
• microsoftCommercialCodeSigning
• microsoftKernelCodeSigning
SubjectKeyIdentifierHashSets the Subject Key Identifier extension as the hash of the public key.
BasicConstraintsCAContains the boolean value for basic constraints CA extension.
BasicConstraintsMaxPathLengthContains the integer value for basic constraints CA path length extension.
DNSContains DNS address.
IpAddrContains IP address.

CSRCreateResponse

Server response to CSRCreateRequest.

<CSRCreateResponse>
   <ID>...</ID>
   <Success>...</Success>
   <CSRData>
   </CSRData>
</CSRCreateResponse>
ElementDescription
IDContains the user-specified request ID.
SuccessIndicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the CSRData element described below. When the operation fails, the response element contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages.
CSRDataContains the certificate signing request data.

Creating a CSR Example

Request

<CSRCreateRequest>
   <ID>1</ID>
   <KeyName>test_key</KeyName>
   <CommonName>itest</CommonName>
   <OrganizationName>Organization</OrganizationName>
   <OrganizationalUnitName>OrganizationalUnit</OrganizationalUnitName>
   <Locality>City</Locality>
   <StateProvinceName>State</StateProvinceName>
   <CountryName>US</CountryName>
   <EmailAddr>safe-net@gmail.com</EmailAddr>
   <ExtensionList>
      <SubjectAlternativeName>
         <DNS>www.safe-net.com</DNS>
         <DNS>www.safe-net.org</DNS>
         <DNS>www.safe-net.net</DNS>
         <IpAddr>192.168.0.1</IpAddr>
         <IpAddr>192.168.0.2</IpAddr>
      </SubjectAlternativeName>
   </ExtensionList>
</CSRCreateRequest>

Response

<CSRCreateResponse>
   <ID>1</ID>
   <Success>true</Success>
   <CSRData>-----BEGIN CERTIFICATE REQUEST-----
MIIDODCCAiACAQAwgZMxDjAMBgNVBAMTBWl0ZXN0MRUwEwYDVQQKEwxPcmdhbml6
YXRpb24xGzAZBgNVBAsTEk9yZ2FuaXphdGlvbmFsVW5pdDENMAsGA1UEBxMEQ2l0
eTEOMAwGA1UECBMFU3RhdGUxCzAJBgNVBAYTAlVTMSEwHwYJKoZIhvcNAQkBFhJz
YWZlLW5ldEBnbWFpbC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
AQD0------hitFULJ6FfjKhtg
-----END CERTIFICATE REQUEST-----
   </CSRData>
</CSRCreateResponse>

CertificateSignRequest

Signs an SSL certificate with an existing local certificate authority (CA). This element has the following structure.

<CertificateSignRequest>
   <ID>...</ID>
   <CAName>...</CAName>
   <CertificateUsage>...</CertificateUsage>
   <CertificateExpiry>...</CertificateExpiry>
   <CSRData>
   </CSRData>
</CertificateSignRequest>
ElementDescription
IDContains the user-specified request ID.
CANameContains the ID/Name of the Certificate Authority (CA) that signs the certificate. This must be an existing Local CA on the CipherTrust Manager.
CertificateUsageIndicates whether the certificate is used for a Client, the Server, or an Intermediate CA.
CertificateExpiryContains the certificate expiry time in days. For example, a value of 365 indicates that the certificate expires 365 days from the creation date.
CSRDataContains the certificate signing request data.

CertificateSignResponse

Server response to <CertificateSignRequest>.

<CertificateSignResponse>
   <ID>...</ID>
   <Success>...</Success>
   <CertificateData>
   </CertificateData>
</CertificateSignResponse>
ElementDescription
IDContains the user-specified request ID.
SuccessIndicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the CertificateData element described below. When the operation fails, the response element contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages.
Once a certificate is successfully signed, it can be viewed on the signing local CA's page in the console, as described in Certificate Authority.
CertificateDataContains the certificate data.

Signing an SSL certificate with a Local CA example

Request

<CertificateSignRequest>
   <ID>1</ID>
   <CAName>testCA</CAName>
   <CertificateUsage>Client</CertificateUsage>
   <CertificateExpiry>365</CertificateExpiry>
   <CSRData>-----BEGIN CERTIFICATE REQUEST-----
MIIDODCCAiACAQAwgZMxDjAMBgNVBAMTBWl0ZXN0MRUwEwYDVQQKEwxPcmdhbml6
YXRpb24xGzAZBgNVBAsTEk9yZ2FuaXphdGlvbmFsVW5pdDENMAsGA1UEBxMEQ2l0
eTEOMAwGA1UECBMFU3RhdGUxCzAJBgNVBAYTAlVTMSEwHwYJKoZIhvcNAQkBFhJz
YWZlLW5ldEBnbWFpbC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
AQD0K4dKRfI+e4xAjYSjO9q9891Em5NxEpmYbPUlLDd03sAg2E4wjfCjFMrVLjGC
UHbx1a-----/Ngs/RDg1Kqozasq4+bU0bH7u6hitFULJ6FfjKhtg
-----END CERTIFICATE REQUEST-----
   </CSRData>
</CertificateSignRequest>

Response

<CertificateSignResponse>
   <ID>1</ID>
   <Success>true</Success>
   <CertificateData>-----BEGIN CERTIFICATE-----
MIID7jCCAtagAwIBAgICW+cwDQYJKoZIhvcNAQELBQAwcDELMAkGA1UEBhMCQ0Ex
EDAOBgNVBAgTB09udGFyaW8xDzANBgNVBAcTBk90dGF3YTENMAsGA1UEChMEc2Zu
dD--------Odkxo7Ed88=
-----END CERTIFICATE-----
   </CertificateData>
</CertificateSignResponse>

On this page