From 146b8620c28a3260bdb20c91b4326e5afbf70dd0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jordi=20Subir=C3=A0=20Nieto?= Date: Tue, 16 Nov 2021 14:27:43 +0100 Subject: [PATCH] doc: DRkey documentation This PR contains the updated documentation for DRKey based on the discussion #4039. [doc] Closes #4102 GitOrigin-RevId: 18d2a8d7beb87b0ace36ade0424d830ff265dd01 --- doc/cryptography/DRKeyInfra.md | 544 --------------------------------- doc/cryptography/drkey.rst | 416 +++++++++++++++++++++++++ doc/cryptography/index.rst | 2 +- 3 files changed, 417 insertions(+), 545 deletions(-) delete mode 100644 doc/cryptography/DRKeyInfra.md create mode 100644 doc/cryptography/drkey.rst diff --git a/doc/cryptography/DRKeyInfra.md b/doc/cryptography/DRKeyInfra.md deleted file mode 100644 index b585b410f1..0000000000 --- a/doc/cryptography/DRKeyInfra.md +++ /dev/null @@ -1,544 +0,0 @@ -# Dynamically Recreatable Key (DRKey) Infrastructure - -This document presents the design for the Dynamically Recreatable Key (DRKey) -infrastructure. - -- Author: Benjamin Rothenberger -- Last updated: 2019-05-02 -- Status: draft - -## Overview - -The DRKey protocol enables routers and end hosts to derive symmetric -cryptographic keys on-the-fly from a single local secret. - -DRKey is used for the following systems: - -- SCMP -- SIBRA / COLIBRI -- Security Extension -- PISKES -- OPT -- EPIC - -## Notation - -```spec -| bitstring concatenation -^ superscript -_ subscript - -PRF_K (X) pseudorandom function using key K and taking X as an input -{X}_PK_A public key encryption using public key of AS A -{X}_PK_A^-1 public key signing using private key of AS A - -A autonomous system -H_A end host identified by their IP address -CS_A certificate server located in AS A - -SV_A AS A's local secret value -K_{A→B} symmetric key between AS A and AS B with direct key derivation for AS A -K_{A:H_A→B:H_B}^{p} symmetric key between host H_A in AS A and host H_B in AS B for protocol 'p' -DS_{A→B}^{p} delegation secret between AS A and AS B for protocol 'p' -``` - -Note that the arrow notation does *not* refer to the directionality of the key, but -rather states for which entity the key derivation must be efficient. For example, -`K_{A→B:H_B}` can be used in both direction of communication, but is directly -derivable by AS A, whereas host `H_B` might be required to fetch a key from its -local CS. - -## Design - -In the DRKey protocol, key establishment is offloaded to the certificate server -(CS). Each certificate server selects a local secret value, which is only shared -with trustworthy entities in the same AS; it is never shared outside the AS. The -secret value will serve as the root of a symmetric key hierarchy, where keys of -a level are derived from keys of the preceding level using an efficient -Pseudo-Random Function (PRF). Thanks to the one-way property of the PRF, the -derived key can be shared with another entity without disclosing the higher level -symmetric key. This system ensures rapid key derivation on the service side, -whereas a slower key fetch is required by a client to a local certificate server. - -### Key Hierarchy - -```spec - SV_A (0th level) - | - +------+-----.... - | - K_{A→B} (1st level) - | - +----------------+-------------------+---... - | | | -K_{A→B}^{p} K_{A→B:H_B}^{p} K_{A:H_A→B:H_B}^{p} (2nd level) -``` - -#### 0th Level - -On the zeroth level of the hierarchy, each AS A randomly generates a local and -AS-specific secret value SV\_A. The secret value represents the per-AS basis of -the hierarchy and is renewed frequently. This is not shared with any entity outside -the AS. - -#### 1st Level - -Given the AS-specific secret value, an AS can derive pairwise symmetric keys -destined for other ASes from this secret value. These derived keys form the -first level of the key hierarchy and are called first-level keys. For example, a -first-level key that is used between AS A and AS B, is derived as follows: - -```spec -K_{A→B} = PRF_{SV_A} (B) -``` - -where SV\_A is the AS-specific secret value from the zeroth level of the key -hierarchy. - -#### 2nd Level - -Using the symmetric keys of the first level of the hierarchy, second-level keys -are derived to provide symmetric keys to hosts within the same AS. Second-level -keys can be established between a pair of AS infrastructure nodes (such as -border routers or servers), end hosts or a combination of both. For example, a -key between end hosts H\_A in AS A and H\_B in AS B is derived as follows: - -```spec -K_{A:H_A→B:H_B}^{prot} = PRF_K_{A→B} (“prot” | H_A | H_B) -``` - -where “prot” denotes an arbitrary protocol, and H\_A and H\_B represent host -addresses. We distinguish between IPv4, IPv6 and service addresses. - -### Key Validity - -#### Epochs - -An epoch is an interval between a starting and end point in time. The length of -epochs can be chosen by a given AS and can change over time. However, epochs -must not overlap. Thus, a secret value is associated with exactly one epoch. - -#### Validity Periods - -Secret values must be renewed for every epoch. Thus, also lower level keys -must be renewed at the beginning of a new epoch. However, if the key used to -authenticate a packet expires while the packet is in transit, the packet could no -longer be verified by the receiver. To avoid race conditions, the validity of -second-level keys exceeds the epoch end time by a small extent. By default, we -assume a epoch length of 24 hours and the following key validity periods: - -- Secret value: 24 hours -- First-level keys: 24 hours (inherited) + maximum offset (see Key Rollover) -- Second-level keys: 24 (inherited) + maximum offset (see Key Rollover) + 0.1 hours - -First- and second-level keys are valid during the same time frame as the -corresponding secret value. If a specific protocol requires shorter key expiration -times, this will be implemented as an extension to the basic protocol. The 'misc' -part in the key exchange is used to supply such additional information. - -![Validity Periods figure](fig/validity_period.png) - -### Key Establishment - -#### First-Level Key Exchange - -To exchange a first-level key the certificate servers of corresponding ASes -perform the key exchange protocol. The key exchange is initialized by CS\_B by -sending the following request: - -```spec -token = A | val_time | timestamp -CS_B → CS_A : A | B | token | {token}_PK_B^−1 -``` - -where `val_time` specifies a point in time at which the requested key is valid. -The requested key may not be valid at the time of request, either because it -already expired or because it will become valid in the future. For example, -prefetching future keys allows for seamless transition to the new key. Thus, -`val_time` is used to identify the epoch in which the requested key can be used. -In case `val_time` is close to the end of the current epoch, the CS will also -include the key for the next epoch. - -To sign and encrypt the first level key exchange, AS-level certificate -distributed using the SCION control-plane PKI are used. The request token is -signed with B’s private key to prove authenticity of the request. Upon receiving -the initial request, CS\_A checks the signature and timestamp for authenticity -and expiration. If the request has not yet expired, the certificate server -CS\_A will reply with an encrypted and signed first-level key derived from the -local secret value SV\_A. SV\_A is chosen according to the epoch identified by -`val_time`. - -```spec -K_{A→B} = PRF_{SV_A} (B) -ciphertext = {A | B | K_{A→B}}_PK_B -signature = {ciphertext | epoch_begin | epoch_end | timestamp}_PK_A^−1 -CS_A → CS_B : ciphertext | epoch_begin | epoch_end | timestamp | signature -``` - -Once the requesting certificate server CS\_B has received the key, it shares it -among other local certificate servers to ensure a consistent view. Each -certificate server can now respond to queries by entities within the same AS -requesting second-level keys derived from K_{A→B}. - -The first-level key is accompanied by `epoch_begin` and `epoch_end` that denote -the begin and end of the validity period of the corresponding key. These values -are determined by the AS that issues the key. The beginning of an epoch must -not overlap with the end of the previous epoch, as otherwise multiple -DRKeys need to be checked for verification. Additionally, a packet that is -authenticated using DRKey should contain a timestamp to avoid clock drift -issues. - -First-level keys of frequently contacted ASes are prefetched such that -second-level keys can be instantaneously derived. In case a certificate server -is missing a first-level key that is required for the derivation of a -second-level key, the certificate server initiates a first-level key exchange. -The amount of cached first-level keys is configurable by each AS. We suggest a -default policy of caching 10'000 first-level keys, where the least frequently -used keys get replaced. This requires fetching on average one first-level key -every 8 seconds (assuming a key lifetime of 24h). - -Note that *only one AS* is required to perform a first-level key exchange to -fetch a symmetric first-level key. For example, to obtain `K_{A→B}`, only AS B -is required to obtain the first-level key. AS A can directly derive the key -from SV\_A. - -#### Second-Level Key Exchange - -End hosts request a second-level key from their local certificate server with -the following request format: - -```spec -{keyType, requestID, protocol, srcIA, dstIA, srcHost, dstHost, misc} -``` - -`keyType` defines which type of second-level key is requested. Currently, -there exist three types of second-level keys: AS-to-AS, AS-to-end-host, and -end-host-to-end-host. `misc` is used to supply additional information that -might be required for protocol-specific keys (e.g., shorter key lifetime). - -An end host H\_A in AS A uses this format for issuing the following request to -its local certificate server CS\_A: - -```spec -H_A → CS_A : format | val_time | timestamp -``` - -Similar to the first-level key exchange, 'val\_time' specifies a point in time at -which the requested key is valid. -The certificate server only replies with a key to requests with a valid -timestamp, and if the querying host is authorized to use the key at the specified -point in time. An authorized host must either be an end point of the communication -that is authenticated using the second-level key, or authorized separately by the -AS. The following second-level requests exist: - -```spec -1. AS → AS: -Request: { 0, req.ID, prot, A, B, ⊥, ⊥, ⊥ } - -2. AS → end host -Request: { 1, req.ID, prot, A, B, ⊥, H_B, ⊥ } - -3. end host → end host: -Request: { 2, req.ID, prot, A, B, H_A , H_B, ⊥ } -``` - -### Second-Level Key Derivation - -The key derivation for second-level keys can be defined by each protocol. By -default, the DRKey infrastructure offers two key derivation procedures. For -these, we distinguish between protocols that perform key derivations only on -trusted AS infrastructure (e.g., SCMP), and protocols that can profit from -"outsourcing" key derivation to AS-owned infrastructure entities (e.g., PISKES). -In the former case, key derivation can be performed as follows: - -```spec -1. AS → AS: -Key Derivation: K_{A→B}^prot = PRF_{K_{A→B}}( “prot” ) - -2. AS → end host -Key Derivation: K_{A→B:H_B}^prot = PRF_{K_{A→B}} ( “prot” | H_B ) - -3. end host → end host: -Key Derivation: K_{A:H_A→B:H_B}^prot = PRF_{K_{A→B}} ( “prot” | H_A | H_B ) -``` - -In the latter case, where key derivation should be performed by AS-owned -entities, we introduce an intermediate step: - -```spec -SV_A - | -K_{A→B} - | -DS_{A→B}^{prot} - | -K_{A:H_A→B:H_B}^{prot} -``` - -The delegation secret `DS_{A→B}^{prot}` can be shared with services to enable -them to locally derive second-level keys in a single derivation step. On the -client-side, the CS is required to perform an additional derivation step to -get a second-level key. This is particularly useful for AS-controlled services -that require authentication of the first packet. The secret of the intermediate -step is derived as follows: - -```spec -DS_{A→B}^{prot} = PRF_{K_{A→B}} ( “prot” ) -``` - -Consequently, the second-level key derivation is adapted: - -```spec -1. AS → AS: -Key Derivation: K_{A→B}^prot = DS_{A→B}^{prot} (no derivation required) - -2. AS → end host -Key Derivation: K_{A→B:H_B}^prot = PRF_{DS_{A→B}^{prot}} ( H_B ) - -3. end host → end host: -Key Derivation: K_{A:H_A→B:H_B}^prot = PRF_{DS_{A→B}^{prot}} ( H_A | H_B ) -``` - -Other protocols could also introduce other procedures to derive second-level -keys. However, the CSes of both participating ASes must be upgraded to support -the additional derivation mechanism. - -### Key Rollover - -Shared symmetric keys are short-lived to avoid explicit key revocation. However, -letting all keys expire at the same time would lead to peaks in key requests. -Such peaks can be avoided by spreading out key expiration, which in turn will -lead to spreading out the fetching requests. To this end, we introduce the -following deterministic mapping: - -```spec -offset : (A, B) → [0, t) -``` - -that uniformly maps the AS identifiers of the source in AS A and the destination -in AS B to a range between 0 and the maximum lifetime t of SV\_A. The offset is -used to determine the validity period of a key by determining the secret value -SV\_A^j that is used to derive K_{A→B} at the current sequence j such that: - -```spec -[ start(SV_A^j) + offset(A, B), start(SV_A^j+1) + offset(A, B) ) -``` - -![Offset figure](fig/offset.png) - -The offset function is AS-specific. By default, we suggest to use a function -that uniformly distributes the offset values in the following interval: - -```spec -[0, minimum epoch length / 2 ) -``` - -For prefetching of DRKeys, a `valTime` that exceeds the end of the current epoch -can be selected. To allow seamless key rollover, an entity is required to store -secret values of the current, previous, and next epoch. In case a key for a -different epoch is requested, an AS is not required to return a corresponding -key. - -## Implementation - -The implementation of the protocol will consist of the first-level key exchange -between CS. The second-level key exchange is implemented between sciond and CS. -Additionally, a key store needs to be implemented to cache keys. - -### Key Derivation - -As a key derivation function we will use AES-CMAC as a single block operation, -which can be performed in less than 100 cycles on a modern CPU. The input to -the key derivation function looks as follows: - -#### 0th Level - -As secret values are directly derived from an AS-specific secret, we need to use -a secure password-based key derivation function. We use `PBKDF2` with at least -1000 iterations of `Sha256`. - -Data input: - -```spec -secLen uint8 -secret []byte -date []byte -``` - -#### 1st Level - -Key input: - -```spec -SV_A []byte -``` - -Data input: - -```spec -DstIA uint64 -``` - -#### 2nd Level (Default) - -Key input: - -```spec -K_{A→B} []byte -``` - -Data input: - -```spec -1. AS → AS: -ProtoLen uint8 -Protocol []byte -KeyType uint8 - -2. AS → end host: -ProtoLen uint8 -Protocol []byte -KeyType uint8 -DstHostLen uint8 -DstHost []byte - -3. end host → end host: -ProtoLen uint8 -Protocol []byte -KeyType uint8 -SrcHostLen uint8 -DstHostLen uint8 -SrcHost []byte -DstHost []byte -``` - -The input size of the PRF depends on the address type that is used to -address end hosts. - -#### 2nd Level (with Intermediate Step) - -Key input: - -```spec -DS_{A→B}^{p} []byte -``` - -Data input: - -```spec -1. AS → AS: -KeyType uint8 - -2. AS → end host: -KeyType uint8 -DstHostLen uint8 -DstHost []byte - -3. end host → end host: -KeyType uint8 -SrcHostLen uint8 -DstHostLen uint8 -SrcHost []byte -DstHost []byte -``` - -### Key Exchange - -#### First Level - -For the first-level key exchange between CS, we can use SignedCtrlPld. Thus, -the request ID, timestamp, signature, certificate and TRC version do not need -to be part of the protocol. For the response, certVerDst describes the version -of the certificate used to encrypt the message. Furthermore, all time-specific -data such as timestamps, validity time, or expiration time are specified as -the time in seconds since the unix epoch. - -```spec -DRKeyLvl1Req { - isdas UInt64 # Src ISD-AS of the requested DRKey - valTime UInt32 # Point in time where requested DRKey must be valid. - # Used to identify the epoch. -} - -DRKeyLvl1Rep { - isdas UInt64 # Src ISD-AS of the DRKey - epochBegin UInt32 # Begin of validity period of DRKey - epochEnd UInt32 # End of validity period of DRKey - cipher Data # Encrypted DRKey - certVerDst UInt64 # Version of cert of public key used to encrypt -} -``` - -#### Second Level - -The second level key response will also be transmitted with SignedCtrlPld. - -```spec -DRKeyLvl2Req { - valTime UInt32 # Point in time where requested DRKey must be valid. - # Used to identify the epoch. - protocol Data # Protocol identifier - keyType UInt8 # Key type of requested DRKey - srcIA UInt64 # Src ISD-AS of the requested DRKey - dstIA UInt64 # Dst ISD-AS of the requested DRKey - srcHost Data # Src Host of the request DRKey (optional) - dstHost Data # Dst Host of the request DRKey (optional) - misc Data # Additional information for DRKey derivation (optional) -} - -DRKeyLvl2Rep { - timestamp UInt32 # Timestamp - drkey Data # Derived DRKey - epochBegin UInt32 # Begin of validity period of DRKey - epochEnd UInt32 # End of validity period of DRKey - misc Data # Additional information (optional) -} -``` - -### Key Store - -As a key store, we will use sqlite. It is already used in sciond and CS to cache -certificates and TRCs. - -The key store also stores the begin and end of an epoch for an individual key. - -### Offset Function - -The offset function to spread out key expiration is implemented as follows: - -```spec -hash(srcAS | dstAS) % mod (min epoch length / 2) -``` - -As a hash function, we will use the non-cryptographic hash function -`MurmurHash3`. It provides a good distribution, while being faster than an -unkeyed cryptographic hash function. However, as this function is local to an AS, -it can be replaced to receive a different key expiration spread. Remote ASes don't -need to be aware of the offset function that is used, as the key lifetime is -included in the exchange. - -## DRKey Use Cases - -Key selection in DRKey is based on which entity requires fast key derivation -(without querying the required key at the certificate server). In the following, -we discuss an example usages of DRKey where key derivation is performed on border -routers (BR). - -### Key Derivation by AS Infrastructure - -In the case where key derivation is performed by BRs (e.g., SCMP), the BR must be -able to directly derive the key without requiring to fetch an additional key. - -For example, a host in AS A sends a data packet to a host in AS C, but forwarding -fails (e.g., due to an expired hop field) at the ingress interface of AS B’s border -router `BR_B`. The router creates an SCMP message, which describes the problem. When -the packet is created, then `BR_B` derives a key for authenticating packets destined -for the source based on the key shared with AS A and calculates a MAC over the -packet. Theoretically either `K_{B→A:Source}` or `K_{A:Source→B}` could be used to -authenticate the packet. However, as AS B shares its secret value `SV_B` with -`BR_B`, `BR_B` can directly derive all first- and second-level keys `K_{B→*}`. Thus, -`K_{B→A:Source}` must be used for authenticating the SCMP message. On the source -side, the host either has the same key already cached, or it contacts its CS and -queries the missing key. - -![Offset figure](fig/scmp_auth.png) diff --git a/doc/cryptography/drkey.rst b/doc/cryptography/drkey.rst new file mode 100644 index 0000000000..7b148cfca3 --- /dev/null +++ b/doc/cryptography/drkey.rst @@ -0,0 +1,416 @@ +************************************************** +Dynamically Recreatable Key (DRKey) Infrastructure +************************************************** + +This document presents the design for the Dynamically Recreatable Key (DRKey) +infrastructure. + +Overview +======== +The DRKey protocol enables routers and end hosts to derive cryptographic +symmetric keys on the fly from a single local secret. + +DRKey is used for the following systems: + +- SCION Packet Authenticator Option (SPAO) +- COLIBRI +- EPIC + +In the DRKey system, the key establishment is offloaded to the Control Service +(CS). +Control services exchange top-level keys that will be used afterwards +to derive lower level keys locally. +The DRKey system leverages efficient key derivation and pseudorandom functions +to derive keys in the hierarchy from top to bottom. + +The first secret in the hierarchy (:math:`SV_A`) is derived from a long-term ``master_secret``, +using a key derivation function. +For the rest of the derivations, DRKey utilizes pseudorandom functions, which are more efficient. +Informally, key derivation functions output a cryptographic key indistingushible from +a random key if the secret is unknown for the attacker. +In contrast, the security of pseudorandom functions relies on the input being a uniformly +random secret. + +Notation +======== + +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - Notation + - Description + * - :math:`KDF_{K}(X)` + - key derivation function using key K and taking X as an input + * - :math:`PRF_K (X)` + - pseudorandom function using key K and taking X as an input + * - :math:`A` + - Autonomous system (identified by the pair ISD and AS number) + * - :math:`H_A` + - end host (identified by its address) + * - :math:`CS_A` + - Control service located in AS A + * - :math:`SV_A` + - AS A's local secret value + + +Derivation scheme +================= + +We define two types of derivation: the :ref:`drkey-specific-derivation` derivation and +the :ref:`drkey-generic-derivation`. Both of them leverage the 4-level derivation scheme. + +4-level derivation +------------------ + +**Secret value (Level 0)** + +Each AS locally derives one :math:`SV_A^{protocol}` per protocol and epoch. This secret value +is renewed at every epoch and it is only shared with trustworthy entities that require +to derive keys on the fly for the specified protocol. + +**AS-AS (Level 1)** + +The ``AS-AS`` key is derived locally in the AS :math:`A` CS (:math:`CS_A`) and exchanged +with remote CS. More specifically :math:`CS_A` shares :math:`K_{A,B}` with +:math:`CS_B`. + +**host-AS (Level 2)** + +The ``host-AS`` key is derived using the Level 1 symmetric key. +It is intended to be used as an intermediate derivation allowing the node holding this +key to derive Level 3 keys locally. +Therefore, the key :math:`K_{A:H_A,B}` is only available to :math:`A:H_A` and trusted +infrastructure. + +**AS-host (Level 2)** + +The ``AS-host`` key is also derived using the Level 1 symmetric key, +however this key is intended to be used for communication. +In this case, the key :math:`K_{A,B:H_B}` is shared between :math:`AS_A` trusted nodes +and :math:`B:H_B`. + +**host-host (Level 3)** + +The ``host-host`` key is derived in :math:`H_A` and :math:`CS_B` using the ``host-AS`` key. This key +is available to both hosts :math:`H_A` and :math:`H_B`. + +.. _drkey-specific-derivation: + +Protocol-specific derivation +---------------------------- + +.. list-table:: + :widths: 50 100 50 + :header-rows: 1 + + * - Identifier + - Derivation + - Name + * - :math:`SV_A^{protocol}` + - :math:`KDF(input)` + - Secret value (Level 0) + * - :math:`K_{A,B}^{protocol}` + - :math:`PRF_{SV_A^{protocol}}(type||B)` + - AS-AS key (Level 1) + * - :math:`K_{A,B:H_B}^{protocol}` + - :math:`PRF_{K_{A,B}^{protocol}}(type||len/type(H_B)||H_B)` + - AS-host key (Level 2) + * - :math:`K_{A:H_A,B}^{protocol}` + - :math:`PRF_{K_{A,B}^{protocol}}(type||len/type(H_A)||H_A)` + - host-AS key (Level 2) + * - :math:`K_{A:H_A,B:H_B}^{protocol}` + - :math:`PRF_{K_{A:H_A,B}^{protocol}}(type||len/type(H_B)||H_B)` + - host-host key (Level 3) + +The SV computation is local, thus the AS is free to compute it as desired as long as +it outputs a cryptographic key indistingushible from a random key for an attacker. +We suggest to use the *PBKDF2* as KDF function and set ``input`` to: +``input = "len(master_secret) || master_secret || protocol || epoch_begin || epoch_end"``. + +The key notation states for which entity the key derivation must be efficient. +The term in the left identifies the key *issuer* (the fast side in the derivation), +whereas the right term identifies the key *subject* (the slow side in the derivation). +For example, :math:`K_{A,B:H_B}` can be used in both communication directions, +but it is directly derivable by :math:`AS_A`, whereas the :math:`AS_B` requires to contact +:math:`CS_A` to fetch the intermediate Level 1 key. + +.. _drkey-generic-derivation: + +Generic-protocol derivation +--------------------------- + +.. list-table:: + :widths: 50 50 50 + :header-rows: 1 + + * - Identifier + - Derivation + - Name + * - :math:`SV_A` + - :math:`KDF(input)` + - Secret value (Level 0) + * - :math:`K_{A,B}` + - :math:`PRF_{SV_A}(type||B)` + - AS-AS key (Level 1) + * - :math:`K_{A,B:H_B}^{protocol}` + - :math:`PRF_{K_{A,B}}(type||protocol||len/type(H_B)||H_B)` + - AS-host key (Level 2) + * - :math:`K_{A:H_A,B}^{protocol}` + - :math:`PRF_{K_{A,B}}(type||protocol||len/type(H_A)||H_A)` + - host-AS key (Level 2) + * - :math:`K_{A:H_A,B:H_B}^{protocol}` + - :math:`PRF_{K_{A:H_A,B}^{protocol}}(type||len/type(H_B)||H_B)` + - host-host key (Level 3) + +This derivation scheme allows applications to define "niche" protocols. By including +the protocol in the Level 2 derivation input. + +PRF derivation specification +---------------------------- + +type + 1 byte field identifying the derivation type (``AS-AS``, ``AS-host``, + ``host-AS`` and ``host-host``). This enables domain separation among computed + keys. For instance, it outputs (with high probability) + :math:`K_{A:H_A,B} ≠ K_{A,B:H_B}` when :math:`H_A==H_B`. + +protocol + 2 byte field used in the PRF derivation for Lvl2 generic-protocol derivations + to identify the concrete protocol. + +ISD-AS address + This field is present in Lvl1 derivations and follows the format in + :ref:`SCION Address Header `. + +host length/type + This field is present in Lvl2/3 derivations and follows the format for the DT/DL + field in :ref:`SCION Common Header `. + +host address + This field is present in Lvl2/3 derivations and follows the format in + :ref:`SCION Address Header `. + + +DRKey uses AES-CBC MAC as PRF. The MAC is computed over the following fields: + +* **type** (1 byte) +* **protocol** in Lvl2 generic-protocol derivations (2 bytes) +* **ISD-AS address** in Lvl1 derivations (8 bytes) +* **Host type/length** in Lvl2/3 derivations (4-bit, padded to 1 byte) +* **Host address** in Lvl2/3 derivations (variable size). + +The derivation using CBC MAC is safe since all fields are of a fixed size, +except for the host address whose length is prepended. + +Key Validity time +================= + +Epochs +------ +An epoch is an interval between a starting and ending point in time. The epoch +length can be chosen by a given AS and can change over time, however, epochs +must not overlap. Thus, a secret value is associated with exactly one epoch. + +Every AS can define different epoch lengths for each protocol-specific +0th level key. + +Defining a reasonable lower bound for the epoch length used in DRKey +is necessary to avoid nonsensical scenarios. This value is +globally set to 6 minutes. + +.. note:: + + This lower bound might be changed in the future in case a more suitable + value is found. + +Grace period +------------ +We define a short overlapping period in which the protocol accepts packets with the key +for the previous epoch *i-1* and also for the current one *i*. This period should be +ideally as short as possible, although long enough to allow using the same key for +single packet request/response use cases (e.g. a few seconds). Thus, we set +``GRACE_PERIOD = 5 seconds``. + +.. _drkey-prefetching: + +Prefetching period +------------------ +ASes will be allowed to prefetch keys some time before the key for the current epoch expires. +This period must be long enough to allow every remote AS to attempt the key prefetching +enough times to be succesful even in the presence of failures. However, this period +should not be too long, since the issuer AS is not assumed to carry out any changes +once it has issued keys for a given epoch (e.g. modifying SV epoch duration, +rotating the master secret, etc.). + +We suggest globally setting ``PREFETCHING_PERIOD = 30 minutes``. + +.. note:: + + Whether ASes are allowed to request/serve keys for past epochs is up for discussion. + +Key establishment +================= + +Level 1 key establishment +------------------------- + +The Level 1 key establishment occurs between CSes located in different ASes. +The subject-AS on the slow side (i.e. the AS requesting the key) will establish a TLS secure connection with +the issuer-AS on the fast side (i.e. the AS serving the key). Both parties identify each other by using +the CP-PKI infrastructure. + +The Level 1 key request message contains the ``validTime`` for which the key must be active +and the ``protocol_id``. The Level 1 key response includes the symmetric key along with the epoch +for which this key will be valid. + +The ``protocol_id`` is either set to ``GENERIC = 0`` to request Lvl1 keys that will be derived according to +the `generic-protocol` hierarchy or to the protocol number for the `protocol-specific` derivation. + +Level 0/2/3 key establishment +----------------------------- + +Even though Level 0/2/3 key exchange happens within the same AS (i.e. intra-AS communication), +the protocol should establish a secure channel. +This would avoid that hosts in the AS can eavesdrop on symmetric keys that are not +intended for them. + +The CS will only respond to the specific request if the requesting host +is authorized to receive the requested key. +This is especially important in the Level 0 key case since only trustworthy nodes should +be authorized to receive this key. + +The Level 0 key request contains the ``validTime`` and the specific ``protocol_id``. +The CS responds with the SV and the epoch for which this key will be valid. + +The Level 2/3 key request includes the ``validTime`` and the necessary host and AS +information (depending on the key type). +The server responds with the symmetric key and the epoch. + +The ``protocol_id`` in Lvl2/3 requests is always set to the final protocol identifier. +The key service will choose between the `protocol-specific` derivation, if it exists, or +the `generic-protocol` derivation, otherwise. + +Spreading Level 1 key requests +============================== + +Shared symmetric keys are short-lived to avoid explicit key revocation. In order +to avoid peaks in the requests for Level 1 keys derived from a given SV, every requesting +CS (i.e. the CS on the slow side) SHOULD wait a random time before trying to prefetch +the Level 1 key. This time ``t`` is u.r.d. in the interval [0, 15] minutes. + +In this manner, the CS on the slow side SHOULD NOT request a Level 1 key before +``epoch_end - (PREFETCHING_PERIOD - t)`` instant in time (the ``PREFETCHING_PERIOD`` +is defined in :ref:`drkey-prefetching`). + +Key exchange message format +=========================== + +.. code-block:: text + + enum Protocol { + GENERIC = 0; + SCMP = 1; + ... + reserved 65536 to max; // only 16-bit values allowed + } + + message SVRequest{ + // Point in time when the requested key is valid. + Timestamp val_time = 1; + // Protocol value. + Protocol protocol_id = 2; + } + + message SVResponse{ + // Begin of the SV validity period. + Timestamp epoch_begin = 1; + // End of the SV validity period. + Timestamp epoch_end = 2; + // SV key. + bytes key = 3; + } + + message Lvl1Request{ + // Point in time when the requested key is valid. + Timestamp val_time = 1; + // Protocol value. + Protocol protocol_id = 2; + } + + message Lvl1Response{ + // Begin of validity period. + Timestamp epoch_begin = 1; + // End of validity period. + Timestamp epoch_end = 2; + // Lvl1 key. + bytes key = 3; + } + + message HostASRequest{ + // Point in time where requested key is valid. + Timestamp val_time = 1; + // Protocol value. + Protocol protocol_id = 2; + // Src ISD-AS of the requested DRKey. + uint64 src_ia = 3; + // Dst ISD-AS of the requested DRKey. + uint64 dst_ia = 4; + // Src Host of the request DRKey. + string src_host = 5; + } + + message HostASResponse{ + // Begin of validity period of DRKey. + Timestamp epoch_begin = 1; + // End of validity period of DRKey. + Timestamp epoch_end = 2; + // Lvl2 key. + bytes key = 3; + } + + message ASHostRequest{ + // Point in time where requested key is valid. + Timestamp val_time = 1; + // Protocol value. + Protocol protocol_id = 2; + // Src ISD-AS of the requested DRKey. + uint64 src_ia = 3; + // Dst ISD-AS of the requested DRKey. + uint64 dst_ia = 4; + // Dst Host of the request DRKey. + string dst_host = 5; + } + + message ASHostResponse{ + // Begin of validity period of DRKey. + Timestamp epoch_begin = 1; + // End of validity period of DRKey. + Timestamp epoch_end = 2; + // Lvl2 key. + bytes key = 3; + } + + message HostHostRequest{ + // Point in time where requested key is valid. + Timestamp val_time = 1; + // Protocol value. + Protocol protocol_id = 2; + // Src ISD-AS of the requested DRKey. + uint64 src_ia = 3; + // Dst ISD-AS of the requested DRKey. + uint64 dst_ia = 4; + // Src Host of the request DRKey. + string src_host = 5; + // Dst Host of the request DRKey. + string dst_host = 6; + } + + message HostHostResponse{ + // Begin of validity period of DRKey. + Timestamp epoch_begin = 1; + // End of validity period of DRKey. + Timestamp epoch_end = 2; + // Lvl2 key. + bytes key = 3; + } diff --git a/doc/cryptography/index.rst b/doc/cryptography/index.rst index 49b288c9f7..19d6231186 100644 --- a/doc/cryptography/index.rst +++ b/doc/cryptography/index.rst @@ -16,5 +16,5 @@ Open source cryptography documentation: ca-operations interactions standards - DRKeyInfra + drkey forwarding-key-rollover