logo WinWrap®

WinWrap® Basic Certificates

WinWrap® Basic v10 uses certificates to authorize actions during the design of the application and execution of scripts.

Authorized Action

The primary function of a certificate is to authorize an action:
Action Occurs when...
Design a BasicIdeCtl control is placed on a form while using Visual Studio. (The COM/.NET licensing model and Visual Studio enforce this requirement.)
Run any Basic object or control is created by the executing Windows application.
Edit/Debug a BasicIdeCtl control or BasicIdeObj object is created by the executing Windows application.
CheckPassphrase a developer uses the '#EditingCert or '#ViewingCert comment.
Encrypt a developer uses the '#EncryptingCert comment. (The application's certificate must have the Encryption option.)
Decrypt an end-user executes an encrypted script. (The application's/server's certificate must have the Encryption option.)

Developers, End-Users and Certificates

WinWrap® Basic application developers are required to have one Development certificate installed on their development machine.

Your WinWrap® Basic host application is deployed on the end-user's machine with the appropriate Application, Azure Website or Server certificate.

Windows Application Certificate

application
  • Each installation uses the same certificate.
  • Allows a host application to Run/Edit/Debug WinWrap® Basic scripts. A Windows Application certificate is specific to a particular application name. On 32 bit systems both AppName.exe and AppName32.exe match. On 64 bit systems both AppName.exe and AppName64.exe match. The AppName may contain <Win32:abc> or <Win64:xyz> which is a general method for defining different 32 and 64 bit application names. (e.g. MyProgram-<Win32:x86><Win64:x64> matches MyProgram-x86 for Win32 and MyProgram-x64 for Win64.)
  • Only the actions authorized by the certificate are allowed. If a Development certificate exists, its characteristics limit the actions authorized.
  • This certificate does not expire on an end-user's computer.

Azure Website Certificate

azure
  • Allows an Azure Website to Run WinWrap® Basic scripts using WinWrap® Basic - For Azure Websites. The website's host name must match the certificate's host name.
  • Only the actions authorized by the certificate are allowed. If a Development certificate exists, its characteristics limit the actions authorized.
  • This certificate does not expire on an azure website.

Server Certificate

server
  • Each installation of the host server application uses the same Server certificate.
  • Allows a host server application to Run WinWrap® Basic scripts.
  • A Server certificate is specific to a particular server application name. (A server application name may be wildcarded.) On 32 bit systems both AppName.exe and AppName32.exe match. On 64 bit systems both AppName.exe and AppName64.exe match. The AppName may contain <Win32:abc> or <Win64:xyz> which is a general method for defining different 32 and 64 bit application names. (e.g. The AppName 'MyProgram-<Win32:x86><Win64:x64>' matches 'MyProgram-x86' for Win32 and 'MyProgram-x64' for Win64.)
  • Only the actions authorized by the certificate are allowed. If a Development certificate exists, its characteristics limit the actions authorized.
  • A Server certificate does not expire on an end-user's computer.

Development Certificate

development
  • Each development machine requires a specific Development certificate. A Development certificate is specific to a computer name. The certificate authorizes compilation.
  • Allows a developer to work with WinWrap® Basic until the Development certificate expires.
  • If no Application/Server certificate is involved, an application can Run/Edit/Debug WinWrap® Basic scripts.
  • A Development certificate does expire.

Advanced Certificates

Developers interested in protecting scripts which contain intellectual property can use Permission, Encryption and Decryption certificates.

Permission Certificate

permission
  • A Permission certificate can only be used in conjunction with a Development certificate.
  • Allows an application to protect scripts when a developer provides the Permission certificate's passphrase.
  • A developer utilizes a Permission certificate by adding one of these two comments
    '#EditingCert CertKey ["Prompt"]
        '#ViewingCert CertKey ["Prompt"]
    to a script.
  • The Development certificate characteristics limit the actions authorized.
  • A Permission certificate does expire.

Encryption Certificate

