html/OpenTC_D03.3_Collection_of_internal_deliverables

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

Start date of the
project

November 2005

Thematic Priority

IST

Duration

42 months

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

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

Start date of the
project

November 2005

Thematic Priority

IST

Duration

42 months

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

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

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

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

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

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

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

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

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)

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

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 (

) 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

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

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:

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).

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

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 (

) 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

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

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

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

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

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.

aaSignature

MUST be sent to the server as

DAASignature

element of the list

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

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

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

INTEGER,

-- sV

sF0

INTEGER,

-- sF0

sF1

INTEGER,

-- sF1

INTEGER,

-- sE

nonceVerifier

INTEGER,

-- nV

}

TssVersion ::= SEQUENCE
{

major

INTEGER,

minor

INTEGER,

revMajor

INTEGER,

revMinor

INTEGER

}

Open_TC Deliverable 03c.3

23/27

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

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

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

Certification Authority

DAA

Direct Anonymous Attestation

DER

Distinguished Encoding Rules

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

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

Start date of the
project

November 2005

Thematic Priority

IST

Duration

42 months

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

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

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

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

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

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

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

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

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

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

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

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

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

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 *

, 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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.

daa_do_sign()

returns a

DAA_SIG

structure.

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

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
a

DAA_SIG

structure, invoking

d2i_DAA_SIG()

(which relies on a primitive

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

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.

daa_do_verify()

returns either success or failure.

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

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

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

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

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

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 *

, TLSEXT_GENERAL *

)

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

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

making the DAA signature.

Parameters:

a pointer to the SSL object

a pointer to the DAA extension

int ssl_tlsext_daa_server_ext_cb (SSL *

, TLSEXT_GENERAL *

)

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:

a pointer to the SSL object

a pointer to the DAA extension

int ssl_tlsext_daa_server_finish_cb (SSL *

, TLSEXT_GENERAL *

)

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:

a pointer to the SSL object

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

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

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

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 *

, 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:

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

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

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

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

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

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

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

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

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 **

, const unsigned char **

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:

Pointer to the DAA_KEY (platform credential) structure.

Pointer to the buffer.

len

Buffer length.

Returns:

the DAA_KEY (platform credential) structure.

int i2d_daatcg_key (const DAA_KEY *

, 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:

the DAA_KEY (platform credential) structure.

out

Pointer to the buffer.

Returns:

the buffer length.

Open_TC Deliverable D03c.6

45/61

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 **

, const unsigned char **

, 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:

Pointer to the DAA_ISSUER (issuer credential) structure.

Pointer to the buffer.

len

Buffer length.

Returns:

the DAA_ISSUER (issuer credential) structure.

int i2d_daatcg_issuer (const DAA_ISSUER *

, 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:

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

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

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

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

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

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 *

, unsigned

char *

, unsigned char *

limit

)

Processes the extensions within the SSL object

and appends their content to

the buffer

, 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 *

, unsigned

char *

, unsigned char *

limit

)

Processes the extensions within the SSL object

and appends their content to

the buffer

, 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 *

, 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 *

, 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 *

)

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

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 *

)

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)

(ext->server_send == 1)

Supplemental data entry pool:

ext->client_supp_data

ext->server_supp_data

Parameters of

s->method->ssl_get_message

Call to

ssl3_get_server_supp_data()

ssl3_get_client_supp_data()

int ssl3_send_client_supp_data (SSL *

)

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)

(ext->server_send == 1)

Supplemental data entry pool:

ext->client_supp_data

ext>server_supp_data

The callback to invoke:

ext->client_supp_data_callback()

ext->server_supp_data_callback

int ssl_tlsext_general_client_finish_cb (SSL *

)

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:

int ssl3_send_server_supp_data (SSL *

)

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

libssl

Open_TC Deliverable D03c.6

52/61

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)

(ext->server_send == 1)

Supplemental data entry pool:

ext->client_supp_data

ext->server_supp_data

The callback to invoke:

ext->client_supp_data_callback()

ext->server_supp_data_callback

int ssl3_get_client_supp_data (SSL *

)

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)

(ext->server_send == 1)

Supplemental data entry pool:

ext->client_supp_data

ext->server_supp_data

Parameters of

s->method->ssl_get_message

Call to

ssl3_get_server_supp_data()

ssl3_get_client_supp_data()

int ssl_tlsext_general_server_finish_cb (SSL *

)

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 *

)

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:

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

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 **

, const unsigned char **

, long

len

)

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

Parameters:

Pointer to the DAA_SIG structure.

Pointer to the buffer.

len

Buffer length.

Returns:

Pointer to the DAA_SIG structure.

int i2d_daa1_sig (const DAA_SIG *

, unsigned char **

out

)

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

Parameters:

Pointer to the DAA_SIG structure.

out

Pointer to the buffer.

Open_TC Deliverable D03c.6

54/61

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 **

, const unsigned char **

, long

len

)

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

Parameters:

Pointer to the DAA_SIG structure.

Pointer to the buffer.

len

Buffer length.

Returns:

Pointer to the DAA_SIG structure.

int i2d_daa3_sig (const DAA_SIG *

, unsigned char **

out

)

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

Parameters:

Pointer to the DAA_SIG structure.

out

Pointer to the buffer.

Open_TC Deliverable D03c.6

55/61

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 **

, const unsigned char **

long

len

)

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

Open_TC Deliverable D03c.6

56/61

OpenSSL engine/DAA enhancement design specification

FINAL | 2.00

buffer.
Relies on d2i_DAAFAKE_SIG().

Parameters:

Pointer to the DAA_SIG structure.

Pointer to the buffer.

len

Buffer length.

Returns:

Pointer to the DAA_SIG structure.

int i2d_daafake_sig (const DAA_SIG *

, unsigned char **

out

)

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

Parameters:

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

)

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

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

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

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

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

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

Start date of the
project

November 2005

Thematic Priority

IST

Duration

42 months

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Start date of the
project

November 2005

Thematic Priority

IST

Duration

42 months

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

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

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

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

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

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:

zypper si <source packages listed in the section 2.3.1>;

zypper install <packages listed in the section 2.3.1>;

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

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

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:

%define flavors_to_build kma default pae

7. Modify this line as follow:

%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

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

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

/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:

modprobe tpmd_dev

(executing the kernel-side portion of the TPM emulator)

tpmd clear

(executing the user-side portion of the TPM emulator)

Open_TC Deliverable 03c.9

10/35

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

service tcsd start

(executing the trouser daemon)

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

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

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

/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

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:

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

0001

/usr/sbin/sshd

0002

/usr/sbin/racoon

0003

/usr/sbin/setkey

0004

/usr/bin/ssh-keygen

0005

/usr/bin/nano

0006

/bin/ls

0007

/bin/rm

0008

/usr/bin/svn

0009

/usr/sbin/smartd

0010

/sbin/swapon

0011

/lib/udev/edd_id

0012

/lib/udev/scsi_id

0013

/lib/udev/ata_id

0014

/lib/udev/vol_id

0015

/usr/sbin/dmidecode

0016

/opt/firefox/firefox-bin

0017

/usr/sbin/pkcsconf

0018

/opt/thunderbird/thunderbird-bin

0019

/usr/bin/Xorg

0020

Open_TC Deliverable 03c.9

13/35

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

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):

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:

●

Document Outline