mac2pwd.1
Author: cmaier@cmassoc.net

    mac2pwd(1)                                   Qualcomm Atheros Open Powerline Toolkit                                  mac2pwd(1)

    NAME
           mac2pwd - Qualcomm Atheros Ethernet Device Password Generator

    SYNOPSIS
           mac2pwd [options] file [file] [ ... ]

    DESCRIPTION
           Read Ethernet MAC addresses from one or more files and print a unique password for each address.  Program output is suit‐
           able as input to the Qualcomm Atheros HomePlug AV Production Test System or may be used  in  custom  production  systems.
           Input  addresses  can  appear in any order and need not be consecutive.  Computed passwords consist of upper case letters
           and digits with optional group separators.  Output consists of address/password pairs in text format.

           This program may be used to generate passwords for large numbers of non-consecutive MAC addresses that occur in  unspeci‐
           fied  order.   It  complements program mac2pw which generates passwords for consecutive MAC addresses over a given range.
           Options exist to modify the password algorithm, password length and character bunching.

           This program is part of the Qualcomm Atheros Powerline Toolkit.  See the AMP man page for an  overview  and  installation
           instructions.

    CAVEATS
           Atheros  provides  this program as a simple means of generating unique and apparently random device passwords for a large
           volume of Ethernet devices.  Two different password algorithms are implemented but neither one is required  for  HomePlug
           AV compliance.  Vendors are free to use other methods to generate their own device passwords and are encouraged to do so.

           Random Method
                  Generate  random passwords based on system entropy.  A different set of passwords is generated for a given address
                  range with each program execution.  There is no correlation at  between  addresses  and  passwords.   This  method
                  secure but requires care when programming and labelling devices at the factory.  It may be necessary to maintain a
                  database if regular device maintenance and firmware upgrade are needed.

           Device Method
                  Generate apparently random passwords based on device address.  The same set of passwords will be generated  for  a
                  given  address  range with each program execution.  This method may be appropriate on system where regular mainte‐
                  nance and firmware updates are required.  This method is not secure because device  addresses  can  be  determined
                  using  a  variety  of  network management programs.  Anyone having access to this program, or the algorithm, could
                  compute the device password and gain access to device features reserved for privileged users.  This  program  does
                  provide features to mitigate the risks of using this method.

    OPTIONS
           -b bunch
                  The  password  bunching  factor.  Passwords consists of count uppercase letters and digits optionally displayed in
                  groups separated by hyphens.  The bunching factor specifies the number of letters and digits in each group.   When
                  bunch  is  0  or greater than count, bunching is suppressed.  Separating hyphens increase overall password length.
                  The minimum is 0 and the maximum is 255.  The default is 0 which suppresses bunching.

           -e     Compute passwords based on host system entropy.  Passwords consist of uppercase letters [A-Z]  optionally  grouped
                  using  option -b.  This method produces a non-repeatable set of unique passwords over a given address range.  This
                  method is the default and is secure.

           -l count
                  The number of letters in the password string.  The default count is 16.  Overall password length  is  the  sum  of
                  count plus the number of delimiters implied by bunch.

           -m     Compute passwords based on target device address.  Passwords consist of uppercase letters [A-Z].  This method pro‐
                  duces a repeatable set of unique passwords over a given address range.  This method is not secure.

           -q     Quiet mode.  Exclude the MAC address on output.  This option can be used in scripts to return the password associ‐
                  ated with a given MAC address.

           -v     Verbose mode.  Prefix each line with a '0' column.  The Atheros Production Test System (PTS) uses the first column
                  of a password database file to indicate which addresses and passwords have already been used.

           -?,--help
                  Print program help information on stdout.  This option takes precedence over other options on the command line.

           -!,--version
                  Print program version information on stdout.  This option takes precedence over other options on the command line.
                  Use  this option when sending screen dumps to Atheros Technical Support so that they know exactly which version of
                  the Linux Toolkit you are using.

    ARGUMENTS
           file   The name of a file that contains Ethernet address strings.  Individual address strings consist of  12  consecutive
                  hexadecimal digits.  Addresses are seperated by whites space.  This allows multiple addresses on a line.  There is
                  no line length limit.  Punctuation is not permitted; however, a hash ('#') or semicolon (';') in any column starts
                  comment  text  that  continues to the end of that line.  An error in any input file terminates the program with an
                  error message.

    EXAMPLES
           An example input file, mac.txt, is shown below.  Comment lines document the file.  Blank lines are permitted and multiple
           addresses appear on one line.  This file contains 5 MAC addresses.  Punctuation is not permitted within a MAC address.

              # =================================
              # unused MAC addresses;
              # ---------------------------------
              00b052000004
              00b052BABE33
              00b052BABE34 00b052CAFE05
              00b052CAFE01

           Another  example  input  file,  mac2.txt,  appears  below.  A hash ('#') and a semi-colon (';') are used to hide selected
           addresses.  Hidden addresses are ignored because they are comments.  This file contains 7 addresses but only  5  will  be
           recognized.

              002b88ffff00
              002b887fff00
              # 002b88660066
              002b88660067
              002b88660063 ; 002b8800FFFF
              002b88660066

           The  next  example  reads the two files shown above and prints 10 addresses, 5 from each file, with associated passwords.
           Output appears on the console but may be piped to a file or another process.

              # mac2pwd mac.txt more.mac
              00B052000004 8C69GFCXATB8RA9SF52LK79UD
              00B052BABE33 MMKGF5SP5DP23KHY27BSLRV2A
              00B052BABE34 CVBG6QHJFQVVCYSACPAPBZT79
              00B052CAFE05 MCXUABFPC33CPMXWFWYX5N2KC
              00B052CAFE01 5GHUWD9YDEL8TCAGEZJ8ESRCC
              002B88FFFF00 CJCW4VB2HZ37DAK2XE9CGCWZZ
              002B887FFF00 W2W9AQU5TE8K4ZLH7R3K5C6X4
              002B88660067 2LWQ5LGBUCDFDYSZYQ2XZSPJ2
              002B88660063 62NKW6RM87UBZG34KH87AXXEY
              002B88660066 KNQAGGFH9G9XQGR96GR4HK4SS

           The next example does the the two files, as before but shortens password length and groups password  character.   Overall
           password  length  includes password characters plus delimiters.  Option -l sets password length to 16 characters.  Option
           -b sets bunching to 4 characters.

              # mac2pwd mac.txt more.mac -l 16 -b 4
              00B052000004 R5YH-E6XG-TECA-24R8
              00B052BABE33 WBQJ-77PC-VQTX-63Q5
              00B052BABE34 4M2X-GVUY-6PYH-H5V7
              00B052CAFE05 Z8JA-A2MV-49JF-WJZZ
              00B052CAFE01 5L7Z-ZXZP-NUFS-RBKE
              002B88FFFF00 3RAD-HQPN-92G2-HJKA
              002B887FFF00 7YD7-9NJJ-39S7-8ZGF
              002B88660067 HZ6K-SBG5-ZL8S-K2DK
              002B88660063 MX5K-W7PF-T823-38MJ
              002B88660066 PDXL-84QH-GKUN-KVEE

           The next example is the same but prints output suitable for input to the Qualcomm Atheros PTS because option -v is speci‐
           fied.  The output format is similar to that produced by the Qualcomm Atheros DB Builder Utility for Windows.

              # mac2pwd -v mac.txt more.mac
              0 00B052000004 ZZYBQP7EAZKBNWWCKKC4HX3AW
              0 00B052BABE33 LG7XD97UPSBUHA6F7CU28P3WW
              0 00B052BABE34 8BF288CZN4NTBUFSJAQLUYYNF
              0 00B052CAFE05 RTK4XHMWKWWD654QRBQGW5UNH
              0 00B052CAFE01 EE5YLRXD2EGKS6TSGZZK7ES74
              0 002B88FFFF00 BRYJDWYGP79GFWZN8ZU8ZQ3GN
              0 002B887FFF00 KEULLGC6PYFAM3FE89TYTSMP6
              0 002B88660067 H4STMXB67QR22J39MAZQRHHA5
              0 002B88660063 HKF32QX2GCZKGR3XYTMQCWTRB
              0 002B88660066 STKF28Q2JXYEMAQZVQSFVTKFB

           The next example omits the MAC address.  This may used to generate random passwords for other purposes.

              # mac2pwd -q mac.txt more.mac
              W6QXL6KDY4SZLL538CAMWSH8N
              PMYLFYMNA5TKYU2S6LBJS6QCR
              B2P58XQ2L4JSNR6SXEZ6BSVSN
              GYG6MS8NFEVH8EFBPD483WWCJ
              44TQ6FYCVSGP9GLS6YSYRTWFQ
              GUGPUJ6284X22ZU4RKXAX5T65
              LGSV6L9Y9398DFY3Z2TUFBCAJ
              H95A2FYV3LNT7BBFSLCLHXEH8
              JXSY7TMKK6CP3LDWNE3M74G87
              V4TEAG2ZX3J3NJHPAJMMQTQNT

    DISCLAIMER
           Qualcomm Atheros reserves the right to modify program names, functionality, input format or output format in future tool‐
           kit releases without any obligation to notify or compensate toolkit users.

    SEE ALSO
           hpavkey(1), hpavkeys(1), keys(1), mac2pw(1), rkey(1)

    CREDITS
            Charles Maier <cmaier@qca.qualcomm.com>
            Pouyan Sepehrdad <pouyans@qti.qualcomm.com>
            Ning Shang <nshang@qti.qualcomm.com>

    open-plc-utils-0.0.3                                        Mar 2014                                                  mac2pwd(1)

[PREV] [HOME] [NEXT]