IONSECRC(5)

📦 version 3.2.1, in ubuntu jammy

💖 ionsecrc(5) — ICI configuration files 💖

🌸 NAME 🌸

ionsecrc — ION security policy management commands file

✨ DESCRIPTION ✨

okay bestie, so ION security policy management commands get passed to ionsecadmin in one of two ways: either from a file of text lines, or interactively at ionsecadmin's command prompt, which is literally just : 🫶

Commands are interpreted line-by-line, and the vibe check is strict: exactly one command per line. no stacking, no chaos, one command per line, periodt 💅

The formats and effects of the ION security policy management commands are described below. yes, below below, keep scrolling bestie, it's all coming 🔥

A parameter identified as an eid_expr is an "endpoint ID expression." that's the whole thing, no cap.

For all commands, whenever the last character of an endpoint ID expression is the wild-card character *, an applicable endpoint ID "matches" this EID expression if all characters of the endpoint ID expression prior to the last one are equal to the corresponding characters of that endpoint ID. otherwise, an applicable endpoint ID "matches" the EID expression only when all characters of the EID and the EID expression are identical. so like: star at the end means prefix-match energy, no star means exact-match energy, iykyk ⭐

ION's security policy management encompasses both BP security and LTP authentication. both. iconic. 👑

✨ COMMANDS ✨

okay bestie, here's the whole command roster 💅 these are the things you type at the ionsecadmin prompt, and honestly? they're giving main character energy. let's go one by one.

  • ? — the help command. it shows you a listing of the commands and their formats. literally the same thing as the h command. twins fr fr 🫶
  • # — comment line. any line starting with # is just... not interpreted. vibe only, no action. 💭
  • e { 1 | 0 } — echo control. set echo to 1 and every single thing ionsecadmin prints gets logged and sent to stdout (double the slay). set echo to 0 and that behavior is off. simple as. ✨
  • v — version number. prints out the version of ION currently installed. HINT: combine it with the e 1 command to log the version number at startup. cute trick, no cap. 🎀
  • 1 — the initialize command. 🚨 okay so listen: until you run this, the local ION node has no security policy database and most ionsecadmin commands will just fail. so like, do this first. periodt.
  • a key key_name file_name — the add key command. adds a named key value to the security policy database. the content of file_name gets taken as the value of the key. named keys can be referenced by other elements of the security policy database. 🗝️
  • c key key_name file_name — the change key command. changes the value of the named key, grabbing the new key value from the content of file_name.
  • d key key_name — the delete key command. deletes the key identified by name. bye bye 👋
  • i key key_name — prints information about the named key, i.e., the length of its current value.
  • l key — lists all keys in the security policy database. the whole roster, iconic. 📋

🛡️ BAB rules (bundle authentication, babes)

  • a bspbabrule sender_eid_expr receiver_eid_expr { '' | ciphersuite_name key_name } — the add bspbabrule command. adds a rule specifying the manner in which Bundle Authentication Block (BAB) validation will be applied to all bundles sent from any node whose endpoints' IDs match sender_eid_expr and received at any node whose endpoints' IDs match receiver_eid_expr. both sender_eid_expr and receiver_eid_expr should terminate in wild-card characters, because both the security source and security destination of a BAB are actually nodes rather than individual endpoints. lowkey important detail, don't skip it.

if a zero-length string ('') is indicated instead of a ciphersuite_name, then BAB validation is disabled for this sender/receiver EID expression pair: all bundles sent from nodes with matching administrative endpoint IDs to nodes with matching administrative endpoint IDs will be immediately deemed authentic. otherwise, a bundle from a node with matching administrative endpoint ID to a node with matching administrative endpoint ID will only be deemed authentic if it contains a BAB computed via the ciphersuite named by ciphersuite_name using a key value that is identical to the current value of the key named key_name in the local security policy database.

