Security Annotations

A P P E N D I X B

This chapter describes optional security annotations, which can be used by developers to secure their applications. Annotations are very useful when implementing security for many features, including user authentication, secure communication channels, and local encryption.

However, on smart card platforms, application-level security is not always sufficient. Smart cards are widely deployed and they may fall in the wrong hands. This means that, beyond software-based attacks, it is also possible to perform other, physical attacks on cards. Such physical attacks are considered in most smart card risk analyses and countermeasures exist for them. The two most significant categories of such physical attacks are:

Side-channel observation attacks. The attacker observes a side effect of the program's execution in order to determine some properties of the application and/or its data. The most well-known examples are the various versions of power analysis, which can be used to retrieve the values of cryptographic keys.

Perturbation or fault induction attacks. The attacker exploits a property of the silicon media on which all chips are based to disturb the execution of a program and, for instance, skip a part of the execution.

These physical attacks usually target either the confidentiality of sensitive data or the integrity of sensitive code and data. While it is possible to defend against such attacks at the application level, because the attacks target low-level features, such as cryptographic routines, it is easier to implement countermeasures at the platform level.

Some of these countermeasures can be activated continuously, as, for instance, when they can be systematically activated during cryptographic computations. In contrast, some countermeasures cannot be active at all times, especially for an application that manages mostly non-sensitive data. These countermeasures often prove too costly to implement when activating them at all times would result in performance issues.

The set of annotations defined in this chapter allow a developer to declare the security requirements of an application regarding the platform. The objective of such applications is to associate the source code with a set of security requirements that indicate the parts of the code whose confidentiality and/or integrity are particularly sensitive.

More precisely, this set of annotations is visible in the class file, but without mandating any particular behavior at the platform level. The choice of the implementation is left to the platform developer and to the application developer. The annotations are used to define security requirements in an unambiguous way, but they do not mandate any particular kind of countermeasure. Among the possible implementations are to:

Launch some specific mechanisms inside the virtual machine, but with no specific behavior being mandatory. This is what currently happens when each platform provider has, along with the application code, the security policy it wants to enforce. In this scenario, it is up to the platform provider to decide which protections will be run in order to guarantee the policy.

Use an external tool to process the source code and its annotations and perform some transformations that enhance the application code's resistance to attacks.

Use an external tool to process the byte code (because the annotations are visible inside the class file) and increase the code's resistance to attacks in a way similar to the preceding scenario.

These techniques can be used separately, or they can be combined. Standard APIs can be used, or you can rely on proprietary APIs. As mentioned above, there are no constraints on the implementation.

This lack of implementation constraint is possible because these security measures should not modify the nominal behavior of the application. As such, they cannot be tested, because they have no visible effect on the execution of the application. This is why no compliance testing can be defined for this feature, and this is also why interoperability is not the main objective here.

Although security cannot be tested using a functional testing tool, there are standardized test procedures, vulnerability assessments, in which platforms are subjected to attacks by specialized laboratories and must demonstrate their resistance to a given attack level. These standardized procedures are defined in ISO-15408, which defines the Common Criteria for Information Technology Security Evaluation (known as Common Criteria or “CC”). The detailed definition of security levels for CC evaluations is outside of the scope of this document, as it should be included in the definition of a Protection Profile for Java Card-based platforms.

These security annotations allow an application developer to document the basic security requirements of an application by associating confidentiality and integrity requirements to classes and methods. Such annotations are expected to be used in security evaluations of the application to rapidly identify which security-sensitive features were identified. This is particularly important in contexts where composition of evaluations is used, as applications should use the features offered by the underlying platform in order to protect their most sensitive assets.

B.1 Annotations Defined

The required level of security can be defined for a class, for an interface or for a method, but not for a field. If a field is protected, the methods that use the fields will need to perform special operations, and the execution of methods that use these fields will, therefore, need to be adapted accordingly.

B.1.1 Type Annotations

Annotations can be defined for a class or an interface.

B.1.1.1 Class Annotations

By tagging an entire class, you can indicate that a given set of fields are sensitive, together with the methods that handle them. This annotation is inherited. Once a class has been annotated as sensitive, all its subclasses are also considered sensitive.

The following code shows security annotation usage for sensitivity tagging of a class.

CODE EXAMPLE B-1 Class Security Annotation Example
@SensitiveType( sensitivity=SensitiveValue.CONFIDENTIALITY, proprietaryValue="Transit" ) public class TicketBookSIO implements TicketBookSI, TicketBookControlSI { public int getBalance() {...} public int credit(int count) {...} public int debit(int count) {...} public void unblock() {...} }

CODE EXAMPLE B-1 Class Security Annotation Example

@SensitiveType(
  sensitivity=SensitiveValue.CONFIDENTIALITY,
  proprietaryValue="Transit"
)
public class TicketBookSIO implements TicketBookSI, TicketBookControlSI {
		public int getBalance() {...}
		public int credit(int count) {...}
		public int debit(int count) {...}
		public void unblock() {...}
}

B.1.1.2 `SensitiveType(sensitivity=INTEGRITY)`

Tagging a class as sensitive in INTEGRITY indicates that:

Consistency of the data (the fields) of the class is important. If this data is modified outside the scope of the normal proposed services, it could be detrimental to the application, the application user, and/or the application provider.

Consistency of the services (the methods) of the class is important. If these services’ behavior is modified outside the scope of the normal proposed services, it could be detrimental to the application, the application user and/or the application provider.

B.1.1.3 `SensitiveType(sensitivity=CONFIDENTIALITY)`

Tagging a class as sensitive in CONFIDENTIALITY indicates that:

