P1735VisibilityManagement < P1735

P1735 Web>P1735GroupPrivateWorkspace>P1735VisibilityManagement (2010-07-26, JohnShields) (raw view)EditAttach
---+!! %TOPIC%

---++!! Table Of Contents

%TOC%

Back to [[#Table_Of_Contents][Table Of Contents]]

---+ Introduction

The ability to control what is visible and when it is visible in a protected HDL description is a basic mechanism that IP authors need. This proposal clarifies the definition of the existing mechanisms and provides clearer semantics about their use. In addition, new mechanisms are defined that provide flexibility for IP authors to make their IP more or less usable within tools, where visibility of information is the concern.

---+ Background

There is a description of the kinds of visibility problems that exist today and the general approach that should be used to solve them. This [[P1735VisibilityOverview][high level discussion]] is useful background.

---+PLI (VPI/VHPI/...)

Visibility matters when it comes to C code that uses the HDL information model.  If you can "see" everything, you can write a decompiler using VPI with SV or VHPI with VHDL.  Those APIs and  the information models they work with carry protection attributes and a have a default visibility in protected regions that prevents that from happening.  This proposal does not explore the details behind that currently, nor does it propose any visibility management features that directly affect PLI.  What is missing is a meaningful definition of use cases for PLI that require more visibility to be provided.  When the IP stakeholders provide them ( if there are any ), this proposal can be extended to address PLI.  It is likely that the details will have to be taken up by PLI experts in SV and VHDL. -- Main.JohnShields - 2010-07-26

---+ Granularity of protected envelopes in HDLs

Encryption envelopes define a protected region and are used to control visibility in a body of HDL code. The current definition in both SV and VHDL is that protect pragmas that define these envelopes can be placed between any tokens in the language. As such, one can protect an arbitrary subset of any HDL description with granularity down to an individual token. Judiciously applied, it suggests any desired partition between fully visible and protected is possible and supportable by using some number of disjoint encryption envelopes. That comes with a high degree of touch labor on the HDL src code. It is also ill-specified and not interoperable.

---++ HDL LRM aspects

There is a fundamental problem that must be addressed that will limit this granularity. The relationship between a protected subset and its surrounding HDL does not have an adequate semantic definition. It will be unknown to the IP author what effect his protection will have. It may imply an information model be maintained during analysis, elaboration, or runtime that adversely affects performance or capacity. The spirit was good, be flexible and expect protection will want to be used in ways that aren't anticipated. However, this is a case where not having restrictions hurts rather than helps. The SV and VHDL standards must define:
   * a granularity that is supportable
   * rules for granularity which, when violated, will cause a semantic error
   * when semantic checking of granularity happens

It is out of scope for P1735 to define language specific rules for what is legal granularity. We suggest:

   * owner is HDL working group, not p1735
   * granularity should be expressed in the formal information model for VPI and VHPI and encryption envelopes enclosing finer granularity will be illegal, ignored, or considered to cover the entire protectable aspect of the model
   * protection of a subset of a single decl or stmt would not be allowed
   * careful consideration of individual decls within container decls like SV classes
   * for interoperability, a conservative definition of granularity based on known use cases is better

It would be ideal if encryption tools were required to check granularity rules. That is directly contradicted in the HDL LRMs, where encryption tools are expected to ignore the HDL text. It is required that decryption tools check these rules and it would be ideal if these checks were enforced as syntax errors so that they would be detected as early as possible. A IP author that doesn't analyze their protected IP with a compiler before shipping deserves the bad reputation it will give them if granularity errors exist.

---++ Recommended granularity

The language specific rules are a foundation. Given a better definition of legal use within the language, the IP author still needs recommendations on how to use granularity of protected envelopes and tool vendors need to know what support is expected. P1735 recommendations are generally more restrictive than what is legal. They are defined by a practical use case the IP author understands. The candidate use cases are:

* design unit granularity - Only whole packages, package bodies, entities, architectures, configurations in VHDL can be protected. In SV, the equivalent model for packages, modules, programs, etc. It is a simple model and fits a common use case for protecting entire libraries of components. It is compatible with encryption tools that support an encapsulation use model. In this scenario, an entire src file or set of src files are protected with protection defined externally and with behavior that is equivalent to protecting each design unit individually with the same directives.

* package declaration granularity - Individual data or subprogram declarations may be protected within declarative regions of either HDL's packages. This allows a package to be constructed with some data and subprograms hidden from the user. The use case at a high level is to allow private extension to otherwise public or standard libraries. This may be an advantage to IP authors and tool vendors. A caution is that some likely restrictions will exist on the declarative regions in which this could be allowed in the language standards.

* general declaration granularity - Some likely legal restrictions will exist on the declarative regions in which this could be allowed in the language standards.

There are other visibility use cases, but solving them with disjoint encryption envelopes is a poor use of granularity. For example, the ports and parameters of a design unit represent the interface to that design unit. Instantiation of protected design units is a basic use case. This would requires too much touch labor to express with a disjoint encryption envelope. There is no evidence that anyone supports that or wants that today (but it just works). A better way to support it is defined below.

P1735 recommends only design unit granularity be used by IP authors. The potential for elaboration issues and structural overhead with declaration granularity should be sorted out in the language working groups first before finer granularity is recommended.

---++ Relationship of disjoint protected regions

Given that granularity is employed by an IP author, there is no defined relationship between 2 distinct protected regions. Whether they were created by the same author is unknown. Whether they were created in the same execution step of some encryption tool is unknown. They may or may not have all the same protection attributes in common including enabling the same tools or users to use them. There is nothing formalized that ties 2 protected regions together that provides a privilege to access information from one region by another region.

Is that a problem? One school of thought is, yes, of course! How can reasonable references between them work while at the same time protecting against other references? The defacto behavior, however, is that all reasonable references work today and there is no known conflict between what is reasonable and other references. If that changes, one could restrict what is reference-able and/or when. A mechanism to associate a secure and verifiable signature with each region would be then required to authenticate that two disjoint regions are allowed open access to each other. This proposal doesn't propose any such mechanism because it is believed to be unnecessary.

There is no special relationship between disjoint protected regions and none is required.

---+ The visibility directive

The visibility directive defines classes of visibility that apply to an encryption envelope. There is some interaction with decisions on granularity and here we assume only DU granularity. The use cases to be satisfied are:

   * everything shall be visible during analysis for error/warning messages associated with IP user's code that references protected IP. The message may include pathnames to objects, source text references(i.e., file and line number info) into protected IP. This improves understandability of such messages and the ability for the IP author to provide support. Original source text must remain protected and cannot, for example, be displayed to add additional context. The concept is that this level of information does not compromise protection.
   * everything can be referenced for elaboration of the user's model only, though the IP remains protected. It starts with using information provided out-of-band, in user documentation of the IP, for example. If you don't know how to reference the IP, tools are still not allowed to provide mechanisms to browse or review it. This supports instantiation, definition and override of parameter values, elaboration of hierarchical references, binding of assertions, SDF annotation, UPF power-aware model processing, etc.
   * runtime access to protected interface objects, e.g., ports of protected IP that are instantiated in IP user code, which can be logged and inspected. The user clearly knows and references these objects for instantiation and can look at objects connected to interface objects. The ability to reference these objects at runtime is a convenience issue and exposes nothing new.
   * everything visible at runtime for the purpose of error and exception handling that involves protected IP. The produced messages may include pathnames to objects, source text references(i.e., file and line number info) with protected IP to improve understandability and ability for IP author to provide support. Original source text must remain protected and cannot, for example, be displayed for additional context. The concept is that this level of information also does not compromise protection.

The general nature of all these visibility use cases is to preserve protection of IP from reverse engineering while providing expected visibility or increasing usability. Defacto behavior today provides some of this visibility, but at the discretion of individual tools.

The proposed rough syntax is:

*`pragma protect visibility_class* = (vclass {, vclass} ) , *phase* = ( vphase{, vphase} )

vclass ::= ANY_NAME_REFERENCE | INTERFACE_NAMES | ERROR_REPORTING

vphase ::= NONE | ANALYSIS | ELABORATION | RUN | ALL

Note: No problem with changing the syntax to use string_literals to be consistent with the way the LRMs define pragmas or any other reasonable improvement.

The following classes are defined:

   * ANY_NAME_REFERENCE - any object name may be referenced in the associated phase
   * INTERFACE_NAMES - any interface name (port, parameter, or design unit) may be referenced in the associated phase
   * ERROR_REPORTING - object names and source text references may be employed in any error reporting in the associated phase. No original source text declarations or statements may be reproduced.

The following phases are defined:
   * NONE - disables the visibility class for all phases
   * ANALYSIS - enables the class for local analysis or compilation
   * ELABORATION - enables the class for elaboration and loading of a design prior to running, e.g., simulating, synthesizing, etc.
   * RUNTIME - enables the associated class for running, e.g., simulating, synthesizing, etc.  For example, if name references are allowed at runtime for simulation, this implies access to the objects for querying or setting values, etc. 
   * ALL - enables class for all execution phases

The visibility class pragma is an attribute of the encryption or decryption envelope it is associated with. Separate visibility_class pragmas are processed in order of appearance to compose a specification of visibility over the execution phases. The union of all the visibility pragmas defines the visibility, except when the phase is NONE, which means that visibility class is removed in all phases from the specification being composed.

More details may be necessary about the interaction of class and phase.  The basic idea is that if an object is visible, it can be referenced by the IP user in their HDL code and tool commands.  It remains a high level responsibility of the tool not to provide features that show source code of the protected model or would allow the user to infer it.

These visibility classes and phase names may be extended in the future, but the above definition is required to be supported by all tools.  There is nothing that prevents classes or phases to be defined that are specific to particular kinds of tools, but there is strong goal to standardize the definitions and expect interoperability.

---+ The viewport directive

This is a detailed mechanism for visibility that involves explicit specification of objects and the nature of their visibility. It involves heavy touch labor on the IP author to employ it. The current definitions in SV and VHDL are inconsistent. The VHDLViewportDirective is portable and rigorous. Object specification is tied to the formal information model defined by VHPI. The SVViewportDirective is not in any way portable. Neither has any concept of execution phases, but appear to be focused only on runtime objects that have values.  

Recommend to keep the viewport idea and extend it to be applicable to execution phases. It should be able to apply a class of visibility defined above to one particular object. It does go beyond that visibility model by distinguishing permitted runtime operations. It doesn't address any fine tuning of error handling. I doubt that is needed and I don't know of a portable way fine tune the visibility for specific error messages. This needs work on the details after agreement on the direction we should take.

---+ The default visibility model

I thought SV said something about the tool's obligation to protect. It is not in clause 34 (which normative) or in Appendix O. There is something to be extracted from the VPI formal information model - TBD. The VHDL LRM makes a high level normative statement about DecryptionToolProtectionRequirements.

The new default will be equivalent to visibility_class=(ANY_NAME_REFERENCE), phase = (ANALYSIS, ELABORATION) and visibility_class=(ERROR_REPORTING), phase = (ALL)

This covers the main use cases that need visibility and meets expectations for name reference resolution prior to runtime without revealing anything. There is a fair amount of defacto behavior in tools today for this kind of name resolution, but it is at the discretion of the tool vendor. The default also enables reasonable tool error handling. The defacto behavior today is to provide obscure to useless messages to comply with the high-level intent to hide information as much as possible. No doubt specific useless errors have been improved as needed. The whole aspect of error handling in protected regions was ill considered in the LRMs.

---+ Other considerations

   * We may have to consider use cases in which the goal is to protect the identity of the IP provider in 3rd party supply chains of IP. The main IP provider brings branding, sales and support channel, and perhaps licensing. A specialty 3rd party provider may actually own the IP. Either party may bound the other not to disclose their identity and the identity may be inferrable in error reporting, for example. Obfuscation techniques applied directly to the unprotected src code before encryption may be the best answer here.

   * rights management, when finally proposed, may wish to incorporate these pragmas into a rights block as an option, rather than grant them to all tools or users. It would be a completely orthogonal concern. It may also give rise to a few more nit picky visibility classes including proprietary ones than only particular tools know how to process.  An IP user should have a right to know that one tool has a favored status over another and is allowed to do things that another tool may be capable of doing, but merely not privileged to do.  That will have to be taken up in the rights management definition as well as here.

* A suggested concept from one of the synthesis tool stakeholders is abstraction visibility - A synthesis tool may normally report information such as "found a counter, etc. here is what we are doing with it". This a detailed trace of its behavior, but not directly making HDL visible. Some IP authors may wish to explicitly enable or disable this kind of visibility.

* Are there other tool outputs of a similar nature,.e.g, coverage reporting, in which tool vendors need detailed visibility guidance? Is it reasonable to provide recommendations at high level, but unreasonable to require visibility controls?

---+ Summary

With a visibility model clearly defined, there is much less need for tool vendor interpretation of details. With that, there is more confidence that the real intent of the IP author has been expressed.

IP authors can make an informed decision about how paranoid they wish to be about protection and still provide the visibility they want to achieve. There is a better balance of visibility control for the encapsulated model of IP protection that preserves very light to no touch labor directly on the HDL src code. The most paranoid of protection schemes is still allowed with the expectation that an explicit annotation of allowed visibility is then require to accomplish almost anything.

---+ Definitions

TBD

Back to [[#Table_Of_Contents][Table Of Contents]]

-- Main.JohnShields - 2010-07-23
Topic revision: r2 - 2010-07-26 - 18:17:20 - JohnShields
P1735