encryption
  • An Encryption certificate can only be used in conjunction with a Development certificate.
  • Allows an application which has the Encryption option to encrypt scripts when a developer provides the Encryption certificate's passphrase.
  • A developer utilizes an Encryption certificate by adding this comment
    '#EncryptingCert CertKey ["Prompt"]
    to a script.
  • The Development certificate characteristics limit the actions authorized.
  • An Encryption certificate does expire.

Decryption Certificate

decryption
  • Each installation uses the same Decryption certificate.
  • Allows an application which has the Encryption option to decrypt scripts.
  • A Decryption certificate does not expire on an end-user's computer.
  • A developer utilizes a Decryption certificate by adding
    '#EncryptingCert CertKey ["Prompt"]
    to a script.
  • If a Development certificate exists, its characteristics limit the actions authorized.
  • A Decryption certificate does not expire on an end-user's computer.

Certificate Details

Developers Only Developers and End-Users
Certificate Kind Development Permission Encryption Decryption Application Server
Test Test
Reconfigurable No2 No2 No2 No2 No2 Yes3 No2 Yes3
LicenseKey Yes4 Yes4 Yes4 Yes4 Yes4 Yes4
Secret No No No No Yes5 Yes5
Computer Name Yes6 No No No No No
Application Name No No No No Yes7 Yes7
Passphrase No Yes8 Yes8 No No No
EncryptionKey No No Yes9 Yes9 No No
Platform All No No No Yes10 Yes10
OS All No No No Yes11 Yes11
Option Yes12 No No No Yes13 Yes13
Designing Yes14 No No No No No
Running Yes15 No No No Yes15 Yes15
Editing/Debugging Yes16 No No No Yes16 No
Expires Yes18 Yes18 Yes18 Yes19 Yes19 Yes20 Yes19 Yes20
Revokable Yes21 Yes21 Yes21 Yes21 Yes21 No Yes21 No
Redistributable No No No Yes Yes No Yes No
  1. An evaluator automatically receives a link for downloading an Evaluation certificate.
  2. A Development/Application/Server certificate is issued by Polar based on the type of certificate purchased.
  3. The developer issues the certificate via the Certificates web page.
  4. Non-Evaluation certificates are associated by the LicenseKey.
  5. The Secret is 128 bit number.
  6. The Computer Name must match the executing computer's name.
  7. The Application Name must match the executing application's name (not path). On 32 bit systems both <AppName>.exe and <AppName>32.exe match. On 64 bit systems both <AppName>.exe and <AppName>64.exe match.
  8. The Passphrase is encrypted.
  9. The EncryptionKey is encrypted and shared by an Encryption-Decryption certificate pair.
  10. The Platform must match the executing platform. Encoded as a bit field.
  11. The OS must match the executing OS. Encoded as a bit field.
  12. The Option(s) enabled. Adds to the set enabled by the Application/Server certificate. Encoded as a bit field. (All options are enabled when the Secret is null.)
  13. The Option(s) enabled. Encoded as a bit field.
  14. Designing with WinWrap® Basic components in Visual Studio is allowed.
  15. Running WinWrap® Basic code is allowed.
  16. Editing/Debugging WinWrap® Basic code is allowed.
  17. Expires 60 days after creation.
  18. Expires 14 months after the date of the last paid annual fee on all machines.
  19. Expires 14 months after the date of the last paid annual fee on a development machine. Does not expire on an end-user machine.
  20. Expires 30 days after creation on all machines.
  21. A certificate is revoked, if it is listed in the compiled "revoked list". (The revoked list is generated from the cert table based on the CertRevokedDate field.) When revoked, execution fails on all machines. Previous versions of certificates can be revoked also.

When viewing a certificate (HTML) the web page displays the cert record info for the Key. If the certificate information does not match the cert record then an "invalid certificate" is displayed.

