PKIX

PKIX refers to Public Key Infrastructure using X.509
certificates. The PKIX API allows admins to manage certificates,
certificate signing requests, and OCSP settings for the system.

IMPORTANT: changes to these settings may cause an immediate reboot or
require another API call to initiate a reboot of the system for the
changes to take effect. It is important to determine the requirements
for rebooting the system before making changes to certificates or OCSP
settings.

To restart the system, use the plcm-power-management API
restart method.

To determine the need for a restart due to the
installation of new certificates, use the plcm-pkix API
"certificates/status" method.

[tags: DMA]

Resource Root

https://localhost:8443/api/rest/pkix/certificates

Summary

Resources	Methods
https://localhost:8443/api/rest/pkix/certificates	POST Install an X509 certificate, PKCS7 or PKCS12 file. POST Install PEM-formatted certificate(s) from text. GET Get details in text for all the currently installed certificates.
https://localhost:8443/api/rest/pkix/certificates/{alias}	DELETE Delete the certificate identified by the alias.
https://localhost:8443/api/rest/pkix/certificates/reset-to-selfsigned	POST Regenerate the self signed certificate.
https://localhost:8443/api/rest/pkix/certificates/status	GET Indicates the need for a reboot due to the installation of new certificates.
https://localhost:8443/api/rest/pkix/certificates/csr	GET Get the current Certificate Signing Request. POST Create a new or update an existing certificate signing request.
https://localhost:8443/api/rest/pkix/certificates/ocsp-settings	GET Get the OCSP settings for the system. PUT Update the OCSP settings for the system.

Resources

https://localhost:8443/api/rest/pkix/certificates

Methods

POST

Install an X509 certificate, PKCS7 or PKCS12 file. X509 and
PKCS7 files can be in either DER or PEM format. If the file is
PKCS12, a password must be provided in plain text in the 'password'
parameter. Data should be uploaded using 'multipart/form-data'
semantics, defined in RFC 7578, with a 'file' part and a 'password'
part. The 'file' part should use a Content-Type of
'application/octet-stream' in all cases. The 'password' part may
omit the Content-Type, but if supplied, should use a Content-Type
of 'text/plain'.

The need for a reboot can be established with the
plcm-pkix method "/certificates/status".

IMPORTANT: Changes to certificates will not take effect until the
system has been rebooted. To restart the system, use the
plcm-power-management API restart method.

[tags: DMA]

Request

Representations

multipart/form-data

Response

Status	Representation	Description
201		The file's contents were installed successfully. A reboot is required to take effect.
400	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The 'file' multipart parameter was not supplied.
403	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Unauthorized. Administrator privileges are required.
409	application/vnd.plcm.plcm-pkix-certificate-status+xml application/vnd.plcm.plcm-pkix-certificate-status+json	Errors and/or warnings have occurred during the installation of this certificate. Check the body of the response for a list of the errors and/or warnings.

POST

Install PEM-formatted certificate(s) from text. The text for
the PEM entry can contain one or more certificates.

IMPORTANT:
Changes to certificates will not take effect until the system has
been rebooted. To restart the system, use the plcm-power-management
API restart method.

[tags: DMA]

Request

Representations

text/plain

Response

Status	Representation	Description
201		The PEM certificates were installed successfully. A reboot is required to take effect.
409	application/vnd.plcm.plcm-pkix-certificate-status+xml application/vnd.plcm.plcm-pkix-certificate-status+json	Errors and/or warnings have occurred during the installation of this certificate. Check the body of the response for a list of the errors and/or warnings.

GET

Get details in text for all the currently installed
certificates.

[tags: DMA]

Request

Query Parameters

Name	Type	Description
type	xs:string	Specifies an enumerated type that will indicate that the resource should be read by the type. The URL form is https://{host}:{port}/api/rest/{resource}?type={installed\|changed} The read will default to the "installed" type enumeration. As a result, "?type=installed" is not required.

Response

Status	Representation	Description
200	application/vnd.plcm.plcm-certificate-info-list+xml plcm-pkix-certificate-info-list:plcm-pkix-certificate-info-list+json
406	text/plain	Unacceptable. Invalid accept header.

https://localhost:8443/api/rest/pkix/certificates/{alias}

Template Parameters

Name	Type	Description
alias	xs:string

Methods

DELETE

Delete the certificate identified by the alias.

IMPORTANT:
Changes to certificates will not take effect until the system has
been rebooted. To restart the system, use the
plcm-power-management API restart method.

[tags: DMA]

Request

Response

Status	Representation	Description
204		The certificate deleted successfully.
404	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Requested resource could not be found.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	This certificate is in use and cannot be removed.

https://localhost:8443/api/rest/pkix/certificates/reset-to-selfsigned

Methods

POST

Regenerate the self signed certificate.

IMPORTANT: Changes to certificates will not take
effect until the system has been rebooted. To restart the system,
use the plcm-power-management API restart method.

[tags: DMA]

Request

Response

Status	Representation	Description
204		The self signed certificate is successful regenerated.
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Invalid credentials.
403	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Unable to get permission. regenerate self signed certificate requires administrator role.

https://localhost:8443/api/rest/pkix/certificates/status

Methods

GET

Indicates the need for a reboot due to the installation of new
certificates.

