= Using PKI CA Certificate CLI =

== Overview ==

PKI provides CLI to manage certificates and certificate requests.
See also link:https://github.com/dogtagpki/pki/wiki/Adding-System-User[Adding System User].

To manage certificate profiles, see link:https://github.com/dogtagpki/pki/wiki/PKI-CA-Profile-CLI[PKI CA Profile CLI].

To manage certificate requests, see link:https://github.com/dogtagpki/pki/wiki/PKI-CA-Certificate-Request-CLI[PKI CA Certificate Request CLI].

== Listing Certificates ==

Listing certificates can be executed anonymously.

To list all certificates:

----
$ pki ca-cert-find
----

To list certificates with specific status:

----
$ pki ca-cert-find --status VALID
----

To list certificates with specific name:

----
$ pki ca-cert-find --name "Subsystem Certificate"
----

To list certificates with search constraints defined in a file:

----
$ pki ca-cert-find --input <filename>
----

where file is in the following format:

----
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CertSearchRequest>

    <serialNumberRangeInUse>true</serialNumberRangeInUse>
    <serialFrom></serialFrom>
    <serialTo></serialTo>

    <subjectInUse>false</subjectInUse>
    <eMail></eMail>
    <commonName></commonName>
    <userID></userID>
    <orgUnit></orgUnit>
    <org></org>
    <locality></locality>
    <state></state>
    <country></country>

    <matchExactly>false</matchExactly>

    <status></status>

    <revokedByInUse>false</revokedByInUse>
    <revokedBy></revokedBy>

    <revokedOnFrom>false</revokedOnFrom>
    <revokedOnTo></revokedOnTo>

    <revocationReasonInUse>false</revocationReasonInUse>
    <revocationReason></revocationReason>

    <issuedByInUse>false</issuedByInUse>
    <issuedBy></issuedBy>

    <issuedOnInUse>false</issuedOnInUse>
    <issuedOnFrom></issuedOnFrom>
    <issuedOnTo></issuedOnTo>

    <validNotBeforeInUse>false</validNotBeforeInUse>
    <validNotBeforeFrom></validNotBeforeFrom>
    <validNotBeforeTo></validNotBeforeTo>

    <validNotAfterInUse>false</validNotAfterInUse>
    <validNotAfterFrom></validNotAfterFrom>
    <validNotAfterTo></validNotAfterTo>

    <validityLengthInUse>false</validityLengthInUse>
    <validityOperation></validityOperation>
    <validityCount></validityCount>
    <validityUnit></validityUnit>

    <certTypeInUse>false</certTypeInUse>
    <certTypeSubEmailCA></certTypeSubEmailCA>
    <certTypeSubSSLCA></certTypeSubSSLCA>
    <certTypeSecureEmail></certTypeSecureEmail>

</CertSearchRequest>
----

== Displaying a Certificate ==

To display a particular certificate:

----
$ pki ca-cert-show <certificate ID>
----

= Listing Certificate Request Templates =

To list certificate profiles available to end-entities:

----
$ pki ca-cert-request-profile-find
------------------
25 entries matched
------------------
  Profile ID: caUserCert
  Name: Manual User Dual-Use Certificate Enrollment
  Description: This certificate profile is for enrolling user certificates.

  ...

-----------------------------
Number of entries returned 20
-----------------------------
----

== Displaying a Certificate Request Template ==

----
$ pki ca-cert-request-profile-show caUserCert
--------------------------------------------
Enrollment Template for Profile "caUserCert"
--------------------------------------------
  Profile ID: caUserCert
  Renewal: false

  Name: Key Generation
  Class: keyGenInputImpl

    Attribute Name: cert_request_type
    Attribute Description: Key Generation Request Type
    Attribute Syntax: keygen_request_type

    Attribute Name: cert_request
    Attribute Description: Key Generation Request
    Attribute Syntax: keygen_request

...
----

