File: submit.txt

package info (click to toggle)
certmonger 0.75.14-3
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 8,540 kB
  • ctags: 2,176
  • sloc: ansic: 41,340; sh: 9,551; makefile: 528; python: 207; xml: 190; sed: 16
file content (102 lines) | stat: -rw-r--r-- 5,713 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
The CA submission internal API uses child processes to do the heavy
lifting.  Self-signing is handled internally, but interaction with
most CAs is done through external helpers.

An external CA helper has a few jobs:
* Invoked either with "SUBMIT" or "POLL" as the value of the
  $CERTMONGER_OPERATION environment variable, with command-line arguments as
  specified in certmaster's configuration.  Some of the data from the request
  is also provided in the environment.
  * $CERTMONGER_REQ_SUBJECT   -> requested subject name
  * $CERTMONGER_REQ_EMAIL     -> email address subjectAltName values
  * $CERTMONGER_REQ_HOSTNAME  -> DNS name subjectAltName values
  * $CERTMONGER_REQ_PRINCIPAL -> Kerberos principal name subjectAltName values
  * $CERTMONGER_CA_PROFILE    -> requested enrollment profile/template/certtype
  * $CERTMONGER_CERTIFICATE   -> previously-issued certificate, if there is one
  * $CERTMONGER_CA_NICKNAME   -> nickname of CA (since 0.73)
  * $CERTMONGER_SPKAC         -> signing request as an SPKAC (since 0.73)
  * $CERTMONGER_SPKI          -> request's SubjectPublicKeyInfo (since 0.73)
  * $CERTMONGER_KEY_TYPE      -> client's public key type (since 0.73)
* If in "submit" mode, $CERTMONGER_CSR has as its value a PEM-formatted CSR.
  * Submit request to CA.
    * Issued         -> output PEM-formatted cert on stdout, exit with status 0.
    * Wait a bit     -> output CA cookie value on stdout, exit with status 1.
    * Rejected       -> output error message on stdout, exit with status 2.
    * Connect error  -> output error message on stdout, exit with status 3.
    * Underconfigured-> output error message on stdout, exit with status 4.
    * Wait a bit more-> output recommended delay (seconds) and CA cookie value
                        on stdout, separated by newline, and exit with status 5.
* If in "poll" mode, $CERTMONGER_CA_COOKIE has as its value a CA cookie value
  in addition to the PEM-formatted CSR in $CERTMONGER_CSR.
  * Poll CA for result of previously-started enrollment operation.
    * Issued         -> output PEM-formatted cert on stdout, exit with status 0.
    * Wait some more -> output CA cookie value on stdout, exit with status 1.
    * Rejected       -> output error message on stdout, exit with status 2.
    * Connect error  -> output error message on stdout, exit with status 3.
    * Underconfigured-> output error message on stdout, exit with status 4.
    * Wait some more -> output recommended delay (seconds) and CA cookie value
                        on stdout, separated by newline, and exit with status 5.
* Invoked with "IDENTIFY" as the value of the $CERTMONGER_OPERATION
  environment variable:
  * Output suggested ID for CA, exit with status 0.
  * Connect error -> exit with status 3.
* Invoked with "FETCH-ROOTS" as the value of the $CERTMONGER_OPERATION
  environment variable:
  * Output suggested nickname for root certificate when stored in an NSS
    database (a.k.a FriendlyName), root certificate in PEM format,
    blank line, set of other trusted roots with nicknames (no
    separators between them, nicknames first to match the presentation
    of the root), another blank line, set of "other" known (chain)
    certificates with nicknames (no separators between them, nicknames
    first to match the presentation of the root), exit with status 0.
  * Connect error: exit with status 3.
  * Poll for this at startup and before any of them become invalid.
* Invoked with "GET-NEW-REQUEST-REQUIREMENTS" as the value of the
  $CERTMONGER_OPERATION environment variable:
  * Output list of environment variable names which are expected to
    have non-empty values when the helper is run in SUBMIT or POLL
    mode, without $s, separated by newlines, exit with status 0.
  * Connect error: exit with status 3.
  * Polled at startup.
* Invoked with "GET-RENEW-REQUEST-REQUIREMENTS" as the value of the
  $CERTMONGER_OPERATION environment variable:
  * Output list of environment variable names which are expected to
    have non-empty values when the helper is run in SUBMIT or POLL
    mode, without $s, separated by newlines, exit with status 0.
  * Connect error: exit with status 3.
  * Polled at startup.
* Invoked with "GET-SUPPORTED-TEMPLATES" as the value of the
  $CERTMONGER_OPERATION environment variable:
  * Output list of templates/profiles/certtypes which the server claims
    to be able to issue, exit with status 0.
  * Connect error: exit with status 3.
  * Polled at startup.
* Invoked with "GET-DEFAULT-TEMPLATE" as the value of the
  $CERTMONGER_OPERATION environment variable:
  * Output a single template/profile/certtype which the server claims
    to be able to issue, which we'll assign to new requests if there's
    no value to be recovered from an already-issued certificate and
    none is specified on the command line, exit with status 0.
  * Connect error: exit with status 3.
  * Polled at startup.

* Other operations will be defined later.
  * Operation not supported by this helper -> exit with status 6.

Operations to be added (tentative):
  * Caching CRLs and delta CRLs.

For testing purposes, a helper can be added by creating a file in the CAs
directory (usually /var/lib/certmonger/cas) with these contents:
  id=Test
  ca_type=EXTERNAL
  ca_is_default=0
  ca_external_helper=/usr/libexec/certmonger/test-submit-helper

Passing the "-c Test" flag to the "getcert request" command will then use the
helper to attempt enrollment.

This, with some built-in defaults that provide the same result when no
existing CAs file defines a CA named "IPA", is how the daemon knows about IPA.
The ipa-getcert client, meanwhile, just assumes that clients want to use the
CA nicknamed "IPA".