From 17ff81988b30a021a5a153192d0d398b9e25819b Mon Sep 17 00:00:00 2001 From: Simon Josefsson Date: Mon, 22 Apr 2013 13:26:03 +0200 Subject: [PATCH] Add YCFG draft. JSON name fixups. --- contrib/draft-josefsson-yubikey-config.xml | 376 +++++++++++++++++++++ ykpers_lcl.c | 22 +- 2 files changed, 387 insertions(+), 11 deletions(-) create mode 100644 contrib/draft-josefsson-yubikey-config.xml diff --git a/contrib/draft-josefsson-yubikey-config.xml b/contrib/draft-josefsson-yubikey-config.xml new file mode 100644 index 0000000..03f607d --- /dev/null +++ b/contrib/draft-josefsson-yubikey-config.xml @@ -0,0 +1,376 @@ + + + + + + + + + +]> + + + + + + + + + + + Yubico YubiKey Configuration Format (YCFG) + + + + + Yubico + +
+ simon@yubico.com + http://www.yubico.com/ +
+ + + + + + + The YubiKey Configuration Format (YCFG) is a data format for + transportation of configuration parameters for a YubiKey slot. + The YubiKey is a small portable device manufactured by Yubico + that generate One-Time-Passwords and has room for two separate + configuration slots. + + + + + + + +
+ + The YubiKey is a small portable device manufactured by Yubico that generate One-Time-Passwords + and has room for two separate configuration slots. + + The YubiKey Configuration Format (YCFG) is a JavaScript Object Notation (JSON) data + format for transportation of configuration parameters for a + YubiKey slot. + + The PSKC format may be used to + transport key material for YubiKey tokens. However, for a + YubiKey to be personalized in any meaningful way, it also needs + a configuration. The YubiKey Configuration Format (YCFG) + described in this document provides a convenient way to express + all possible configuration variants of a YubiKey. + + The reference documentation for the YubiKey is available + and describes all configuration + options. + + Briefly, each slot can be configured in one of the following + modes: + + + + "yubicoOTP": YubiKey One-Time-Password: consists of a + static identifier concatenated with a never-repeating Advanced Encryption Standard + (AES) encrypted part. Personalization of the device + consumes several data fields, including a public identifier, + an internal identifier and an AES key. + + "oathHOTP": OATH HOTP mode, + using a HMAC-SHA1 secret. + + "hmacCR": A challenge response mode, using a HMAC-SHA1 secret. + + "yubicoCR": A challenge response mode which is YubiKey OTP + compatible. + + "staticTicket": A mode that emits a static password. + + + There is a number of options that applies to all modes, and + some options that is only relevant for a particular mode. + +
+ +
+ + Each YCFG instance is a JSON object with one member with name + "yubiProdConfig" having an object value. + + The following illustrate a small YCFG example. + +
+ +
+ + The following members of the "yubiProdConfig" object are + always permitted to exist. + + + "mode": A string, used to specify the basic operation mode + of the slot. Permitted values include "unconfigured" to + denote bare keys, "yubicoOTP" to denote normal YubiKey OTP + mode, "oathHOTP" meaning OATH HOTP mode, "yubicoCR" means + Yubico OTP-based challenge response "hmacCR" means HMAC-based + challenge response mode, and "staticTicket" means static + password mode. + "options": An object with configuration parameters, see + below for definition. + "protection": A string having a value of "random", "none", + "batch", or "id", specifying how write access to the slot is + to be protected. + "scope": A string having a value of "noPublicId", + "yubiCloud", or "privatePrefix". + "ndefType": A string with the NFC NDEF type. + "ndefString": A string with the NFC NDEF content. + + + The following members of the "yubiProdConfig" object only + exists when "mode" is "yubicoOTP", "yubicoCR", and + "oathHOTP". + + + "prefix": A string, identifying the YubiKey prefix. + + + The following members of the "options" object are always + permitted to exist. + + + "allowUpdate": A literal (false or true). + "appendCR": A literal (false or true). + "appendDelay1": A literal (false or true). + "appendDelay2": A literal (false or true). + "sendRef": A literal (false or true). + "pacing10ms": A literal (false or true). + "pacing20ms": A literal (false or true). + "dormant": A literal (false or true). + "fastTrig": A literal (false or true). + "shortTicket": A literal (false or true). + "protectSecond": A literal (false or true). + "serialApiVisible": A literal (false or true). + "serialBtnVisible": A literal (false or true). + "serialUsbVisible": A literal (false or true). + "tabBetween": A literal (false or true). + "tabFirst": A literal (false or true). + "tabLast": A literal (false or true). + "useNumericKeypad": A literal (false or true). + "invertLed": A literal (false or true). + + + The following members of the "options" object only exists + when "mode" is "oathHOTP". + + + "fixedSeedValue": A number indicating the OATH + HOTP initial moving factor (must be a multiple of 16). + "oathDigits": A number indicating the number of + digits in OATH HOTP to emit (6 or 8). + "randomSeed": A literal (false or true) denoting + whether the seed should be initialized to random. + + + The following members of the "options" object only exists + when "mode" is "hmacCR" or "yubicoCR". + + + "buttonReqd": A literal (false or true) denoting + whether user presence is required. + + + The following members of the "options" object only exists + when "mode" is "hmacCR". + + + "hmacLt64": A literal (false or true). + + + The following members of the "options" object only exists + when "mode" is "staticTicket". + + + "strongPw1": A literal (false or true). + "strongPw2": A literal (false or true). + "manUpdate": A literal (false or true). + + + All literal options have a default of "false"; thus it is + only required to include a particular option if there is an + intent to indicate a "true" value. + +
+ +
+ + The following illustrate a slot configured in OATH HOTP + mode. + +
+ +
+ + The following illustrate a slot configured in YubiKey OTP + mode. + +
+ +
+ + The following illustrate a slot configured in challenge + response mode. + +
+ +
+ +
+ +
+ + The following people contributed to the design of the YCFG + format: Jakob Ehrensvärd, Fredrik Thulin, Klas Lindfors, and + John Salter. + +
+ +
+ + General security considerations for the YubiKey and of JSON + are relevant and critical to safe usage of the YCFG format. + + YCFG data needs to be integrity protected during transport in + order to avoid attacks which causes YubiKeys to be personalized + with unintended behaviour. + + Software that operates in this data format must be + implemented properly to not introduce security vulnerabilities + triggered by specially crafted input. + +
+ + + + + + + + &rfc4627; + + + + YubiKey Manual + + + + + + + + + + + + Yubico Company Web Page + + + + + + &aes; + &rfc4226; + &rfc6030; + + + + + + diff --git a/ykpers_lcl.c b/ykpers_lcl.c index 42364de..1512929 100644 --- a/ykpers_lcl.c +++ b/ykpers_lcl.c @@ -34,8 +34,8 @@ struct map_st _ticket_flags_map[] = { { TKTFLAG_TAB_FIRST, "TAB_FIRST", "tabFirst", capability_has_ticket_mods, MODE_OUTPUT }, { TKTFLAG_APPEND_TAB1, "APPEND_TAB1", "tabBetween", capability_has_ticket_mods, MODE_OUTPUT }, { TKTFLAG_APPEND_TAB2, "APPEND_TAB2", "tabLast", capability_has_ticket_mods, MODE_OUTPUT }, - { TKTFLAG_APPEND_DELAY1,"APPEND_DELAY1","appendDelay1", capability_has_ticket_mods, MODE_OUTPUT }, /* XXX: name? */ - { TKTFLAG_APPEND_DELAY2,"APPEND_DELAY2","appendDelay2", capability_has_ticket_mods, MODE_OUTPUT }, /* XXX: name? */ + { TKTFLAG_APPEND_DELAY1,"APPEND_DELAY1","appendDelay1", capability_has_ticket_mods, MODE_OUTPUT }, + { TKTFLAG_APPEND_DELAY2,"APPEND_DELAY2","appendDelay2", capability_has_ticket_mods, MODE_OUTPUT }, { TKTFLAG_APPEND_CR, "APPEND_CR", "appendCR", capability_has_ticket_mods, MODE_OUTPUT }, { TKTFLAG_PROTECT_CFG2, "PROTEXT_CFG2", "protectSecond",capability_has_slot_two, MODE_ALL }, { TKTFLAG_OATH_HOTP, "OATH_HOTP", 0, capability_has_oath, MODE_OATH_HOTP }, @@ -46,21 +46,21 @@ struct map_st _ticket_flags_map[] = { struct map_st _config_flags_map[] = { { CFGFLAG_CHAL_YUBICO, "CHAL_YUBICO", 0, capability_has_chal_resp, MODE_CHAL_YUBICO }, { CFGFLAG_CHAL_HMAC, "CHAL_HMAC", 0, capability_has_chal_resp, MODE_CHAL_HMAC }, - { CFGFLAG_HMAC_LT64, "HMAC_LT64", "hmacLT64", capability_has_chal_resp, MODE_CHAL_HMAC }, /* XXX: name? */ + { CFGFLAG_HMAC_LT64, "HMAC_LT64", "hmacLt64", capability_has_chal_resp, MODE_CHAL_HMAC }, { CFGFLAG_CHAL_BTN_TRIG, "CHAL_BTN_TRIG", "buttonReqd", capability_has_chal_resp, MODE_CHAL_RESP }, { CFGFLAG_OATH_HOTP8, "OATH_HOTP8", 0, capability_has_oath, MODE_OATH_HOTP }, { CFGFLAG_OATH_FIXED_MODHEX1, "OATH_FIXED_MODHEX1", 0, capability_has_oath, MODE_OATH_HOTP }, { CFGFLAG_OATH_FIXED_MODHEX2, "OATH_FIXED_MODHEX2", 0, capability_has_oath, MODE_OATH_HOTP }, { CFGFLAG_OATH_FIXED_MODHEX, "OATH_FIXED_MODHEX", 0, capability_has_oath, MODE_OATH_HOTP }, - { CFGFLAG_SEND_REF, "SEND_REF", "sendRef", capability_has_ticket_mods, MODE_OUTPUT }, /* XXX: name? */ + { CFGFLAG_SEND_REF, "SEND_REF", "sendRef", capability_has_ticket_mods, MODE_OUTPUT }, { CFGFLAG_TICKET_FIRST, "TICKET_FIRST", 0, capability_has_ticket_mods, MODE_OUTPUT }, - { CFGFLAG_PACING_10MS, "PACKING_10MS", "pacing10MS", capability_has_ticket_mods, MODE_OUTPUT }, /* XXX: name? */ - { CFGFLAG_PACING_20MS, "PACING_20MS", "pacing20MS", capability_has_ticket_mods, MODE_OUTPUT }, /* XXX: name? */ + { CFGFLAG_PACING_10MS, "PACKING_10MS", "pacing10ms", capability_has_ticket_mods, MODE_OUTPUT }, + { CFGFLAG_PACING_20MS, "PACING_20MS", "pacing20ms", capability_has_ticket_mods, MODE_OUTPUT }, { CFGFLAG_ALLOW_HIDTRIG, "ALLOW_HIDTRIG", 0, capability_has_hidtrig, MODE_OUTPUT }, - { CFGFLAG_SHORT_TICKET, "SHORT_TICKET", "shortTicket", capability_has_static_extras, MODE_STATIC_TICKET }, /* XXX: name? */ - { CFGFLAG_STRONG_PW1, "STRONG_PW1", "strongPw1", capability_has_static_extras, MODE_STATIC_TICKET }, /* XXX: name? */ - { CFGFLAG_STRONG_PW2, "STRONG_PW2", "strongPw2", capability_has_static_extras, MODE_STATIC_TICKET }, /* XXX: name? */ - { CFGFLAG_MAN_UPDATE, "MAN_UPDATE", "manUpdate", capability_has_static_extras, MODE_STATIC_TICKET }, /* XXX: name? */ + { CFGFLAG_SHORT_TICKET, "SHORT_TICKET", "shortTicket", capability_has_static_extras, MODE_STATIC_TICKET }, + { CFGFLAG_STRONG_PW1, "STRONG_PW1", "strongPw1", capability_has_static_extras, MODE_STATIC_TICKET }, + { CFGFLAG_STRONG_PW2, "STRONG_PW2", "strongPw2", capability_has_static_extras, MODE_STATIC_TICKET }, + { CFGFLAG_MAN_UPDATE, "MAN_UPDATE", "manUpdate", capability_has_static_extras, MODE_STATIC_TICKET }, { 0, 0, 0, 0, 0 } }; @@ -80,7 +80,7 @@ struct map_st _extended_flags_map[] = { struct map_st _modes_map[] = { { MODE_OATH_HOTP, 0, "oathHOTP", 0, 0 }, { MODE_CHAL_HMAC, 0, "hmacCR", 0, 0 }, - { MODE_STATIC_TICKET, 0, "staticTicket", 0, 0 }, /* XXX: name? */ + { MODE_STATIC_TICKET, 0, "staticTicket", 0, 0 }, { MODE_CHAL_YUBICO, 0, "yubicoCR", 0, 0 }, { MODE_OTP_YUBICO, 0, "yubicoOTP", 0, 0 }, { 0, 0, 0, 0, 0 } -- 2.39.5