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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
= The CA user interface tools =
[[TracNav(doc/RPKI/TOC)]]
[[PageOutline]]
The design of rpkid and pubd assumes that certain tasks can be thrown
over the wall to the registry's back end operation. This was a
deliberate design decision to allow rpkid and pubd to remain
independent of existing database schema, business PKIs, and so forth
that a registry might already have. All very nice, but it leaves
someone who just wants to test the tools or who has no existing back
end with a fairly large programming project. The user interface tools
attempt to fill that gap. Together with irdbd, these tools consitute
the "IR back-end" (IRBE) programs.
[[./rpkic|rpkic]] is a command line interface to the the IRBE. The
[[./GUI|web interface]] is a Django-based graphical user interface to
the IRBE. The two user interfaces are built on top of the same
libraries, and can be used fairly interchangeably. Most users will
probably prefer the GUI, but the command line interface may be useful
for scripted control, for testing, or for environments where running a
web server is not practical.
A large registry which already has its own back-end system might want
to roll their own replacement for the entire IRBE package. The tools
are designed to allow this.
The user interface tools support two broad classes of operations:
1. Relationship management: setting up relationships between RPKI
parent and child entities and between publication repositories and
their clients. This is primarily about exchange of BPKI keys with
other entities and learning the service URLs at which rpkid should
contact other servers. We refer to this as the "setup phase".
2. Operation of rpkid once relationships have been set up: issuing
ROAs, assigning resources to children, and so forth. We refer to
this as the "data maintenance" phase.
During setup phase, the tools generate and processes small XML
messages, which they expects the user to ship to and from its parents,
children, etc via some out-of-band means (email, perhaps with PGP
signatures, USB stick, we really don't care). During data maintenance
phase, the tools control the operation of rpkid and pubd.
While the normal way to enter data during maintenance phase is by
filling out web forms, there's also a file-based format which can be
used to upload and download data from the GUI; the command line tool
uses the same file format. These files are simple
whitespace-delimited text files (".csv files" -- the name is
historical, at one point these were parsed and generated using the
Python "csv" library, and the name stuck). The intent is that these
be very simple files that are easy to parse or to generate as a dump
from relational database, spreadsheet, awk script, whatever works in
your environment.
As with rpkid and pubd, the user interface tools use a configuration
file, which defaults to the same system-wide rpki.conf file as the
other programs.
== Overview of setup phase == #overview
While the specific commands one uses differ depending on whether you
are using the command line tool or the GUI, the basic operations
during setup phase are the same:
1. If you haven't already done so,
[[Installation|install the software]], create the
[[Configuration|rpki.conf]] for your installation, and
[[MySQLSetup|set up the MySQL database]].
2. If you haven't already done so, create the initial BPKI database
for your installation by running the "rpkic initialize" command.
This will also create a BPKI identity for the handle specified in
your rpki.conf file. BPKI initialization is tied to creation of
the initial BPKI identity for historical reasons. These operations
probably ought to be handled by separate commands, and may be in
the future.
3. If you haven't already done so, start the servers, using the
{{{rpki-start-servers}}} script.
4. Send a copy of the XML identity file written out by "rpkic
initialize" to each of your parents, somehow (email, USB stick,
carrier pigeon, we don't care). The XML identity file will have a
filename like ./${handle}.identity.xml where "." is the directory
in which you ran rpkic and ${handle} is the handle set in your
rpki.conf file or selected with rpkic's {{{select_identity}}}
command. This XML identity file tells each of your parents what
you call yourself, and supplies each parent with a trust anchor for
your resource-holding BPKI.
5. Each of your parents configures you as a child, using the XML
identity file you supplied as input. This registers your data with
the parent, including BPKI cross-registration, and generates a
return message containing your parent's BPKI trust anchors, a
service URL for contacting your parent via the "up-down" protocol,
and (usually) either an offer of publication service (if your
parent operates a repository) or a referral from your parent to
whatever publication service your parent does use. Referrals
include a CMS-signed authorization token that the repository
operator can use to determine that your parent has given you
permission to home underneath your parent in the publication tree.
6. Each of your parents sends (...) back the response XML file
generated by the "configure_child" command.
7. You feed the response message you just got into the IRBE using
rpkic's "configure_parent" command. This registers the
parent's information in your database, handles BPKI
cross-certification of your parent., and processes the repository
offer or referral to generate a publication request message.
8. You send (...) the publication request message to the repository.
The {{{contact_info}}} element in the request message should (in
theory) provide some clue as to where you should send this.
9. The repository operator processes your request using rpkic's "configure_publication_client" command. This registers
your information, including BPKI cross-certification, and generates
a response message containing the repository's BPKI trust anchor
and service URL.
10. Repository operator sends (...) the publication confirmation
message back to you.
11. You process the publication confirmation message using rpkic's "configure_repository" command.
At this point you should, in theory, have established relationships,
exchanged trust anchors, and obtained service URLs from all of your
parents and repositories.
== Troubleshooting ==
If you run into trouble setting up this package, the first thing to do
is categorize the kind of trouble you are having. If you've gotten
far enough to be running the daemons, check their log files. If
you're seeing Python exceptions, read the error messages. If you're
getting CMS errors, check to make sure that you're using all the right
BPKI certificates and service contact URLs.
If you've completed the steps above, everything appears to have gone
OK, but nothing seems to be happening, the first thing to do is check
the logs to confirm that nothing is actively broken. rpkid's log
should include messages telling you when it starts and finishes its
internal "cron" cycle. It can take several cron cycles for resources
to work their way down from your parent into a full set of
certificates and ROAs, so have a little patience. rpkid's log should
also include messages showing every time it contacts its parent(s) or
attempts to publish anything.
rcynic in fully verbose mode provides a fairly detailed
explanation of what it's doing and why objects that fail have
failed.
You can use rsync (sic) to examine the contents of a publication
repository one directory at a time, without attempting validation,
by running rsync with just the URI of the directory on its command
line:
{{{
#!sh
$ rsync rsync://rpki.example.org/where/ever/
}}}
If you need to examine RPKI objects in detail, you have a few options:
* The [[../../Utils|RPKI utilities]] include several programs for dumping
RPKI-specific objects in text form.
* The OpenSSL command line program can also be useful for examining
and manipulating certificates and CMS messages, although the syntax
of some of the commands can be a bit obscure.
* Peter Gutmann's excellent
[[http://www.cs.auckland.ac.nz/~pgut001/dumpasn1.c|dumpasn1]]
program may be useful if you are desperate enough that you need to
examine raw ASN.1 objects.
|