Certificate File Location and Usage

  1. The Root directory for all certificates depends on the OS:
    • Win32: Program Files\Polar Engineering\WinWrap Basic\
    • Win64: Program Files (x86)\Polar Engineering\WinWrap Basic\
  2. Evaluation certificate:
    • File: Evaluation.htm.
    • Directory (Win32/Win64): The installation directory.
  3. Development/Permission/Encryption certificates:
    • File (Development): Development-<CertKey>.htm or Development.htm.
    • File (Permission): Permission-<CertKey>.htm.
    • File (Encryption): Encryption-<CertKey>.htm.
    • Directory: Root\DesignCertificates.
  4. Application/Server/Decryption certificates:
    • File (Application): Application-<CertKey>.htm.
    • File (Server): Server-<CertKey>.htm.
    • File (Decryption): Decryption-<CertKey>.htm.
    • Directory (search):
      1. Application's directory.
      2. WW10_[32W|64].DLL's directory.
      3. Root\Certificates.
    • The CertKey value must match <CertKey> in the file's name.
  5. Test Application/Server certificates:
    • File (Application): Application-<CertKey>.htm.
    • File (Server): Server-<CertKey>.htm.
    • Directory: Root\TestCertificates.
    • The CertKey value must match <CertKey> in the file's name.
  6. Reissued certificates retain the same CertKey. Once a certificate is created, it retains the same CertKey for its entire life.
  7. When a developer distributes WinWrap Basic, the developer must install their Application/Server/Decryption certificates to the appropriate directory using the downloaded certificate (htm) files.
  8. Creating a "licensed component" (resident on a Form) uses the stored Secret property. These certificates are used:
    • null Secret: A valid Development/Evaluation certificate.
    • non-null Secret: The certificate of the form Application-<CertKey>-*.htm or Server-<CertKey>-*.htm is checked using the Secret. (Where <CertKey> is indicated by beginning part of the Secret.) A Development certificate can circumvent authorization.
  9. Creating an "unlicensed object" (not resident on a Form) at run-time requires an Initialize method call. The Secret property must be set prior to calling Initialize. During the Initialize call the same rules as are applied as when creating a "licensed component".

Validating a Certificate and Authorizing an Action (host application's secret is null)

  1. The Design, Run, Edit/Debug and Option actions uses the DesignCertficates\Development-*.htm or DesignCertficates\Development.htm certificate. If that's not found, the Evaluation.htm certificate is used.
  2. If the certificate is expired or revoked, the action is not allowed.
  3. If the Development certificate is revoked, the action is not allowed.
  4. If no authorizing certificate is found, the action is not allowed.

Validating a Certificate and Authorizing an Action (host application's secret is not null)

  1. The certificate is validated using Polar's public 2048 bit RSA key and the Secret. (Evaluation/Development certificates have a null Secret.)
  2. The certificate considered must meet the criteria of the certificate (e.g. Computer Name, Application Name, Platform and correct OS).
  3. If the certificate is revoked or expired and a Development certificate is found, the action is not allowed.
  4. If no authorizing certificate is found, an unexpired Evaluation certificate is the authorizing certificate.
  5. If no authorizing certificate is found, the Development certificate with the same LicenseKey limits the number of days left of the authorizing certificate.
  6. If the Development certificate is expired or revoked, the action is not allowed.
  7. If no authorizing certificate is found, the action is not allowed.

Reissued Certificates (non-Test certificates only)

The reissued list is generated from the cert table based on the ReissuedVersion field. A certificate with Version less than the ReissuedVersion is ignored. Developers cause certificates to be reissued.

Each time a certificate is signed its Version is incremented. A certificate's ReissuedVersion changes to the current Version if any of it's characteristics are changed in such a way that the new certificate authenticates differently from the old certificate. (Examples: changing the application name, platform, OS or option.)

Changing the certificate's expiration date does not change ReissuedVersion.

Revoked Certificates (non-Test certificates only)

The revoked list is generated from the cert table based on the CertRevokedDate field. When revoked, execution fails on all machines. Polar Engineering revokes certificates.