Harpy
Description
The Harpy plugin for Eagle provides public key infrastructure-based software license enforcement. It supports the creation, verification, and renewal of license and script certificates. It also supports signed script verification and evaluation, via the aforementioned script certificates.
The Badge plugin is used with Harpy and provides the signed script certificates for the Eagle script library and test suite infrastructure.
These plugins are commercial products of Eyrie Solutions . Both binary and source code licenses are available.
Licensing
As of Eagle beta 41, Eagle will ship with the Harpy and Badge plugins included by default, along with a means of dynamically requesting a demo license certificate allowing their use. The following script fragment should be used to make use of this functionality:
#
# NOTE: After running this command, the Harpy and Badge plugins
# may be loaded successfully using either [package require]
# or [source enableSecurity]. The [requestLicenseCertificate]
# command requests a "demo" license certificate for Harpy
# from the appropriate server. The certificate returned
# will only be valid for a limited time. Please save the
# returned file somewhere if you wish to use it multiple
# times. Requesting too many license certificates will be
# considered abusive and may result in being banned from
# requesting any more.
#
set env(Override_Badge_Certificate) [set \
env(Override_Harpy_Certificate) [requestLicenseCertificate]]A Word About File Formats
- All Harpy certificates are XML documents with a full schema .
- Key pair files are SNK files or PVK files (with or without password protection).
- Key ring files are signed Eagle script files that use only the set command (see demo key ring file ).
Secure Script Evaluation
Harpy contains a security policy engine that is capable of monitoring the evaluation of (script) files and streams.
When a security policy is set to "signed only", a script must be signed by a trusted key pair in order for it to be successfully evaluated.
The key pair must be valid for signing scripts, must not be expired, and must chain back up to the trusted root key pair.
All script files shipped with Eagle are signed and their signatures are checked when appropriate; the Badge plugin provides the script certificates associated with these script files.
It is possible to setup a "safe" interpreter in such a way that it will evaluate signed scripts with elevated privileges.
It is also possible to use native Tcl and Eagle in tandem (and in the same process) in such a way that native Tcl scripts can take full advantage of the security provided by Harpy.
Script certificates can be set to remain valid forever -OR- to expire at some point.
Harpy supports the automatic renewal of script certificates via its certificate renewal server, Kapok.
As of Beta 41, Harpy supports the revocation of both license and script certificates via its associated server, Kapok.
Secure Script Creation
The Harpy plugin also provides a complete set of commands for managing license certificates, script certificates, and key pairs, and key rings. The following example shows how to sign a script file:
# # NOTE: You can use SNK files, PVK files, or generate a new key pair. # set privateKey [keypair open -public -private C:/path/to/private.snk] # # NOTE: Either you can create a Certificate object from scratch -OR- # you can load an XML file as a template and modify the properties # you need to change. # set certificate [certificate import -alias -validate C:/path/to/some/template.xml] # # NOTE: For example, set the certificate to expire after 7 days and # include your company name. # $certificate Duration 7.00:00:00 $certificate Vendor "Your Company Name Here" # # NOTE: This performs the actual RSA signing of the certificate. # certificate signfile -setid -settimestamp -setkey $certificate $privateKey C:/path/to/your/script/someFile.eagle # # NOTE: This exports the signed certificate to a file. # certificate export -validate $certificate C:/path/to/your/script/someFile.eagle.harpy
Example Usage
There are several ways to enable secure script evaluation; however, the simplest way is:
# # NOTE: This command will fail if it cannot find a valid license # certificate for the Harpy plugin. Please refer to the # [requestLicenseCertificate] example above on how to make # this work. # source enableSecurity; # note the lack of a file extension here
The above command does several things:
- It attempts to load the Harpy and Badge plugins.
- It loads the trusted key rings.
- It sets all security policies to "signed only".
#
# NOTE: The associated script certificate
# ("C:/path/to/some/someFile.eagle.harpy")
# will be checked before evaluation.
#
source C:/path/to/some/someFile.eagle
#
# NOTE: The associated script certificate
# ("https://script.eagle.to/scripts/secureTest7.eagle.harpy")
# will be checked before evaluation.
#
source https://script.eagle.to/scripts/secureTest7.eagleBefore the above source command is allowed to execute, Harpy attempts to locate and verify the associated script certificate. In the event of a failure of any kind, including the script file having been modified after being signed, the script file will not be evaluated. It should be noted that both local file names and URIs may be used to the as the argument to source and both are handled by Harpy. It will always look for a file named exactly the same as the target file, with the literal string ".harpy" appended to it. For remote URIs, this will cause an additional request to the target server. It is possible to avoid this by using what is known as an "embedded script certificate", in which the entire script certificate specially formatted and appended to the end of the script file itself.
Here is an example:
proc helloWorld {} {
puts stdout [appendArgs "Hello World - " [info script]]
}
helloWorld
# <<CERTIFICATE-1.0>>
# <?xml version="1.0" encoding="utf-8"?>
# <!--
# Eagle Enterprise Edition Script Certificate
#
# The format of this file is proprietary and may not be reverse
# engineered.
#
# This certificate file is subject to the terms of the license agreement
# located at:
#
# https://eagle.to/enterprise/license.html
#
# By using this file and/or the associated software, you agree to abide
# by the terms of the license agreement.
#
# PLEASE DO NOT EDIT THIS FILE.
# THE ASSOCIATED SOFTWARE MAY NOT WORK PROPERLY IF THIS FILE IS ALTERED.
# -->
# <Certificate xmlns="https://eagle.to/2011/harpy"
# xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
# xmlns:xsd="http://www.w3.org/2001/XMLSchema">
# <Protocol>None</Protocol>
# <Vendor>Mistachkin Systems</Vendor>
# <Id>f6377aa9-70f4-4740-919e-47d5b271a039</Id>
# <HashAlgorithm>SHA512</HashAlgorithm>
# <EntityType>Script</EntityType>
# <TimeStamp>2016-09-29T03:47:15.5664062Z</TimeStamp>
# <Duration>-1.00:00:00</Duration>
# <Key>0x107cdfbbd26112c9</Key>
# <Signature>
# IpGUBFvchP6NAJ/hSuXldCZjFhonAUJ3B0HU7vqyNQi4XxjaqUvoMC1NdmZewwc/dje8hw6hQmi+
# AZUkOhhjkt091PU4m4IoVxMj3iIQxLVVuPkYXTwtq1HNbYwvQBIqG5gbM3TCHDkaF9hB3dt2iyzq
# SWDIyiSQWN0yaAz/sGtayU5ik5O1SOkgeenOcbwy70yBQd8lseHY/M8vD4zs2TNvhBTMmurW56iR
# DtgsCmUR0PyOHNKkyXM/fawzt4s5sBcofMmakNy8OfDmt7lGs6Y9/+HFEwWPRE00S22AHbix9VLh
# 0SsoLbCWiNoUVA2mKimV7DaqmcR5y23lgY4j6Q==
# </Signature>
# </Certificate>
# <</CERTIFICATE-1.0>>