diff options
Diffstat (limited to 'docs')
25 files changed, 0 insertions, 1450 deletions
diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index a568b5e4..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -# $Id$ - -all: repository-engine-objects.pdf bpki.pdf - -bpki.pdf: bpki-symmetric.pdf bpki-asymmetric.pdf - -.SUFFIXES: .pdf .dot .tex - -.dot.pdf: - dot -Tps2 $< | ps2pdf - $@ - -.tex.pdf: - pdflatex $< - pdflatex $< - rm -f $*.log $*.aux diff --git a/docs/README b/docs/README deleted file mode 100644 index 26bc0688..00000000 --- a/docs/README +++ /dev/null @@ -1,27 +0,0 @@ -$Id$ - -Ok, there's getting to be enough stuff in this directory to be -confusing. - -README This file - -entity-decompose.pdf An overview presentation - -images Some old pictures - -left-right-protocol Pseudo-code for left-right protocol - -left-right-xml XML samples of left-right protocol - -presentations More presentations - -publication-protocol Pseudo-code for publication protocol - -repository-engine-objects.dot Objects in the RPKI engine (PDF) -repository-engine-objects.pdf Graphviz source for " - -repository-structure.txt Old notes on repository structure - -signed-manifests ASN.1 for signed manifests - -up-down-protocol Pointer to up-down protocol specification diff --git a/docs/bpki-asymmetric.dot b/docs/bpki-asymmetric.dot deleted file mode 100644 index 739cd6ee..00000000 --- a/docs/bpki-asymmetric.dot +++ /dev/null @@ -1,84 +0,0 @@ -// $Id$ -// -// Color code: -// Black: Hosting entity -// Blue: Hosted entity -// Red: Cross-certified peer -// -// Shape code: -// Octagon: TA -// Diamond: CA -// Record: EE - -digraph bpki_asymmetric { - rotate = 90; size = "11,8.5"; splines = true; ratio = fill; - - // Hosting entity - node [ color = black, shape = record ]; - TA [ shape = octagon ]; - rpkid [ label = "rpkid|{HTTPS server|HTTPS left-right client|CMS left-right}" ]; - irdbd [ label = "irdbd|{HTTPS left-right server|CMS left-right}" ]; - irbe [ label = "IRBE|{HTTPS left-right client|CMS left-right}" ]; - - // Hosted entities - node [ color = blue, fontcolor = blue ]; - Alice_CA [ shape = diamond ]; - Ellen_CA [ shape = diamond ]; - - // Peers - node [ color = red, fontcolor = red, shape = diamond ]; - Bob_CA; - Carol_CA; - Dave_CA; - Frank_CA; - Ginny_CA; - Harry_CA; - - // EE certs issued to us by peers - node [ color = red, fontcolor = red, shape = record ]; - Alice_Bob_EE [ label = "Alice-Bob\nBSC EE|{HTTPS up-down client|CMS up-down}" ]; - Alice_Carol_EE [ label = "Alice-Carol\nBSC EE|{HTTPS up-down client|CMS up-down}" ]; - Alice_Dave_EE [ label = "Alice-Dave\nBSC EE|{HTTPS up-down client|CMS up-down}" ]; - Ellen_Frank_EE [ label = "Ellen-Frank\nBSC EE|{HTTPS up-down client|CMS up-down}" ]; - Ellen_Ginny_EE [ label = "Ellen-Ginny\nBSC EE|{HTTPS up-down client|CMS up-down}" ]; - Ellen_Harry_EE [ label = "Ellen-Harry\nBSC EE|{HTTPS up-down client|CMS up-down}" ]; - Bob_EE [ label = "Bob\nEE|{HTTPS up-down|CMS up-down}" ]; - Carol_EE [ label = "Carol\nEE|{HTTPS up-down|CMS up-down}" ]; - Dave_EE [ label = "Dave\nEE|{HTTPS up-down|CMS up-down}" ]; - Frank_EE [ label = "Frank\nEE|{HTTPS up-down|CMS up-down}" ]; - Ginny_EE [ label = "Ginny\nEE|{HTTPS up-down|CMS up-down}" ]; - Harry_EE [ label = "Bob\nEE|{HTTPS up-down|CMS up-down}" ]; - - edge [ color = black, style = solid ]; - TA -> Alice_CA; - TA -> Ellen_CA; - - edge [ color = black, style = dotted ]; - TA -> rpkid; - TA -> irdbd; - TA -> irbe; - - edge [ color = blue, style = solid ]; - Alice_CA -> Bob_CA; - Alice_CA -> Carol_CA; - Alice_CA -> Dave_CA; - Ellen_CA -> Frank_CA; - Ellen_CA -> Ginny_CA; - Ellen_CA -> Harry_CA; - - edge [ color = red, style = dotted ]; - Bob_CA -> Alice_Bob_EE; - Carol_CA -> Alice_Carol_EE; - Dave_CA -> Alice_Dave_EE; - Frank_CA -> Ellen_Frank_EE; - Ginny_CA -> Ellen_Ginny_EE; - Harry_CA -> Ellen_Harry_EE; - - edge [ color = red, style = solid ]; - Bob_CA -> Bob_EE; - Carol_CA -> Carol_EE; - Dave_CA -> Dave_EE; - Frank_CA -> Frank_EE; - Ginny_CA -> Ginny_EE; - Harry_CA -> Harry_EE; -} diff --git a/docs/bpki-asymmetric.pdf b/docs/bpki-asymmetric.pdf Binary files differdeleted file mode 100644 index fbd0362d..00000000 --- a/docs/bpki-asymmetric.pdf +++ /dev/null diff --git a/docs/bpki-symmetric.dot b/docs/bpki-symmetric.dot deleted file mode 100644 index 48e89483..00000000 --- a/docs/bpki-symmetric.dot +++ /dev/null @@ -1,74 +0,0 @@ -// $Id$ -// -// Color code: -// Black: Hosting entity -// Blue: Hosted entity -// Red: Cross-certified peer -// -// Shape code: -// Octagon: TA -// Diamond: CA -// Record: EE - -digraph bpki_symmetric { - rotate = 90; size = "11,8.5"; splines = true; ratio = fill; - - // Hosting entity - node [ color = black, shape = record ]; - TA [ shape = octagon ]; - rpkid [ label = "rpkid|{HTTPS server|HTTPS left-right client|CMS left-right}" ]; - irdbd [ label = "irdbd|{HTTPS left-right server|CMS left-right}" ]; - irbe [ label = "IRBE|{HTTPS left-right client|CMS left-right}" ]; - - // Hosted entities - node [ color = blue, fontcolor = blue ]; - Alice_CA [ shape = diamond ]; - Alice_EE [ label = "Alice\nBSC EE|{HTTPS up-down client|CMS up-down}" ]; - Ellen_CA [ shape = diamond ]; - Ellen_EE [ label = "Ellen\nBSC EE|{HTTPS up-down client|CMS up-down}" ]; - - // Peers - node [ color = red, fontcolor = red, shape = diamond ]; - Bob_CA; - Carol_CA; - Dave_CA; - Frank_CA; - Ginny_CA; - Harry_CA; - node [ shape = record ]; - Bob_EE [ label = "Bob\nEE|{HTTPS up-down|CMS up-down}" ]; - Carol_EE [ label = "Carol\nEE|{HTTPS up-down|CMS up-down}" ]; - Dave_EE [ label = "Dave\nEE|{HTTPS up-down|CMS up-down}" ]; - Frank_EE [ label = "Frank\nEE|{HTTPS up-down|CMS up-down}" ]; - Ginny_EE [ label = "Ginny\nEE|{HTTPS up-down|CMS up-down}" ]; - Harry_EE [ label = "Bob\nEE|{HTTPS up-down|CMS up-down}" ]; - - edge [ color = black, style = solid ]; - TA -> Alice_CA; - TA -> Ellen_CA; - - edge [ color = black, style = dotted ]; - TA -> rpkid; - TA -> irdbd; - TA -> irbe; - - edge [ color = blue, style = solid ]; - Alice_CA -> Bob_CA; - Alice_CA -> Carol_CA; - Alice_CA -> Dave_CA; - Ellen_CA -> Frank_CA; - Ellen_CA -> Ginny_CA; - Ellen_CA -> Harry_CA; - - edge [ color = blue, style = dotted ]; - Alice_CA -> Alice_EE; - Ellen_CA -> Ellen_EE; - - edge [ color = red, style = solid ]; - Bob_CA -> Bob_EE; - Carol_CA -> Carol_EE; - Dave_CA -> Dave_EE; - Frank_CA -> Frank_EE; - Ginny_CA -> Ginny_EE; - Harry_CA -> Harry_EE; -} diff --git a/docs/bpki-symmetric.pdf b/docs/bpki-symmetric.pdf Binary files differdeleted file mode 100644 index 9db46451..00000000 --- a/docs/bpki-symmetric.pdf +++ /dev/null diff --git a/docs/bpki.pdf b/docs/bpki.pdf Binary files differdeleted file mode 100644 index 979c1380..00000000 --- a/docs/bpki.pdf +++ /dev/null diff --git a/docs/bpki.tex b/docs/bpki.tex deleted file mode 100644 index c07c6534..00000000 --- a/docs/bpki.tex +++ /dev/null @@ -1,80 +0,0 @@ -% $Id$ -% -\documentclass[11pt]{article} -\usepackage[pdftex]{graphicx} -\usepackage{palatino} -\usepackage{color} -\DeclareGraphicsExtensions{.pdf} -\setlength{\topmargin}{0in} -\setlength{\headheight}{0in} -\setlength{\headsep}{0in} -\setlength{\oddsidemargin}{0in} -\setlength{\evensidemargin}{0in} -\setlength{\textheight}{9in} -\setlength{\textwidth}{6.5in} -\setlength{\parskip}{2ex} -\setlength{\parindent}{0in} -\hyphenpenalty=5000 -\tolerance=1000 -\hbadness=9999 -\sloppy -\pagestyle{plain} -% -\begin{document} - -\section*{Implementation experience with the two BPKI models} - -Having recently converted my code base to the single-trust-anchor -model Russ recommended, I thought it might be useful to share what -I've learned. This may not apply to all implementations, but it does -apply to mine, and given what I understand of RIPE's business model, -it will probably apply to RIPE's implementation as well. - -In spite of a strong desire to do so, I was not able to use exactly -the same BPKI keys and certificates for HTTPS and CMS. The reason for -this is simple: each hosted entity in my engine has its own BPKI, as -does the hosting entity, but the HTTPS listener is shared. The only -ways I know of to avoid this would be to use separate listeners for -each hosted entity, which scales poorly, or to rely on the TLS -``Server Name Indication'' extension (RFC 4366 3.1) which is not yet -widely implemented. - -\begin{figure}[hbp] -\includegraphics[width = 6.5in]{bpki-symmetric} -\caption{Symmetric BPKI model} -\label{bpki-symmetric} -\end{figure} - -Figure \ref{bpki-symmetric} shows my engine's view of the BPKI tree in -the symmetric model. Black objects belong to the hosting entity, blue -objects belong to the hosted entities, red objects are cross-certified -objects from peers. The arrows indicate certificate issuance: solid -arrows are the ones that my own RPKI engine will care about during -certificate validation, dotted arrows show the origin of EE -certificates my engine uses to sign things. ``BSC'' stands for -``business signing context,'' which is a database object in my -implementation representing the context needed to sign a CMS message -or TLS session. - -Other than the above-mentioned annoyance with the HTTPS server -certificate, the ``symmetric'' BPKI model worked out pretty much as -expected here. The certificate tree looks complicated, but the set of -certificates needed to build a particular validation chain is obvious, -again excepting the HTTPS server case, where client certificate is the -first hint that the engine has of the client's identity, so the server -must be prepared to accept any current client certificate. - -\begin{figure}[hbp] -\includegraphics[width = 6.5in]{bpki-asymmetric} -\caption{Asymmetric BPKI model} -\label{bpki-asymmetric} -\end{figure} - -Figure \ref{bpki-asymmetric} shows my engine's view of the BPKI tree -in the asymmetric model. Note that not much has changed here from the -symmetric case. As far as I can tell, the asymmetric model is just as -complex for my engine as the symmetric model; the only real difference -is that the engine has to keep track of a larger number of BSC EE -certificates in the asymmetric case. - -\end{document} diff --git a/docs/entity-decompose.pdf b/docs/entity-decompose.pdf Binary files differdeleted file mode 100644 index afde3c27..00000000 --- a/docs/entity-decompose.pdf +++ /dev/null diff --git a/docs/images/prague-whiteboard-2007-03-21-02-29-14.jpg b/docs/images/prague-whiteboard-2007-03-21-02-29-14.jpg Binary files differdeleted file mode 100644 index 79c0a807..00000000 --- a/docs/images/prague-whiteboard-2007-03-21-02-29-14.jpg +++ /dev/null diff --git a/docs/images/prague-whiteboard-2007-03-22-21-50-26.jpg b/docs/images/prague-whiteboard-2007-03-22-21-50-26.jpg Binary files differdeleted file mode 100644 index 4c3c828d..00000000 --- a/docs/images/prague-whiteboard-2007-03-22-21-50-26.jpg +++ /dev/null diff --git a/docs/images/prague-whiteboard-2007-03-22-23-15-01.jpg b/docs/images/prague-whiteboard-2007-03-22-23-15-01.jpg Binary files differdeleted file mode 100644 index 7b973ab0..00000000 --- a/docs/images/prague-whiteboard-2007-03-22-23-15-01.jpg +++ /dev/null diff --git a/docs/images/repository-structure.dot b/docs/images/repository-structure.dot deleted file mode 100644 index 7154202d..00000000 --- a/docs/images/repository-structure.dot +++ /dev/null @@ -1,42 +0,0 @@ -// $URL$ -// $Id$ -// -// Pictures to go with repository-structure.txt. First picture is rekeying b with -// a g(ski)/g(ski)/g(ski).cer model, second is with stable meaningless identifiers. - -graph rekeying_ski { - rotate=90; size="11,8.5"; splines=true; ratio=fill; - node [ shape=box ]; - a [ color=black, label="rsync://host/foo/g(ski(a)).cer" ] - b [ color=red, label="rsync://host/foo/g(ski(a))/g(ski(b)).cer" ] - c [ color=red, label="rsync://host/foo/g(ski(a))/g(ski(b))/g(ski(c)).cer" ] - d [ color=red, label="rsync://host/foo/g(ski(a))/g(ski(b))/g(ski(c))/g(ski(d)).cer" ] - a -- b [ color=red ]; - b -- c [ color=red ]; - c -- d [ color=red ]; - b_ [ color=green, label="rsync://host/foo/g(ski(a))/g(ski(b')).cer" ] - c_ [ color=green, label="rsync://host/foo/g(ski(a))/g(ski(b'))/g(ski(c)).cer" ] - d_ [ color=green, label="rsync://host/foo/g(ski(a))/g(ski(b'))/g(ski(c))/g(ski(d)).cer" ] - a -- b_ [ color=green ]; - b_ -- c_ [ color=green ]; - c_ -- d_ [ color=green ]; -} - -graph rekeying_gensym { - rotate=90; size="11,8.5"; splines=true; ratio=fill; - node [ shape=box ]; - a [ color=black, label="rsync://host/foo/g(ski(a)).cer" ] - b [ color=red, label="rsync://host/foo/G001/g(ski(b)).cer" ] - c [ color=black, label="rsync://host/foo/G001/G002/g(ski(c)).cer" ] - d [ color=black, label="rsync://host/foo/G001/G002/G003/g(ski(d)).cer" ] - a -- b [ color=red ]; - b -- c [ color=red ]; - c -- d [ color=black ]; - b_ [ color=green, label="rsync://host/foo/G001/g(ski(b')).cer" ] - a -- b_ [ color=green ]; - b_ -- c [ color=green ]; -} - -// Local Variables: -// compile-command: "dot -Tps2 repository-structure.dot | ps2pdf - repository-structure.pdf" -// End: diff --git a/docs/images/repository-structure.pdf b/docs/images/repository-structure.pdf Binary files differdeleted file mode 100644 index 0fcc7615..00000000 --- a/docs/images/repository-structure.pdf +++ /dev/null diff --git a/docs/images/whiteboard-object-model.dot b/docs/images/whiteboard-object-model.dot deleted file mode 100644 index 3c61f3ab..00000000 --- a/docs/images/whiteboard-object-model.dot +++ /dev/null @@ -1,65 +0,0 @@ -// $URL$ -// $Id$ - -// This is an attempt to capture -// http://subvert-rpki.hactrn.net/docs/prague-whiteboard-2007-03-22-23:15:01.jpg - -// {arrowhead,arrowtail} shapes to use for database object relationships: -// 1- none -// m- crow -// Color code: -// Blue: visible in left-right protocol -// Green: created on the fly - -// Explanation for many-many mapping beween CA and child objects -// (courtesy of RobL): Each child is an entity; each CA can have -// multiple children, and each child can hold certs from multiple CAs. - -digraph rpki_engine_objects { - rotate=90; size="11,8.5"; splines=true; ratio=fill; - node [ shape=record ]; - - // Objects visible in left-to-right protocol - node [ color=blue ]; - self [ label="Self|{Preferences}" ]; - parent [ label="Parent|{URI|TA}" ]; - repo [ label="Repository|{URI|TA}" ]; - child [ label="Child|{TA}" ]; - biz_sign [ label="Business\nSigning Context|{Keypair|CertChain}" ]; - - // Objects created on the fly by the RPKI engine - node [ color=green ]; - ca [ label="CA|{CRL #|Last Issued Serial #}" ]; - child_cert [ label="Child Certificate" ]; - ee_cert [ label="EE Certificate|{ROA}" ]; - ca_key_pair [ label="CA Key Pair|{Latest CA Certificate|Latest CRL}" ]; - - // One-many mappings - edge [ color=blue, arrowtail=none, arrowhead=crow ]; - biz_sign -> child; - biz_sign -> parent; - biz_sign -> repo; - self -> child; - self -> parent; - repo -> parent; - - // Many-many mappings - edge [ color=green, arrowtail=crow, arrowhead=crow ]; - ca -> child; - - // One-many mappings - edge [ color=green, arrowtail=none, arrowhead=crow ]; - ca -> ca_key_pair; - child -> child_cert; - self -> ca; - parent -> ca; - - // Weird one-many - edge [ color=green, arrowtail=none, arrowhead=crow, style=dashed ]; - ca_key_pair -> child_cert; - ca_key_pair -> ee_cert; -} - -// Local Variables: -// compile-command: "neato -Tps2 whiteboard-object-model.dot | ps2pdf - whiteboard-object-model.pdf" -// End: diff --git a/docs/images/whiteboard-object-model.pdf b/docs/images/whiteboard-object-model.pdf Binary files differdeleted file mode 100644 index 9b7da850..00000000 --- a/docs/images/whiteboard-object-model.pdf +++ /dev/null diff --git a/docs/left-right-protocol b/docs/left-right-protocol deleted file mode 100644 index 1ec9d1f6..00000000 --- a/docs/left-right-protocol +++ /dev/null @@ -1,477 +0,0 @@ -Left-right protocol - - The left-right protocol is really two separate client/server protocols - over separate channels between the RPKI engine and the IR back end - (IRBE). - - The IRBE is the client for one of the subprotocols, the RPKI engine is - the client for the other. - -Terminology - - * IRBE: Internet Registry Back End - - * IRDB: Internet Registry Data Base - - * BPKI: Business PKI - - * RPKI: Resource PKI - -initiated by the IRBE - - This part of the protcol uses a kind of message-passing. Each object - that the RPKI engine knows about takes five messages: "create", "set", - "get", "list", and "destroy". Actions which are not just data - operations on objects are handled via an SNMP-like mechanism, as if - they were fields to be set. For example, to generate a keypair one - "sets" the "generate-keypair" field of a BSC object, even though there - is no such field in the object itself as stored in SQL. This is a bit - of a kludge, but the reason for doing it as if these were variables - being set is to allow composite operations such as creating a BSC, - populating all of its data fields, and generating a keypair, all as a - single operation. With this model, that's trivial, otherwise it's at - least two round trips. - - Fields can be set in either "create" or "set" operations, the - difference just being whether the object already exists. A "get" - operation returns all visible fields of the object. A "list" operation - returns a list containing what "get" would have returned on each of - those objects. - - Left-right protocol objects are encoded as signed CMS messages - containing XML as eContent and using an eContentType OID of id-ct-xml - (1.2.840.113549.1.9.16.1.28). These CMS messages are in turn passed as - the data for HTTPS POST operations, with an HTTP content type of - "application/x-rpki" for both the POST data and the response data. - - All operations allow an optional "tag" attribute which can be any - alphanumeric token. The main purpose of the tag attribute is to allow - batching of multiple requests into a single PDU. - -<self/> object - - A <self/> object represents one virtual RPKI engine. In simple cases - where the RPKI engine operator operates the engine only on their own - behalf, there will only be one <self/> object, representing the engine - operator's organization, but in environments where the engine operator - hosts other entities, there will be one <self/> object per hosted - entity (probably including the engine operator's own organization, - considered as a hosted customer of itself). - - Some of the RPKI engine's configured parameters and data are shared by - all hosted entities, but most are tied to a specific <self/> object. - Data which are shared by all hosted entities are referred to as - "per-engine" data, data which are specific to a particular <self/> - object are "per-self" data. - - Since all other RPKI engine objects refer to a <self/> object via a - "self_id" value, one must create a <self/> object before one can - usefully configure any other left-right protocol objects. - - Every <self/> object has a self_id attribute, which must be specified - for the "set", "get", and "destroy" actions. - - Payload data which can be configured in a <self/> object: - - * use_hsm (attribute): Whether to use a Hardware Signing Module. At - present this option has no effect, as the implementation does not - yet support HSMs. - - * crl_interval (attribute): Positive integer representing the planned - lifetime of an RPKI CRL for this <self/>, measured in seconds. - - * regen_margin (attribute): Positive integer representing how long - before expiration of an RPKI certificiate a new one should be - generated, measured in seconds. At present this only affects the - one-off EE certificates associated with ROAs. - - * bpki_cert (element): BPKI CA certificate for this <self/>. This is - used as part of the certificate chain when validating incoming TLS - and CMS messages, and should be the issuer of cross-certification - BPKI certificates used in <repository/>, <parent/>, and <child/> - objects. If the bpki_glue certificate is in use (below), the - bpki_cert certificate should be issued by the bpki_glue - certificate; otherwise, the bpki_cert certificate should be issued - by the per-engine bpki_ta certificate. - - * bpki_glue (element): Another BPKI CA certificate for this <self/>, - usually not needed. Certain pathological cross-certification cases - require a two-certificate chain due to issuer name conflicts. If - used, the bpki_glue certificate should be the issuer of the - bpki_cert certificate and should be issued by the per-engine - bpki_ta certificate; if not needed, the bpki_glue certificate - should be left unset. - - Control attributes that can be set to "yes" to force actions: - - * rekey: Start a key rollover for every RPKI CA associated with every - <parent/> object associated with this <self/> object. This is the - first phase of a key rollover operation. - - * revoke: Revoke any remaining certificates for any expired key - associated with any RPKI CA for any <parent/> object associated - with this <self/> object. This is the second (cleanup) phase for a - key rollover operation; it's separate from the first phase to leave - time for new RPKI certificates to propegate and be installed. - - * reissue: Not implemented, may be removed from protocol. Original - theory was that this operation would force reissuance of any object - with a changed key, but as that happens automatically as part of - the key rollover mechanism this operation seems unnecessary. - - * run_now: Force immediate processing for all tasks associated with - this <self/> object that would ordinarily be performed under cron. - Not currently implemented. - - * publish_world_now: Force (re)publication of every publishable - object for this <self/> object. Not currently implemented. Intended - to aid in recovery if RPKI engine and publication engine somehow - get out of sync. - -<bsc/> object - - The <bsc/> ("business signing context") object represents all the BPKI - data needed to sign outgoing CMS or HTTPS messages. Various other - objects include pointers to a <bsc/> object. Whether a particular - <self/> uses only one <bsc/> or multiple is a configuration decision - based on external requirements: the RPKI engine code doesn't care, it - just cares that, for any object representing a relationship for which - it must sign messages, there be a <bsc/> object that it can use to - produce that signature. - - Every <bsc/> object has a bsc_id, which must be specified for the - "get", "set", and "destroy" actions. Every <bsc/> also has a self_id - attribute which indicates the <self/> object with which this <bsc/> - object is associated. - - Payload data which can be configured in a <isc/> object: - - * signing_cert (element): BPKI certificate to use when generating a - signature. - - * signing_cert_crl (element): CRL which would list signing_cert if it - had been revoked. - - Control attributes that can be set to "yes" to force actions: - - * generate_keypair: Generate a new BPKI keypair and return a PKCS #10 - certificate request. The resulting certificate, once issued, should - be configured as this <bsc/> object's signing_cert. - - Additional attributes which may be specified when specifying - "generate_keypair": - - * key_type: Type of BPKI keypair to generate. "rsa" is both the - default and, at the moment, the only allowed value. - - * hash_alg: Cryptographic hash algorithm to use with this keypair. - "sha256" is both the default and, at the moment, the only allowed - value. - - * key_length: Length in bits of the keypair to be generated. "2048" - is both the default and, at the moment, the only allowed value. - - Replies to "create" and "set" actions that specify "generate-keypair" - include a <bsc_pkcs10/> element, as do replies to "get" and "list" - actions for a <bsc/> object for which a "generate-keypair" command has - been issued. The RPKI engine stores the PKCS #10 request, which allows - the IRBE to reuse the request if and when it needs to reissue the - corresponding BPKI signing certificate. - -<parent/> object - - The <parent/> object represents the RPKI engine's view of a particular - parent of the current <self/> object in the up-down protocol. Due to - the way that the resource hierarchy works, a given <self/> may obtain - resources from multiple parents, but it will always have at least one; - in the case of IANA or an RIR, the parent RPKI engine may be a trivial - stub. - - Every <parent/> object has a parent_id, which must be specified for the - "get", "set", and "destroy" actions. Every <parent/> also has a self_id - attribute which indicates the <self/> object with which this <parent/> - object is associated, a bsc_id attribute indicating the <bsc/> object - to be used when signing messages sent to this parent, and a - repository_id indicating the <repository/> object to be used when - publishing issued by the certificate issued by this parent. - - Payload data which can be configured in a <parent/> object: - - * peer_contact_uri (attribute): HTTPS URI used to contact this - parent. - - * sia_base (attribute): The leading portion of an rsync URI that the - RPKI engine should use when composing the publication URI for - objects issued by the RPKI certificate issued by this parent. - - * sender_name (attribute): Sender name to use in the up-down protocol - when talking to this parent. The RPKI engine doesn't really care - what this value is, but other implementations of the up-down - protocol do care. - - * recipient_name (attribute): Recipient name to use in the up-down - protocol when talking to this parent. The RPKI engine doesn't - really care what this value is, but other implementations of the - up-down protocol do care. - - * bpki_cms_cert (element): BPKI CMS CA certificate for this - <parent/>. This is used as part of the certificate chain when - validating incoming CMS messages If the bpki_cms_glue certificate - is in use (below), the bpki_cms_cert certificate should be issued - by the bpki_cms_glue certificate; otherwise, the bpki_cms_cert - certificate should be issued by the bpki_cert certificate in the - <self/> object. - - * bpki_cms_glue (element): Another BPKI CMS CA certificate for this - <parent/>, usually not needed. Certain pathological - cross-certification cases require a two-certificate chain due to - issuer name conflicts. If used, the bpki_cms_glue certificate - should be the issuer of the bpki_cms_cert certificate and should be - issued by the bpki_cert certificate in the <self/> object; if not - needed, the bpki_cms_glue certificate should be left unset. - - * bpki_https_cert (element): BPKI HTTPS CA certificate for this - <parent/>. This is like the bpki_cms_cert object, only used for - validating incoming TLS messages rather than CMS. - - * bpki_cms_glue (element): Another BPKI HTTPS CA certificate for this - <parent/>, usually not needed. This is like the bpki_cms_glue - certificate, only used for validating incoming TLS messages rather - than CMS. - - Control attributes that can be set to "yes" to force actions: - - * rekey: This is like the rekey command in the <self/> object, but - limited to RPKI CAs under this parent. - - * reissue: This is like the reissue command in the <self/> object, - but limited to RPKI CAs under this parent. - - * revoke: This is like the revoke command in the <self/> object, but - limited to RPKI CAs under this parent. - -<child/> object - - The <child/> object represents the RPKI engine's view of particular - child of the current <self/> in the up-down protocol. - - Every <child/> object has a parent_id, which must be specified for the - "get", "set", and "destroy" actions. Every <child/> also has a self_id - attribute which indicates the <self/> object with which this <child/> - object is associated. - - Payload data which can be configured in a <child/> object: - - * bpki_cert (element): BPKI CA certificate for this <child/>. This is - used as part of the certificate chain when validating incoming TLS - and CMS messages. If the bpki_glue certificate is in use (below), - the bpki_cert certificate should be issued by the bpki_glue - certificate; otherwise, the bpki_cert certificate should be issued - by the bpki_cert certificate in the <self/> object. - - * bpki_glue (element): Another BPKI CA certificate for this <child/>, - usually not needed. Certain pathological cross-certification cases - require a two-certificate chain due to issuer name conflicts. If - used, the bpki_glue certificate should be the issuer of the - bpki_cert certificate and should be issued by the bpki_cert - certificate in the <self/> object; if not needed, the bpki_glue - certificate should be left unset. - - Control attributes that can be set to "yes" to force actions: - - * reissue: Not implemented, may be removed from protocol. - -<repository/> object - - The <repository/> object represents the RPKI engine's view of a - particular publication repository used by the current <self/> object. - - Every <repository/> object has a repository_id, which must be specified - for the "get", "set", and "destroy" actions. Every <repository/> also - has a self_id attribute which indicates the <self/> object with which - this <repository/> object is associated. - - Payload data which can be configured in a <repository/> object: - - * peer_contact_uri (attribute): HTTPS URI used to contact this - repository. - - * bpki_cms_cert (element): BPKI CMS CA certificate for this - <repository/>. This is used as part of the certificate chain when - validating incoming CMS messages If the bpki_cms_glue certificate - is in use (below), the bpki_cms_cert certificate should be issued - by the bpki_cms_glue certificate; otherwise, the bpki_cms_cert - certificate should be issued by the bpki_cert certificate in the - <self/> object. - - * bpki_cms_glue (element): Another BPKI CMS CA certificate for this - <repository/>, usually not needed. Certain pathological - cross-certification cases require a two-certificate chain due to - issuer name conflicts. If used, the bpki_cms_glue certificate - should be the issuer of the bpki_cms_cert certificate and should be - issued by the bpki_cert certificate in the <self/> object; if not - needed, the bpki_cms_glue certificate should be left unset. - - * bpki_https_cert (element): BPKI HTTPS CA certificate for this - <repository/>. This is like the bpki_cms_cert object, only used for - validating incoming TLS messages rather than CMS. - - * bpki_cms_glue (element): Another BPKI HTTPS CA certificate for this - <repository/>, usually not needed. This is like the bpki_cms_glue - certificate, only used for validating incoming TLS messages rather - than CMS. - - At present there are no control attributes for <repository/> objects. - -<route_origin/> object - - The <route_origin/> object is a kind of prototype for a ROA. It - contains all the information needed to generate a ROA once the RPKI - engine obtains the appropriate RPKI certificates from its parent(s). - - Note that a <route_origin/> object represents a ROA to be generated on - behalf of <self/>, not on behalf of a <child/>. Thus, a hosted entity - that has no children but which does need to generate ROAs would be - represented by a hosted <self/> with no <child/> objects but one or - more <route_origin/> objects. While lumping ROA generation in with the - other RPKI engine activities may seem a little odd at first, it's a - natural consequence of the design requirement that the RPKI daemon - never transmit private keys across the network in any form; given this - requirement, the RPKI engine that holds the private keys for an RPKI - certificate must also be the engine which generates any ROAs that - derive from that RPKI certificate. - - The precise content of the <route_origin/> has changed over time as the - underlying ROA specification has changed. The current implementation as - of this writing matches what we expect to see in - draft-ietf-sidr-roa-format-03, once it is issued. In particular, note - that the exactMatch boolean from the -02 draft has been replaced by the - prefix and maxLength encoding used in the -03 draft. - - Payload data which can be configured in a <route_origin/> object: - - * as_number (attribute): Autonomous System Number (ASN) to place in - the generated ROA. A single ROA can only grant authorization to a - single ASN; multiple ASNs require multiple ROAs, thus multiple - <route_origin/> objects. - - * ipv4 (attribute): List of IPv4 prefix and maxLength values, see - below for format. - - * ipv6 (attribute): List of IPv6 prefix and maxLength values, see - below for format. - - Control attributes that can be set to "yes" to force actions: - - * suppress_publication: Not implemented, may be removed from - protocol. - - The lists of IPv4 and IPv6 prefix and maxLength values are represented - as comma-separated text strings, with no whitespace permitted. Each - entry in such a string represents a single prefix/maxLength pair. - - ABNF for these address lists: - - - <ROAIPAddress> ::= <address> "/" <prefixlen> [ "-" <max_prefixlen> ] - ; Where <max_prefixlen> defaults to the same - ; value as <prefixlen>. - - <ROAIPAddressList> ::= <ROAIPAddress> *( "," <ROAIPAddress> ) - - - For example, "10.0.1.0/24-32,10.0.2.0/24", which is a shorthand form of - "10.0.1.0/24-32,10.0.2.0/24-24". - -Operations initiated by the RPKI engine - - The left-right protocol also includes queries from the RPKI engine back - to the IRDB. These queries do not follow the message-passing pattern - used in the IRBE-initiated part of the protocol. Instead, there's a - single query back to the IRDB, with a corresponding response. The CMS - and HTTPS encoding are the same as in the rest of the protocol, but the - BPKI certificates will be different as the back-queries and responses - form a separate communication channel. - -<list_resources/> messages - - The <list_resources/> query and response allow the RPKI engine to ask - the IRDB for information about resources assigned to a particular - child. The query must include both a "self_id" attribute naming the - <self/> that is making the request and also a "child_id" attribute - naming the child that is the subject of the query. The query and - response also allow an optional "tag" attribute of the same form used - elsewhere in this protocol, to allow batching. - - A <list_resources/> response includes the following attributes, along - with the tag (if specified), self_id, and child_id copied from the - request: - - * valid_until: A timestamp indicating the date and time at which - certificates generated by the RPKI engine for these data should - expire. The timestamp is expressed as an XML xsd:dateTime, must be - expressed in UTC, and must carry the "Z" suffix indicating UTC. - - * subject_name: An optional text string naming the child. Not - currently used. - - * asn: A list of autonomous sequence numbers, expressed as a - comma-separated sequence of decimal integers with no whitespace. - - * ipv4: A list of IPv4 address prefixes and ranges, expressed as a - comma-separated list of prefixes and ranges with no whitespace. See - below for format details. - - * ipv6: A list of IPv6 address prefixes and ranges, expressed as a - comma-separated list of prefixes and ranges with no whitespace. See - below for format details. - - Entries in a list of address prefixes and ranges can be either - prefixes, which are written in the usual address/prefixlen notation, or - ranges, which are expressed as a pair of addresses denoting the - beginning and end of the range, written in ascending order separated by - a single "-" character. This format is superficially similar to the - format used for prefix and maxLength values in the <route_origin/> - object, but the semantics differ: note in particular that - <route_origin/> objects don't allow ranges, while <list_resources/> - messages don't allow a maxLength specification. - -Error handling - - Error in this protocol are handled at two levels. - - Since all messages in this protocol are conveyed over HTTPS - connections, basic errors are indicated via the HTTP response code. 4xx - and 5xx responses indicate that something bad happened. Errors that - make it impossible to decode a query or encode a response are handled - in this way. - - Where possible, errors will result in a <report_error/> message which - takes the place of the expected protocol response message. - <report_error/> messages are CMS-signed XML messages like the rest of - this protocol, and thus can be archived to provide an audit trail. - - <report_error/> messages only appear in replies, never in queries. The - <report_error/> message can appear on either the "forward" (IRBE as - client of RPKI engine) or "back" (RPKI engine as client of IRDB) - communication channel. - - The <report_error/> message includes an optional "tag" attribute to - assist in matching the error with a particular query when using - batching, and also includes a "self_id" attribute indicating the - <self/> that issued the error. - - The error itself is conveyed in the error_code (attribute). The value - of this attribute is a token indicating the specific error that - occurred. At present this will be the name of a Python exception; the - production version of this protocol will nail down the allowed error - tokens here, probably in the RelaxNG schema. - - The body of the <report_error/> element itself is an optional text - string; if present, this is debugging information. At present this - capabilty is not used, debugging information goes to syslog. - __________________________________________________________________ - - - Generated on Thu Jun 12 02:43:52 2008 for RPKI Engine by doxygen - 1.5.5 diff --git a/docs/presentations/070523.lacnic-pki.pdf b/docs/presentations/070523.lacnic-pki.pdf Binary files differdeleted file mode 100644 index 5ab83fa3..00000000 --- a/docs/presentations/070523.lacnic-pki.pdf +++ /dev/null diff --git a/docs/publication-protocol b/docs/publication-protocol deleted file mode 100644 index 29834874..00000000 --- a/docs/publication-protocol +++ /dev/null @@ -1,227 +0,0 @@ -Publication protocol - - The publication protocol is really two separate client/server - protocols, between different parties. - - The first is a configuration protocol for the IRBE to use to configure - the publication engine, the second is the interface by which authorized - clients request publication of specific objects. - - Much of the architecture of the publication protocol is borrowed from - the left-right protocol: like the left-right protocol, the publication - protocol uses CMS-wrapped XML over HTTPS with the same eContentType OID - and the same HTTPS content-type, and the overall style of the XML - messages is very similar to the left-right protocol. All operations - allow an optional "tag" attribute to allow batching. - - The publication engine operates a single HTTPS server which serves both - of these subprotocols. The two subprotocols share a single server port, - but use distinct URLs. - -Terminology - - * IRBE: Internet Registry Back End - - * IRDB: Internet Registry Data Base - - * BPKI: Business PKI - - * RPKI: Resource PKI - -Publication control subprotocol - - The control subprotocol reuses the message-passing design of the - left-right protocol. Configured objects support the "create", "set", - "get", "list", and "destroy" actions, or a subset thereof when the full - set of actions doesn't make sense. - -<config/> object - - The <config/> object allows configuration of data that apply to the - entire publication server rather than a particular client. - - There is exactly one <config/> object in the publication server, and it - only supports the "set" and "get" actions -- it cannot be created or - destroyed. - - Payload data which can be configured in a <config/> object: - - * bpki_crl (element): This is the BPKI CRL used by the publication - server when signing the CMS wrapper on responses in the publication - subprotocol. As the CRL must be updated at regular intervals, it's - not practical to restart the publication server when the BPKI CRL - needs to be updated. Fortunately, the BPKI model doesn't require - use of a BPKI CRL between the IRBE and the publication server, so - we can use the publication control subprotocol to update the BPKI - CRL. - -<client/> object - - The <client/> object represents one client authorized to use the - publication server. - - The <client/> object supports the full set of "create", "set", "get", - "list", and "destroy" actions. Each client has a "client_id" attribute, - which is used in responses and must be specified in "set", "get", or - "destroy" actions. - - Payload data which can be configured in a <client/> object: - - * base_uri (attribute): This is the base URI below which this client - is allowed to publish data. The publication server may impose - additional constraints in the case of a child publishing beneath - its parent. - - * bpki_cert (element): BPKI CA certificate for this <client/>. This - is used as part of the certificate chain when validating incoming - TLS and CMS messages. If the bpki_glue certificate is in use - (below), the bpki_cert certificate should be issued by the - bpki_glue certificate; otherwise, the bpki_cert certificate should - be issued by the publication engine's bpki_ta certificate. - - * bpki_glue (element): Another BPKI CA certificate for this - <client/>, usually not needed. Certain pathological - cross-certification cases require a two-certificate chain due to - issuer name conflicts. If used, the bpki_glue certificate should be - the issuer of the bpki_cert certificate and should be issued by the - publication engine's bpki_ta certificate; if not needed, the - bpki_glue certificate should be left unset. - -Publication subprotocol - - The publication subprotocol is structured somewhat differently from the - publication control protocol. Objects in the publication subprotocol - represent objects to be published or objects to be withdrawn from - publication. Each kind of object supports two actions: "publish" and - "withdraw". In each case the XML element representing hte object to be - published or withdrawn has a "uri" attribute which contains the - publication URI. For "publish" actions, the XML element body contains - the DER object to be published, encoded in Base64; for "withdraw" - actions, the XML element body is empty. - - In theory, the detailed access control for each kind of object might be - different. In practice, as of this writing, access control for all - objects is a simple check that the client's "base_uri" is a leading - substring of the publication URI. Details of why access control might - need to become more complicated are discussed in a later section. - -<certificate/> object - - The <certificate/> object represents an RPKI certificate to be - published or withdrawn. - -<crl/> object - - The <crl/> object represents an RPKI CRL to be published or withdrawn. - -<manifest/> object - - The <manifest/> object represents an RPKI publication manifest to be - published or withdrawn. - - Note that part of the reason for the batching support in the - publication protocol is because every publication or withdrawal action - requires a new manifest, thus every publication or withdrawal action - will involve at least two objects. - -<roa/> object - - The <roa/> object represents a ROA to be published or withdrawn. - -Error handling - - Error in this protocol are handled at two levels. - - Since all messages in this protocol are conveyed over HTTPS - connections, basic errors are indicated via the HTTP response code. 4xx - and 5xx responses indicate that something bad happened. Errors that - make it impossible to decode a query or encode a response are handled - in this way. - - Where possible, errors will result in a <report_error/> message which - takes the place of the expected protocol response message. - <report_error/> messages are CMS-signed XML messages like the rest of - this protocol, and thus can be archived to provide an audit trail. - - <report_error/> messages only appear in replies, never in queries. The - <report_error/> message can appear on either the "forward" (IRBE as - client of RPKI engine) or "back" (RPKI engine as client of IRDB) - communication channel. - - The <report_error/> message includes an optional "tag" attribute to - assist in matching the error with a particular query when using - batching, and also includes a "self_id" attribute indicating the - <self/> that issued the error. - - The error itself is conveyed in the error_code (attribute). The value - of this attribute is a token indicating the specific error that - occurred. At present this will be the name of a Python exception; the - production version of this protocol will nail down the allowed error - tokens here, probably in the RelaxNG schema. - - The body of the <report_error/> element itself is an optional text - string; if present, this is debugging information. At present this - capabilty is not used, debugging information goes to syslog. - -Additional access control considerations. - - As detailed above, the publication protocol is trivially simple. This - glosses over two bits of potential complexity: - - * In the case where parent and child are sharing a repository, we'd - like to nest child under parent, because testing has demonstrated - that even on relatively slow hardware the delays involved in - setting up separate rsync connections tend to dominate - synchronization time for relying parties. - - * The repository operator might also want to do some checks to assure - itself that what it's about to allow the RPKI engine to publish is - not dangerous toxic waste. - - The up-down protocol includes a mechanism by which a parent can suggest - a publication URI to each of its children. The children are not - required to accept this hint, and the children must make separate - arrangements with the repository operator (who might or might not be - the same as the entity that hosts the children's RPKI engine - operations) to use the suggested publication point, but if everything - works out, this allows children to nest cleanly under their parents - publication points, which helps reduce synchronization time for relying - parties. - - In this case, one could argue that the publication server is - responsible for preventing one of its clients (the child in the above - description) from stomping on data published by another of its clients - (the parent in the above description). This goes beyond the basic - access check and requires the publication server to determine whether - the parent has given its consent for the child to publish under the - parent. Since the RPKI certificate profile requires the child's - publication point to be indicated in an SIA extension in a certificate - issued by the parent to the child, the publication engine can infer - this permission from the parent's issuance of a certificate to the - child. Since, by definition, the parent also uses this publication - server, this is an easy check, as the publication server should already - have the parent's certificate available by the time it needs to check - the child's certificate. - - The previous paragraph only covers a "publish" action for a - <certificate/> object. For "publish" actions on other objects, the - publication server would need to trace permission back to the - certificate issued by the parent; for "withdraw" actions, the - publication server would have to perform the same checks it would - perform for a "publish" action, using the current published data before - withdrawing it. The latter in turn implies an ordering constraint on - "withdraw" actions in order to preserve the data necessary for these - access control decisions; as this may prove impractical, the - publication server may probably need to make periodic sweeps over its - published data looking for orphaned objects, but that's probably a good - idea anyway. - - Note that, in this publication model, any agreement that the repository - makes to publish the RPKI engine's output is conditional upon the - object to be published passing whatever access control checks the - publication server imposes. - __________________________________________________________________ - - - Generated on Thu Jun 12 02:43:52 2008 for RPKI Engine by doxygen - 1.5.5 diff --git a/docs/repository-engine-objects.dot b/docs/repository-engine-objects.dot deleted file mode 100644 index 24abc8dd..00000000 --- a/docs/repository-engine-objects.dot +++ /dev/null @@ -1,86 +0,0 @@ -// $URL$ -// $Id$ -// -// {arrowhead,arrowtail} shapes indicate database object relationships: -// 1- none -// m- crow -// -// Color code: -// Blue: visible in left-right protocol -// Green: created on the fly - -digraph rpki_engine_objects { - rotate=90; size="11,8.5"; splines=true; ratio=fill; - node [ shape=record ]; - - // Objects visible in left-to-right protocol - node [ color=blue ]; - self [ label="Self|{Preferences}" ]; - parent [ label="Parent|{URI|TA|SIA Base}" ]; - repo [ label="Repository|{URI|TA}" ]; - child [ label="Child|{TA}" ]; - biz_sign [ label="Business\nSigning Context|{Keypair|CertChain}" ]; - route_origin [ label="Route\nOrigin|{AS Number}" ]; - - // Objects which left-right protocol sees as part of other - // objects but which SQL needs to be separate for - // normalization. - - addr_set [ label="Address\nPrefix", color=purple ]; - - // Objects created on the fly by the RPKI engine - node [ color=green ]; - ca [ label="CA|{Last CRL #|Next CRL Date|Last Issued Serial #|Last Manifest #|Next Manifest Date|SIA URI}" ]; - ca_detail [ label="CA Detail|{CA Private Key Handle|CA Public Key|Latest CA Certificate|Manifest EE Private Key Handle|Manifest EE Public Key|Latest Manifest EE Certificate|Latest Manifest|Latest CRL}" ]; - - // Some question whether these objects need to be in database - // per se or are just properties hanging on some other object - // like ca or ca_detail. For manifests, we need last serial, - // same as for CRL. - roa [ label="ROA|{EE Certificate|ROA}" ]; - - // This one is a table of everything we have ever issued to - // this child, not to be confused with what's -currently- - // issued to this child. Some question whether this hangs off - // ca or ca_detail, but we -think- hanging off of ca_detail is - // correct because certificates are issued by a particular - // keypair. - - child_cert [ label="Child CA Certificate" ]; - - // One-many mappings - edge [ color=blue, arrowtail=none, arrowhead=crow ]; - self -> biz_sign; - biz_sign -> child; - biz_sign -> parent; - biz_sign -> repo; - self -> child; - self -> parent; - repo -> parent; - self -> route_origin; - - route_origin -> addr_set [ color=purple, arrowtail=none, arrowhead=crow ]; - - // This is many-many because each child is an entity, each CA - // can have multiple children, and each child can hold certs - // from multiple CAs (thanks, RobL). - // - ca -> child [ color=green, arrowtail=crow, arrowhead=crow ]; - - // One-many mappings - edge [ color=green, arrowtail=none, arrowhead=crow ]; - ca -> ca_detail; - child -> child_cert; - parent -> ca; - ca_detail -> child_cert; - ca_detail -> roa; - - // One-one mapping -- separate object to highlight dynamic nature - edge [ color=green, arrowtail=none, arrowhead=none, style=solid ]; - route_origin -> roa; - -} - -// Local Variables: -// compile-command: "dot -Tps2 repository-engine-objects.dot | ps2pdf - repository-engine-objects.pdf" -// End: diff --git a/docs/repository-engine-objects.pdf b/docs/repository-engine-objects.pdf Binary files differdeleted file mode 100644 index 68c6d2d6..00000000 --- a/docs/repository-engine-objects.pdf +++ /dev/null diff --git a/docs/repository-structure.txt b/docs/repository-structure.txt deleted file mode 100644 index 327663b7..00000000 --- a/docs/repository-structure.txt +++ /dev/null @@ -1,111 +0,0 @@ -$Id$ - -Copyright (C) 2007--2008 American Registry for Internet Numbers ("ARIN") - -Permission to use, copy, modify, and distribute this software for any -purpose with or without fee is hereby granted, provided that the above -copyright notice and this permission notice appear in all copies. - -THE SOFTWARE IS PROVIDED "AS IS" AND ARIN DISCLAIMS ALL WARRANTIES WITH -REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY -AND FITNESS. IN NO EVENT SHALL ARIN BE LIABLE FOR ANY SPECIAL, DIRECT, -INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM -LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE -OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR -PERFORMANCE OF THIS SOFTWARE. - - -This note is an attempt to write up the conclusions that several of us -came to at the RPKI meeting in Prague, March 2007. - -We currently have two examples of possible repository structure, -neither of which is quite what at least some of us think we want yet. - -APNIC's hierarchy of directories named by the g(SKI) function applied -to the public keys has some nice properties: in particular, the -hierarchical structure (subjects being stored underneath their issuers -when sharing a repository) has very nice scaling properties with -rsync. With this structure, a top-down walk such as rcynic uses will -pick up an entire tree as a side effect of fetching the top-most -issuer's SIA collection. Combined with a trivial memory cache to let -rcynic keep track of which URIs it has already fetched, this speeds up -rcynic's runtime by nearly two orders of magnitude in testing late -last year. The reason for this turns out to be simple: rsync is a -reasonably fast protocol, so one rsync connection to fetch an SIA -collection that hasn't changed takes approximately 500ms on not -terribly exciting hardware -- but in a system with more than 40,000 -objects, the cumulative total of all those half-second rsync -connections becomes significant. - -There is, however, one problem with the current APNIC structure: the -g(SKI) naming scheme means that the URIs associated with every -decendent of a particular node in the tree will change when that -node's key changes. This means that a key rollover event near the -root of the tree (eg, when APNIC's own key changes) will require a -painfully large number of certificates to be reissued. NB: only one -key is rolling in this scenario, the rest of the certificates are -being reissued with the same key, and the only reason why they need to -be reissued at all is that the path has changed. - -At the same time, the g(SKI) naming scheme has good properties for -naming certificates and CRLs, as it means that we can perform "make -before break" rollovers, leaving the old certificate path in place -until the new one is fully operational. - -So the goal here is to preserve the nice hierarchical structure of -APNIC's model, and preserve the nice properties of the g(SKI) naming -for certificates and CRLs, while avoiding the need to reissue every -desendent after a key rollover. We think that we can do this by using -static names for the directories and g(SKI)-based names for the files. - -This immediately begs the question of what the static names should be. -Some of us were tempted to make them organization names, but others of -us felt strongly that they should be completely meaningless, as they -only need to be unique within a particular parent directory and as we -really want to avoid all the "identity" issues that we have thus far -carefully avoided. We did not achieve consensus on this point, but I -(sra) am firmly in the meaningless name camp on this one. - -The upshot of all this is that I expect to be using URIs like: - - rsync://hostname/g0001/g0002/g0003/ - rsync://hostname/g0001/g0002/g0003/g(ski).cer - rsync://hostname/g0001/g0002/g0003/g(ski).crl - -where "gNNNN" indicates a generated symbol with no significance other -than that it is unique enough to avoid collisions. In this particular -case, the scope in which the symbol must be unique is just the -directory in which it appears. - -We haven't yet discussed how to name ROAs, but since we expect ROAs to -be tied to particular single-use EE certs, my guess is that a g(SKI) -name based on the key of the EE cert would be appropriate, so either -of the following forms would probably work: - - rsync://hostname/g0001/g0002/g0003/g0004/g(ski).roa - rsync://hostname/g0001/g0002/g0003/g(ski)/g(ski).roa - -The latter violates the rule of only using g(SKI) names for files, -never for directories, but in this case it'd probably be ok. - -This assumes that we're generating a new key for each ROA; if we're -reusing keys (dunno), we'd need a naming scheme like: - - rsync://hostname/g0001/g0002/g0003/g(ski)/g0004.roa - -For those unfamiliar with the notation (borrowed from Lisp): g0001 etc -are just "gensym" symbols, ie, the output of some function whose sole -purpose is to generate meaningless symbols. - -See images/repository-structure.pdf for an illustration of the problem -and solution. - -There may be compromise-driven rollover cases in which we will need to -reissue all of the children of a node whose key has been compromised. -Whether or not this is necessary depends on whether the master copy of -the authoritative data is safe somewhere else; if it is, and the -resource certificates are just a signed representation of an -authoritative database that has not been compromised, reissuing all of -the descendants may not be necessary, but if the resource certificates --are- the database, and one level in it has been compromised, it's -probably advisable to reissue all the descendants. diff --git a/docs/sample-irdb-data.sql b/docs/sample-irdb-data.sql deleted file mode 100644 index df24b48f..00000000 --- a/docs/sample-irdb-data.sql +++ /dev/null @@ -1,80 +0,0 @@ --- $Id$ - --- Copyright (C) 2007-2008 American Registry for Internet Numbers ("ARIN") --- --- Permission to use, copy, modify, and distribute this software for any --- purpose with or without fee is hereby granted, provided that the above --- copyright notice and this permission notice appear in all copies. --- --- THE SOFTWARE IS PROVIDED "AS IS" AND ARIN DISCLAIMS ALL WARRANTIES WITH --- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY --- AND FITNESS. IN NO EVENT SHALL ARIN BE LIABLE FOR ANY SPECIAL, DIRECT, --- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM --- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE --- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR --- PERFORMANCE OF THIS SOFTWARE. - -INSERT INTO registrant (IRBE_mapped_id) VALUES ('ARIN'); -INSERT INTO registrant (IRBE_mapped_id) VALUES ('TIER1_ISP1'); -INSERT INTO registrant (IRBE_mapped_id) VALUES ('TIER1_ISP2'); -INSERT INTO registrant (IRBE_mapped_id) VALUES ('JOES_PIZZA'); - -INSERT INTO resource_class (subject_name, valid_until, registrant_id) -SELECT 'All ARIN resources', '2099-12-31', registrant_id -FROM registrant WHERE IRBE_mapped_id = 'ARIN'; - -INSERT INTO resource_class (subject_name, valid_until, registrant_id) -SELECT 'Tier 1 ISP foo subject name', '2008-12-31', registrant_id -FROM registrant WHERE IRBE_mapped_id = 'TIER1_ISP1'; - -INSERT INTO resource_class (subject_name, valid_until, registrant_id) -SELECT 'Tier 1 ISP foo subject name', '2009-06-30', registrant_id -FROM registrant WHERE IRBE_mapped_id = 'TIER1_ISP1'; - -INSERT INTO resource_class (subject_name, valid_until, registrant_id) -SELECT 'Tier 1 ISP bar subject name', '2007-07-31', registrant_id -FROM registrant WHERE IRBE_mapped_id = 'TIER1_ISP2'; - -INSERT INTO resource_class (subject_name, valid_until, registrant_id) -SELECT 'arbitrary characters', '2007-12-31', registrant_id -FROM registrant WHERE IRBE_mapped_id = 'JOES_PIZZA'; - -INSERT INTO net (start_ip, end_ip, version, resource_class_id) -SELECT 'DEAD:BEEF:0000:0000:0000:0000:0000:0000', 'DFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF', 6, resource_class_id -FROM resource_class WHERE subject_name = 'All ARIN resources'; - -INSERT INTO net (start_ip, end_ip, version, resource_class_id) -SELECT 'DEAD:BEEF:FACE:0000:0000:0000:0000:0000', 'DEAD:BEEF:FACE:FFFF:FFFF:FFFF:FFFF:FFFF', 6, resource_class_id -FROM resource_class WHERE subject_name = 'TIER 1 ISP foo subject name' AND valid_until = '2009-06-30'; - -INSERT INTO net (start_ip, end_ip, version, resource_class_id) -SELECT 'DEAD:BEEF:FACE:FADE:0000:0000:0000:0000', 'DEAD:BEEF:FACE:FADE:FFFF:FFFF:FFFF:FFFF', 6, resource_class_id -FROM resource_class WHERE subject_name = 'arbitrary characters' AND valid_until = '2007-12-31'; - -INSERT INTO net(start_ip, end_ip, version, resource_class_id) -SELECT '010.000.000.000', '010.255.255.255', 4, resource_class_id -FROM resource_class WHERE subject_name = 'All ARIN resources'; - -INSERT INTO net(start_ip, end_ip, version, resource_class_id) -SELECT '010.128.000.000', '010.191.255.255', 4, resource_class_id -FROM resource_class WHERE subject_name = 'Tier 1 ISP foo subject name' AND valid_until = '2009-06-30'; - -INSERT INTO net(start_ip, end_ip, version, resource_class_id) -SELECT '010.000.000.000', '010.063.255.255', 4, resource_class_id -FROM resource_class WHERE subject_name = 'Tier 1 ISP foo subject name' AND valid_until = '2009-06-30'; - -INSERT INTO net(start_ip, end_ip, version, resource_class_id) -SELECT '010.128.000.000', '010.191.255.255', 4, resource_class_id -FROM resource_class WHERE subject_name = 'arbitrary characters'; - -INSERT INTO asn(start_as, end_as, resource_class_id) -SELECT 12345, 12345, resource_class_id -FROM resource_class WHERE subject_name = 'Tier 1 ISP foo subject name' AND valid_until = '2009-06-30'; - -INSERT INTO asn(start_as, end_as, resource_class_id) -SELECT 23456, 23457, resource_class_id -FROM resource_class WHERE subject_name = 'Tier 1 ISP foo subject name' AND valid_until = '2009-06-30'; - -INSERT INTO asn(start_as, end_as, resource_class_id) -SELECT 34567, 34567, resource_class_id -FROM resource_class WHERE subject_name = 'Tier 1 ISP foo subject name' AND valid_until = '2008-12-31'; diff --git a/docs/signed-manifests b/docs/signed-manifests deleted file mode 100644 index d1bd3f5e..00000000 --- a/docs/signed-manifests +++ /dev/null @@ -1,74 +0,0 @@ --- $Id$ - --- Copyright (C) 2007-2008 American Registry for Internet Numbers ("ARIN") --- --- Permission to use, copy, modify, and distribute this software for any --- purpose with or without fee is hereby granted, provided that the above --- copyright notice and this permission notice appear in all copies. --- --- THE SOFTWARE IS PROVIDED "AS IS" AND ARIN DISCLAIMS ALL WARRANTIES WITH --- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY --- AND FITNESS. IN NO EVENT SHALL ARIN BE LIABLE FOR ANY SPECIAL, DIRECT, --- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM --- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE --- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR --- PERFORMANCE OF THIS SOFTWARE. - --- Signed manifests for RPKI repositories. Relying parties use object --- (as opposed to channel) security for everything in this design --- repository, which is the right thing to do for various reasons but --- leaves us open to attacks which intercept the rsync connection and --- drop valid objects out of an SIA collection. At present this is --- not detectable, so we need a mechanism. --- --- Manifests as described here are modeled on CRLs, because the issues --- involved in detecting stale manifests, manifest replays, etc are --- similar to those for CRLs. So we want many of the fields that a --- CRL has. Syntax differs, though, since RPKI repositories can --- contain objects not covered by CRLs (eg, ROAs), and reuse CMS as --- the manifest signature format rather than inventing another one. --- --- See RFC 3280 section 5 for CRL layout and extensions. --- --- We're only trying to cover objects in the same SIA collection --- (directory) as the manifest. We will probably want to name the --- manifest itself with a name derived from the g(ski) of the cert of --- which this is the SIA collection. We'll need an EE cert to sign --- the manifest; the EE cert should probably just use RFC 3779 --- inheritance to cover all the resources that its issuer holds. If we --- use CMS, we might just want to include the EE cert in the CMS --- bag of certs. --- --- Lisp pseudo-code version of my original proposal for what goes --- inside the CMS wrapper: --- --- (manifest :version 1 --- :collection-uri "rsync://foo.example/wombat/" --- :this-update timestamp --- :next-update timestamp --- :manifest-serial 17 --- :hash-algorithm :sha256 --- (:name foo.cer :hash aabbccdd...) --- (:name bar.cer :hash bbccddee...) --- (:name foo.roa :hash ccddeeff...) --- (:name baz.crl :hash ddeeff00...) --- ...) --- --- Steve Kent came up with something very similar in ASN.1. At this --- point I think that Steve and I have converged, so here is Steve's --- ASN.1, which, absent new issues, I expect to implement with --- OpenSSL's ASN.1 engine. - -Manifest ::= SEQUENCE { - version [0] INTEGER DEFAULT 0, -- first version is 0 - manifestNumber INTEGER, -- to identify unscheduled manifest issuance - thisUpdate GeneralizedTime, -- this manifest issuance time - nextUpdate GeneralizedTime, -- next scheduled manifest issuance time - fileHashAlg OBJECT IDENTIFIER, -- algorithm used to generate file content hash values - fileList SEQUENCE OF FileAndHash -- list of file name and content hash pairs -} - -FileAndHash ::= SEQUENCE { - file IA5String -- file name - hash BIT STRING -- hash of file content -} diff --git a/docs/up-down-protocol b/docs/up-down-protocol deleted file mode 100644 index 4e4aa86c..00000000 --- a/docs/up-down-protocol +++ /dev/null @@ -1,8 +0,0 @@ -$Id$ - -The master copy of the up-down protocol currently lives in a wiki at -APNIC. A flat text mirror of this document can be found at: - -http://subvert-rpki.hactrn.net/wiki-mirror/text/mirin.apnic.net/resourcecerts/wiki/index.php/IR-ISP_Definition - -(ie, ../wiki-mirror/text/mirin.apnic.net/resourcecerts/wiki/index.php/IR-ISP_Definition within this repository). |