NOTE: if the security policy database contains no BAB rules at all, then BAB authentication is disabled; all bundles received from all neighboring nodes are considered authentic. otherwise, BAB rules must be defined for all nodes from which bundles are to be received; all bundles received from any node for which no BAB rule is defined are considered inauthentic and are discarded. 💀 so yeah, be thorough.
  • c bspbabrule sender_eid_expr receiver_eid_expr { '' | ciphersuite_name key_name } — the change bspbabrule command. changes the ciphersuite name and/or key name for the BAB rule pertaining to the sender/receiver EID expression pair identified by sender_eid_expr and receiver_eid_expr. note that the eid_exprs must exactly match those of the rule that is to be modified, including any terminating wild-card character. exact match or it's not happening bestie 🫠
  • d bspbabrule sender_eid_expr receiver_eid_expr — the delete bspbabrule command. deletes the BAB rule pertaining to the sender/receiver EID expression pair identified by sender_eid_expr and receiver_eid_expr. again: the eid_exprs must exactly match those of the rule that is to be deleted, including any terminating wild-card character.
  • i bspbabrule sender_eid_expr receiver_eid_expr — prints information (the ciphersuite and key names) about the BAB rule pertaining to sender_eid_expr and receiver_eid_expr.
  • l bspbabrule — lists all BAB rules in the security policy database.

🧩 PIB rules

  • a bsppibrule sender_eid_expr receiver_eid_expr block type number { '' | ciphersuite_name key_name } — the add bsppibrule command. adds a rule specifying the manner in which Payload Integrity Block (PIB) validation will be applied to all bundles sent from any node whose administrative endpoint ID matches sender_eid_expr and received at any node whose administrative endpoint ID ID matches receiver_eid_expr.

if a zero-length string ('') is indicated instead of a ciphersuite_name, then PIB validation is disabled for this sender/receiver EID expression pair: all bundles sent from nodes with matching administrative endpoint IDs to nodes with matching administrative endpoint IDs will be immediately deemed valid. otherwise, a bundle from a node with matching administrative endpoint ID to a node with matching administrative endpoint ID will only be deemed valid if it contains a PIB computed via the ciphersuite named by ciphersuite_name using a key value that is identical to the current value of the key named key_name in the local security policy database.

  • c bsppibrule sender_eid_expr receiver_eid_expr block type number { '' | ciphersuite_name key_name } — the change bsppibrule command. changes the ciphersuite name and/or key name for the PIB rule pertaining to the sender/receiver EID expression pair identified by sender_eid_expr and receiver_eid_expr. and yes, the eid_exprs must exactly match those of the rule that is to be modified, including any terminating wild-card character. consistency is the vibe ✨
  • d bsppibrule sender_eid_expr receiver_eid_expr block type number — the delete bsppibrule command. deletes the PIB rule pertaining to the sender/receiver EID expression pair identified by sender_eid_expr and receiver_eid_expr. once more for the people in the back: the eid_exprs must exactly match those of the rule that is to be deleted, including any terminating wild-card character.
  • i bsppibrule sender_eid_expr receiver_eid_expr block type number — prints information (the ciphersuite and key names) about the PIB rule pertaining to sender_eid_expr and receiver_eid_expr.
  • l bsppibrule — lists all PIB rules in the security policy database.

🔐 LTP receive authentication rules

  • a ltprecvauthrule ltp_engine_id ciphersuite_nbr [key_name] — the add ltprecvauthrule command. adds a rule specifying the manner in which LTP segment authentication will be applied to LTP segments received from the indicated LTP engine.

a segment from the indicated LTP engine will only be deemed authentic if it contains an authentication extension computed via the ciphersuite identified by ciphersuite_nbr using the applicable key value. if ciphersuite_nbr is 255 then the applicable key value is a hard-coded constant and key_name must be omitted; otherwise key_name is required and the applicable key value is the current value of the key named key_name in the local security policy database.

valid values of ciphersuite_nbr are:

