background image

 

 

D3.3 Collected internal deliverables for year 3

Project number

IST-027635

Project acronym

Open_TC

Project title

Open Trusted Computing

Deliverable type

Report, Prototype
(see page 87/88 of Annex1)

Deliverable reference number

IST-027635/D3.3/1.0

Deliverable title

Collected internal deliverables for year 3

WP contributing to the deliverable

WP3

Due date

M38 (postponed to M42)

Actual submission date

03.06.09

Responsible Organisation

POLITO

Authors

Emanuele Cesena, Davide Vernizzi, Gianluca 
Ramunno, Roberto Sassu (POL)

Abstract

Collection of internal deliverables of WP3 in 
year 3

Keywords

OpenTC WP3

Dissemination level

Public

Revision

1.0

Instrument

IP

Start date of the 
project

1

st

 November 2005

Thematic Priority

IST

Duration

42 months

 

background image

 

 

Collected internal deliverables for year 3

   V 1.0

Introduction:

This Deliverable is a collection of the following internal WP3 Deliverables out of the 
Sub-Workpackages with Nature R (Report) and P (Prototype) within the period of M25 - 
M36:

D03c.3 – TLS DAA enhancement specification

D03c.6 – TLS DAA enhancement OpenSSL design

D03c.12 – OpenSSL engine TLS DAA enhancement

D03c.9 Enhancement of Key Management Adaptation (KMA), which also 
includes:

D03c.10 Adapting IPsec configuration tools and IKE demon source

D03c.11 PKCS#11 source code and documentation

The source code and the binaries of these Deliverables are located on a FTP server. 
The link and the credentials for accessing this FTP server are being sent separately via 
email to both, the EC and the Reviewers.

If you need further information, please visit our website 

www.opentc.net

 or contact 

the coordinator:

Technikon Forschungs-und Planungsgesellschaft mbH
Burgplatz 3a, 9500 Villach, AUSTRIA
Tel.+43 4242 23355 –0
Fax. +43 4242 23355 –77
Email 

coordination@opentc.net

The information in this document is provided “as is”, and no guarantee 

or warranty is given that the information is fit for any particular purpose. 

The user thereof uses the information at its sole risk and liability.

Open_TC Deliverable 3.3

background image

 

 

D03c.3 SSL/TLS DAA-enhancement 

specification

Project number

IST-027635

Project acronym

Open_TC

Project title

Open Trusted Computing

Deliverable type

Internal deliverable

Deliverable reference number

IST-027635/D03c.3/FINAL | 1.20

Deliverable title

SSL/TLS DAA-enhancement specification

WP contributing to the deliverable

WP03c

Due date

Dec 2006 - M12

Actual submission date

May 15, 2009 (second revision)

Responsible Organisation

POL

Authors

Emanuele Cesena, Gianluca Ramunno, 
Davide Vernizzi (editor)

Abstract

This deliverable specifies the enhancements 
to TLS protocol in order to use DAA for group 
authentication.

Keywords

OPEN_TC, TPM, TLS, DAA

Dissemination level

Public

Revision

FINAL | 1.20

Instrument

IP

Start date of the 
project

1

st

 November 2005

Thematic Priority

IST

Duration

42 months

 

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

Table of Contents

1  Introduction.................................................................................................................4
2  The Direct Anonymous Attestation (DAA) protocol.....................................................4
3  Using the DAA for authentication................................................................................5

3.1  Application scenario...............................................................................................5
3.2  Combining TLS and DAA protocols.........................................................................6

4  Enhancing TLS protocol (informative).........................................................................6

4.1  TLS protocol............................................................................................................6
4.2  Hello extensions.....................................................................................................6
4.3  Supplemental data message..................................................................................9

5  DAA-enhanced TLS (DAA-TLS)...................................................................................10

5.1  Overview..............................................................................................................10
5.2  Summary of DAA-TLS capabilities and protocol flow............................................11
5.3  Binding between TLS channel and DAA authentication........................................13
5.4  Verification of the authentication.........................................................................14
5.5  Definition of the hello extension DAAAuthExt.......................................................14
5.6  Definition of the supplemental data entry  DAAAuthSupplDataEntry...................16

6  Specification of TCG TSS/TPM DAA profile for DAA-TLS.............................................18

6.1  Profile requirements and specification.................................................................18
6.2  Prerequisites for using TSS functions for DAA-TLS................................................19
6.3  Nonce and basename generation.........................................................................19
6.4  DAA signature.......................................................................................................20
6.5  Signature verification...........................................................................................21
6.6  Data encoding/decoding.......................................................................................22

6.6.1  Basic data types..............................................................................................22
6.6.2  Complex types.................................................................................................23

6.6.2.1  DAA Signature (normative).........................................................................23

7  Security considerations.............................................................................................24

7.1  Endorsement Key (EK) exposure..........................................................................24
7.2  Basename and DAA signature..............................................................................24

8  IANA considerations..................................................................................................25
9  Final considerations (IPsec and IKE/ISAKMP).............................................................25
10  List of abbreviations................................................................................................26
11  Referenced Documents...........................................................................................26

Open_TC Deliverable 03c.3

2/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

List of figures

Figure 1: Messages exchanged during the TLS handshake protocol...............................7
Figure 2: Supplemental data exchange in TLS handshake protocol................................9
Figure 3: TLS extended to support DAA authentication (DAA-TLS)...............................12
Figure 4: TCG TSS/TPM DAA profile for DAA-TLS: TLS handshake and TSS calls...........19

Open_TC Deliverable 03c.3

3/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

1   Introduction

Secure channels allow two or more entities to communicate securely over insecure 
networks. These channels use cryptographic primitives to provide confidentiality, 
integrity and authentication of network messages. Trusted Computing (TC) technology 
allows to extend the network protection to the peers involved in the communication. 
TC, in facts, allows a platform with TC-enabled hardware to provide cryptographic 
proofs about its behavior. By using this information, the counterpart can be 
guaranteed about the security of the message not only while it is transmitted, but also 
after it is received on the TC-platform.

2   The Direct Anonymous Attestation (DAA) protocol

Direct Anonymous Attestation (DAA) ([6]) is a privacy-friendly protocol that was 
designed to overcome the privacy issues of the Privacy CA (PCA). In particular, the 
main problem related to the use of a Privacy CA, is that it is possible for the privacy CA 
to disclose sensitive data that could allow a third party to link different remote 
attestations made by the same platform and, therefore, breaking the platform's 
privacy. DAA overcomes this problem using a zero-knowledge proof.
In this section is given an overview of the DAA protocol and described how this 
protocol can be used to provide anonymous authentication.
The DAA scheme involves four principals, three mandatory and one optional:

TC-platform equipped with a TPM.

DAA issuer.

Verifier.

A revocation authority. This last entity is optional.

The purpose of the DAA is to convince the verifier that a signature received from the 
TC-platform was made using a genuine TPM, without revealing the actual identity of 
the platform (in TCG architecture the identity of a platform is represented by the 
Endorsement Key (EK) of the TPM).
The DAA is composed of two main protocols: the Join protocol and the Sign protocol.
The Join protocol occurs between the platform and the issuer and results in the TC-
platform receiving a DAA credential, so it can authenticate to verifiers. In details, the 
issuer checks that the platform is equipped with a genuine TPM and, if this is the case, 
issues to the TPM the DAA credentials. This protocol occurs once for a TC-platform and 
has to happen before it can meaningfully interact with verifiers. 
The Sign protocol allows a verifier to decide if a signature received from a TC-platform 
was made using a genuine TPM or not. Unlike with other protocols (e.g. those involving 
the use of an AIK), the verifier does not need to see the actual DAA credential, but the 
proof of the existence of the credentials is provided through a zero-knowledge proof.
In detail, the DAA signature is a group signature that provides the verifier with an 
evidence that the platform belongs to the group of platforms that received the DAA 
credentials from a particular issuer.
DAA provides both complete anonymity and pseudonymity. Complete anonymity 
means that the verifier can only verify if the platform that generated the DAA 

Open_TC Deliverable 03c.3

4/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

signature belongs to the group of platforms that received the DAA credentials from the 
issuer. Therefore each issuer represents a group of platforms, but each platform can 
belong to different groups through DAA credentials obtained from different issuers.
The pseudonymous option allows a verifier to link together different signatures made 
by the same platform. Notably, the verifier can recognize the pseudonym under which 
a particular platform made a signature and link it to previous signatures made by the 
same pseudonym, but it is not possible for the verifier, to link the pseudonym with the 
actual platform.
Furthermore, the DAA signature can selectively provide a zero-knowledge proof on a 
subset of the attributes that belong to the DAA certificate; for instance, it is possible to 
prove that the expiration date of a DAA credential has not been reached, without 
revealing it.
Finally, the DAA protocol allows to use a trusted third party as a Revocation Authority 
(RA). The RA can revoke the anonymity or the pseudonymity provided by the DAA 
credentials under particular circumstances determined by a policy. When the RA is 
used, the platform encrypts its identity using the public key of the RA; the verifier then 
can forward the encrypted identity of the platform to the revocation authority that 
reveals the identity of the platform if the circumstances determined by the policy 
apply.
Note that in this version of the document, neither the attributes nor the revocation 
authority are used.

3   Using the DAA for authentication

It is possible to use the DAA to authenticate a platform, and therefore to authenticate 
its owner, while guaranteeing its privacy. In general, a TC-enabled platform receives 
the DAA credentials from an issuer, and many different verifiers challenge the platform 
to verify if it belongs to the group of platforms that received the DAA credentials from 
that issuer. The TPM guarantees that the DAA credentials cannot be shared with other 
platforms and actually belong to the platform, while the DAA protocol guarantees that 
it is not possible to link one challenge to the actual identity of the platform, thus 
preserving the privacy of the platform.
The DAA signature allows a verifier to authenticate the platform that made the 
signature w.r.t. a group of platforms (i.e. those that received the credentials from a 
particular issuer), and the platform has assurance that it is not possible to link such 
authentication to its real identity.

3.1   Application scenario

A possible scenario for a DAA-based authentication for a service is the following: a 
company wants to allow access to the internal network only to authorized platforms. 
This requirement can be fulfilled using a TPM-enabled platform and the DAA protocol:

1. The company issues a DAA certificate to each laptop before giving it to the 

employee.

2. The company verifies that only allowed platforms (i.e. those that received a DAA 

certificate) access the network with a DAA challenge.

In this scenario, the company is assured that only certified laptops can access the 

Open_TC Deliverable 03c.3

5/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

network, and the employees are guaranteed that the company can not link the 
authentication to their specific platform. The company might also desire to link the 
accesses to different services provided to the remote users. In this case the 
pseudonymous option provided by DAA can meet the requirement.

3.2   Combining TLS and DAA protocols

An implementation of a protocol for anonymous authentication through the DAA 
signature is possible by enhancing the TLS protocol (see [3]) to implement the 
concepts described in section 5. Using the TLS protocol has many advantages: it is 
widely supported, many open source implementations are available and it is possible 
to extend the protocol without loosing backward compatibility.
The latter point in particular is helpful because allows to design a protocol that can be 
used, when a TPM is available, to provide anonymous authentication, but can also 
work on platforms without TC-enabled hardware, thus providing classical 
authentication. Moreover, TLS also provides confidentiality and integrity of the 
messages exchanged on the channel.

4   Enhancing TLS protocol (informative)

4.1   TLS protocol

The Transport Layer Security (TLS) protocol implements a secure channel, namely a 
client/server communication guaranteeing authenticity, integrity and confidentiality of 
the exchanged data. Two main and subsequent phases can be identified: during the 
first one, a 

handshake

 protocol is run by peers to authenticate themselves to each 

other and agree on a session key; then, once the handshake is completed, the 
communication begins and the peers exchange messages over the established secure 
channel.
In Figure 1 a diagram shows the messages exchanged by client and server during the 
TLS handshake.
It is possible to extend the TLS handshake by defining:

1. extensions to the hello messages according to the framework specified in [4]
2. new data units carried over an additional handshake message, called 

supplemental data and specified in [5], which can be exchanged between client 
and the server in both directions 

All definitions recalled in the following are expressed using the Presentation Language 
specified and used in [3].

4.2   Hello extensions

The hello extensions consist of additional data that may be used to add functionalities 
to TLS and are designed to be backward compatible. Indeed the extensions must be 
negotiated: therefore TLS clients supporting the extensions can communicate with TLS 
servers not supporting them and vice versa.

Open_TC Deliverable 03c.3

6/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

The extended client hello message definition is: 

struct {

ProtocolVersion client_version;
Random random;
SessionID session_id;
CipherSuite cipher_suites<2..2^16-1>;
CompressionMethod compression_methods<1..2^8-1>;
Extension client_hello_extension_list<0..2^16-1>;

} ClientHello;

and, symmetrically, the extended server hello message definition is:

struct {

ProtocolVersion server_version;
Random random;
SessionID session_id;
CipherSuite cipher_suite;
CompressionMethod compression_method;
Extension server_hello_extension_list<0..2^16-1>;

} ServerHello;

Open_TC Deliverable 03c.3

7/27

Figure 1: Messages exchanged during the TLS handshake protocol

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

where 

client_hello_extensions_list

 and 

server_hello_extension_list 

represent the new field containing a list of extensions, while the other fields have the 
same meaning as in the base TLS specification ([3]).
Each extension is defined as:

struct {

ExtensionType extension_type;
opaque extension_data<0..2^16-1>;

} Extension;

where 

extension_type

 is (the unique identifier of) the type of the extension and 

extension_data

 contains data specific for the particular extension type.

Clients and servers using the extensions must adhere to the following rules:

1. if the client wants to request the server for extended functionalities, it sends the 

extended client hello message instead of the standard hello message

2. if the server supports the extended functionalities required by the client, it may 

reply with an extended server hello that contains a subset of the extensions 
sent by the client in order to signal to the latter which functionalities will be 
provided

The extended server hello message can only be sent in response to a received 
extended client hello message and cannot contain any extension that was not 
previously requested by the client. The complete definition of the TLS extension 
framework is specified in [4].
Each 

Extension

 must be defined by explicit specification. Five new extensions are 

specified in [4].

Open_TC Deliverable 03c.3

8/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

4.3   Supplemental data message

The supplemental data is an additional message of the TLS handshake, specified in [5], 
to carry extra authentication and/or authorization data units for the application 
establishing the secure channel.
Different data units, called supplemental data entries, can be transferred from server 
to client and vice versa: however, for each direction all supplemental data entries must 
be carried over a single message exchanged during the handshake, as shown in 
Figure 2.
The supplemental data message is defined as:

struct {

SupplementalDataEntry supp_data<1..2^24-1>;

} SupplementalData;

where 

supp_data

 is a list of items defined as:

struct {

SupplementalDataType supp_data_type;
uint16 supp_data_length;

Open_TC Deliverable 03c.3

9/27

Figure 2: Supplemental data exchange in TLS handshake protocol

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

select(SupplementalDataType) { }

} SupplementalDataEntry;

enum {

(65535)

} SupplementalDataType;

Each 

SupplementalDataEntry

 is defined by a unique type (

supp_data_type

) and 

includes the length (

supp_data_length

) and the value 

(

select (SupplementalDataType) { }

).

If present, the 

SupplementalData

 message must contain at least one non empty 

SupplementalDataEntry

 which is then used by the application.

Each 

SupplementalDataEntry

 must be negotiated between client and server via 

specific hello extension; receiving an unexpected 

SupplementalDataEntry

 must result 

in a fatal error, and the receiver must close the connection.
Furthermore, supplemental data entries must not be evaluated during (and interfere 
with) the TLS handshake by the protocol implementation but only at the end of the 
handshake and by the applications.
Each 

SupplementalDataEntry

 must be defined by explicit specification. Supplemental 

data entries can be sent by client and/or server according to their definition. The 
supplemental data message must be sent by either party (client/server) to the other 
one according to which data entries have to be carried in each direction.

5   DAA-enhanced TLS (DAA-TLS)

5.1   Overview

TLS supports different key exchange and authentication methods. 

DH_anon

 key 

exchange implies non-authenticated (i.e. anonymous) TLS sessions. Any other key 
exchange algorithm, instead, implies server authentication being mandatory and client 
authentication being optional.
Enhancing TLS with DAA leads to additional authentication methods. In this document 
the use of DAA is specified only for the client authentication and with 

RSA

 key 

exchange method. Subsequent specifications may define further methods considering 
DAA also for the server authentication and other key exchange methods supported by 
TLS.
In this specification DAA is used to add a group authentication scheme for client, with 
two variants: complete anonymity within the group or use of a pseudonym chosen by 
the verifier to let it link different client authentications made by the same platform 
with specific group credentials (i.e. with DAA credentials released by a specific issuer).
For brevity, in the following the former variant will be referred to as DAA 
authentication while the latter as DAA authentication with pseudonymous (or also DAA 
pseudonymous authentication).
Table 1 summarizes all possible authentication methods for a TLS implementation 
adherent to this specification (i.e. supporting DAA-TLS).

Open_TC Deliverable 03c.3

10/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

Complete anonymous TLS session

Standard TLS with 

DH_anon

 key exchange 

method

Server authentication only

Standard TLS with all key exchange 
methods but 

DH_anon

Client and server authentication

Standard TLS with all key exchange 
methods but 

DH_anon

Group authentication for client and 
standard RSA authentication for server 

DAA-enhanced TLS with 

RSA

 key exchange 

method

Group authentication with pseudonym for 
client and standard RSA authentication for 
server 

DAA-enhanced TLS with 

RSA

 key exchange 

method, pseudonym specified by verifier

Table 1: Authentication methods for DAA-TLS capable client and server

In this document the enhancement of TLS with DAA is specified through the definition 
of a new hello extension and a new supplemental data entry, both expressed using the 
Presentation Language specified and used in [3].

5.2   Summary of DAA-TLS capabilities and protocol flow

DAA is composed of two main protocols: Join where the platform obtains a DAA 
credential from an issuer and Sign where the platform performs a DAA signature and a 
verifier verifies it.
In this specification only the DAA Sign protocol is used to enhance TLS for client 
authentication. The DAA Join protocol is out of scope and not described: it is assumed 
as previously run to obtain the DAA credential required by DAA Sign.
The enhancement defined throughout this section (Section 5) is generic to support any 
specification of DAA; in the next sections, instead, a binding to a particular DAA 
specification and design (i.e. TCG TSS/TPM) is defined.
In this document, the revocation of DAA credentials and revocation checking, whilst 
essential elements for authentication, are not considered as part of DAA-TLS and, 
therefore, not specified, but left to the application.
The DAA Sign protocol involves a platform and a verifier; there roles are respectively 
mapped onto client and server TLS roles. In order to preserve its privacy, the client 
authenticates itself by performing a DAA signature verified by the server.
The protocol flow is:

1. The client starts the TLS handshake by sending the 

ClientHello

 message. The 

latter MUST contain an extension to inform the server that the client is capable 
of using DAA for authentication.

2. If the server agrees on using DAA for client authentication, it replies to the client 

with the 

ServerHello

 message by sending back the same extension. In the 

hello extension, the server also specifies the nonce needed for the DAA 
signature; moreover, if the server wants the client to use DAA authentication 
with pseudonymous, it MUST also specify the basename that the client MUST 
use while performing the DAA signature. If the client does not accept to use the 

Open_TC Deliverable 03c.3

11/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

pseudonym, it MUST terminate the handshake. Otherwise the latter continues 
and the DAA authentication for client with the related variant are then agreed 
on.

3. The server MUST also request the client authentication by sending the 

CertificateRequest

 message. This is needed to bind the TLS session to the 

DAA signature. See section 5.3 for further details.

4. The client performs the DAA signature over a self-signed client certificate and 

sends it to the server using a 

SupplementalDataEntry

 carried over the 

SupplementalData

 message. It also contains all data necessary to verify the 

DAA signature.

5. The TLS handshake protocol continues according to [3] until its completion.
6. To comply with [5], any action caused by the evaluation of the data carried by 

SupplementalData

 MUST be performed after the handshake is completed. 

Therefore, before accepting any data from the channel, the server MUST 
conclude the verification of the DAA signature over the client certificate. This 
operation MUST NOT happen during the handshake, but MUST take place 
immediately after the handshake is completed. If the verification fails, the 
server MUST shut down the TLS channel; otherwise the client is successfully 
authenticated and the data exchange over the secure channel can start.

The TLS protocol extended to support the DAA authentication of the client is shown in 
Figure 3.

Open_TC Deliverable 03c.3

12/27

Figure 3: TLS extended to support DAA authentication (DAA-TLS)

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

5.3   Binding between TLS channel and DAA authentication

In order to complete the client authentication, it is required to provide the binding 
between TLS session and DAA authentication. This is done by the client by DAA-signing 
a client certificate. For the purposes of this specification, the client certificate must be 
a self-signed X.509v3 certificate, DER-encoded, including all extensions required by 
TLS specification [3]. In subsequent specifications, a format for DAA signature 
algorithm for X.509 certificates may be defined in order to replace the self-signed 
client certificate with another DAA-signed. This would imply, however, a revision of the 
DAA-TLS protocol as defined in this document.
The binding is provided as follows:

1. The client MUST create a self-signed certificate with no indication about its 

identity (e.g. with a random distinguished name) for each TLS handshake.

2. The TLS handshake enhanced with hello extensions and supplemental data must 

proceed as described in section 5.1.

3. The server MUST require the client authentication during the handshake by 

sending the 

CertificateRequest

 message. According to [3], the server can 

provide a list of accepted certification authorities (CAs); in this case, the client 
MUST choose a certificate issued by one of these CAs. Because the client self-
generates a new certificate for each TLS connection, the server MUST send the 

CertificateRequest

 message with the field 

certificate_authorities

 empty; 

therefore, according to [3], the client MAY send any certificate.

4. The client must DAA-sign the certificate used for TLS client authentication. This 

provides the binding between the TLS session and the DAA authentication and 
complete the client group authentication. The DAA signature MUST be sent to 
the server through the 

SupplementalData

 message while the self-signed client 

certificate MUST be sent to the server through the 

Certificate

 message.

The DAA protocol MAY also be used to sign other data, in addition to the self-signed 
client certificate used for the TLS authentication. This data, if present, depends on the 
context of the application. The input of the DAA-signing function must be

SHA1 (TLS_Client_Certificate || AdditionalData)

where 

SHA1

 is the digest calculation using SHA-1 [10] algorithm, 

TLS_Client_Certificate

 is the self-signed certificate used for the TLS authentication 

and DER-encoded, 

||

 is the concatenation operator and 

AdditionalData

 represents 

any additional data the application wants to DAA-sign.
An example of possible 

AdditionalData

 to DAA-sign is an Attestation Identity Key 

(AIK) which can be used for a remote attestation of the configuration of the platform; 
in this case the AIK must be signed by the DAA to convince the verifier that the AIK 
was generated and is used by a genuine TPM. This document neither defines the 
encoding of 

AdditionalData

 nor how it is created, but this might be specified in future 

documents.
If no additional data is present, the input of the DAA-signing function must be:

SHA1 (TLS_Client_Certificate)

Open_TC Deliverable 03c.3

13/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

Any additional data DAA-signed MUST be transported within the supplemental data 
message so that it is possible for the verifier to recompute the signed digest.

5.4   Verification of the authentication

The server MUST verify the authentication of the client. This is done by combining the 
different data exchanged during the handshake. 
First, the server needs to check the correctness of the DAA signature. Besides, once 
the DAA signature is verified, it is necessary to verify the binding between the TLS 
session and the DAA authentication. In order to do this, the server MUST verify that the 
digest signed by the client corresponds to the digest calculated over the data 
exchanged during the TLS handshake. This is done by repeating on the server side the 
operations previously done on the client side: concatenating the self-signed certificate 
received from the client through the 

Certificate

 message with the additional data, if 

present, received from the client through the 

SupplementalData

 message and 

computing the digest over these composed data.
Since the 

SupplementalData

 message is sent from client to server before the 

Certificate 

message, the described verification can be done only after receiving the 

latter message. Moreover, according to [5], for security reasons the data exchanged as 
supplemental data MUST NOT have any effect on the handshake and MUST be 
evaluated only after its completion. Therefore the complete verification of the 
authentication MUST be performed only after the handshake is completed and the 
server MUST NOT accept any data from the TLS channel before the verification is 
finished and successful. If the verification fails the server MUST shut down the TLS 
channel.

5.5   Definition of the hello extension DAAAuthExt

This document specifies the 

DAAAuthExt

 hello extension according to [4]. This 

extension indicates the intention to use the DAA authentication of the TLS client. When 
sent by the latter, it means that the client supports the DAA authentication and wants 
to use it for authenticating itself; when it is sent by the server (only as response to the 
client), it means that the server agrees on using DAA authentication for the client. 
This extension is defined as:

enum {
   DAAAuthExt (XX)
} ExtensionType;

struct {

ExtensionType extension_type;
opaque extension_data<0..2^16-1>;

} Extension;

where the type (

XX

) of the extension must be assigned by the IANA through the IETF 

Consensus process (see Section 8 for details). The 

extension_data

 is defined as:

struct {
   uint8

daa_tls_version;

Open_TC Deliverable 03c.3

14/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

   DAAAuthParam

daa_auth_param <0..2^7-1>;

} DAAAuthExt;

struct {
   uint8

daa_auth_param_type;

   opaque daa_auth_param_data <0..2^8-1>;
} DAAAuthParam;

where 

daa_tls_version

 specifies the version of the DAA-enhancement of TLS and 

indicates the set of the 

DAAAuthParam

 to exchange and in which sequence as well as 

the 

DAAAuthSupplDataEntry

 within the 

SupplementalDataEntry

. A DAA-enhancement 

conforming to this specification is identified by the value 1. Each parameter 

DAAAuthParam 

is defined by a type 

daa_auth_param_type

 and a payload 

daa_auth_param_data

 and must appear at most once in the list:

enum {
   daa_error (0),
   daa_binding_version (1),
   daa_nonce (2),
   daa_basename (3),
   (255)
} daa_auth_param_type;

struct {
   uint8

daa_auth_param_type;

   select (daa_auth_param_type) {
      case daa_error: 

DAAError;

      case daa_binding_version: DAABindingVersion;
      case daa_nonce: 

DAANonce;

      case daa_basename: 

DAABasename;

   }
} DAAAuthParam;

struct {
   uint8 daa_error_code;
} DAAError;

struct {
   uint8 daa_binding_version;
} DAABindingVersion;

struct {
   uint8 daa_nonce_length;
   opaque daa_nonce <0..2^8-1>;
} DAANonce;

Open_TC Deliverable 03c.3

15/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

struct {
   uint8 daa_basename_length;
   opaque daa_basename <0..2^8-1>;
} DAABasename;

The semantic of the different parameters which can be carried by 

daa_auth_param_data

 is defined as follows:

DAAError

 indicates an error related to the DAA extension occurred on the peer. 

This specification defines the following error codes:

enum {
   daa_error_disabled (1),
   daa_error_binding_version_not_supported (2),
   (255)
} error_code;

with the following semantic:

1.

daa_error_disabled 

means the server does not accept the DAA extension 

for the current session (note that the server ignores the received DAA 
extension if it does not support it at all, but SHOULD reply with the DAA 
extension if it supports it, but for any reason does not want to accept it).

2.

daa_error_binding_version_not_supported 

means the server does not 

support the binding version requested by the client.

DAABindingVersion

 indicates a specific binding (i.e. profile) for which includes a 

standardized specification of DAA (like the one proposed by the TCG) and the 
specific relations with the DAA enhancement, including the data encoding and 
optionally software interfaces to be used.

DAANonce

 is a DAA's own parameter, the nonce that the client must use during 

the DAA signature. This parameter must be always sent by the server (i.e. the 
DAA verifier).

DAABasename

 is a DAA's own parameter, the basename that must be used 

during the DAA signature. If the server wants the client to have a 
pseudonymous, then this parameter must be present in the 

DAAAuthExt

 server 

hello extension. If the server wants the client to be completely anonymous, then 
the server must not send the basename in its 

DAAAuthExt

 hello extension: at 

the signature time the client must then use a randomly generated basename; 
the client must not ever send the basename in its 

DAAAuthExt

 hello extension.

5.6   Definition of the supplemental data entry 

DAAAuthSupplDataEntry

This document specifies the 

DAAAuthSupplDataEntry

 supplemental data entry, 

exchanged within the supplemental data message, according to [5].
The supplemental data entry must transport all data needed by the server to verify the 
DAA signature performed by the client; therefore, if negotiated, it must only be sent by 
client to server and never in the opposite direction.
The structure of the supplemental data entry for DAA authentication is defined as:

Open_TC Deliverable 03c.3

16/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

enum {
   DAA_auth_suppl_data_entry (XX)
}  SupplementalDataType;

struct { 
   SupplementalDataType supp_data_type;
   uint16 supp_data_length;
   select(SupplementalDataType) {
      case  DAA_auth_suppl_data_entry: DAAAuthSupplDataEntry;
   }
} SupplementalDataEntry;

where the type (

XX

) of the supplemental data entry must be assigned according to [5] 

(see Section 8 for details). The payload of the supplemental data entry, 

DAAAuthSupplDataEntry

, is defined as:

struct {
   DAAAuthSupplDataEntryType

daa_suppl_data_entry_type;

   uint16

daa_suppl_data_entry_length;

   select(DAAAuthSupplDataEntryType) { }
} DAAAuthSupplDataEntry;

where 

daa_suppl_data_entry_length 

indicates the length of the data and 

daa_suppl_data_entry_type

 indicates the type of the data and is defined as:

enum {
   daa_signature (0),
   daa_additional_signed_data (1),
   (255)
} DAAAuthSupplDataEntryType;

struct {
   DAAAuthSupplDataEntryType

daa_suppl_data_entry_type;

   uint16

daa_suppl_data_entry_length;

   select(DAAAuthSupplDataEntryType) {
      case  daa_signature: DAASignature;
      case  daa_additional_signed_data: DAAAdditionalSignedData;
   }
} DAAAuthSupplDataEntry;

struct {
   opaque daa_signature <0..2^16-4>;
} DAASignature;

struct {
   opaque daa_additional_signed_data <0..2^16-4>;
} DAAAdditionalSignedData;

where: 

Open_TC Deliverable 03c.3

17/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

DAASignature

 contains the DAA signature whose encoding depends on the 

value of 

DAABindingVersion

 and it is specified accordingly;

DAAAdditionalSignedData

 contains the additional signed data whose encoding 

depends on the value of 

DAABindingVersion

 and it is specified accordingly.

6   Specification of TCG TSS/TPM DAA profile for DAA-TLS

To have a complete specification for DAA-TLS it is necessary to define a DAA profile, 
i.e. a specific design and data format for DAA; therefore each profile must refer to a 
specific version of DAA protocol, standardized through a specification. The profile is 
build upon such base specification and must define the (sub)set of features defined in 
the base specification to use for DAA-TLS, data encoding/decoding, interactions with 
APIs (if any), and any other aspect relevant to have a complete and interoperable 
specification for DAA-TLS. Depending on the features selected from the base 
specification, when defining a new DAA profile, it might be necessary to add new types 
for 

DAAAuthParam

 and 

DAAAuthSupplDataEntry

 respectively, thus leading to a new 

version of DAA-TLS.
In this section a DAA profile based on TCG TSS [2] and TPM [1] specifications is defined 
for the DAA-enhanced TLS protocol specified in Section 5. This profile is identified by 
the value 1 to assign to 

DAABindingVersion

 carried by a 

DAAAuthParam

6.1   Profile requirements and specification