Hiding the data (the fields) of the class from the outside is important. If this data is disclosed outside the application, it could be detrimental to the application, the application user, and/or the application provider.

Hiding the data handling by the services (the methods) of the class from the outside is important. If the data handling by these services is disclosed outside the application, it could be detrimental to the application, the application user and/or the application provider.

B.1.1.4 `SensitiveType(sensitivity=FULL)`

Tagging a class as FULL in sensitivity is equivalent to annotating the class both as sensitive in INTEGRITY and in CONFIDENTIALITY.

B.1.1.5 `SensitiveType(proprietaryValue=”...”)`

Tagging a class with a proprietaryValue value provides additional information that can be used by proprietary tools or the platform to perform more precise tasks. This element can be used by each platform provider to give its own proprietary information and, thereby, improve its tools’ processing or VM execution. This information may be ignored if processing information from another platform provider.

B.1.2 Interface Annotation

Annotations of implemented interfaces have no effect on a class. Nevertheless, the SensitiveType annotation can be used to annotate an interface, in which case, it has just an informative purpose and simply describes the security level that is expected of classes which implements the interface. The effective security annotation is only that defined on the classes which implement the interface.

The following code shows security annotation usage for sensitivity tagging of an interface. The effective security annotation is only that of the TicketBookSIO class given in CODE EXAMPLE B-1.

CODE EXAMPLE B-2 Interface Security Annotation Example
@SensitiveType( sensitivity=CONFIDENTIALITY, proprietaryValue="Transit" ) public interface TicketBookSI { int getBalance(); int credit(int count); int debit(int count); }

B.1.3 Method Annotations

Method annotations are used to tag specific methods as sensitive. Method-scoped annotations cannot be inherited, so every individual sensitive method needs to be annotated as required.

The following code shows security annotation usage for sensitivity tagging of a method. The annotation of the unblock method with sensitivity=INTEGRITY overrides the type annotation with sensitivity=CONFIDENTIALITY of the TicketBookSIO class.

CODE EXAMPLE B-3 Method Security Annotation Example
public class TicketBookSIO implements TicketBookSI, TicketBookControlSI { public int getBalance() {...} public int credit(int count) {...} public int debit(int count) {...} @SensitiveType( sensitivity=SensitiveValue.INTEGRITY, proprietaryValue="Transit" ) public void unblock() {...} }

CODE EXAMPLE B-3 Method Security Annotation Example

public class TicketBookSIO implements TicketBookSI,   TicketBookControlSI {
		public int getBalance() {...}
		public int credit(int count) {...}
		public int debit(int count) {...}
 
		@SensitiveType(
		  sensitivity=SensitiveValue.INTEGRITY,
		  proprietaryValue="Transit"
		)
		public void unblock() {...}
}

B.1.3.1 `SensitiveMethod(sensitivity=INTEGRITY)`

Tagging a method as sensitive in INTEGRITY indicates that consistency of this method is important. If the method’s behavior is modified outside the scope of the normal proposed services, it could be detrimental to the application, the application user and/or the application provider.

B.1.3.2 `SensitiveMethod(sensitivity=CONFIDENTIALITY)`

Tagging a method as sensitive in CONFIDENTIALITY indicates that hiding the data handling by this method from the outside is important. If the data handling by this method is disclosed outside the application, it could be detrimental to the application, the application user and/or the application provider.

B.1.3.3 `SensitiveMethod(sensitivity=FULL)`

Tagging a method as FULL in sensitivity is equivalent to annotating the method both as sensitive in INTEGRITY and in CONFIDENTIALITY.

B.1.3.4 `SensitiveMethod(proprietaryValue=”...”)`

Tagging a method with a proprietaryValue value provides additional information that can be used by proprietary tools or the platform to perform more precise tasks. This element can be used by each platform provider to give its own proprietary information and, thereby, improve its tools’ processing or VM execution. This information may be ignored if processing information from another platform provider.

B.2 Semantics of Annotations

B.2.1 Scope of Annotations

The scope of security annotations is determined at runtime, as follows:

If a method that is declared sensitive in INTEGRITY (respectively CONFIDENTIALITY) runs, then the integrity-preserving (respectively confidentiality-preserving) countermeasures are activated during its execution.

The activated countermeasures remain active until the end of the method's execution, including the execution of any method that is invoked from the method initially declared sensitive. This includes in particular methods from parent classes.

The activated countermeasures remain active until the end of the method's execution, regardless of the way in which the execution ends (method return or exception), unless the countermeasures were already active when the execution started.

The countermeasures are also assumed to remain active during execution of API methods.

The countermeasures are activated separately on distinct threads.

In some cases, the behavior is not defined:

If a field of a class that is declared sensitive in INTEGRITY or in CONFIDENTIALITY is not declared private and is accessed from a method outside of its declaring class, the resulting security behavior is undefined.

Although the scope of the annotations is normally known only at runtime, it is also possible to determine it at deployment time, once the classes of an application have been bundled, by using simple static analysis techniques.

B.2.2 Annotated APIs

Some of the classes and interfaces specified in Application Programming Interface Specification, Java Card Platform, Version 3.0.1, Connected Edition are assumed to be annotated. Because of inheritance, all their subclasses are also considered sensitive. For instance, all Key objects are integrity sensitive, and all SecretKey and PrivateKey objects are also confidentiality sensitive.

B.1 Annotations Defined

B.1.1 Type Annotations

B.1.1.1 Class Annotations

B.1.1.2 SensitiveType(sensitivity=INTEGRITY)

B.1.1.3 SensitiveType(sensitivity=CONFIDENTIALITY)

B.1.1.4 SensitiveType(sensitivity=FULL)

B.1.1.5 SensitiveType(proprietaryValue=”...”)