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}

GET  Get the certificate identified by the 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

GET


Get the certificate identified by the alias.
[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-certificate-info+xml
plcm-pkix-certificate:plcm-pkix-certificate-info+json

Response

Status Representation Description
200 Returned the certificate successfully.
404 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Requested resource could not be found.

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.