This profile specifies that all functions and data structures related to the attributes of 
DAA credentials and the Anonymity Revocation Authority (ARA) defined by TSS 
specification [2] MUST NOT be used with DAA-TLS. Future versions of this DAA profile 
may specify the use of such features.
This profile requires a TCG-enabled platform for the TLS client (assuming the 

platform 

DAA role) equipped with a TPM 1.2 [1] and a TCG Software Stack (TSS) version 1.2 
Errata A [2], while the TLS server (assuming the 

verifier

 DAA role) MUST only have 

installed the TSS with the same version as the client.
This profile defines a list of the TSS functions required for DAA-TLS; for each one, the 
function prototype and a summary are included.
This profile also defines the data encoding/decoding rules.
Both the DAA-TLS handshake messages and the interactions (i.e. the function calls) 
with the TSP Interface exposed by TSS are shown in the combined diagram of Figure 4.

Open_TC Deliverable 03c.3

18/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

6.2   Prerequisites for using TSS functions for DAA-TLS

The TSP Interface (TSPI) provided by TSS exposes objects whose instances can be 
referenced through handles. Therefore before using an object it is necessary to create 
it and obtain the related handle. This can be done using specific functions provided by 
TSPI. This profile does not specify which functions must be used: refer to the TSS 
specification [2]. For this DAA profile, the necessary objects are:

TPM object that allows to use the chip functionalities

An object that contains information about the DAA issuer

DAA credentials

Furthermore DAA-TLS requires that the platform (i.e. the TLS client) receives DAA 
credentials from a DAA issuer. This aspect is not covered in this document and it is 
supposed that such credentials are available on the client before the DAA-TLS 
handshake begins.

6.3   Nonce and basename generation

The DAA verifier's nonce and the basename MUST be generated by the server and sent 
to the client via server hello extension; they must obtained by calling the TSS function

TSS_RESULT Tspi_DAA_Verifier_Init

(

Open_TC Deliverable 03c.3

19/27

Figure 4: TCG TSS/TPM DAA profile for DAA-TLS: TLS handshake and TSS calls

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

TSS_HDAA_CREDENTIAL

hDAACredential,

// in

UINT32*

nonceVerifierLength, // out

BYTE**

nonceVerifier,

// out

UINT32*

baseNameLength,

// out

BYTE**

baseName

// out

);

where the first parameter is the handle of the DAA credential; the other parameters 
constitute the output of the function and represent respectively the size of the nonce, 
the nonce, the size of the basename and the basename. 
The nonce MUST be sent to the client as 

Nonce

 as element of the list of 

DAAAuthParam 

carried over the 

DAAAuthExt

 server hello extension.

If the basename is not returned by the function (i.e. 

*baseNameLength

 is set to 0 and 

**baseName

 to NULL), then the 

Basename

 MUST NOT be present as element of the list 

of 

DAAAuthParam

 carried over the 

DAAAuthExt

 server hello extension.

6.4   DAA signature

The client MUST generate the DAA signature over the self-signed TLS client certificate 
and optionally over additional data; the signature MUST be sent to the server via 
supplemental data entry. The signature is generated by calling the TSS function

TSS_RESULT Tspi_TPM_DAA_Sign
(

TSS_HTPM

hTPM,

// in

TSS_HDAA_CREDENTIAL

hDAACredential,

// in

TSS_HDAA_ARA_KEY

hARAKey,

// in

TSS_HHASH

hARACondition,

// in

TSS_DAA_SELECTED_ATTRIB*

revealAttributes,

// in

UINT32

verifierNonceLength,

// in

BYTE*

verifierNonce,

// in

UINT32

verifierBaseNameLength,

// in

BYTE*

verifierBaseName,

// in

TSS_HOBJECT

signData,

// in

TSS_DAA_SIGNATURE**

daaSignature

// out

);

where the parameters are:

hTPM

 is the handle of the TPM object.

hDAACredential

 is the handle of the object holding the DAA credential.

hARAKey

 is the handle of the Anonymity Revocation Authority (ARA) object. If it 

is NULL, then ARA is not used. This profile requires this parameter set to NULL.

hARACondition

 is the handle of the object indicating the conditions under which 

ARA should reveal the pseudonym. This MUST be NULL if 

hARAKey

 is NULL. This 

profile requires this parameter set to NULL.

revealAttributes

 represents the attributes the credential owner wants to 

reveal to the DAA verifier. This profile requires this parameter set to NULL.

verifierBaseName

 and 

verifierBaseNameLength

 are respectively the 

Open_TC Deliverable 03c.3

20/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

basename and its length. If 

Basename

 was not present as element of the list of 

DAAAuthParam

, then 

verifierBaseName

 MUST be set to NULL and 

verifierBaseNameLength

 MUST be set to 0; else the basename MUST be set to 

the value received by the client as 

Basename

 element of the list of 

DAAAuthParam

 carried over the 

DAAAuthExt

 server hello extension.

verifierNonce

 and 

verifierNonceLength

 are respectively the nonce and its 

length. The nonce MUST be set to the value received by the client as 

Nonce 

element of the list of 

DAAAuthParam

 carried over the 

DAAAuthExt

 server hello 

extension.

signData

 is the handle of the object containing data to be DAA-signed to bind 

the TLS session to the DAA authentication; the type of the handle MUST be 

TSS_HHASH

; the data carried by the object MUST be the digest calculated using 

SHA-1 algorithm over the self-signed TLS client certificate (DER-encoded) and, if 
present, additional data. The details of this calculation are specified in section 
5.3.

daaSignature

 is the output of the function, i.e. the DAA signature performed by 

TSS/TPM with the credential handled by 

hDAACredential

, over 

SignData

 using 

the nonce received from the server and the basename either received from the 
server or randomly generated by the client itself at the signature time. 

d

aaSignature

 MUST be sent to the server as 

DAASignature

 element of the list 

of 

DAAAuthSupplDataEntry 

carried over the 

SupplementalDataEntry

. The 

daaSignature 

MUST be encoded in DER format, as detailed in Section 6.6.2.1.

6.5   Signature verification

The server MUST verify the DAA signature received from client through the 
supplemental data. The signature is verified by calling the TSS function

TSS_RESULT Tspi_DAA_VerifySignature
(

TSS_HDAA_CREDENTIAL

hDAACredential,

// in

TSS_HDAA_ISSUER_KEY

hIssuerKey,

// in

TSS_HDAA_ARA_KEY

hARAKey,

// in

TSS_HHASH

hARACondition,

// in

UINT32                

attributesLength,

// in

UINT32                 

attributesLength2,

// in

BYTE**                

attributes,

// in

UINT32                

verifierNonceLength,

// in

BYTE*                 

verifierNonce,

// in

UINT32                

verifierBaseNameLength,

// in

BYTE*                 

verifierBaseName,

// in

TSS_HOBJECT           

signData,

// in

TSS_DAA_SIGNATURE*    

daaSignature,

// in

TSS_BOOL*             

isCorrect

// out

);

where the parameters are:

hDAACredential

 is the handle of the object holding the DAA credential.

hIssuerKey

 is the handle of the object holding the issuer public key.

Open_TC Deliverable 03c.3

21/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

hARAKey

 is the handle of the Anonymity Revocation Authority (ARA) object. If it 

is NULL, then ARA is not used. This profile requires this parameter set to NULL.

hARACondition

 is the handle of the object indicating the conditions under which 

ARA should reveal the pseudonym. This MUST be NULL if 

hARAKey

 is NULL. This 

profile requires this parameter set to NULL.

attributesLength

attributesLength2

 and 

attributes

 are respectively the 

number of attributes revealed by the owner of the DAA credential, the size in 
bytes of each attribute and the list of the revealed attributes. This profile 
requires the first two parameters set to 0 and the last one set to NULL

verifierBaseName

 and 

verifierBaseNameLength

 are respectively the 

basename and its length used for the signature. If the function 

Tspi_DAA_VerifyInit

 previously called by the server returned a basename, 

then 

verifierBaseName

 and 

verifierBaseNameLength

 must be set to 

corresponding values returned by 

Tspi_DAA_VerifyInit

. Instead, if the latter 

returned NULL, then 

verifierBaseName

 and 

verifierBaseNameLength

 must be 

set respectively to NULL and 0.

verifierNonce

 and 

verifierNonceLength

 are respectively the nonce and its 

length used for the signature and must be set to the corresponding values 
returned by the function 

Tspi_DAA_VerifyInit

 previously called by the server.

signData

 is the handle of the object containing data DAA-signed by the client to 

bind the TLS session to the DAA authentication. The type of the handle MUST be 

TSS_HHASH

; this object MUST be created by computing the SHA-1 digest over the 

TLS client certificate (DER-encoded) and, if present, additional data. The details 
of this calculation are specified in section 5.3. 

daaSignature

 is the actual signature to be verified, received by the client as 

DAASignature

 element of the list of 

DAAAuthSupplDataEntry 

carried over the 

SupplementalDataEntry

. The 

DAASignature

 

MUST be decoded from DER 

format, as detailed in Section 6.6.2.1.

isCorrect

 is the function output and indicates if the verification of the DAA 

signature was successful.

6.6   Data encoding/decoding

6.6.1   Basic data types

According to [2], Section 4.3.4.29.10, all DAA-related data structures used as 
input/output to/from TSS are encoded with the big endian (or network order byte) 
format, with the Most Significant Byte at the far left of a multi-byte data unit (e.g. 
buffer or word) and the Least Significant Byte at the far right. Since data structures 
can contain other embedded structures but are, at the end, made up of elementary 
data, also the latter are encoded with the big endian format.
According to [3], Section 4, all data types defined using the Presentation Language for 
TLS (like 

DAAAuthExt

 hello extension and supplemental data entry) and holding multi-

byte values are encoded with the big endian (or network order byte) format.
Therefore converting elementary data as buffers or words from/to TSS encoding 
to/from TLS encoding does not require any adaptation of the order byte but only, if 

Open_TC Deliverable 03c.3

22/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

necessary, the adjustment of the length in bytes.

6.6.2   Complex types

6.6.2.1   DAA Signature (normative)

The DAA Signature, sent by the server as 

DAASignature

 element of the list of 

DAAAuthSupplDataEntry

 MUST be BER-encoded according to the ASN.1 definition of 

the Portable Data specified in the following. This definition is required in this document 
because in Section 3.23 of [2] there is lack of Portable Data definition for DAA 
Signature.
Each member of the TSS structure must be individually re-encoded to BER and vice-
versa. If the member is not an elementary data, it MUST be recursively expanded until 
all elementary data are exposed: then they can be re-encoded as the corresponding 
members for the target encoding rules.
With respect to the DAA Signature structure as defined in Section 3.12 of [2], in the 
following definition the unnecessary fields are not present (including those related to 
the credential attributes, which are not supported in this profile):

DaaSignature ::= SEQUENCE
{

versionInfo

TssVersion,

zeta

INTEGER,

   -- z

capitalT

INTEGER,

   -- T

challenge

INTEGER,      -- c

nonceTpm

INTEGER,      -- nT

sV

INTEGER,

   -- sV

sF0

INTEGER,

   -- sF0

sF1

INTEGER,

   -- sF1

sE

INTEGER,

   -- sE

nonceVerifier

INTEGER,

   -- nV

}

TssVersion ::= SEQUENCE
{

major

INTEGER,

    

minor

INTEGER,

   

revMajor

INTEGER,

    

revMinor

INTEGER   

}

Open_TC Deliverable 03c.3

23/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

7   Security considerations

7.1   Endorsement Key (EK) exposure

TCG design ([1,2]) of DAA protocol gives the verifier assurance about the genuineness 
of the TPM making DAA signatures. By issuing the DAA credentials, the issuer 
guarantees that the TPM is genuine.
To enforce this behavior, once the issuer verified the credentials (e.g. EK certificate) 
provided by the platform requesting a DAA credential, the issuer creates the latter and 
encrypts it with the public part of the Endorsement Key (EK) of the TPM requesting the 
credential. This procedure guarantees that only the TPM owning the private part of the 
Endorsement Key can decrypt, install and use the received DAA credential.
This procedure has the drawback that the issuer gets to know the public part of the EK: 
being unique to every TPM, the EK can be used as a identifier to track TPM operations 
that involve the EK (i.e. requesting other DAA credentials or an AIK certificate). For this 
reason, the issuer must be a trusted third party that guarantees to the verifier that the 
genuineness of the TPM is checked and to the platform the sensitive data (i.e. the 
public part of the EK) are kept secure.
While this is not a problem in the reference scenario (where the company is the 
issuer), it may become a problem in more open scenarios; in these latter cases, the 
platform must carefully choose the DAA issuer.

7.2   Basename and DAA signature

In some scenarios, the basename or the DAA signature may be considered sensitive 
data. For instance, a man in the middle can forge the basename by modifying the 
server hello message. In this case it can persuade the client to make a DAA signature 
over a chosen basename. If the basename was chosen to be fixed, it is possible for the 
attacker to track successive DAA signatures of the same platform over the same 
basename.
The TLS protocol allows both the client and the server to detect the attack, but only 
after the DAA signature was made. This attack can be detected when the finished 
messages are exchanged: these messages contain the hash of all the messages 
exchanged during the handshake; if the attacker modified the server hello, the server 
will compute a hash different from the hash computed by the client, leading to the 
discover of the attack.
Furthermore, by listening to the channel in the case of a pseudonymous 
authentication, an eavesdropper could be able to link together different DAA 
signatures generated by the same platform. Listening on the channel leads the 
attacker to know both the basename and the DAA signature; in the case of 
pseudonymity, these two data are enough to link different signatures made by the 
same platform. Differently from the previous attack, this attack can not be detected by 
the client nor the server and, hence, it puts at risk the privacy of the client.
For these reasons in some scenarios, the data exchanged within the supplemental 
data message must be protected. [5] asserts that such protection must be provided 
through the use of a double handshake. The first handshake is a regular one that only 
aims to the creation of a secure channel. Next, within the secure channel a second 

Open_TC Deliverable 03c.3

24/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

handshake happens; this latter handshake actually carries the hello extensions and the 
supplemental data necessary for the anonymous authentication.
Note that in the case of a double handshake, the first handshake must be done in a 
way that exposes no information about the peer that must be authenticated 
anonymously using the DAA during the second handshake.

8   IANA considerations

The hello extensions and the supplemental data entries are defined by their types. The 
hello extensions types MUST be assigned by the IANA through a IETF consensus 
procedure, while the supplemental data specification allows the use of private types 
for the supplemental data entries.
Because each supplemental data entry MUST be negotiated using the hello extensions 
mechanism, it is not actually possible to use the private types for the supplemental 
data entry defined in this document.
For this reason this document does not defines the types of the hello extension nor the 
type of the supplemental data entry.

9   Final considerations (IPsec and IKE/ISAKMP)

The IKE/ISAKMP protocols are part of the IPsec protocols family and are used to 
authenticate the peers, to negotiate the security services and the keys.
As for TLS protocol, DAA can be used to enhance the Internet Key Exchange protocol 
(IKEv1/ISAKMP and IKEv2) to add a group authentication scheme to preserve the 
platform privacy while using the security protocols of the IPsec family.

Open_TC Deliverable 03c.3

25/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

10   List of abbreviations

Listing of term definitions and abbreviations used in this document (IT expressions and 
terms from the application domain).

Abbreviation

Explanation

AIK

Attestation Identity Key

ARA

Anonymity Revocation Authority

ASN.1

Abstract Syntax Notation 1

BER

Basic Encoding Rules

CA

Certification Authority

DAA

Direct Anonymous Attestation

DER

Distinguished Encoding Rules

EK

Endorsement Key

PCA

Privacy CA

SHA-1

Secure Hash Algorithm 1

TCG

Trusted Computing Group

TLS

Transport Layer Security

TPM

Trusted Platform Module

TSS

TCG Software Stack

11   Referenced Documents

/1/ TCG TPM Main Specification (parts 1,2,3)
July 9, 2007,
Version 1.2 Level 2 Revision 103

/2/ TCG Software Stack (TSS) Specification
March 7, 2007, 
Version 1.2, Level 1, Errata A

/3/ IETF RFC 4346, The Transport Layer Security (TLS) Protocol Version 1.1
April, 2006

/4/ IETF RFC 4366, Transport Layer Security (TLS) Extensions
April, 2006

/5/ IETF RFC 4680, TLS Handshake Message for Supplemental Data
September, 2006

/6/ Direct Anonymous Attestation
Ernie Brickell, Jan Camenisch, Liqun Chen
CCS '04: 11th ACM conference on Computer and Communications Security
2004

/7/ ITU-T Rec. X.208, Specification of Abstract Syntax Notation One (ASN.1)
1988

/8/ ITU-T Recommendation X.690, Information Technology – ASN.1 encoding rules: 

Open_TC Deliverable 03c.3

26/27

background image

 

 

SSL/TLS DAA-enhancement specification

FINAL | 1.20

Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and 
Distinguished Encoding Rules (DER)

1997

/9/ ITU-T Recommendation X.509, Information technology – Open Systems 

Interconnection – The Directory: Public-key and attribute certificate frameworks

/10/ IETF RFC 3174, US Secure Hash Algorithm 1 (SHA1)
September, 2001

Open_TC Deliverable 03c.3

27/27

background image

 

 

D03c.6 OpenSSL engine/DAA enhancement 

design specification

Project number

IST-027635

Project acronym

Open_TC

Project title

Open Trusted Computing

Deliverable type

Internal deliverable

Deliverable reference number

IST-027635/D03c.6/FINAL | 2.00

Deliverable title

OpenSSL engine/DAA enhancement design 
specification

WP contributing to the deliverable

WP03c

Due date

Oct 2007 - M24

Actual submission date

May 15, 2009 (major revision)

Responsible Organisation

POL

Authors

Emanuele Cesena, Davide Vernizzi, Gianluca 
Ramunno

Abstract

This deliverable describes which 
modifications must be done to OpenSSL in 
order to support the anonymous 
authentication made through the DAA 
protocol.

Keywords

OPEN_TC, TPM, TLS, OpenSSL, DAA

Dissemination level

Public

Revision

FINAL | 2.00

Instrument

IP

Start date of the 
project

1

st

 November 2005

Thematic Priority

IST

Duration

42 months

 

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Table of Contents

1  Introduction.................................................................................................................5
2  Architecture overview.................................................................................................5
3  TLS Hello Extensions and Supplemental Data.............................................................8

3.1  Architecture............................................................................................................8

3.1.1  Overview............................................................................................................8
3.1.2  Data Structures................................................................................................10
3.1.3  Workflow..........................................................................................................11

3.2  Application Programming Interface......................................................................13

3.2.1  Interface..........................................................................................................13
3.2.2  Application Interface........................................................................................19

3.3  Examples..............................................................................................................20

3.3.1  Hello World!.....................................................................................................20
3.3.2  Supplemental Data..........................................................................................22

4  Direct Anonymous Attestation..................................................................................24

4.1  Architecture..........................................................................................................24

4.1.1  Overview..........................................................................................................24
4.1.2  Data Structures................................................................................................25
4.1.3  Workflow..........................................................................................................27

4.2  Application Programming Interface......................................................................29

4.2.1  Application Interface........................................................................................29

4.3  Examples..............................................................................................................32

5  TLS DAA-Enhancement.............................................................................................33

5.1  Architecture..........................................................................................................33

5.1.1  Overview..........................................................................................................33
5.1.2  Data Structures................................................................................................34
5.1.3  Implementation Details....................................................................................34

5.1.3.1  Core.............................................................................................................34

5.1.4  Workflow..........................................................................................................35
5.1.5  Other Features.................................................................................................37

5.1.5.1  Support to TLS Sessions Resumption..........................................................37
5.1.5.2  Legacy Mode...............................................................................................37

5.2  Application Programming Interface......................................................................38

5.2.1  Application Interface........................................................................................38

5.3  Example...............................................................................................................39

5.3.1  Common Modifications.....................................................................................39
5.3.2  Modifications on the Client..............................................................................40
5.3.3  Modifications on the Server.............................................................................40
5.3.4  Running the commands...................................................................................41

6  Implementation of the Specification of TCG TSS/TPM DAA Profile for DAA-TLS.........42

6.1  Architecture..........................................................................................................42

6.1.1  Overview..........................................................................................................42
6.1.2  Implementation Details....................................................................................43

6.1.2.1  DAA_METHOD..............................................................................................44

6.1.3  Workflow..........................................................................................................46

6.2  Examples..............................................................................................................48

7  List of abbreviations..................................................................................................49
8  Referenced Documents.............................................................................................49

Open_TC Deliverable D03c.6

2/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

9  Appendix. Code Documentation................................................................................51

9.1  General TLS Extensions framework......................................................................51

9.1.1  Patch................................................................................................................51
9.1.2  Core.................................................................................................................53
9.1.3  Interface..........................................................................................................54
9.1.4  Application Interface........................................................................................54

9.2  Direct Anonymous Attestation..............................................................................54

9.2.1  Implementation................................................................................................54
9.2.2  Method Interface..............................................................................................58
9.2.3  Application Interface........................................................................................60

9.3  TLS DAA-Enhancement.........................................................................................60

9.3.1  Core.................................................................................................................60
9.3.2  Application Interface........................................................................................60

9.4  Engine TPM-DAA...................................................................................................60

9.4.1  TSS Binding Utilities.........................................................................................60
9.4.2  DAA_METHOD..................................................................................................61

Open_TC Deliverable D03c.6

3/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

List of figures

Figure 1: System Architecture Overview.........................................................................6
Figure 2: TLS Hello Extensions and Supplemental Data Overview..................................9
Figure 3: TLS Hello Extensions and Supplemental Data Data Structure........................10
Figure 4: TLS Hello Extensions and Supplemental Data Workflow................................12
Figure 5: Direct Anonymous Attestation Architecture Overview...................................24
Figure 6: Direct Anonymous Attestation Data Structure...............................................26
Figure 7: Direct Anonymous Attestation Sign Workflow................................................28
Figure 8: Direct Anonymous Attestation Verify Workflow..............................................29
Figure 9: TLS DAA-Enhancement Architecture Overview..............................................33
Figure 10: TLS DAA-Enhancement Workflow.................................................................36
Figure 11: Implementation of the specification of TCG TSS/TPM DAA profile for DAA-TLS 
Overview.......................................................................................................................42
Figure 12: TCG TSS/TPM DAA Profile for DAA-TLS Workflow..........................................47

Open_TC Deliverable D03c.6

4/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

1   Introduction

Secure channels allow two or more entities to communicate securely over insecure 
networks using cryptographic primitives to provide confidentiality, integrity and 
authentication of network messages. Trusted Computing (TC) technology extends the 
network protection to the peers involved in the communication. TC, in facts, allows a 
platform with TC-enabled hardware to provide cryptographic proofs about its behavior. 
Using these information, the counterpart can be guaranteed about the security of the 
message not only while it is transmitted, but also after it is received on the TC-
platform.
Among the primitives available to a TC-platform, Direct Anonymous Attestation (DAA) 
[7] is a privacy-friendly protocol that was designed to overcome the privacy issues of 
the privacy CA. In particular, the main problem related with the use of a privacy CA, is 
that it is possible for the privacy CA to disclose sensitive data that could allow a third 
party to link different remote attestation made by the same platform and, therefore, 
breaking the platform's privacy. DAA overcomes this problem using a zero-knowledge 
proof.
In [1], a TLS DAA-Enhancement is proposed to exploit DAA as a mechanism to achieve 
(client) anonymous authentication. Furthermore, based on the Trusted Platform 
Module (TPM) and Trusted Software Stack (TSS), a TCG TSS/TPM profile is specified to 
exploit the DAA-related functions available in the TC technology. This document 
describes an implementation of the TLS DAA-Enhancement, including the TCG TSS/TPM 
profile.

2   Architecture overview

The implementation of SSL/TLS DAA-enhancement as specified in [1] is organized as a 
set of components that act at different layers, beginning from the lower cryptographic 
level, up to the TLS protocol enhancement level. The design through components is 
motivated by:

code modularity: smaller components with a defined interface allow applications 
to select only the required features, avoiding unnecessary growth of their code.

future reuse: components may be shared among other applications or higher 
layer components that exploit the provided capabilities.

support for real-world applications: both DAA-aware and legacy applications 
may exploit the TLS DAA-enhancement to take advantage of the (client) 
anonymous authentication.

security-oriented design: code modularity and reuse, as well as best practice 
and policy for configuring applications, result in an added value with respect to 
the security provided by the code. Furthermore it is possible to expect that 
lower layer components may be integrated in the mainstream libraries, thus 
bringing the code to be publicly shared and evaluated.

OpenSSL supports engines as a way to provide alternative implementations for a 
cryptographic primitive, usually to exploit cryptographic hardware accelerators. 
Engines are used to provide two different implementations of the DAA protocol: the 
first one exploits the TPM/TSS capabilities, the latter is pure software and implements 
a newer version of the protocol [9].

Open_TC Deliverable D03c.6

5/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

The whole implementation has been done and tested with OpenSSL v0.9.9, snapshot 
20081204.
Figure 1 presents the overall architecture.

In more detail:

TLS Hello Extensions and Supplemental Data (TLSEXT) 

is a framework for 

supporting generic TLS Hello Extensions (RFC 4366) [5] and Supplemental Data 
(RFC 4680) [6] into OpenSSL's 

libssl

. Both TLS Hello Extensions and 

Supplemental Data are needed for the TLS DAA-enhancement. The framework is 
intended to help developers who want to add support for new TLS Extensions 
into OpenSSL. This is detailed in Section 3.

Direct Anonymous Attestation (DAA)

 is an interface to implement the Sign 

and Verify algorithms of Direct Anonymous Attestation within the OpenSSL 

libcrypto

. According to the original design of DAA, the interface considers the 

Sign algorithm as a two-parties protocol between the Host and the TPM. The 
interface is designed to provide DAA support in any context 

libcrypto 

is 

available, not only for the TLS DAA-enhancement. A default implementation is 
included; the use of engines allows to override the default implementation. This 
is detailed in Section 4.

TLS DAA-Enhancement (DAA-TLS)

 is an implementation of the TLS DAA-

Enhancement Specification [1] to enhance OpenSSL's 

libssl

. It is build upon 

Open_TC Deliverable D03c.6

6/61

Figure 1: System Architecture Overview

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

TLSEXT and uses primitives offered by DAA. It also provides an interface for 
applications that wants to take advantage of the (client) anonymous 
authentication. Furthermore, a special compile-time option allows building it in 
legacy mode, that allows unmodified applications to exploit the TLS DAA-
Enhancement as well. This is detailed in Section 5.

Engine Implementing the Specification of TCG TSS/TPM DAA Profile 
(Engine TPM-DAA) 

is an OpenSSL engine that implements the TCG Profile of 

the TLS DAA-enhancement, according to [1]. It requires a Trusted Software 
Stack capable of supporting the DAA protocol. As DAA-TLS is implemented 
within OpenSSL, the engine manages conversion between OpenSSL data 
structures and TSS' ones. This is detailed in Section 6.

Engine Implementing the Asymmetric Pairing-based DAA (Engine 
Miracl) 

is an OpenSSL engine that implements a purely software version of 

DAA, according to [9]. This version is based on asymmetric pairing over elliptic 
curves and the engine exploits the Miracl library [10] as a software 
cryptographic accelerator to compute pairing. This engine is not described in 
more detail within this document, but it is included in the architecture to give a 
more comprehensive overview. Furthermore, it is part of the demonstrator of 
the TLS DAA-enhancement.

Application layer

 is the collection of software that demonstrates the use of the 

TLS DAA-enhancement. Modified versions of OpenSSL tools 

s_client

 and 

s_server

 are able to communicate with DAA-TLS through its interface (e.g. set 

platform/issuer credentials). An unmodified version of Apache web server with 
mod_ssl demonstrates the possibility to use the framework with legacy 
applications. The application layer is not described in more detail within this 
document, but it is included in the architecture to give a more comprehensive 
overview. Furthermore, it is part of the demonstrator of the TLS DAA-
enhancement.

Open_TC Deliverable D03c.6

7/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

3   TLS Hello Extensions and Supplemental Data

3.1   Architecture

This is a framework for supporting generic TLS Hello Extensions (RFC 4366) [5] and 
Supplemental Data (RFC 4680) [6]. It is intended to help developers who want to add 
support for new TLS Extensions into OpenSSL.
The framework allows to embed new TLS Extensions into the OpenSSL 

libssl

; this 

feature becomes especially useful when it is required to exploit the framework with 
legacy applications not designed to support the TLS Extensions. Furthermore it is 
designed to let the developers define a new TLS Extension, dynamically load, create 
and handle it at application layer; in this last case, it is possible to support applications 
that were designed to support the TLS Extensions natively.
The framework treats every TLS Extension as an object, with data to be exchanged 
during the handshake and methods that implement the extension logic. Supplemental 
Data are part of such objects, to adhere with RFC 4680:

Information provided in a supplemental data object MUST be intended to 
be used exclusively by applications and protocols above the TLS 
protocol layer. Any such data MUST NOT need to be processed by the TLS 
protocol.

By having this unified view for extensions, it is easy to support once fr all some of the 
requirements imposed by RFCs, for instance RFC 4366:

There MUST NOT be more than one extension of the same type.

In the event that a client requests additional functionality 
using the extended client hello, and this functionality is not 
supplied by the server, the client MAY abort the handshake.

3.1.1   Overview

The code is organized in four main modules, as shown in Figure 2.

Open_TC Deliverable D03c.6

8/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Patch.

 The lower layer contains the changes to the existing code of the 

unmodified 

libssl

 necessary to handle TLS Extensions and support the new 

SupplementalData handshake message.
For simplicity, the patch to the existent code is limited to single function calls, 
which carry out all the necessary computation.
OpenSSL allows to disable all the TLS Extensions at compilation time by defining 
the macro 

OPENSSL_NO_TLSEXT

. This framework extends this concept supporting 

the macro 

OPENSSL_NO_TLSEXT_GENERAL

 which disables the framework at 

compilation time. Moreover, the macro 

OPENSSL_NO_TLSEXT

 automatically forces 

OPENSSL_NO_TLSEXT_GENERAL

.

Core.

 The middle layer contains the data structures and the core functionality.

Open_TC Deliverable D03c.6

9/61

Figure 2: TLS Hello Extensions and 

Supplemental Data Overview

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Interface.

 The upper layer consists in the interface available to programmers to 

write new TLS Extensions (see Section 

3.3

).

Application Interface.

 This module contains portions of the Interface that are 

common to all the TLS Extension and are useful for the application: for instance 
this code offers the possibility for the client to require the use of an extension, 
or abort the handshake if the server ignores it). Even if this code is common to 
all the TLS Extension, it SHOULD NOT be directly accessed by applications, but it 
SHOULD be wrapped by any extension which provide such functionalities to the 
application layer.

3.1.2  

Data Structures

The OpenSSL 

SSL

 object is extended with a 

STACK_OF TLSEXT_GENERAL

.

TLSEXT_GENERAL

 is an object that contains data related to a TLS Extension (in the 

meaning of the general framework) as well as callback functions to implement the 
logic of the extension.
Figure 3 gives an overall idea.

The object has two parts, quite symmetric: one for the Client data and one for the 
Server.
For what concerns data, the two parts will contains data to be sent or received 
depending on the object is instantiated on the client or server side.
In more detail:

type

 is the type of the extension (it must be the same on client and server).

client_data

 is the payload the client will send (and the server will receive) 

through the TLS Hello Extension (ClientHello handshake message).

client_data_length

 

is the length of the payload.