== Downloading a Request Template ==

To download a request template for a particular profile, specify the profile name and the output file in the following command:

----
$ pki ca-cert-request-profile-show caUserCert --output caUserCert.xml
----------------------------------------------------------
Saved enrollment template for caUserCert to caUserCert.xml
----------------------------------------------------------
----

The request template will be stored in XML format:

----
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CertEnrollmentRequest>
    <Attributes/>
    <ProfileID>caUserCert</ProfileID>
    <Renewal>false</Renewal>
    <RemoteHost></RemoteHost>
    <RemoteAddress></RemoteAddress>
    <Input id="i1">
        <ClassID>keyGenInputImpl</ClassID>
        <Name>Key Generation</Name>
        <Attribute name="cert_request_type">
            <Value></Value>
            <Descriptor>
                <Syntax>keygen_request_type</Syntax>
                <Description>Key Generation Request Type</Description>
            </Descriptor>
        </Attribute>
        <Attribute name="cert_request">
            <Value></Value>
            <Descriptor>
                <Syntax>keygen_request</Syntax>
                <Description>Key Generation Request</Description>
            </Descriptor>
        </Attribute>
    </Input>
...
</CertEnrollmentRequest>
----

== Creating a Certificate Request ==

link:https://github.com/dogtagpki/pki/wiki/Generating-Certificate-Request[Generate a certificate request], for example:

----
$ PKCS10Client -d ~/.dogtag/nssdb -p Secret.123 -a rsa -l 1024 -o testuser.csr -n "uid=testuser"
PKCS10Client: Debug: got token.
PKCS10Client: Debug: thread token set.
PKCS10Client: token Internal Key Storage Token logged in...
PKCS10Client: key pair generated.
PKCS10Client: pair.getPublic() called.
PKCS10Client: CertificationRequestInfo() created.
PKCS10Client: CertificationRequest created.
PKCS10Client: calling Utils.b64encode.
PKCS10Client: b64encode completes.
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBfTCB5wIBADAaMRgwFgYKCZImiZPyLGQBARMIdGVzdHVzZXIwgZ8wDQYJKoZI
hvcNAQEBBQADgY0AMIGJAoGBAPEcxFJBu2lNmIS+MNaZKO43h0dIhKZWZ8wEomQc
tc9guIUGM5eFU+psj6n0XQCPMIVRe7mrzYHF8mlwAp416P5/97g9U6JOKkTXc5ia
HVE1JRhykHiQ17Lp7Y6xXxfe6xKAXDoLOPJ4fNdadtbVeIGjudWktjgwh5CQBXsA
GFP5AgMBAAGgJDAiBggrBgEFBQcHFzEWBBTmaclfLv+kkK5z5kTMP54dlnecUDAN
BgkqhkiG9w0BAQQFAAOBgQAXrm979HwcG63Z64u+aybYrfOgyWxQ4kTtCA+NKYge
HC6Z/mlb10J/wggOzrHUbE4IFyjbBo2k1FKe8zYcXIB6Ok5Z0TXueR1zKcb8hE35
o9dkH2sGJsSqMLN8NRyY5QeqOKmtaX8pm1aPhJ0wkvOYou52YqJdq6LF9KXmBGOH
hA==

-----END NEW CERTIFICATE REQUEST-----
PKCS10Client: done. Request written to file: testuser.csr
----

== Submitting a Certificate Request ==

See also link:https://github.com/dogtagpki/pki/wiki/Certificate-Profiles[Certificate Profiles].

=== Basic requests ===

Basic requests can be submitted to the server using the following command:

----
$ pki ca-cert-request-submit --profile caUserCert \
    --request-type pkcs10 --csr-file testuser.csr --subject uid=testuser
----

=== Advanced requests ===

First obtain the request template for a certificate profile:

----
$ pki ca-cert-request-profile-show caUserCert --output testuser.xml
----

