![build](https://github.com/uhppoted/uhppoted-app-s3/workflows/build/badge.svg)
uhppoted-app-s3
cron
'able command line utility to download access control lists stored on S3 to UHPPOTE UTO311-L0x
access controller boards.
Supported operating systems:
Release Notes
Current Release
v0.8.7 - 2023-12-01
- Maintenance release for compatibility with uhppoted-lib v0.8.7
Installation
Executables for all the supported operating systems are packaged in the releases. The provided archives contain the executables for all the operating systems - OS specific tarballs can be found in the uhppoted releases.
Installation is straightforward - download the archive and extract it to a directory of your choice and then place the executable in a directory in your PATH. The uhppoted-app-s3
utility requires the following additional
files:
uhppoted.conf
aws.credentials
keys
directory containg the public keys for all user ID's permitted to sign an ACLuhppoted
key file used to (optionally) sign uploaded files
uhppoted.conf
uhppoted.conf
is the communal configuration file shared by all the uhppoted
project modules and is (or will
eventually be) documented in uhppoted. uhppoted-app-s3
requires the
devices section to resolve non-local controller IP addresses and door to controller door identities.
A sample uhppoted.conf file is included in the uhppoted
distribution.
aws.credentials
The credentials required to directly access files in AWS S3 buckets are retrieved from an AWS credentials file. The
file follows the current AWS credentials convention:
[default]
aws_access_key_id = AK...
aws_secret_access_key = FR...
uhppoted-app-s3
uses the [default]
credentials and defaults to the .aws/credentials
file - use the -credentials
option to specify an alternative credentials file. Future releases may add a command line option to select alternative credential sets from within the file.
NOTE:
It is highly recommended that a dedicated set of IAM credentials be created for use with uhppoted-app-s3
,
with a policy that restricts access to only the required S3 buckets and keys.
keys directory
The keys directory should contain the RSA public keys of the users that are authorised to provide ACL files. The
public key files should be named:
<userID>.pub
where userID
is the user ID included as the uname
attribute of the ACL file in the tar.gz archive (or corresponding comment
in a ZIP file). The default keys directory is /acl/keys. An alternative directory can be specified
with the --keys
command line option for the load
and compare
commands.
key file
The key file is the RSA private key used by uhppoted-app-s3
to sign uploaded files (derived ACL's and reports). The default key file is /acl/keys/uhppoted. An alternative key file can be specified with the --keys
command line option for the store
and compare
commands.
Building from source
Assuming you have Go
and make
installed:
git clone https://github.com/uhppoted/uhppoted-app-s3.git
cd uhppoted-app-s3
make build
If you prefer not to use make
:
git clone https://github.com/uhppoted/uhppoted-app-s3.git
cd uhppoted-app-s3
mkdir bin
go build -trimpath -o bin ./...
The above commands build the 'uhppoted-app-s3
executable to the bin
directory.
Dependencies
uhppoted-app-s3
Usage: uhppoted-app-s3 <command> <options>
Supported commands:
help
version
load-acl
store-acl
compare-acl
ACL file format
The only currently supported ACL file format is TSV (tab separated values) and is expected to be formatted as follows:
Card Number PIN From To Workshop Side Door Front Door Garage Upstairs Downstairs Tower Cellar
123465537 1234 2023-01-01 2023-12-31 N N Y N Y N Y Y
231465538 4321 2023-01-01 2023-12-31 Y N Y N N Y 29 N
635465539 2023-01-01 2023-12-31 N N N N Y N Y Y
Field | Description |
---|
Card Number | Access card number |
From | Date from which card is valid (valid from 00:00 on that date) |
To | Date until which card is valid (valid until 23:59 on that date) |
<door> | Door name matching controller configuration (case and space insensitive) |
<door> | ... |
... | |
PIN | Keypad PIN code (optional) |
The ACL file must include a column for each controller + door configured in the devices section of the uhppoted.conf
file used to configure the utility.
An example ACL file is included in the full uhppoted
distribution, along with the matching conf file.
load-acl
Fetches an ACL file from S3 (or other URL) and downloads it to the configured UHPPOTE controllers. Intended for use in a cron
task that routinely updates the controllers from an authoritative source that exports the access control list as a TSV file. The ACL file is expected to be a .tar.gz
or .zip
archive and should include the following two files:
The signature
file is the RSA signature of the ACL file - it can be created using the openssl
command:
openssl dgst -sha256 -sign <key file> <ACL file> signature
The user ID used to sign the ACL file should be included in the command to create the .tar.gz
file:
tar cvzf acl.tar.gz --uname <user id> --gname <uhppoted> myacl.acl signature
and should match a public key file in the keys directory for the uhppoted-app-s3
utility. For .zip
archives, the user ID should be included as a comment to the ACL file entry:
zip -c myacl.zip myacl.acl signature
A sample tar.gz file is included in the full uhppoted
distribution.
Command line:
uhppoted-app-s3 load-acl --url <url>
uhppoted-app-s3 load-acl [--debug] [--with-pin] [--no-log] [--no-report] [--no-verify] [--config <file>] [--workdir <dir>] [--keys <dir>] [--credentials <file>] [--region <region>] --url <url>
--url URL from which to fetch the ACL files. A URL starting with s3:// specifies
that the file should be fetched from an AWS S3 bucket using S3 operations
and AWS credentials (files stored in AWS S3 buckets can also be retrieved
using pre-signed https:// URL's). URL's with the file:// protocol can be used to specify local files. The file is expected to be a .tar.gz or .zip archive containing an ACL and signature file (defaults to .tar.gz unless the URL ends with .zip)
--credentials AWS credentials file (described below) for fetching files from s3:// URL's
--region AWS S3 region (e.g. us-east-1) for use with the AWS credentials
--keys Directory containing the public keys for RSA keys used to sign the ACL's
--config Sets the uhppoted.conf file to use for controller configurations
--workdir Sets the working directory for generated report files
--with-pin Updates the card keypad PIN code
--no-log Writes log messages to the console rather than the rotating log file
--no-report Prints the load-acl operational report to the console rather than creating a report file
--no-verify Disables verification of the ACL file signature
--debug Displays verbose debugging information, in particular the communications with the UHPPOTE controllers
store-acl
Fetches the cards stored in the configured UHPPOTE controllers, creates a matching ACL file from the UHPPOTED controller configuration and uploads it to an AWS S3 bucket (or other URL). Intended for use in a cron
task that routinely audits the cards stored on the controllers against an authoritative source. The ACL file is a .tar.gz
or .zip
archive and contains the following two files:
The signature
file is the RSA signature of the ACL file - it can be verified using the openssl
command:
openssl dgst -sha256 -verify <uhppoted public key file> -signature signature <ACL file>
Command line:
uhppoted-app-s3 store-acl --url <url>
uhppoted-app-s3 store-acl [--debug] [--with-pin] [--no-log] [--no-sign] [--config <file>] [--key <RSA signing key>] [--credentials <file>] [--region <region>] --url <url>
--url URL to which to store the ACL file. A URL starting with s3:// specifies
that the file should be stored in an AWS S3 bucket using S3 operations
and AWS credentials (files stored in AWS S3 buckets can also be uploaded
using a pre-signed https:// URL). URL's with the file:// protocol can be used to specify local files. The created file is a .tar.gz (or .zip)
archive containing an ACL and signature file (defaults to .tar.gz unless
the URL ends with .zip)
--credentials AWS credentials file (described below) for fetching files from s3:// URL's
--region AWS S3 region (e.g. us-east-1) for use with the AWS credentials
--key File containing the private RSA key used to sign the ACL
--config Sets the uhppoted.conf file to use for controller configurations
--with-pin Includes the card keypad PIN code in the retrieved ACL
--no-sign Does not sign the generated ACL file with the uhppoted RSA signing key
--no-log Writes log messages to the console rather than the rotating log file
--debug Displays verbose debugging information, in particular the communications with the UHPPOTE controllers
compare-acl
Fetches an ACL file from S3 (or other URL) and compares it to the cards stored in the configured UHPPOTE controllers. Intended for use in a cron
task that routinely audits the controllers against an authoritative source that exports the access control list as a TSV file. The ACL file follows the structure outlined above for the load-acl
command i.e. should be a .tar.gz
or .zip
archive and should include the following two files:
The signature
file is the RSA signature of the ACL file - it can be created using the openssl
command:
openssl dgst -sha256 -sign <key file> <ACL file> signature
The user ID used to sign the ACL file should be included in the command to create the .tar.gz
file:
tar cvzf acl.tar.gz --uname <user id> --gname <uhppoted> myacl.acl signature
and should match a public key file in the keys directory for the uhppoted-app-s3
utility. For .zip
archives, the user ID should be included as a comment to the ACL file entry:
zip -c myacl.zip myacl.acl signature
Command line:
uhppoted-app-s3 compare-acl --acl <url> --report <url>
uhppoted-app-s3 compare-acl [--debug] [-with-pin] [--no-log] [--no-verify] [--config <file>] [--keys <dir>] [--key <file>] [--credentials <file>] [--region <region>] --acl <url> --report <url>
--acl URL from which to fetch the ACL files. A URL starting with s3:// specifies
that the file should be fetched from an AWS S3 bucket using S3 operations
and AWS credentials (files stored in AWS S3 buckets can also be retrieved
using pre-signed https:// URL's). URL's with the file:// protocol can be used to specify local files. The file is expected to be a .tar.gz or .zip archive containing an ACL and signature file (defaults to .tar.gz unless the URL ends with .zip)
--report URL to which to store the compare report file. A URL starting with s3:// specifies
that the file should be stored in an AWS S3 bucket using S3 operations
and AWS credentials (files stored in AWS S3 buckets can also be uploaded
using a pre-signed https:// URL). URL's with the file:// protocol can be used to specify local files. The created file is a .tar.gz (or .zip) archive containing an ACL and signature file (defaults to .tar.gz unless the URL ends with .zip)
--credentials AWS credentials file (described below) for fetching files from s3:// URL's
--region AWS S3 region (e.g. us-east-1) for use with the AWS credentials
--keys Directory containing the public keys for RSA keys used to sign the ACL's
--key File containing the private RSA key used to sign the report
--config Sets the uhppoted.conf file to use for controller configurations
--with-pin Includes the card keypad PIN code when comparing cards
--no-verify Disables verification of the ACL file signature
--no-log Writes log messages to the console rather than the rotating log file
--debug Displays verbose debugging information, in particular the communications with the UHPPOTE controllers