Open_TC Deliverable D03c.6

10/61

Figure 3: TLS Hello Extensions and 
Supplemental Data Data Structure

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

client_supp_data

 

is a stack of 

SUPP_DATA_ENTRY

 objects, each describing in 

TLV (type-length-value) format a supplemental data entry related to this 
extension. The client sends (and the server receives) this data through the 
SupplementalData handshake message.

The same (but symmetric) is for server data.
Callback functions (

client_ext_cb()

client_supp_data_cb()

client_finish_cb()

, respectively for the server) are used to implement the logic of 

the TLS Extension. These are automatically invoked by the framework at the proper 
time (see Section 3.1.3 for more details) and they are only handled on the side the 
object is instantiated, i.e. client's callback functions are handled when the object is 
instantiated on the client while server's callback functions are only handled on the 
server.
Similarly, the context data (

client_ctx_data

, respectively 

server_ctx_data

) to 

exchange information from/to the callbacks, SHOULD be used only on the correct side.
Finally, there are three flags:

client_required

 tells if the client has to abort in case the server ignores the 

extension.

server_send

 tells if the server should send this extension (see Section 3.1.3 for 

more details).

received

 tells if the extension has been received. It is for internal use, both to 

check for duplicates and to have a list of the negotiated extensions.

3.1.3  

Workflow

The workflow of the framework with respect to the TLS Handshake is depicted in Figure
4.

Open_TC Deliverable D03c.6

11/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

1. If the Client registers a 

TLSEXT_GENERAL

 object, then it is sent as part of the TLS 

Hello Extension within the ClientHello handshake message.
The Server, on the contrary, is supposed to register all the 

TLSEXT_GENERAL 

objects it wants to handle

2. When the Server receives the ClientHello, it parses the TLS Hello Extensions and 

- if any is handled by the framework - it invokes the related 

server_ext_cb()

.

This callback is in charge of taking the decision to reply or not to the extension, 
by setting the flag 

server_send

.

3. The Server replies with the ServerHello message containing the accepted TLS 

Hello Extensions, for which the Client invokes the 

client_ext_cb()

.

4. The Client verifies that every extension with 

client_required

 flag set to true 

has been received. If not, it aborts the handshake.

5. For each extension requiring supplemental data on server side, the server calls 

the 

server_supp_data_cb()

 callback function which is in charge of creating the 

supplemental data payload. This data is pushed within the 

server_supp_data 

stack. Finally, if the 

server_supp_data

 stack is not empty, the server 

SupplementalData handshake message is sent.

6. The handshake continues until the ServerDone message.
7. For each extension requiring supplemental data on client side, the client calls 

the 

client_supp_data_cb()

 callback function which is in charge of creating the 

Open_TC Deliverable D03c.6

12/61

Figure 4: TLS Hello Extensions and Supplemental Data Workflow

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

supplemental data payload. This data is pushed within the 

client_supp_data 

stack. Finally, if the 

client_supp_data

 stack is not empty, the client 

SupplementalData handshake message is sent.

8. The handshake continues until its conclusion.
9. After the handshake is terminated the Client (respectively the Server), invokes 

the 

client_finish_cb()

 (respectively the 

server_finish_cb()

), for each 

negotiated extension. These callback functions are in charge of evaluating the 
supplemental data received.

3.2   Application Programming Interface

3.2.1   Interface

These functions are needed by the developers that want to write new TLS Extensions.

TLSEXT_GENERAL* SSL_TLSEXT_GENERAL_new (int 

type

)

Creates a new extension of type 

type

 .

Parameters:

type

 extension type (SHOULD be defined by IANA) 

Returns:

the extension created 

SUPP_DATA_ENTRY* SSL_TLSEXT_GENERAL_client_supp_data_new (TLSEXT_GENERAL 

ext

,   int 

type

)

Creates a new supplemental data entry of type 

type

  and pushes it in the 

Client

  stack of a TLSEXT_GENERAL object 

ext

 .

Parameters:

ext

 TLSEXT_GENERAL object containing the Supplemental Data stack 

type

 extension type (SHOULD be defined by IANA) 

Returns:

the supplemental data entry created 

SUPP_DATA_ENTRY* SSL_TLSEXT_GENERAL_server_supp_data_new (TLSEXT_GENERAL 

ext

,   int 

type

)

Creates a new supplemental data entry of type 

type

  and pushes it in the 

Server

  stack of a TLSEXT_GENERAL object 

ext

 .

Parameters:

ext

 TLSEXT_GENERAL object containing the Supplemental Data stack 

type

 extension type (SHOULD be defined by IANA) 

Returns:

the supplemental data entry created 

int SSL_TLSEXT_GENERAL_init_cb (TLSEXT_GENERAL * 

ext

,   void * 

cb_ptr

)

Sets the init callback function for a given extension.
The callback function will be executed at the moment of the initialization of the 

Open_TC Deliverable D03c.6

13/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

extension.

Parameters:

ext

 extension to associate with the callback 

cb_ptr

 pointer to the callback function 

Returns:

0 success 
-1 error 

TLSEXT_GENERAL* SSL_TLSEXT_GENERAL_init (SSL * 

s

,   TLSEXT_GENERAL * 

ext

)

Initialization function that makes basic checks common to all the extension.
The server extensions are enabled by default, while the client extensions are 
not. It SHOULD be called by the constructor of each extension.

Parameters:

ext

 extension to initialize 

s

 a pointer to a SSL object 

Returns:

the extension success 
NULL error 

TLSEXT_GENERAL* SSL_CTX_tlsext_get_extension (SSL_CTX * 

ctx

,   int 

type

)

Returns a pointer to an extension

Parameters:

ctx

 a pointer to a SSL_CTX object 

type

 the type of the extension to be returned 

Returns:

the extension success 
NULL error 

int SSL_TLSEXT_GENERAL_client_data (TLSEXT_GENERAL * 

ext

,   unsigned int 

length

,   unsigned char * 

data

)

Sets the client data to send within the extension 

ext

  (Client Hello).

Parameters:

ext

 extension to set. It SHOULD be initialized with 

SSL_TLSEXT_GENERAL_new()

 

length

 lenght of 

data

  

data

 data to transmit within the extension 

Returns:

0 success 
-1 error 

int SSL_TLSEXT_GENERAL_client_supp_data (TLSEXT_GENERAL * 

ext

,   int 

type

,   unsigned int 

length

,   unsigned char * 

data

)

Open_TC Deliverable D03c.6

14/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Sets a client supplemental data entry related to the extension 

ext

 .

The supplemental data entry MUST be created with 

SSL_TLSEXT_GENERAL_client_supp_data_new()

 before setting its payload. It 

will be transmitted within the Supplemental Data handshake message.

Parameters:

ext

 extension to set the supplemental data entry into 

type

 the type of the supplemental data entry. It MUST be registered before with 

SSL_TLSEXT_GENERAL_client_supp_data_new()

 

length

 lenght of 

data

  

data

 data to transmit within the supplemental data 

Returns:

0 success 
-1 error 

int SSL_TLSEXT_GENERAL_client_ctx_set (TLSEXT_GENERAL * 

ext

,   void * 

ctx_data

)

Sets the context data available to the client within the callback functions.
The context data can be used to exchange data from/to the application and 

libssl

  and is usually used within callback functions.

Parameters:

ext

 extension to set. It SHOULD be initialized with 

SSL_TLSEXT_GENERAL_new()

 

ctx_data

 pointer to the context data. SHOULD be casted to 

(void *)

  

Returns:

0 success 
-1 error 

void* SSL_TLSEXT_GENERAL_client_ctx_get (TLSEXT_GENERAL * 

ext

)

Returns the context data available to the client.
The context data can be used to exchange data from/to the application and 

libssl

  and is usually used within callback functions. The result need to be 

casted to the proper type.

Parameters:

ext

 extension to get from 

Returns:

the context data. It SHOULD be casted to the proper type 

NULL

  error 

int SSL_TLSEXT_GENERAL_client_ext_cb (TLSEXT_GENERAL * 

ext

,   void * 

cb_ptr

)

Sets the callback function the client will use to handle the TLS Extension 

ext 

(received within the Server Hello).
The callback is called immediately after receiving the Server Hello, thus before 

Open_TC Deliverable D03c.6

15/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

receiving any further message from the server. See 

ssl_parse_serverhello_tlsext_general()

 for more details.

The callback MUST have prototype: 

 void callback(SSL *, TLSEXT_GENERAL *);

 and MAY use context data to communication with the application.

Parameters:

ext

 extension to set. It SHOULD be initialized with 

SSL_TLSEXT_GENERAL_new()

 

cb_ptr

 pointer to the callback function 

Returns:

0 success 
-1 error 

int SSL_TLSEXT_GENERAL_client_supp_data_cb (TLSEXT_GENERAL * 

ext

,   void 

cb_ptr

)

Sets the callback function the client will use to create the supplemental data 
entry to send within the client's Supplemental Data message.
The callback is called immediately before sending the Supplemental Data 
message and allows to access any data received from the server (e.g. 
supplemental data or certificate).
The callback MUST have prototype: 

 void callback(SSL *, TLSEXT_GENERAL *);

 and MAY use context data to communication with the application.

Parameters:

ext

 extension to set. It SHOULD be initialized with 

SSL_TLSEXT_GENERAL_new()

 

cb_ptr

 pointer to the callback function 

Returns:

0 success 
-1 error 

int SSL_TLSEXT_GENERAL_client_finish_cb (TLSEXT_GENERAL * 

ext

,   void * 

cb_ptr

)

Sets the callback function the client will use to handle the supplemental data 
received from the server.
The callback is called at the end of the handshake, according to RFC 4680: 

Information provided in a supplemental data object MUST be intended 
to be used exclusively by applications and protocols above the TLS 
protocol layer.  Any such data MUST NOT need to be processed by the 
TLS protocol.

 The callback MUST have prototype: 

Open_TC Deliverable D03c.6

16/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

 void callback(SSL *, TLSEXT_GENERAL *);

 and MAY use context data to communication with the application.

Parameters:

ext

 extension to set. It SHOULD be initialized with 

SSL_TLSEXT_GENERAL_new()

 

cb_ptr

 pointer to the callback function 

Returns:

0 success 
-1 error 

int SSL_TLSEXT_GENERAL_server_data (TLSEXT_GENERAL * 

ext

,   unsigned int 

length

,   unsigned char * 

data

)

Sets the server data to send within the extension 

ext

  (Server Hello).

Parameters:

ext

 extension to set. It SHOULD be initialized with 

SSL_TLSEXT_GENERAL_new()

 

length

 lenght of 

data

  

data

 data to transmit within the extension 

Returns:

0 success 
-1 error 

int SSL_TLSEXT_GENERAL_server_supp_data (TLSEXT_GENERAL * 

ext

,   int 

type

,   unsigned int 

length

,   unsigned char * 

data

)

Sets a server supplemental data entry related to the extension 

ext

 .

The supplemental data entry MUST be created with 

SSL_TLSEXT_GENERAL_server_supp_data_new()

 before setting its payload. It 

will be transmitted within the Supplemental Data handshake message.

Parameters:

ext

 extension to set the supplemental data entry into

type

 the type of the supplemental data entry. It MUST be registered before with 

SSL_TLSEXT_GENERAL_server_supp_data_new()

length

 lenght of 

data

data

 data to transmit within the supplemental data

Returns:

0 success
-1 error

int SSL_TLSEXT_GENERAL_server_ctx_set (TLSEXT_GENERAL * 

ext

,   void * 

ctx_data

)

Sets the context data available to the server within the callback functions. The 
context data can be used to exchange data from/to the application and 

libssl 

and is usually used within callback functions.

Open_TC Deliverable D03c.6

17/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Parameters:

ext

 extension to set. It SHOULD be initialized with 

SSL_TLSEXT_GENERAL_new()

 

ctx_data

 pointer to the context data. SHOULD be casted to 

(void *)

  

Returns:

0 success 
-1 error 

void* SSL_TLSEXT_GENERAL_server_ctx_get (TLSEXT_GENERAL * 

ext

)

Returns the context data available to the server. The context data can be used 
to exchange data from/to the application and 

libssl

  and is usually used within 

callback functions. The result need to be casted to the proper type.

Parameters:

ext

 extension to get from. 

Returns:

the context data. It SHOULD be casted to the proper type 

NULL

  error 

int SSL_TLSEXT_GENERAL_server_ext_cb (TLSEXT_GENERAL * 

ext

,   void * 

cb_ptr

)

Sets the callback function the server will use to handle the TLS Extension 

ext 

(received within the Client Hello).
The callback is called immediately after receiving the Client Hello, thus before 
sending the Server Hello. It is used to process the data received from the client 
and to create the response to send within the Server Hello. See 

ssl_parse_clienthello_tlsext_general()

 for more details.

The callback MUST have prototype: 

 void callback(SSL *, TLSEXT_GENERAL *);

 and MAY use context data to communication with the application.

Parameters:

ext

 extension to set. It SHOULD be initialized with 

SSL_TLSEXT_GENERAL_new()

 

cb_ptr

 pointer to the callback function 

Returns:

0 success 
-1 error 

int SSL_TLSEXT_GENERAL_server_supp_data_cb (TLSEXT_GENERAL * 

ext

,   void 

cb_ptr

)

Sets the callback function the server will use to create the supplemental data 
entry to send within the server's Supplemental Data message.
The callback is called immediately before sending the Supplemental Data 
message.
The callback MUST have prototype: 

Open_TC Deliverable D03c.6

18/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

 void callback(SSL *, TLSEXT_GENERAL *);

 and MAY use context data to communication with the application.

Parameters:

ext

 extension to set. It SHOULD be initialized with 

SSL_TLSEXT_GENERAL_new()

 

cb_ptr

 pointer to the callback function 

Returns:

0 success 
-1 error 

int SSL_TLSEXT_GENERAL_server_finish_cb (TLSEXT_GENERAL * 

ext

,   void * 

cb_ptr

)

Sets the callback function the server will use to handle the supplemental data 
received from the client.
The callback is called at the end of the handshake, according to RFC 4680:

Information provided in a supplemental data object MUST be intended 
to be used exclusibely by applications and protocols above the TLS 
protocol layer. Any such data MUST NOT need to be processed by the 
TLS protocol.

The callback MUST have prototype: 

void callback(SSL *, TLSEXT_GENERAL *);

and MAY use context data to communication with the application.

Parameters:

ext

 extension to set. It SHOULD be initialized with 

SSL_TLSEXT_GENERAL_new()

 

cb_ptr

 pointer to the callback function 

Returns:

0 success 
-1 error

3.2.2   Application Interface

These functions are used by developers that write applications that use TLS Extensions 
already defined.

int SSL_TLSEXT_GENERAL_server_send (TLSEXT_GENERAL * 

ext

)

Instructs the server to respond with the extension 

ext

 .

It MUST be called only if the client sent the extension 

ext

 , so usually by the 

server_ext_callback

 .

This fuction is part of the Application Interface, however it SHOULD only be used 
in a TLS Extension implementation. In any case it SHOULD at least be wrapped 
by the TLS Extension.

Open_TC Deliverable D03c.6

19/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Parameters:

ext

 extension to set. It SHOULD be initialized with 

SSL_TLSEXT_GENERAL_new()

 

Returns:

0 success 
-1 error 

int SSL_TLSEXT_GENERAL_client_required (TLSEXT_GENERAL * 

ext

)

Forces the client to abort the handshake if the server does not reply with the 
extension 

ext

 .

This function is part of the Application Interface, so it SHOULD be wrapped by 
the TLS Extension implementation.

Parameters:

ext

 extension to set. It SHOULD be initialized with 

SSL_TLSEXT_GENERAL_new()

 

Returns:

0 success 
-1 error 

void SSL_CTX_tlsext_set_enabled (SSL_CTX * 

ctx

,   int 

type

)

Enables an extension.

Parameters:

ctx

 a pointer to a SSL_CTX object 

type

 the type of the extension to be enabled 

void SSL_CTX_tlsext_set_disabled (SSL_CTX * 

ctx

,   int 

type

)

Disables an extension.

Parameters:

ctx

 a pointer to a SSL_CTX object

type

 the type of the extension to be disabled

3.3   Examples

This section shows how to write an extension using the General TLS Extension; in order 
to understand this example, it is required to be familiar with programming with 
OpenSSL. Two programs are needed: one to implement the logic Client-side, one 
Server-side. Both requires an initialization function for the TLS Extension and optionally 
some of the available callback functions. As mentioned in Section 3.1, this Extension 
can be embedded into 

libssl

 or directly specified by the application. The latter 

scenario is the more appropriated for this example.
Before starting to implement the "Hello world!" extensions, it is worth of noting that 
extension implemented by exploiting the General TLS Extension framework still are 
part of the 

libssl

 and MUST still be standardized by IANA.

3.3.1   Hello World!

The first example is a simple TLS Extension in the sense of RFC 4366 (i.e. without 

Open_TC Deliverable D03c.6

20/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

supplemental data).
The initialization function on Client side is:

void SSL_TLSEXT_TEST_client_init(SSL * s) {
   TLSEXT_GENERAL * e;
   e = SSL_TLSEXT_GENERAL_new(s, 65000);
   SSL_TLSEXT_GENERAL_client_data(e, 6, "Hello\0");
   SSL_TLSEXT_GENERAL_client_ext_cb(e, ssl_tlsext_test_client_ext_cb);
}

It creates an extension of type 65000, with payload "Hello", and registers a callback 
function 

ssl_tlsext_test_client_ext_cb()

.

Such initialization function has to be invoked between the creation of the 

SSL

 object 

and the connection opening.
The callback function is a simple debug function, which prints out the data received 
from the server:

void ssl_tlsext_test_client_ext_cb(SSL * s, TLSEXT_GENERAL * e) {
   /* prints the extension received */
   fprintf(stderr, "TEST: %d\n", e->type);
   fprintf(stderr, "TEST: %d\n", e->server_data_length);
   fprintf(stderr, "TEST: %s\n", e->server_data);
}

This callback function will be executed immediately after the Client receives the 
ServerHello message, with the related TLS Extension.
The main difference between the Client and Server implementation is that the Client 
sets the payload to be send through the TLS Extension within the initialization function, 
while the Server does it in the 

server_ext_cb()

. The reason for this different behavior 

is that the payload sent by the Server may depend on the payload sent by the Client. 
For simplicity the following example does not take into account the payload sent by 
the Client when creating the payload on the Server side.
On Server side, the initialization function only describes the extension and registers 
the 

server_ext_cb()

:

void SSL_TLSEXT_TEST_server_init(SSL * s) {
   TLSEXT_GENERAL * e;
   e = SSL_TLSEXT_GENERAL_new(s, 65000);
   SSL_TLSEXT_GENERAL_server_ext_cb(e, ssl_tlsext_test_server_ext_cb);
}

The following callback function prints out the data received from the Client, sets the 
payload to be send and enables the TLS Extension by calling the 

SSL_TLSEXT_GENERAL_server_send()

 Interface function:

void ssl_tlsext_test_server_ext_cb(SSL * s, TLSEXT_GENERAL * e) {
   /* prints the extension received */
   fprintf(stderr, "TEST: %d\n", e->type);
   fprintf(stderr, "TEST: %d\n", e->client_data_length);

Open_TC Deliverable D03c.6

21/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

   fprintf(stderr, "TEST: %s\n", e->client_data);
   
   /* generates the response */
   SSL_TLSEXT_GENERAL_server_data(e, 7, "World!\0");
   SSL_TLSEXT_GENERAL_server_send(e);
}

This callback function will be executed immediately after the Server receives the 
ClientHello message, with the related TLS Extension.

3.3.2   Supplemental Data

In this second example supplemental data are added: it is assumed that only the 
Server has to send supplemental data (in particular two supplemental data entries).
Note that both the Client and the Server MUST define the extension, including in the 
definition the number and type of related supplemental data entries (which is assumed 
to be fixed and standardized).
On Client side the initialization function is modified by describing the supplemental 
data entries (even if it is the Server who will send them) and registering a finish 
callback function to handle the data received:

void SSL_TLSEXT_TEST_client_init(SSL * s) {
   TLSEXT_GENERAL * e;
   e = SSL_TLSEXT_GENERAL_new(s, 65000);
   SSL_TLSEXT_GENERAL_client_data(e, 8, "test-c1\0");
   SSL_TLSEXT_GENERAL_client_ext_cb(e, ssl_tlsext_test_client_ext_cb);

   /* the server will send supplemental data */
   SSL_TLSEXT_GENERAL_server_supp_data_new(e, 65100);
   SSL_TLSEXT_GENERAL_server_supp_data_new(e, 65101);
   SSL_TLSEXT_GENERAL_client_finish_cb(e,
         ssl_tlsext_test_client_finish_cb);
}

Again, a simple debug callback function is used:

void ssl_tlsext_test_client_finish_cb(SSL * s, TLSEXT_GENERAL * e) {
   int i;
   SUPP_DATA_ENTRY * sd;
   if (e->server_supp_data) {
      for (i=0; i<sk_SUPP_DATA_ENTRY_num(e->server_supp_data); i++) {
         sd = sk_SUPP_DATA_ENTRY_value(e->server_supp_data, i);
         fprintf(stderr, "TEST > SD %d (%d) %s\n", 
               sd->type, sd->length, sd->data);
      }
   }
}

where 

sk_SUPP_DATA_ENTRY_num()

 and  

sk_SUPP_DATA_ENTRY_value()

 are standard 

functions of the OpenSSL 

STACK_OF

 interface.

Open_TC Deliverable D03c.6

22/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

On Server side, the initialization function is modified to add the supplemental data 
entries and register a callback function to fill their payload:

void SSL_TLSEXT_TEST_server_init(SSL * s) {
   TLSEXT_GENERAL * e;
   e = SSL_TLSEXT_GENERAL_new(s, 65000);
   SSL_TLSEXT_GENERAL_server_ext_cb(e, ssl_tlsext_test_server_ext_cb);

   /* the server will send supplemental data */
   SSL_TLSEXT_GENERAL_server_supp_data_new(e, 65100);
   SSL_TLSEXT_GENERAL_server_supp_data_new(e, 65101);
   SSL_TLSEXT_GENERAL_server_supp_data_cb(e,
         ssl_tlsext_test_server_supp_data_cb);
}

And finally the Server's callback that fills the content of the supplemental data entries 
(it might access all data exchanged previously) is:

void ssl_tlsext_test_server_supp_data_cb(SSL * s, TLSEXT_GENERAL * e){
   SSL_TLSEXT_GENERAL_server_supp_data(e, 65100, 10, "test-Ssd0\0");
   SSL_TLSEXT_GENERAL_server_supp_data(e, 65101, 10, "test-Ssd1\0");
}

Open_TC Deliverable D03c.6

23/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

4   Direct Anonymous Attestation

4.1   Architecture

This is an interface to implement the Direct Anonymous Attestation (DAA) protocol 
[7,8,9] within OpenSSL 

libcrypto

DAA is composed by many different cryptographic algorithms: Setup, Join, Sign, Verify, 
Link and Rogue Tagging. Currently only the Sign and Verify algorithms are supported 
and, according to the original design of DAA, the Sign algorithm is considered as a two-
parties protocol between the Host and the TPM. This is a common point between all 
versions of DAA in literature.
The interface is designed to be as general as possible in order to support all DAA 
versions: RSA-based or Pairing-based DAA, with or without an actual (hardware) TPM.
The current version provides a default dummy implementation together with the 
interface. Such dummy version does not implement a complete DAA protocol, but its 
sole purpose is to demonstrate its functionality without the need of any other software 
than OpenSSL. A proper DAA protocol will replace the dummy implementation in future 
versions. The use of OpenSSL engines allows overriding the default implementation.

4.1.1   Overview

The code is organized in three main modules, as shown in Figure 5.

In more details:

Open_TC Deliverable D03c.6

24/61

Figure 5: Direct Anonymous 

Attestation Architecture Overview

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Implementations 

contains:

The specific implementation of the cryptographic primitives.

The specific implementation of functions to manage related data types 
(e.g. signature, credentials).

According to OpenSSL design, the primitives are put together in a single object 
called DAA method (refer to the 

DAA_METHOD

 structure, described in Section 

4.1.2)
Currently, a single default implementation is available.
OpenSSL engines overwrite this layer.

Method Interface

 is a low level interface that hides the view on the 

DAA_METHOD

 behind a higher level object represented by the 

DAA

 structure (refer 

to Section 4.1.2 for more details). This interface allows to:

Get and set the default DAA method to be used when creating new 

DAA 

structures.

Select and use a specific DAA method for a given 

DAA

 structure.

Access the method primitives from the 

DAA

 structure.

According to OpenSSL design, at this layer input/output of functions are 
internal data structures.

This interface should not directly used by an Application, but provides a first 
layer of separation between the Implementation layer where a structure 

DAA_METHOD

 is instantiated and the Application Interface layer where functions 

need to access the method.

Application Interface 

is the interface available to the applications. It provides 

functions to:

Created/destroy a 

DAA

 structure.

Access/modify properties of the 

DAA

 structure.

Invoke cryptographic primitives of the referenced method. According to 
OpenSSL design, at this layer input/output of functions are buffers 
(notably, in this context, digests and signatures) and there is not visibility 
of the internal data structures used to make computation.

Further details are given in Section 4.2.

4.1.2   Data Structures

Four main data structures are involved in the DAA interface. The relationship among 
them is depicted in Figure 6.

Open_TC Deliverable D03c.6

25/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

In more details:

DAA

 is the main data structure, available at Application Interface layer. It 

contains references to other structures and to two buffers to store the Verifier's 
nonce and basename.

DAA_METHOD

 contains pointers to functions that represent the implementation of 

the DAA algorithms, which mainly consists of:

DAA Core Functions

: the cryptographic primitives, detailed in Section 

4.1.3.

DAA_ISSUER

 Management

: constructor/destructor and serialization 

functions for the 

DAA_ISSUER

 structure (Issuer credentials).

DAA_KEY

 Management

: constructor/destructor and serialization functions 

for the 

DAA_KEY

 structure (Platform credentials).

DAA_SIG

 Management

: constructor/destructor and serialization functions 

for the 

DAA_SIG

 structure (DAA signature).

DAA_KEY

 represents the Platform credentials, necessary to compute a DAA 

signature. This structure is a wrapper to a specific key type, which depends on 
the actual implementation provided by the DAA method.

DAA_ISSUER

 represents the Issuer credentials, necessary to verify the 

correctness of a DAA signature. This structure is a wrapper to a specific type, 
which depends on the actual implementation provided by the DAA method.

In order to maintain consistency inside a DAA structure, all data structure contain a 

Open_TC Deliverable D03c.6

26/61

Figure 6: Direct Anonymous Attestation Data Structure

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

version

 field (not shown for simplicity in the figure). A proper implementation of a 

DAA method SHOULD process only data structures with its same version.
Currently, this implementation defines the following versions:

The original RSA-based DAA described in [7] (purely software implementation, 
currently not implemented).

The TCG TSS/TPM DAA profile that exploits the RSA-based version of DAA and is 
specified in [1] (with actual TPM support, implemented through the engine 
described in Section 6).

The symmetric pairing-based version of DAA described in [8] (purely software 
implementation, currently not implemented).

The asymmetric pairing-based version of DAA described in [9] (purely software 
implementation, currently implemented through the Miracl engine mentioned in 
Section 2).

In addition to the previously described structures, a 

DAA_SIG

 structure is defined (not 

shown in Figure 6 for simplicity). Similarly to 

DAA_KEY

 and 

DAA_ISSUER

, it is a wrapper 

to a specific signature type, which depends on the actual implementation provided by 
the DAA method. As already mentioned, the 

DAA_SIG

 structure is hidden at Application 

Interface layer, by encoding/decoding it into buffers. For this reason no further details 
are presented in the following.

4.1.3   Workflow

This section describes in more details the cryptographic primitives related to DAA and 
the workflow from the Application Interface down to the actual Implementation layer.

Verifier Init

. The Verifier generates a nonce and sets a basename. The 

Application Interface layer function 

DAA_sign_verifier_init()

 directly 

accesses the Implementation layer primitive 

sign_verifier_init()

 of the 

method. Since both nonce and basename are buffers, there is no need for the 
intermediate Method Interface layer.

Sign

. The User/platform computes a DAA signature on a message digest. The 

workflow is summarized in Figure 7. This implementation reflects the original 
design of DAA where the User/platform is divided into Host and TPM; note that in 
this context TPM does not refer to the hardware TCG's TPM, but it is used to 
isolate the critical component from the rest of the platform.

Open_TC Deliverable D03c.6

27/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

1.The Application Interface layer function 

DAA_sign()

 invokes the Method 

Interface layer function 

DAA_do_sign()

.

2.The Method Interface layer function 

DAA_do_sign()

 invokes the 

Implementation layer primitive 

daa_do_sign()

 of the method.

3.

daa_do_sign()

 actually computes the DAA signature. In order to reflect the 

original design in the DAA definition,  

daa_do_sign()

 is expected to call 

the primitives 

daa_sign_tpm_phase1()

 and 

daa_sign_tpm_phase2() 

which perform the computation on the TPM side. Note that an actual 
implementation may avoid the definition of the two TPM primitives.

4.

daa_do_sign()

 returns a 

DAA_SIG

 structure.

5.

DAA_do_sign()

 forwards the 

DAA_SIG

 structure to the caller.

6.At Application Interface layer, 

DAA_sign()

 converts the 

DAA_SIG

 structure 

in a buffer, calling the function 

i2d_DAA_SIG()

 (which relies on a primitive 

at Implementation layer, not shown for simplicity in the picture).

7.Finally, 

DAA_sign()

 returns the DAA signature as a buffer to the calling 

application.

Verify

. The Verifier checks the correctness of a DAA signature. The worklow is 

summarized in Figure 8.

Open_TC Deliverable D03c.6

28/61

Figure 7: Direct Anonymous Attestation Sign Workflow

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

1.The Application Interface layer function 

DAA_verify()

 receives in input a 

buffer containing the DAA signature. First it deserializes the signature into 

DAA_SIG

 structure, invoking 

d2i_DAA_SIG()

 (which relies on a primitive 

at Implementation layer, not shown for simplicity in the picture).

2.

DAA_verify()

 continues by invoking the Method Interface layer function 

DAA_do_verify()

, that accepts in input the 

DAA_SIG

 structure.

3.The Method Interface layer function 

DAA_do_verify()

 invokes the 

Implementation layer primitive 

daa_do_verify()

 of the method.

4.

daa_do_verify()

 returns either success or failure.

5.

DAA_do_sign()

 forwards the response to the caller.

6.Finally, 

DAA_verify()

 returns either success or failure to the calling 

application.

4.2   Application Programming Interface

4.2.1   Application Interface

These functions are used by developers that write applications that use DAA as 
cryptographic protocol.

DAA* DAA_new (void)

DAA structure constructor.

Open_TC Deliverable D03c.6

29/61

Figure 8: Direct Anonymous Attestation Verify Workflow

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Generates a new DAA structure relying on the Method Interface layer function 

DAA_new_method()

. It invokes 

DAA_new_method()

 with a NULL engine, which 

means the function actually returns a DAA structure with method 

DAA_get_default_method()

 and engine ENGINE_get_default_DAA().

Loading an engine (e.g. with standard -engine option of OpenSSL commands) 
overwrite the default method and engine, hence the result of this function is a 
DAA structure which is based on the loaded engine.

Returns:

Pointer to the new DAA structure 

void DAA_free (DAA * 

daa

)