[tags: DMA]

Request

Response

Status	Representation	Description
200	application/vnd.plcm.plcm-pkix-status+xml application/vnd.plcm.plcm-pkix-status+json	The indicator for reboot require is successfully retrieved.
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Invalid credentials.
403	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Unable to get permission. Get reboot status requires administrator role.

https://localhost:8443/api/rest/pkix/certificates/csr

Methods

GET

Get the current Certificate Signing Request.

[tags: DMA]

Request

Response

Status	Representation	Description
200	application/vnd.plcm.plcm-pkix-certificate-signing-request+xml application/vnd.plcm.plcm-pkix-certificate-signing-request+json	Successfully retrieved the current certificate signing request.
304		The Certificate Signing Request record has not changed since the last get. Note: The API client must provide the "plcm-pkix-certificate-signing-request" representation's ETag value in the "If-None-Match" HTTP header to ensure conditional retrieval. This will improve network performance by reducing bandwidth consumption. If the API client chooses to exclude an ETag value from a previous, identical search in the "If-None-Match" header, then the HTTP response will contain the search results in the message body. The "plcm-pkix-certificate-signing-request" ETag can be accessed from the initial search result's HTTP response header. Also, subsequent searches require the identical search filter to ensure an equivalent ETag value. This also assumes no other client made changes to the Certificate Signing Request on the server.
404		No certificate signing request found
406	text/plain	Not acceptable. Invalid accept header.

POST

Create a new or update an existing certificate signing
request. CAUTION: this will overwrite an existing CSR.

[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-pkix-certificate-signing-request+xml

application/vnd.plcm.plcm-pkix-certificate-signing-request+json

Response

Status	Representation	Description
201		Certificate Signing Request successfully saved.
400	text/plain	Bad request.
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	User is not authorized to update the Certificate Signing Request.
406	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Not Acceptable.
409	application/vnd.plcm.plcm-pkix-certificate-status+xml application/vnd.plcm.plcm-pkix-certificate-status+json	One or more errors occurred while creating the CSR. See the body of the response for the specific messages.

https://localhost:8443/api/rest/pkix/certificates/ocsp-settings

Methods

GET

Get the OCSP settings for the system.

[tags: DMA]

Request

Response

Status	Representation	Description
200	application/vnd.plcm.plcm-pkix-ocsp-settings+xml application/vnd.plcm.plcm-pkix-ocsp-settings+json	Successfully retrieved OCSP settings for the system
304		OCSP settings records have not changed since the last get. Note: The API client must provide the "plcm-pkix-ocsp-settings" representation's ETag value in the "If-None-Match" HTTP header to ensure conditional retrieval. This will improve network performance by reducing bandwidth consumption. If the API client chooses to exclude an ETag value from a previous, identical search in the "If-None-Match" header, then the HTTP response will contain the search results in the message body. The "plcm-pkix-ocsp-settings" ETag can be accessed from the initial search result's HTTP response header. Also, subsequent searches require the identical search filter to ensure an equivalent ETag value. This also assumes no other client made changes to the OCSP settings on the server.
400	text/plain	Bad request.
403	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	User has insufficient permissions to perform the operation.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The request contained ETags in both the header (header-ETag) and the body (body-ETag) and they do not match.
412	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The resource has changed on the server. The API client must retrieve the latest resource version, apply the resource modifications, then update to the server.
428	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The API client must supply the ETag in the message body that is bounded by the "entity-tag" XML tag. Refer to the "plcm-pkix-ocsp-settings.xsd" for details. If the message body does not contain the ETag value, the server will look for the ETag in the "If-Match" header.

PUT

Update the OCSP settings for the system.

IMPORTANT:
Enabling/disabling of the OCSP settings will cause
an immediate
reboot of the system. Changes to these settings
should only be
performed when rebooting will cause the least
interruption to
service.

[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-ocsp-settings+xml

application/vnd.plcm.plcm-pkix-ocsp-settings+json

Response

Status	Representation	Description
204		OCSP settings record successfully updated.
428		OCSP settings have changed since the last retrieval. Note: The response will contain the ETag value and link that reflects the server's OCSP settings resource in the HTTP response header. The API client must supply the ETag in the message body that is bounded by the "entity-tag" XML tag. Refer to the "plcm-pkix-ocsp-settings.xsd" for details. If the message body does not contain the ETag value, the server will look for the ETag in the "If-Match" header. The "plcm-pkix-ocsp-settings" ETag can be accessed from the initial retrieval result's HTTP response header. This also assumes no other client made changes to OCSP settings on the server.
400	text/plain	Bad request.
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	User is not authorized to update the OCSP settings.
406	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Not Acceptable.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The request contained ETags in both the header (header-ETag) and the body (body-ETag) and they do not match.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The OCSP responder URL is required if the OCSP certificate is specified.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Malformed OCSP Responder URL.
412	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The resource has changed on the server. The API client must retrieve the latest resource version, apply the resource modifications, then update to the server.
428	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The API client must supply the ETag in the message body that is bounded by the "entity-tag" XML tag. Refer to the "plcm-pkix-ocsp-settings.xsd" for details. If the message body does not contain the ETag value, the server will look for the ETag in the "If-Match" header.