0: HMAC-SHA1-80 1: RSA-SHA256 255: NULL
  • c ltprecvauthrule ltp_engine_id ciphersuite_nbr [key_name] — the change ltprecvauthrule command. changes the parameters of the LTP segment authentication rule for the indicated LTP engine.
  • d ltprecvauthrule ltp_engine_id — the delete ltprecvauthrule command. deletes the LTP segment authentication rule for the indicated LTP engine.
  • i ltprecvauthrule ltp_engine_id — prints information (the LTP engine id, ciphersuite number, and key name) about the LTP segment authentication rule for the indicated LTP engine.
  • l ltprecvauthrule — lists all LTP segment authentication rules in the security policy database.

✍️ LTP transmit (signing) rules

  • a ltpxmitauthrule ltp_engine_id ciphersuite_nbr [key_name] — the add ltpxmitauthrule command. adds a rule specifying the manner in which LTP segments transmitted to the indicated LTP engine must be signed.

signing a segment destined for the indicated LTP engine entails computing an authentication extension via the ciphersuite identified by ciphersuite_nbr using the applicable key value. if ciphersuite_nbr is 255 then the applicable key value is a hard-coded constant and key_name must be omitted; otherwise key_name is required and the applicable key value is the current value of the key named key_name in the local security policy database.

valid values of ciphersuite_nbr are:

0: HMAC_SHA1-80 1: RSA_SHA256 255: NULL
  • c ltpxmitauthrule ltp_engine_id ciphersuite_nbr [key_name] — the change ltpxmitauthrule command. changes the parameters of the LTP segment signing rule for the indicated LTP engine.
  • d ltpxmitauthrule ltp_engine_id — the delete ltpxmitauthrule command. deletes the LTP segment signing rule for the indicated LTP engine.
  • i ltpxmitauthrule ltp_engine_id — prints information (the LTP engine id, ciphersuite number, and key name) about the LTP segment signing rule for the indicated LTP engine.
  • l ltpxmitauthrule — lists all LTP segment signing rules in the security policy database.

🧹 clearing all the things

  • x [ { ~ | sender_eid_expr } [ { ~ | receiver_eid_expr} [ { ~ | bab | pib | pcb | esb } ] ] ] — this command will clear all rules for the indicated type of bundle security block between the indicated security source and security destination. if block type is omitted it defaults to ~ signifying "all BSP blocks". if both block type and security destination are omitted, security destination defaults to ~ signifying "all BSP security destinations". if all three command-line parameters are omitted, then security source defaults to ~ signifying "all BSP security sources". it's giving ✨spring cleaning✨
  • h — the help command. shows you a listing of the commands and their formats. it's the same as the ? command. (told you they were twins 💖)

🌸 EXAMPLES 🌸

ok bestie this is the part where it all clicks, i promise. here's how it actually looks in real life 💖

  • a key BABKEY ./babkey.txt

adds a brand new key named "BABKEY" whose value is literally just the content of the file "./babkey.txt". that's it. that's the whole thing. copy the file into the key, slay ✨

  • a bspbabrule ipn:19.* ipn:11.* HMAC_SHA1 BABKEY

adds a BAB rule that says: every single bundle travelling from node number 19 to node number 11 has to have Bundle Authentication Blocks computed with the HMAC_SHA1 ciphersuite, using a key value that is identical to whatever the current value of the key named "BABKEY" is in the local security policy database. like, the vibe check is mandatory now 💅

  • c bspbabrule ipn:19.* ipn:11.* ''

changes the BAB rule for all bundles sent from node number 19 to node number 11. BAB checking is disabled, and those bundles will be automatically deemed authentic. no checking, no problem, we're just trusting them now 🫶

the '' at the end there is a real, actual, intentionally-empty argument. not a typo, not me being lazy, it's giving "empty string" and it means something. do not skip it 😭

💜 SEE ALSO 💜

ok that's genuinely the whole page, you made it to the end, main character behaviour honestly 👑 go forth and manage your security policy, no cap.

this lil icon was brought to you by perl v5.24.1, dated 2016-07-07, and it lives its life as IONSECRC(5) — bye bestie, love u, drink water 🌈💖

📦 where this page comes from