DAA structure destructor.
Destroys a DAA structure, by calling internal DAA_KEY and DAA_ISSUER free.

Parameters:

daa

 Pointer to the DAA structure 

int DAA_get_version (const DAA * 

daa

)

Returns the binding version of the supplied DAA structure.

Parameters:

daa

 Pointer to the DAA structure 

Returns:

The DAA binding version 

int DAA_set_nonce (unsigned int 

nonce_len

,   unsigned char * 

nonce

,   DAA 

daa

)

Sets the Verifier's nonce into the supplied DAA structure.

Parameters:

nonce_len

 Length of the buffer containing the Verifier's nonce 

nonce

 Buffer containing the Verifier's nonce 

daa

 Pointer to the DAA structure 

Returns:

1 in case of success 
-1 in case of error 

int DAA_set_basename (unsigned int 

basename_len

,   unsigned char * 

basename

,   DAA * 

daa

)

Sets the Verifier's basename into the supplied DAA structure.

Parameters:

basename_len

 Length of the buffer containing the Verifier's basename 

basename

 Buffer containing the Verifier's basename 

daa

 Pointer to the DAA structure 

Returns:

1 in case of success 

Open_TC Deliverable D03c.6

30/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

-1 in case of error 

int DAA_SIG_size (const DAA * 

daa

)

Returns the size (in bytes) of a DAA signature for the supplied DAA structure.
Returns an upper bound to the DAA_SIG size. Useful to allocate a buffer that will 
contains a signature, without knowing in advantage what the signature will be.

Parameters:

daa

 Pointer to the DAA structure 

Returns:

The required size for a buffer to store a DAA_SIG structure 

int DAA_sign_verifier_init (unsigned int * 

nonce_len

,   unsigned char ** 

nonce

,   unsigned int * 

basename_len

,   unsigned char ** 

basename

,   DAA 

daa

)

Returns the Verifier's nonce and basename and sets them within the supplied 
DAA structure.

Parameters:

nonce_len

 Pointer to a int, where the length of the Verifier's nonce buffer is 

returned 

nonce

 Pointer to a buffer, where the Verifier's nonce is returned 

basename_len

 Pointer to a int, where the length of the Verifier's basename 

buffer is returned 

basename

 Pointer to a buffer, where the Verifier's basename is returned 

daa

 Pointer to the DAA structure containing a reference to the DAA method 

Returns:

Pointer to the DAA_SIG structure created 
NULL if an error occurred 

int DAA_sign (int 

type

,   const unsigned char * 

dgst

,   int 

dgst_len

unsigned char * 

sig

,   unsigned int * 

sig_len

,   DAA * 

daa

)

Computes the DAA signature (buffer) of the given hash value using the DAA 
method supplied and returns the created signature.

Parameters:

type

 This parameter is ignored 

dgst

 Buffer containing the hash value 

dgst_len

 Length of the hash value buffer 

sig

 Pointer to a buffer, where the DAA signature is returned 

sig_len

 Pointer to a int, where the length of the DAA signature buffer is returned 

daa

 Pointer to the DAA structure containing a reference to the DAA method 

Returns:

1 in case of success 
0 in case of error 

Open_TC Deliverable D03c.6

31/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

int DAA_verify (int 

type

,   const unsigned char * 

dgst

,   int 

dgst_len

const unsigned char * 

sigbuf

,   int 

sigbuf_len

,   DAA * 

daa

)

Verifies that the supplied signature (buffer) is a valid DAA signature of the 
supplied hash value using the supplied DAA method.

Parameters:

type

 This parameter is ignored 

dgst

 Buffer containing the hash value 

dgst_len

 Length of the hash value buffer 

sigbuf

 Buffer containing a serialized DAA signature 

sigbuf_len

 Length of the DAA signature buffer 

daa

 Pointer to the DAA structure containing a reference to the DAA method 

Returns:

1 if the signature is correct 
0 if the signature is incorrect 
-1 in case of error

4.3   Examples

Section 5.1.3 provides details about the use of the DAA protocol in a TLS Extension. 
Such details can be used as an example showing the usage of the DAA protocol in 
OpenSSL.

Open_TC Deliverable D03c.6

32/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

5   TLS DAA-Enhancement

5.1   Architecture

The TLS DAA-Enhancement (DAA-TLS) is a TLS Enhancement that implements the 
(client) anonymous authentication according to [1], and using the TLSEXT general 
framework (Section 3) and the DAA primitives (Section 4).
The TLSEXT general framework is used to transport a DAA-TLS Extension which carries 
the required messages between client and server. The DAA cryptographic primitives 
are used as group signature for authenticating the user anonymously.
DAA-TLS is designed to rely on the underlying DAA implementation and hence to 
support all the DAA versions provided: RSA-based or Pairing-based DAA, with or 
without an actual (hardware) TPM.
This code is designed to be part of the OpenSSL 

libssl

 library and it is compiled in it.

5.1.1   Overview

The code is organized in two main modules as shown in Figure 9.

In more details:

Core

 contains the core functions required by DAA-TLS. In particular among the 

core functions there are the initialization function needed to activate the hello 

Open_TC Deliverable D03c.6

33/61

Figure 9: TLS DAA-Enhancement 

Architecture Overview

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

extension, the callback functions for creating and managing the exchanged data 
and the final callback function to verify the DAA signature.

Application Interface

 is a module that allows the application to manage the 

behavior of the DAA-TLS Extension. Further details are given in Section 5.2.

5.1.2   Data Structures

The TLS DAA-Enhancement saves the data needed during the TLS handshake in a data 
structure called 

ssl_tlsext_daa_ctx_st

. This structure contains the following data:

struct ssl_tlsext_daa_ctx_st {

DAA *daa;

unsigned int key_len;
unsigned char *key_buf;

unsigned int issuer_key_len;
unsigned char *issuer_key_buf;

};

In more details:

daa

 is a pointer to the 

DAA

 structure described in Section 4.1.2.

key_buf

 is a buffer of 

key_buf_len

 bytes that contains the DAA key.

issuer_key_buf

 is a buffer of 

issuer_key_buf_len

 bytes that contains the DAA 

Issuer public key.

This structure is created during the initialization of the DAA-TLS Extension and is 
managed by specific functions (refer to Section 5.1.3 for more details).
Section 5.3 presents an example of how to use this data structure to implement an 
Application that supports DAA-TLS.

5.1.3   Implementation Details

5.1.3.1   Core

This section shows how the TLS Extensions is structured and gives details about the 
internals.

TLSEXT_GENERAL* SSL_TLSEXT_DAA_new ()

Creates a new DAA extension.
It is called by the ssl_tlsext_general_create_list() which is executed during the 
creation of the SSL_CTX object.
It sets 

ssl_tlsext_daa_init()

 as init callback function. 

void ssl_tlsext_daa_client_supp_data_cb (SSL * 

s

,   TLSEXT_GENERAL * 

e

)

Callback function for creating the supplemental data entry on the client.
It parses the data received from the server through the TLS Hello Extension that 
contains the nonce and the basename.
Furthermore it retrieves the digest of the X509 certificate used for the client 
authentication.
It uses the nonce, the basename and the digest of the X509 certificate for 

Open_TC Deliverable D03c.6

34/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

making the DAA signature.

Parameters:

s

 a pointer to the SSL object 

e

 a pointer to the DAA extension 

int ssl_tlsext_daa_server_ext_cb (SSL * 

s

,   TLSEXT_GENERAL * 

e

)

Callback function for receiving the TLS Hello Extension on the server.
It decides if the server must accept the DAA authentication or not. If the server 
accepts it, then it creates a TLS Hello extension to send within the server hello in 
response to the client request. If the DAA signature is refused, the server 
creates an extension that contains an error code and send it back.
Furthermore it sets the callbacks needed to handle the supplemental data 
message that will carry the DAA signature

Parameters:

s

 a pointer to the SSL object 

e

 a pointer to the DAA extension 

int ssl_tlsext_daa_server_finish_cb (SSL * 

s

,   TLSEXT_GENERAL * 

e

)

Callback function for managing the supplemental data message on the server.
This is executed at the end of the handshake.
If the DAA signature verification fails, then the USER_CANCELLED error is 
returned.

Parameters:

s

 a pointer to the SSL object 

e

 a pointer to the DAA extension

5.1.4   Workflow

Figure 10 gives an overview of the TLS DAA-Enhancement workflow. More details are 
given in the following.

Open_TC Deliverable D03c.6

35/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

1. The DAA-TLS Extension is created and initialized on both sides through 

ssl_tlsext_daa_init()

 (see Section 6.1.2 for more details). During this 

operation, the client loads the DAA Platform credentials, while the server loads 
the Issuer credentials. These data will be used later on to make the DAA 
signature and to verify it.

2. The client begins the TLS handshake by sending a ClientHello with the DAA-TLS 

Extension indicating that it wants to use the anonymous authentication. Within 
the extension payload, the client sends the supported version.

3. If the server supports the DAA-TLS anonymous authentication, the 

ssl_tlsext_daa_server_cb()

 callback is called. This callback decides if the 

server accepts to use the DAA anonymous authentication.
If the server accepts the use of DAA-TLS, it calls the 

DAA_sign_verifier_init()

 function. The 

DAA_sign_verifier_init()

 is part 

of the DAA Application Interface (refer to Section 4.1.3 for details). Furthermore, 
since DAA-TLS requires a client authentication with a self-signed certificate 
(refer to [1]), the callback function disables the verification of the client 
certificate in OpenSSL by modifying the 

verify_mode

 field of the 

SSL

 object.

4. The server always replies with the ServerHello with the DAA-TLS Extension, both 

in case of acceptance or rejection.
If the server accepts, the extension contains the Verifier's nonce and basename 
that must be used in the signature computation.
According to [1], if the server does not accept the use of DAA-TLS, the extension 
contains an error code.

5. The TLS handshake continues as usually until the client needs to send the 

SupplementalData message that carries the DAA signature (recall that, 

Open_TC Deliverable D03c.6

36/61

Figure 10: TLS DAA-Enhancement Workflow

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

according to [1], only Client Supplemental Data are required).

6. In order to prepare the data to be sent in the SupplementalData message, the 

client executes the 

ssl_tlsext_daa_client_supp_data_cb()

. This callback 

function calls the 

DAA_sign()

 in order to compute the DAA signature. The 

DAA_sign()

 is part of the DAA Application Interface (refer to Section 4.1.3 for 

details). According to [1], the data signed corresponds to the digest of the X509 
certificate used for the TLS client authentication. The callback function retrieves 
the certificate from the 

SSL

 object and uses the OpenSSL 

X509_digest() 

function to compute the digest.

7. The TLS handshake continues as usually until the server and the client exchange 

the Finish message.

8. After the Finish message is exchanged, the server can verify the DAA signature. 

This is accomplished by the 

ssl_tlsext_daa_server_finish_cb()

. This 

callback function verifies the signature using the 

DAA_sign_verify()

 function. 

The 

DAA_sign_verify()

 is part of the DAA Application Interface (refer to 

Section 4.1.3 for details). The callback function retrieves the digest of the 
certificate used for the client authentication from the session data contained in 
the 

SSL

 object.

9. When the handshake is completed, the client and the server can exchange the 

application data.

5.1.5   Other Features

In this section some additional features of the current implementation are described.

5.1.5.1   Support to TLS Sessions Resumption

The current implementation supports TLS session resumption and is compatible with 
the OpenSSL implementation of the SessionTicket TLS Extension for session 
resumption without server-side state (RFC 4507).
If a client wants to resume a previous TLS session, it makes explicit request during the 
ClientHello message. If the server agrees the session resumption, then the handshake 
jumps to the Finish messages. From the perspective of the DAA-TLS Extension, no 
computation is done at all.
This ClientHello message MAY still contain a DAA-TLS Extension, whose purpose is to 
dictate that, in case the server will refuse session resumption, the client wish to open a 
new TLS session with DAA enhancement.

5.1.5.2   Legacy Mode

The current implementation allows, at compile time, to turn the DAA enhanced 

libssl 

into legacy mode.
Legacy mode means that the DAA extension can be used even by unmodified 
applications, that link the DAA enhanced 

libssl

. This is an experimental feature, 

which only works in Unix-like environment and has been tested with Apache+mod_ssl.
The legacy mode works as follows:

On client side, the DAA-TLS Extension is activated by default.

Open_TC Deliverable D03c.6

37/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

On client side, the DAA Platform credentials are assumed to be stored in a file 
specified in a system variable called 

DAA_LEGACY_CRED

. If such variable is not 

defined, the default location 

/usr/local/daatoolkit/etc/daa/daa_cred.bin 

is used

.

On server side, the DAA Issuer credentials are assumed to be stored in  a file 
specified in a system variable called 

DAA_LEGACY_ISSUER

. If such variable is not 

defined, the default location 

/usr/local/daatoolkit/etc/daa/daa_issuer.bin

 is used.

The application MUST support and load a (self-signed) client certificate.
In addition it MAY load a DAA capable engine.

5.2   Application Programming Interface

5.2.1   Application Interface

These functions are used by the developers that write applications that use TLS-DAA.

TLSEXT_GENERAL* ssl_tlsext_daa_init (SSL * 

s

,   TLSEXT_GENERAL * 

ext

)

Initializes a DAA extension
The initialization calls the SSL_TLSEXT_GENERAL_init. Then it verifies whether 
the extension is created on the client or on the server and sets the callback 
functions accordingly.

Parameters:

s

 a pointer to the SSL object 

ext

 a pointer to the DAA extension to be initialized 

void SSL_CTX_tlsext_daa_set_enabled (SSL_CTX * 

ctx

)

Enable the DAA extension.
This is a wrapper for the 

SSL_CTX_tlsext_set_enabled()

 where the type is 

fixed to TLSEXT_TYPE_daa.

Parameters:

ctx

 a pointer to a SSL_CTX object 

void SSL_CTX_tlsext_daa_set_disabled (SSL_CTX * 

ctx

)

Disable the DAA extension.
This is a wrapper for the 

SSL_CTX_tlsext_set_enabled()

 where the type is 

fixed to TLSEXT_TYPE_daa.

Parameters:

ctx

 a pointer to a SSL_CTX object 

void SSL_CTX_tlsext_daa_client_set_key (SSL_CTX * 

ctx

,   unsigned int 

len

,   unsigned char * 

buf

)

Sets on the client the DAA credential for signing.
This is used by the application to set the DAA credential in the SSL_CTX object. 
This must happen before the SSL object is created.

Parameters:

Open_TC Deliverable D03c.6

38/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

ctx

 a pointer to a SSL_CTX object 

len

 size of 

buf

  

buf

 DAA credential 

void SSL_CTX_tlsext_daa_client_set_issuer_key (SSL_CTX * 

ctx

,   unsigned 

int 

len

,   unsigned char * 

buf

)

Sets on the client the DAA Issuer public key.
This is used by the application to set the DAA credential in the SSL_CTX object. 
This must happen before the SSL object is created.

Parameters:

ctx

 a pointer to a SSL_CTX object 

len

 size of 

buf

  

buf

 DAA Issuer public key 

void SSL_CTX_tlsext_daa_server_set_issuer_key (SSL_CTX * 

ctx

,   unsigned 

int 

len

,   unsigned char * 

buf

)

Sets on the server the DAA Issuer public key.
This is used by the application to set the DAA credential in the SSL_CTX object. 
This must happen before the SSL object is created.

Parameters:

ctx

 a pointer to a SSL_CTX object

len

 size of 

buf

buf

 DAA Issuer public key

5.3   Example

This example is based on the commands 

s_client

 and 

s_server

 provided by 

OpenSSL. This section shows how to modify the code of the commands in order to 
support the DAA-TLS protocol without relying on the legacy mode.
This example is based on the DAA-TLS Extension described in this section, but the 
skeleton and the basic concepts can be used with any extension defined in OpenSSL.
The modifications are minimal and only affect the initialization phase where the 
parameters of the connection are decided. After the parameters are set up, the code 
for creating the TLS channel remains unchanged and the application manages the 
connection as without the DAA-TLS Extension.

5.3.1   Common Modifications

Both client and server must include the header file of the extension DAA-TLS.
The following line must be added at the beginning of the code:

#include <openssl/t1_daa.h>

According to OpenSSL design, an application should create a 

SSL_CTX

 structure, set 

default values for the SSL/TLS connection it wishes to open, then it creates the 

SSL 

Open_TC Deliverable D03c.6

39/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

structure from the previously generated context.
In general, an application will have the following skeleton:

ctx = SSL_CTX_new();

/* Functions that set flags and options in the SSL_CTX */

ssl = SSL_new(ctx);

The DAA-TLS Extension offers some API functions that allow to modify its behavior. 
These functions set data, flags and options in the context data of the extension. The 

SSL_new()

 function will use such data to initialize the DAA-TLS Extension.

In the following it is assumed that 

ctx

 is the 

SSL_CTX

 structure created through the 

SSL_CTX_new()

 function and all proposed modifications are located in the code before 

the creation of the 

SSL

 structure.

5.3.2   Modifications on the Client

The client must enable the support for the DAA-TLS Extension. A switch passed in input 
on the command line enables the DAA-TLS Extension. This switch also specifies the file 
that contains the DAA key.
Currently, 

s_client

 supports a command line option 

-daa

, which enables the DAA-TLS 

Extension and expects the name of a file containing the platform credentials as 
parameter.
Within the code, the option 

-daa 

triggers the following events: setting the value of the 

integer value 

daa

 to 1, and loading the content of the specified file into a buffer 

buf

 of 

length 

len

.

The DAA-TLS Extension is then enabled using the following function:

if (daa) {
   SSL_CTX_tlsext_daa_set_enabled(ctx);
}

After the extension is enabled, it is possible to set the DAA Platform credentials using 
the function

SSL_CTX_tlsext_daa_client_set_key(ctx, len, buf);

where 

buf

 is a buffer of 

len

 bytes that contains the DAA Platform credentials . 

5.3.3   Modifications on the Server

The server does not need to enable the support for the DAA-TLS Extension since the 
library enables by default the extensions on the server.
Currently, 

s_server

 supports a command line option 

-daa_issuer

 to specify the name 

of a file containing the DAA Issuer credentials as the following parameter. Within the 
code, this parameter forces to load the issuer credential from the specified file into a 
buffer 

buf

 of length 

len

.

Open_TC Deliverable D03c.6

40/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

After the 

SSL_CTX

 object was created, it is possible to set the DAA Issuer credentials as 

shown in the following:

ctx = SSL_CTX_new();
SSL_CTX_tlsext_daa_server_set_issuer_key(ctx, len, buf);

where 

buf

 is a buffer of 

len

 bytes that contains the DAA Issuer key.

In addition, 

s_server

 supports a command line option 

-no_daa

 to disable the DAA-TLS 

Extension. Within the code, this parameter sets to 1 the value of an integer variable 

no_daa

. It is then possible to disable the DAA-TLS Extension using the function:

if (no_daa) {
   SSL_CTX_tlsext_daa_set_disabled(ctx);
}

5.3.4   Running the commands

Before running the commands, the DAA credential must be generated. Since this 
example relies on the dummy implementation, it is sufficient to used empty files for, 
both, the DAA Issuer credentials and the DAA Platform credentials.
The command line for a server that supports the DAA-TLS is:

./openssl s_server

-daa_issuer /usr/local/daatoolkit/etc/daa/daa_issuer.bin

where the option 

-daa_issuer

 is used to specify the name of a file containing the 

Issuer credentials (

/usr/local/daatoolkit/etc/daa/daa_issuer.bin

 in the example 

above).
The command line for a client that supports the DAA-TLS is:

./openssl s_client -tls1 -cert client.pem

-daa /usr/local/daatoolkit/etc/daa/daa_cred.bin

where 

-tls1

 forces the use of TLS channel (SSL does not support extensions), 

-cert 

specifies a client (self-signed) certificate to use during the handshake 

-daa

 enables the 

DAA-TLS Extension and loads the platform credentials from the specified file 
(

/usr/local/daatoolkit/etc/daa/daa_cred.bin

 in the example above).

It is also possible to run OpenSSL s_server with the DAA-TLS disabled:

./openssl s_server -no_daa

In this case the server will not respond to DAA-TLS Extension requests.

Open_TC Deliverable D03c.6

41/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

6   Implementation of the Specification of TCG TSS/TPM 

DAA Profile for DAA-TLS

6.1   Architecture

The majority of the code presented in this section is implemented in an OpenSSL 
engine which overloads the functions offered by OpenSSL in the default DAA 
implementation.
For actually making and verifying the DAA signature the engine makes use of the 
functions offered by a Trusted Software Stack (TSS).
Next to the engine, also OpenSSL 

libcrypto

 DAA-enhanced and a Trusted Software 

Stack (TSS) are required. Furthermore, the OpenSSL 

libssl

 enhanced with the 

framework for general extension is required in order to correctly run protocol between 
client and server.

6.1.1   Overview

Figure 11 shows how the OpenSSL engine is internally organized and how it interacts 
with OpenSSL 

libcrypto

 and the TSS. Refer to Section 6.1.2 for more details.

Open_TC Deliverable D03c.6

42/61

Figure 11: Implementation of the specification of TCG 

TSS/TPM DAA profile for DAA-TLS Overview

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

In more details:

Engine Core

. This module layer contains all functions required by OpenSSL and 

needed to manage the engine. These functions are, for instance, used to create 
and initialize the engine or to destroy it.

TSS Binding Utilities

. This module allows the engine to share data with the 

Trusted Software Stack. These functions are used to translate the representation 
of internal data structures (e.g. DAA signature) from OpenSSL to TSS and vice 
versa.

DAA_METHOD

. This overrides the default DAA method provided by OpenSSL. 

This method contains:

DAA Core Functions

. This module implements the code to make and 

verify the DAA signature. This code relies on the TSS to make the actual 
signature and verification and it is called by the TLS Extension that 
implements the protocol. More details are given in Section 6.1.2.

DAA_KEY Management

. This module is in charge of loading the 

DAA_KEY structure (platform credentials), needed to compute signatures. 
According to the design described in Section 4.1.2, the application loads 
the key in a buffer. This module expects the buffer containing the data 
encoded according to the TSS specification [3]; hence, the engine passes 
the keys to the TSS which decodes and loads them into the appropriate 
internal data structure.

DAA_ISSUER Management

. This module is in charge of loading the 

DAA_ISSUER structure (Issuer credentials), needed to verify signatures. 
According to the design described in Section 4.1.2, the application loads 
the Issuer credentials in a buffer. This module expects the buffer 
containing the data encoded according to the TSS specification [3]; 
hence, the engine passes the keys to the TSS which decodes and loads 
them into the appropriate internal data structure.

DAA_SIG Management

. This module manages the DAA signatures. It 

allows to create and destroy a signature and to encode and decode it in 
and from network format. Since TSS specification [3] does not describe 
how to encode the DAA signature, this module relies on the DER-encoding 
provided by OpenSSL.

Application Interface

. This layer allows the engine to offer a control interface 

to the application. Currently, it is not used by this engine, but it is described for 
a more complete overview. It could be used in a future implementation for 
operations such as setting the TPM owner's password.

Beside the engine, also other components are required:

libcrypto

 is a version of OpenSSL libcrypto library that supports the DAA 

cryptographic primitives as described in Section 4.

TSS

 is a library that implements the functions of the Trusted Software Stack as 

described in [3].

6.1.2   Implementation Details

Open_TC Deliverable D03c.6

43/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

6.1.2.1   DAA_METHOD

This sections shows how the engine for implementing the specification of TCG TSS/TPM 
DAA Profile for DAA-TLS is structured. Furthermore this section provides some details 
about the TSS functions that are called by the engine.

int daatcg_sign_verifier_init (int * 

nonce_len

,   unsigned char ** 

nonce

int * 

basename_len

,   unsigned char ** 

basename

,   DAA * 

daa

)

The DAA Verifier initializes her nonce and basename.
The basename can be NULL (and its length 0), which means that no Verifier's 
basename is needed.
Relies on the TSS function Tspi_DAA_Verifier_Init(), then converts Verifier's 
nonce and basename into the internal DAA structure.

Parameters:

nonce_len

 Pointer to the nonce length 

nonce

 Pointer to the nonce buffer 

basename_len

 Pointer to the basename length 

basename

 Pointer to the basename buffer 

daa

 DAA structure reference 

Returns:

0 in case of success 
1 in case of error 

DAA_SIG* daatcg_do_sign (const unsigned char * 

dgst

,   int 

dgst_len

DAA * 

daa

)

Computes a DAA signature on a given digest.
Converts the digest to a TSS_OBJECT_TYPE_HASH, then calls the TSS function 
Tspi_TPM_DAA_Sign(), finally convert the resulting signature to the internal 
OpenSSL format.

Parameters:

dgst

 Digest to be signed 

dgst_len

 Length of the digest 

daa

 DAA structure reference 

Returns:

DAA signature on dgst (in OpenSSL format) 
NULL in case of error 

int daatcg_do_verify (const unsigned char * 

dgst

,   int 

dgst_len

,   const 

DAA_SIG * 

sig

,   DAA * 

daa

)

Verifies a DAA signature.
Converts the digest to a TSS_OBJECT_TYPE_HASH, then calls the TSS function 
Tspi_DAA_VerifySignature().

Parameters:

Open_TC Deliverable D03c.6

44/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

dgst

 Digest to be signed 

dgst_len

 Length of the digest 

sig

 DAA signature 

daa

 DAA structure reference 

Returns:

1 f the signature is correct 
0 if the verification failed 

DAA_KEY* daatcg_key_new (void)

DAA_KEY (platform credential) constructor.
Relies on the TSS function Tspi_Context_CreateObject().

Returns:

a new DAA_KEY (platform credential) structure. 

void daatcg_key_free (DAA_KEY * 

daa

)

DAA_KEY (platform credential) destructor.
Does not free memory allocated by the TSS: this is automatically done when the 
TSS context is closed.

Parameters:

daa

 the DAA_KEY (platform credential) structure. 

DAA_KEY* d2i_daatcg_key (DAA_KEY ** 

a

,   const unsigned char ** 

in

long 

len

)

DAA_KEY (platform credential) deserialization: read a DAA_KEY from a buffer.
Relies on the TSS function Tspi_SetAttribData(). The buffer contains credential 
serialized according to the TSS Specifications.

Parameters:

a

 Pointer to the DAA_KEY (platform credential) structure. 

in

 Pointer to the buffer. 

len

 Buffer length. 

Returns:

the DAA_KEY (platform credential) structure. 

int i2d_daatcg_key (const DAA_KEY * 

a

,   unsigned char ** 

out

)

DAA_KEY (platform credential) serialization: converts a DAA_KEY to a buffer.
Not implemented. Actually not needed by the TLS-DAA Extension.

Parameters:

a

 the DAA_KEY (platform credential) structure. 

out

 Pointer to the buffer. 

Returns:

the buffer length. 

Open_TC Deliverable D03c.6

45/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

DAA_ISSUER* daatcg_issuer_new (void)

DAA_ISSUER (issuer credential) constructor.
Relies on the TSS function Tspi_Context_CreateObject().

Returns:

a new DAA_ISSUER (issuer credential) structure. 

void daatcg_issuer_free (DAA_ISSUER * 

daa

)

DAA_ISSUER (issuer credential) destructor.
Does not free memory allocated by the TSS: this is automatically done when the 
TSS context is closed.

Parameters:

daa

 the DAA_ISSUER (issuer credential) structure. 

DAA_ISSUER* d2i_daatcg_issuer (DAA_ISSUER ** 

a

,   const unsigned char ** 

in

,   long 

len

)

DAA_ISSUER (issuer credential) deserialization: reads a DAA_ISSUER from a 
buffer.
Relies on the TSS function Tspi_SetAttribData(). The buffer contains credential 
serialized according to the TSS Specifications.

Parameters:

a

 Pointer to the DAA_ISSUER (issuer credential) structure. 

in

 Pointer to the buffer. 

len

 Buffer length. 

Returns:

the DAA_ISSUER (issuer credential) structure. 

int i2d_daatcg_issuer (const DAA_ISSUER * 

a

,   unsigned char ** 

out

)

DAA_ISSUER (issuer credential) serialization: converts a DAA_ISSUER to a buffer.
Not implemented. Actually not needed by the TLS-DAA Extension.

Parameters:

a

 the DAA_ISSUER (issuer credential) structure. 

out

 Pointer to the buffer. 

Returns:

the buffer length.

6.1.3   Workflow

The workflow of the usage of the engine for implementing the specification of TCG 
TSS/TPM DAA Profile for DAA-TLS is depicted in Figure 12.

Open_TC Deliverable D03c.6

46/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

1. Both client and server initialize the respective engines by calling the engine 

initialization function.

2. After the engine is initialized, the extension is created and initialized through 

ssl_tlsext_daa_init()

 (see Section 6.1.2 for more details). During this 

operation, the client loads the DAA Platform credentials, while the server loads 
the DAA Issuer credentials. These data will be used later on to make the DAA 
signature and to verify it.

3. The client begins the TLS handshake by sending a ClientHello with the DAA-TLS 

Extension indicating that it wants to use the anonymous authentication. 
According to Section 5.1.4, it sets a proper version.

4. If the server agrees on using the DAA anonymous authentication, the 

ssl_tlsext_daa_server_cb callback()

 is called. This callback function calls 

the 

Tspi_DAA_Verifier_Init()

 function offered by the TSS in order to obtain a 

nonce and the basename for the DAA signature.

5. The server replies with the ServerHello with the DAA-TLS Extension. The 

extension contains the Verifier's nonce and basename that must be used in the 
signature computation.

6. The TLS handshake continues as usually until the client needs to send the 

SupplementalData message that carries the DAA signature.

7. In order to send the SupplementalData message, the client executes the 

ssl_tlsext_daa_client_supp_data_cb()

. This callback function computes the 

DAA signature relying on the 

Tspi_TPM_DAA_Sign()

 function offered by the TSS. 

This signature is sent through the SupplementalData message.

8. The TLS handshake continues as usually until the server and the client exchange 

Open_TC Deliverable D03c.6

47/61

Figure 12: TCG TSS/TPM DAA Profile for DAA-TLS Workflow

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

the Finish message.

9. After the Finish message is exchanged, the server can verify the DAA signature. 

This is accomplished by the 

ssl_tlsext_daa_server_finish_cb()

. This 

callback function verifies the signature relying on the 

Tspi_DAA_VerifySignature()

 function of the TSS.

10.When the handshake is completed, the client and the server can exchange the 

application data.

11.Finally, when the application ends, the TLS channel is closed and the engine 

shutdown.

6.2   Examples

Before running the commands, the DAA credential must be generated. Such creation is 
not covered by this document. For further information, refer to [11].
This example is based on the commands 

s_client

 and 

s_server

 provided by 

OpenSSL. 
Both commands support dynamic loading of engines through the 

-engine

 command 

line option.
The examples in Section 5.3.4, can be adapted to use the TPM-DAA engine in a 
straightforward way.
The server runs:

./openssl s_server -engine tpmdaa

-daa_issuer /usr/local/daatoolkit/etc/daa/daa_issuer.bin

The client runs:

./openssl s_client -tls1 -cert client.pem -engine tpmdaa 

-daa /usr/local/daatoolkit/etc/daa/daa_key.bin

Open_TC Deliverable D03c.6

48/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

7   List of abbreviations

Listing of term definitions and abbreviations used in this document (IT expressions and 
terms from the application domain).

Abbreviation

Explanation

CA

Certification Authority

DAA

Direct Anonymous Attestation

DER

Distinguished Encoding Rules

TCG

Trusted Computing Group