Edit the template and fill in the input attributes:

----
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CertEnrollmentRequest>
    ...
    <Input id="i1">
        <Attribute name="cert_request_type">
            <Value>pkcs10</Value>
            ...
        </Attribute>
        <Attribute name="cert_request">
            <Value>
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBfTCB5wIBADAaMRgwFgYKCZImiZPyLGQBARMIdGVzdHVzZXIwgZ8wDQYJKoZI
hvcNAQEBBQADgY0AMIGJAoGBAPEcxFJBu2lNmIS+MNaZKO43h0dIhKZWZ8wEomQc
tc9guIUGM5eFU+psj6n0XQCPMIVRe7mrzYHF8mlwAp416P5/97g9U6JOKkTXc5ia
HVE1JRhykHiQ17Lp7Y6xXxfe6xKAXDoLOPJ4fNdadtbVeIGjudWktjgwh5CQBXsA
GFP5AgMBAAGgJDAiBggrBgEFBQcHFzEWBBTmaclfLv+kkK5z5kTMP54dlnecUDAN
BgkqhkiG9w0BAQQFAAOBgQAXrm979HwcG63Z64u+aybYrfOgyWxQ4kTtCA+NKYge
HC6Z/mlb10J/wggOzrHUbE4IFyjbBo2k1FKe8zYcXIB6Ok5Z0TXueR1zKcb8hE35
o9dkH2sGJsSqMLN8NRyY5QeqOKmtaX8pm1aPhJ0wkvOYou52YqJdq6LF9KXmBGOH
hA==
-----END NEW CERTIFICATE REQUEST-----
            </Value>
            ...
        </Attribute>
    </Input>
    <Input id="i2">
        ...
        <Attribute name="sn_uid">
            <Value>testuser</Value>
            ...
        </Attribute>
    </Input>
    ...
</CertEnrollmentRequest>
----

Then use the following command to submit the request:

----
$ pki ca-cert-request-submit testuser.xml
----

== Retrieving Certificates ==

To download a certificate:

----
$ pki ca-cert-show <certificate ID> --encoded --output <filename>
----

== Revoking Certificates ==

Revoking, holding, or releasing certificates must be executed as an agent.

To revoke a certificate:

----
$ pki <agent authentication> ca-cert-revoke <certificate ID>
----

To hold a certificate temporarily:

----
$ pki <agent authentication> ca-cert-hold <certificate ID>
----

To release a certificate that has been held:

----
$ pki <agent authentication> ca-cert-release-hold <certificate ID>
----

== Checking Certificate Status ==

The `pki ca-cert-status` provides a simpler way to test OCSP request by downloading the issuer certificate automatically from the server. However, the proper OCSP request should be generated using the proper OCSP client with the issuer certificate already installed on the client.

To check certificate status using the CA's internal OCSP responder:

----
$ pki ca-cert-status <certificate ID>
----

To check certificate status using other OCSP responder:

----
$ pki ca-cert-status <certificate ID> --ocsp http://$HOSTNAME:8080/ocsp/ee/ocsp
----

See also link:https://github.com/dogtagpki/pki/wiki/Using-OCSPClient[OCSPClient].

== See Also ==

* link:https://github.com/dogtagpki/pki/wiki/PKI-CLI[PKI CLI]
* link:https://github.com/dogtagpki/pki/wiki/PKI-CA-CLI[PKI CA CLI]
* link:https://github.com/dogtagpki/pki/wiki/PKI-CA-Certificate-Request-CLI[PKI CA Certificate Request CLI]
* link:https://github.com/dogtagpki/pki/wiki/PKI-Client-CLI[PKI Client CLI]
* link:https://github.com/dogtagpki/pki/wiki/PKI-User-Certificate-CLI[PKI User Certificate CLI]
* link:https://github.com/dogtagpki/pki/wiki/PKI-CA-Profile-CLI[PKI CA Profile CLI]
