1.. _module-pw_software_update-get-started: 2 3------------------------------- 4pw_software_update: Get started 5------------------------------- 6.. pigweed-module-subpage:: 7 :name: pw_software_update 8 9Hello Bundles! 10-------------- 11 12A bundle represents a single software release instance -- including 13all target files of the software build and metadata needed to match, 14verify and install the build on a target device. 15 16The following illustrates how a bundle is created, signed, inspected, 17and verified using ``pw update ...`` commands. 18 191. First let's make a working directory under your Pigweed dir. The 20 ``pw update`` command is not yet visible outside the Pigweed 21 directory. 22 23.. code-block:: bash 24 25 $ cd ~/pigweed 26 $ source activate.sh 27 28 $ mkdir hello_bundles 29 $ cd hello_bundles 30 31 322. Create signing keys for "root" and "targets" roles. 33 34.. note:: 35 Here keys are generated locally for demonstration purposes only. In 36 production, you must use a proper key management service (such as 37 `Google Cloud KMS <https://cloud.google.com/security-key-management>`_) 38 to generate, control access to, and log usage of software signing keys. 39 40.. code-block:: bash 41 42 $ mkdir keys 43 $ pw update generate-key keys/root_key 44 $ pw update generate-key keys/targets_key 45 $ tree 46 . 47 └── keys 48 ├── root_key 49 ├── root_key.pub 50 ├── targets_key 51 └── targets_key.pub 52 533. Now that we have the keys, let's find them an owner by creating the root 54 metadata. 55 56.. code-block:: bash 57 58 # Assign a single key to each "root" and "targets" roles. 59 $ pw update create-root-metadata --append-root-key keys/root_key.pub \ 60 --append-targets-key keys/targets_key.pub -o root_metadata.pb 61 62 # Sign the root metadata with the root key to make it official. 63 $ pw update sign-root-metadata --root-metadata root_metadata.pb \ 64 --root-key keys/root_key 65 66 # Review the generated root metadata (output omitted for brevity). 67 $ pw update inspect-root-metadata root_metadata.pb 68 694. Now we are ready to create a bundle. 70 71.. code-block:: bash 72 73 # Start with an empty bundle. 74 $ pw update create-empty-bundle my_bundle.pb 75 76 # Add root metadata. 77 $ pw update add-root-metadata-to-bundle \ 78 --append-root-metadata root_metadata.pb --bundle my_bundle.pb 79 80 # Add some files. 81 $ mkdir target_files 82 $ echo "application bytes" > target_files/application.bin 83 $ echo "rtos bytes" > target_files/rtos.bin 84 $ pw update add-file-to-bundle --bundle my_bundle.pb --file target_files/application.bin 85 $ pw update add-file-to-bundle --bundle my_bundle.pb --file target_files/rtos.bin 86 $ tree 87 . 88 ├── keys 89 │ ├── root_key 90 │ ├── root_key.pub 91 │ ├── targets_key 92 │ └── targets_key.pub 93 ├── my_bundle.pb 94 ├── root_metadata.pb 95 └── target_files 96 ├── application.bin 97 └── rtos.bin 98 99 # Sign our bundle with the "targets" key. 100 $ pw update sign-bundle --bundle my_bundle.pb --key keys/targets_key 101 102 # Review and admire our work (output omitted). 103 $> pw update inspect-bundle my_bundle.pb 104 1055. Finally we can verify the integrity of our bundle. 106 107.. note:: 108 Here we are using ``python3 -m pw_software_update.verify`` because the 109 ``pw verify-bundle`` command is WIP. 110 111.. code-block:: bash 112 113 $ python3 -m pw_software_update.verify --incoming my_bundle.pb 114 Verifying: my_bundle.pb 115 (self-verification) 116 Checking content of the trusted root metadata 117 Checking role type 118 Checking keys database 119 Checking root signature requirement 120 Checking targets signature requirement 121 Checking for key sharing 122 Verifying incoming root metadata 123 Checking signatures against current root 124 Total=1, threshold=1 125 Verified: 1 126 Checking content 127 Checking role type 128 Checking keys database 129 Checking root signature requirement 130 Checking targets signature requirement 131 Checking for key sharing 132 Checking signatures against current root 133 Total=1, threshold=1 134 Verified: 1 135 Checking for version rollback 136 Targets key rotation: False 137 Upgrading trust to the incoming root metadata 138 Verifying targets metadata 139 Checking signatures: total=1, threshold=1 140 Verified signatures: 1 141 Checking content 142 Checking role type 143 Checking targets metadata for version rollback 144 Verifying target file: "application" 145 Verifying target file: "rtos" 146 Verification passed. 147 148���� 149Congratulations on creating your first ``pw_software_update`` bundle! 150���� 151 152To learn more, see :ref:`module-pw_software_update-design`. 153