TLS

Transport Layer Security

TPM

Trusted Platform Module

TSS

TCG Software Stack

8   Referenced Documents

/1/ OpenTC D03c.3 SSL/TLS DAA-enhancement specification

/2/ TCG TPM Main Specification (parts 1,2,3)
July 9, 2007,
Version 1.2 Level 2 Revision 103

/3/ TCG Software Stack (TSS) Specification
March 7, 2007, 
Version 1.2, Level 1, Errata A

/4/ IETF RFC 4346, The Transport Layer Security (TLS) Protocol Version 1.1
April, 2006

/5/ IETF RFC 4366, Transport Layer Security (TLS) Extensions
April, 2006

/6/ IETF RFC 4680, TLS Handshake Message for Supplemental Data
September, 2006

/7/ Direct Anonymous Attestation
Ernie Brickell, Jan Camenisch, Liqun Chen
CCS '04: 11th ACM conference on Computer and Communications Security
2004

/8/ Simplified Security Notions of Direct Anonymous Attestation and a Concrete 

Scheme from Pairings
Ernie Brickell, Liqun Chen, Jiangtao Li
Trust08
2008

/9/ Pairings in Trusted Computing

Liqun Chen, Paul Morrissey, Nigel P. Smart
Pairing 2008

Open_TC Deliverable D03c.6

49/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

2008

/10/ Miracl – Multiprecision Integer and Rational Arithmetic C/C++ Library 

