Update docs to clarify file extensions for gpg key file names

Update http source docs now that digest verification and file permissions are supported options

Author: adamperlin

website/docs/examples/repos/msft-ubuntu.yml.md

@@ -8,16 +8,18 @@ dependencies:
     msft-golang:
   extra_repos:
     - keys:
-        msft.gpg: # Note: This must currently use a `.gpg` suffix or apt will not be happy
+       # Note: The name for the key must use the proper `.gpg` (binary) or `.asc` (ascii)
+       # extension, or apt will not be able to import the key properly
+        msft.asc:          
           http:
             url: https://packages.microsoft.com/keys/microsoft.asc
             digest: sha256:2cfd20a306b2fa5e25522d78f2ef50a1f429d35fd30bd983e2ebffc2b80944fa
       config:
         microsoft-prod.list:
           inline:
             file:
-              # Note the `signed-by` path is always going to be `/usr/share/keyrings/<source key name>` for Ubuntu, in this case our source key name is `msft.gpg`
-              contents: deb [arch=amd64,arm64,armhf signed-by=/usr/share/keyrings/msft.gpg] https://packages.microsoft.com/ubuntu/22.04/prod jammy main
+              # Note the `signed-by` path is always going to be `/usr/share/keyrings/<source key name>` for Ubuntu, in this case our source key name is `msft.asc`
+              contents: deb [arch=amd64,arm64,armhf signed-by=/usr/share/keyrings/msft.asc] https://packages.microsoft.com/ubuntu/22.04/prod jammy main
       envs:
         # The repository will only be available when installing build dependencies
         - build

website/docs/repositories.md

@@ -14,7 +14,7 @@ structure:
   A map of keys required to enable the configured repositories. Each key in
   this map is associated with a specific source and must be imported to allow
   the repositories to function as expected. The content of this is a
-  [source](sources.md) just like in the sources section.
+  [source](sources.md) just like in the sources section. 
 
 - **`config`**
   A collection of repository configurations to add to the environment. The
@@ -43,6 +43,11 @@ structure:
 
 These configurations are highly distribution specific.
 
+:::tip
+Be careful to name the key files properly depending on whether they are ascii armored (`*.asc`) or binary (`*.gpg`). 
+Some package managers such as `apt` do not handle keys properly if they are not named with the correct extension.
+:::
+
 ### Examples:
 
 import MsftUbuntuRepo from './examples/repos/msft-ubuntu.yml.md'

website/docs/sources.md

@@ -97,18 +97,23 @@ by the client, not the actual secret values.
 
 ### HTTP
 
-HTTP sources fetch a file from an HTTP URL.
-HTTP content is not verified by digest today, but it is in the roadmap.
+HTTP sources fetch a file from an HTTP URL. The HTTP source type is considered to be a "file" source. 
+
+The fetched file can be verified against a digest
+if one is supplied. There is also a `permissions` field that can set the octal permissions
+of the fetched file.
 
 ```yaml
 sources:
   someSource1:
     http:
-      # No Digest verification
       url: https://example.com/someFile.txt
+      # optional digest field
+      digest: sha256:1234567890abcdef
+      # optional permissions field
+      permissions: 0644
 ```
 
-The HTTP source type is considered to be a "file" source.
 
 ### Build context