(http://ftp.computing.dcu.ie/pub/crypto/miracl.zip)
Mike Scott
2007

/11/ OpenTC D03c.12 OpenSSL engine/DAA enhancement source code and 

documentation

Open_TC Deliverable D03c.6

50/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

9   Appendix. Code Documentation

9.1   General TLS Extensions framework

General framework for TLS Extensions (RFC 4366) and Supplemental Data (RFC 4680) 
support. 

9.1.1   Patch

unsigned char* ssl_add_clienthello_tlsext_general (SSL * 

s

,   unsigned 

char * 

p

,   unsigned char * 

limit

)

Processes the extensions within the SSL object 

s

  and appends their content to 

the buffer 

p

 , thus generating the payload for the Client Hello message.

This is a patch to ssl_add_clienthello_tlsext() (

libssl

 ), from which inherits the 

prototype. : include within 

libssl

 . 

unsigned char* ssl_add_serverhello_tlsext_general (SSL * 

s

,   unsigned 

char * 

p

,   unsigned char * 

limit

)

Processes the extensions within the SSL object 

s

  and appends their content to 

the buffer 

p

 , thus generating the payload for the Server Hello message.

This is a patch to ssl_add_serverhello_tlsext() (

libssl

 ), from which inherits the 

prototype. : include within 

libssl

 . 

int ssl_parse_clienthello_tlsext_general (SSL * 

s

,   unsigned short 

type

unsigned short 

size

,   unsigned char * 

data

)

Handles an extension received in the Client Hello message and specified in TLV 
format (

type

 , 

size

 , 

data

 ), pushes it to the stack of received extensions and 

calls the related callback function.
This is a patch to ssl_parse_clienthello_tlsext() (

libssl

 ), from which inherits the 

prototype. : include within 

libssl

 . : MUST be the last extension type to parse. 

int ssl_parse_serverhello_tlsext_general (SSL * 

s

,   unsigned short 

type

unsigned short 

size

,   unsigned char * 

data

)

Handles an extension received in the Server Hello message and specified in TLV 
format (

type

 , 

size

 , 

data

 ), pushes it to the stack of received General 

Extensions and calls the related callback function.
This is a patch to ssl_parse_serverhello_tlsext() (

libssl

 ), from which inherits 

the prototype. : include within 

libssl

 . : MUST be the last extension type to 

parse. 

int ssl_parse_serverhello_tlsext_general_required (SSL * 

s

)

Checks for required extensions.

This function is used by the client to verify if any extension flagged as "required" 
was not received from the server. In this case the handshake is aborted.
This is a patch to ssl_parse_serverhello_tlsext() (

libssl

 ).

RFC 4366: 

Open_TC Deliverable D03c.6

51/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

In the event that a client requests additional functionality using 
the extended client hello, and this functionality is not supplied 
by the server, the client MAY abort the handshake.

If the client does not want to abort the handshake, it has not to flag the 
extension as required. 

int ssl3_get_server_supp_data (SSL * 

s

)

Receives the server SupplementalData handshake message (if any).
This is a patch to ssl3_connect() (

libssl

 ).

Differences between ssl3_get_server_supp_data() and 
ssl3_get_client_supp_data():
1.

Condition to select the extensions pool:

(ext->received == 1)

  vs 

(ext->server_send == 1)

 .

2.

Supplemental data entry pool: 

ext->client_supp_data

  vs 

ext->server_supp_data

 .

3.

Parameters of 

s->method->ssl_get_message

 .

4.

Call to 

ssl3_get_server_supp_data()

 vs 

ssl3_get_client_supp_data()

int ssl3_send_client_supp_data (SSL * 

s

)

Sends the client SupplementalData handshake message (if any).
This is a patch to ssl3_connect() (

libssl

 ).

Differences between ssl3_send_client_supp_data() and 
ssl3_send_server_supp_data():
1.

Condition to select the extensions pool:

(ext->received == 1)

  vs 

(ext->server_send == 1)

 .

2.

Supplemental data entry pool:

ext->client_supp_data

  vs 

ext>server_supp_data

 .

3.

The callback to invoke: 

ext->client_supp_data_callback()

  vs

ext->server_supp_data_callback

 . 

int ssl_tlsext_general_client_finish_cb (SSL * 

s

)

Invokes the client finish callback for each negotiated extension.
This is a patch to ssl3_connect() (

libssl

 ).

The callbacks are invoked at the end of the handshake, according to RFC 4680: 

Information provided in a supplemental data object MUST be intended 
to be used exclusibely by applications and protocols above the TLS 
protocol layer.  Any such data MUST NOT need to be processed by the 
TLS protocol.

int ssl3_send_server_supp_data (SSL * 

s

)

Sends the server SupplementalData handshake message (if any).
This is a patch to ssl3_accept() (

libssl

 ).

Open_TC Deliverable D03c.6

52/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Differences between ssl3_send_client_supp_data() and 
ssl3_send_server_supp_data():
1.

Condition to select the extensions pool:

(ext->received == 1)

  vs 

(ext->server_send == 1)

 .

2.

Supplemental data entry pool:

ext->client_supp_data

  vs 

ext->server_supp_data

 .

3.

The callback to invoke: 

ext->client_supp_data_callback()

  vs

ext->server_supp_data_callback

 . 

int ssl3_get_client_supp_data (SSL * 

s

)

Receives the client SupplementalData handshake message (if any).
This is a patch to ssl3_accept() (

libssl

 ).

Differences between ssl3_get_server_supp_data() and 
ssl3_get_client_supp_data():
1.

Condition to select the extensions pool:

(ext->received == 1)

  vs 

(ext->server_send == 1)

 .

2.

Supplemental data entry pool:

ext->client_supp_data

  vs 

ext->server_supp_data

 .

3.

Parameters of 

s->method->ssl_get_message

 .

4.

Call to 

ssl3_get_server_supp_data()

 vs 

ssl3_get_client_supp_data()

int ssl_tlsext_general_server_finish_cb (SSL * 

s

)

Invokes the server finish callback for each negotiated extension.
This is a patch to ssl3_accept() (

libssl

 ).

The callbacks are invoked at the end of the handshake, according to RFC 4680:

Information provided in a supplemental data object MUST be intended 
to be used exclusively by applications and protocols above the TLS 
protocol layer.  Any such data MUST NOT need to be processed by the 
TLS protocol.

void ssl_tlsext_general_init_list (SSL * 

s

)

Runs the init function for each extension within the SSL_CTX object.
If the init function returns not NULL, the initialized extension is pushed into the 
stack of extensions available for this TLS connection.
This is called by SSL_new ()

Parameters:

s

 a pointer to a SSL object 

9.1.2   Core

void SSL_TLSEXT_GENERAL_free (TLSEXT_GENERAL * e)

Destructor of a TLSEXT_GENERAL object. It is called by the stack destructor.

void SSL_SUPP_DATA_ENTRY_free (SUPP_DATA_ENTRY * sd)

Open_TC Deliverable D03c.6

53/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Destructor of a SUPP_DATA_ENTRY object. It is called by the stack destructor.

9.1.3   Interface

These functions are detailed in Section 3.2.1.

9.1.4   Application Interface

These functions are detailed in Section 3.2.2.

9.2   Direct Anonymous Attestation

9.2.1   Implementation

DAA_SIG* daa1_sig_new (void)

DAA_SIG constructor for OpenSSL DAA-1 method.
Relies on DAA1_SIG_new().

Returns:

Pointer to a new DAA_SIG structure. 

void daa1_sig_free (DAA_SIG * 

daa

)

DAA_SIG destructor for OpenSSL DAA-1 method.
Relies on DAA1_SIG_free().

Parameters:

daa

 Pointer to the DAA_SIG structure. 

DAA_SIG* d2i_daa1_sig (DAA_SIG ** 

a

,   const unsigned char ** 

in

,   long 

len

)

DAA_SIG deserialization for OpenSSL DAA-1 method: reads a DAA_SIG from a 
buffer.
Relies on d2i_DAA1_SIG().

Parameters:

a

 Pointer to the DAA_SIG structure. 

in

 Pointer to the buffer. 

len

 Buffer length. 

Returns:

Pointer to the DAA_SIG structure. 

int i2d_daa1_sig (const DAA_SIG * 

a

,   unsigned char ** 

out

)

DAA_SIG serialization for OpenSSL DAA-1 method: converts a DAA_SIG to a 
buffer.
Relies on i2d_DAA1_SIG().

Parameters:

a

 Pointer to the DAA_SIG structure. 

out

 Pointer to the buffer. 

Open_TC Deliverable D03c.6

54/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Returns:

The buffer length. 

int daa1_sig_size (const DAA * 

daa

)

DAA_SIG size for OpenSSL DAA-1 method.
Returns an upper bound to the DAA_SIG size. Useful to allocate a buffer that will 
contains a signature, without knowing in advantage what the signature will be.

Parameters:

daa

 Pointer to the DAA structure. 

Returns:

The DAA_SIG size. 

DAA_SIG* daa3_sig_new (void)

DAA_SIG constructor for OpenSSL DAA-3 method.
Relies on DAA3_SIG_new().

Returns:

Pointer to a new DAA_SIG structure. 

void daa3_sig_free (DAA_SIG * 

daa

)

DAA_SIG destructor for OpenSSL DAA-3 method.
Relies on DAA3_SIG_free().

Parameters:

daa

 Pointer to the DAA_SIG structure. 

DAA_SIG* d2i_daa3_sig (DAA_SIG ** 

a

,   const unsigned char ** 

in

,   long 

len

)

DAA_SIG deserialization for OpenSSL DAA-3 method: reads a DAA_SIG from a 
buffer.
Relies on d2i_DAA3_SIG().

Parameters:

a

 Pointer to the DAA_SIG structure. 

in

 Pointer to the buffer. 

len

 Buffer length. 

Returns:

Pointer to the DAA_SIG structure. 

int i2d_daa3_sig (const DAA_SIG * 

a

,   unsigned char ** 

out

)

DAA_SIG serialization for OpenSSL DAA-3 method: converts a DAA_SIG to a 
buffer.
Relies on i2d_DAA3_SIG().

Parameters:

a

 Pointer to the DAA_SIG structure. 

out

 Pointer to the buffer. 

Open_TC Deliverable D03c.6

55/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Returns:

The buffer length. 

int daa3_sig_size (const DAA * 

daa

)

DAA_SIG size for OpenSSL DAA-3 method.
Returns an upper bound to the DAA_SIG size. Useful to allocate a buffer that will 
contains a signature, without knowing in advantage what the signature will be.

Parameters:

daa

 Pointer to the DAA structure. 

Returns:

The DAA_SIG size. 

int daa3_sign_verifier_init (int * 

nonce_len

,   unsigned char ** 

nonce

int * 

basename_len

,   unsigned char ** 

basename

,   DAA * 

daa

)

The DAA Verifier initializes her nonce and basename.
The basename can be NULL (and its length 0), which means that no Verifier's 
basename is needed.
This fake implementation output fixed nonce and basename.

Parameters:

nonce_len

 Pointer to the nonce length 

nonce

 Pointer to the nonce buffer 

basename_len

 Pointer to the basename length 

basename

 Pointer to the basename buffer 

daa

 DAA structure reference 

Returns:

0 in case of success 
1 in case of error 

DAA_SIG* daafake_sig_new (void)

DAA_SIG constructor for OpenSSL DAA-FAKE method.
Relies on DAAFAKE_SIG_new().

Returns:

Pointer to a new DAA_SIG structure. 

void daafake_sig_free (DAA_SIG * 

daa

)

DAA_SIG destructor for OpenSSL DAA-FAKE method.
Relies on DAAFAKE_SIG_free().

Parameters:

daa

 Pointer to the DAA_SIG structure. 

DAA_SIG* d2i_daafake_sig (DAA_SIG ** 

a

,   const unsigned char ** 

in

long 

len

)

DAA_SIG deserialization for OpenSSL DAA-FAKE method: reads a DAA_SIG from a 

Open_TC Deliverable D03c.6

56/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

buffer.
Relies on d2i_DAAFAKE_SIG().

Parameters:

a

 Pointer to the DAA_SIG structure. 

in

 Pointer to the buffer. 

len

 Buffer length. 

Returns:

Pointer to the DAA_SIG structure. 

int i2d_daafake_sig (const DAA_SIG * 

a

,   unsigned char ** 

out

)

DAA_SIG serialization for OpenSSL DAA-FAKE method: converts a DAA_SIG to a 
buffer.
Relies on i2d_DAAFAKE_SIG().

Parameters:

a

 Pointer to the DAA_SIG structure. 

out

 Pointer to the buffer. 

Returns:

The buffer length. 

int daafake_sig_size (const DAA * 

daa

)

DAA_SIG size for OpenSSL DAA-FAKE method.
Returns an upper bound to the DAA_SIG size. Useful to allocate a buffer that will 
contains a signature, without knowing in advantage what the signature will be.

Parameters:

daa

 Pointer to the DAA structure. 

Returns:

The DAA_SIG size. 

int daafake_sign_verifier_init (int * 

nonce_len

,   unsigned char ** 

nonce

,   int * 

basename_len

,   unsigned char ** 

basename

,   DAA * 

daa

)

The DAA Verifier initializes her nonce and basename.
The basename can be NULL (and its length 0), which means that no Verifier's 
basename is needed.
This fake implementation output fixed nonce and basename.

Parameters:

nonce_len

 Pointer to the nonce length 

nonce

 Pointer to the nonce buffer 

basename_len

 Pointer to the basename length 

basename

 Pointer to the basename buffer 

daa

 DAA structure reference 

Open_TC Deliverable D03c.6

57/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Returns:

0 in case of success 
1 in case of error 

DAA_SIG* daafake_do_sign (const unsigned char * 

dgst

,   int 

dgst_len

DAA * 

daa

)

Computes a DAA signature on a given digest.
This fake implementation returns a BIGNUM containing the bitstream of the 
supplied digest.

Parameters:

dgst

 Digest to be signed 

dgst_len

 Length of the digest 

daa

 DAA structure reference 

Returns:

DAA signature on dgst (in OpenSSL format) 
NULL in case of error 

int daafake_do_verify (const unsigned char * 

dgst

,   int 

dgst_len

const DAA_SIG * 

daasig

,   DAA * 

daa

)

Verifies a DAA signature.
This fake implementation checks whether the signature and digest are equal.

Parameters:

dgst

 Digest to be signed 

dgst_len

 Length of the digest 

daasig

 DAA signature 

daa

 DAA structure reference 

Returns:

1 f the signature is correct 
0 if the verification failed 

const DAA_METHOD* DAA_OpenSSL (void)

Returns DAAFAKE as the default OpenSSL DAA method. 

9.2.2   Method Interface

DAA* DAA_new_method (ENGINE * 

engine

)

Returns a new DAA structure, possibly from a supplied engine. 

Parameters:

engine

 Pointer to the engine supporting DAA, or NULL 

Returns:

Pointer to the new DAA structure 

int DAA_set_method (DAA * 

daa

,   const DAA_METHOD * 

meth

)

Open_TC Deliverable D03c.6

58/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

Associates the supplied DAA structure with the supplied DAA method. 

Parameters:

daa

 Pointer to the DAA structure 

meth

 Pointer to the DAA_METHOD structure 

Returns:

1 in case of success 

const DAA_METHOD* DAA_get_default_method (void)

Gets the default DAA method. 

Returns:

Pointer to the default DAA_METHOD structure 

void DAA_set_default_method (const DAA_METHOD * 

meth

)

Sets the default DAA method. 

Parameters:

meth

 The method to set as default 

const DAA_METHOD* DAA_OpenSSL (void)

Returns the default OpenSSL DAA method. 

Returns:

Pointer to a DAA_METHOD structure
Returns DAAFAKE as the default OpenSSL DAA method. 

DAA_SIG* DAA_do_sign (const unsigned char * 

dgst

,   int 

dgst_len

,   DAA * 

daa

)

Computes the DAA signature (DAA_SIG structure) of the given hash value using 
the DAA method supplied and returns the created signature.

Parameters:

dgst

 Buffer containing the hash value 

dgst_len

 Length of the hash value buffer 

daa

 Pointer to the DAA structure containing a reference to the DAA method 

Returns:

Pointer to the DAA_SIG structure created 
NULL if an error occurred 

int DAA_do_verify (const unsigned char * 

dgst

,   int 

dgst_len

,   const 

DAA_SIG * 

sig

,   DAA * 

daa

)

Verifies that the supplied signature (DAA_SIG structure) is a valid DAA signature 
of the supplied hash value using the supplied DAA method.

Parameters:

dgst

 Buffer containing the hash value 

dgst_len

 Length of the hash value buffer 

sig

 Pointer to the DAA_SIG structure 

Open_TC Deliverable D03c.6

59/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

daa

 Pointer to the DAA structure containing a reference to the DAA method 

Returns:

1 if the signature is correct 
0 if the signature is incorrect 
-1 in case of error 

9.2.3   Application Interface

These functions are detailed in Section 4.2.1.

9.3   TLS DAA-Enhancement

9.3.1   Core

These functions are detailed in Section 5.1.3.1.

9.3.2   Application Interface

These functions are detailed in Section 5.2.1.

9.4   Engine TPM-DAA

9.4.1   TSS Binding Utilities

BYTE* bi_export_dynamic (TSS_HCONTEXT 

tsp

,   BIGNUM const * 

op1

unsigned int 

obuf_bytes

)

Converts an OpenSSL BIGNUM in a BYTE buffer.
Allocates a buffer of the requested size and pads with 0 the unused bytes.
Is a TSS context is available, uses calloc_tspi() to allocate memory within the 
TSS context; the memory is deallocated when the context is closed.

Parameters:

tsp

 TSS context 

op1

 The BIGNUM to convert 

obuf_bytes

 The number of bytes to allocate 

Returns:

The buffer containing the BIGNUM representation 

TSS_DAA_SIGNATURE* ossl2tss_DAA_SIG (TSS_HCONTEXT 

tsp

,   DAA1_SIG * 

daasig

)

Converts a DAA signature from the OpenSSL internal form to the TSS form 
TSS_DAA_SIGNATURE.
Uses calloc_tspi() to allocate memory within the TSS context. The memory is 
deallocated when the context is closed.

Parameters:

Open_TC Deliverable D03c.6

60/61

background image

 

 

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

tsp

 TSS context 

daasig

 DAA signature (in OpenSSL internal form) 

Returns:

DAA signature (in TSS form) 

DAA1_SIG* tss2ossl_DAA_SIG (DAA1_SIG ** 

daasig

,   TSS_DAA_SIGNATURE * 

daaSignature

)

Converts a DAA signature from the TSS form TSS_DAA_SIGNATURE to the 
OpenSSL internal form.

Parameters:

daasig

 Pointer to DAA signature (in OpenSSL internal form)

daaSignature

 DAA signature (in TSS form)

Returns:

DAA signature (in OpenSSL internal form)

void print_error (char * 

str

,   TSS_RESULT 

result

)

Outputs an error message.

Parameters:

str

 The name of the TSS function generating the error.

result

 The error result.

9.4.2   DAA_METHOD

These functions are detailed in Section 6.1.2.1.

Open_TC Deliverable D03c.6

61/61

background image

 

 

D03c.12 OpenSSL engine/DAA enhancement 

source code and documentation

Project number

IST-027635

Project acronym

Open_TC

Project title

Open Trusted Computing

Deliverable type

Internal deliverable

Deliverable reference number

IST-027635/D03c.12/FINAL | 1.00

Deliverable title

OpenSSL engine/DAA enhancement source 
code and documentation

WP contributing to the deliverable

WP03c

Due date

Oct 2008 - M36

Actual submission date

May 15, 2009 

Responsible Organisation

POL

Authors

Emanuele Cesena, Davide Vernizzi, Gianluca 
Ramunno

Abstract

This companion document describes the 
procedures for building, installing and testing 
the toolkit with DAA-enhancement (group 
authentication) for TLS implemented upon 
OpenSSL.

Keywords

OPEN_TC, TPM, TLS, OpenSSL, DAA

Dissemination level

Public

Revision

FINAL | 1.00

Instrument

IP

Start date of the 
project

1

st

 November 2005

Thematic Priority

IST

Duration

42 months

 

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

Table of Contents

1  Introduction.................................................................................................................3
2  Prerequisites...............................................................................................................4
3  Structure of the Package.............................................................................................5
4  OpenSSL with DAA Support.........................................................................................6

4.1  Building from the Source........................................................................................6
4.2  Testing the Plain OpenSSL......................................................................................6
4.3  Testing the DAA-TLS Extension..............................................................................7

5  Trousers with DAA support..........................................................................................9

5.1  Building from the source........................................................................................9
5.2  Configuring the DAA-Enhanced Trousers..............................................................10
5.3  Testing the Installation and Creating DAA Credentials.........................................11

6  Engine TPM-DAA........................................................................................................14

6.1  Building from the source......................................................................................14
6.2  Testing the DAA-TLS Extension, TCG TSS/TPM Profile..........................................14

7  Engine Miracl.............................................................................................................16

7.1  Building from the source......................................................................................16
7.2  Creating DAA Credentials for Engine Miracl..........................................................16
7.3  Testing the DAA-TLS Extension, with Pairing-based DAA......................................17

8  Legacy Mode: Apache Web Server............................................................................18

8.1  Rebuilding OpenSSL with DAA Support in Legacy Mode.......................................19
8.2  Installing and Configuring Apache Web Server.....................................................20
8.3  Testing the Advanced Scenario............................................................................20

9  List of abbreviations..................................................................................................23
10  Referenced Documents...........................................................................................23

Open_TC Deliverable 03c.12

2/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

1   Introduction

Secure channels allow two or more entities to communicate securely over insecure 
networks using cryptographic primitives to provide confidentiality, integrity and 
authentication of network messages. Trusted Computing (TC) technology allows 
extending the network protection to the peers involved in the communication. TC, in 
facts, allows a platform with TC-enabled hardware to provide cryptographic proofs 
about its behavior. Using this information, the counterpart can have assurance about 
the security of the message not only while it is transmitted, but also after it is received 
on the TC-platform.
Among the primitives available to a TC-platform, Direct Anonymous Attestation (DAA) 
[7] is a privacy-friendly protocol that was designed to overcome the privacy issues of 
the Privacy CA. In particular, the main problem related to the use of that particular CA, 
is that the latter can disclose sensitive data that could allow a third party to link 
different remote attestation made by the same platform,  thus breaking the platform's 
privacy. DAA overcomes this problem using a zero-knowledge proof.
In [1], a TLS DAA-Enhancement is proposed to exploit DAA as a mechanism to achieve 
(client) anonymous authentication. Furthermore, based on the Trusted Platform 
Module (TPM) and Trusted Software Stack (TSS), a TCG TSS/TPM profile is specified to 
exploit the DAA-related functions available in the TC technology. In [2] the design for 
an implementation (made using OpenSSL) of the TLS DAA-Enhancement is given, 
including the TCG TSS/TPM profile.
This document describes in detail how to configure, install and test the implementation 
of the design specified in [2], i.e. the software whose this document is companion. In 
the sequel, DAA Toolkit refers to the set of programs released.

Open_TC Deliverable 03c.12

3/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

2   Prerequisites

DAA Toolkit package requires TPM 1.2 with the EK certificate embedded; it has been 
tested with OpenSuSE 11.1 running on platforms equipped with the Infineon TPM only 
(HP Compaq nx6325 and nw8440). Many TPM vendors do not provide the EK 
certificate; the DAA operations do not work on platforms equipped with such TPMs. 
Platforms with more recent revisions of Infineon TPMs (requiring authorization for NV 
access) may not work as well.
In addition to a default installation, the following packages are required to build the 
DAA Toolkit:

autoconf

automake

gcc

gcc-c++

gtk2-devel

libtool

trousers

It is assumed that Trousers is already installed (and the daemon 

tcsd

) running, and 

TPM Ownership has already been taken using ASCII encoding for the secrets (e.g. using 
Trousers tpm-tools).
The installation procedure has been tested on a system where the following packages 
(that could interfere with DAA Toolkit) were installed:

openssl-devel

trousers-devel

Open_TC Deliverable 03c.12

4/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

3   Structure of the Package

The DAA Toolkit package contains the following directories:

openssl-daa

, contains OpenSSL v0.9.9 Snapshot 20081210 and a patch to 

support DAA, TLSEXT and TLS-DAA as described in [2].

trousers-daa

, contains Trousers 0.3.0 CVS-20070701, the associated testsuite, 

and patches to support DAA. In addition, a program 

getcert3

 to extract the EK 

certificate is available; the certificate is necessary to properly configure 
Trousers. The patches and 

getcert3

 were written by Hal Finney.

engine-tpm-daa

, contains an engine which uses TSS/TPM capabilities for DAA. It 

implements the TCG TSS/TPM Profile defined in [1].

engine-miracl-daa

, contains an engine which uses MIRACL [11] cryptographic 

library to implement an advanced (pairing-based) version of the DAA protocol, 
described in [10].

apache-daa

, contains a version of 

apache+mod_ssl

 recompiled for OpenSSL 

v0.9.9. This will demonstrate the use of DAA Toolkit with legacy applications.

In the sequel it is assumed that the DAA Toolkit tarball has been extracted into a 
temporary directory 

TEMPDIR

, where 

TEMPDIR 

is a full path including the “/” root 

directory.
Furthermore, the DAA Toolkit will be installed in the system under the 

/usr/local/daatoolkit

 location.

After compilation and installation of the whole DAA Toolkit, all the content of 

TEMPDIR 

can be removed still allowing to use the installed programs. Moreover, in order to 
cleanly uninstall the DAA Toolkit it is sufficient to delete the content of 

/usr/local/daatoolkit

. Only apache needs to be uninstalled.

Superuser privileges are required at some steps (usually 

make install

 command). For 

simplicity it is assumed that the whole process is performed under the 'root' account.

Open_TC Deliverable 03c.12

5/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

4   OpenSSL with DAA Support

In this section OpenSSL will be patched to support DAA, TLSEXT and DAA-TLS (refer to 
[2] for more details). A test to verify the correctness of the installation follows.
The working directory is 

TEMPDIR/openssl-daa

, and installed files go under 

/usr/local/daatoolkit

.

4.1   Building from the Source

1. Unpack the source 

openssl-SNAP-20081204.tar.gz

:

cd TEMPDIR/openssl-daa
tar -xvvzf openssl-SNAP-20081204.tar.gz

2. Apply the DAA-TLS patch (which includes TLSEXT framework, DAA primitives and 

DAA-TLS Extension):

cd openssl-SNAP-20081204
patch -p1 < ../openssl_daa_tls_patch.diff

3. Prepare OpenSSL:

./config --prefix=/usr/local/daatoolkit -shared

4. Compile and install

make
make install

5. Copy server and client certificates into the 

bin

 directory within the installation 

path. These files are needed by OpenSSL 

s_server

 and 

s_client

 commands.

It is also possible to generate and/or use different certificates (while the client 
certificate should be a self-signed certificate that will be used by the DAA-TLS 
Extension).

cd apps
cp server.pem client.pem /usr/local/daatoolkit/bin
cd ../..

4.2   Testing the Plain OpenSSL

1. Move to the 

bin

 directory within the installation path:

cd /usr/local/daatoolkit/bin

2. Begin by testing plain OpenSSL commands, without the DAA-TLS Extension.

Run OpenSSL 

s_server

:

./openssl s_server

Open_TC Deliverable 03c.12

6/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

3. In another shell window, in the same working directory, run OpenSSL 

s_client

:

./openssl s_client -tls1 [-cert client.pem]

The command line option 

-tls1

 forces the use of TLSv1 protocol; the normal 

behavior of OpenSSL would be to open a SSLv3 connection and eventually 
switch to TLSv1 protocol if the server requires it.
The default behavior is not suitable for testing the extensions since they are 
only defined for the TLS protocol. Optionally, one can specify a client certificate 
with the 

-cert

 command line option to trigger the TLS client authentication.

4. Type something in either window and verify that the transmission between 

client and server succeeded.

5. Stop the client and the server by pressing CTRL+C and close the second shell 

window.

4.3   Testing the DAA-TLS Extension

1. Create dummy credentials. The default dummy DAA implementation, included in 

OpenSSL only for testing purpose, actually does not use credentials, but 
requires files to be present. These files will be substituted with actual DAA 
credentials in the sequel:

mkdir -p /usr/local/daatoolkit/etc/daa/
touch /usr/local/daatoolkit/etc/daa/daa_issuer.bin
touch /usr/local/daatoolkit/etc/daa/daa_cred.bin

2. Move to the 

bin

 directory within the installation path:

cd /usr/local/daatoolkit/bin

3. Run OpenSSL 

s_server

 specifying, via the command line option 

-daa_issuer

the name of the file containing the DAA Issuer credentials needed to verify the 
DAA signature:

./openssl s_server \

-daa_issuer /usr/local/daatoolkit/etc/daa/daa_issuer.bin

4. In another shell window, in the same working directory, run OpenSSL 

s_client

:

./openssl s_client -tls1 -cert client.pem \

-daa /usr/local/daatoolkit/etc/daa/daa_cred.bin

The command line option 

-cert

 is now mandatory since the TLS DAA-

Enhancement [1] requires the client authentication through a (self-signed) client 
certificate. Currently, if the client certificate is not set, the client does not send 
any certificate and the server closes the handshake with an error message.
The command line option 

-daa

 enables the DAA-TLS Extension on the client and 

accepts as argument the name of the file containing the DAA Platform's 
credential necessary to compute the DAA signature.

5. The connection is established. Some debug messages [DBG] DAA-TLS show that 

Open_TC Deliverable 03c.12

7/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

the DAA-TLS Extension is actually used (compare the output of the two 
commands with the one in the previous section), i.e. the anonymous 
authentication has been performed.

6. Type something in either window and verify that the transmission between 

client and server succeeded.

7. Stop the client and the server by pressing CTRL+C and close the second shell 

window.

Open_TC Deliverable 03c.12

8/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

5   Trousers with DAA support

In this section a proper version of Trousers will be patched to support DAA. The 
associated testsuite is run to verify the correctness of the installation. As a side effect 
of the test, DAA credentials will be generated to be used in the following.
The working directory is 

TEMPDIR/trousers-daa

, and installed files go under 

/usr/local/daatoolkit

.

5.1   Building from the source

1. You MUST have the ownership of the TPM before continuing.

It is also necessary to shut down Trousers:

service tcsd stop

2. Unpack the two tarballs containing Trousers and the testsuite (CVS version 

dated 2007-07-01):

cd TEMPDIR/trousers-daa
tar -xvvzf trousers-20070701.tar.gz
tar -xvvzf testsuite-20070701.tar.gz

3. Apply Hal Finney's DAA patches:

cd trousers 
patch -p1 < ../trousers_daa_patch.diff
cd ../testsuite
patch -p1 < ../testsuite_daa_patch.diff
cd ..

4. Compile and install Trousers:

cd trousers
sh boostrap.sh
CFLAGS="-Wno-error=format" ./configure --enable-loadkey2 \
 

--enable-debug --prefix=/usr/local/daatoolkit \

 

--with-openssl=/usr/local/daatoolkit 

make 
make install
cd ..

Trousers is compiled in debug mode (

--enable-debug

 option) to better follow 

what happens at the TSS/TPM level. In particular when the TPM will do DAA-
related computations, the debug mode allows following the process evolution 
step by step.

5. Compile the testsuite

export CFLAGS="-I/usr/local/daatoolkit/include
 

-L/usr/local/daatoolkit/lib -lcrypto"

cd testsuite/tcg/common
make

Open_TC Deliverable 03c.12

9/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

cd ../highlevel/daa
make

Since the compilation of the whole testsuite is not completely working, only the 
DAA testsuite, which depends upon 

common

, is compiled.

6. Reset the environment

export CFLAGS=""
cd ../../../..

5.2   Configuring the DAA-Enhanced Trousers

1. Compile 

getcert3

, which extracts the EK certificate from the TPM.

Note that this program is not installed under the installation path, so it will be 
removed when deleting the source package tree.

cd TEMPDIR/trousers-daa
export LD_LIBRARY_PATH=/usr/local/daatoolkit/lib 
gcc -o getcert3 getcert3.c -Itrousers/include \
 -L/usr/local/daatoolkit/lib -ltspi -lcrypto

2. Run the tcsd daemon. This must be done in an independent root shell window:

export LD_LIBRARY_PATH=/usr/local/daatoolkit/lib
cd /usr/local/daatoolkit/sbin
./tcsd -f

3. Run getcert3, which extracts the EK certificate from the TPM:

./getcert3 ek.cert

4. Stop the tcsd daemon. Press CTRL-C in the related window.
5. Take a look at the certificate data (using the standard OpenSSL):

openssl x509 -text -noout -inform DER -in ek.cert

6. Save the EK certificate within the installation path:

cp ek.cert /usr/local/daatoolkit/etc/

7. Edit the Trousers' configuration file:

/usr/local/daatoolkit/etc/tcsd.conf

and set (by uncommenting and completing the line):

endorsement_cred = /usr/local/daatoolkit/etc/ek.cert

8. Prepare the proper file for PS database (this step is needed because the 

ownership is already taken).

Open_TC Deliverable 03c.12

10/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

1. Alternative if SRK password is not null:

cp trousers/dist/system.data.auth \

/usr/local/daatoolkit/var/lib/tpm/system.data

2. Alternative if SRK password set to null or to WELL_KNOWN_SECRET:

cp trousers/dist/system.data.noauth \

/usr/local/daatoolkit/var/lib/tpm/system.data

9. Run the tcsd daemon.

Open an independent root shell window and run the commands:

export LD_LIBRARY_PATH=/usr/local/daatoolkit/lib
cd /usr/local/daatoolkit/sbin
./tcsd -f

Since Trousers is required for the whole demonstration described in this 
document, this shell window MUST remain open with the tcsd daemon running 
(the option 

-f

 starts the daemon in foreground and is useful for testing 

purposes).

5.3   Testing the Installation and Creating DAA Credentials

As already mentioned, in this section commands from the testsuite are run to verify 
the correct installation of Trousers, with DAA support.
As a side effect, these commands will produce DAA Issuer and Platform credentials, 
that will be stored for future usage.
The use of the command line tool 

time

 prepended to all following commands is 

optional but its usage is interesting because it gives information on the time needed 
for the computation (sometimes tens of seconds): this demonstrates that DAA is a very 
expensive cryptographic operation.
It is possible to run the commands more than once, in order to create multiple Issuer 
and/or Platform credentials.
Note that these programs are not installed under the installation path, so they will be 
removed when deleting the source package tree.

1. Prepare to test:

cd TEMPDIR/trousers-daa
cd testsuite/tcg/highlevel/daa
export LD_LIBRARY_PATH=/usr/local/daatoolkit/lib
export TESTSUITE_OWNER_SECRET=xxxxxx

where 

xxxxxx

 must be substituted with the TPM owner secret.

2. Create the DAA Issuer credentials:

time ./Tspi_DAA_Issuer_GenerateKey "IssuerBaseName" \

authkeys.bin tpm_daa_issuer.bin skissuer.bin prfissuer.bin

Open_TC Deliverable 03c.12

11/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

where 

IssuerBaseName

 is a string containing the Issuer base name, 

authkeys.bin

 is the file to store the authentication keys, 

tpm_daa_issuer.bin 

is the file to store the DAA Issuer credentials (public key), 

skissuer.bin

 is the 

file to store the DAA Issuer private key and 

prfissuer.bin

 is the file to store 

the proof of correctness of the DAA Issuer credentials.
The most important file for the following is 

tpm_daa_issuer.bin

, that will be 

needed to verify DAA signatures.

3. Optionally, for testing, verify the correctness of the DAA Issuer credentials, 

given the related proof of correctness. This operation should be done once by 
any user (and verifier) that receives the DAA Issuer credentials. 

time ./Tspi_DAA_IssuerKeyVerify tpm_daa_issuer.bin prfissuer.bin

4. Perform a DAA Join. This will create the DAA Platform credential.

time ./Tspi_DAA_Join authkeys.bin tpm_daa_issuer.bin \

skissuer.bin tpm_daa_cred.bin

where 

authkeys.bin

 contains the authentication keys, 

tpm_daa_issuer.bin 

the Issuer credential, 

skissuer.bin

 the Issuer private key. Finally 

tpm_daa_cred.bin

 is the file to store the generated DAA Platform credentials. 

The file 

tpm_daa_cred.bin

 is necessary to compute a DAA signature. Note that 

part of this credential is bound to the TPM, i.e. the TPM owner secret will be 
necessary to access this credential.

5. Optionally, for testing, compute a DAA signatures on a input string. The 

command also verifies the correctness of the signature.

time ./Tspi_DAA_SignData tpm_daa_issuer.bin tpm_daa_cred.bin \

"data to sign"

where 

tpm_daa_issuer.bin

 is the DAA Issuer credentials necessary to the 

verification, 

tpm_daa_cred.bin

 is the DAA Platform credentials used to compute 

the DAA signature and 

data to sign

 is the input string that is signed.

6. Optionally, for testing, compute a DAA signature over an AIK. This program 

automatically generates a new AIK, DAA-signs it and verifies the signature. It 
requires the SRK secret.
Signing AIKs is one of the most important usage of DAA in the TC context, 
however it is not further addressed in this document.

export TESTSUITE_SRK_SECRET=xxxxxx
time ./Tspi_DAA_SignKey tpm_daa_issuer.bin tpm_daa_cred.bin

where 

tpm_daa_issuer.bin

 is the DAA Issuer credentials necessary to the 

verification, 

tpm_daa_cred.bin

 is the DAA Platform credentials used to compute 

the DAA signature.

7. Finally save the created DAA credentials to 

/usr/local/daatoolkit/etc/daa 

for future usage:

Open_TC Deliverable 03c.12

12/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

cp tpm_daa_issuer.bin /usr/local/daatoolkit/etc/daa
cp tpm_daa_cred.bin /usr/local/daatoolkit/etc/daa
cd ../../../..

Open_TC Deliverable 03c.12

13/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

6   Engine TPM-DAA

In this section an Engine TPM-DAA is built and installed. This is then used in 
conjunction with OpenSSL to implement the TCG TPM/TSS Profile of the TLS DAA-
Enhancement [1].
The working directory is 

TEMPDIR/engine-tpm-daa

, and installed files go under 

/usr/local/daatoolkit

.

6.1   Building from the source

1. Unpack the source code:

cd TEMPDIR/engine-tpm-daa
tar -xvvzf engine-tpm-daa-1.0.0.tar.gz

2. Compile and install the engine:

cd engine-tpm-daa-1.0.0
./configure --with-ssl=/usr/local/daatoolkit \

--with-tss=/usr/local/daatoolkit \
--libdir=/usr/local/daatoolkit/lib/engines

make
make install
cd ..

6.2   Testing the DAA-TLS Extension, TCG TSS/TPM Profile

1. Link the TPM-related credentials:

cd /usr/local/daatoolkit/etc/daa/
rm daa_*
ln -s tpm_daa_cred.bin daa_cred.bin
ln -s tpm_daa_issuer.bin daa_issuer.bin

2. Move to the 

bin

 directory within the installation path:

cd /usr/local/daatoolkit/bin

3. Run OpenSSL 

s_server

 specifying the usage of the Engine TPM-DAA via the 

command line option 

-engine tpmdaa

:

export LD_LIBRARY_PATH=/usr/local/daatoolkit/lib
./openssl s_server -engine tpmdaa \ 

-daa_issuer /usr/local/daatoolkit/etc/daa/daa_issuer.bin

4. In another shell window, in the same working directory, run OpenSSL 

s_client 

specifying the usage of the Engine TPM-DAA via the command line option 

-engine tpmdaa

Note that on the client side the TPM owner secret is required to access the DAA 
Platform credentials.

Open_TC Deliverable 03c.12

14/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

export LD_LIBRARY_PATH=/usr/local/daatoolkit/lib
export TESTSUITE_OWNER_SECRET=xxxxxx
./openssl s_client -tls1 -cert client.pem -engine tpmdaa \

-daa /usr/local/daatoolkit/etc/daa/daa_cred.bin

where 

xxxxxx

 must be substituted with the TPM owner secret.

5. The connection is established. Additional debug messages from the TSS notify 

the progress of the TPM DAA-Sign operation on the client side.

6. Type something in either window and verify that the transmission between 

client and server succeeded.

7. Stop the client and the server by pressing CTRL+C and close the second shell 

window.

Open_TC Deliverable 03c.12

15/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

7   Engine Miracl

In this section an Engine Miracl is built and installed. This is then used in conjunction 
with OpenSSL to show an advanced use of TLS DAA-Enhancement [1] with pairing-
based DAA [10].
In order to generate credentials suitable for the demonstration, a program 
implementing a complete run of the full DAA protocol (Setup, Join, Sign and Verify) is 
also installed.
The working directory is 

TEMPDIR/engine-miracl-daa

, and installed files go under 

/usr/local/daatoolkit

.

Note that MIRACL is NOT free software and for commercial use a license is required. 
Check the file 

first.txt

 distributed with MIRACL for additional details.

7.1   Building from the source

1. Unpack the source code:

cd TEMPDIR/engine-miracl-daa
tar -xvvzf engine-miracl-daa-1.0.0.tar.gz

2. This engine expects a full MIRACL distribution withing the 

miracl/

 directory.

MIRACL is not distributed as part of the Engine Miracl for license reasons: 
MIRACL is not free software.
1. Download 

miracl.zip

 from:

http://www.shamus.ie/index.php?page=Downloads

OR use 

miracl.zip

 in the distribution directory.

2. Unpack and build MIRACL (refer to the documentation file 

linux.txt 

distributed with MIRACL for additional details):

cd engine-miracl-daa-1.0.0/miracl
unzip -j -aa -L -o ../../miracl.zip
bash linux
cd ..

3. Compile and install the engine:

./configure --with-ssl=/usr/local/daatoolkit \

--prefix=/usr/local/daatoolkit \
--libdir=/usr/local/daatoolkit/lib/engines

make
make install
cd ..

7.2   Creating DAA Credentials for Engine Miracl

1. Move to the 

bin

 directory within the installation path:

Open_TC Deliverable 03c.12

16/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

cd /usr/local/daatoolkit/bin

2. Run the 

daacred

 program, which shows a complete run of the full DAA protocol 

(Setup, Join, Sign and Verify) with random parameters and save Issuer 
credentials in 

mr_daa_issuer.bin

 and Platform credentials in 

mr_daa_cred.bin

:

export LD_LIBRARY_PATH=/usr/local/daatoolkit/lib
./daacred

3. Copy the generated credentials to 

/usr/local/daatoolkit/etc/daa

 for future 

usage:

cp mr_daa_issuer.bin /usr/local/daatoolkit/etc/daa
cp mr_daa_cred.bin /usr/local/daatoolkit/etc/daa

7.3   Testing the DAA-TLS Extension, with Pairing-based DAA

1. Link the Miracl-related credentials:

cd /usr/local/daatoolkit/etc/daa/
rm daa_*
ln -s mr_daa_cred.bin daa_cred.bin
ln -s mr_daa_issuer.bin daa_issuer.bin

2. Move to the 

bin

 directory within the installation path:

cd /usr/local/daatoolkit/bin

3. Run OpenSSL 

s_server

 specifying the usage of the Engine Miracl via the 

command line option 

-engine miracl

:

export LD_LIBRARY_PATH=/usr/local/daatoolkit/lib
./openssl s_server -engine miracl \ 

-daa_issuer /usr/local/daatoolkit/etc/daa/daa_issuer.bin

4. In another shell window, in the same working directory, run OpenSSL 

s_client 

specifying the usage of the Engine Miracl via the command line option 

-engine 

miracl

:

export LD_LIBRARY_PATH=/usr/local/daatoolkit/lib
./openssl s_client -tls1 -cert client.pem -engine miracl

-daa /usr/local/daatoolkit/etc/daa/daa_cred.bin

5. The connection is established. Additional debug messages show the engine is 

working.

6. Type something in either window and verify that the transmission between 

client and server succeeded.

7. Stop the client and the server by pressing CTRL+C and close the second shell 

window.

Open_TC Deliverable 03c.12

17/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

8   Legacy Mode: Apache Web Server

This section presents an advanced usage scenario for the TLS DAA-Enhancement with 
legacy applications, namely Apache web server and a web browser. An HTTPS 
connection will be established where a DAA-TLS Extension is expected during the TLS 
handshake. For simplicity we refer to this as HTTPS DAA-Enhanced connection in the 
sequel.
In order to work with legacy, i.e. unmodified, applications the TLS DAA-Enhancement 
supports the so called Legacy Mode. As detailed in [2], when the TLS DAA-
Enhancement is compiled in Legacy Mode, it automatically enables the DAA-TLS 
Extension on both client and server and sets default values for the name of the files 
containing DAA Issuer and Platform credentials.
In more detail, two roles participate in the following scenario: a Server and a Client.
The Server runs an unmodified version of Apache web server listening on the standard 
HTTPS port, which relies on the OpenSSL with TLS DAA-Enhancement in Legacy Mode 
for HTTPS DAA-Enhanced connections: when the HTTPS channel is opened, i.e. the TLS 
handshake takes place, a DAA-TLS Extension is expected from the Client.
The Client runs a web browser (in the example below Firefox, but any browser can 
indifferently be used) and an instance of the Apache web server acting as a reverse 
proxy and listening for HTTP connections on port 8080. The proxy is needed since the 
majority of the browsers do not rely on OpenSSL for establishing HTTPS connections 
(for instance Firefox relies on NSS library), while the TLS DAA-Enhancement is 
designed for OpenSSL. For the purpose of this demonstration browser and proxy are 
seen as a unique entity, namely the Client, but the proxy actually establishes the 
HTTPS DAA-Enhanced connection with the Server.
It is important to note that:

Both Client and Server can coexist on a single machine, provided that Apache 
web server spawns at least two child processes (one will act as proxy on the 
Client, the other as web server on the Server). The HTTPS DAA-Enhanced 
connection will take place over the loopback network interface (localhost). For 
simplicity, in this demonstration a single machine is used both for Client and 
Server; it is straightforward to adapt the procedure if two machines are 
available. 

RPM packages with Apache web server are actually provided. These are 
generated from the OpenSuSE 11.1 original Apache package. Apache web 
server is “unmodified” in the sense that it is only recompiled against OpenSSL 
v0.9.9, while in the original OpenSuSE packages Apache is compiled against 
OpenSSL v0.9.8; actually a patch is needed because of small changes in the 
OpenSSL API that are included in the main Apache source tree since a newer 
version than the one currently used by OpenSuSE 11.1. However all these 
modifications are only needed to support OpenSSL v0.9.9, and they are 
independent from the TLS DAA-Enhancement. This is because, in this context, 
Apache is considered “unmodified”.

Open_TC Deliverable 03c.12

18/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

In the Client, the proxy is actually a reverse proxy, which is not the usual way of 
using a proxy (forward proxy) for HTTPS connections; moreover a reverse proxy 
is usually installed in the neighborhood of the server, not on the client. As 
already mentioned the proxy is a trick whose only purpose is to achieve a Client 
which makes HTTPS connections with OpenSSL to use the DAA enhancement, 
while standard browsers do not.

The remaining of this section is organized as follows: first recompile OpenSSL and in 
particular the TLS DAA-Enhancement in Legacy Mode; then install and properly 
configure Apache web server, as web server on the Server and as reverse proxy on the 
Client; finally test the connection with a web browser

8.1   Rebuilding OpenSSL with DAA Support in Legacy Mode

1. Return into the 

openssl-daa

 directory. Here it is assumed that OpenSSL with 

DAA support has already been installed:

cd TEMPDIR/openssl-daa/openssl-SNAP-20081204

2. Prepare OpenSSL:

./config --prefix=/usr/local/daatoolkit -shared \

-DTLSEXT_DAA_LEGACY_MODE

where the option 

-DTLSEXT_DAA_LEGACY_MODE

 enables the Legacy Mode at the 

next compilation.

3. Recompile and install:

make clean
make
make install

4. Verify that the installation was correct by running OpenSSL 

s_server

 and 

s_client

 as done in the previous sections. Since Legacy Mode automatically 

enables the DAA-TLS Extension and sets the name of the files containing the 
DAA Issuer and Platform credentials, it is sufficient to run the commands without 
DAA-related command line options. The following example uses the Engine 
Miracl (but any other similar example can be done as well).

1. Link the Miracl-related credentials:

cd /usr/local/daatoolkit/etc/daa/
rm daa_*
ln -s mr_daa_cred.bin daa_cred.bin
ln -s mr_daa_issuer.bin daa_issuer.bin

2. Move to the 

bin

 directory within the installation path:

cd /usr/local/daatoolkit/bin

3. Run OpenSSL 

s_server

 specifying the usage of the Engine Miracl via the 

command line option 

-engine miracl

:

Open_TC Deliverable 03c.12

19/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

export LD_LIBRARY_PATH=/usr/local/daatoolkit/lib
./openssl s_server -engine miracl

4. In another shell window, in the same working directory, run OpenSSL 

s_client

 specifying the usage of the Engine Miracl via the command line 

option 

-engine miracl

:

export LD_LIBRARY_PATH=/usr/local/daatoolkit/lib
./openssl s_client -tls1 -cert client.pem -engine miracl

5. Type something in either window and verify that the transmission 

between client and server succeeded.

6. Stop the client and the server by pressing CTRL+C and close the second 

shell window.

8.2   Installing and Configuring Apache Web Server

1. Move to the 

apache-daa

 directory:

cd TEMPDIR/apache-daa

2. Install Apache2 RPM packages (it is assumed that Apache2 is not already 

installed in the system):

rpm -i --nodeps *.rpm

3. Copy the configuration files for the virtual host in 

/etc/apache2/vhosts.d

proxy.conf

 for the Client proxy, 

ssl.conf

 for the Server:

cp proxy.conf ssl.conf /etc/apache2/vhosts.d

4. Enable Proxy SSL support, according to OpenSuSE methodology:

a2enmod proxy
a2enmod proxy_http
a2enmod ssl
a2enflag SSL

5. Generate certificates for the Server, according to OpenSuSE methodology:

gensslcert

6. Finally start Apache. Note that it is necessary to specify the library path to let 

Apache find the OpenSSL libraries with DAA support (

libssl

 and 

libcrypto

):

export LD_LIBRARY_PATH=/usr/local/daatoolkit/lib
rcapache2 start

8.3   Testing the Advanced Scenario

1. Open a web browser, for instance Firefox.

Open_TC Deliverable 03c.12

20/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

2. In an independent shell window, monitor the Apache log:

tail -F /var/log/apache2/*

3. Connect to the Server via HTTP, to check that Apache is working properly. Type 

in the URL bar:

http://localhost/

4. Connect to the Server via HTTPS. Again this is to check that Apache is working 

properly and this connection is not an HTTPS DAA-Enhanced connection. Type in 
the URL bar (please note the final 's' of the prefix 'https'):

https://localhost/

5. Let the browser contact the proxy. This forces the proxy (which is a component 

of the Client in this demonstration) to open a HTTPS DAA-Enhanced connection 
to the Server. Type in the URL bar (please note that the prefix is again 'http'):

http://localhost:8080/

In the monitoring shell window debug messages show that the TLS-DAA 
Extension is enabled. Note that Apache prints the debug messages of the TLS-
DAA Extension only after it has been stopped; therefore in order to see the 
debug log, run:

rcapache2 stop

Steps from 3 to 5 can be repeated to experiment with the engines. In order to test the 
TPM-DAA Engine before repeating those steps it is necessary to perform the following 
operations.

1. Link the TPM-related credentials:

cd /usr/local/daatoolkit/etc/daa/
rm daa_*
ln -s tpm_daa_cred.bin daa_cred.bin
ln -s tpm_daa_issuer.bin daa_issuer.bin

2. Edit the following file which contains global directives to configure 

mod_ssl

:

/etc/apache2/ssl-global.conf

and add a line soon after the tag 

<IfModule mod_ssl.c>

 with the 

SSLCryptoDevice

 directive that allows specifying the 

tpmdaa

 engine:

SSLCryptoDevice tpmdaa

3. Restart Apache

rcapache2 restart

The experiment will take some time while TPM executes DAA operations.

Open_TC Deliverable 03c.12

21/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

The case for the Miracl Engine is analogous.

1. Link the Miracl -related credentials:

cd /usr/local/daatoolkit/etc/daa/
rm daa_*
ln -s mr_daa_cred.bin daa_cred.bin
ln -s mr_daa_issuer.bin daa_issuer.bin

2. Edit the following file which contains global directives to configure 

mod_ssl

:

/etc/apache2/ssl-global.conf

and add a line soon after the tag 

<IfModule mod_ssl.c>

 with the 

SSLCryptoDevice

 directive that allows specifying the 

miracl

 engine:

SSLCryptoDevice miracl

3. Restart Apache:

rcapache2 restart

Note that either 'SSLCryptoDevice miracl' or 'SSLCryptoDevice tpmdaa' can be present 
in the file, not both of them.

Open_TC Deliverable 03c.12

22/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

9   List of abbreviations

Listing of term definitions and abbreviations used in this document (IT expressions and 
terms from the application domain).

Abbreviation

Explanation

AIK

Attestation Identity Key

EK

Endorsement Key

DAA

Direct Anonymous Attestation

SRK

Storage Root Key

TCG

Trusted Computing Group

TLS

Transport Layer Security

TPM

Trusted Platform Module

TSS

TCG Software Stack

10   Referenced Documents

/1/ OpenTC D03c.3 SSL/TLS DAA-enhancement specification

/2/ OpenTC OpenSSL engine/DAA enhancement design specification

/3/ TCG TPM Main Specification (parts 1,2,3)
July 9, 2007,
Version 1.2 Level 2 Revision 103

/4/ TCG Software Stack (TSS) Specification
March 7, 2007, 
Version 1.2, Level 1, Errata A

/5/ IETF RFC 4346, The Transport Layer Security (TLS) Protocol Version 1.1
April, 2006

/6/ IETF RFC 4366, Transport Layer Security (TLS) Extensions
April, 2006

/7/ IETF RFC 4680, TLS Handshake Message for Supplemental Data
September, 2006

/8/ Direct Anonymous Attestation
Ernie Brickell, Jan Camenisch, Liqun Chen
CCS '04: 11th ACM conference on Computer and Communications Security
2004

/9/ Simplified Security Notions of Direct Anonymous Attestation and a Concrete 

Scheme from Pairings
Ernie Brickell, Liqun Chen, Jiangtao Li
Trust08
2008

Open_TC Deliverable 03c.12

23/24

background image

 

 

OpenSSL engine/DAA enhancement source code and documentation  FINAL | 1.00

/10/ Pairings in Trusted Computing

Liqun Chen, Paul Morrissey, Nigel P. Smart
Pairing 2008
2008

/11/ Miracl – Multiprecision Integer and Rational Arithmetic C/C++ Library 

(http://ftp.computing.dcu.ie/pub/crypto/miracl.zip)
Mike Scott
2007

Open_TC Deliverable 03c.12

24/24

background image

 

 

D03c.9 Enhancement of Key Management 

Adaptation (KMA)

service source code and documentation

Project number

IST- 027635

Project acronym

Open_TC

Project title

Open Trusted Computing

Deliverable type

Internal document

Deliverable reference number

IST-027635/D03c.9/FINAL 1.10

Deliverable title

Key Management Adaptation (KMA) service 
source code and documentation

WP contributing to the deliverable

WP3

Due date

Apr 2008 - M30

Actual submission date

May 2009 (revised version)

Responsible Organisation

Politecnico di Torino

Authors

Gianluca Ramunno and Roberto Sassu (POL)

Abstract

Key and data Management Adaptation layer 
(KMA), formerly “High-level Key Manager 
service”, is intended to be a software system 
built upon TPM and TSS, whose goals are 
protecting keys and other sensitive data for 
generic applications and services and 
binding the access to the protected 
information to the integrity of the system.
This document describes the procedures for 
building, installing and configuring KMA 
version 1.0. This deliverable also includes 
D03c.10 and D03c.11.

Keywords

Open_TC, KMA, TPM, TSS

Dissemination level

Public

Revision

FINAL 1.10

Instrument

IP

Start date of the 
project

1

st

 November 2005

Thematic Priority

IST

Duration

42 months

 

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

Table of Contents

 1 Introduction................................................................................................................4
 2 Building and installing KMA........................................................................................5

 2.1 Important notes (to read carefully before building or using KMA)..........................5
 2.2 Introduction...........................................................................................................5
 2.3 KMA package dependencies (prerequisites)..........................................................6

 2.3.1 Prerequisites.....................................................................................................6

 2.4 KMA building procedure.........................................................................................7

 2.4.1 Building from the source tarball........................................................................7

 2.5 Creating a openSUSE repository with KMA RPMS...................................................8

 2.5.1 Using the distributed tarball with RPMS............................................................8
 2.5.2 Using the RPMS built as described in the section 2.4.1.....................................9

 2.6 Installation.............................................................................................................9

 2.6.1 Adding the KMA repository................................................................................9
 2.6.2 Set the packages to install................................................................................9
 2.6.3 Alternative installation....................................................................................10
 2.6.4 Do not reboot..................................................................................................10

 3 Preliminary steps......................................................................................................10

 3.1 Configuration of the TPM emulator......................................................................10
 3.2 Generation of the initram disk.............................................................................11
 3.3 TrustedGRUB modifications.................................................................................11

 4 Configuration............................................................................................................12

 4.1 Preliminary steps.................................................................................................12
 4.2 Creation of the file /etc/kma/boot.conf.................................................................12
 4.3 Creation of the file /etc/kma/signed_binaries.......................................................13
 4.4 Configuration of the protected filesystem............................................................14
 4.5 Creation of the file /etc/kma/checkfilelist.............................................................16
 4.6 MasterKey generation and NV storage configuration (only for TPM v1.2)............17
 4.7 First boot in learning mode..................................................................................18

 4.7.1 Checking the filesystem configuration............................................................18
 4.7.2 Discovering kernel modules............................................................................19
 4.7.3 Discovering applications that need direct access to devices..........................19
 4.7.4 Certifying binaries...........................................................................................19
 4.7.5 Importing unprotected files in the eCryptfs filesystem....................................19
 4.7.6 Learning activity of certified applications........................................................20
 4.7.7 Reviewing the libraries loading and direct access detected............................20

 4.8 Reboot in enforcing mode....................................................................................20
 4.9 Sealing.................................................................................................................20
 4.10 Unsealing...........................................................................................................21
 4.11 Using KMA..........................................................................................................21
 4.12 Maintenance procedures....................................................................................23

 4.12.1 Software update and new certified applications............................................23
 4.12.2 Adding to the database /etc/kma/logs/mmap_list non discovered libraries...25
 4.12.3 Adding to the database /etc/kma/logs/directaccess_list the processes that 
require direct access to devices................................................................................26
 4.12.4 Allowing new or updated modules to be loaded in the kernel ......................26
 4.12.5 Updating the system – a file included in /etc/kma/checkfilelist is changed...27
 4.12.6 Updating filesystem policies..........................................................................27

Open_TC Deliverable 03c.9

2/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

 4.12.7 Restoring access to a renamed or a moved eCryptfs file..............................27

 5 Removing KMA.........................................................................................................27
 6 List of all command used with parameters...............................................................28
 7 Workarounds............................................................................................................30
 8 PKCS#11 library configuration.................................................................................30

 8.1 Token configuration – Administrator side.............................................................30
 8.2 Token configuration – User side...........................................................................32
 8.3 Install software token in Firefox...........................................................................33
 8.4 Test and use the software token with Firefox......................................................34

 9 Glossary....................................................................................................................34
 10 List of Abbreviations...............................................................................................35
 11 Related Work..........................................................................................................35

Open_TC Deliverable 03c.9

3/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

 1  Introduction

Key and data Management Adaptation layer (KMA), formerly “High-level Key Manager 
service”, is a software system built upon TPM [1] and TSS [3], whose goals are 
protecting keys and other sensitive data for generic applications and services and 
binding the access to the protected information to the integrity of the system.
Specific objectives for KMA are:

access to protected data granted only if the integrity of system and the 
application/service requiring the access are verified;

(optional) access to protected data granted only if the system and the 
application/service have specific values for selected run-time properties (e.g. 
the user currently logged in);

isolation between protected data of different applications/services at run-time 
to prevent that, if an application gets compromised (e.g. because of a flaw) and 
the protected data can be accessed in memory by an attacker, the protected 
data of all other applications/services can be accessed by the attacker;

data protection robust against off-line attacks to the storage device;

generic protection mechanism for data files that does not require any 
modification to the application/service at build time, in order to use KMA with 
standard distributions;

support for the access to TPM keys bound to system/application integrity and 
properties, requiring minimal modifications at build time for application directly 
using the TPM keys;

seamless upgrade of the operating system and the protected applications while 
keeping the data protection;

support for platforms with a single operating systems running or (optionally) full 
virtual machines;

This is the companion document for 

D03c.9_KMA_source_code_and_RPMS.zip

, the 

tarball including source code and binary RPM packages. This document describes the 
procedures for building, installing, configuring KMA version 1.0. Among the examples 
it includes the configurations to make secure the following applications: OpenSSH 
(client and server), an implementation of SSH [2] protocol, tools for Ipsec configuration 
(i.e. setkey) and racoon the implementation of the IKE protocol, subversion client 
(svn), other applications like the editor nano. In addition the configuration for 
OpenCryptoki is included, an existing software implementation of a PKCS#11 
cryptographic device which has been updated to support multiple “tokens”. For this 
reason this deliverable actually incorporate an updated version of D03c.4 as well as 
D03c.10 and D03c.11.
With respect to the first version of KMA delivered as D03c.4 [4], this final version of 
KMA prototype has been improved with mechanisms that avoid any modification of 
applications to protect, allowing to secure arbitrary applications or services. It now 
includes the shared libraries used by applications for integrity checks. With the 
experience of the previous prototype and its enhancement, the overall KMA 
architecture/prototype was redesigned and to be more efficient, flexible and robust. 

Open_TC Deliverable 03c.9

4/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

The new prototype supports flexible access rights for the protected folders. These 
rights are controlled by the administrator and enforced by KMA throughout the lifetime 
of the boot session. We also added access control for critical devices (physical 
memory and hard disk). Some critical components running in user space in the 
previous prototype have been redesigned and moved to kernel space: eCryptFS was 
extended to work with KMA, and we implemented a Mandatory Access Control (MAC) 
subsystem based on Linux SMAC.
This version of KMA consists of five main components:

Mandatory Access Control, which is intended as an enhancement of SMACK;

EcryptFS filesystem with some modifications to adapt it to other components;

Policy module which is used by other components to verify if a process can 
access a resource;

Binary signature runtime verification to verify the integrity of certified 
applications;

kernel services for TPM.

 2  Building and installing KMA

 2.1  Important notes (to read carefully before building or using KMA)

KMA version 1.0 includes patches applied to the Linux kernel and it requires the 
installation of the boot loader TrustedGRUB which may result in a platform not booting 
anymore, if something fails. The passwords in this version are input in clear text. With 
respect of the first prototype of KMA, this version has been deeply tested  and used on 
daily basis with a development machine: it resulted in a stable system. However 
security tests have not yet been executed and no formal proof made yet. Finally until 
the user does not get familiar with the system and all precautions are taken (like 
backing up the bound MasterKey), there exist the risk that in case of problems the 
protected data can be irreversibly lost. .

For all aforementioned reasons, KMA version 1.0 must be still considered as 
preliminary and experimental software: it should not be installed on 
platforms in production while it should be only installed on testing platforms 
by experienced users.

 2.2  Introduction

KMA version 1.0 is distributed in two forms:

a tarball 

pol-kma-sources.tar.bz2

 including source code and scripts for 

building

a tarball 

pol-kma-rpms.tar.bz2

 including RPM packages with binaries only for 

direct installation

Both have to be extracted from the tarball 

D03c.9_KMA_source_code_and_RPMS.zip 

associated to this document.
Two procedures will be specified:

building RPMs packages with binaries from the source tarball and installing KMA 

Open_TC Deliverable 03c.9

5/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

from the newly generated RPM packages

installing KMA directly from the provided RPM binary packages

Before installing KMA packages, some prerequisites must be met. To build KMA there 
are also additional requirements. In the following subsection all prerequisites are 
listed, indicating whether they are required for installing only or also for building.

 2.3  KMA package dependencies (prerequisites)

The prerequisites are mostly expressed in terms of software packages to be installed. 
For each package (or group of packages), it is indicated if the package is required 
when 

building

 KMA or when 

installing

 it.

 2.3.1  Prerequisites

a hardware platform with TPM 1.1 or 1.2 and ownership correctly taken; 
currently it has been tested only on HP Compaq nw8000, nx6325 and HP 
dc7700 platforms [installing]

a specific Linux distribution and version installed, 

openSUSE 11.1

, with a 

specific SUSE Linux kernel, version 

2.6.27.21

: with future versions of the Linux 

kernel KMA v. 1.0 might not work [building, installing]

a file system (e.g. ext3) supporting the extended attributes which must be 
enabled to make KMA work [installing]

superuser privileges, i.e. access to root account [building, installing]

packages required for kernel development (gcc, make, etc.)[building]

kernel-source [building]

kernel-source (source package) [building]

sparse [building]

createrepo [building, installing]

trousers-devel [building] 

trustedgrub [installing]

openCryptoki (source package) [building]

MozillaFirefox (source package) [building]

libica [building]

libgnomeui-devel [building]

libidl-devel [building]

mozilla-xulrunner190-devel [building]

orbit-devel [building]

update-desktop-files [building]

trousers [installing]

tpm-tools [installing]

In order to use the sample configuration files without any modifications, the packages 

Open_TC Deliverable 03c.9

6/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

nano, subversion, ipsec-tools are also required for the configuration phase of KMA. 
With hand-crafted configuration files or with sample configuration files amended with 
deletion of entries for nano, subversion and ipsec-tools, these packages do not require 
to be installed.

 2.4  KMA building procedure

 2.4.1  Building from the source tarball

1. Copy the distributed tarball with source code (

pol-kma-sources.tar.bz2

) to a 

temporary directory (

TEMPDIR

, where “

TEMPDIR

” 

is a full path including the 

root “/” of the file system

), enter this directory and extract the content from 

the tarball with the following command;
1.

tar jxf pol-kma-sources.tar.bz2 -C TEMPDIR

2. Enable the repository  “

openSUSE-11.1-Source

1. Go to YaST/Software Repositories
2. Click the item “

openSUSE-11.1-Source

” and check the box “Enabled”

3. Press the OK button to confirm

3. Execute these commands to download required packages:

1.

zypper si <source packages listed in the section 2.3.1>;

2.

zypper install <packages listed in the section 2.3.1>;

3.

wget 

http://mozilla.mirrors.easynews.com/mozilla/firefox/releases/3.0
.10/linux-i686/en-US/firefox-3.0.10.tar.bz2

 -P 

/usr/src/packages/SOURCES

4.

wget http://download.berlios.de/tpm-
emulator/tpm_emulator-0.5.1.tar.gz -P /usr/src/packages/SOURCES

4. Enter the 

/usr/src

 directory and take note of the kernel source directory and 

the version;

5. From the TEMPDIR/pol-kma-filemac-1.0

 

path enter the directory 

build/config/i386

”;

6. Execute the command: 

cp kma.full.default-<kernel-version> kma

;

7. From the TEMPDIR/pol-kma-filemac-1.0 path enter the directory “

build”

;

8. Edit the file “

generate_packages.sh

” and replace the value of the variable 

KERNELDIR

” with the full path of installed kernel sources;

9. Execute the script 

generate_packages.sh

 without any parameter;

10.From the TEMPDIR/pol-kma-filemac-1.0 path enter the directory “

dist”

;

11.Edit (if the case) the file “

packages_list

” and add the list of “spec” files to 

build; these are currently used:
1. kernel-kma-2.6.27.21.spec
2. kernel-kma-source.spec

Open_TC Deliverable 03c.9

7/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

3. kma-boot.spec
4. kma-utils.spec
5. libtpm11.spec
6. libtpm12.spec
7. opencryptoki_kma.spec
8. firefox-bin.spec
9. tpm_emulator.spec

12.Execute the script “

buildkma.sh

”; if a package cannot be compiled because of 

a missing dependence, fix the issues and restart the script from the point it was 
interrupted using the command 

./buildkma –-resume <spec failed>

13.The build of tpm_emulator.spec fails. Execute these steps:

1. The package kernel-kma-source and kernel-kma must be generated before 

the TPM emulator

2. Execute 

rpm -Uhvi /usr/src/packages/RPMS/i586/kernel-kma-source-

<kernel version>-<kma version>kma.i586.rpm

3. Execute 

rpm -Uhvi /usr/src/packages/RPMS/i586/kernel-kma-<kernel 

version>-<kma version>kma.i586.rpm –nodeps

4. Execute 

rpm -Uhvi /usr/src/packages/RPMS/i586/kernel-kma-base-

<kernel version>-<kma version>kma.i586.rpm –nodeps

5. Execute 

uname -r

 and take the string after the last “

-

” (it can be 

default, 

pae, xen

), which is called kernel flavor

6. Edit the file tpm_emulator.spec and search for the line:

1.

%define flavors_to_build kma default pae

7. Modify this line as follow:

1.

%define flavors_to_build kma <your kernel flavor>

;

8. Execute the command 

./buildkma.sh --resume tpm_emulator.spec

14.Get the newly generated RPM packages from the directory 

/usr/src/packages/RPMS/i586

.

 2.5  Creating a openSUSE repository with KMA RPMS

 2.5.1  Using the distributed tarball with RPMS

1. Copy the distributed tarball with rpms (

pol-kma-rpms.tar.bz2

) to a temporary 

directory (

TEMPDIR

, where “

TEMPDIR

” 

is a full path including the root “/” of 

the file system

), enter this directory and extract the content from the tarball 

with the following command;
1. tar jxf pol-kma-rpms.tar.bz2

2. Execute the command 

createrepo

 

TEMPDIR/RPMS

;

Open_TC Deliverable 03c.9

8/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

 2.5.2  Using the RPMS built as described in the section 2.4.1

1. Create a new directory called TEMPDIR;
2. Copy the directory 

/usr/src/packages/RPMS 

to TEMPDIR, executing the 

command 

cp -R /usr/src/packages/RPMS TEMPDIR

;

3. Execute the command 

createrepo TEMPDIR/RPMS

;

 2.6  Installation

Two alternative methods for installation are described in the following. Both of them 
require that Yast is configured with the KMA repository containing the packages just 
created or unpacked.

 2.6.1  Adding the KMA repository

1. Open YaST/Software repositories;
2. Click on “Add”;
3. Select “Local Directory”;
4. Type “

/<pathname of TEMPDIR>/RPMS

” in the field “

Path to Directory

” and 

an identifier in the field “

Repository Name

”.

 2.6.2  Set the packages to install

1. Open/YaST/Software Management
2. From the “Filter” field select “Repositories”
3. From the list of repositories select the KMA repository
4. From the package list, at the right of the screen, select these packages:

kernel-kma

REQUIRED

kernel-kma-base

REQUIRED

kernel-kma-extra

REQUIRED

kernel-kma-source

REQUIRED 

to build additional kernel modules from 

scratch

kma-utils

REQUIRED

kma-boot

REQUIRED

libtpm11

REQUIRED

 

ONLY

 if the TPM version is 1.1b

libtpm12

REQUIRED

 

ONLY

 if the TPM version is 1.2

tpm_emulator

REQUIRED

 

ONLY

 if the platform doesn't have an hardware TPM 

(the package 

libtpm11

 is required)

tpm_emulator-kmp-kma

REQUIRED

 

ONLY

 if the platform doesn't have an 

hardware TPM

tpm_emulator-kmp-<your current kernel flavor>

REQUIRED

 

ONLY

 if the 

platform doesn't have an hardware TPM

Open_TC Deliverable 03c.9

9/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

openCryptoki_kma

OPTIONAL

 to use PKCS#11 software token protected by 

KMA

openCryptoki_kma-32bit

OPTIONAL

 to use PKCS#11 software token 

protected by KMA

MozillaFirefox-bin

REQUIRED

 

ONLY

 if one of the packages openCryptoki or 

openCryptoki_kma is installed.

 2.6.3  Alternative installation

This alternative path for the installation can be used if there is the need to change the 
default kernel configuration with regards to modules and if additional modules need to 
be built.

1. Install all required packages (the 

kernel-kma-source

 must be included) as 

described in the section 2.6.2 except: 

kernel-kma

kernel-kma-base

kernel-

kma-extra, tpm_emulator, tpm_emulator-kma-kma

. Ignore package 

dependencies.

2. Copy the predefined kernel configuration file “

.config

” from the directory 

/usr/src/linux-<kernel version>-<kma version>kma-obj/i386/kma

 to 

/usr/src/linux-<kernel version>-<kma version>kma

;

3. Enter the directory 

/usr/src/linux-<kernel version>-<kma version>kma

;

4. Execute 

make menuconfig

 to edit the kernel configurations;

5. Execute 

make all

;

6. Execute 

make modules_install

;

7. Execute 

cp arch/x86/boot/bzImage /boot/vmlinuz-<kernel version>-<kma 

version>kma

;

8. Execute 

cp .config /boot/config-<kernel version>-<kma version>kma

;

9. Execute 

cp System.map /boot/System.map-<kernel version>-<kma 

version>kma

;

10.If required unpack the tpm_emulator tarball from /

usr/src/packages/SOURCES 

and follow the standard procedure to compile and install this software.

 2.6.4  Do not reboot

Even if Yast proposes to reboot, this operation must not be done at this point.

 3  Preliminary steps

 3.1  Configuration of the TPM emulator

If the platform has not an hardware TPM, the TPM emulator is required in order to use 
KMA. It must be configured using the packages Trousers and TPM tools. In the first run 
of this software these commands must be executed with the root privilege:

1.

modprobe tpmd_dev

 (executing the kernel-side portion of the TPM emulator)

2.

tpmd clear

 (executing the user-side portion of the TPM emulator)

Open_TC Deliverable 03c.9

10/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

3.

service tcsd start

 (executing the trouser daemon)

4.

tpm_takeownership

 (taking the ownership of the software TPM)

If a hardware TPM is present in the platform, the requirement is that the ownership is 
taken and the Administrator has the knowledge of the owner password (which must be 
encoded with ASCII characters). The Administrator must decide if he/she wants to 
input a blank SRK password or input a not null one. In the latter case, the user is 
required to input the SRK password at every boot and the variable 

srk_ask=yes

 must 

be set in the configuration file 

/etc/kma/boot.conf

 (see section 4.2).

IMPORTANT NOTE: at every subsequent reboot, for both configuring and 
using the system, the following commands must be executed:

1. (only if the TPM emulator is used) 

modprobe tpmd_dev

2. (only if the TPM emulator is used) 

tpmd

3.

service tcsd start

 3.2  Generation of the initram disk

After all packages are installed, the initram disk must be generated another time 
because the proper TPM kernel module must be loaded before the KMA script is 
executed. These steps must be performed:

1. Edit the file 

/etc/sysconfig/kma

;

2. Specify the TPM kernel module name as value of the variable 

TPM_MODULE

Acceptable values:
1.  TPM emulator: 

tpmd_dev

;

2. Infineon TPM: “

tpm_infineon

”;

3. Atmel TPM: “

tpm_atmel

”;

4. NSC TPM: “

tpm_nsc

”;

3. If there is the need to change the standard configuration of the initram disk, 

edit the file /lib/mkinitrd/scripts/boot-kma.sh;

4. Add to the line which starts with “#%modules: “ the kernel modules that are 

required to mount specific filesystems listed in 

/etc/fstab

 or the removable 

device where the MasterKey will be stored;

5. Currently there is an issue that mkinitrd does not recognize the new installed 

scripts. Execute the command “

ls /lib/mkinitrd/scripts

6. Generate the new initrd with the command (to insert the right file names see 

the content of the directory 

/boot

):

mkinitrd -k  /boot/vmlinuz-<kernel_version>-<kma_version>kma -i 

/boot/initrd-<kernel_version>-<kma_version>kma -M 
/boot/System.map-<kernel_version>-<kma_version>kma

 3.3  TrustedGRUB modifications

To simplify the management of the KMA it is useful to create three different entries in 
the TrustedGRUB menu:

Open_TC Deliverable 03c.9

11/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

One that executes the KMA in enforcing mode (this is created by the kernel-kma 
RPM package during the installation; add the extra parameter in the kernel 
command line: 

kma_mode=enabled

 and add the string “

ENABLED

” in the entry 

name);

One that executes the KMA in learning mode (add the extra parameter in the 
kernel command line: 

kma_mode=learning 

and add the string “

LEARNING

” in 

the entry name);

One that executes the KMA in disabled mode (add the extra parameter in the 
kernel command line: 

kma_mode=disabled 

and add the string “

DISABLED

” in 

the entry name);

To create the new entries:

1. Go to YaST/System/Boot loader;
2. Click on the existent KMA entry;
3. Click the button “Add” and select “Clone Selected Section”;
4. In the field “Section name” add the string previously suggested;
5. In the field “Optional Kernel Command line parameter” add to the end the 

parameter listed before.

Note that the original entry for KMA created by installing the packages and used as 
source for cloning, must be never used and can therefore be deleted.

 4  Configuration

 4.1  Preliminary steps

The package “

kma-boot

” when installed copies sample configuration files to the 

/etc/

kma/sample_config 

directory. The Administrator can edit those files and after must 

place the final version of them in the 

/etc/kma

 directory. In particular the files stored 

in 

/etc/kma/sample_config

 can be copied and used as they are; the files stored in 

/etc/kma/sample_config/user1

 require the creation of the user 

user1

 with 

UID=1000 

and 

GID=100

, to be used as they are. If UID an GID for 

user1

 are different, then the 

sample files must be updated. In particular the content of the file 

/etc/kma/sample_config/user1/template.conf.user1

 must be appended to the file 

/etc/kma/template.conf

.

 4.2  Creation of the file /etc/kma/boot.conf

This file is used to set some variables that affect the behaviour of the KMA script 
placed in the initram disk.

srk_ask=[yes/no]

: defines if the SRK password must be asked to execute KMA 

commands on TPM, and during the normal unsealing procedure at every boot; 
this variable must set to 'no' if the SRK is set to the well-known secret (i.e. 
during the TPM take ownership operation) and 'yes' if the SRK password is set; 
the default value is 'no', if the variable is absent;

BLOBDEV=[pathname]

: defines the external device (the partition) where to save 

the MasterKey; it must be present only if the MasterKey is not stored on the root 

Open_TC Deliverable 03c.9

12/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

file system but on an external device;

BLOBDEV_FSTYPE=[fs type]

: defines the filesystem type of the partition 

selected; it must be present only if 

BLOBDEV

 is present;

MOUNTPOINT=[pathname]

: defines the pathname where the protected filesystem 

will be mounted; the pathname is considered after all filesystem listed in 

/etc/

fstab

 are mounted; this is the only mandatory variable.

 4.3  Creation of the file /etc/kma/signed_binaries

This file describes what applications must be certified by the Administrator, in order to 
use the protected filesystem or to directly access devices. Each application will be 
associated to a “

TAG

”: this is a property introduced by KMA to distinguish between 

binary executables (identified by means of their SHA1 digest), its values are four 
characters long and it is used when setting policies.
The format of this file is:

<pathname> <Authority ID>  <value>

where:

pathname

: the file to certify;

Authority ID

: is the property associated to the file. Currently only the TAG is 

associated to a binary and the identifier is always zero;

value

: the TAG value associated to the binary file: it must be unique.

The utility 

certbin

 creates the extended attribute “

kma_sign

”, whose content is 

protected for confidentiality and integrity using the MasterKey, for each file listed and 
appends this to the file itself. This is a configuration example:

/usr/bin/ssh

0

0001

/usr/sbin/sshd

0

0002

/usr/sbin/racoon

0

0003

/usr/sbin/setkey

0

0004

/usr/bin/ssh-keygen

0

0005

/usr/bin/nano

0

0006

/bin/ls

0

0007

/bin/rm

0

0008

/usr/bin/svn

0

0009

/usr/sbin/smartd

0

0010

/sbin/swapon

0

0011

/lib/udev/edd_id

0

0012

/lib/udev/scsi_id

0

0013

/lib/udev/ata_id

0

0014

/lib/udev/vol_id

0

0015

/usr/sbin/dmidecode

0

0016

/opt/firefox/firefox-bin

0

0017

/usr/sbin/pkcsconf

0

0018

/opt/thunderbird/thunderbird-bin 

0

0019

/usr/bin/Xorg 

0

0020

Open_TC Deliverable 03c.9

13/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

 4.4  Configuration of the protected filesystem

The purpose of KMA is to securely store applications' data files in order to prevent off-
line attacks and to restrict accesses only to authorized subjects, whose properties are 
verified by the kernel, trusted by assumption. To achieve this goal, the directories 
used by applications and their content are moved to an cryptographic filesystem, the 
access is restricted by a Mandatory Access Control module that resides in the kernel 
and symbolic links are created in old locations in order to preserve the pathname. New 
directories created in the cryptographic filesystem are called protected directories.
The Mandatory Access Control has these goals:

1. restrict accesses on files and directories in the cryptographic filesystem 

depending on policies written by the Administrator;

2. forbid the creation of symbolic links in the cryptographic filesystem: all files 

must be encrypted and should not point to others in a unencrypted filesystem;

3. protect symbolic links that replaced original application directories: the goal is 

to force the application to access the cryptographic filesystem when refers to 
old pathnames.

Before writing the policy for an application, the Administrator must:

1. Assign a tag to the application (described in the section 4.3);
2. Examine the behaviour of the application (single process, multiple processes, 

multi thread);

3. Examine the application data model (i.e. build a list of files and directories 

used);

Then, for discovered directories the directory policy must be added to the file 

/etc/kma/template.conf

”. 

The first two elements are:

Protected directory pathname in the cryptographic filesystem 

directory <pathname> { 

The discovered directory pathname that will be replaced with a symbolic link to 
the protected directory

bounddir <pathname>

NOTE: the pathname specified in the “bounddir” parameter in the policy 
statement must follow these rules:

1. The pathname of the parent directory must exist at the time the 

system is booted in learning mode (executing the procedure described 
in the sections 4.7 until 4.10 is recommended);

2. Components of the pathname of the parent must be directories (trees 

with symbolic links are not allowed).

These following parameters are used to set correct permissions for the protected 
directory:

POSIX permission

permission <mask>

Open_TC Deliverable 03c.9

14/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

User and group owner

owner <uid:gid>

Then subjects allowed to access the directory must be defined using the parameter 

access_mask

”.  The term subject refers to a process with a set of properties for 

example the effective UID or the KMA introduced TAG. These properties are used as 
access control criteria for accessing the protected filesystem: each policy specifies the 
values that a subject must have at the time it opens a file or a directory. Currently 
these are the properties defined:

TAG

;

effective user identifier

 (the current user privilege that can be modified 

by the application itself by invoking the system call 

setuid()

).

While the effective UID is stored in a standard kernel structure associated to the 
process, the TAG is extracted from the extended attribute by a KMA kernel module 
that decrypts the content, verifies if the SHA1 of the executable bound matches this 
read from the payload and verifies the integrity of the latter using the MasterKey.
The object that permits to specify values that a subject must have for the defined 
properties to access the protected filesystem is called “

access vector

”.

An example is:

|TAG(4 characters)|UID(5 characters)|

General case (when N properties are defined):

|Property#1 value|Property#2 value|...|Property#N value|

Acceptable values depend on the property, but a special symbol (i.e. a “wild card”) 
has been defined to represent “all possible values”. In order to specify that all values 
are allowed for a property the relative field of the access vector must be filled with a 
string of the character “X”.
This is the complete directory policy of a protected directory:

directory /system/ssh {

bounddir /etc/ssh

permission 755
owner 0:0

access_mask |XXXX|XXXXX|
declarevar UID=00000

policyfile /root/etc/kma/ssh_system_config

}

Parameters:

directory

: is the pathname of the new directory will be created in the 

protected filesystem;

bounddir

: is the old pathname of the directory to protect;

permission

: POSIX permission mask;

owner

: userID:groupID identifiers;

access_mask

: access vector allowed to read/write/execute in the protected; 

Open_TC Deliverable 03c.9

15/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

directory; may be used multiple times to grant the permission to different 
subjects;

declarevar

: this parameter is used to define some variables which value will be 

replaced in the policy file;

policyfile

: pathname of the file policy that must have the prefix “

/root/

” 

(because this file is read within the initram disk);

The policy file determines for each file in the protected directory:

subjects allowed to create (access vector followed by the character “c”)

subjects allowed to access (access vector followed by the type of operation 
granted)

depending on its name. Subjects with create permission have read, write, append 
permission: it is not necessary to specify an access policy for them.  The “*” character 
is used to define the default policy, which must be specified as last statement for files 
which name does not match any of other listed. If the default policy is not present, 
files with name not listed cannot be created under the protected directory. 
An example can be:

file id_rsa {

|0005|$UID|000|

c

|0001|$UID|000|

r

}

Parameters:

file

:

 contains the filename of the file will be created

<access vector>

if followed by the letter 'c' it means that the subject is 

allowed to create; if followed by '

r

', '

w

', '

x

', '

a

' or a combination, these are 

respectively the read/write/execute/append permissions granted to subjects 
with this access vector. Multiple access vectors can be defined in the same 
policy.

 4.5  Creation of the file /etc/kma/checkfilelist

Contains the list of files that will be measured at boot and which SHA1 extends the 
PCR#13 of the TPM. Typically these are the files measured:

/etc/fstab

/etc/kma/boot.conf

/etc/kma/template.conf (and the files whose pathname is specified 

in the policyfile parameter)

/etc/kma/logs/mmap_list (introduced in section 4.7.6)

/etc/kma/logs/directaccess_list (introduced in section 4.7.6)

/etc/kma/logs/modules_list (introduced in section 4.7.2)

/etc/kma/signed_binaries

Open_TC Deliverable 03c.9

16/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

 4.6  MasterKey generation and NV storage configuration (only for TPM 
v1.2)

The last task to execute before booting the KMA kernel in learning mode is to setup a 
new MasterKey: this is done by executing these steps:

1. Be sure that the TPM driver is loaded: execute the command 

modprobe <your TPM module>

1. For the TPM emulator run the additional command 

tpmd

2. Be sure that Trousers daemon is not running: execute the command

service tcsd stop

;

3. Execute the command 

init_masterkey.sh

 without any parameter;

4. Restart Trousers daemon for the next steps: execute the command

service tcsd start

.

This operation may require to plug an external device, before saving the new 
MasterKey; otherwise this will be saved in the default path 

/etc/kma/keys

.

A new MasterKey is randomly generated using the device “

/dev/urandom

” and a new 

TPM wrapping key is created to encrypt it.  In order to protect the unwrapping 
operation the Administrator must set, for this TPM key, a password: the knowledge of 
this secret allows an user to boot the system in learning mode, to access all data in 
the protected filesystem and to certify binaries.
For platforms with TPM 1.2 it is available a feature that permits to check the “version” 
of the sealed blob containing the MasterKey. This is useful in the following case: the 
Administrator creates a new sealed blob when a component in the measurement list 
changes; if an attacker has a copy of the old sealed blob and he knowns exactly the 
previous state of the changed component, he will be able to use the MasterKey with 
the old configuration, which may be replaced due to a discovered vulnerability. 
In order to avoid this situation the Administrator must attach an unique label to the 
MasterKey, during the generation process and stores the same label in a portion of the 
NV storage of the TPM.
During the boot, the kernel module which performs the unsealing reads the label 
stored within the MasterKey and compares it with the one read from the TPM. If they 
are different, the kernel module forbids the access to the MasterKey and the system 
must be rebooted.
When the Administrator updates the sealed blob he writes a new label with the 
MasterKey and in the NV storage: this way old sealed blobs cannot be used.
If the utility 

init_masterkey.sh

 finds a compatible TPM, it asks to the Administrator 

the label to append to the MasterKey; otherwise the feature will be disabled. For now, 
the size is hard coded and must be exactly 10 characters long.
In order to define and protect the NV storage portion these steps must be performed:

1. Execute the command: 

kma_define_nv

1. Enter the TPM owner password;
2. Enter the secret will be used to protect this portion from writes;

2. Execute the command: 

kma_write_nv

Open_TC Deliverable 03c.9

17/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

1. Enter the secret set for the portion of the NV storage;
2. Enter the same label appended to the MasterKey when the utility 

init_masterkey.sh

 was executed.

In case of the error TSS_E_NV_AREA_EXIST is displayed, it means that the index has 
already defined. At the moment it is not possible to define an alternate address of the 
TPM where to place the label: the Administrator must move data in the existent index 
to another and call the command 

kma_release_nv

 to release the space. Then the 

steps described above must be re-executed.
In order to verify if the label has correctly written in the NV storage the Administrator 
can execute the utility 

kma_read_nv

 without any parameter. The utility asks to insert 

the label 10 character long must be inserted.
After the script has been executed, these files are created under the path 

/etc/kma/keys

:

1.

masterkey.key

: TPM wrapping key, private portion;

2.

masterkey.pem

: TPM wrapping key, public portion;

3.

masterkey.blob

: MasterKey blob bound to the TPM wrapping key.

 4.7  First boot in learning mode

The KMA-enabled kernel should be started for the first time in learning mode in order 
to:

1. Check the filesystem configuration;
2. Discover kernel modules loaded and identify what are necessary for the system 

to work correctly;

3. Discover applications that need direct access to devices;
4. Certify applications;
5. Importing existent data files of certified applications  
6. Discover and measure libraries used by certified applications.

The following sub paragraphs describe how to set up correctly the KMA before it is 
executed in enforcing mode.
To boot the system in learning mode select the proper entry in the TrustedGRUB 
menu.

 4.7.1  Checking the filesystem configuration

The ecryptfs filesystem is mounted in the initram disk. The mount parameter 

kmatemplate=

” introduced by KMA is used to specify the corresponding filesystem 

policy to be loaded. During the learning phase the Administrator must verify if the 
syntax is correct. To do this operation he must perform the command “

dmesg | more

” 

and check these lines:

KMA learning mode enabled
Inserted auth tok with sig [2d8f66ccb71c579f] into the user session 

keyring
mask: |XXXX|XXXXX|XXX|, access: 7

Open_TC Deliverable 03c.9

18/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

name UID - value 00000

mask: |0006|00000|000|, access: -1
mask: |0006|XXXXX|000|, access: 6

mask: |0001|XXXXX|000|, access: 4
Info: added file ssh_config

If an error is encountered, the following message appears and the Administrator must 
recheck the policy files:

Failed to initialize protected filesystem

The Administrator must fix the files by booting the KMA in “disabled” mode and then 
must recheck the configuration in learning mode.

 4.7.2  Discovering kernel modules

The Administrator must detect which kernel modules will be allowed to load when the 
KMA is executed in enforcing mode and must check if they contain malicious code. 
When the system is started in learning mode some modules are loaded automatically 
when initializing devices. Others must be manually inserted by the Administrator using 
the command 

insmod

 or 

modprobe

. Then, when all required modules are loaded, the 

Administrator can review the list and the digest of every item by executing the 
command 

kma_modules_db /etc/kma/logs/modules_list 

and typing the command 

view<ENTER>

. To exit the application type the command 

quit<ENTER>

.

 4.7.3  Discovering applications that need direct access to devices

The Administrator can discover them by prompting the command: 

dmesg | grep 

“signed”

. This type of message will be displayed: 

“KMA direct access: process X 

needs to be signed”

. If the Administrator wants to allow an application to access 

directly a device he must add a new record in the file 

/etc/kma/signed_binaries.

NOTE: the process name specified in the log message may be incomplete: to 
find the full pathname of the binary executable this command should be 
performed: find / -name “<part of the process name>*”.

 4.7.4  Certifying binaries

The Administrator after having verified binaries listed in the file 

/etc/kma/signed_binaries

 executes the utility 

certbin

. The syntax is:

certbin --list /etc/kma/signed_binaries;

If the message “

hashing of <filename> failed

” appears the Administrator must 

recheck the file 

/etc/kma/signed_binaries

 and correct the path of the not found 

executable(s). A requirement for booting the KMA in enforcing mode is that the 
mentioned file contains valid pathnames and the command 

certbin

 is executed: this 

is necessary in order to prevent that certified binaries are replaced by others 
unsigned, when KMA is not loaded, and users execute them without being noticed.

 4.7.5  Importing unprotected files in the eCryptfs filesystem

During the previous boot (the first one in learning mode) the KMA creates protected 
directories in the eCryptfs filesystem as specified in the file 

/etc/kma/template.conf

renames directories specified in the parameter “

bounddir

” in the unprotected 

Open_TC Deliverable 03c.9

19/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

filesystem by adding the suffix “

_save

” and creates instead symbolic links to the 

protected directories with the old name; the KMA script creates the file 

/etc/kma/files_saved

 that contains records with the renamed directory in the 

unprotected filesystem and the directory in the protected filesystem where existent 
files would be copied. An example file ready to use is provided in 

/etc/kma/sample_config

. The Administrator decides, for all directories, what files to 

copy to protected locations and executes the command 

kma_makesecure.sh

 by 

specifying as parameters the file 

/etc/kma/files_saved

 and a output file that will 

contain the full pathname of all files saved in the eCryptfs filesystem and the relative 
SHA1 digests. This command automatically copies files from directories in the 
unprotected filesystem to the protected one. The file specified as second parameter of 
the script can be included in the measurement list and it can be used by users to 
verify their original files are not modified.

 4.7.6  Learning activity of certified applications

At this point rebooting again in learning mode is highly recommended to discover 
libraries and access to devices in case of system services. In other cases is sufficient 
to run the desired application and to use it for a while to ensure all libraries required 
have been loaded.
The kernel writes discovered libraries and device accesses respectively in files 

/etc/kma/logs/mmap_list

 and 

/etc/kma/logs/directaccess_list

.

 4.7.7  Reviewing the libraries loading and direct access detected

The Administrator run these utilities:

1.

kma_mmap_db /etc/kma/logs/mmap_list

 to review all libraries mapped in 

memory by certified applications;

2.

kma_directaccess_db /etc/kma/logs/directaccess_list

 to review direct 

accesses to devices performed by certified applications.

 4.8  Reboot in enforcing mode

As final part of the configuration phase a reboot cycle must be executed: the KMA 
enable kernel is executed in enforcing mode by selecting the proper entry in the 
TrustedGRUB menu.

 4.9  Sealing

The MasterKey is sealed when the KMA enabled kernel is executed in enforcing mode 
and when the blob is not present in the default path or in a removable device. This 
procedure asks the Administrator password set by the 

init_masterkey.sh

 utility and 

permits to modify it if needed. If a TPM v1.2 is detected, the kernel module which 
performs the operation  compares the label read from the NV storage and the one 
extracted from the MasterKey and alerts the Administrator if they are different. Lastly 
the file 

blobfile

 will be created in the default path 

/etc/kma/keys

 or in an external 

device. The system reboots and at this point the KMA is suitable for use by regular 
users of the platform.

Open_TC Deliverable 03c.9

20/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

 4.10  Unsealing

During the normal system start up in enforcing mode a kernel module tries to unseal 
the MasterKey after TPM registers are extended with all measurements. If a TPM v1.2 
is detected this module compares the label extracted from the MasterKey with this 
read from the NV storage. If the unsealing or the label check fail, KMA will not be 
activated and the system reboots: the system must be booted in learning mode to fix 
the label (but the Administrator password is required) or with KMA completely 
disabled.

 4.11  Using KMA

After the system completed the boot cycle, regular users can log into the platform and 
start to save theirs files in the protected filesystem. Thanks to symlinks users continue 
to use previous directories, with the difference that the files effectively reside in the 
cryptographic filesystem and the access is restricted depending on the policies written 
by the Administrator. An user can know how to access a directory or a file in the 
cryptographic filesystem by using the utility “

kma_policy.sh

”. The syntax is:

kma_policy.sh <pathname of the symlink>

An example of execution of this command is:

Directory: /root/.ssh
        USER: root, Application: all

Policy file: /etc/kma/ssh_users_config

File: id_rsa
        User: root, Application: /usr/bin/ssh-keygen, Permissions: Create

        User: root, Application: /usr/bin/ssh, Permissions: Read

File: id_rsa.pub
        User: root, Application: /usr/bin/ssh-keygen, Permissions: Create

        User: root, Application: all, Permissions: Read

File: known_hosts
        User: root, Application: /usr/bin/ssh, Permissions: Create

        User: root, Application: /usr/bin/ssh, Permissions: Read, Write, 
Append

File: authorized_keys

        User: root, Application: /usr/bin/nano, Permissions: Create
        User: root, Application: /usr/sbin/sshd, Permissions: Read

        User: root, Application: /usr/bin/nano, Permissions: Read, Write

When a user tries to access a file he can encounter these types of errors:

1.

“<command>: cannot open directory/file <name>: Permission denied“. 

Possible causes:
1. The user has not sufficient privileges (POSIX) to open the file/directory;

Open_TC Deliverable 03c.9

21/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

2. The KMA policy for the file/directory forbids this user/process to access the 

file

2.

“<command>: cannot open directory/file <name>: Input/Output Error”

Possible causes:
1. The file has been moved from the original position at the time of creation;
2. The file has been encrypted with another key

3. Abnormal program termination and 

“Killed”

 message.  Possible causes:

1. The application ran tried to map a library not authorized

4.

“FATAL: Error inserting <module name> ... Invalid module format”

Possible causes:
1. The module has been compiled with another kernel
2. The module is not in the database of allowed modules list

If the system returns “

Permission denied

” or if a system service failed to start, the 

user can check the reason by executing the command 

dmesg

 and seeing error 

messages. A typical error message is:

Denying access: kdesvn[4856] ->  <filename> - reason: permission 1 not 

allowed to subject |XXXX|01000|

The permission requested is reported with decimal notation.  The access vector 
contains the actual values of the properties 

|TAG|effective UID|

.  If the value in the 

TAG field is “

XXXX

” this means that the application is not certified or that the 

verification of the certification failed because for example the binary of the application 
has been updated. In the second situation the maintenance procedure in the section 
4.12.1 must be executed by the Administrator.
The “

Permission denied

” error is also displayed when an user tries to create a new 

file with an application not listed in the policy file. The detailed message in the system 
log is:

Found policy create for id_rsa

Denying create: bash[3990] with mask |XXXX|00000| is not allowed to 
create the file <filename>

The “

Input/Output Error

” issue depends on the fact that eCryptfs files cannot be 

moved from their original location after they are created. This feature is necessary for 
the correct behaviour of the Mandatory Access Control that apply policies on files and 
directories depending on their pathname. In order to enforce the position, a KMA patch 
has been inserted in the eCryptfs code that appends in the header of each file a keyed 
digest of the file name and the parent directories until the root using the File 
Encryption Key (FEK) as key. The move operation is always denied when the MAC is 
active; this can be done when another kernel is loaded or when the KMA is not in 
enforcing mode. The next time a moved file is accessed, eCryptfs returns I/O error. A 
detailed error message is written in the system log and it's like this:

ecryptfs_parse_packet_set: Error: file /system/ssh/sshd_config in the 
protected filesystem has been moved from the original position

.

Another error may be encountered when the user tries to run a certified application 
which is not correctly configured. The application is terminated and the system 

Open_TC Deliverable 03c.9

22/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

prompts the message “

Killed

”. The maintenance procedure described in the section 

4.12.1 must be followed to solve the issue.
The error 

“FATAL: Error inserting <module name> ... Invalid module format” 

may happen when the root user tries to load a module using the command 

insmod

 or 

modprobe

. If the module is not present in the database of allowed modules or it has 

been modified (there's a module with the same name but with different digest) the 
kernel denies the operation and prompts in the system log this message:

Cannot load module <module name>: not found in the database or wrong 

digest

 4.12  Maintenance procedures

 4.12.1  Software update and new certified applications

Adding new certified applications or updating the existent ones is a critical process 
because the configuration created during the learning process may change: in case of 
new certified applications the database of mapped libraries will include new libraries, 
the database of direct accesses to devices may include new rules; in case of updated 
packages, the libraries used by certified applications may change and their new 
digests must be written in the database.
Another aspect is that the update operation is not possible when KMA is started in 
enforcing mode: if the application set to be updated has been already executed, its 
libraries are accessible only in read-only mode and cannot be replaced.
Lastly when installing or updating a RPM package, multiple executables may be 
involved in this procedure (for example for the package 

openssh

 the certified 

applications are 

/usr/bin/ssh

/usr/sbin/sshd

/usr/bin/ssh-keygen

);

The Administrator must follow these steps to perform the system update or to add a 
new certified application:

1. Start the system in learning mode;
2. Perform the system update or install the new application;

1. For a new installed application add the executable to the file 

/etc/kma/signed_binaries

 (see section 4.3)

2. For a new installed application build the filesystem configuration and add 

new files to the measurements file list 

/etc/kma/checkfilelist

 (it may be 

not necessary in case of the application only need to access directly to a 
device) (see sections 4.4 and 4.5);

3. Execute the utility 

init_masterkey.sh

 (stop Trousers: 

service tcsd stop

);

1. Delete the old MasterKey (confirm when requested);
2. Enter the Administrator password (and the SRK password, if requested);
3. Set a new label (TPM v1.2 only);

4. Execute the utility 

kma_write_nv 

(TPM v1.2 only - start Trousers: 

service tcsd 

start

);

1. Enter the secret associated to the NV storage portion;

Open_TC Deliverable 03c.9

23/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

2. Write the same label specified when updating the MasterKey;

5. Execute the command 

certbin --list /etc/kma/signed_binaries

;

6. Execute the command 

kma_directaccess_db 

/etc/kma/logs/directaccess_list

 and delete records containing the tag of 

updated applications;

7. Restart the system in learning mode (only needed for new applications installed 

for which a filesystem configuration has been created)
1. Execute the command 

kma_makesecure.sh /etc/kma/files_saved 

<created filelist>

 to import application's files to the protected 

filesystem; if the file specified as first parameter does not exist this step can 
be skipped;

8. Execute the application;
9. Execute the command 

kma_mmap_db /etc/kma/logs/mmap_list

:

1. The utility notifies if there are duplicate entries with different digest;
2. Specify the correct entry: the Administrator must investigate the current 

digest value, by executing in another shell the command: 

sha1sum <path of 

the loadable item in the filesystem>

;

3. Type the command 

verify

:

1. For each loadable item in the list the program verifies if the digest of a 

loadable item is changed;

2. If a loadable item is changed the program requests to update the value 

stored in the database;

4. Write changes by executing the command 

write

 followed by the new 

filename;

5. Replace the 

/etc/kma/logs/mmap_list

 file with the new file created;

10. Execute the command 

kma_directaccess_list 

/etc/kma/logs/directaccess_list

 to review direct accesses to devices 

performed by certified applications;

11. Check for invalid eCryptfs files by executing the command 

dmesg | grep 

ecryptfs

 (the 

rpm

 utility, when updating a package, creates a new copy of 

existent files by adding a random string as suffix of the name for avoiding 
collisions, then renames the others with the extension 

.rpmnew

 and lastly 

deletes the suffix from the firsts);
1. Copy temporarily invalid files to a backup directory in the unprotected 

filesystem, delete it and recreate them in the original location;

12. Start the system in enforcing mode, and execute the sealing procedure.

NOTE: steps 9.4 and 9.5 are required only if one or more entries in the database of 
mapped libraries are updated (in case of duplicated entries or a loadable items 
modified). If the database is not correctly updated during the boot process this 
message may be displayed and the system is not able to boot:

Error: duplicated entry /lib/libvolume_id.so.1.0.1, digests:

Open_TC Deliverable 03c.9

24/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

526350333ecb1804ec946761f90e985574cdc1ed

bc605ced62d035fddf4d095f4b38b0198f9d17e1

In case of a library or an application is updated and the learning process has not been 
executed the certified application stop working and in the system log is present a 
similar message:

Error: sshd[2120] tried to mmap the loadable /lib/libz.so.1.2.3: library 

has been modified

Running steps listed at point 9 is useful to detect if a library used by a certified 
application is changed.

 4.12.2  Adding to the database /etc/kma/logs/mmap_list non discovered libraries

It may happen that a library has not discovered in the learning phase, for example 
because some libraries are loaded only if a particular function of the application is 
activated. If a certified application tries to mmap a library that doesn't exist in the 
database it will be killed by the kernel. The user can verify the operation that caused 
the termination of the process by seeing the system log by prompting the command 

dmesg

.

An example of an error message is:

Error: sshd[2134] tried to mmap the loadable /lib/libz.so.1.2.3: item not 
found in the list

or

Error: sshd[2134] tried to mmap the loadable /lib/libz.so.1.2.3: tag 
kma0002 not in the list of allowed tags

In the first case the library specified has not been discovered by any certified 
application. In the second one, the library has been discovered by other certified 
applications.
The Administrator, after having verified the library, can include it in the database by 
executing these steps:

1. Execute the utility 

init_masterkey.sh

 (stop Trousers: 

service tcsd stop

);

1. Delete the old MasterKey (confirm when requested);
2. Enter the Administrator password (and the SRK password, if requested);
3. Set a new label (TPM v1.2 only);

2. Execute the utility 

kma_write_nv 

(TPM v1.2 only - start Trousers: 

service tcsd 

start

);

1. Enter the secret associated to the NV storage portion;
2. Type the same label specified when updating the MasterKey;

3. Execute the command 

kma_mmap_db /etc/kma/logs/mmap_list

;

1. At the prompt type the command 

add

;

2. Specify the file to include;
3. Specify the TAG of the application that is allowed to map it;
4. Type the command write followed by the new file name containing the 

Open_TC Deliverable 03c.9

25/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

updated database;

4. Replace the file /

etc/kma/logs/mmapped_list

 with the new file created;

5. Restart the sealing procedure by rebooting the system in enforcing mode.

If there are too many libraries to add another possibility is to execute the steps 
described in the section 4.12.1 without the point 4.

 4.12.3  Adding to the database /etc/kma/logs/directaccess_list the processes that 
require direct access to devices

The Administrator during the learning mode defines what processes will be allowed to 
access devices. When the system is executed in enforcing mode, non-authorized tasks 
cannot access protected devices. Each attempt is recorded by the kernel that displays 
a message (and records in the system log) like this:

Error: process fdisk[1428] is not authorized to access dev/sdx

If the Administrator wants to authorize the application to directly access a device, 
he/she must execute the procedure for new certified applications described in the 
section 4.12.1.

 4.12.4  Allowing new or updated modules to be loaded in the kernel 

Following steps need to be performed by the Administrator in order to add extra 
modules to database or to fix the case of duplicated entries:

1. Execute the utility 

init_masterkey.sh

;

1. Delete the old MasterKey (confirm when requested);
2. Enter the Administrator password (and the SRK password, if requested);
3. Set a new label (TPM v1.2 only);

2. Execute the utility 

kma_write_nv 

(TPM v1.2 only - start Trousers: 

service tcsd 

start

);

1. Enter the secret associated to the NV storage portion;
2. Type the same label specified when updating the MasterKey;

3. Reboot the system in learning mode;
4. Execute the command 

insmod <kernel module file>

 or 

modprobe <kernel 

module name>

 for each module to add to the database;

5. Review the database of modules by executing the command 

kma_modules_db /

etc/kma/logs/modules_list

;

1. If there are duplicate entries, the utility asks to update the digest value of 

the module;

2. If the database has been modified, type the command 

write

 followed by a 

filename;

6. Replace the file 

/etc/kma/logs/modules_list

 with the new file just created;

7. Reboot the system in enforcing mode and restart the sealing procedure.

In case of duplicated entries KMA will not be able to boot and it displays this message 

Open_TC Deliverable 03c.9

26/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

during the boot process:

Error: duplicated entry <module name>, digests:

526350333ecb1804ec946761f90e985574cdc1ed
bc605ced62d035fddf4d095f4b38b0198f9d17e1

Note: in case of kernel update a recommended is deleting the file 

/etc/kma/logs/modules_list

 before executing the procedure described 

above.

 4.12.5  Updating the system – a file included in /etc/kma/checkfilelist is changed

If one file of the list is changed, the sealing of the MasterKey must be restarted in 
order to include in the sealed blob the updated PCRs. The Administrator must execute 
the steps 1-2 in the section 4.12.4, start the utility 

init_masterkey.sh

 and reboot the 

system in enforcing mode. If the MasterKey bound blob is present, the Administrator 
can seal the same MasterKey and KMA can work without doing extra steps; otherwise 
if the bound blob has been deleted, the MasterKey 

WILL NOT BE RECOVERABLE

, a 

new key should be generated and all data saved in the protected filesystem 

WILL BE 

LOST

. The bound blob needs therefore to be backed up.

 4.12.6  Updating filesystem policies

The Administrator may decide to revoke the access to an application, for example 
because a vulnerability has been discovered. The file 

/etc/kma/template.conf

 or 

another file containing policies changes and, if the pathname has been included in 

/etc/kma/checkfilelist

, the same procedure described in section 4.12.5 must be 

followed.

 4.12.7  Restoring access to a renamed or a moved eCryptfs file

This issue can be solved by the Administrator that can decide if the file will be made 
available to regular users by executing the following steps:

1. Execute steps 1-2 in the section 4.12.4;
2. Reboot the system in learning mode;
3. Inspects all files moved from their regular position by executing the command 

dmesg | grep ecryptfs

. The Administrator must inspect this type of message:

1.

ecryptfs_parse_packet_set: Error: file /system/ssh/sshd_config 
in the protected filesystem has been moved from the original 
position

;

4. Copy temporarily invalid files to a backup directory in the unprotected 

filesystem, delete and recreate them in the original location.

5. Restart the sealing procedure.

 5  Removing KMA

In order to remove the KMA software these steps must be performed by the 
Administrator:

Open_TC Deliverable 03c.9

27/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

1. Reboot the system in learning mode in order to access all saved data in the 

protected filesystem;

2. Execute the command 

kma_makeinsecure.sh

: this copies all protected 

directories to the unprotected filesystem by removing symlinks and creating 
instead directories with the same name

3. Open YaST/Software Management;
4. Select the entry “

Repositories

” from the tab “

Filter

”;

5. Select the KMA repository from the repositories list;
6. Remove all packages from this repository;
7. Reinstall the 

openCryptoki

 and the 

firefox

 packages included in the 

openSUSE distribution.

 6  List of all command used with parameters

init_masterkey.sh <destination directory>

: generates the MasterKey, 

eventually appends a label to the former, creates a blob of them by using a 
newly generated TPM wrapping key;

certbin --list <signed files list> 

: certifies a list of binaries;

kma_mmap_db <mmap file list>

: used to inspect libraries mapped by certified 

applications or to modify this list. Commands:

view

tag

: display all libraries mapped by each tag

libraries

: display all tags that use each library

add

library

: a new library to be included in the list

tag

: the tag allowed to use this library

verify

used to compare all digests stored in the database with actual values

write

<filename>

: writes the modifications to a file called filename

quit

kma_directaccess_db <directaccess list>

: used to inspect direct accesses 

to devices by certified applications. Commands:

view

view the list of current rules 

add

tag

: certified application

<device name>

: pathname of the device that the certified application will 

access

Open_TC Deliverable 03c.9

28/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

<permission>

: type of operation the certified application is allowed to 

perform

modify

<entry identifier>

: cardinal number that identifies an element of the 

list; it can be seen by executing the command view

tag

: certified application

<device name>

: pathname of the device that the certified application will 

access

<permission>

: type of operation allowed to the certified application

delete

<entry identifier>

: cardinal number that identifies an element of the 

list

: it can be seen by executing the command view

write

<filename>

: writes the modifications to a file called filename

quit

kma_modules_db <modules list>

: used to review the list of modules will be 

allowed to load when the KMA is executed in enforcing mode and their digest

view

display the list of modules

delete

<entry number>

: cardinal number that identifies an element of the list: it 

can be seen by executing the command view

write

<filename>

: writes a modified database to a file called filename

kma_makesecure.sh <file list> <output file>

: used to copy files from the 

unprotected filesystem to the protected one;

file list

: by default 

/etc/kma/files_saved

;

output file

: filename that will be created and will contain files effectively 

copied in the protected filesystem and the relative SHA1.

kma_makeinsecure.sh

: used to restore the original configuration before the 

KMA installation: deletes symlinks, replaces them with directories having the 
same name and copies to files from the protected filesystem;

kma_policy.sh <path of symlink>

: used to show the policy associated to a 

protected directory

kma_define_nv

: defines a new space in the NV storage of the TPM (only v1.2) 

starting at index 0x00011136 and set a secret to protect the write operation; 
the owner's password is required

kma_write_nv

: writes 10 bytes inserted by the Administrator to the defined 

space in the NV storage, after prompting the secret set

Open_TC Deliverable 03c.9

29/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

kma_read_nv

: reads 10 bytes from the index 0x00011136 of the NV storage 

without requiring any authorization

kma_release_nv

: releases the space defined in the NV starting at index 

0x00011136; the owner password is required.

 7  Workarounds

Subversion:

Problem: if the 

$HOME/.subversion

 directory has not been initialized before the 

KMA installation, 

svn

 is unable to setup the directory tree;

Solution: the user must create the directory 

$HOME/auth/svn.simple

 before 

using the 

svn

 utility, in order store its passwords in the protected filesystem.

 8  PKCS#11 library configuration

A modified version of the library 

openCryptoki

 is distributed together with the KMA 

software. This allows using software tokens together with the protection offered by 
KMA.
In a KMA-enabled system tokens are saved in the cryptographic filesystem; accesses 
to data files are controlled by the KMA mandatory access control mechanism and are 
granted depending on the policies configured by the Administrator. He decides, 
depending on the users of the platform, the applications installed and the security 
requirements he wants to apply, how many tokens will be assigned to each user and 
how they will be accessed. Typical configurations are:

One token assigned to each user, accessible to all or a subset of PKCS#11 
enabled applications;

Two tokens: one for applications that require an high security level and one for 
all other applications;

Multiple tokens.

 8.1  Token configuration – Administrator side

The data backend of each token is stored in a directory under the path 

/var/lib/openCryptoki/swtok

. The Administrator must define the directory name 

and a filesystem policy which will be valid for all users. These steps must be 
performed (as alternative for the steps in the following which require manual editing of 
configuration files, it is possible to append the content of the files with suffix ".pkcs11" 
present in 

/etc/kma/sample_config

 to the files with the same name in 

/etc/kma

):

1. Start the system in learning mode;
2. Install these packages from the configured KMA repository: 

openCryptoki_kma

openCryptoki_kma-32bit

MozillaFirefox-bin

; confirm the deletion of the 

existent packages if installed: 

openCryptoki

openCryptoki-32bit

MozillaFirefox

;

1. Add these records in the file 

/etc/kma/signed_binaries

:

1.

/opt/firefox-<version>/firefox-bin

0

<TAG>

Open_TC Deliverable 03c.9

30/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

2.

/usr/sbin/pkcsconf

0

<TAG>

2. Define the filesystem policy for each token as described in the section 4.4. It 

is recommended to assign at least one token to each user of the platform:
1. Directory policy in 

/etc/kma/template.conf

: the Administrator 

configures a protected directory for each token will be created. Each 
statement must contain: 
1.

directory /system/opencryptoki/swtok/<token dirname> {

2.

bounddir /var/lib/opencryptoki/swtok/<token dirname>

3.

permission 775

4.

owner 0:<GID of the pkcs11 group>

5.

access_mask |<tag of pkcsconf>|<UID>|

6.

access_mask |<tag of firefox>|<UID>|

7.

policyfile /root/etc/kma/pkcs11_users_config

8.

}

2. File policy 

/root/etc/kma/pkcs11_users_config

1.

file * {

2.

|XXXX|$UID|

c

3.

|XXXX|$UID|

rw

4.

}

3. Set the 

pkcsslotd

 service to be executed at system startup:

1. Open 

YaST/System/System Services (Runlevel)

;

2. Select the entry 

pkcsslotd

;

3. Click on the button 

Enable;

4. Confirm the operation;

4. Execute the utility 

init_masterkey.sh

 (stop Trousers: 

service tcsd stop

);

1. Delete the old MasterKey (confirm when requested);
2. Enter the Administrator password (and the SRK password, if requested);
3. Set a new label (TPM v1.2 only);

5. Execute the utility 

kma_write_nv

 (TPM v1.2 only - start Trousers: 

service tcsd 

start

);

1. Enter the secret associated to the NV storage portion;
2. Write the same label specified when updating the MasterKey;

6. Certify the new applications installed by executing the command: 

1.

certbin --list /etc/kma/signed_binaries 

7. Execute the learning of 

firefox

: the operations described in the section 8.3 

Installing software token in firefox

” must be performed with root 

Open_TC Deliverable 03c.9

31/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

privilege;

8. Execute the utility 

pkcsconf

 without parameters: it server just for KMA to learn 

about the libraries the utility depends on

;

9. Create the 

/etc/kma/pkcs11_mapping

 file:

1. Assign a different profile name to each token assigned to a user; 
2. For each user and profile write as many records as the access vectors listed 

in the directory policy like this: 
1.

PROFILE_NAME

access vector

token_directory 

10.Review libraries loaded by the new certified applications, executing the 

command 

kma_mmap_db /etc/kma/logs/mmap_list

 (for all details see step 9 in 

section 4.12.1):
1. Type the command 

verify

;

2. Replace the database 

/etc/kma/logs/mmap_list

 if modified;

11.Restart the system in learning mode

1. Execute the command 

dmesg | more

 and verify that the message “

Failed 

to initialize protected filesystem

” doesn't appear;

2. In case of the 

openCryptoki

 library has previously installed and tokens 

were created start the command 

kma_makesecure.sh 

/etc/kma/files_saved <output file>;

12.Add each user allowed to access the PKCS#11 library in the “

pkcs11

” group 

(modify the file 

/etc/groups

 with superuser privileges);

13.Add created filesystem policy files to 

/etc/kma/checkfilelist

1.

/etc/kma/pkcs11_users_config

2.

/etc/kma/pkcs11_mapping

14.Restart the sealing procedure, i.e. reboot in enforcing mode and after the 

sealing is done, reboot again in enforcing mode.

 8.2  Token configuration – User side

Each user is assigned a number of tokens, depending on the filesystem policy defined 
by the Administrator. To easy identify a particular token a profile name is assigned. 
The user can discover and setup its tokens by running the utility 

kma_pkcs11_conf

.

The initialization consists of setting two passwords (PINs in PKCS#11 slang): the first 
one is called Security Officer (SO) PIN (the hardcoded default PIN will be changed) and 
allows access to token administration functions, otherwise the User PIN allows the 
access to the token's data. When a software token is initialized a master key for each 
PIN is generated in order to protect the objects stored in that software device. A 
typical output of the script is:

Entry ID Profile name Dirname

Pathname

1

DEFAULT

root.token1

/opt/firefox-3.0.10/firefox-bin

Open_TC Deliverable 03c.9

32/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

2

DEFAULT

root.token1

/usr/sbin/pkcsconf

The first column specifies a cardinal number to identify the record, the second column 
specifies the profile name assigned to each user's token, the third contains the target 
directory in the path 

/var/lib/opencryptoki/swtok

, the fourth specifies the 

application allowed to use it.
Conditions necessary for using a token are:

1. the platform is running the KMA services ;
2. the integrity of the platform has been verified by the unsealing procedure;
3. the application accessing it is certified;
4. the filesystem policy of the token directory has been defined by the 

Administrator and it is enforced.

Steps executed by the user:

1. start the initialization script 

kma_pkcs11_conf;

2. select the token by typing its identification number (select one entry for each 

profile)
1. NOTE: if the token is already initialized the user is asked if he/she want to 

reinitialize it. In that case it's possible reinitialize typing YES (in capital 
letters) and pressing <ENTER>. If you do not want to reinitialize the token 
type NO and then press <ENTER>, the procedure will finish at this step.

3. set a new label for this soft-token

1. insert the default SO PIN 

87654321

 upon request and press <ENTER>

2. insert a label that identifies this token and press <ENTER>

4. change the SO PIN

1. insert the default SO PIN 

87654321

 upon request and press <ENTER>

2. insert a new SO PIN upon request and press <ENTER>
3. re-insert the SO PIN upon request and press <ENTER>

5. set the User PIN

1. insert the chosen SO PIN upon request and press <ENTER>
2. insert a new User PIN upon request and press <ENTER>
3. re-insert the User PIN upon request and press <ENTER>

6. set up the user file 

$HOME/.profile

 by adding the line at the end (this will be 

valid at the next user login):
1.

export TOKENPROFILE=<profile to use>

 (e.g. DEFAULT)

 8.3  Install software token in Firefox

1. start Mozilla Firefox;
2. click on the “Edit” button and select “Preferences”, a window with that title will 

Open_TC Deliverable 03c.9

33/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

be opened;

3. select the tab “Advanced/Encryption” and then click on the button “Security 

Devices”, a window called “Device Manager” will be opened;

4. click on the button “Load”, a box called “New PKCS#11 Module” will be opened;
5. change the default Module Name (e.g. into “KMA-protected”);

1. insert in the “Module filename” field the string 

/usr/lib/pkcs11/PKCS11_API.so 

[or search it using the button Browse]

2. confirm the operation clicking OK in order to close the windows

 8.4  Test and use the software token with Firefox

1. start Mozilla Firefox;
2. click on the “Edit” button and select “Preferences”, a window with that title will 

be opened;

3. select the tab “Advanced/Encryption” and then click on the button “Security 

Devices”, a window called “Device Manager” will be opened;

4. click on the label previously entered (e.g. “KMA-protected”) and the on “IBM OS 

PKCS#11”;

5. Then click on the button “Log in” and use the user PIN: if the login is successful, 

this means that the software token is working properly; it can be used for 
instance to create an asymmetric key pair and make a request for an X.509 
certificate;

6. Use the standard 

pkcsconf

 (shipped with 

openCryptoki

) to perform the 

management of the software token (see the related documentation for details).

 9  Glossary

Property

: this is an information associated to a process or a system component 

that permits to identify it or to know its status;

Access vector

: this is an object which stores properties values: each field is 

bound to a specific property (for example field 0 is bound to the "TAG" property, 
field 1 is bound to the "UID" property);

Access vector permission

: this describes allowed operations that a subject 

identified by the access vector can do to a file (or a generic object): "r" for read, 
"w" for write, "x" for execution, "a" for append permission (combinations of 
these are possible);

Label

: this element associated to an object (file or directory) contains a set of 

access vectors with their relative access vector permission;

Directory policy

: this is an object that contains the label associated to the 

directory, the pathname of the file policy and other parameters used for 
management;

Protected directory

: this is a directory with a directory policy defined;

File policy

: set of labels to be applied for existent or newly created files in a 

Open_TC Deliverable 03c.9

34/35

background image

 

 

WP03c.9 Enhancement KMA service source code and documentation FINAL 1.10

protected directory.

 10  List of Abbreviations

Listing of term definitions and abbreviations used in this document (IT expressions and 
terms from the application domain).

Abbreviation

Explanation

KMA

Key and data Management Adaptation layer

SRK

Storage Root Key

NV storage

Non Volatile storage

TCG

Trusted Computing Group

TPM

Trusted Platform Module

TSS

TCG Software Stack

 11  Related Work

/1/ TCG TPM Main Specification (parts 1,2,3)
July 9, 2007,
Version 1.2 Level 2 Revision 103

/2/ IETF RFC 4251, The Secure Shell (SSH) Protocol Architecture
January, 2006

/3/ TCG Software Stack (TSS) Specification
March 7, 2007,
Version 1.2, Level 1, Errata A

/4/ OpenTC IST-027635/D03c.4/FINAL 2.00
Key Management Adaptation (KMA) service source code and documentation

/5/ OpenTC D03c.10 deliverable
Adapting IPsec configuration tools and IKE demon source code and document

/6/ OpenTC D03c.11 deliverable
PKCS#11 source code and documentation

Open_TC Deliverable 03c.9

35/35


Document Outline