Digital PDFs

XX-XXXXX-XX

2000

355 pages

Original

2.4MB

Document:	Lost document 26284
Order Number:	XX-XXXXX-XX
Revision:	000
Pages:	355
Original Filename:	http://www.digiater.nl/openvms/decus/vmslt05a/net/cl-manual.pdf

OCR Text

Security Toolkit
Version 3.2.2
Copyright Peter Gutmann 1992-2005

September 2005

cryptlib Overview

INTRODUCTION
cryptlib Overview
cryptlib features
Architecture
S/MIME
PGP/OpenPGP
Secure Sessions
Plug-and-play PKI
Certificate Management
CA Operations
Crypto Devices and Smart Card Support
Certificate Store Interface
User Interface
Security Features
Embedded Systems
Performance
Cryptographic Random Number Management
Programming Interface
Documentation
Algorithm Support
Standards Compliance
Y2K Compliance
Configuration Options
cryptlib Applications
Encryption Code Example
Secure Session Code Example
Certificate Management Code Example
Document conventions
Recommended Reading

INSTALLATION
AMX
BeOS
ChorusOS
DOS
DOS32
eCOS
µC/OS-II
Embedded Linux
µITRON
Macintosh OS X
MVS
OS2
PalmOS
QNX Neutrino
RTEMS
Tandem
uClinux
Unix
VM/CMS
VxWorks
Windows 3.x
Windows 95/98/ME and Windows NT/2000/XP
Windows CE / Pocket PC / SmartPhone
Xilinx XMK
Other Systems
Key Database Setup
Customised and Cut-down cryptlib Versions
Debug vs. Release Versions of cryptlib

1
1
2
2
3
3
4
4
4
6
8
8
9
9
10
10
11
11
11
12
12
13
13
13
14
14
15
15
15

17
17
17
17
17
17
17
18
18
18
18
18
18
19
19
19
19
19
20
20
21
21
21
22
22
23
23
24
24

Introduction

cryptlib Version Information
Support for Vendor-specific Algorithms

CRYPTLIB BASICS
Programming Interfaces
Container Object Interface
Mid-level Interface
Action Object Interface
Objects and Interfaces
Objects and Attributes
Interfacing with cryptlib
Initialisation
C / C++
C# / .NET
Delphi
Java
Python
Tcl
Visual Basic
Return Codes
Working with Object Attributes
Attribute Types
Attribute Lists and Attribute Groups
Attribute Cursor Management
Object Security
Role-based Access Control
Managing User Roles
Creating and Destroying Users and Roles
Miscellaneous Issues
Multi-threaded cryptlib Operation
Interaction with External Events

25
25

26
27
27
27
27
27
28
29
29
30
30
30
31
32
32
32
32
33
35
37
38
41
43
43
44
45
45
46

SECURITY AND USABILITY

Security Usability Fundamentals
Theoretical vs. Effective Security
User Conditioning
Security at Layers 8 and 9
Ease of Use
Automation vs. Explicitness
Safe Defaults
Interaction with other Systems
Matchi
ngUs
e
r
s
’Me
nt
alMode
l
s
Activity-Based Planning
Use of Familiar Metaphors
Speakingt
heUs
e
r
’
sLa
ng
ua
g
e
Use of Visual Cues
Usability Testing
Pre-implementation Testing
Post-implementation Testing
Post-delivery Reviews

47
47
47
48
49
49
50
51
51
52
53
54
55
56
56
57
59

DATA ENVELOPING
Creating/Destroying Envelopes
The Data Enveloping Process
Data Size Considerations
Basic Data Enveloping
Compressed Data Enveloping

60
60
61
63
64
65

cryptlib Overview

Password-based Encryption Enveloping
Conventional Encryption Enveloping
De-enveloping Mixed Data
De-enveloping with a Large Envelope Buffer
Obtaining Envelope Security Parameters
Enveloping Large Data Quantities
Alternative Processing Techniques
Enveloping with Many Enveloping Attributes

ADVANCED ENVELOPING
Public-Key Encrypted Enveloping
Digitally Signed Enveloping
Enveloping with Multiple Attributes
Processing Multiple De-enveloping Attributes
Nested Envelopes

S/MIME
S/MIME Enveloping
Encrypted Enveloping
Digitally Signed Enveloping
Detached Signatures
Alternative Detached Signature Processing
Extra Signature Information
Timestamping

PGP
PGP Enveloping
Encrypted Enveloping
Digitally Signed Enveloping
Detached Signatures

FROM ENVELOPES TO EMAIL
S/MIME email
Data
Signed Data
Detached Signature
Encrypted Data
Nested Content
PGP email
Implementing S/MIME and PGP email using cryptlib
c-client/IMAP4
Eudora
MAPI
Windows 95/98/ME and NT/2000/XP Shell

SECURE SESSIONS
Creating/Destroying Session Objects
Client vs. Server Sessions
Server Names/URLs
Server Private Keys
Establishing a Session
Persistent Connections
SSH Sessions
SSH Client Sessions
SSH Server Sessions
SSH Channels
SSH Subsystems
SSH Port Forwarding

iii

66
68
69
70
70
71
72
73

75
75
79
81
82
84

86
86
87
89
90
91
92
93

95
95
95
97
97

100
100
100
100
100
101
101
101
102
102
103
103
103

105
105
107
107
108
109
109
110
110
111
113
114
115

Introduction

SSH Multiple Channels
SSL/TLS Sessions
SSL/TLS Client Sessions
SSL/TLS with Shared Keys
SSL/TLS with Client Certificates
SSL/TLS Server Sessions
SSL/TLS Servers with Shared Keys
SSL/TLS Servers with Client Certificates
Request/Response Protocol Sessions
RTCS Server Sessions
OCSP Server Sessions
TSP Server Sessions
Obtaining Session Status Information
Obtaining Session Security Parameters
Authenticating the Host with Key Fingerprints
Authenticating the Host or Client using Certificates
Authenticating the Client via Port and Address
Exchanging Data
Network Issues
Secure Sessions with Proxies
Network Timeouts
Managing your Own Network Connections and I/O

KEY GENERATION
Creating/Destroying Encryption Contexts
Generating a Key into an Encryption Context
Asynchronous Key Generation

KEY STORAGE
Keyset Types
Creating/Destroying Keyset Objects
File Keysets
HTTP Keysets
Database Keysets
LDAP Keysets
Reading a Key from a Keyset
Obtaining a Key for a User
General Keyset Queries
Handling Multiple Certificates with the Same Name
Key Group Management
Writing a Key to a Keyset
Changing a Private Key Password
Deleting a Key

CERTIFICATES AND CERTIFICATE MANAGEMENT
High-level vs. Low-level Certificate Operations
Plug-and-play PKI
Mid-level Certificate Management
Low-level Certificate Management
Certificates and Keys
Using Separate Signature and Encryption Certificates
Plug-and-play PKI
Simple Certificate Creation
The Certification Process
Obtaining Certificates using CMP
CMP Certificate Requests

116
117
118
119
119
120
120
121
122
122
123
123
124
124
124
124
125
125
127
127
127
128

131
131
131
132

133
133
134
135
136
137
139
141
141
143
145
145
146
147
148

149
149
149
149
149
150
150
151
152
154
157
158

cryptlib Overview

CMP Operation Types
CMP Sessions
Obtaining Certificates using SCEP
SCEP Certificate Requests
SCEP Sessions
Certificate Status Checking using RTCS
Basic RTCS Queries
Creating an RTCS Request
Communicating with an RTCS Responder
Advanced RTCS Queries
Certificate Revocation Checking using OCSP
Basic OCSP Queries
Creating an OCSP Request
Communicating with an OCSP Responder
Advanced OCSP Queries

MANAGING A CERTIFICATION AUTHORITY

159
160
162
162
162
164
164
165
166
167
168
168
168
169
170

171

Creating the Top-level (Root) CA Key
Initialising PKI User Information
Other PKI User Information
PKI User IDs
Managing a CA using CMP or SCEP
Making Certificates Available Online
Managing a CA Directly
Recording Incoming Requests
Retrieving Stored Requests
CA Management Operations
Issuing and revoking a Certificate
Issuing a CRL
Expiring Certificates
Recovering after a Restart

171
173
174
175
176
177
179
179
179
180
181
181
181
181

ENCRYPTION AND DECRYPTION

183

Creating/Destroying Encryption Contexts
Generating a Key into an Encryption Context
Deriving a Key into an Encryption Context
Loading a Keys into an Encryption Context
Working with Initialisation Vectors
Loading Public/Private Keys
Loading Multibyte Integers
Querying Encryption Contexts
Using Encryption Contexts to Process Data
Conventional Encryption
Public-key Encryption
Hashing

EXCHANGING KEYS
Exporting a Key
Exporting using Conventional Encryption
Importing a Key
Importing using Conventional Encryption
Querying an Exported Key Object
Extended Key Export/Import
Key Agreement

SIGNING DATA

183
184
185
186
186
187
187
189
189
190
191
191

193
193
194
195
195
196
196
197

199

Introduction

Querying a Signature Object
Extended Signature Creation/Checking

CERTIFICATES IN DETAIL
Overview of Certificates
Certificates and Standards Compliance
Certificate Compliance Level Checking
The Certification Process
Creating/Destroying Certificate Objects
Working with Certificate Attributes
Certificate Structures
Attribute Certificate Structure
Certificate Structure
Certification Request Structure
CRL Structure
Basic Certificate Management
Certificate Identification Information
DN Structure for Business Use
DN Structure for Private Use
DN Structure for Use with a Web Server
Other DN Structures
Working with Distinguished Names
Creating Customised DNs
Extended Certificate Identification Information
Working with GeneralName Components
Certificate Fingerprints
Importing/Exporting Certificates
Signing/Verifying Certificates
Certificate Chains
Working with Certificate Chains
Signing Certificate Chains
Checking Certificate Chains
Exporting Certificate Chains
Certificate Revocation using CRLs
Working with CRLs
Creating CRLs
Advanced CRL Creation
Checking Certificates against CRLs
Automated CRL Checking
Certificate Trust Management
Controlling Certificate Usage
Implicitly Trusted Certificates
Working with Trust Settings

CERTIFICATE EXTENSIONS
Extension Structure
Working with Extension Attributes
Extension Cursor Management
Composite Extension Attributes
X.509 Extensions
Alternative Names
Basic Constraints
Certificate Policies, Policy Mappings, and Policy Constraints, and Policy Inhibiting
CRL Distribution Points/Freshest CRL and Subject/Authority Information Access
Directory Attributes
Key Usage, Extended Key Usage, and Netscape certificate type

200
200

203
203
203
204
206
206
207
207
208
209
211
211
212
214
215
215
216
216
216
217
219
220
220
221
223
225
225
226
227
228
228
228
229
229
230
231
231
231
232
232

234
234
234
235
237
238
238
238
239
240
241
241

cryptlib Overview

vii

Name Constraints
Private Key Usage Period
Subject and Authority Key Identifiers
CRL Extensions
CRL Reasons, CRL Numbers, Delta CRL Indicators
Hold Instruction Code
Invalidity Date
Issuing Distribution Point and Certificate Issuer
Digital Signature Legislation Extensions
Certificate Generation Date
Other Restrictions
Reliance Limit
Signature Delegation
Qualified Certificate Extensions
Biometric Info
QC Statements
SET Extensions
SET Card Required and Merchant Data
SET Certificate Type, Hashed Root Key, and Tunnelling
Application-specific Extensions
OCSP Extensions
Vendor-specific Extensions
Netscape Certificate Extensions
Thawte Certificate Extensions
Generic Extensions

244
245
245
245
245
246
247
247
248
248
248
248
248
249
249
249
249
249
250
251
251
251
251
252
252

OTHER CERTIFICATE OBJECT EXTENSIONS

253

CMS/SMIME Attributes
Content Type
Countersignature
Message Digest
Signing Description
Signing Time
Extended CMS/SMIME Attributes
AuthentiCode Attributes
Content Hints
DOMSEC Attributes
Mail List Expansion History
Nonce
Receipt Request
SCEP Attributes
Security Label, Equivalent Label
Signature Policy
S/MIME Capabilities
Signing Certificate
OCSP Attributes

CRYPTLIB USER INTERFACE COMPONENTS
Displaying Certificates
Key/Certificate Generation

253
253
254
254
254
254
254
255
256
256
256
257
257
257
258
259
260
260
261

262
262
262

ENCRYPTION DEVICES AND MODULES

265

Creating/Destroying Device Objects
Activating and Controlling Cryptographic Devices
Device Initialisation
User Authentication
Device Zeroisation

265
266
266
267
268

viii

Introduction

Working with Device Objects
Key Storage in Crypto Devices
Querying Device Information
Considerations when Working with Devices
Fortezza Cards
PKCS #11 Devices
Installing New PKCS #11 Modules
Accessing PKCS #11 Devices
CryptoAPI

MISCELLANEOUS TOPICS
Querying crypt
l
i
b’
sCapabi
l
i
t
i
e
s
Working with Configuration Options
Querying/Setting Configuration Options
Saving Configuration Options
Obtaining Information About Cryptlib
Random Numbers
Gathering Random Information
Obtaining Random Numbers
Working with Newer Versions of cryptlib

ERROR HANDLING

268
269
269
270
271
271
271
272
272

274
274
274
277
278
278
279
279
280
280

282

Extended Error Reporting

284

EMBEDDED SYSTEMS

287

Embedded OS Types
AMX
ChorusOS
eCOS
µC/OS-II
Embedded Linux
µITRON
Palm OS
QNX Neutrino
RTEMS
uClinux
Windows CE
VxWorks
Xilinx XMK
Embedded cryptlib Configuration Options
Debugging with Embedded cryptlib
Porting to Devices without a Filesystem
Porting to Devices without Dynamic Memory Allocation
Memory Allocation Strategy
cryptlib Memory Usage
Tracking Memory Usage
Porting to Devices without Randomness/Entropy Sources

DATABASE AND NETWORKING PLUGINS
The Database Plugin Interface
Database Plugin Functions
The Network Plugin Interface
Network Plugin Functions
The Crypto Plugin Interface

ALGORITHMS
AES

287
287
288
288
288
288
288
288
289
289
289
289
289
289
290
291
291
291
292
292
293
293

295
295
296
299
299
300

302
302

cryptlib Overview

Blowfish
CAST-128
DES
Triple DES
Diffie-Hellman
DSA
Elgamal
HMAC-MD5
HMAC-SHA1
HMAC-RIPEMD-160
IDEA
MD2
MD4
MD5
RC2
RC4
RC5
RIPEMD-160
RSA
SHA
Skipjack

DATA TYPES AND CONSTANTS
CRYPT_ALGO_TYPE
CRYPT_ATTRIBUTE_TYPE
CRYPT_CERTFORMAT_TYPE
CRYPT_CERTTYPE_TYPE
CRYPT_DEVICE_TYPE
CRYPT_FORMAT_TYPE
CRYPT_KEYID_TYPE
CRYPT_KEYOPT_TYPE
CRYPT_KEYSET_TYPE
CRYPT_MODE_TYPE
CRYPT_OBJECT_TYPE
CRYPT_SESSION_TYPE
Data Size Constants
Miscellaneous Constants

DATA STRUCTURES
CRYPT_OBJECT_INFO Structure
CRYPT_PKCINFO_xxx Structures
CRYPT_QUERY_INFO Structure

FUNCTION REFERENCE
cryptAddCertExtension
cryptAddPrivateKey
cryptAddPublicKey
cryptAddRandom
cryptAsyncCancel
cryptAsyncQuery

302
302
302
302
302
303
303
303
303
303
303
304
304
304
304
304
304
305
305
305
305

306
306
307
307
308
308
308
309
309
309
310
310
310
311
311

313
313
313
314

315
315
315
315
316
316
316

Introduction

cryptCAAddItem
cryptCACertManagement
cryptCAGetItem
cryptCheckCert
cryptCheckSignature
cryptCheckSignatureEx
cryptCreateCert
cryptCreateContext
cryptCreateEnvelope
cryptCreateSession
cryptCreateSignature
cryptCreateSignatureEx
cryptDecrypt
cryptDeleteAttribute
cryptDeleteCertExtension
cryptDeleteKey
cryptDestroyCert
cryptDestroyContext
cryptDestroyEnvelope
cryptDestroyObject
cryptDestroySession
cryptDeviceClose
cryptDeviceCreateContext
cryptDeviceOpen
cryptDeviceQueryCapability
cryptEncrypt
cryptEnd
cryptExportCert
cryptExportKey
cryptExportKeyEx
cryptFlushData
cryptGenerateKey
cryptGenerateKeyAsync
cryptGetAttribute
cryptGetAttributeString
cryptGetCertExtension
cryptGetPrivateKey
cryptGetPublicKey
cryptImportCert
cryptImportKey
cryptInit
cryptKeysetClose
cryptKeysetOpen
cryptPopData
cryptPushData
cryptQueryCapability
cryptQueryObject
cryptSetAttribute

316
317
317
318
318
318
319
319
319
320
320
320
321
321
322
322
322
323
323
323
323
323
324
324
324
325
325
325
326
326
327
327
328
328
328
329
329
330
330
331
331
331
331
332
332
333
333
333

cryptlib Overview

cryptSetAttributeString
cryptSignCert
cryptUIDisplayCert
cryptUIGenerateKey

334
334
334
335

STANDARDS CONFORMANCE

336

AES
Blowfish
CAST-128
DES
Triple DES
Diffie-Hellman
DSA
Elgamal
HMAC-MD5
HMAC-SHA1
IDEA
MD2
MD4
MD5
RC2
RC4
RC5
RIPEMD-160
RSA
SHA/SHA1
SHA2/SHA-256/SHA-384/SHA-512
Skipjack

336
336
336
336
337
337
337
338
338
338
338
338
338
339
339
339
339
339
340
340
340
340

ACKNOWLEDGEMENTS

341

cryptlib Overview

Introduction
The information age has seen the development of electronic pathways that carry vast
amounts of valuable commercial, scientific, and educational information between
financial institutions, companies, individuals, and government organisations.
Unfortunately the unprecedented levels of access provided by systems like the
Internet also expose this data to breaches of confidentiality, disruption of service, and
outright theft. As a result, there is an enormous (and still growing) demand for the
means to secure these online transactions. One report by the Computer Systems
Policy Project (a consortium of virtually every large US computer company,
including Apple, AT&T, Compaq, Digital, IBM, Silicon Graphics, Sun, and Unisys)
estimated that the potential revenue arising from these security requirements in the
US alone could be as much as US$30-60 billion in the next few years, and the
potential exposure to global users from a lack of this security is projected to reach
between US$320 and 640 billion.
Unfortunately the security systems required to protect data are generally extremely
difficult to design and implement, and even when available tend to require
considerable understanding of the underlying principles in order to be used. This has
l
e
a
dt
oapr
ol
i
f
e
r
a
t
i
ono
f“
s
n
a
k
eoi
l
”pr
od
uc
t
st
ha
tof
f
e
ro
nl
yi
l
l
us
i
ona
r
ys
e
c
ur
i
t
y
,
ort
o
organisations holding back from deploying online information systems because the
me
a
nst
os
e
c
ur
et
he
ma
r
e
n
’
tr
e
a
di
l
ya
v
a
i
l
a
bl
e
,
orb
e
c
a
us
et
he
ye
mpl
oy
e
dwe
a
k
,
e
a
s
i
l
y
broken security that was unacceptable to users.
The cryptlib security toolkit provides the answer to this problem. A complete
description of the capabilities provided by cryptlib is given below.

cryptlib Overview
cryptlib is a powerful security toolkit that allows even inexperienced crypto
programmers to easily add encryption and authentication services to their software.
The high-level interface provides anyone with the ability to add strong security
capabilities to an application in as little as half an hour, without needing to know any
of the low-level details that make the encryption or authentication work. Because of
this, cryptlib dramatically reduces the cost involved in adding security to new or
existing applications.
At the highest level, cryptlib provides implementations of complete security services
such as S/MIME and PGP/OpenPGP secure enveloping, SSL/TLS and SSH secure
sessions, CA services such as CMP, SCEP, RTCS, and OCSP, and other security
operations such as secure timestamping (TSP). Since cryptlib uses industry-standard
X.509, S/MIME, PGP/OpenPGP, and SSH/SSL/TLS data formats, the resulting
encrypted or signed data can be easily transported to other systems and processed
there, and cryptlib itself runs on virtually any operating system — c
r
y
pt
l
i
bdo
e
s
n
’
tt
i
e
you to a single platform. This allows email, files, and EDI transactions to be
authenticated with digital signatures and encrypted in an industry-standard format.
cryptlib provides an extensive range of other capabilities including full X.509/PKIX
certificate handling (all X.509 versions from X.509v1 to X.509v4) with additional
support for SET, Microsoft AuthentiCode, Identrus, SigG, S/MIME, SSL, and
Qualified certificates, PKCS #7 certificate chains, handling of certification requests
and CRLs including automated checking of certificates against CRLs and online
checking using RTCS and OCSP, and issuing and revoking certificates using CMP
and SCEP. In addition cryptlib implements a full range of certification authority
(CA) functions, as well as providing complete CMP, SCEP, RTCS, and OCSP server
implementations to handle online certificate enrolment/issue/revocation and
certificate status checking. Alongside the certificate handling, cryptlib provides a
sophisticated key storage interface that allows the use of a wide range of key database
types ranging from PKCS #11 devices, PKCS #15 key files, and PGP/OpenPGP key
rings through to commercial-g
r
a
deRDBMS’a
ndLDAPdi
r
e
c
t
or
i
e
swi
t
ho
pt
i
o
na
l
SSL protection.

Introduction

In addition to its built-in capabilities, cryptlib can make use of the crypto capabilities
of a variety of external crypto devices such as hardware crypto accelerators, Fortezza
cards, PKCS #11 devices, hardware security modules (HSMs), and crypto smart
cards. For particularly demanding applications cryptlib can be used with a variety of
crypto devices that have received appropriate FIPS 140 or ITSEC/Common Criteria
certification. The crypto device interface also provides a convenient general-purpose
plug-in capability for adding new functionality that will be automatically used by
cryptlib.
cryptlib is supplied as source code for AMX, BeOS, ChorusOS, DOS, DOS32, eCOS,
µC/OS-II, embedded Linux, IBM MVS, µITRON, Macintosh/OS X, OS/2, PalmOS,
RTEMS, Tandem, a variety of Unix versions (including AIX, Digital Unix, DGUX,
FreeBSD/NetBSD/OpenBSD, HP-UX, IRIX, Linux, MP-RAS, OSF/1, QNX,
SCO/UnixWare, Solaris, SunOS, Ultrix, and UTS4), uClinux, VM/CMS, VxWorks,
Windows 3.x, Windows 95/98/ME, Windows CE/PocketPC/SmartPhone, Windows
NT/
20
00/
XP,
a
n
dXi
l
i
nxXMK.c
r
y
pt
l
i
b
’
sh
i
g
hl
yportable nature means that it is also
being used in a variety of custom embedded system environments. In addition,
cryptlib is available as a standard Windows DLL and an ActiveX control.. cryptlib
comes with language bindings for C / C++, C# / .NET, Delphi, Java, Python, and
Visual Basic (VB).

cryptlib features
cryptlib provides a standardised interface to a number of popular encryption
algorithms, as well as providing a high-level interface that hides most of the
implementation details and uses operating-system-independent encoding methods that
make it easy to transfer secured data from one operating environment to another.
Although use of the high-level interface is recommended, experienced programmers
can directly access the lower-level encryption routines for implementing custom
encryption protocols or methods not directly provided by cryptlib.

Architecture
cryptlib consists of a set of layered security services and associated programming
interfaces that provide an integrated set of information and communications security
capabilities. Much like the network reference model, cryptlib contains a series of
layers that provide each level of abstraction, with higher layers building on the
capabilities provided by the lower layers.
At the lowest level are basic components such as core encryption and authentication
routines, which are usually implemented in software but may also be implemented in
hardware (due to the speed of the software components used in cryptlib, the software
is usually faster than dedicated hardware). At the next level are components that
wrap up the specialised and often quite complex core components in a layer that
provides abstract functionality and ensures complete cross-platform portability of
data. These functions typically cover a
r
e
a
ss
uc
ha
s“
c
r
e
a
t
eadi
g
i
t
a
ls
i
g
na
t
ur
e
”or
“
e
x
c
ha
ng
ea
ne
nc
r
y
pt
i
onk
e
y
”
.Att
hehi
g
he
s
tl
e
v
e
la
r
ee
x
t
r
e
me
l
ypowe
r
f
ula
n
de
a
s
y
to-us
ef
u
nc
t
i
o
nss
uc
ha
s“
e
n
c
r
y
ptame
s
s
a
g
e
”
,
“
s
i
g
name
s
s
a
g
e
”
,
“
ope
nas
e
c
ur
el
i
nk
”
,
a
nd“
c
r
e
a
t
eadi
g
i
t
a
lc
e
r
t
i
f
i
c
a
t
e
”t
ha
trequire no knowledge of encryption techniques,
and that take care of complex issues such as key management, data encoding,
en/decryption, and digital signature processing.

cryptlib features

High-level interface
Secure data
enveloping

Secure communications
sessions

Certificate
management

Security services interface
Key
exchange

Digital
signature

Key
generation

Encryption services interface

Native
encryption
services

Adaptation
layer

Third-party
encryption
services

Key management

Key store interface

Native
database
services

Adaptation
layer
Third-party
database
services

c
r
y
pt
l
i
b’
sp
owe
r
f
ulo
bj
e
c
tma
na
g
e
me
n
ti
n
t
e
r
f
a
c
epr
ov
i
de
s the ability to add
encryption and authentication capabilities to an application without needing to know
all the low-level details that make the encryption or authentication work. The
automatic object-management routines take care of encoding issues and crosspl
a
t
f
or
mpor
t
a
bi
l
i
t
ypr
o
bl
e
ms
,
s
ot
ha
tah
a
n
df
uloff
u
nc
t
i
o
nc
a
l
l
si
sa
l
lt
h
a
t
’
sne
e
de
dt
o
wrap up data in signed or encrypted form with all of the associated information and
parameters needed to recreate it on the other side of a communications channel. This
provides a considerable advantage over other encryption toolkits that often require
hundreds of lines of code and the manipulation of complex encryption data structures
to perform the same task.

S/MIME
cryptlib employs the IETF-standardised Cryptographic Message Syntax (CMS,
formerly called PKCS #7) format as its native data format. CMS is the underlying
format used in the S/MIME secure mail standard, as well as a number of other
standards covering secure EDI and related systems like HL7 medical messaging and
the Session Initiation Protocol (SIP) for services such as Internet telephony and
instant messaging. As an example of its use in secure EDI, cryptlib provides security
services for the Symphonia EDI messaging toolkit which is used to communicate
medical lab reports, patient data, drug prescription information, and similar
information requiring a high level of security.
TheS/
MI
MEi
mpl
e
me
n
t
a
t
i
o
nus
e
sc
r
y
pt
l
i
b’
se
nv
e
l
opi
ngi
nt
e
r
f
a
c
ewhi
c
ha
l
l
ows
simple, rapid integration of strong encryption and authentication capabilities into
existing email agents and messaging software. The resulting signed enveloped data
format provides message integrity and origin authentication services, the encrypted
enveloped data format provides confidentiality. In addi
t
i
o
nc
r
y
pt
l
i
b
’
sS/
MI
ME
implementation allows external services such as trusted timestamping authorities
(TSAs) to be used when a signed message is created, providing externally-certified
proof of the time of message creation. The complexity of the S/MIME format means
that the few other toolkits that are available require a high level of programmer
k
nowl
e
dg
eofS/
MI
MEpr
oc
e
s
s
i
ngi
s
s
ue
s
.
I
nc
ont
r
a
s
tc
r
y
pt
l
i
b
’
se
nv
e
l
op
i
ngi
nt
e
r
f
a
c
e
makes the process as simple as pushing raw data into an envelope and popping the
processed data back out, a total of three function calls, plus one more call to add the
appropriate encryption or signature key.

PGP/OpenPGP
Alongside the PKCS #7/CMS/SMIME formats, cryptlib supports the PGP/OpenPGP
message format, allowing it to be used to send and receive PGP-encrypted email and

Introduction
da
t
a
.Aswi
t
ht
h
eS/
MI
MEi
mp
l
e
me
nt
a
t
i
on,
t
hePGPi
mp
l
e
me
nt
a
t
i
onus
e
sc
r
y
pt
l
i
b
’
s
enveloping interface to allow simple, rapid integration of strong encryption and
authentication capabilities into existing email agents and messaging software. Since
the enveloping interface is universal, the process involved in creating PGP and
S/MIME messages is identical except for the envelope format specifier, allowing a
one-off development effort to handle any secure message format.

Secure Sessions
cryptlib secure sessions can include SSH, SSL, and TLS sessions, and general
communications sessions can include protocols such as the certificate management
protocol (CMP), simple certificate enrolment protocol (SCEP), real-time certificate
status protocol (RTCS), online certificate status protocol (OCSP), and timestamping
(TSP). As with envelopes, cryptlib takes care of the session details for you so that all
you need to do is provide basic communications information such as the name of the
server or host to connect to and any other information required for the session such as
a password or certificate. cryptlib takes care of establishing the session and
managing the details of the communications channel and its security parameters.
cryptlib provides both client and server implementations of all session types. By
tying a key or certificate store to the session, you can let cryptlib take care of any key
management issues for you. For example, with an SSH, SSL or TLS server session
cryptlib will use the key/certificate store to authenticate incoming connections, and
with a CMP or SCEP server session cryptlib will use the certificate store to handle the
certificate management process. In this way a complete CMP-based CA that handles
enrolment, certificate update and renewal, and certificate revocation, can be
implemented with only a handful of function calls.

Plug-and-play PKI
Working with certificates can be complex and painful, requiring the use of a number
of arcane and difficult-to-use mechanisms to perform even the simplest operations.
To eliminate this problem, cryptlib provides a plug-and-play PKI interface that
manages all certificate processing and management operations for you, requiring no
special knowledge of certificate formats, protocols, or operations. Using the plugand-play PKI interface with an appropriately-configured CA means that cryptlib will
automatically and transparently handle key generation, certificate enrolment, securely
obtaining trusted CA certificates, and certifying the newly-generated keys for the
user, all in a single operation. Similarly, certificate validity checking can be
performed using an online real-time status check that avoids the complexity and
delayed status information provided by mechanisms such as CRLs. The plug-andplay PKI interface removes most of the complexity and difficulty involved in
working with certificates, making it easier to use certificates than with any of the
conventional certificate management mechanisms.

Certificate Management
cryptlib implements full X.509 certificate support, including all X.509 version 3 and
X.509 version 4 extensions as well as extensions defined in the IETF PKIX certificate
profile. cryptlib also supports additional certificate types and extensions including
SET certificates, Microsoft AuthentiCode and Netscape and Microsoft server-gated
crypto certificates, Identrus certificates, qualified certificates, S/MIME and SSL
client and server certificates, SigG extensions, and various vendor-specific extensions
such as Netscape certificate types and the Thawte secure extranet.
In addition to certificate handling, cryptlib allows the generation of certification
requests suitable for submission to certification authorities (CAs) in order to obtain a
certificate. Since cryptlib is itself capable of processing certification requests into
certificates, it is also possible to use cryptlib to provide full CA services. cryptlib
also supports the creating and handling of the certificate chains required for S/MIME,
SSL, and other applications, and the creation of certificate revocation lists (CRLs)
with the capability to check certificates against existing or new CRLs either
automatically or under programmer control. In addition to CRL-based revocation

cryptlib features

checking, cryptlib also supports online status protocols such as RTCS and OCSP.
cryptlib also implements the CMP protocol which fully automates the management of
certificates, allowing online certificate enrolment, issue, update/replacement, and
revocation of certificates, and the SCEP protocol, which automates the certificate
issue process. Using CMP removes from the user any need for technical knowledge
of certificate management, since all details are managed by the CA.
cryptlib can import and export certification requests, certificates, certificate chains,
and CRLs, covering the majority of certificate transport formats used by a wide
variety of software such as web browsers and servers. The certificate types that are
supported include:

 Basic X.509 version 1 and 2 certificates

 Extended X.509 version 3 and 4 certificates

 Certificates conformant to the IETF PKIX profile

 SSL/TLS server and client certificates

 S/MIME email certificates

 SET certificates

 SigG certificate extensions

 AuthentiCode code signing certificates

 Identrus certificates

 Qualified certificates

 IPsec server, client, end-user, and tunnelling certificates

 Server-gated crypto certificates

 Timestamping certificates
In addition cryptlib supports X.509v3, X.509v4, IETF, S/MIME, SET, and SigG
certificate extensions and many vendor-specific extensions including ones covering
public and private key usage, certificate policies, path and name constraints, policy
constraints and mappings, and alternative names and other identifiers. This
comprehensive coverage makes cryptlib a single solution for almost all certificate
processing requirements.
The diagram below shows a typical cryptlib application, in which it provides the full
functionality of both a CA (processing certification requests, storing the issued
certificates locally in a certificate database, and optionally publishing the certificates
on the web or in an LDAP directory) and an end entity (generating certification
requests, submitting them to a CA, and retrieving the result from the web or a
directory service).

Introduction

CA
repository
Web
server

cryptlib CA
Cert request/
retrieve

SSL
server

LDAP
directory

Publish

User
Retrieve
Local
certificate
repository
To handle certificate trust and revocation issues, cryptlib includes a certificate trust
manager that can be used to automatically manage CA trust settings. For example a
CA can be designated as a trusted issuer that will allow cryptlib to automatically
evaluate trust along certificate chains. Similarly, cryptlib can automatically check
certificates against RTCS and OCSP responders and CRLs published by CAs,
removing from the user the need to perform complex manual checking.

CA Operations
cryptlib includes a scalable, flexible Certificate Authority (CA) engine built on the
transaction-processing capabilities of a number of proven, industrial-strength
relational databases running on a variety of hardware platforms. The CA facility
provides an automated means of handling certificate issuance without dealing directly
with the details of processing request, signing certificates, saving the resulting
certificates in keys stores, and assembling CRLs. This constitutes a complete CA
system for issuance and management of certificates and CRLs. A typical cryptlib CA
configuration is shown below.

cryptlib features

Smart
card
Certificate
client

Status
client

CMP/SCEP/
PKCS #10

RTCS/
OCSP

cryptlib CA

LDAP

HSM

Certificate
store

Certificates/CRLs
Available CA operations include:

 Certificate enrolment/initialisation operations

 Certificate issue

 Certificate update/key update

 Certificate expiry management

 Revocation request processing

 CRL issue
Al
lCAope
r
a
t
i
o
nsa
r
er
e
c
or
d
e
dt
oa
ne
v
e
n
tl
ogus
i
ngc
r
y
pt
l
i
b
’
sb
ui
l
t
-in CA
logging/auditing facility, which provides a full account of certificate requests,
certificates issued or renewed, revocations requested and issued, certificates expired,
and general CA management operations. The logs may be queried for information on
all events or a specified subset of events, for example all certificates that were issued
on a certain day.
cryptlib contains a full implementation of a CMP server (to handle online certificate
management), and SCEP server (to handle online certificate issue), a RTCS server (to
handle real-time certificate status checking), and an OCSP server (to handle
revocation checking). All of these servers are fully automated, requiring little user
intervention beyond the initial enrolment process in which user eligibility for a
certificate is established. These services make it easier than ever to manage your own
CA. Certificate expiration and revocation are handled automatically by the CA
engine. Expired certificates are removed from the certificate store, and CRLs are
assembled from previously processed certificate revocation requests. These
operations are handled with a single function call.
The CA keys can optionally be generated and held in tamper-resistant hardware
security modules, with certificate signing being performed by the hardware module.
Issued certificates can be stored on smart cards or similar crypto devices in addition
to being managed using software-only implementations. The CA facility supports the
simultaneous operation of multiple CAs, for example to manage users served through

Introduction

divisional CAs certified by a root CA. Each CA can issue multiple certificates to
users, allowing the use of separate keys bound to signature and encryption
certificates.

Crypto Devices and Smart Card Support
In addition to its built-in capabilities, cryptlib can make use of the crypto capabilities
of a variety of external crypto devices such as:

 Hardware crypto accelerators

 Fortezza cards

 PKCS #11 devices

 Crypto smart cards

 Hardware security modules (HSMs)

 PCI crypto cards

 Dallas iButtons

 Datakeys/iKeys

 PCMCIA crypto tokens

 USB tokens
These devices will be used by cryptlib to handle functions such as key generation and
storage, certificate creation, digital signatures, and message en- and decryption.
Typical applications include:

 Running a certification authority inside tamper-resistant hardware

 Smart-card based digital signatures

 Message encryption/decryption in secure hardware
cryptlib manages any device-specific interfacing requirements so that the
pr
og
r
a
mmi
ngi
nt
e
r
f
a
c
ef
ora
n
yc
r
y
pt
ode
v
i
c
ei
si
de
nt
i
c
a
lt
oc
r
y
pt
l
i
b
’
sn
a
t
i
v
ei
nt
e
r
f
a
c
e
,
allowing existing applications that use cryptlib to be easily and transparently migrated
to using crypto devices. The ability to mix and match crypto devices and the
software-only implementation allows appropriate tradeoffs to be chosen between
flexibility, cost, and security.

Certificate Store Interface
cryptlib utilizes commercial-s
t
r
e
ng
t
hRDBMS’t
os
t
or
ek
e
y
si
nt
hei
nt
e
r
na
t
i
o
na
l
l
y
standardised X.509 format. The certificate store integrates seamlessly into existing
databases and can be managed using existing tools. For example a key database
stored on an MS SQL Server might be managed using Visual Basic or MS Access; a
key database stored on an Oracle server might be managed through SQL*Plus.
In addition to standard certificate stores, cryptlib supports the storage and retrieval of
certificates in LDAP directories, HTTP access for keys accessible via the web, and
external flat-file key collections such as PKCS #15 soft-tokens and PGP/OpenPGP
key rings. The key collections may be freely mixed (so for example a private key
could be stored in a PKCS #15 soft-token, a PGP/OpenPGP key ring or on a smart
card with the corresponding X.509 certificate being stored in a certificate store, an
LDAP directory, or on the web).
Private keys may be stored on disk encrypted with an algorithm such as triple DES or
AES (selectable by the user), with the password processed using several thousand
iterations of a hashing algorithm such as SHA-1 (also selectable by the user). Where
the operating system supports it, cryptlib will apply system security features such as
ACLs under Windows NT/2000/XP and file permissions under Unix to the private
key file to further restrict access.

cryptlib features

User Interface
In addition to its general security functionality, cryptlib includes a number of user
interface components that simplify the task of working with keys and certificates.
Components such as the certificate viewer shown below allow users to browse the
contents of certificates, certificate chains, requests, and other certificate objects. The
key generation wizard simplifies the task of key and certificate generation by
handling most of the details of the process automatically, producing a complete
public/private key pair and certificate request suitable for submission to a CA, or a
self-signed certificate for immediate use. These user interface components remove
much of the complexity of the key and certificate management process, allowing
developers to concentrate on applying the completed keys and certificates towards
securing data, email, or communications sessions rather than on the process needed to
create them.

Security Features
cryptlib is built around a security kernel with Orange Book B3-level security features
to implement its security mechanisms. This kernel provides the interface between the
out
s
i
dewor
l
da
n
dt
hea
r
c
h
i
t
e
c
t
ur
e
’
sob
j
e
c
t
s(
i
nt
r
a
-object security) and between the
objects themselves (inter-object security). The security kernel is the basis of the
entire cryptlib architecture — all objects are accessed and controlled through it, and
all object attributes are manipulated through it. The kernel is implemented as an
interface layer that sits on top of the objects, monitoring all accesses and handling all
protection functions.
Each cryptlib object is contained entirely within the security perimeter, so that data
and control information can only flow in and out in a very tightly-controlled manner,
and objects are isolated from each other within the perimeter by the security kernel.
For example once keying information has been sent to an obj
e
c
t
,
i
tc
a
n
’
tber
e
t
r
i
e
v
e
d

Introduction

by the user except under tightly-controlled conditions. In general keying information
i
s
n’
te
v
e
nv
i
s
i
bl
et
ot
heus
e
r
,
s
i
nc
ei
t
’
sg
e
ne
r
a
t
e
di
ns
i
d
et
h
eobj
e
c
ti
t
s
e
l
fa
n
dne
v
e
r
leaves the security perimeter. This design is ideally matched to hardware
implementations that perform strict red/black separation, since sensitive information
can never leave the hardware.
Associated with each object is a set of mandatory ACLs that determine who can
access a particular object and under which conditions the access is allowed. If the
operating system supports it, all sensitive information used will be page-locked to
e
ns
ur
et
ha
ti
t
’
sne
v
e
rs
wa
ppe
dt
od
i
s
kf
r
o
m whe
r
ei
tc
ou
l
dber
e
c
ov
e
r
e
dus
i
ngadi
s
k
editor. All memory corresponding to security-related data is managed by cryptlib and
will be automatically sanitised and freed when cryptlib shuts down even if the calling
program forgets to release the memory itself.
Where the operating system supports it, cryptlib will apply operating system security
features to any objects that it creates or manages. For example under Windows
NT/2000/XP cryptlib private key files will be created with an access control list
(ACL) that allows only the key owner access to the file; under Unix the file
permissions will be set to achieve the same result.

Embedded Systems
c
r
y
pt
l
i
b’
sh
i
g
hl
e
v
e
lofpor
t
a
b
i
l
i
t
ya
ndc
on
f
i
g
ur
a
bi
l
i
t
yma
k
e
si
ti
de
a
lf
orus
ei
n
embedded systems with limited resources or specialised requirements, including ones
based on ARM7, ARM9, ARM TDMI, Fujitsu FR-V, Hitachi SuperH, MIPS IV,
MIPS V, Motorola ColdFire, NEC V8xx series, NEC VRxxxx series,
Pa
n
a
s
o
ni
c
/
Ma
‌
t
s
us
hi
t
aAM33
/
AM34,
Powe
r
PC,
Sa
ms
u
ngCa
l
mRI
SC,
SH3,
SH4,
SPARC, SPARClite, StrongArm, TI OMAP, and Intel XScale processors. cryptlib
doe
s
n’
t perform any floating-point operations and runs directly on processors without
an FPU.
The code is fully independent of any underlying storage or I/O mechanisms, and
works just as easily with abstractions such as named memory segments in flash
memory as it does with standard key files on disk. It has been deployed on embedded
systems without any conventional I/O capabilities (stdio) or dynamic memory
allocation facilities, with proprietary operating system architectures and services
including ATMs, printers, web-enabled devices, POS systems, embedded device
controllers, and similar environments, and even in devices with no operating system
at all (cryptlib runs on the bare metal). It can also run independent of any form of
operating system, and has been run on the bare metal in environments with minimal
available resources, in effect functioning as a complete crypto operating system for
the underlying hardware.
Be
c
a
us
ec
r
y
pt
l
i
bf
u
nc
t
i
o
nsi
d
e
nt
i
c
a
l
l
ya
c
r
os
sa
l
ls
up
por
t
e
de
nv
i
r
on
me
nt
s
,
i
t
’
sp
os
s
i
bl
e
to perform application development in a full-featured development environment such
as Windows or Unix and only when the application is complete and tested move it to
the embedded system. This flexibility saves countless hours of development time,
greatly reducing the amount of time that needs to be spent with embedded systems
debuggers or in-circuit emulators since most of the development and code testing can
be done on the host system of choice.
If required the cryptlib developers can provide assistance in moving the code to any
new or unusual environments.

Performance
cryptlib is re-entrant and completely thread-safe, allowing it to be used with
multithreaded applications under BeOS, OS/2, Windows 95/98/ME, Windows
NT/2000/XP, Windows CE, and Unix systems that support threads. Because it is
thread-safe, lengthy cryptlib operations can be run in the background if required
while other processing is performed in the foreground. In addition cryptlib itself is
multithreaded so that computationally intensive internal operations take place in the
background without impacting the performance of the calling application.

cryptlib features

Most of the core algorithms used in cryptlib have been implemented in assembly
language in order to provide the maximum possible performance, and will take
advantage of crypto hardware acceleration facilities present in some CPUs such as the
Via C3 family. These routines provide an unprecedented level of performance, in
most cases running faster than expensive, specialised encryption hardware designed
to perform the same task. This means that cryptlib can be used for high-bandwidth
applications such as video/audio encryption and online network and disk encryption
without the need to resort to expensive, specialised encryption hardware.

Cryptographic Random Number Management
cryptlib contains an internal secure random data management system that provides
the cryptographically strong random data used to generate session keys and
public/private keys, in public-key encryption operations, and in various other areas
that require secure random data. The random data pool is updated with unpredictable
process-specific information as well as system-wide data such as current disk I/O and
paging statistics, network, assorted client/server network protocol traffic, packet filter
statistics, multiprocessor statistics, process information, users, VM statistics, process
statistics, battery/power usage statistics, system thermal management data, open files,
inodes, terminals, vector processors, streams, and loaded code, objects in the global
heap, loaded modules, running threads, process, and tasks, and an equally large
number of system performance-related statistics covering virtually every aspect of the
operation of the system.
The exact data collected depends on the hardware and operating system, but generally
includes extremely detailed and constantly changing operating statistics and
information. In addition if a /dev/random, EGD, or PRNGD-style style
randomness driver (which continually accumulates random data from the system) is
available, cryptlib will use this as a source of randomness. Finally, cryptlib supports
a number of cryptographically strong hardware random number generators, either
built into the CPU or system chipset or available as external crypto devices, that can
be used to supplement the internal generator. As a post-processing stage, cryptlib
employs an ANSI X9.17/X9.31 generator for additional security and for FIPS 140
compliance. This level of secure random number management ensures that security
prob
l
e
mss
uc
ha
st
h
os
epr
e
s
e
nti
nNe
t
s
c
a
pe
’
swe
bbr
ows
e
r(
whi
c
ha
l
l
owe
de
nc
r
y
pt
i
o
n
k
e
y
st
obepr
e
di
c
t
e
dwi
t
ho
utbr
e
a
k
i
ngt
hee
nc
r
y
pt
i
o
nbe
c
a
us
et
h
e“
r
a
n
do
m”d
a
t
a
wa
s
n’
ta
ta
l
lr
a
nd
o
m)c
a
n
’
toc
c
urwi
t
hc
r
y
pt
l
i
b.

Programming Interface
The application programming interface (API) serves as an interface to a range of
plug-in encryption modules that allow encryption algorithms to be added in a fairly
transparent manner, so that adding a new algorithm or replacing an existing software
implementation with custom encryption hardware can be done without any trouble.
The standardised API allows any of the algorithms and modes supported by cryptlib
to be used with a minimum of coding effort. In addition the easy-to-use high-level
routines allow for the exchange of encrypted or signed messages or the establishment
of secure communications channels with a minimum of programming overhead.
Language bindings are available for C / C++, C# / .NET, Delphi, Java, Python, Tcl,
and Visual Basic (VB).
cryptlib has been written to be as foolproof as possible. On initialisation it performs
extensive self-testing against test data from encryption standards documents, and the
APIs check each parameter and function call for errors before any actions are
performed, with error reporting down to the level of individual parameters. In
addition logical errors such as, for example, a key exchange function being called in
the wrong sequence, are checked for and identified.

Documentation
cryptlib comes with extensive documentation in the form of a 310-page user manual
and a 320-page technical reference manual. The user manual is intended for
everyday cryptlib use and contains detailed documentation on every aspect of

Introduction
c
r
y
pt
l
i
b’
sf
u
nc
t
i
o
na
l
i
t
y
.I
nmos
tc
a
s
e
st
hec
odene
e
de
dt
os
e
c
ur
ea
na
p
pl
i
c
a
t
ion can
be cut and pasted directly from the appropriate section of the manual, avoiding the
need to learn yet another programming API. The user manual concludes with a
reference section covering the various cryptlib API functions, constants, and data
types.
The technical reference manual covers the design and internals of cryptlib itself,
including the cryptlib security model and security mechanisms that protect every part
ofc
r
y
pt
l
i
b’
so
pe
r
a
t
i
o
n.I
na
d
di
t
i
o
nt
h
et
e
c
hn
i
c
a
lma
nu
a
lpr
ov
i
de
sawe
a
l
t
hof
background information to help users understand the security foundations on which
cryptlib is built.

Algorithm Support
Included as core cryptlib components are implementations of the most popular
encryption and authentication algorithms, AES, Blowfish, CAST, DES, triple DES,
IDEA, RC2, RC4, RC5, and Skipjack, conventional encryption, MD2, MD4, MD5,
RIPEMD-160, SHA-1, and SHA-2 hash algorithms, HMAC-MD5, HMAC-SHA, and
HMAC-RIPEMD-160 algorithms, and Diffie-Hellman, DSA, Elgamal, and RSA
public-key encryption, with elliptic-curve encryption under development. The
algorithm parameters are summarised below:
Algorithm
AES
Blowfish
CAST-128
DES
Triple DES
IDEA
RC2
RC4
RC5
Skipjack
MD2
MD4
MD5
RIPEMD-160
SHA-1
SHA-2 / SHA-256
HMAC-MD5
HMAC-SHA
HMAC-RIPEMD-160
Diffie-Hellman
DSA
Elgamal
RSA

Key size
128/192/256
448
128
56
112 / 168
128
1024
2048
832
80
—
—
—
—
—
—
128
160
160
4096
40961
4096
4096

Block size
128
64
64
64
64
64
64
8
64
64
128
128
128
160
160
256
128
160
160
—
—
—
—

Standards Compliance
All algorithms, security methods, and data encoding systems in cryptlib either comply
with one or more national and international banking and security standards, or are
implemented and tested to conform to a reference implementation of a particular
algorithm or security system. Compliance with national and international security
standards is automatically provided when cryptlib is integrated into an application.
These standards include ANSI X3.92, ANSI X3.106, ANSI X9.9, ANSI X9.17, ANSI
X9.30-1, ANSI X9.30-2, ANSI X9.31-1, ANSI X9.42, ANSI X9.52, ETSI TS 101
733, ETSI TS 101 861, ETSI TS 101 862, ETSI TS 102, FIPS PUB 46-2, FIPS PUB
46-3, FIPS PUB 74, FIPS PUB 81, FIPS PUB 113, FIPS PUB 180, FIPS PUB 180-1,
FIPS PUB 186, FIPS PUB 198, ISO/IEC 8372, ISO/IEC 8731 ISO/IEC 8732,
1

The DSA standard only defines key sizes from 512 to 1024 bits, cryptlib supports longer keys but there is no
extra security to be gained from using these keys.

cryptlib features

ISO/IEC 8824/ITU-T X.680, ISO/IEC 8825/ITU-T X.690, ISO/IEC 9797, ISO/IEC
10116, ISO/IEC 10118, ITU-T X.842, ITU-T X.843, PKCS #1, PKCS #3, PKCS #5,
PKCS #7, PKCS #9, PKCS #10, PKCS #11, PKCS #15, RFC 1319, RFC 1320, RFC
1321, RFC 1750, RFC 1991, RFC 2040, RFC 2104, RFC 2144, RFC 2202, RFC
2246, RFC 2268, RFC 2311 (cryptography-related portions), RFC 2312, RFC 2313,
RFC 2314, RFC 2315, RFC 2437, RFC 2440, RFC 2459, RFC 2510, RFC 2511, RFC
2528, RFC 2560, RFC 2585, RFC 2630, RFC 2631, RFC 2632, RFC 2633
(cryptography-related portions), RFC 2634, RFC 2785, RFC 2876, RFC 2898, RFC
2984, RFC 2985, RFC 2986, RFC 3039, RFC 3058, RFC 3114, RFC 3126, RFC
3161, RFC 3174, RFC 3183, RFC 3211, RFC 3218, RFC 3261 (cryptography-related
portions), RFC 3268, RFC 3274, RFC 3279, RFC 3280, RFC 3281, RFC 3369, RFC
3370, RFC 3447, RFC 3546, and RFC 3565. Because of the use of internationally
recognised and standardised security algorithms, cryptlib users will avoid the
problems caused by home-grown, proprietary algorithms and security techniques that
often fail to provide any protection against attackers, resulting in embarrassing bad
publicity and expensive product recalls.

Y2K Compliance
cryptlib handles all date information using the ANSI/ISO C time format, which does
not suffer from Y2K problems. Although earlier versions of the X.509 certificate
format do have Y2K problems, cryptlib transparently converts the dates encoded in
certificates to and from the ANSI/ISO format, so cryptlib users will never see this.
c
r
y
pt
l
i
b’
sownt
i
me
/
da
t
ef
or
ma
ti
sno
ta
f
f
e
c
t
e
dbya
nyY2Kpr
ob
l
e
ms
,
a
ndc
r
y
p
t
l
i
b
i
t
s
e
l
fc
on
f
or
mst
ot
her
e
qui
r
e
me
nt
si
nt
h
eBr
i
t
i
s
hSt
a
n
da
r
d
sI
ns
t
i
t
u
t
i
on
’
sDI
SC
PD2000-1:1998 Y2K compliance standard.

Configuration Options
cryptlib works with a configuration database that can be used to tune its operation for
different environments. This allows a system administrator to set a consistent
security policy which is then automatically applied by cryptlib to operations such as
key generation and data encryption and signing, although they can be overridden on a
per-application or per-user basis if required.

cryptlib Applications
The security services provided by cryptlib can be used in virtually any situation that
requires the protection or authentication of sensitive data. Some areas in which
cryptlib is currently used include:

 Protection of medical records transmitted over electronic links.

 Protection of financial information transmitted between branches of banks.

 Transparent disk encryption.

 Strong security services added to web browsers with weak, exportable
security.

 Running a CA.

 Encrypted electronic mail.

 File encryption.

 Protecting content on Internet servers.

 Digitally signed electronic forms.

 S/MIME mail gateway.

 Secure database access.

 Protection of credit card information.

Introduction

Encryption Code Example
The best way to illustrate what cryptlib can do is with an example. The following
code encrypts a message using public-key encryption.
/* Create an envelope for the message */
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_SMIME );
/* Push in the message recipient's name */
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_RECIPIENT,
recipientName, recipientNameLength );
/* Push in the message data and pop out the signed and encrypted
result */
cryptPushData( cryptEnvelope, message, messageSize, &bytesIn );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, encryptedMessage, encryptedSize,
&bytesOut );
/* Clean up */
cryptDestroyEnvelope( cryptEnvelope );

This performs the same task as a program like PGP using just 6 function calls (to
create a PGP/OpenPGP message, just change the CRYPT_FORMAT_SMIME to
CRYPT_FORMAT_PGP). All data management is handled automatically by
c
r
y
pt
l
i
b,
s
ot
he
r
e
’
sn
one
e
dt
owor
r
ya
boute
nc
r
y
p
t
i
on modes and algorithms and key
lengths and key types and initialisation vectors and other details (although cryptlib
provides the ability to specify all this if you feel the need).
The code shown above results in cryptlib performing the following actions:

 Generate a random session key for the default encryption algorithm (usually
triple DES or AES).

 Lookupt
her
e
c
i
pi
e
n
t
’
spu
bl
i
ck
e
yi
nak
e
yda
t
a
ba
s
e
.

 Enc
r
y
ptt
hes
e
s
s
i
onk
e
yus
i
ngt
her
e
c
i
pi
e
nt
’
sp
ub
l
i
ck
e
y
.

 Encrypt the signed data with the session key.

 Pass the result back to the user.
However unless you want to call cryptlib using the low-level interface, you never
need to know about any of this. cryptlib will automatically know what to do with the
data based on the resources you add to the envelope — if you add a signature key it
will sign the data, if you add an encryption key it will encrypt the data, and so on.

Secure Session Code Example
Establishing a secure session using SSL/TLS is similarly easy:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_SSL );
/* Add the server name and activate the session */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
serverName, serverNameLength );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

If you prefer SSH to SSL, just change the CRYPT_SESSION_SSL to CRYPT_SESSION_SSH and add a user name and password to log on. As with the encryption
code example above, cryptlib provides a single unified interface to its secure session
me
c
ha
ni
s
ms
,
s
oy
oud
on
’
tha
v
et
oi
nv
e
s
tal
oto
fe
f
f
or
ti
na
ddi
ngs
pe
c
i
a
l
-case
handling for different security protocols and mechanisms.
The corresponding SSL/TLS (or SSH if you prefer) server is:

Document conventions

CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_SSL_SERVER
);
/* Add the server key/certificate and activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_PRIVATEKEY, privateKey
);
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

As with the secure enveloping example, cryptlib is performing a large amount of
wor
ki
nt
heba
c
k
g
r
ound,
b
uta
g
a
i
nt
he
r
e
’
sn
one
e
dt
ok
nowa
bo
utt
hi
ss
i
nc
ei
t
’
sa
l
l
taken care of automatically.

Certificate Management Code Example
The foll
owi
ngc
odei
l
l
us
t
r
a
t
e
sc
r
y
pt
l
i
b
’
sp
l
ug
-and-play PKI interface:
CRYPT_SESSION cryptSession;
/* Create the CMP session and add the server name/address */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_CMP );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER, server,
serverLength );
/* Add the username, password, and smart card */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
userName, userNameLength );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_PASSWORD,
password, passwordLength );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_CMP_PRIVKEYSET,
cryptDevice );
/* Activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, TRUE );

This code takes a smart card and generates separate encryption and signing keys in it,
requests a signature certificate from the CA for the signing key, uses that to obtain a
certificate for the encryption key, obtains any further certificates that may be needed
from the CA (for example for S/MIME signing or SSL server operation), and stores
everything in the smart card. Compare this to the hundreds or even thousands of lines
of code required to do the same thing using other toolkits.
Oh yes, and cryptlib provides the CA-side functionality as well — t
he
r
e
’
sn
oneed to
pay an expensive commercial CA for your certificates, since cryptlib can perform the
same function.

Document conventions
This manual uses the following document conventions:
Example

Description

cryptlib.h

This font is used for filenames.

cryptCreateContext

Bold type indicates cryptlib function names.

Value

Words or portions of words in italics indicate
placeholders for information that you need to
supply.

if( i == 0 )

This font is used for sample code and operating
system commands.

Recommended Reading
One of the best books to help you understand how to use cryptlib is Network Security
by Charlie Kaufman, Radia Perlman, and Mike Speciner, which covers general
security principles, encryption techniques, and a number of potential cryptlib
applications such as X.400/X.500 security, PEM/S/MIME/PGP, Kerberos, and
various other security, authentication, and encryption techniques. The book also

Introduction

contains a wealth of practical advice for anyone considering implementing a
cryptographic security system. Security Engineering: A Guide to Building
Dependable Distributed Systems by Ross Anderson also contains a large amount of
useful information and advice on engineering secure systems. Building Secure
Software by John Viega and Gary McGraw and Writing Secure Software by Michael
Howard and David LeBlanc contain a wealth of information on safe programming
techniques and related security issues.
Cryptographic Security Architecture Design and Verification by Peter Gutmann is the
technical documentation for cryptlib and complements the cryptlib user manual. It
contains full details of the architectural and security features of cryptlib, as well as a
wealth of background material to help you understand the security foundations on
which cryptlib is built.
A tutorial in 8 parts totalling over 700 slides and covering all aspects of encryption
and general network security, including encryption and security basics, algorithms,
key management and certificates, CAs, certificate profiles and policies, PEM, PGP,
S/MIME, SSL, SSH, SET, smart cards, and a wide variety of related topics, is
available from http://www.cs.auckland.ac.nz/~pgut001/tutorial/. If
you want to do anything with certificates, you should definitely read Everything you
Never Wanted to Know about PKI but were Forced to Find Out, available from
http://www.cs.auckland.ac.nz/~pgut001/pubs/pkitutorial.pdf,
t
of
i
n
dou
twha
ty
ou
’
r
ei
nf
ori
fy
o
uha
v
et
owor
kwi
t
h
certificates.
In addition to this, there are a number of excellent books available that will help you
in understanding the cryptography used in cryptlib. The foremost of these are
Applied Cryptography by Bruce Schneier and the Handbook of Applied Cryptography
by Alfred Menezes, Paul van Oorschot, and Scott Vanstone. Applied Cryptography
provides an easy-to-read overview while the Handbook of Applied Cryptography
provides extremely comprehensive, in-depth coverage of the field.
For general coverage of computer security issues, Security in Computing by Charles
Pfleeger provides a good overview of security, access control, and secure operating
systems and databases, and also goes into a number of other areas such as ethical
i
s
s
ue
st
ha
ta
r
e
n’
tc
ov
e
r
e
dbymos
tbo
ok
sonc
o
mp
ut
e
rs
e
c
u
r
i
t
y
.Computer Security:
Art and Science by Matt Bishop provides in-depth coverage of all aspects of
computer security modelling and design, with a particular emphasis on access control
and security models and high-assurance systems.

Recommended Reading

Installation
This chapter describes how to install cryptlib for a variety of operating systems.

AMX
The AMX Multitasking Executive is a real-time OS (RTOS) with development
hosted under Unix or Windows. You can build cryptlib for AMX using the crosscompilation capabilities of the standard makefile, see the entry for Unix on page 20
for more details on working with the makefile. The make target for AMX is
target-amx,
s
oy
ou’
dbui
l
dc
r
y
pt
l
i
bwi
t
hmake target-amx. Details on building
and using cryptlib for AMX, and on embedded cryptlib in general, are given in
“
Embedded Systems”onp
a
g
e287.

BeOS
The BeOS version of cryptlib can be built using a procedure which is identical to that
given for Unix on page 20. Any current version of BeOS can build the code directly
from the Unix makefile. Old versions of BeOS using the Be development
environment will require that you edit the Unix makefile slightly by un-commenting
the marked lines at the start of the file.

ChorusOS
ChorusOS is an embedded OS with development hosted under Unix. You can build
cryptlib for ChorusOS using the cross-compilation capabilities of the standard
makefile, see the entry for Unix on page 20 for more details on working with the
makefile. The make target for ChorusOS is target-chorus,
s
oy
ou’
dbui
l
d
cryptlib with make target-chorus. Details on building and using cryptlib for
Chor
us
OS,
a
n
done
mbe
d
de
dc
r
y
pt
l
i
bi
ng
e
ne
r
a
l
,
a
r
eg
i
v
e
ni
n“
Embedded Systems”
on page 287.

DOS
The 16-bit DOS version of cryptlib can be built from the same files as the 16-bit
Windows version, so no separate makefile is provided. Any attempt to use high-level
routines that require random data will fail with a CRYPT_ERROR_RANDOM error
code unless a /dev/random-s
t
y
l
edr
i
v
e
ri
sa
v
a
i
l
a
b
l
eb
e
c
a
us
et
he
r
ei
s
n
’
ta
nywa
yt
o
reliably obtain random data under DOS. You can however treat DOS as an
embedded systems environment and use the random seeding capability described in
“
Porting to Devices without Randomness/Entropy Sources”onp
a
g
e293.

DOS32
The 32-bit DOS version of cryptlib can be built using the supplied makefile, which
requires the djgpp compiler. The DOS32 version of cryptlib uses the same 32-bit
assembly language code used by the Win32 and 80x86 Unix versions, so it runs
significantly faster than the 16-bit DOS version. Like the 16-bit DOS version, any
attempt to use the high-level key export routines will fail with a CRYPT_ERROR_RANDOM error code unless a /dev/random-style driver is available because there
i
s
n’
ta
nywa
yt
or
e
l
i
a
bl
yo
bt
a
i
nr
a
nd
o
m da
t
au
nde
rDOS.Youc
a
nh
owe
v
e
rt
r
e
a
t
DOS as an embedded systems environment and use the random seeding capability
described in “
Porting to Devices without Randomness/Entropy Sources”onp
a
g
e293.

eCOS
eCOS is an embedded/real-time OS (RTOS) with development hosted under Unix or
Windows. You can build cryptlib for eCOS using the cross-compilation capabilities
of the standard makefile, see the entry for Unix on page 20 for more details on
working with the makefile. The make target for eCOS is target-ecos,
s
oy
ou’
d
build cryptlib with make target-ecos. Details on building and using cryptlib for
e
COS,
a
ndone
mbe
dde
dc
r
y
p
t
l
i
bi
ng
e
ne
r
a
l
,
a
r
eg
i
v
e
ni
n“
Embedded Systems”o
n
page 287.

Installation

µC/OS-II
µC/OS-II is an embedded/real-time OS (RTOS) with development usually hosted
under Windows. You can build cryptlib for µC/OS-II using the cross-compilation
capabilities of the standard makefile, see the entry for Unix on page 20 for more
details on working with the makefile. The make target for µC/OS-II is targetucos,
s
oy
ou’
dbui
l
dc
r
y
pt
l
i
bwi
t
hmake target-ucos. Details on building and
using cryptlib for µC/OS-II, and on embedded cryptlib in general, are given in
“
Embedded Systems”onp
a
g
e287.

Embedded Linux
The embedded Linux version of cryptlib can be built using the standard Linux
development tools. Since this environment is identical to the generic Unix one, the
installation instructions for Unix on page 20 apply here.

µITRON
µITRON is an embedded/real-time OS (RTOS) with development usually hosted
under Unix or a Unix-like OS. You can build cryptlib for µITRON using the crosscompilation capabilities of the standard makefile, see the entry for Unix on page 20
for more details on working with the makefile. The make target for µITRON is
target-itron,
s
oy
ou’
db
ui
l
dc
r
y
pt
l
i
bwi
t
hmake target-itron. Details on
building and using cryptlib for µITRON, and on embedded cryptlib in general, are
g
i
v
e
ni
n“
Embedded Systems”onp
a
g
e287.

Macintosh OS X
Thes
t
a
nda
r
dMa
c
i
n
t
os
hbu
i
l
de
nv
i
r
on
me
ntus
e
sAppl
e
’
sMa
cOSXDe
v
e
l
ope
rTo
ol
s
,
driven by the standard makefile, for which the instructions in the section on building
cryptlib for Unix on page 20 apply. Alternatively, you can build cryptlib using
Me
t
r
owor
k
s
’Cod
e
wa
r
r
i
orwi
t
ht
heMac.mcp project file. This can build cryptlib
either as a static or shared library for both 68K and PowerPC Macs, although since
t
hi
si
s
n’
tt
h
epr
i
ma
r
ybu
i
l
de
n
v
i
r
onme
n
tt
h
epr
oj
e
c
tf
i
l
ema
ya
ppl
yt
oas
l
i
g
ht
l
yol
de
r
cryptlib release and require a little updating to match the current configuration (the
standard makefile willa
l
wa
y
sbec
ur
r
e
n
t
)
.I
na
ddi
t
i
o
ni
t
’
sp
os
s
i
b
l
et
obu
i
l
di
tus
i
ng
Appl
e
’
sf
r
e
eMr
Cc
o
mpi
l
e
r
,
wi
t
ht
hes
a
mec
a
v
e
a
ta
b
ou
tu
pda
t
i
ngofc
on
f
i
g
ur
a
t
i
o
n
files.

MVS
The MVS version of cryptlib can be built using the standard IBM C/C++ compiler
and accompanying tools. Since this environment is very similar to the Unix one, the
installation instructions for Unix on page 20 apply here also. Note that PTF
UQ50384 (which fixes a bug in the macro version of the strcat function as
described i
nAPARPQ43
13
0
)i
sr
e
qui
r
e
di
fy
ou
’
r
eus
i
ngt
heV2R10C/
C++c
o
mp
i
l
e
r
.
You can control the use of ddnames with the DDNAME_IO define. If DDNAME_IO
is defined when building the code, cryptlib will use ddnames for all I/O, and user
options will be saved in dynamically allocated datasets userid.CRYPTLIB.filename.
If DDNAME_IO is not defined when building the code, cryptlib will use HFS for all
I/O, and user options will be saved in $HOME/.cryptlib.
Af
t
e
ry
ou
’
v
ebu
i
l
tc
r
y
pt
l
i
b,
y
ous
h
ou
l
dr
unt
hes
e
l
f
-test program to make sure that
everything is working OK. You can use the ussalloc USS shell script to allocate
MVS data sets for testlib, and the usscopy shell script to copy the files in the test
directory to the MVS data sets allocated with ussalloc. testlib.jcl is the JCL needed
to execute testlib.

OS2
The OS/2 version of cryptlib can be built using the command-line version of the IBM
compiler. The supplied makefile will build the DLL version of cryptlib, and can also
build the cryptlib self-test program, which is a console application. You should run

Recommended Reading

the self-t
e
s
tpr
og
r
a
ma
f
t
e
ry
ou’
v
eb
ui
l
tc
r
y
pt
l
i
bt
oma
k
es
u
r
et
ha
te
v
e
r
y
t
h
i
ngi
s
working OK.
I
fy
ou’
r
eus
i
ngt
heI
BM OS/
2c
ompi
l
e
ry
ous
h
oul
ds
e
te
nu
me
r
a
t
e
dt
y
p
e
st
oa
l
wa
y
sbe
32-bit values because the compiler by default uses variable-length types depending on
the enum range (so one enum could be an 8-bit type and another 32). cryptlib is
i
mmunet
ot
hi
s“
f
e
a
t
ur
e
”
,
a
ndf
un
c
t
i
onc
a
l
l
sf
r
o
my
ourc
o
d
et
oc
r
y
pt
l
i
bs
h
ou
l
da
l
s
ob
e
unaffected because of type promotion to 32-bit integers, but the variable-range enums
may cause problems in your code if you try to work with them under the assumption
that they have a fixed type.

PalmOS
PalmOS is the operating system for the Palm series of PDAs, with development
hosted under Unix or Windows. You can build cryptlib for PalmOS using the
PalmOS 6 SDK and the cross-compilation capabilities of the standard makefile, see
the entry for Unix on page 20 for more details on working with the makefile. The
make target for the PalmOS SDK is target-palmos and for the alternative PRC
development tools is target-palmos-prc,
s
oy
ou’
db
ui
l
dc
r
y
pt
l
i
bwi
t
hmake
target-palmos or make target-palmos-prc. Details on building and using cryptlib
for PalmOS, and on embedd
e
dc
r
y
pt
l
i
bi
ng
e
ne
r
a
l
,
a
r
eg
i
v
e
ni
n“
Embedded Systems”
on page 287.

QNX Neutrino
The QNX Neutrino version of cryptlib can be built using the standard QNX
development tools. Since this environment is identical to the generic Unix one, the
installation instructions for Unix on page 20 apply here.

RTEMS
The Real-Time Operating System for Multiprocessor Systems (RTEMS) is a realtime OS (RTOS) with development hosted under Unix or Windows. You can build
cryptlib for RTEMS using the cross-compilation capabilities of the standard makefile,
see the entry for Unix on page 20 for more details on working with the makefile. The
make target for RTEMS is target-rtems,
s
oy
ou’
dbu
i
l
dc
r
y
pt
l
i
bwi
t
hmake
target-rtems. Details on building and using cryptlib for RTEMS, and on embedded
c
r
y
pt
l
i
bi
ng
e
ne
r
a
l
,
a
r
eg
i
v
e
ni
n“
Embedded Systems”o
np
a
g
e287.

Tandem
The Tandem version of cryptlib can be built using the standard c89 compiler and
accompanying tools under the OSS environment. Since this environment is very
similar to the Unix one, the installation instructions for Unix on page 20 apply here
also. The default target is Tandem OSS, you can re-target the built for NSK using the
-Wsystype=guardian directive in the makefile.
The Guardian sockets implementation changed in newer releases of the OS. Older
releases required the use of nonstandard nowait sockets handled via AWAITIOX()
i
ns
t
e
a
do
ft
hes
t
a
nd
a
r
dBSDs
oc
k
e
t
si
n
t
e
r
f
a
c
e
.I
fy
ou
’
r
er
u
nni
nga
nol
de
rv
e
r
s
i
o
nof
the OS and need to use any of the secure networking protocols such as SSL/TLS,
SSH,
CMP,
SCEP,
RTCS,
orOCSP,
y
ou’
l
lne
e
dt
ous
ec
r
y
pt
l
i
b
’
sa
l
t
e
r
na
t
i
v
ene
t
wor
k
data-ha
n
dl
i
ngs
t
r
a
t
e
g
yde
s
c
r
i
be
di
n“
Network Issues”o
np
a
g
e127.

uClinux
uClinux is a real-mode/embedded version of Linux with development hosted under
Unix. You can build cryptlib for uClinux using the cross-compilation capabilities of
the standard makefile, see the entry for Unix on page 20 for more details on working
with the makefile. The make target for uClinux is target-uclinux,
s
oy
ou’
d
build cryptlib with make target-uclinux. Details on building and using cryptlib for
uCl
i
n
ux
,
a
ndo
ne
mbe
dd
e
dc
r
y
pt
l
i
bi
ng
e
ne
r
a
l
,
a
r
eg
i
v
e
ni
n“
Embedded Systems”on
page 287.

Installation

Unix
To unzip the code under Unix use the -a option to ensure that the text files are
converted to the Unix format. The makefile by default will build the statically-linked
library when you invoke it with make. To build the shared library, use make
shared. Once cryptlib has been built, use make testlib to build the cryptlib
self-test program testlib, or make stestlib to build the shared-library self-test
program stestlib. This will run fairly extensive self-tests of cryptlib that you can run
a
f
t
e
ry
ou’
v
eb
ui
l
ti
tto make sure that everything is working OK. testlib needs to be
run from the cryptlib root directory (the one that the main data files are in) since it
uses a large number of pre-generated data files that are located in a subdirectory
below this one. Depending on your system setup and privileges you may need to
either copy the shared library to /usr/lib or set the LD_LIBRARY_PATH
environment variable (or an OS-specific equivalent) to make sure that the shared
library is used.
I
fy
ou’
r
eus
i
ngt
hes
t
a
t
i
c
a
l
l
y-linked form of cryptlib in your application rather than
t
hes
h
a
r
e
dl
i
br
a
r
y
,
y
ou’
l
lpr
o
b
a
bl
yne
e
dt
ol
i
nki
na
d
di
t
i
o
na
l(
s
y
s
t
e
m-specific) static
libraries to handle threads, network access, and system-specific odds and ends. The
makefile contains a list of the needed additional libraries, ordered by system type and
version. The shared-l
i
br
a
r
yve
r
s
i
onofc
r
y
pt
l
i
bdo
e
s
n
’
tr
e
q
ui
r
et
h
e
s
ea
d
di
t
i
ona
l
libraries to be linked in, since the references are automatically resolved by the OS.
I
fy
ours
y
s
t
e
md
oe
s
n
’
tc
o
me pre-configured with a /dev/random, EGD, or
PRNGD-style style randomness driver (which continually accumulates random data
from the system), you may want to download one and install it, since cryptlib will
make use of it for gathering entropy. cryptlib has a built-in randomness polling
subsystem so it will function without an external randomness driver, but it never hurts
to have one present to supplement the internal entropy polling.
I
fy
ou’
r
eus
i
ngak
e
yda
t
a
ba
s
eorc
e
r
t
i
f
i
c
a
t
es
t
or
e
,
y
oune
e
dt
oe
n
a
b
l
e the use of the
a
ppr
o
pr
i
a
t
ei
nt
e
r
f
a
c
emod
ul
ef
ort
heda
t
a
b
a
s
eba
c
k
e
n
d.De
t
a
i
l
sa
r
eg
i
v
e
ni
n“
Key
Database Setup”o
npa
g
e23. For the cryptlib self-test code you can define the
database libraries using the TESTLIBS setting at the start of the makefile. If you
don
’
te
na
bl
et
heus
eo
fada
t
a
ba
s
ei
nt
e
r
f
a
c
e
,
t
hes
e
l
f
-test code will issue a warning
that no key database is present and continue without testing the database interface.
I
fy
ou’
r
eus
i
nga
nLDAPdirectory, you need to install the required LDAP client
library on your system, enable the use of LDAP using the USE_LDAP define before
you build cryptlib, and link the LDAP client library into your executable. If you
don
’
te
na
bl
et
heus
eo
fa
nLDAPdi
r
e
c
tory interface, the self-test code will issue a
warning that no LDAP directory interface is present and continue without testing the
LDAP interface.
I
fy
ou’
r
eus
i
ngs
pe
c
i
a
le
nc
r
y
p
t
i
o
nha
r
dwa
r
eora
ne
x
t
e
r
na
le
nc
r
y
pt
i
ond
e
v
i
c
es
u
c
ha
sa
PCMCIA card or smart card, you need to install the required device drivers on your
system and enable their use when you build cryptlib by linking in the required
i
nt
e
r
f
a
c
el
i
br
a
r
i
e
s
.I
fy
oud
on
’
te
na
b
l
et
heus
eofac
r
y
pt
od
e
v
i
c
e
,
t
hes
e
l
f
-test code
will issue a warning that no devices are present and continue without testing the
crypto device interface.
For any common Unix system, cryptlib will build without any problems, but in some
rare cases you may need to edit random/unix.c and possibly io/file.h and io/tcp.h if
y
ou’
r
erunning an unusual Unix variant that puts include files in strange places or has
broken Posix or sockets support.

VM/CMS
The VM/CMS version of cryptlib can be built using the standard C/370 compiler and
accompanying tools. The supplied EXEC2 file VMBUILD EXEC will build cryptlib
as a TXTLIB and then build the self-test program as an executable MODULE file.
Since VM sites typically have different system configurations, this file and possibly
portions of the source code may require tuning in order to adjust it to suit the build
process normally used at your site.

Recommended Reading

VxWorks
VxWorks is an embedded/real-time OS (RTOS) with development hosted under Unix
or Windows. You can build cryptlib for VxWorks using the cross-compilation
capabilities of the standard makefile, see the entry for Unix on page 20 for more
details on working with the makefile. The make target for VxWorks is targetvxworks,
s
oy
ou’
dbui
l
dc
r
y
pt
l
i
bwi
t
hmake target-vxworks. Details on building
and using cryptlib for VxWorks, and on embedded cryptlib in general, are given in
“
Embedded Systems”onp
a
g
e287.

Windows 3.x
The 16-bit cryptlib DLL can be built using the cl16.mak makefile, which is for
version 1.5x of the Visual C++ compiler. The mixed C/assembly language
encryption and hashing code will give a number of warnings, the remaining code
should compile without warnings. Once the DLL has been built, test.mak will build
the cryptlib self-test program, which is a console application. You can run this after
y
ou’
v
eb
ui
l
tc
r
y
pt
l
i
bt
oma
k
es
ur
et
ha
te
v
e
r
y
t
hi
ngi
swor
k
i
ngOK.
I
fy
ou’
r
eus
i
ngak
e
yda
t
a
ba
s
eorc
e
r
t
i
f
i
c
a
t
es
t
or
e
,
y
oune
e
dt
os
e
tu
pa
nODBCd
a
t
a
s
our
c
ef
ort
h
i
s
.De
t
a
i
l
sa
r
eg
i
v
e
ni
n“
Key Database Setup”onp
a
g
e23.

Windows 95/98/ME and Windows NT/2000/XP
The 32-bit cryptlib DLL can be built using the crypt32 project file, which is for
Visual C++ 6 and Visual C++ .NET. Once the DLL has been built, the test32
project file will build the cryptlib self-test program test32, which is a console
a
pp
l
i
c
a
t
i
on.Youc
a
nr
unt
hi
sa
f
t
e
ry
ou
’
v
eb
ui
l
tc
r
y
pt
l
i
bt
oma
k
es
ur
et
ha
te
v
e
r
y
t
h
i
ng
is working OK. test32 needs to be run from the cryptlib root directory (the one that
the main data files are in) since it uses a large number of pre-generated data files that
a
r
el
oc
a
t
e
di
nas
u
bd
i
r
e
c
t
or
ybe
l
owt
hi
so
ne
.I
fy
ou
’
l
lbeu
s
i
ngt
hec
r
y
pt
l
i
bus
e
r
interface components you need to install the cryptlib user interface library cl32ui.dll
alongside cryptlib itself.
I
fy
ou’
r
eus
i
nga
nol
de
rv
e
r
s
i
ono
fVi
s
ua
lC++.
NET,
abu
gi
ni
t
sv
e
r
s
i
on6pr
oj
e
c
t
file import process results in files having the $(NoInherit) property set, so that a
de
f
i
n
ema
dea
tt
h
epr
oj
e
c
tl
e
v
e
lwon
’
tb
epa
s
s
e
ddown to other files. If you want to
enable options based on global defines, you need to disable this property before the
defines will propagate down to other files.
I
fy
ou’
r
eus
i
ngak
e
yda
t
a
ba
s
eorc
e
r
t
i
f
i
c
a
t
es
t
or
e
,
y
oune
e
dt
os
e
tu
pa
nODBCd
a
t
a
sourc
ef
ort
h
i
s
.De
t
a
i
l
sa
r
eg
i
v
e
ni
n“
Key Database Setup”onp
a
g
e23.
I
fy
ou’
r
eus
i
nga
nLDAPdi
r
e
c
t
or
y
,
y
ouma
yne
e
dt
oi
ns
t
a
l
lt
her
e
q
ui
r
e
dLDAPc
l
i
e
nt
DLL on your system. By default cryptlib will use Wi
n
dows
’bu
i
l
t
-in LDAP client,
howe
v
e
rs
omer
a
t
h
e
rol
dv
e
r
s
i
onsofWi
nd
owsdon
’
tc
o
nt
a
i
nt
h
i
sa
ndy
o
u’
l
ln
e
e
dt
o
use the Netscape LDAP client DLL which is available for download from the
Netscape web site. To use this client instead of the Windows one, you need to define
NETSCAPE_CLI
ENTwhe
ny
oubu
i
l
dc
r
y
pt
l
i
b.I
fy
oud
o
n’
tha
v
et
heWi
n
dows
LDAPc
l
i
e
ntpr
e
s
e
nta
nddo
n’
tus
et
h
eNe
t
s
c
a
peo
ne
,
t
h
es
e
l
f
-test code will issue a
warning that no LDAP directory interface is present and continue without testing the
LDAP interface.
I
fy
ou’
r
eus
i
ngs
pe
c
i
a
le
nc
r
y
p
t
i
o
nha
r
dwa
r
eora
ne
x
t
e
r
na
le
nc
r
y
pt
i
ond
e
v
i
c
es
u
c
ha
sa
PCMCIA card or smart card, you need to install the required device drivers on your
s
y
s
t
e
m,
a
n
di
fy
o
u’
r
eus
i
ngag
e
ne
r
i
cPKCS#11de
v
i
c
ey
o
une
e
dt
oc
onfigure the
a
ppr
o
pr
i
a
t
edr
i
v
e
rf
ori
ta
sde
s
c
r
i
be
di
n“
Encryption Devices and Modules”onpa
g
e
265. cryptlib will automatically detect and use any devices that it recognises and that
have drive
r
spr
e
s
e
n
t
.I
fy
oud
on
’
te
na
b
l
et
heus
eofac
r
y
pt
ode
v
i
c
e
,
t
hes
e
l
f
-test code
will issue a warning that no devices are present and continue without testing the
crypto device interface.
Personal firewall products from some vendors can interfere with network operations
f
orde
v
i
c
e
sot
he
rt
h
a
ns
t
a
n
da
r
dwe
bbr
ows
e
r
sa
n
dma
i
lc
l
i
e
nt
s
.I
fy
ou’
r
ee
x
p
e
r
i
e
nc
i
ng
odd behaviour when using cryptlib for network operations (for example you can

Installation
c
on
ne
c
tbu
tc
a
n’
te
x
c
ha
ng
eda
t
a
,
ory
oug
e
ts
t
r
a
ng
ee
r
r
orme
s
s
a
g
e
swhe
ny
ou
connect), you can try temporarily disabling the personal firewall to see if this fixes
the problem. If it does, you should contact the personal firewall vendor to fix their
product, or switch to a different product.
I
fy
ou’
r
eus
i
ngBor
l
a
n
dC++r
a
t
he
rt
h
a
nVi
s
u
a
lC++,
y
ou
’
l
lne
e
dt
os
e
tupt
he.def
and .lib files for use with the Borland compiler. To do this, run the following
commands in the cryptlib directory:
impdef cl32 cl32
implib cl32 cl32.def

The first one will produce a Borland-specific .def file from the DLL, the second one
will produce a Borland-specific .lib file from the DLL and .def file.
To install the ActiveX control, put the cryptlib DLL and the ActiveX wrapper
clcom.dll into the Windows system directory and register the ActiveX wrapper with:
regsvr32 clcom.dll

To use the ActiveX control with Visual Basic, use Project | Reference to add
clcom.dll, after which VB will recognise the presence of the ActiveX wrapper.

Windows CE / Pocket PC / SmartPhone
The 32-bit cryptlib DLL for Windows CE/PocketPC can be built using the crypt32ce
project file, which is for version 3 or 4 of the eMbedded Visual C++ compiler. Once
the DLL has been built, the test32ce project file will build the cryptlib self-test
program test32ce, which is a (pseudo-)console application that produces its output
ont
hede
bugc
ons
o
l
e
.Youc
a
nr
unt
hi
sa
f
t
e
ry
ou’
v
eb
ui
l
tc
r
y
pt
l
i
bt
oma
k
es
ur
et
ha
t
everything is working OK. test32ce needs to be run from the cryptlib root directory
(the one that the main data files are in) since it uses a large number of pre-generated
data files that are located in a subdirectory below this one.
The cryptlib Windows CE self-t
e
s
tus
e
st
h
e‘
St
or
a
g
eCa
r
d’ps
e
u
do-folder to access
the files needed for the self-test. Depending on the system setup, you need to either
copy the files to the storage card or (the easier alternative) use folder sharing to
access the directory containing the test files. From the Windows CE menu, select
Folder Sharing and share the testdata subdirectory, which will appear as \\Storage
Card\ on the Windows CE device.
Windows CE is a Unicode environment, which means that all text strings are passed
to and from cryptlib as Unicode strings. For simplicity the examples in this manual
are presented using the standard char data type used on most systems, however
under Windows CE all character types and strings are Unicode in line with standard
Wi
nd
owsCEpr
a
c
t
i
c
e
.Whe
ny
ou’
r
eus
i
ngt
hee
x
a
mpl
e
s
,
y
ous
h
ou
l
dt
r
e
a
ta
ny
occurrence of characters and strings as standard Unicode data types.
A fe
wol
de
rv
e
r
s
i
o
nsofe
VC++f
ors
o
mep
l
a
t
f
or
msd
on
’
ti
nc
l
udet
heANSI
/
I
SOC
standard time.h header, which is a required file for a conforming ANSI/ISO C
c
o
mp
i
l
e
r
.I
fy
ouha
v
eav
e
r
s
i
ono
fe
VC++t
ha
tdoe
s
n’
ti
n
c
l
udet
hi
ss
t
a
n
da
r
dh
e
a
d
e
r
,
you need to add it from another source, for example an eVC++ distribution that does
include it or the standard (non-embedded) VC++ distribution.

Xilinx XMK
The Xilinx Microkernel (XMK) is a real-time OS (RTOS) with development hosted
under Unix or Windows. You can build cryptlib for XMK using the crosscompilation capabilities of the standard makefile, see the entry for Unix on page 20
for more details on working with the makefile. The make target for XMK is
target-xmk-mb for the MicroBlaze core and target-xmk-ppc for the
Powe
r
PCc
or
e
,
s
oy
o
u’
dbu
i
l
dc
r
y
pt
l
i
bwi
t
hmake target-xmk-mb or make targetxmk-ppc. Details on building and using cryptlib for XMK, and on embedded
c
r
y
pt
l
i
bi
ng
e
ne
r
a
l
,
a
r
eg
i
v
e
ni
n“
Embedded Systems”on page 287.

Recommended Reading

Other Systems
cryptlib should be fairly portable to other systems, the only part that needs special
attention is the randomness-gathering in random/os_name.c (
c
r
y
pt
l
i
bwon
’
twor
k
without this, the code will produce a link error). The idea behind the randomnessgathering code is to perform a comprehensive poll of every possible entropy source in
t
hes
y
s
t
e
mi
nas
e
pa
r
a
t
et
hr
e
a
dorba
c
k
g
r
oundt
a
s
k(
“
s
l
owPol
l
”
)
,
a
swe
l
la
spr
ov
i
di
ng
a less useful but much faster poll of quick-r
e
s
po
ns
es
o
ur
c
e
s(
“
f
a
s
t
Po
l
l
”
)
.I
na
dd
i
t
i
on
the filesystem I/O code in io/file.c may need system-specific code and definitions
a
dd
e
dt
oi
ti
ft
hes
y
s
t
e
my
ou
’
r
er
unn
i
ngondoe
s
n’
tus
eas
t
a
nda
r
df
or
mo
ff
i
l
eI
/
O,
f
or
example a system that has its ownf
i
l
eI
/
Ol
a
y
e
rt
ha
ti
s
n
’
tc
ompa
t
i
b
l
ewi
t
hs
t
a
nda
r
d
mo
de
l
soronet
ha
tdo
e
s
n
’
th
a
v
ef
i
l
eI
/
Oa
ta
l
ls
uc
ha
sa
ne
mb
e
d
de
dde
v
i
c
et
ha
tus
e
s
flash memory for storage.
To find out what to compile, look at the Unix makefile, which contains all of the
necessary source files (the group_name_OBJS dependencies) and compiler
options. Link all of these into a library (as the makefile does) and then compile and
link the modules in the test subdirectory with the library to create the self-test
program. There is additional assembly-language code included that will lead to
noticeable speedups on some systems, you should modify your build options as
appropriate to use these if possible.
Depending on your compiler you may get a few warnings about some of the
encryption and hashing code (one or two) and the bignum code (one or two). This
code mostly relates to the use of C as a high-level assembler and changing things
around to remove the warnings on one system could cause the code to break on
another system.

Key Database Setup
If you want to work with a key database or certificate store, you need to configure a
database for cryptlib to use. Under Windows, go to the Control Panel and click on
t
heODBC/
ODBC3
2i
t
e
m.Cl
i
c
kon“
Ad
d”a
n
ds
e
l
e
c
tt
heODBCda
t
as
our
c
e(
t
ha
ti
s
,
thed
a
t
a
ba
s
et
y
p
e
)t
ha
ty
ouwa
ntt
ous
e
.I
fi
t
’
so
nt
h
el
o
c
a
lma
c
hi
ne
,
t
h
i
swi
l
l
pr
oba
bl
ybea
nAc
c
e
s
sda
t
a
ba
s
e
,
i
fi
t
’
sac
e
nt
r
a
l
i
s
e
dda
t
a
ba
s
eonan
e
t
wor
kt
hi
swi
l
l
pr
oba
bl
ybeSQLSe
r
v
e
r
.Onc
ey
ou’
v
es
e
l
e
c
t
e
dt
hed
a
t
as
o
ur
c
et
y
pe
,
y
oun
e
e
dt
og
i
v
e
it a na
mef
orc
r
y
pt
l
i
bt
ous
e
.“
Pu
bl
i
cKe
y
s
”i
sag
oodc
ho
i
c
e(
t
hes
e
l
f
-test code uses
two sources called testkeys and testcertstore during the self-test procedure, and
will create these itself if possible). In addition you may need to set up other
parameters like the server that the database is located on and other access
information. Once the data source is set up, you can access it as a CRYPT_KEYSET_ODBCk
e
ys
e
tus
i
n
gt
hena
met
ha
ty
o
u’
v
ea
s
s
i
g
ne
dt
oi
t
.
Under Unix or similar systems the best way to work with a key database or certificate
store is to use the ODBC interface, either via a layered driver such as unixODBC or
iODBC, or directly via interfaces such as MyODBC. Alternatively, you can use the
cryptlib generic database interface to compile database-specific support code directly
into cryptlib, or the database network plugin capability to make a network connection
to a database server such as IBM DB2, Informix, Ingres, Oracle, Postgres, or Sybase.
The easiest interface to use is the ODBC one, which hides all of the low-level
database interface details. The ODBC configuration process follows the same pattern
as the one given above for ODBC under Windows, with OS-specific variations
de
p
e
n
di
ngont
h
epl
a
t
f
or
mt
h
a
ty
ou
’
r
er
un
ni
ngi
tun
de
r
.Youc
a
ne
n
a
bl
e the use of the
ODBCi
nt
e
r
f
a
c
eus
i
ngt
heUSE_ODBCde
f
i
nebe
f
or
ey
oub
ui
l
dc
r
y
pt
l
i
b,
a
n
di
fy
ou
’
r
e
not using Windows (which uses dynamic binding to the ODBC interface) you need to
link the ODBC client library into your executable.
For Unix and Unix-like systems the two most common ODBC implementations are
unixODBC and iODBC, although a variety of other products are also available, and
some databases have native ODBC support, examples being MySQL (via MyODBC)
and IBM DB2. These interfaces support a wide range of commercial database
including AdabasD, IBM DB2, Informix, Ingres, Interbase, MySQL, Oracle,
Postgres, and Sybase. unixODBC uses the ODBCConfig GUI application to

Installation

configure data sources and drivers in a manner identical to the standard Windows
interface, and also provides the odbcinst CLI utility to configure data sources and
drivers. odbcinst can be used to automatically install and configure database drivers
for ODBC using template files that contain information about the driver such as the
location of the driver binaries, usually somewhere under /usr/local. For example to
c
on
f
i
g
ur
et
heOr
a
c
l
edr
i
v
e
r
sf
orODBCus
i
ngapr
e
pa
r
e
dt
e
mp
l
a
t
ef
i
l
ey
ou
’
dus
e
:
odbcinst –i –d –f oracle.tmpl

iODBC provides drivers as platform-specific binaries that are installed using the
iODBC installation shell scripts. See the documentation for the particular ODBC
i
nt
e
r
f
a
c
et
h
a
ty
ou
’
r
eus
i
ngf
ormor
ei
nf
or
ma
t
i
o
noni
ns
t
a
l
l
a
t
i
ona
ndc
on
f
i
g
ur
a
t
i
on
issues.
I
fy
oudo
n
’
twa
ntt
ous
et
heODBCi
nt
e
r
f
a
c
e
,
y
ouc
a
ne
i
t
he
rc
ompi
l
eda
tabasespecific interface code directly into cryptlib or use the database network plugin
c
a
pa
bi
l
i
t
yt
oma
k
ean
e
t
wor
kc
on
ne
c
t
i
ont
oada
t
a
b
a
s
es
e
r
v
e
r
.Tous
ec
r
y
pt
l
i
b’
s
generic database interface you need to define USE_DATABASE when you build
cryptlib and add the appropriate interface code to communicate with the database
back-e
n
dofy
o
urc
ho
i
c
e
,
a
sd
e
s
c
r
i
be
di
n“
Database and Networking Plugins”onpa
g
e
295. In addition you need to link the database library or libraries (for example
libmysql.a) into your executable.
To use the database plugin capability to make a network connection to a database
server such as Informix, Ingres, Oracle, Postgres, or Sybase, you need to create the
appropriate plugin for y
ours
e
r
v
e
ra
sde
s
c
r
i
be
di
n“
Database and Networking
Plugins”onpa
g
e295.
If you need to use a database keyset on an embedded system, you can use a system
like the SQLite embedded database engine, http://sqlite.org/. SQLite is a selfcontained, embeddable, zero-configuration SQL database engine that provides all of
the capabilities needed by cryptlib database keysets.

Customised and Cut-down cryptlib Versions
In some cases you may want to customise the cryptlib build or create a cut-down
version that omits certain capabilities in order to reduce code size for constrained
environments. You can do this by editing the configuration build file cryptini.h,
whi
c
ha
l
l
owsa
l
mos
te
v
e
r
ypa
r
tofc
r
y
pt
l
i
b
’
sf
un
ctionality to be selectively enabled or
di
s
a
bl
e
d(
s
omef
unc
t
i
on
a
l
i
t
yi
sus
e
dbya
l
lofc
r
y
pt
l
i
ba
n
dc
a
n’
tbedi
s
a
bl
e
d)
.Ea
c
h
portion of functionality is controlled by a USE_name define, by undefining the value
before you build cryptlib the named functionality will be removed. For example,
undefining USE_SSH1 would disable the use of SSHv1 (this is disabled by default,
s
i
nc
ei
t
’
sbe
e
ns
up
e
r
s
e
de
dbySSHv
2)
;unde
f
i
n
i
ngUSE_SKI
PJ
ACKwou
l
dd
i
s
a
b
l
e
the use of the Skipjack algorithm. In addition you can use the build file to disable the
us
eo
ft
h
et
wopa
t
e
n
t
e
da
l
g
or
i
t
h
msI
DEAa
ndRC5(
s
e
e“
Algorithms”o
npa
g
e302 for
more information on whether these two patents affect your use of cryptlib) by
undefining USE_PATENTED_ALGORI
THMS.Mor
ede
t
a
i
l
sont
un
i
ngc
r
y
pt
l
i
b
’
s
size and capabilities (particularly for use in embedded systems) is given in
“
Embedded Systems”onp
a
g
e287.

Debug vs. Release Versions of cryptlib
cryptlib can be built in one of two forms, a debug version and a release version. The
main difference between the two is that the release version is built with the NDEBUG
value defined, which disables the large number of internal consistency checks that are
present in the debug build of cryptlib. These consistency checks are used to catch
conditions such as inappropriate error codes being returned from internal functions,
invalid data values being passed to functions inside cryptlib, configuration errors, and
general sanity checks that ensure that everything is operating as it should. If one of
these internal checks is triggered, cryptlib will throw an exception and display an
error message indicating that an assertion in the code has failed. These assertions are
useful for tracking down areas of code that may need revision in later releases.

Recommended Reading

I
fy
oudo
n
’
twa
ntt
os
e
et
he
s
edi
a
g
nos
t
i
cme
s
s
a
g
e
s
,
y
ous
ho
ul
dbu
i
l
dc
r
y
p
t
l
i
bwi
t
ht
he
NDEBUG value defined (this is the default under Unix and is done automatically
under Windows when you build a release version of the code with Visual C++).
Building a version in this manner will disable the extra consistency checks that are
present in the debug version so that, for example, error conditions will be indicated
by cryptlib returning an error code for a function call rather than throwing an
e
x
c
e
pt
i
o
n.Thi
swi
l
lh
a
v
et
hes
l
i
g
htdowns
i
d
et
h
a
ti
t
’
l
lma
k
et
r
a
c
k
i
ngt
hee
x
a
c
t
location of a problem a bit more complex, since the error code which is returned
pr
oba
bl
ywon
’
tbe checked until the flow of execution has progressed a long way
from where the problem was detected. On the other hand the release version of the
code is significantly smaller than the debug version.
Asa
l
wa
y
s
,
i
fy
ou’
r
ewor
k
i
ngwi
t
hade
bugbui
l
do
ft
hecode and perform an
operation that triggers an internal consistency check you should report the details and
the code necessary to recreate it to the cryptlib developers in order to allow the
exception condition to be analysed and corrected.

cryptlib Version Information
cryptlib uses 3-digit version numbers, available at runtime through the configuration
options CRYPT_OPTION_INFO_MAJORVERSION, CRYPT_OPTION_INFO_MINORVERSION, and CRYPT_OPTION_INFO_STEPPING, and at compile time
through the define CRYPTLIB_VERSION. CRYPTLIB_VERSION contains the
current version as a 3-digit decimal value with the first digit being the major version
number (currently 3), the second digit being the minor version number, and the third
digit being the update or stepping number. For example, cryptlib version 3.2.1 would
have a CRYPTLIB_VERSION value of 321.
All cryptlib releases with the same stepping version number are binary-compatible.
This means that if you move from (for example) cryptlib version 3.2.1 to 3.2.2, all
you need to do is replace the cryptlib DLL or shared library to take advantage of new
cryptlib features and updates. All cryptlib releases with the same minor version
number as source-compatible, so that if you move from (for example) 3.2.1 to 3.3.5,
you need to recompile your application to match new features in cryptlib.

Support for Vendor-specific Algorithms
cryptlib supports the use of vendor-specific algorithm types with the predefined
values CRYPT_ALGO_VENDOR1, CRYPT_ALGO_VENDOR2, and
CRYPT_ALGO_VENDOR3. For each of the algorithms you use, you need to add a
call to initialise the algorithm capability information to device/system.c alongside
the existing algorithm initialisation, and then provide your implementation of the
algorithm to compile and link into cryptlib. When you rebuild cryptlib with the
preprocessor define USE_VENDOR_ALGOS set, the new algorithm types will be
i
nc
l
u
de
di
nc
r
y
pt
l
i
b
’
sc
a
pa
bi
l
i
t
i
e
s
.
For example if you wanted to add support for the Foo256 cipher to cryptlib you
would create the file vendalgo.c containing the capability definitions and then
rebuild cryptlib with USE_VENDOR_ALGOS defined. The Foo256 algorithm
would then become available as algorithm type CRYPT_ALGO_VENDOR1.

cryptlib Basics

cryptlib Basics
cryptlib works with two classes of objects, container objects and action objects. A
container object is an object that contains one or more items such as data, keys or
certificates. An action object is an object which is used to perform an action such as
encrypting or signing data. The container types used in cryptlib are envelopes (for
data), sessions (for communications sessions), keysets (for keys), and certificates (for
attributes such as key usage restrictions and signature information). Container
objects can have items such as data or public/private keys placed in them and
retrieved from them. In addition to containing data or keys, container objects can
also contain other objects that affect the behaviour of the container object. For
example pushing an encryption object into an envelope container object will result in
all data which is pushed into the envelope being encrypted or decrypted using the
encryption object.
Encryption contexts are the action objects used by cryptlib. Action objects are used
to act on data, for example to encrypt or decrypt a piece of data or to digitally sign or
check the signature on a piece of data.
The usual mechanism for processing data is to use an envelope or session container
object. The process of pushing data into an envelope and popping the processed data
back out is known as enveloping the data. The reverse process is known as deenveloping the data. Session objects work in a similar manner, but are used to
encapsulate a secure session with a remote client or server rather than a local data
transformation. The first section of this manual covers the basics of enveloping data,
which introduces the enveloping mechanism and covers various aspects of the
enveloping process such as processing data streams of unknown length and handling
errors. Once you have the code to perform basic enveloping in place, you can add
extra functionality such as password-based data encryption to the processing. After
the basic concepts behind enveloping have been explained, more advanced techniques
such as public-key based enveloping and digital signature enveloping for S/MIME
and PGP are covered.
Session objects are very similar to envelope objects except that they represent a
communications session with a remote client or server. The next section covers the
use of session objects for protocols such as SSL, TLS, and SSH to secure
communications or work with protocols such as CMS, SCEP, RTCS, OCSP, and TSP
that handle functions such as certificate status information and timestamping.
The use of public keys for enveloping requires the use of key management functions,
and the next section covers key generation and storing and retrieving keys from
keyset objects and crypto devices. The public portions of public/private key pairs are
typically managed using X.509 certificates and certificate revocation lists. The next
sections cover the management of certificates including certificate issue, certificate
status checking, and certificate revocation list (CRL) creation and checking, as well
as the full CA management process. This covers the full key life cycle from creation
through certification to revocation and/or destruction.
So far all the objects that have been covered are container objects. The next section
covers the creation of action objects that you can either push into a container object or
apply directly to data, including the various ways of loading or generating keys into
them. The next sections explain how to apply the action objects to data and cover the
process of encryption, key exchange, and signature generation and verification,
working at a much lower level than the encryption or session interface.
The next sections cover certificates and certificate-like objects in more detail than the
earlier ones, covering such topics as DN structures, certificate chains, trust
management, and certificate extensions. This deals with certificates at a very low
l
e
v
e
la
twhi
c
ht
he
y
’
r
er
a
t
he
rh
a
r
de
rt
oma
n
a
g
et
ha
nwi
t
ht
hehi
g
h-level certificate
management functions.
The next section covers the use of encryption devices such as smart cards, crypto
devices, HSMs, and Fortezza cards, and explains how to use them to perform many of

Programming Interfaces

the tasks covered in previous sections. Finally, the last sections cover miscellaneous
topics such as random number management, the cryptlib configuration database,
database and network plugins, and use in embedded systems.

Programming Interfaces
cryptlib provides three levels of interface, of which the highest-level one is the easiest
to use and therefore the recommended one. At this level cryptlib works with
envelope and session container objects, an abstract object into which you can insert
and remove data which is processed as required while it is in the object. Using
envelopes and session objects requires no knowledge of encryption or digital
signature techniques. At an intermediate level, cryptlib works with encryption action
objects, and requires some knowledge of encryption techniques. In addition you will
need to handle some of the management of the encryption objects yourself. At the
very lowest level cryptlib works directly with the encryption action objects and
requires you to know about algorithm details and key and data management methods.
Before you begin you should decide which interface you want to use, as each one has
its own distinct advantages and disadvantages. The three interfaces are:

Container Object Interface
This interface requires no knowledge of encryption and digital signature techniques,
a
ndi
se
a
s
i
e
s
tf
orus
ewi
t
hl
a
n
g
ua
g
e
sl
i
k
eVi
s
ua
lBa
s
i
ca
ndJ
a
v
at
ha
tdo
n’
ti
n
t
e
r
f
a
c
et
o
C data structures very well. The container object interface provides services to create
and destroy envelopes and secure sessions, to add security attributes such as
encryption information and signature keys to a container object, and to move data
into and o
uto
fac
o
nt
a
i
n
e
r
.Be
c
a
us
eofi
t
ss
i
mp
l
i
c
i
t
ya
n
de
a
s
eofus
e
,
i
t
’
ss
t
r
ong
l
y
recommended that you use this interface if at all possible.

Mid-level Interface
This interface requires some knowledge of encryption and digital signature
techniques. Because it handles encoding of things like session keys and digital
s
i
g
na
t
ur
e
sbutno
to
ft
heda
t
ai
t
s
e
l
f
,
i
t
’
sbe
t
t
e
rs
u
i
t
e
df
ora
p
pl
i
c
a
t
i
o
nst
ha
tr
e
q
ui
r
ehi
g
hspeed data encryption, or encryption of many small data packets (such as an
encrypted terminal session). The mid-level interface provides services such as
routines to export and import encrypted keys and to create and check digital
signatures. The container object interface is built on top of this interface.

Action Object Interface
This interface requires quite a bit of knowledge of encryption and digital signature
techniques. It provides a direct interface to the raw encryption capabilities of
cryptlib. The only reason for using these low-level routines is if you need them as
building blocks for your own custom encryption protocol. Note though that cryptlib
is designed to benefit the application of encryption in standard protocols and not the
raw use of crypto in home-made protocols. Getting such security protocols right is
v
e
r
ydi
f
f
i
c
u
l
t
,
wi
t
hma
ny“
ob
v
i
ous
”a
nd“
s
i
mpl
e
”a
p
pr
oa
c
h
e
sbe
i
ngqui
t
ev
ul
ne
r
a
b
l
e
to attack. This is why cryptlib encourages the use of vetted security protocols, and
does not encourage roll-your-owns
e
c
ur
i
t
yme
c
ha
ni
s
ms
.I
npa
r
t
i
c
ul
a
ri
fy
oud
on
’
t
know what PKCS #1 padding is, what CBC does, or why you need an IV, you
s
hou
l
d
n’
tbeus
i
ngt
hi
si
nt
e
r
f
a
c
e
.
The low-level interface serves as an interface to a range of plug-in encryption
modules that allow encryption algorithms to be added in a fairly transparent manner,
with a standardised interface allowing any of the algorithms and modes supported by
cryptlib to be used with a minimum of coding effort. As such the main function of
the action object interface is to provide a standard, portable interface between the
underlying encryption routines and the user software. The mid-level interface is built
on top of this interface.

Objects and Interfaces
The cryptlib object types are as follows:

cryptlib Basics

Type

Description

CRYPT_CERTIFICATE

A key certificate objects that usually contain a
key certificate for an individual or organisation
but can also contain other information such as
certificate chains or digital signature attributes.

CRYPT_CONTEXT

A encryption context objects that contain
encryption, digital signature, hash, or MAC
information.

CRYPT_DEVICE

A device object that provide a mechanism for
working with crypto devices such as crypto
hardware accelerators and PCMCIA and smart
cards.

CRYPT_ENVELOPE

An envelope container object that provide an
abstract container for performing encryption,
signing, and other security-related operations on
an item of data.

CRYPT_KEYSET

A key collection container object that contain
collections of public or private keys.

CRYPT_SESSION

A secure session object that manage a secure
session with a server or client.

These objects are referred to via arbitrary integer values, or handles, which have no
meaning outside of cryptlib. All data pertaining to an object is managed internally by
cryptlib, with no outside access to security-related information being possible. There
is also a generic object handle of type CRYPT_HANDLE which is used in cases
where the exact type of an object is not important. For example most cryptlib
functions that require keys can work with either encryption contexts or key certificate
objects, so the objects they use have a generic CRYPT_HANDLE which is equivalent
to either a CRYPT_CONTEXT or a CRYPT_CERTIFICATE.

Objects and Attributes
Each cryptlib object has a number of attributes of type CRYPT_ATTRIBUTE_TYPE
that you can get, set, and in some cases delete. For example an encryption context
would have a key attribute, a certificate would have issuer name and validity
attributes, and an envelope would have attributes such as passwords or signature
information, depending on the type of the envelope. Most cryptlib objects are
controlled by manipulating these attributes.
The attribute classes are as follows:
Type

Description

CRYPT_ATTRIBUTE_name

Generic attributes that apply to all objects.

CRYPT_CERTINFO_name

Certificate object attributes.

CRYPT_CTXINFO_name

Encryption context attributes.

CRYPT_DEVINFO_name

Crypto device attributes.

CRYPT_ENVINFO_name

Envelope attributes.

CRYPT_KEYINFO_name

Keyset attributes.

CRYPT_OPTION_name

cryptlib-wide configuration options.

CRYPT_PROPERTY_name

Object properties.

CRYPT_SESSINFO_name

Session attributes.

Some of the attributes apply only to a particular object type but others may apply
across multiple objects. For example a certificate contains a public key, so the key
size attribute, which is normally associated with a context, would also apply to a

Interfacing with cryptlib

certificate. To determine the key size for the key in a certificate, you would read its
key size attribute as if it were an encryption context.
Attribute data is either a single numeric value or variable-length data consisting of a
(data, length) pair. Numeric attribute values are used for objects, boolean values and
integers. Variable-length data attribute values are used for text strings, binary data
blobs, and representations of time using the ANSI/ISO standard seconds-since-1970
format.

Interfacing with cryptlib
All necessary constants, types, structures, and function prototypes are defined in a
language-specific header file as described below. You need to use these files for each
module that makes use of cryptlib. Although many of the examples given in this
manual are for C/C++ (the more widely-used ones are given for other languages as
well), they apply equally for the other languages.
All language bindings for cryptlib are provided in the bindings subdirectory. Before
you can use a specific language interface, you may need to copy the file(s) for the
l
a
ng
ua
g
et
ha
ty
ou’
r
eus
i
ngi
nt
ot
hec
r
y
p
t
l
i
bma
i
ndi
r
e
c
t
or
yort
hed
i
r
e
c
t
or
yc
ont
a
i
ni
ng
t
hea
pp
l
i
c
a
t
i
ont
ha
ty
ou’
r
ebu
i
l
d
i
ng
.Al
t
e
r
na
t
i
v
e
l
y
,
y
ouc
an refer to the file(s) in the
bindings directory by the absolute pathname.

Initialisation
Before you can use any of the cryptlib functions, you need to call the cryptInit
function to initialise cryptlib. You also need to call its companion function cryptEnd
a
tt
h
ee
n
do
fy
ourpr
og
r
a
ma
f
t
e
ry
ou’
v
ef
i
ni
s
he
dus
i
ngc
r
y
pt
l
i
b.cryptInit initialises
cryptlib for use, and cryptEnd performs various cleanup functions including
automatic garbage collection of any objects you may have forgotten to destroy. You
don
’
t have to worry about inadvertently calling cryptInit multiple times (for example
i
fy
ou
’
r
ec
a
l
l
i
ngi
tf
r
ommul
t
i
pl
et
hr
e
a
ds
)
,
i
twi
l
lha
nd
l
et
hei
ni
t
i
a
l
i
s
a
t
i
o
nc
or
r
e
c
t
l
y
.
However you should only call cryptEnd onc
ewhe
ny
o
u’
v
ef
i
ni
s
h
e
dus
i
ngc
r
y
pt
l
i
b.
If you call cryptEnd and there are still objects in existence, it will return CRYPT_ERROR_INCOMPLETE to inform you that there were leftover objects present.
cryptlib can tell this because it keeps track of each object so that it can erase any
sensitive data that may be present in the object (cryptEnd will return a CRYPT_ERROR_INCOMPLETE error to warn you, but will nevertheless clean up and free
each object for you).
To make the use of cryptEnd in a C or C++ program easier, you may want to use the
C atexit() function or add a call to cryptEnd to a C++ destructor in order to have
cryptEnd called automatically when your program exits.
I
fy
ou’
r
eg
oi
ngt
obedo
i
ngs
ome
t
hi
ngt
ha
tne
e
dse
n
c
r
y
pt
i
o
nk
e
y
s(
whi
c
hi
spr
e
t
t
y
much everything), you should also perform a randomness poll fairly early on to give
cryptlib enough random data to create keys:
cryptAddRandom( NULL, CRYPT_RANDOM_SLOWPOLL );

Ra
n
do
mn
e
s
spo
l
l
sa
r
ed
e
s
c
r
i
b
e
di
nmor
ede
t
a
i
li
n“
Random Numbers”onp
a
g
e279.
Ther
a
n
do
mn
e
s
spo
l
le
x
e
c
ut
e
sa
s
y
nc
hr
on
ous
l
y
,
s
oi
twon
’
ts
t
a
l
lt
her
e
s
tofy
ourc
ode
whi
l
ei
t
’
sr
u
nn
i
ng
.Theonep
os
s
i
b
l
ee
x
c
e
p
t
i
ont
ot
h
i
sp
ol
l
i
ngons
t
a
r
t
upi
swhe
n
y
ou’
r
eus
i
ngc
r
y
pt
l
i
ba
sp
a
r
to
fal
a
r
g
e
ra
ppl
i
c
a
t
i
onwh
e
r
ey
ou
’
r
eno
tc
e
r
t
a
i
nthat
c
r
y
pt
l
i
bwi
l
la
c
t
u
a
l
l
ybeus
e
d.Fore
x
a
mpl
eaPHPs
c
r
i
ptt
h
a
t
’
sr
u
nr
e
pe
a
t
e
dl
yf
r
o
m
the command line may only use the encryption functionality on rare occasions (or not
a
ta
l
l
)
,
s
ot
ha
ti
t
’
sbe
t
t
e
rt
ope
r
f
or
mt
hes
l
owpo
l
lo
nl
ywhe
ni
t
’
sa
c
t
ua
l
l
yne
e
ded rather
than unconditionally every time the script is invoked. This is a somewhat special
c
a
s
et
h
oug
h,
a
ndn
or
ma
l
l
yi
t
’
sbe
t
t
e
rpr
a
c
t
i
c
et
oa
l
wa
y
spe
r
f
or
mt
h
es
l
owp
ol
lon
startup.
As the text above mentioned, you should initialise cryptlib when your program first
starts and shut it down when your program is about to exit, rather than repeatedly
starting cryptlib up and shutting it down again each time you use it. Since cryptlib

cryptlib Basics

consists of a complete crypto operating system with extensive initialisation, internal
security self-tests, and full resource management, repeatedly starting and stopping it
will unnecessarily consume resources such as processor time during each
initialisation and shutdown. It can also tie up host operating system resources if the
host contains subsystems that leak memory or handles (under Windows, ODBC and
LDAP are particularly bad, with ODBC leaking memory and LDAP leaking handles.
DNS is also rather leaky — this is one of the reasons why programs like web
browsers and FTP clients consume memory and handles without bounds). To avoid
this problem, you should avoid repeatedly starting up and shutting down cryptlib:
Right

Wrong

cryptInit();
serverLoop:
process data;
cryptEnd();

serverLoop:
cryptInit();
process data;
cryptEnd();

C / C++
To use cryptlib from C or C++ you would use:
#include "cryptlib.h"
cryptInit();
/* Calls to cryptlib routines */
cryptEnd();

C# / .NET
To use cryptlib from C# / .NET, add cryptlib.cs to your .NET project and the cryptlib
DLL to your path, and then use:
using cryptlib;
crypt.Init();
// Calls to cryptlib routines
crypt.End();

I
fy
ou’
r
eus
i
nga.
NETl
a
ng
ua
g
eot
he
rt
ha
nC#(
f
ore
x
a
mp
l
eVB.
NET)
,y
ou’
l
lne
e
dt
o
build cryptlib.cs as a class library first. From Visual Studio, create a new C# project
of type Class Library, add cryptlib.cs to it, and compile it to create a DLL. Now go
to your VB project and add the DLL as a Reference. The cryptlib classes and
me
t
h
odswi
l
lbea
v
a
i
l
a
b
l
en
a
t
i
v
e
l
yus
i
ngVB(
orwha
t
e
v
e
r.
NETl
a
ng
ua
g
ey
ou’
r
e
using).
All cryptlib functions are placed in the crypt class, so that standard cryptlib
functions like:
cryptSetAttribute( cryptContext, CRYPT_CTXINFO_KEYSIZE, 1024 / 8 );

become:
crypt.SetAttribute( cryptContext, crypt.CTXINFO_KEYSIZE, 1024 / 8 );

In general when calling cryptlib functions you can use Strings wherever the cryptlib
interface requires a null-terminated C string, and byte arrays wherever the cryptlib
interface requires binary data.
Instead of returning a status value like the native C interface, the .NET version throws
CryptException for error status returns, and returns integer or string data return
values as the return value:
value = crypt.GetAttribute( cryptContext, crypt.CTXINFO_ALGO );
stringValue = crypt.GetAttributeString( cryptContext,
crypt.CTXINFO_ALGO_NAME );

Delphi
To use cryptlib from Delphi, add the cryptlib DLL to your path and then use:

Interfacing with cryptlib

implementation
uses cryptlib;
cryptInit;
{ Calls to cryptlib routines }
cryptEnd;
end;

The Delphi interface to cryptlib is otherwise mostly identical to the standard C/C++
one.

Java
To build the JNI version of cryptlib, uncomment the USE_JAVA define in cryptini.h
(
s
e
e“
Customised and Cut-down cryptlib Versions”onp
a
g
e24) or define it when you
inv
ok
et
h
ebu
i
l
dc
o
mma
nd,
a
ndb
ui
l
dc
r
y
pt
l
i
b.You
’
l
lne
e
dt
oh
a
v
et
heJ
DKi
nc
l
u
de
di
r
e
c
t
or
i
e
ss
e
ti
ny
ourc
o
mpi
l
e
r
’
ss
e
t
t
i
ng
s
,
a
ndwi
l
lne
e
da
tl
e
a
s
tJ
DK1.
4.Onc
et
h
i
s
is done, you can put cryptlib.jar on your classpath and use System.LoadLibrary() to load the cryptlib shared library. To use cryptlib with Java you
can then use:
import cryptlib.*;
class Cryptlib
{
public static void main( String[] args )
{
System.loadLibrary( "cl" );
// cryptlib library name
try
{
crypt.Init();
//Calls to cryptlib routines
crypt.End();
}
catch( CryptException e )
{
// cryptlib returned an error
e.printStackTrace();
}
}
};

All cryptlib functions are placed in the crypt class, so that standard cryptlib
functions like:
cryptSetAttribute( cryptContext, CRYPT_CTXINFO_KEYSIZE, 1024 / 8 );

become:
crypt.SetAttribute( cryptContext, crypt.CTXINFO_KEYSIZE, 1024 / 8 );

In general when calling cryptlib functions you can use Java strings wherever the
cryptlib interface requires a null-terminated C string, and Java byte arrays wherever
the cryptlib interface requires binary data. In addition as of JDK 1.4 there is a
nio.ByteBuffer c
l
a
s
st
h
a
tc
a
nbe“
d
i
r
e
c
t
”
,
whi
c
hpr
ov
i
de
samor
ee
f
f
i
c
i
e
n
t
a
l
t
e
r
na
t
i
v
et
os
t
a
nd
a
r
dby
t
ea
r
r
a
y
ss
i
nc
et
he
r
e
’
sn
one
e
dt
ope
r
f
or
ma
nyc
opy
i
ng
.
Instead of returning a status value like the native C interface, the JNI version throws
CryptException for error status returns, and returns integer or string data return
values as the return value:
value = crypt.GetAttribute( cryptContext, crypt.CTXINFO_ALGO );
stringValue = crypt.GetAttributeString( cryptContext,
crypt.CTXINFO_ALGO_NAME );

cryptlib Basics

Python
To build the Python interface to cryptlib, run python setup.py install to
build and install the python.c extension module. On a Unix platform you may need
to create a symlink from cl to the actual shared library before you do this. Once
y
ou’
v
ed
onet
h
i
sy
ouc
a
nus
e
:
from cryptlib_py import *
cryptInit()
# Calls to cryptlib routines
cryptEnd()

Tcl
To use cryptlib from Tcl, you use the Cryptkit extension. Cryptkit is a stubs-enabled
extension that can be used with any modern Tcl interpreter (at least, Tcl 8.4 or later).
Tobu
i
l
dCr
y
pt
k
i
ty
ou
’
l
lne
e
dac
opyo
fTc
lt
ha
tc
a
ni
nt
e
r
pr
e
tSt
a
r
k
i
t
s
,
e
i
t
he
rTc
l
k
i
t
,
the single file Tcl/Tk executable available from
http://www.equi4.com/pub/tk, or ActiveTcl from
http://www.activestate.com.You’
l
la
l
s
on
e
e
dt
odownl
oa
dt
heCr
i
t
c
l
Starkit from http://mini.net/sdarchive/critcl.kit, and make sure
that the current directory contains cryptlib.h and a copy of the cryptlib static library,
named libcl_$platfom.a, where $platform is the current platform name as provided
by the Critcl platform command. For example under x86 Linux the library would be
called libcl_Linux-x86.a. Then run the following Critcl command:
critcl -pkg cryptkit

This will leave you with a lib directory containing the information ready for use in
a
nyTc
la
p
pl
i
c
a
t
i
o
n.Onc
ey
o
u’
v
ed
onet
h
i
sy
ouc
a
nus
e
:
package require Cryptkit
cryptInit
# Calls to cryptlib routines
cryptEnd

Since Tcl objects already contain length infor
ma
t
i
on,
t
he
r
e
’
snone
e
dt
opa
s
sl
e
ng
t
h
parameters to cryptlib function calls. This applies for the AddCertExtension,
CheckSignature, CheckSignatureEx, CreateSignature, CreateSignatureEx, Decrypt,
Encrypt, ExportCert, ExportKey, ExportKeyEx, GetCertExtension, ImportKey,
PushData, and SetAttributeString functions.

Visual Basic
To use cryptlib from Visual Basic you would use:
' Add cryptlib.bas to your project
cryptInit
' Calls to cryptlib routines
cryptEnd

The Visual Basic interface to cryptlib is otherwise mostly identical to the standard
C/C++ one.

Return Codes
Every cryptlib function returns a status code to tell you whether it succeeded or
failed. If a function executes successfully, it returns CRYPT_OK. If it fails, it
returns one of the status valu
e
sde
t
a
i
l
e
di
n“
Error Handling”onp
a
g
e282. The
sample code used in this manual omits the checking of status values for clarity, but
when using cryptlib you should check return values, particularly for critical functions

Working with Object Attributes

such as any that perform active crypto operations like processing data in envelopes,
activating and using secure sessions, signing and checking certificates, and
encryption and signing in general.
The previous initialisation code, rewritten to include checking for returned status
values, is:
int status;
status = cryptInit();
if( status != CRYPT_OK )
/* cryptlib initialisation failed */;
/* Calls to cryptlib routines */
status = cryptEnd();
if( status != CRYPT_OK )
/* cryptlib shutdown failed */;

The C/C++ versions of cryptlib provide the cryptStatusOK() and
cryptStatusError() macros to make checking of these status values easier.
The C#, Java, and Python versions throw exceptions of type CryptException
instead of returning error codes. These objects contain both the status code and an
English error message. In C# the CryptException class has Status and Message
properties:
try
{
crypt.Init();
crypt.End();
}
catch( CryptException e )
{
int status = e.Status;
String message = e.Message;
}

In Java the CryptException class has getStatus() and getMessage()
accessors:
try
{
crypt.Init();
crypt.End();
}
catch( CryptException e )
{
int status = e.getStatus();
String message = e.getMessage();
}

In Python the exception value is a tuple containing the status code, then the message:
try:
cryptInit()
cryptEnd()
except CryptException, e:
status, message = e

Working with Object Attributes
All object attributes are read, written, and deleted using a common set of functions:
cryptGetAttribute/cryptGetAttributeString to get the value of an attribute,
cryptSetAttribute/cryptSetAttributeString to set the value of an attribute, and
cryptDeleteAttribute to delete an attribute. Attribute deletion is only valid for a
small subset of attributes for which it makes sense, for example you can delete the
validity date attribute from a certificate before the certificate is signed but not after
i
t
’
ss
i
g
ne
d,
a
n
dy
ouc
a
nn
e
v
e
rde
l
e
t
et
h
ea
l
g
or
i
t
h
m-type attribute from an encryption
context.

cryptlib Basics

cryptGetAttribute and cryptSetAttribute take as argument an integer value or a
pointer to a location to receive an integer value:
int keySize;
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_PUBLICKEY, cryptKey );
cryptGetAttribute( cryptContext, CRYPT_CTXINFO_KEYSIZE, &keySize );

cryptGetAttributeString and cryptSetAttributeString take as argument a pointer
to the data value to get or set and a length value or pointer to a location to receive the
length value:
char emailAddress[ 128 ]
int emailAddressLength;
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
"1234", 4 );
cryptGetAttributeString( cryptCertificate, CRYPT_CERTINFO_RFC822NAME,
emailAddress, &emailAddressLength );

This leads to a small problem: How do you know how big to make the buffer? The
answer is to use cryptGetAttributeString to tell you. If you pass in a null pointer
for the data value, the function will set the length value to the size of the data, but not
do anything else. You can then use code like:
char *emailAddress;
int emailAddressLength;
cryptGetAttributeString( cryptCertificate, CRYPT_CERTINFO_RFC822NAME,
NULL, &emailAddressLength );
emailAddress = malloc( emailAddressLength );
cryptGetAttributeString( cryptCertificate, CRYPT_CERTINFO_RFC822NAME,
emailAddress, &emailAddressLength );

to obtain the data value. In most cases this two-s
t
e
ppr
oc
e
s
si
s
n’
tne
c
e
s
s
a
r
y
,
t
he
standards that cryptlib conforms to generally place limits on the size of most
attributes so that cryptlib will never return more data than the fixed limit. For
example most strings in certificates are limited to a maximum length set by the
CRYPT_MAX_TEXTSIZE constant. More information on these sizes is given with
the descriptions of the different attributes.
The Visual Basic version is:
Dim emailAddress as String
Dim emailAddressLength as Integer
cryptGetAttributeString cryptCertificate, CRYPT_CERTINFO_RFC822NAME, _
0, emailAddressLength
emailAddress = String( emailAddressLength, vbNullChar )
cryptGetAttributeString cryptCertificate, CRYPT_CERTINFO_RFC822NAME, _
emailAddress, emailAddressLength

In Python you can use cryptGetAttributeString and cryptSetAttributeString as
usual, or use a shortcut syntax to make accessing attributes less verbose. The normal
syntax follows the C form but migrates the integer output values (the length from
cryptGetAttributeString or the output value from cryptGetAttribute) to return
v
a
l
ue
s
,
a
n
ddo
e
s
n
’
tr
e
q
ui
r
eal
e
ng
t
hf
orcryptSetAttributeString:
from array import *
emailAddress = array( 'c', 'x' * 128 )
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
"1234" )
emailAddressLength = cryptGetAttributeString( cryptCertificate,
CRYPT_CERTINFO_RFC822NAME, emailAddress )

The shortcut syntax allows you to get/set attributes as if they were integer and string
members of the object (without the CRYPT_ prefix):
cryptEnvelope.ENVINFO_PASSWORD = "1234"
emailAddress = cryptCertificate.CERTINFO_RFC822NAME

Working with Object Attributes

Just as with Python, C# and Java also migrate returned data to return values. In the
C# and Java cases the string functions take byte arrays or Strings. When passing a
byte array, you can optionally specify an offset following it for
cryptGetAttributeString and an offset and length following it for
cryptSetAttributeString. There is also a special version of
cryptGetAttributeString that returns Strings for convenience:
crypt.SetAttributeString( cryptEnvelope, crypt.ENVINFO_PASSWORD,
"1234" );
String emailAddress = crypt.GetAttributeString( cryptCertificate,
crypt.CERTINFO_RFC822NAME );

Finally, cryptDeleteAttribute lets you delete an attribut
ei
nt
hec
a
s
e
swhe
r
et
ha
t
’
s
possible:
cryptDeleteAttribute( cryptCertificate, CRYPT_CERTINFO_VALIDFROM );

Al
la
c
c
e
s
st
oob
j
e
c
t
sa
n
dob
j
e
c
ta
t
t
r
i
b
ut
e
si
se
nf
or
c
e
dbyc
r
y
pt
l
i
b’
ss
e
c
ur
i
t
yk
e
r
ne
l
.I
f
you try to access or manipulate an attribute in a manner th
a
ti
s
n’
ta
l
l
owe
d(
f
or
example by trying to read a write-only attribute, trying to assign a string value to a
nu
me
r
i
ca
t
t
r
i
bu
t
e
,
t
r
y
i
ngt
ode
l
e
t
ea
na
t
t
r
i
b
ut
et
ha
tc
a
n
’
tbede
l
e
t
e
d,
t
r
y
i
ngt
os
e
ta
certificate-specific attribute for an envelope, or some similar action) cryptlib will
r
e
t
ur
na
ne
r
r
orc
odet
ot
e
l
ly
o
ut
ha
tt
h
i
st
y
peo
fa
c
c
e
s
si
si
n
v
a
l
i
d.I
ft
h
e
r
e
’
sapr
ob
l
e
m
wi
t
ht
heo
bj
e
c
tt
h
a
ty
ou
’
r
et
r
y
i
ngt
oma
n
i
p
ul
a
t
e
,
c
r
y
pt
l
i
bwi
l
lr
e
t
ur
nCRYPT_ERROR_PARAM1 to tell you that the object handle parameter passed to the function
i
si
nv
a
l
i
d.I
ft
h
e
r
e
’
sapr
obl
e
m wi
t
ht
hea
t
t
r
i
bu
t
et
y
pe(
t
y
p
i
c
a
l
l
ybe
c
a
us
ei
t
’
si
nv
a
l
i
d
f
ort
hi
so
bj
e
c
tt
y
pe
)c
r
y
pt
l
i
bwi
l
lr
e
t
ur
nCRYPT_ERROR_
PARAM2.I
ft
h
e
r
e
’
sa
problem with the attribute value, cryptlib will return CRYPT_ERROR_PARAM3,
a
ndi
ft
he
r
e
’
sapr
o
bl
e
m wi
t
ht
hel
e
ng
t
h(
f
ort
h
ef
unc
t
i
onst
ha
tt
a
k
eal
e
ng
t
h
parameter) cryptlib will return CRYPT_ERROR_PARAM4. If you try to perform an
a
t
t
r
i
bu
t
ea
c
c
e
s
swhi
c
hi
sdi
s
a
l
l
owe
d(
r
e
a
d
i
nga
na
t
t
r
i
bu
t
et
h
a
tc
a
n
’
tber
e
a
d,
wr
i
t
i
ngt
o
or deleting a read-only attribute, or something similar) cryptlib will return
CRYPT_ERROR_PERMISSION.
Fi
na
l
l
y
,
i
fy
out
r
yt
oa
c
c
e
s
sa
na
t
t
r
i
bu
t
et
ha
tha
s
n
’
tbe
e
ni
n
i
t
i
a
l
i
s
e
dori
s
n
’
tpr
e
s
e
nt
,
cryptlib will return CRYPT_ERROR_NOTINITED or CRYPT_ERROR_NOTFOUND, the only real distinction between the two is that the former is typically
r
e
t
ur
ne
df
orf
i
x
e
da
t
t
r
i
bu
t
e
st
ha
th
a
v
e
n
’
th
a
dav
a
l
u
ea
s
s
i
g
ne
dt
ot
he
my
e
twhi
l
et
he
l
a
t
t
e
ri
sr
e
t
ur
n
e
df
orop
t
i
ona
la
t
t
r
i
bu
t
e
st
h
a
ta
r
e
n
’
tpr
e
s
e
n
ti
nt
heob
j
e
c
t
.

Attribute Types
Attribute values can be boolean or numeric values, cryptlib objects, time values, text
strings, or binary data:
Type

Description

Binary

A binary data string that can contain almost anything.

Boolean

Fl
a
g
st
ha
tc
a
nbes
e
tt
o‘
t
r
u
e
’(
a
nynonz
e
r
ov
a
l
u
e
)or‘
f
a
l
s
e
’(
a
zero value), and control whether a certain option or operation
is enabled or not. For example the CRYPT_CERTINFO_CA
attribute in a certificate controls whether a certificate is
marked as being a CA certificate or not. Note that cryptlib
usest
h
ev
a
l
ue1t
or
e
pr
e
s
e
nt‘
t
r
ue
’
,
s
omel
a
ng
ua
g
e
sma
y
represent this by the value –
1.

Numeric

A numeric constant such as an integer value or a bitflag. For
example the CRYPT_CTXINFO_KEYSIZE attribute specifies
the size of a key (in bytes) and the CRYPT_CERTINFO_CRLREASON attribute specifies a bitflag that indicates why a
CRL was issued.

Object

A handle to a cryptlib object. For example the CRYPT_CERTINFO_SUBJECTPUBLICKEYINFO attribute specifies
the public key to be added to a certificate.

cryptlib Basics

Type
String

Description
A text string that contains information such as a name,
message, email address, or URL. Strings are encoded using
the standard system local character set, usually ASCII or
latin-1 or UTF-8 (depending on the system), however under
Windows CE, which is a Unicode environment, these are
Unicode strings. In (very rare) cases where the standard
s
y
s
t
e
mc
h
a
r
a
c
t
e
rs
e
tdo
e
s
n
’
ts
upp
or
tt
hec
ha
r
a
c
t
e
r
sus
e
di
nt
he
string (for example when encoding Asian characters), the
characters used will be Unicode or widechars. For all intents
and purposes you can assume that all strings are encoded in
t
hes
t
a
nd
a
r
dc
h
a
r
a
c
t
e
rs
e
tt
h
a
ty
ou’
dnor
ma
l
l
yus
e
,
c
r
y
pt
l
i
b
will perform all conversions for you.
An example string attribute is CRYPT_CTXINFO_LABEL,
which contains a human-readable label used to identify private
keys.
The most frequently used text string components are those that
ma
k
eu
pac
e
r
t
i
f
i
c
a
t
e
’
sdi
s
t
i
n
g
ui
s
he
dna
me
,
whi
c
hi
de
n
t
i
f
i
e
s
the certificate owner. Most of these components are limited to
a maximum of 64 characters by the X.500 standard that covers
certificates and their components, and cryptlib provides the
CRYPT_MAX_TEXTSIZE constant for use with these
components (this value is also used for most other strings such
as key labels). Since this value is specified in characters rather
than bytes, Unicode strings can be several times as long as this
value when their length is expressed in bytes, depending on
which data type the system uses to represent Unicode
characters.

Time

The ANSI/ISO C standard time value containing the local time
expressed as seconds since 1970. This is a binary (rather than
numeric) field, with the data being the time value (in C and
C++ this is a time_t, usually a signed long integer).
Due to the vagaries of international time zones and daylight
savi
ng
st
i
mea
d
j
us
t
me
nt
s
,
i
ti
s
n’
tpos
s
i
bl
et
oa
c
c
ur
a
t
e
l
y
compare two local times from different time zones, or made
across a DST switch (consider for example a country
switching to DST, which has two 2am times while another
country only has one). Because of this ambiguity, times read
from objects such as certificates may appear to be out by an
hour or two.

Since most text strings have a fixed maximum length, you can use code like:
char commonName[ CRYPT_MAX_TEXTSIZE + 1 ];
int commonNameLength;
/* Retrieve the component and null-terminate it */
cryptGetAttributeString( cryptCertificate, CRYPT_CERTINFO_COMMONNAME,
commonName, &commonNameLength );
commonName[ commonNameLength ] = '\0';

to read the value, in this case the common name of a certificate owner.
Note the explicit addition of the terminating null character, since the text strings
r
e
t
ur
ne
da
r
e
n
’
tnu
l
l
-terminated.
In Visual Basic this is:
Dim commonName As String
Dim commonNameLength As Long

Working with Object Attributes

commonName = String( CRYPT_MAX_TEXTSIZE + 1 , vbNullChar )
cryptGetAttributeString cryptCertificate, CRYPT_CERTINFO_COMMONNAME, _
commonName, commonNameLength
commonName = Left( commonName, InStr( commonName, vbNullChar ) - 1 )

The description above assumes that the common name is expressed in a single-byte
character set. Since the values passed to cryptGetAttributeString and
cryptSetAttributeString are untyped, their length is given in bytes and not in
characters (which may not be byte-sized). For Unicode strings, you need to multiply
the size of the buffer by the size of a Unicode character on your system to get the
actual size to pass to the function, or divide by the size of a Unicode character to get
the number of characters returned. For example to perform the same operation as
above in a Unicode environmenty
ou
’
dus
e
:
wchar_t commonName[ CRYPT_MAX_TEXTSIZE + 1 ];
int commonNameLength;
/* Retrieve the component and null-terminate it */
cryptGetAttributeString( cryptCertificate, CRYPT_CERTINFO_COMMONNAME,
commonName, &commonNameLength );
commonName[ commonNameLength / sizeof( wchar_t ) ] = L'\0';

Attribute Lists and Attribute Groups
Several of the container object types (certificates, envelopes, and sessions) contain
large collections of attributes that you can process as a list rather than having to
access each attribute individually by type. The list of attributes is managed through
the use of an attribute cursor that cryptlib maintains for each container object. You
can set or move the cursor either to an absolute position in the list of attributes or
relative to the current position.
Object attributes are usually grouped into collections of related attributes. For
example an envelope object may contain a group of attributes consisting of a
signature, the key that generated the signature, associated signing attributes such as
the time and data type being signed, and even a timestamp on the signature itself.
Similarly, a session object may have a group of attributes consisting of a server name,
server port, and server key. So instead of a straight linear list of attributes:

Object

Attr

the attributes are arranged by group:

Object
Group

Attr

Group

Attr

Group

Attr

Some objects may contain multiple instances of attribute groups, each of which
contains its own set of attributes. For example an envelope could contain several
signature attribute groups, and each attribute group will contain its own signing keys,
certificates, signature information such as the signing time, and so on. One particular
instance of the abstract group/attribute view shown above would be:

cryptlib Basics

Envelope
Signature

Key

Signature

Key

Signature

Key

Sig.
Info

Timestamp

Sig.
Info

In order to navigate across attribute groups, and across attributes within a group,
cryptlib provides the attribute cursor functionality described in the section that
follows. As well as moving the cursor back and forth across attribute groups and
attributes within the group, you can also position it directly on a group or attribute. In
the common case where only a single attribute group is present, for example an
envelope object that contains a single signature or a session object that contains user
information for a single user:

Envelope

Signature
Key

Signature
Info

you can treat the attributes as a single flat list of attributes and not worry about the
hierarchical arrangement into groups.

Attribute Cursor Management
You can move the attribute cursor by setting an attribute that tells cryptlib where to
move it to. This attribute, either CRYPT_ATTRIBUTE_CURRENT_GROUP when
moving by attribute group or CRYPT_ATTRIBUTE_CURRENT when moving by
attribute within the current group, takes as value a cursor movement code that moves
the cursor either to an absolute position (the first or last group or attribute in the list)
or relative to its current position. The movement codes are:
Code

Description

CRYPT_CURSOR_FIRST Move the cursor to the first group or attribute.
CRYPT_CURSOR_LAST

Move the cursor to the last group or attribute.

CRYPT_CURSOR_NEXT

Move the cursor to the next group or attribute.

CRYPT_CURSOR_PREV

Move the cursor to the previous group or
attribute.

Moving by attribute group or attribute then works as follows:

Object
Group

Attr

Group

Attr

Group

Attr

CRYPT_ATTRIBUTE_CURRENT_GROUP
CRYPT_ATTRIBUTE_CURRENT

Working with Object Attributes

Note that CRYPT_ATTRIBUTE_CURRENT only moves the cursor within the
current group. Once you get to the start or end of the group, you need to use
CRYPT_ATTRIBUTE_CURRENT_GROUP to move on to the next one. Moving
the cursor from one group to another will reset the cursor position to the first attribute
wi
t
hi
nt
h
eg
r
oupi
fi
t
’
sb
e
e
np
r
e
v
i
ous
l
ymov
e
dt
os
o
meo
t
h
e
ra
t
t
r
i
b
ut
ewi
t
h
i
nt
he
group. For example to move the cursor to the start of the first attribute group in a
certificate, you would use:
cryptSetAttribute( cryptCertificate, CRYPT_ATTRIBUTE_CURRENT_GROUP,
CRYPT_CURSOR_FIRST );

To advance the cursor to the start of the next group, you would use:
cryptSetAttribute( cryptCertificate, CRYPT_ATTRIBUTE_CURRENT_GROUP,
CRYPT_CURSOR_NEXT );

To advance the cursor to the next attribute in the current group, you would use:
cryptSetAttribute( cryptCertificate, CRYPT_ATTRIBUTE_CURRENT,
CRYPT_CURSOR_NEXT );

In some cases multiple instances of the same attribute can be present, in which case
you can use a third level of cursor movement, handled via the CRYPT_ATTRIBUTE_CURRENT_INSTANCE attribute, and relative cursor movement to
step through the different instances of the attribute. Since the use of multi-valued
a
t
t
r
i
bu
t
e
si
sr
a
r
e
,
i
t
’
ss
a
f
et
oa
s
s
umeon
ev
a
l
uep
e
ra
t
t
r
i
bu
t
ei
nmos
tc
a
s
e
s
,
s
ot
h
a
t
stepping through multiple attribute instances is unnecessary.
Onc
ey
ou
’
v
es
e
tt
h
ec
ur
s
orp
o
s
i
t
i
on,
y
ouc
a
nwor
kwi
t
ht
hea
t
t
r
i
bu
t
eg
r
oupora
t
t
r
i
but
e
at that position in the usual manner. To obtain the group or attribute type at the
current position, you would use:
CRYPT_ATTRIBUTE_TYPE groupID;
cryptGetAttribute( cryptCertificate, CRYPT_ATTRIBUTE_CURRENT_GROUP,
&groupID );

This example obtains the attribute group type, to obtain the attribute type you would
substitute CRYPT_ATTRIBUTE_CURRENT in place of CRYPT_ATTRIBUTE_CURRENT_GROUP. Attribute accesses are relative to the currently selected group,
so for example if you move the cursor in an envelope to a signature attribute group
a
ndt
he
nr
e
a
dt
hes
i
g
na
t
ur
ek
e
y
/
c
e
r
t
i
f
i
c
a
t
eors
i
g
ni
ngt
i
me
,
i
t
’
l
lbet
heonef
ort
he
currently-selected signature attribute group. Since there can be multiple signatures
present in an envelope, you can use this mechanism to read the signing information
for each of the ones that are present.
To delete the attribute group at the current cursor position you would use:
cryptDeleteAttribute( cryptCertificate,
CRYPT_ATTRIBUTE_CURRENT_GROUP );

Deleting the attribute group at the cursor position will move the cursor to the start of
the group that follows the deleted one, or to the start of the previous group if the one
being deleted was the last one present. This means that you can delete every attribute
group simply by repeatedly deleting the one under the cursor.
The attribute cursor provides a convenient mechanism for stepping through every
attribute group and attribute which is present in an object. For example to iterate
through every attribute group you would use:
if( cryptSetAttribute( cryptCertificate,
CRYPT_ATTRIBUTE_CURRENT_GROUP, CRYPT_CURSOR_FIRST ) == CRYPT_OK )
do
{
CRYPT_ATTRIBUTE_TYPE groupID;
/* Get the ID of the attribute group under the cursor */
cryptGetAttribute( cryptCertificate,
CRYPT_ATTRIBUTE_CURRENT_GROUP, &groupID );

cryptlib Basics

/* Handle the attribute if required */
/* ... */
}
while( cryptSetAttribute( cryptCertificate,
CRYPT_ATTRIBUTE_CURRENT_GROUP, CRYPT_CURSOR_NEXT ) ==
CRYPT_OK );

The Visual Basic equivalent is:
Dim groupID As CRYPT_ATTRIBUTE_TYPE
If cryptSetAttribute( cryptCertificate, _
CRYPT_ATTRIBUTE_CURRENT_GROUP, CRYPT_CURSOR_FIRST ) == CRYPT_OK
Then
Do
' Get the type of the attribute group under the cursor
cryptGetAttribute cryptCertificate, CRYPT_ATTRIBUTE_CURRENT, _
groupID
' Handle the attribute if required
' ...
Loop While cryptSetAttribute( cryptCertificate, _
CRYPT_ATTRIBUTE_CURRENT_GROUP, CRYPT_CURSOR_NEXT ) == CRYPT_OK
End If

To extend this a stage further and iterate through every attribute in every group in the
object, you would use:
if( cryptSetAttribute( cryptCertificate,
CRYPT_ATTRIBUTE_CURRENT_GROUP, CRYPT_CURSOR_FIRST ) == CRYPT_OK )
do
{
do
{
CRYPT_ATTRIBUTE_TYPE attributeID;
/* Get the ID of the attribute under the cursor */
cryptGetAttribute( cryptCertificate, CRYPT_ATTRIBUTE_CURRENT,
&attributeID );
}
while( cryptSetAttribute( cryptCertificate,
CRYPT_ATTRIBUTE_CURRENT, CRYPT_CURSOR_NEXT ) == CRYPT_OK );
}
while( cryptSetAttribute( cryptCertificate,
CRYPT_ATTRIBUTE_CURRENT_GROUP, CRYPT_CURSOR_NEXT ) ==
CRYPT_OK );

Note that iterating attribute by attribute works within the current attribute group, but
a
sme
nt
i
on
e
de
a
r
l
i
e
rwon
’
tj
u
mpf
r
o
mo
neg
r
oupt
ot
hene
x
t— to do that, you need to
iterate by group.
You can also position the attribute cursor directly by telling cryptlib which attribute
you want to move the cursor to. For example to move the cursor in a certificate
object to the extended key usage attribute group you would use:
cryptSetAttribute( cryptCertificate, CRYPT_ATTRIBUTE_CURRENT_GROUP,
CRYPT_CERTINFO_EXTKEYUSAGE );

Usually the absolute cursor-positioning capability is only useful for certificate objects
where you know that certain attributes will be present, for envelope and session
obj
e
c
t
sy
oug
e
ne
r
a
l
l
yc
a
n
’
tt
e
l
lt
h
i
si
na
dv
a
nc
ea
n
dwi
l
ln
e
e
dt
ous
et
hea
t
t
r
i
bu
t
e
cursor to walk t
h
el
i
s
tt
os
e
ewha
t
’
st
he
r
e
.
Using this absolute cursor positioning in a variation of the attribute enumeration
operation given earlier, you can enumerate only the attributes of a single attribute
group (rather than all groups) by first selecting the group and then stepping through
t
hea
t
t
r
i
but
e
si
ni
t
.Fore
x
a
mpl
et
or
e
a
da
l
lo
fac
e
r
t
i
f
i
c
a
t
e
’
se
x
t
e
nde
dk
e
yus
a
g
et
y
pe
s
you would use:
if( cryptSetAttribute( cryptCertificate,
CRYPT_ATTRIBUTE_CURRENT_GROUP, CRYPT_CERTINFO_EXTKEYUSAGE ) ==
CRYPT_OK )
do
{
CRYPT_ATTRIBUTE_TYPE attributeID;

Object Security

/* Get the ID of the attribute under the cursor */
cryptGetAttribute( cryptCertificate, CRYPT_ATTRIBUTE_CURRENT,
&attributeID );
}
while( cryptSetAttribute( cryptCertificate,
CRYPT_ATTRIBUTE_CURRENT, CRYPT_CURSOR_NEXT ) == CRYPT_OK );

Object Security
Each cryptlib object has its own security settings that affect the way you can use the
object. You can set these attributes, identified by CRYPT_PROPERTY_name, after
you create an object to provide enhanced control over how it is used. For example on
a system that supports threads you can bind an object to an individual thread within a
process so that only the thread that owns the object can see it. For any other thread in
the process, the object handle is invalid.
You can get a
nds
e
ta
no
bj
e
c
t
’
spr
o
pe
r
t
i
e
sus
i
ngcryptGetAttribute and
cryptSetAttribute, passing as arguments the object whose property attribute you
want to change, the type of property attribute to change, and the attribute value or a
pointer to a location to recei
v
et
hea
t
t
r
i
but
e
’
sv
a
l
ue
.Theo
bj
e
c
tpr
o
pe
r
t
ya
t
t
r
i
bu
t
e
s
that you can get or set are:
Property/Description
Type
CRYPT_PROPERTY_FORWARDCOUNT
Numeric
The number of times an object can be forwarded (that is, the number of
times the ownership of the object c
a
nb
ec
ha
ng
e
d)
.Ea
c
ht
i
met
heo
bj
e
c
t
’
s
ownership is changed, the forwarding count decreases by one; once it
r
e
a
c
he
sz
e
r
o,
t
heobj
e
c
tc
a
n
’
tbef
or
wa
r
de
da
nyf
ur
t
he
r
.Fore
x
a
mpl
ei
fy
o
u
s
e
tt
h
i
sa
t
t
r
i
bu
t
e
’
sv
a
l
uet
o1t
he
ny
o
uc
a
nf
or
wa
r
dt
heo
bj
e
c
tt
oa
nother
t
hr
e
a
d,
bu
tt
ha
tt
hr
e
a
dc
a
n
’
tf
or
wa
r
di
tf
ur
t
h
e
r
.
After you set this attribute (and any other security-related attributes), you
should set the CRYPT_PROPERTY_LOCKED attribute to ensure that it
c
a
n
’
tb
ec
ha
ng
e
dl
a
t
e
r
.
CRYPT_PROPERTY_HIGHSECURITY
Boolean
This is a composite value that sets all general security-related attributes to
their highest security setting. Setting this value will make an object owned,
non-exportable (if appropriate), non-forwardable, and locked. Since this is a
composite valuer
e
pr
e
s
e
n
t
i
nganu
mb
e
rofs
e
pa
r
a
t
ea
t
t
r
i
b
ut
e
s
,
i
t
sv
a
l
uec
a
n’
t
be read or unset after being set.
CRYPT_PROPERTY_LOCKED
Boolean
Locks the security-related object attributes so that they can no longer be
c
ha
ng
e
d.
Yous
houl
ds
e
tt
hi
sa
t
t
r
i
bu
t
eo
nc
ey
ou
’
v
eset other security-related
attributes such as CRYPT_PROPERTY_FORWARDCOUNT.
This attribute is a write-on
c
ea
t
t
r
i
bu
t
e
,
on
c
ey
ou
’
v
es
e
ti
tc
a
n’
tber
e
s
e
t
.
CRYPT_PROPERTY_NONEXPORTABLE
Boolean
Whether a key in an encryption action object can be exported from the object
in encrypted form. Normally only session keys can be exported, and only in
encrypted form, however in some cases private keys are also exported in
encrypted form when they can are saved to a keyset. By setting this attribute
you can make them non-exportable in any form (some keys, such as those
held in crypto devices, are non-exportable by default).
This attribute is a write-on
c
ea
t
t
r
i
bu
t
e
,
on
c
ey
ou
’
v
es
e
ti
tc
a
n’
tber
e
s
e
t
.
CRYPT_PROPERTY_OWNER
Numeric
The identity of the thread that owns t
heo
bj
e
c
t
.Thet
hr
e
a
d’
si
de
n
t
i
t
yi
s
specified using a value that depends on the operating system, but is usually a
thread handle or thread ID. For example under Windows 95/98/ME,
NT/2000/XP, and Windows CE the thread ID is the value returned by the
GetCurrentThreadID function, which returns a system-wide unique

cryptlib Basics

Property/Description
handle for the current thread.

Type

You can also pass in a value of CRYPT_UNUSED, which unbinds the
object from the thread and makes it accessible to all threads in the process.
CRYPT_PROPERTY_USAGECOUNT
Numeric
The number of times an action object can be used before it deletes itself and
becomes unusable. Every time an action object is used (for example when a
signature encryption object is used to create a signature), its usage count is
decremented;o
nc
et
heus
a
g
ec
ou
ntr
e
a
c
he
sz
e
r
o,
t
heobj
e
c
tc
a
n’
tbeus
e
dt
o
perform any further actions (although you can still perform non-action
operations such as reading its attributes).
This attribute is useful when you want to restrict the number of times an
object can be used by other code. For example, before you change the
ownership of a signature object to allow it to be used by another thread, you
woul
ds
e
tt
h
eus
a
g
ec
oun
tt
o1t
oe
ns
ur
et
ha
ti
tc
a
n’
tbeus
e
dt
os
i
g
na
r
bi
t
r
a
r
y
numbers of messages or transactions. This eliminates a troubling security
problem with objects such as smart cards where, once a user has
authenticated themselves to the card, the software can ask the card to sign
arbitrary numbers of (unauthorised) transactions alongside the authorised
ones.
This attribute is a write-on
c
ea
t
t
r
i
bu
t
e
,
on
c
ey
ou
’
v
es
e
ti
tc
a
n’
tber
e
s
e
t
.
For example to create a triple DES encryption context in one thread and transfer
ownership of the context to another thread you would use:
CRYPT_CONTEXT cryptContext;
/* Create a context and claim it for exclusive use */
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_3DES );
cryptSetAttribute( cryptContext, CRYPT_PROPERTY_OWNER, threadID );
/* Generate a key into the context */
cryptGenerateKey( cryptContext );
/* Transfer ownership to another thread */
cryptSetAttribute( cryptContext, CRYPT_PROPERTY_OWNER,
otherThreadID );

The other thread now has exclusive ownership of the context containing the loaded
key. If you wanted to prevent the other thread from transferring the context further,
you would also have to set the CRYPT_PROPERTY_FORWARDCOUNT property
to 1 (to allow you to transfer it) and then set the CRYPT_PROPERTY_LOCKED
a
t
t
r
i
bu
t
e(
t
opr
e
v
e
ntt
heo
t
he
rt
hr
e
a
df
r
o
mc
ha
ng
i
ngt
hea
t
t
r
i
but
e
sy
ou
’
v
es
e
t
)
.
Not
et
h
a
ti
nt
h
ea
b
ov
ec
od
et
h
eobj
e
c
ti
sc
l
a
i
me
da
ss
o
ona
si
t
’
sc
r
e
a
t
e
d(
a
n
dbe
f
or
e
a
nys
e
ns
i
t
i
v
eda
t
ai
sl
o
a
de
di
n
t
oi
t
)t
oe
ns
ur
et
h
a
ta
n
ot
he
rt
h
r
e
a
di
s
n
’
tg
i
v
e
nac
ha
nc
e
to use it when it contains sensitive data. The use of this type of object binding is
recommended when working with sensitive information under Windows 95/98/ME,
Windows NT/2000/XP, and Windows CE, since the Win32 API provides several
security holes whereby any process in the system may interfere with resources owned
by any other process in the system. The checking for object ownership which is
performed typically adds a few microseconds to each call, so in extremely timecritical applications you may want to avoid binding an object to a thread. On the
other hand for valuable resources such as private keys, you should always consider
binding them to a thread, since the small overhead becomes insignificant compared to
the cost of the public-key operation.
Although the example shown above is for encryption contexts, the same applies to
other types of objects such as keysets and envelopes (although in that case the
i
n
f
or
ma
t
i
o
nt
h
e
yc
on
t
a
i
ni
s
n
’
ta
ss
e
ns
i
t
i
v
ea
si
ti
sf
ore
nc
r
y
p
t
i
o
nc
o
nt
e
x
t
s
)
.For
container objects that can themselves contain objects (for example keysets), if the
container is bound to a thread then any objects that are retrieved from it are also
bou
ndt
ot
het
hr
e
a
d.Fore
x
a
mp
l
ei
fy
ou
’
r
er
e
a
d
i
ngapr
i
v
a
t
ek
e
yf
r
om ak
e
y
s
e
t
,
y
ou

Role-based Access Control

should bind the keyset to the current thread after you open it (but before you read any
keys) so that any keys read from it will also automatically be bound to the current
thread. In addition if a key which is used to generate another key (for example the
key that imports a session key) is bound, then the resulting generated key will also be
bound.
On non-multithreaded systems, CRYPT_PROPERTY_OWNER and CRYPT_PROPERTY_FORWARDCOUNT have no effect, so you can include them in your
code for any type of system.

Role-based Access Control
cryptlib implements a form of access control called role-based access control or
RBACi
nwhi
c
ho
pe
r
a
t
i
o
nss
p
e
c
i
f
i
ct
oac
e
r
t
a
i
nus
e
rr
ol
ec
a
n’
tbep
e
r
f
or
me
dbyaus
e
r
acting in a different role. For example in many organisations a cheque can only be
issued by an accountant and can only be signed by a manager, which prevents a
dishonest accountant or manager from both issuing a cheque to themselves and then
signing it as well. This security measure is referred to as separation of duty, in which
it takes at least two people to perform a critical operation. Similarly, cryptlib uses
RBAC to enforce a strong separation of duty between various roles, providing the
same effect as the corporate accounting controls that prevent an individual from
writing themselves cheques.
cryptlib recognises a variety of user types or roles. The default user type has access
t
omos
toft
hes
t
a
n
da
r
df
un
c
t
i
onsi
nc
r
y
pt
l
i
bb
utc
a
n
’
tpe
r
f
o
r
m CAma
na
g
e
me
n
t
operations or specialised administrative functions that are used to manage certain
a
s
pe
c
t
sofc
r
y
pt
l
i
b
’
sope
r
a
t
i
o
n.Whe
ny
ouus
ec
r
y
pt
l
i
bi
nt
her
ol
e of a standard user,
it functions as a normal crypto/security toolkit.
I
na
dd
i
t
i
ont
ot
hes
t
a
nd
a
r
dus
e
rr
ol
e
,
i
t
’
sa
l
s
opos
s
i
bl
et
ous
ec
r
y
pt
l
i
bi
nt
her
o
l
eo
fa
security officer (SO), a special administrative user who can create new users and
perform othe
ra
d
mi
ni
s
t
r
a
t
i
v
ef
u
nc
t
i
o
nsbu
tc
a
n’
tpe
r
f
or
mg
e
ne
r
a
lc
r
y
pt
oo
pe
r
a
t
i
o
ns
like a normal user. This provides a clear separation of duty between administrative
and end-user functionality.
Another role recognised by cryptlib is that of a certification authority that can make
us
eo
fc
r
y
pt
l
i
b
’
sc
e
r
t
i
f
i
c
a
t
ema
na
g
e
me
n
tf
un
c
t
i
on
a
l
i
t
ybutc
a
n’
tpe
r
f
or
mg
e
ne
r
a
l
administrative functions or non-CA-related crypto operations. Again, this provides a
clear separation of duty between the role of the CA and the role of a general user or
SO.

Managing User Roles
When a cryptlib object is created, it is associated with a user role which is specified at
c
r
e
a
t
i
ont
i
mea
n
dc
a
n’
tbea
c
c
e
s
s
e
dbya
nyot
he
rus
e
r
.Fore
x
a
mp
l
ei
fapr
i
v
a
t
ek
e
yi
s
created by a CA for signing certificates,
i
tc
a
n
’
tb
ea
c
c
e
s
s
e
dbyanor
ma
lus
e
rbe
c
a
us
e
i
t
’
son
l
yv
i
s
i
bl
et
ot
h
eus
e
ra
c
t
i
ngi
nt
her
o
l
eo
ft
h
eCA.Si
mi
l
a
r
l
y
,
a
l
t
ho
ug
hanor
ma
l
user may be able to see a certificate store, only a CA user can use it for the purpose of
issuing certificates. The use of RBAC therefore protects objects from misuse by
unauthorised users.
The identity of the user who owns the object is specified as a parameter for the object
creation function. Throughout the rest of the cryptlib documentation this parameter is
denoted through the use of the cryptUser variable. Usually this parameter is set to
CRYPT_UNUSED to indicate that the user is acting in the role of a normal user and
doe
s
n’
tc
a
r
ea
bo
utr
ol
e
-ba
s
e
dc
on
t
r
ol
s
.Thi
si
st
y
p
i
c
a
l
l
yus
e
di
nc
a
s
e
swhe
r
et
h
e
r
e
’
s
only one cryptlib user, for example where cryptlib is running on an end-user PC (e.g.
Windows, Macintosh) or a multi-user system that provides each user with the illusion
of being on a single-us
e
rma
c
hi
n
e(
e
.
g
.
Uni
x
)
.I
na
l
mos
ta
l
lc
a
s
e
st
h
e
r
e
f
or
ey
ou
’
d
pass in CRYPT_UNUSED as the user identity parameter.
In a few specialised cases where the user is acting in a role other than that of a normal
us
e
rt
hede
f
a
u
l
tus
e
rr
o
l
ei
s
n
’
te
no
ug
h.Fore
x
a
mpl
ewhe
ny
ouwa
ntt
oa
c
c
e
s
saCA
c
e
r
t
i
f
i
c
a
t
es
t
or
ey
ouc
a
n
’
tus
et
her
ol
eof a normal user to perform the access because

cryptlib Basics

only a CA can manipulate a certificate store. This prevents a normal user from
issuing themselves certificates in the name of the CA and assorted other mischief
s
uc
ha
sr
e
v
ok
i
nga
not
he
rus
e
r
’
sc
e
r
t
i
f
i
c
a
t
e
.
When acting in a different role than that of the default, normal user, you specify the
i
de
nt
i
t
yoft
heus
e
rwhos
er
ol
ey
ou’
r
ea
c
t
i
ngi
na
sapa
r
a
me
t
e
roft
heo
bj
e
c
tc
r
e
a
t
i
on
function as before, this time passing in the handle of the user identity instead of
CRYPT_UNUSED. When the object is created, it is associated with the given user
and role instead of the default user. The creation and use of user objects is covered in
the next section.

Creating and Destroying Users and Roles
The following section is provided purely for forwards compatibility with functionality
included in future versions of cryptlib. For the current version of cryptlib the user
identity parameter should always be CRYPT_UNUSED since user object
mana
ge
me
n
ti
s
n’
te
na
bl
e
di
nt
hi
sv
e
r
s
i
o
n.
User objects can only be created and destroyed by an SO user, this being one of the
special administrative functions mentioned earlier that can only be performed by an
SO. You create a user object with cryptCreateUser, specifying the identity of the
SO who is creating the user object, type of user role that the object is associated with,
the name of the user, and a password that protects access to the user object:
CRYPT_USER cryptUser;
cryptCreateUser( &cryptUser, cryptSO, type, name, password );

The available user types or roles are:
Role

Description

CRYPT_USER_CA

A certification authority who can perform CA
ma
na
g
e
me
n
tf
unc
t
i
onsb
utc
a
n’
tpe
r
f
or
m
general-purpose crypto operations.

CRYPT_USER_NORMAL A standard cryptlib user.
CRYPT_USER_SO

A security officer who can perform
administrative functions such as creating or
de
l
e
t
i
ngus
e
r
sbutwhoc
a
n’
tp
e
r
f
or
ma
nyot
he
r
type of operation.

Fore
x
a
mpl
et
oc
r
e
a
t
eanor
ma
lus
e
ro
bj
e
c
tf
or“
J
oh
nDoe
”wi
t
ht
hepa
s
s
wor
d
“
pa
s
s
wor
d”a
ndaCAus
e
rob
j
e
c
tf
or“
J
o
hn
’
sCe
r
t
i
f
i
c
a
t
eAut
h
or
i
t
y
”wi
t
ht
h
e
pa
s
s
wor
d“
CApa
s
s
wor
d”y
o
uwoul
dus
e
:
CRYPT_USER cryptUser, cryptCAUser;
cryptCreateUser( &cryptUser, cryptSO, CRYPT_USER_NORMAL, "John Doe",
"password" );
cryptCreateUser( &cryptUser, cryptSO, CRYPT_USER_CA, "John's
Certification Authority", "CA password" );

Onc
eaus
e
ro
bj
e
c
ti
sc
r
e
a
t
e
di
tc
a
n
’
tbeus
e
di
mme
d
i
a
t
e
l
yb
e
c
a
us
ei
t
’
ss
t
i
l
lu
nde
rt
he
no
mi
na
lc
on
t
r
oloft
heSOwhoc
r
e
a
t
e
di
tr
a
t
he
rt
ha
nt
heus
e
ri
t
’
si
nt
e
nd
e
df
or
.Be
f
or
e
it can be used, control over the object needs t
ob
eha
nd
e
do
v
e
rt
ot
heus
e
rt
ha
ti
t
’
s
intended for. After the object is created by the SO, it is said to be in the SO initialised
s
t
a
t
e
.Anya
t
t
e
mptt
ous
ea
nobj
e
c
twhe
ni
t
’
si
nt
h
eSOi
ni
t
i
a
l
i
s
e
ds
t
a
t
ewi
l
lr
e
s
ul
ti
n
cryptlib returning CRYPT_ERROR_NOTINITED.
To move the newly-c
r
e
a
t
e
do
bj
e
c
ti
n
t
oaus
a
b
l
es
t
a
t
e
,
i
t
’
sn
e
c
e
s
s
a
r
yt
oc
h
a
ng
ei
t
s
password from the initial one set by the SO to one chosen by the user. Once this
change occurs, the object is moved into the user initialised state and is ready for use.
You can change the password from the initial one set by the SO to a user-chosen one
with cryptChangePassword:
cryptChangePassword( cryptUser, oldPassword, newPassword );

Miscellaneous Issues

When the password has been changed from the one set by the SO to the one chosen
by the user, the user object is ready for use.
User objects can also be destroyed by the SO who created them:
cryptDeleteUser( cryptUser, "John Doe" );

Miscellaneous Issues
This section contains additional information that may be useful when working with
cryptlib.

Multi-threaded cryptlib Operation
cryptlib is re-entrant and completely thread-safe (the threading model used is
sometimes known as the free-threading model), allowing it to be used with
multithreaded applications in systems that support threading. When you use cryptlib
in a multithreaded application, you should take standard precautions to ensure that a
s
i
ng
l
er
e
s
our
c
es
ha
r
e
da
c
r
os
smu
l
t
i
pl
et
hr
e
a
dsd
oe
s
n
’
tbe
c
o
meab
ot
t
l
e
ne
c
k
,
wi
t
ha
l
l
threads being forced to wait on a single shared object. Fore
x
a
mp
l
ei
fy
ou
’
r
e
timestamping large numbers of messages then creating a single timestamping session
obj
e
c
t(
s
e
e“
Secure Sessions”onpa
g
e105) and using that for all timestamping
services will result in all of the operations waiting on a single session object, which
can often take several seconds to turn around a transaction with a remote server. A
better option in this case would be to create a pool of timestamping session objects
and use the next free one when required.
A similar situation occurs with other objects such as crypto devices and keysets that
may be shared across multiple threads. For example cryptlib provides a facility for
automatically fetching a decryption key from a keyset in order to decrypt data (see
“
Public-Key Encrypted Enveloping”onpa
g
e75). This is convenient when handling
one or two messages since cryptlib will automatically take care of all of the
processing for you, howe
v
e
ri
fy
ou
’
r
epr
oc
e
s
s
i
ngl
a
r
g
enumbe
r
sofme
s
s
a
g
e
st
he
nt
he
need to read and decrypt the same private key for each message is very inefficient,
not only in terms of CPU overhead but also because every message must wait for
each of the previous messages to be processed before it gets its turn at the keyset.
A better alternative in this case is to read the private key from the keyset just once
and then use it with each envelope, rather than having each envelope read and decrypt
the key itself. Extending t
hi
se
v
e
nf
ur
t
he
r
,
i
fy
ou
’
r
eus
i
ngav
e
r
yl
a
r
g
epr
i
v
a
t
ek
e
y
,
running on a slower processor, or processing large numbers of transactions, you may
want to instantiate multiple copies of the private-key object to avoid the single private
key again becoming a bottleneck.
In general most private-key operations, when performed on modern processors, are
f
a
i
r
l
yq
ui
c
k
,
s
ot
h
e
r
e
’
sn
on
e
e
dt
oc
r
e
a
t
el
a
r
g
enu
mbe
r
so
fp
r
i
v
a
t
e
-key objects for fear
of them becoming a bottleneck. In this case the primary bottleneck is the need to read
and decrypt the key for each message processed. However, when run on a multipleCPU system, you should make some attempt to match objects to CPUs — creating a
single private-key object on a four-CPU system guarantees that the overall
performance will be no better than that of a single-CPU system, since the single
object instance acts as a mutex that can only be acquired by one CPU at a time.
Standard programming practice for efficient utilisation of resources on multiprocessor
systems applies to cryptlib just as it does for other applications. Creating a pool of
objects that can be picked up and used as required would be one standard approach to
this problem. Some operating systems provide special support for this with functions
for thread pooling management. For example, Windows 2000 and XP provide the
QueueUserWorkItem function, which submits a work item to a thread pool for
execution when the next thread becomes available.
In order to protect against potential deadlocks when multiple threads are waiting on a
single object, cryptlib includes a watchdog timer that triggers after a certain amount
of time has been spent waiting on the object. Once this occurs, cryptlib will return
CRYPT_ERROR_TIMEOUT to indicate that an object is still in use after waiting for
it to become available. If you experience timeouts of this kind, you should check

cryptlib Basics

your code to see if there are any bottlenecks due to a single object with a long
response time being shared by several fast-response-time objects. Note that timeouts
are also possible with normal cryptlib object use, for example when communicating
data over a slow or stalled network link, so a CRYPT_ERROR_TIMEOUT status
doe
s
n’
ta
u
t
o
ma
t
i
c
a
l
l
yme
a
nt
ha
tt
hewa
t
c
hd
ogt
i
me
rs
i
g
na
l
l
e
dapr
ob
l
e
m.
To help diagnose situations of this kind, the debug build of cryptlib will display on
the console output an indication that it waited on a particular object, along with the
object type that it waited on. You can use this information to identify potential
bottlenecks in your application.
Linux has a somewhat unusual threading implementation built around the clone()
system call that can lead to unexpected behaviour with some kernel and/or glibc
versions. Two common symptoms of glibc/kernel threading problems are phantom
processes (which are actually glibc-internal threads created via clone()) being left
be
h
i
n
dwhe
ny
o
ua
p
pl
i
c
a
t
i
o
ne
x
i
t
s
,
a
ndc
r
y
pt
l
i
b’
si
nt
e
r
na
lc
ons
i
s
t
e
n
c
y
-checking
throwing an exception in the debug build when it detects an problem with threading.
If you run into either of these situations, you can try different glibc and/or kernel
versions to find a combination that works. Searching Internet newsgroups will
provide a wealth of information and advice on problems with glibc and Linux
threads.

Interaction with External Events
Internally, cryptlib consists of a number of security-related objects, some of which
can be controlled by the user through handles to the objects. These objects may also
be acted on by external forces such as information coming from encryption and
system hardware, which will result in a message related to the external action being
sent to any affected cryptlib objects. An example of such an event is the withdrawal
of a smart card from a card reader, which would result in a card removal message
being sent to all cryptlib objects that were created using information stored on the
card. This can affect quite a number of objects.
Typically, the affected cryptlib objects will destroy any sensitive information held in
memory and disable themselves from further use. If you try to use any of the objects,
cryptlib will return CRYPT_ERROR_SIGNALLED to indicate that an external event
has caused a change in the state of the object.
After an object has entered the signalled state, the only remaining operation you can
perform with the object is to destroy it using the appropriate function.

Security Usability Fundamentals

Security and Usability
Ani
mpor
t
a
ntc
ons
i
de
r
a
t
i
onwhe
ny
o
u’
r
eb
ui
l
d
i
nga
na
pp
l
i
c
a
t
i
oni
st
heus
a
bi
l
i
t
yo
ft
he
s
e
c
ur
i
t
yf
e
a
t
ur
e
st
h
a
ty
ou
’
l
lb
ee
mpl
oy
i
ng
.Se
c
ur
i
t
yexperts frequently lament that
security has been bolted onto applications as an afterthought, however the security
community has committed the exact same sin in reverse, placing usability
considerations in second place behind security, if they were considered at all. As a
r
e
s
ul
t
,
wes
pe
n
tt
he1
99
0sbu
i
l
di
nga
ndde
p
l
oy
i
ngs
e
c
ur
i
t
yt
ha
twa
s
n
’
tr
e
a
l
l
yne
e
de
d,
a
ndnowt
h
a
twe
’
r
ee
x
p
e
r
i
e
n
c
i
ngwi
de
s
pr
e
a
dp
hi
s
hi
nga
t
t
a
c
k
swi
t
hv
i
r
us
e
sa
ndwor
ms
running rampant and the security is a
c
t
ua
l
l
yne
e
de
d,
we
’
r
ef
i
ndi
ngt
hat no-one can
use it.
This section provides guidance on security usability principles for your application,
covering everything from the initial design stages through to final pre-release
usability testing.

Security Usability Fundamentals
To understand thepr
ob
l
e
m,
i
t
’
sne
c
e
s
s
a
r
yt
og
oba
c
kt
ot
heba
s
i
cde
f
i
n
i
t
i
o
no
f
functionality and security. An application exhibits functionality if things that are
supposed to happen, do happen. Similarly, an application exhibits security if things
t
ha
ta
r
e
n
’
ts
u
pp
os
e
dt
oh
a
p
pe
n,
don
’
tha
ppe
n.Se
c
ur
i
t
yde
v
e
l
o
pe
r
sa
r
ei
n
t
e
r
e
s
t
e
di
n
the latter (marketers tend to be more interested in the former).
Ens
ur
i
ngt
ha
tt
hi
ng
st
ha
ta
r
e
n
’
ts
u
pp
os
e
dt
oh
a
p
pe
ndo
n’
th
a
pp
e
nc
a
nbea
ppr
oa
c
he
d
from both the application side and from the user side. From the application side, the
application should behave in a safe manner, defaulting to behaviour that protects the
user from harm. From the user side, the application should act in a manner in which
t
heus
e
r
’
se
x
pe
c
t
a
t
i
o
no
fas
a
f
eus
e
re
x
perience are met. The following sections
provide various guidelines on ways of achieving this goal.

Theoretical vs. Effective Security
There can be a significant difference between theoretical and effective security. In
theory, we should all be using smart cards and PKI for authentication. However,
t
he
s
eme
a
s
ur
e
sa
r
es
op
a
i
n
f
ult
ode
pl
oya
ndus
et
h
a
tt
he
y
’
r
ea
l
mos
tn
e
v
e
re
mp
l
oy
e
d,
making them far less effectively secure than basic usernames and passwords. Security
experts tend to focus exclusively on the measures that provide the best (theoretical)
security, however sometimes these measures provide very little effective security
because they end up being misused, or turned off, or bypassed.
Al
oto
ft
h
i
sc
o
me
sf
r
o
ms
e
c
u
r
i
t
y
’
sor
i
g
i
ni
nt
heg
ov
e
r
nme
n
tc
r
y
pto community. For
cryptographers, the security must be perfect — anything less than perfect security
would be inconceivable. In the past this has lead to all-or-nothing attempts at
i
mpl
a
nt
i
ngs
e
c
ur
i
t
ys
uc
ha
st
h
eUSDoD’
s“
C2i
n‘
92
”i
n
i
t
i
a
t
i
v
e(
amor
emodern form
oft
hi
smi
g
htbe“
PKIorBus
t
”
)
,
whi
c
hr
e
s
ul
t
e
di
nn
ot
hi
ngi
n’
9
2ora
ta
nyot
h
e
rda
t
e
.
Ass
e
c
ur
i
t
yg
odBut
l
e
rLa
mps
onh
a
sobs
e
r
v
e
d,
“
Theb
e
s
ti
st
hee
ne
myoft
heg
ood”
— a product that offers generally effective (but less than perfect) security will be
panned by security experts, who would prefer to see a theoretically perfect, but
pr
a
c
t
i
c
a
l
l
yuna
t
t
a
i
n
a
bl
eorun
us
a
b
l
epr
o
du
c
ti
ns
t
e
a
d.Don’
tbea
f
r
a
i
dt
ous
es
i
mpl
e
bute
f
f
e
c
t
i
v
es
e
c
ur
i
t
yme
a
s
ur
e
s
,
e
v
e
ni
ft
h
e
y
’
r
en
ott
het
he
or
e
t
i
c
a
lbe
s
tt
h
a
t
’
s
available.
You should however be careful not to use effective (as opposed to theoretically
perfect) security as an excuse for weak security. Using weak or homebrew
encryption mechanisms when proven, industry-s
t
a
n
da
r
don
e
sa
r
ea
v
a
i
l
a
bl
ei
s
n’
t
effective sec
ur
i
t
y
,
i
t
’
swe
a
ks
e
c
ur
i
t
y
.Us
i
nga
ppr
opr
i
a
t
e
l
ys
e
c
ur
e
dpa
s
s
wor
dsi
ns
t
e
a
d
of PKI is justifiable, effective security.

User Conditioning
I
t
’
so
f
t
e
nc
l
a
i
me
dt
ha
tt
h
ewa
yt
oa
ddr
e
s
ss
e
c
ur
i
t
yi
s
s
ue
si
st
hr
o
ug
hbe
t
t
e
rus
e
r
e
du
c
a
t
i
o
n.Asi
tt
ur
nsou
t
,
we
’
r
ebe
e
n educating users for years about security,
a
l
t
ho
ug
hunf
or
t
u
na
t
e
l
yi
t
’
se
n
t
i
r
e
l
yt
h
ewr
ongk
i
ndo
fe
d
uc
a
t
i
on.“
Co
nd
i
t
i
o
ni
ng
”

Security and Usability
mi
g
htbeab
e
t
t
e
rt
e
r
mf
orwh
a
t
’
sbe
e
nha
ppe
ni
ng
.Whe
ne
v
e
rus
e
r
sg
oonl
i
n
e
,
t
he
y
’
r
e
subjected to a constant barrage of error messages, warnings, and popups: DNS errors,
transient network outages, ASP errors, Javascript problems, missing plugins,
temporary server outages, incorrect certificates, and a whole host of other issues. The
f
i
xf
ora
l
lo
ft
he
s
epr
o
bl
e
msi
st
oc
l
i
c
k“
OK”or“
Ca
nc
e
l
”a
sa
ppr
o
pr
i
a
t
ei
ft
he
s
e
opt
i
o
nsa
r
ea
v
a
i
l
a
bl
e
,
ort
ot
r
ya
g
a
i
nl
a
t
e
ri
ft
he
ya
r
e
n
’
t
.An
yus
e
rwhoha
sus
e
dt
he
Internet for any amount of time has become deeply conditioned to applying this
solution to all Internet/network problems.
When certificates are used to secure network communications, a genuine attack
displays identical symptoms to the dozens of other transient problems that users have
be
e
nc
o
ndi
t
i
one
dt
oi
g
nor
e
.I
not
he
rwor
dswe
’
r
et
r
y
i
ngt
ode
t
e
c
ta
t
t
a
c
k
sus
i
ng
certificates when an astronomical false positive rate (endless dialogs and warnings
crying wolf) has conditioned users to ignore any warnings coming from the certificate
layer. In order to be effective, the false positive rate must be close to zero to have
any impact on the user.
An example of this effect of user conditioning was revealed in a recent case where a
large bank accidentally used an invalid certificate for its online banking services. An
analysis of site access logs indicated that of the approximately 300 users who
accessed the site, just one single user turned back when faced with the invalid
certificate. Although privacy concerns prevented a full-s
c
a
l
es
t
udyo
fus
e
r
s
’r
e
a
c
t
i
o
ns
from being carried out, an informal survey indicated that users were treating this as
yet another transient problem to be sidestepped. For example one user commented
t
ha
t“
Hot
ma
i
ld
oe
st
hi
sal
ot
,
y
ouj
us
twa
i
ta
whi
l
ea
ndi
twor
k
sa
g
a
i
n”
.I
nas
i
mi
l
a
r
case, this time with a government site used to pay multi-thousand dollar property
taxes, users ignored a large red cross and warning text that the certificate was invalid
for over two months before a security expert notified that site administrators that they
needed to fix the certificate.
These real-life examples, taken from a major banking site and a large government
site, indicate that certificates, when deployed into a high-false-positive environment,
are completely ineffective in performing their intended task of preventing man-in-themiddle attacks.
This user conditioning presents a somewhat difficult problem. Probably the best
s
ol
u
t
i
onf
ort
h
epur
pos
e
so
fs
e
c
ur
i
ngne
t
wor
ks
e
s
s
i
onsi
st
ous
eTLS’pa
s
s
wor
d-based
authentication (see the section on ease of use below), which provides automatic
mutual authentication of client and server without any need for certificates, and
without any chance of false positives: The TLS handshake either succeeds with both
sides fully authenticated, or it fails.

Security at Layers 8 and 9
Users are in general unmotivated and will choose the path of least resistance if
pos
s
i
bl
e
,
e
v
e
ni
ft
he
yk
nowt
h
a
ti
t
’
sl
e
s
ss
e
c
ur
e
.Fore
x
a
mp
l
e
,
s
t
ud
e
n
t
sa
tDa
r
t
mo
ut
h
College in the US preferred using passwords on public PCs even though far more
secure USB tokens had been made freely available by the college, because passwords
were more convenient. In general, users dislike being forced to use a particular
interface, with one Gartner group survey finding that although users claimed they
wanted more security, when it came down to it they really wanted to stick with
passwords rather than going to more secure solutions like smart cards and RSA keys.
A similar situation occurs with providers of security services. Most US banking sites
are still using completely insecure, unprotected logins to online banking services
because they want to put advertising on their home pages (low-interest home loans,
pre-approved credit cards, and so on) and using SSL to secure them would make their
pages load more slowly than their competitors. In contrast, the use of un-secured
online banking logins is almost unheard of outside the US, when banks are more
conscious of customer security. In some countries there were concerted efforts by all
banks to ensure that they had a single, consistent, secure interface to all of their online
banking services, although even there it occasionally lead to intense debate over
whe
t
h
e
rs
e
c
ur
i
t
ys
h
oul
dbea
l
l
owe
dt
oov
e
r
r
i
dea
dv
e
r
t
i
s
i
ngpot
e
n
t
i
a
l
.Whe
ny
ou
’
r
e

Ease of Use

planning your security measures, you should be aware of the conflicting requirements
that business and politics will throw up, often requiring solutions at the same business
or political level.

Ease of Use
Us
e
r
sha
t
ec
o
nf
i
g
ur
i
ngt
hi
ng
s
,
e
s
pe
c
i
a
l
l
yc
o
mpl
e
xs
e
c
ur
i
t
yt
e
c
h
no
l
og
yt
ha
tt
h
e
ydon
’
t
understand. One usability study of a PKI (In Search of Usable Security: Five Lessons
from the Field) found that a group of highly technical users, most with PhDs in
computer science, took over two hours to set up a certificate for their own use, and
r
a
t
e
di
ta
st
hemos
td
i
f
f
i
c
ul
tc
ompu
t
e
rt
a
s
kt
he
y
’
de
v
e
rbe
e
na
s
k
e
dt
ope
r
f
or
m.I
n
practice, security experts are terrible at estimating how long a task will take for a
typical user. The assumption is that if the expert can do it in ten minutes then anyone
can do it in ten minutes, when in fact a typical user may still not be able to do it after
ten hours.
To avoid problems like this, your application should auto-configure itself as much as
possible, leaving only a minimal set of familiar operations for the user. For example
a network server can automatically generate a self-signed certificate on installation
and use that to secure communications to it, avoiding the complexity and expense of
obtaining a certificate from an external CA. Even if you consider this to be a
lowering of theoretical s
e
c
ur
i
t
y
,
i
t
’
sr
a
i
s
i
ngi
t
seffective security because n
owi
t
’
l
l
actually be used.
Ont
hec
l
i
e
nts
i
de
,
y
oura
p
pl
i
c
a
t
i
onc
a
nus
ec
r
y
pt
l
i
b
’
spl
ug
-and-play PKI facility to
automatically locate and communicate with a CA server, requiring that the user enter
nothing more than a name and password to authenticate themselves (this process
t
a
k
e
sl
e
s
st
h
a
nami
nut
e
,
a
nddoe
s
n’
tr
e
qu
i
r
eaPhDi
nc
omput
e
rs
c
i
e
n
c
et
o
understand). For embedded devices, the operation can occur automatically when the
device is configured at the time of manufacture.
Since all users are quite used to entering passwords, your application can use the
traditional user name and password (tunnelled over a secure channel such as
SSL/TLS or SSH) rather than more complex mechanisms like PKI, which in most
cases is just an awkward form of user name and password (the user name and
password unlock the private key, which is then used to authenticate the user). Many
us
e
r
sc
ho
os
ep
oorpa
s
s
wor
ds
,
s
opr
ot
o
c
o
l
sl
i
k
eTLS’pa
s
s
wor
d-based authentication,
which never transmit the password even over the secured link, should be preferred to
one
st
ha
tdo.Ana
d
di
t
i
o
na
lb
e
ne
f
i
tofTLS’pa
s
s
wor
d-based authentication is that it
performs mutual authentication of both parties, identifying not only the client to the
server but also the server to the client, without any of the expense, overhead, or
complexity of certificates and a PKI.

Automation vs. Explicitness
Whe
ny
ou
’
r
ep
l
a
n
ni
ngt
hel
e
v
e
lo
fa
u
t
o
ma
t
i
o
nt
ha
ty
ouwa
n
tt
opr
ov
i
def
orus
e
r
s
,
consider the relative tradeoffs between making things invisible and automated vs.
obvious but obtrusive. Users will act to minimise or eliminate monotonous computer
tasks if they can, since humans tend to dislike repetitive tasks and will take shortcuts
wherever possible. The more that users have to perform operations like signing and
encryption, the more they want shortcuts to doing so, which means either making it
mostly (or completely) automated, with a concomitant drop in security, or having
them avoid signing/encrypting altogether. So a mechanism that requires the use of a
smart card and PIN or biometrics will inevitably end up being rarely-used, while one
t
ha
ta
ut
o
ma
t
i
c
a
l
l
ypr
oc
e
s
s
e
sa
ny
t
hi
ngt
ha
tf
l
oa
t
sbywi
l
lbe
.You’
l
lne
e
dt
ode
c
i
d
e
where the best tradeoff point lies — see the section on theoretical vs. effective
security above for more guidance on this.
There are however cases where obtrusive security measures are warranted, such as
when the user is being asked to make important security decisions. In situations like
this, the user should be required to explicitly authorise an action before the action can
proceed. In other words any security-r
e
l
e
v
a
nta
c
t
i
o
nt
ha
t
’
st
a
k
e
ns
ho
ul
dr
e
pr
e
s
e
nta
conscious expression of the will of the user. Silently signing a message behind the

Security and Usability
us
e
r
’
sb
a
c
ki
snoton
l
yba
dpr
a
c
t
i
c
e(
i
t
’
st
h
ee
q
ui
v
a
l
ent of having them sign a contract
without reading it), but is also unlikely to stand up in a court of law, thus voiding the
reason usually given for signing a document.
If the user is being asked to make a security-relevant decision of this kind, make sure
that the action of proceeding really does represents an informed, conscious decision
on their part. Clear the mouse and keyboard buffers to make sure that a keystroke or
mo
us
ec
l
i
c
ks
t
i
l
lpr
e
s
e
ntf
r
o
me
a
r
l
i
e
rondoe
s
n
’
tg
e
ta
c
c
e
p
t
e
da
sar
e
s
po
ns
ef
ort
he
c
ur
r
e
ntde
c
i
s
i
o
n.Don’
ta
s
s
i
g
na
nybu
t
t
onsa
st
hede
f
a
ul
ta
c
t
i
on,
s
i
n
c
es
o
me
t
hi
nga
s
trivial as bumping the space bar will, with most GUIs, trigger the default action and
cause the user to inadvertently sign the document (in this case the secure default is to
do nothing, rather than allowing the user to accidentally create a signature). If
necessary, consult with a lawyer about requirements for the wording and presentation
of requests for security-related decisions that may end up being challenged in court.
The section on user conditioning contains additional guidance on avoiding problems
in this area.

Safe Defaults
Your application should provide sensible security defaults, and in particular ensure
that the default/most obvious action is the safest one. In other words if the user
c
ho
os
e
st
oc
l
i
c
k“
OK”f
ore
v
e
r
ya
c
t
i
on(
a
smos
tus
e
r
swi
l
ld
o)
,
t
he
ys
ho
ul
dbek
e
pt
from harming themselves or others. Remember that if you present the user with a
di
a
l
ogboxt
ha
ta
s
k
s“
Apos
s
i
bl
es
e
c
ur
i
t
ypr
o
bl
e
mha
sbe
e
nde
tected, do you want to
c
on
t
i
nue[
Ye
s
/
No
]
”
,
wha
tt
heus
e
rwi
l
lr
e
a
di
s“
Doy
ouwa
n
tt
hi
sme
s
s
a
g
et
og
oa
wa
y
[
Ye
s
/
No
]
”(
ormor
edi
r
e
c
t
l
y“
Doy
ouwa
ntt
oc
o
nt
i
nu
edo
i
n
gy
ourj
ob[
Ye
s
/
No
]
”
)
.
Ensuring that the Yes option is the safe one helps prevent the user from harming
themselves (and others) when they click it automatically.
cryptlib already enforces this secure-by-default rule by always choosing safe settings
for security options, algorithms, and mechanisms, but you should carefully check
your application to ensure that any actions that it takes (either implicitly, or explicitly
when the user chooses the default action in response to a query) are the safest ones.
The use of safe defaults is also preferable to endless dialogs asking users to confirm
every action that needs to be taken, which rapidly becomes annoying and trains users
to dismiss them without reading them.
Onev
e
r
ye
f
f
e
c
t
i
v
eme
t
h
odofa
v
oi
d
i
ngt
he“
Cl
i
c
kOKt
oma
k
et
hi
sme
s
s
a
g
eg
oa
wa
y
”
problem is to change the question from a basic yes/no one to a multi-choice one. In
one real-world test, about a third of users fell prey to attacks when the system used a
simple yes/no check for a security property such as a verification code or key
fingerprint, but this dropped to zero when users were asked to choose the correct
verification code from a selection of five (one of whi
c
hwa
s“
Noneo
ft
h
ea
b
ov
e
”
)
.
Ther
e
a
s
o
nf
ort
hi
swa
st
ha
tu
s
e
r
se
i
t
he
rd
i
d
n’
tt
h
i
nka
b
ou
tt
hey
e
s
/
n
oqu
e
s
t
i
ona
ta
l
l
,
or rationalised any irregularities away as being transient errors, while the need to
choose the correct value from a selection of several actually forced them to think
about the problem.
The shareware WinZip program uses a similar technique for the message that it
displays when an unregistered copy is run, swapping the buttons around so that users
are actually forced to stop and read thet
e
x
ta
ndt
hi
nka
bo
u
twha
tt
he
y
’
r
ed
oi
ngr
a
t
he
r
t
ha
na
u
t
o
ma
t
i
c
a
l
l
yc
l
i
c
k
i
ng“
Ca
nc
e
l
”wi
t
ho
utt
hi
nk
i
nga
bo
uti
t
.Si
mi
l
a
r
l
y
,
t
he
immigration form used by New Zealand Customs swaps some of the yes/no questions
s
ot
ha
ti
t
’
sn
otp
os
s
i
b
l
et
os
i
mpl
yc
he
c
ke
v
e
r
ybox in the same column without
reading the questions.
Techniques such as this, which present a roadblock to muscle memory, are extremely
e
f
f
e
c
t
i
v
ei
ne
ns
ur
i
ngt
ha
tus
e
r
spa
ypr
ope
ra
t
t
e
n
t
i
onwhe
nt
he
y
’
r
ema
k
i
ngs
e
c
ur
i
t
y
relevant decisions.
Don’
tr
e
l
yonuser education to try and solve problems with your security user
interface. Computer security is simply too complicated, and the motivation for most
users to learn its intricacies too low, for this strategy to ever work. Attackers will
then take advantage of this complexity to sidestep the security measures. For

Matching Us
e
r
s
’Mental Models

example when users, after several years of effort, finally learned that clicking on
random email attachments was dangerous, attackers made sure that the messages
appeared to come from colleagues, friends, trading partners, or family, completely
de
f
e
a
t
i
ngt
he“
Don
’
tc
l
i
c
ko
na
t
t
a
c
h
me
nt
sf
r
o
ms
o
me
o
ney
o
udo
n’
tk
now”
c
on
di
t
i
o
ni
ng
.I
na
ddi
t
i
o
nt
ot
hi
spr
o
bl
e
m,
amo
de
r
ne
l
e
c
t
r
o
ni
co
f
f
i
c
ec
a
n’
tf
unc
t
i
on
without users clicking on attachments, rendering much of this user education effort
useless.
A better use of the time and effort involved would have been to concentrate on
making the types of documents that are sent as attachments purely passive (unable to
cause any action on the destination machine), or only allowing them to be viewed in a
special least-pr
i
v
i
l
e
g
e
sc
ont
e
x
tf
r
om wh
i
c
ht
he
yc
o
ul
dn
’
tc
a
us
ea
nyd
a
ma
g
e
,
ora
variety of other basic security measures dating back to the 1960s and 70s. For
example most operating systems provide a means of dropping privileges, allowing the
a
t
t
a
c
h
me
ntt
obev
i
e
we
di
nac
on
t
e
x
ti
nwh
i
c
ht
he
y
’
r
ei
nc
a
pa
b
l
eo
fc
a
us
i
nga
ny
damage.
Don’
ta
s
s
u
met
ha
ts
o
mes
or
tofus
e
re
du
c
a
t
i
o
nc
a
nma
k
eac
o
mp
l
e
xus
e
ri
nt
e
r
f
a
c
e
provide security — i
t
’
l
lo
nl
ywor
kunt
i
lt
heb
a
dg
uy
sus
ei
t
sc
omplexity against it, or
a new crop of non-educated (for that particular interface) users appears.

Interaction with other Systems
Se
c
ur
es
y
s
t
e
msdo
n’
te
x
i
s
ti
nav
a
c
uu
m,
bu
tne
e
dt
oi
n
t
e
r
a
c
tno
ton
l
ywi
t
hus
e
r
sb
ut
also with other, possibly insecure systems. What assumptions is your design making
about these other systems? Which ones does it trust, and what happens if that trust is
v
i
ol
a
t
e
d,
e
i
t
h
e
rde
l
i
be
r
a
t
e
l
y(
i
t
’
sc
ompr
o
mi
s
e
dbya
na
t
t
a
c
k
e
r
)ora
c
c
i
de
nt
a
l
l
y(
i
t
’
s
running buggy software)? For example a number of SSH implementations assumed
that when the other system had successfully completed an SSH handshake this
constituted proof that it would only behave in a friendly manner, and were completely
vulnerable to any malicious action taken by the other system. On a similar note, there
i
smor
es
pa
mc
o
mi
ngf
r
om c
o
mpr
omi
s
e
d“
g
ood”s
y
s
t
e
mst
ha
n“
ba
d”o
ne
s
.Tr
us
tbu
t
verify — a digitally signed virus is still a virus, even if it has a valid digital signature
attached.
Goi
ngbe
y
ondt
heo
bv
i
o
us“
t
r
us
tn
ob
ody
”approach, your application can also
provide different levels of functionality under different conditions. Just as many file
servers will allow read-only access or access to a limited subset of files under a low
level of user authentication and more extensive access or write/update access only
under a higher level of authentication, so your application can change its functionality
based on how safe (or unsafe) it considers the situation to be. So instead of simply
disallowing all communications to a server whose authentication key has changed (or,
mor
el
i
k
e
l
y
,
c
on
ne
c
t
i
nga
ny
wa
yt
oa
v
oi
dus
e
rc
o
mp
l
a
i
nt
s
)
,
y
ouc
a
nr
u
ni
na“
s
a
f
e
mo
de
”t
ha
tdi
s
a
l
l
owsupl
oa
dsof(
po
t
e
nt
i
a
l
l
ys
e
ns
i
t
i
v
e
)da
t
at
ot
h
epos
s
i
bl
y
compromised server and is more cautious about information coming from the server
than usual.

Mat
chi
ngUser
s’Ment
alModel
s
I
nor
de
rt
ob
eu
nde
r
s
t
a
n
da
b
l
et
ous
e
r
s
,
i
t
’
se
s
s
e
n
t
i
a
lt
ha
ty
o
ura
pp
l
i
c
a
t
i
onma
t
c
ht
he
us
e
r
’
sme
n
t
a
lmode
lo
fhows
ome
t
hi
ngs
houl
dwor
k
,
a
ndt
h
a
ti
tf
o
l
l
owt
hef
l
owo
ft
h
e
us
e
r
s
’c
onc
e
pt
i
o
no
fh
owat
a
s
ks
houl
dbep
e
r
f
or
me
d.I
fy
oud
on
’
tdot
hi
s
,
us
e
r
swi
l
l
find it very difficult to accomplish what they want to do when they sit down in front
of your application.
Cons
i
de
rt
hepr
o
c
e
s
so
fg
e
ne
r
a
t
i
ngapubl
i
c
/
pr
i
v
a
t
ek
e
ypa
i
r
.I
fy
ou’
r
es
i
t
t
i
ng at a
Unix command line, you fire up a copy of gpg or openssl, feed it a long string of
command-line options, optionally get prompted for further pieces of input, and at the
end of the process have a public/private key pair stored somewhere as indicated by
one of the command-line options.
This CLI-style design has been carried over to equivalent GUI interfaces that are used
to perform the same operation. -k keysize has become a drop-down combobox.
-a algorithm is a set of checkboxes, and so on. Overall,
i
t
’
sj
us
tab
i
gg
r
a
phi
c
a
l

Security and Usability

CLI-equivalent, with each command-line option replaced by a GUI element, often
spread over several screens for good measure (one large public CA requires users to
fill out eleven pages of such information in order to be allowed to generate their
public/private key pair).
The problem with this style of interface is that while it may cater quite well to people
moving over from the command-l
i
nei
nt
e
r
f
a
c
e
,
i
t
’
sv
e
r
ydi
f
f
i
c
ul
tt
oc
o
mpr
e
he
n
df
or
the average user without this level of background knowledge, who will find it a
considerable struggle to accomplish their desired goal of generating a key to protect
their email or web browsing. Rather than focusing on the nuts and bolts of the key
generation process, the interface should instead focus on the activity that the user is
trying to perform, and concentrate on making this task as easy as possible. Microsoft
has espoused this user interface design principle in the form of Activity-Based
Planning, which instead of giving the user a pile of atomic operations and forcing
them to hunt through menus and dialogs to piece all the bits and pieces together to
achieve their intended goal, creates a list of things that a user might want to do (see
the section on pre-implementation testing further on) and then builds the user
interface around those tasks.

Activity-Based Planning
Activity-ba
s
e
dpl
a
nn
i
ngma
t
c
he
sus
e
r
s
’na
t
ur
a
lwa
yoft
hi
n
k
i
nga
boutt
h
e
i
ra
c
t
i
v
i
t
i
e
s
,
whi
c
hf
oc
uso
ng
oa
l
ss
uc
ha
s“
Iwa
ntmyme
di
c
a
lr
e
c
or
dsk
e
ptpr
i
v
a
t
e
”or“
Iwa
ntt
o
bes
ur
et
ha
tt
hep
e
r
s
on
/
or
g
a
ni
s
a
t
i
o
nt
ha
tI
’
mt
a
l
k
i
ngt
or
e
a
l
l
yi
swhot
he
yc
l
a
i
mt
o
be
”
,
r
a
t
h
e
rt
ha
nf
oc
us
i
ngont
e
c
h
nol
og
ys
uc
ha
s“
Iwa
ntt
ous
ea
nX.
50
9c
e
r
t
i
f
i
c
a
t
ei
n
conjunction with triple-DESe
nc
r
y
pt
i
ont
os
e
c
ur
emyc
o
mmuni
c
a
t
i
o
ns
”
.Your
applications
ho
ul
dt
he
r
e
f
or
ep
r
e
s
e
ntt
het
a
s
ki
nv
o
l
v
i
ngs
e
c
ur
i
t
yi
nt
e
r
msoft
heus
e
r
s
’
goals rather than of the underlying security technology, and in terms that the users
c
a
nu
nd
e
r
s
t
a
n
d(
mos
tus
e
r
swon
’
ts
p
e
a
ks
e
c
ur
i
t
yj
a
r
g
on)
.Thi
sb
ot
hma
k
e
si
tpos
s
i
bl
e
for use
r
st
oun
de
r
s
t
a
ndwh
a
ti
ti
st
he
y
’
r
edo
i
ng
,
a
nde
nc
our
a
g
e
st
he
mt
oma
k
eus
eof
the security mechanisms that are available.
Using the key generation example from earlier, the two activities mentioned were
generating a key to protect email, and generating a key to protect web browsing (in
other words, for an SSL web server). This leads naturally to an interface in which the
us
e
ri
sf
i
r
s
ta
s
k
e
dwh
i
c
hoft
h
et
wot
a
s
k
st
he
ywa
ntt
oa
c
c
o
mp
l
i
s
h,
a
ndonc
et
h
e
y
’
v
e
made their choice, asked for their name and email address (for the email protection
key) or their web server address (for the SSL/web browsing key). An even better
option would be to try and determine the details automatically, for example by
r
e
a
di
ngt
hee
ma
i
la
ddr
e
s
si
n
f
or
ma
t
i
onf
r
o
mt
h
eus
e
r
’
sma
i
la
ppl
ication configuration,
a
ndme
r
e
l
ya
s
k
i
ngt
heus
e
rt
oc
on
f
i
r
mt
hede
t
a
i
l
s
.Theus
e
rs
hou
l
d
n’
tbebo
t
he
r
e
d
with anything else, since the application is perfectly capable of managing that for
them. Again, see the section on pre-implementation testing for a discussion of how to
work out details such as where to store the generated key.
There are three additional considerations that you need to take into account when
y
ou’
r
eus
i
ngAc
t
i
v
i
t
y
-Based Planning to design your user interface. First, you need
to be careful to plan the activities correctly, so that you cover the majority of typical
us
ec
a
s
e
sa
ndd
on
’
ta
l
i
e
na
t
eu
s
e
r
sbyf
or
c
i
ngt
he
m downpa
t
hst
h
a
tt
he
ydo
n’
twa
ntt
o
take, or having to try and mentally reverse-engineer the flow to try and guess which
path they have to take to get to their desired goal (think of a typical top-level phone
menu, for which there are usually several initial choices that might lead to any desired
goal).
Secondly, you should always provide an opt-out capability to accommodate users
whodo
n
’
twa
ntt
op
e
r
f
or
ma
na
c
t
i
ont
ha
tma
t
c
h
e
son
eo
fy
ourpr
e
-generated ones.
This would be handled in the key-generation interface by the addition of a third
option to generate some other (user-de
f
i
ne
d)t
y
peo
fk
e
y
,
t
hee
qu
i
v
a
l
e
nto
ft
he“
Pr
e
s
s
0 tot
a
l
kt
oa
nop
e
r
a
t
or
”op
t
i
o
ni
nap
ho
neme
nu.
Finally, you should provide the option to select an alternative interface, usually
presented as an expert or advanced mode, for users who prefer the nuts-and-bolts
style interface in which they can specify every little detail themselves. Although the

Matching Us
e
r
s
’Mental Models

subgroup of users who prefer this level of configurability for their options is
relatively small, it tends to be a rather vocal minority who will complain loudly about
the inability to specify their favourite obscure algorithm or select abnormally large
key sizes.

Use of Familiar Metaphors
Many users are reluctant to activate security measures because the difficulty of
c
on
f
i
g
ur
i
ngt
he
mi
sg
r
e
a
t
e
rt
h
a
na
nype
r
c
e
i
v
e
db
e
n
e
f
i
t
s
.Us
i
ngame
t
a
p
hort
ha
t
’
s
familiar to the user can help significantly in overcoming this reluctance to deal with
security issues. For example most users are familiar with the use of keys as security
tools, making a key-like device an ideal mechanism for propagating security
parameters from one system to another. Instead of a conventional key, the device
used to initialise security parameters is a USB memory key that the user takes to each
de
v
i
c
et
ha
t
’
sb
e
i
ngi
ni
t
i
a
l
i
s
e
d.Thi
sme
c
ha
ni
s
mi
sus
e
di
nMi
c
r
os
of
t
’
sWi
nd
ows
Network Smart Key (WNSK), in which Windows stores WiFi/802.11 encryption
keys and other configuration details onto a standard USB memory key, which is then
inserted into the other wireless devices that need to be configured.
Since the USB drives can store amounts of information that would be impossible for
humans to carry from one device to another (the typical WNSK file size is around
100KB)
,
i
t
’
sp
os
s
i
b
l
et
of
ul
l
ya
ut
o
ma
t
et
hes
e
t
u
pus
i
ngf
ul
l
-strength security
parameters and configuration information that would be impossible for humans to
manage. In addition to the automated setup process, for compatibility with nonWNSKs
y
s
t
e
msi
t
’
sa
l
s
op
os
s
i
bl
et
opr
i
ntou
tt
hec
on
f
i
g
ur
a
t
i
onpa
r
a
me
t
e
r
s
,
a
l
t
h
oug
h
the manual data entry process is rather painful. Using the familiar metaphor of
inserting a key into an object in order to provide security greatly increases the
c
ha
nc
e
st
ha
ti
t
’
l
la
c
t
u
a
l
l
ybeu
s
e
d,
s
i
nc
ei
tr
e
q
ui
r
e
sa
l
mos
tn
oe
f
f
or
tont
hep
a
r
to
ft
h
e
user.
This type of security mechanism is known as a location-limited channel, one in which
t
heus
e
r
’
sc
r
e
d
e
n
t
i
a
l
sa
r
epr
ov
e
nbyt
hef
a
c
tt
h
a
tt
he
yha
v
ep
hy
s
i
c
a
la
c
c
e
s
st
ot
he
device(s) being configured. If the threat model involves attackers coming in over a
network, such a location-limited channel is more secure than any fancy (and
complex) use of devices such as smart cards and certificates, since the one thing that
ane
t
wor
ka
t
t
a
c
k
e
rc
a
n
’
td
oi
spl
ugaphy
s
i
c
a
lt
ok
e
ni
nt
ot
h
ede
v
i
c
et
ha
t
’
sb
e
i
ng
configured.
A similar type of mechanism, which is often combined with a location-limited
channel, is a time-limited channel in which two devices have to complete a secure
initialisation within a very small time window. An example of mechanism is one in
which the user simultaneously presses secure initialisation buttons on both devices
being configured. The device being initialised would then assume that anything that
responded at that exact timepoint would be its intended peer device. This mechanism
combines both location-limited channels (the user is demonstrating their authorisation
by being able to activate the secure initialisation process) and a time-limited channel
(the setup process has to be carried out within a precise time window in order to be
successful).
The
s
et
y
pe
sofs
e
c
ur
i
t
yme
c
h
a
ni
s
mspr
ov
i
deb
ot
ht
h
ee
a
s
eofus
et
h
a
t
’
sne
c
e
s
s
a
r
yin
or
de
rt
oe
ns
ur
et
ha
tt
he
y
’
r
ea
c
t
ua
l
l
yus
e
d,
a
ndah
i
g
hde
g
r
e
eofs
e
c
ur
i
t
yf
r
o
mo
ut
s
i
de
attackers, since only an authorised user with physical access to the system is capable
of performing the initialisation steps.
Note though that you have to exercise al
i
t
t
l
ebi
to
fc
a
r
ewh
e
ny
ou
’
r
ede
s
i
g
ni
ngy
our
location-limited channel. The Bluetooth folks, for example, allowed anyone (not just
authorised users) to perform this secure initialisation (forced re-pairing in Bluetooth
terminology), leading to the sport of bluejacking, in which a hostile party hijacks
s
ome
o
nee
l
s
e
’
sBl
ue
t
o
ot
hde
v
i
c
e
.Ag
oodr
ul
eo
ft
hu
mbf
ort
he
s
et
y
p
e
sofs
e
c
ur
i
t
y
me
a
s
ur
e
si
st
ol
o
oka
twha
tBl
ue
t
o
ot
hdoe
sf
ori
t
s“
s
e
c
ur
i
t
y
”a
ndt
he
nma
k
es
ur
et
ha
t
y
oudo
n’
td
oa
ny
t
h
i
ngl
i
k
ei
t
.

Security and Usability

Speakingt
heUser
’
sLanguage
When interacting with the user, particularly over a topic as complex as computer
s
e
c
ur
i
t
y
,
i
t
’
si
mp
or
t
a
ntt
os
pe
a
kt
he
i
rl
a
ng
ua
g
e
.De
v
e
l
ope
r
swhos
pe
n
dt
h
e
i
rl
i
v
e
s
i
mme
r
s
e
di
nt
het
e
c
hn
ol
og
yt
ha
tt
he
y
’
r
ec
r
e
a
t
i
ngof
t
e
nf
i
ndi
tha
r
dto step back and
view it from a non-t
e
c
h
ni
c
a
lus
e
r
’
sp
oi
nto
fv
i
e
w,
wi
t
ht
her
e
s
ul
tt
ha
tt
heus
e
r
interface that they create assumes a high degree of technical knowledge in the end
user.
Thee
a
s
i
e
s
twa
yt
ode
t
e
r
mi
n
ehowt
os
p
e
a
kt
heus
e
r
’
sl
a
ng
ua
g
ewhe
ny
our application
c
o
mmu
ni
c
a
t
e
swi
t
ht
h
e
mi
st
oa
s
kt
heus
e
r
swha
tt
he
y
’
de
x
pe
c
tt
os
e
ei
nt
hei
n
t
e
r
f
a
c
e
.
Studies of users have shown however that there are so many different ways to
describe the same sorts of things that using the results from just one or two users
would invariably lead to difficulties when other users expecting different terms or
different ways of explaining concepts use the interface.
A better alternative is to let users vote on terminology chosen from a list of usersuggested text and then select the option that garners the most votes. A real-world
evaluation of this approach found that users of the interface with the highest-polling
terminology made between two and five times less mistakes than when they used the
same interface with the or
i
g
i
na
lt
e
c
hn
i
c
a
lt
e
r
mi
nol
og
y
,t
hei
nt
e
r
f
a
c
es
t
y
l
et
ha
t
’
s
currently found in most security applications.
The same study found that after prolonged use, error rates were about the same for
both interfaces, indicating that, given enough time, users can eventually learn more or
l
e
s
sa
ny
t
h
i
ng.
.
.
unt
i
la
na
no
ma
l
o
usc
o
ndi
t
i
onoc
c
ur
s
,
a
twhi
c
hp
oi
n
tt
h
e
y
’
l
lbe
completely lost with the technical interface.
Consider how requests for security-related information are presented to the user. For
example many applications, when connecting to a server whose key (which is usually
tied to its identity) has changed will present the user with either too little information
(
“
Thek
e
yha
sc
ha
ng
e
d,
c
ont
i
nue
?
”
)
,
t
oomuc
hi
n
f
or
ma
t
i
o
n(
api
l
eo
f
incomprehensible X.509 technobabble, in one PKI usability study not a single user
was able to make any sense of the certificate information that Windows displayed to
t
he
m)
,
ort
hewr
ongk
i
ndofi
nf
or
ma
t
i
on(
“
Thes
k
yi
sf
a
l
l
i
n
g
,
r
una
wa
y
”
)
.
Look at the problem from the point of view of the use
r
.The
y
’
r
ec
on
ne
c
t
i
ngt
oa
s
e
r
v
e
rt
ha
tt
h
e
y
’
v
ec
o
nne
c
t
e
dt
oma
nyt
i
me
si
nt
hepa
s
ta
n
dt
ha
tt
he
yne
e
dt
og
e
tt
o
now in order to do their job. Their natural inclination will be to do whatever it takes
to get rid of the warning and connect anyway, making i
ta
n
ot
h
e
ri
ns
t
a
nc
eo
ft
he“
Do
y
ouwa
ntt
hi
sme
s
s
a
g
et
og
oa
wa
y
”pr
obl
e
m pr
e
s
e
nt
e
de
a
r
l
i
e
r
.
An additional problem is caused by the fact that security warnings presented to the
user often come with no supporting context. Since web browsers implicitly and
invisibly trust a large number of CAs, and by extension a vast number of certificates,
users have no idea what a certificate is when an error message mentioning one
appears. One user survey found that many users assumed that it represented some
form of notice on the wall of the establishment, like a health inspection notice in a
restaurant or a Better Business Bureau certificate, a piece of paper that indicates
nothing more than that the owner has paid for it (which indeed is the case for most
SSL certificat
e
s
)
.Us
e
r
swe
r
et
he
r
e
f
or
ed
i
s
mi
s
s
i
v
eo
f“
t
r
us
t
e
d”c
e
r
t
i
f
i
c
a
t
e
s
,
a
n
da
sa
n
e
x
t
e
ns
i
onc
a
r
e
de
qua
l
l
yl
i
t
t
l
ea
bo
ut“
un
t
r
us
t
e
d”o
ne
s
.Fur
t
he
re
x
a
mpl
e
so
ft
hi
s
problem are given in the section on user conditioning above.
Your user interface should therefore ex
p
l
a
i
nt
hepr
o
bl
e
mt
ot
he
m,
f
ore
x
a
mpl
e“
The
s
e
r
v
e
r
’
si
de
n
t
i
f
i
c
a
t
i
o
nha
sc
ha
ng
e
ds
i
nc
et
hel
a
s
tt
i
met
ha
ty
ouc
on
ne
c
t
e
dt
oi
t
.Th
i
s
may be a fake server pretending to be the real thing, or it could just mean that the
s
e
r
v
e
rs
of
t
wa
r
eha
sbe
e
nr
e
i
n
s
t
a
l
l
e
d”
.Depending on the severity of the consequences
of connecting to a fake server, you can then allow them to connect anyway, connect
in a reduced-f
unc
t
i
ona
l
i
t
y“
s
a
f
e
”mo
des
u
c
ha
so
net
ha
tdi
s
a
l
l
owsupl
oa
dsof
(potentially sensitive) data to the possibly-compromised server and is more cautious
about information coming from the server than usual, or perhaps even require that
t
he
yf
i
r
s
tv
e
r
i
f
yt
hes
e
r
v
e
r
’
sa
ut
h
e
n
t
i
c
i
t
ybyc
he
c
k
i
ngi
twi
t
ht
hea
d
mi
ni
s
t
r
a
t
orwho
r
unsi
t
.I
fy
oul
i
k
e
,
y
ouc
a
na
l
s
oi
n
c
l
udea
n“
Adv
a
n
c
e
d
”op
t
i
o
nt
h
a
td
i
s
pl
a
y
st
heus
ua
l

Matching Us
e
r
s
’Mental Models

X.509 gobbledigook. Remember though to make the simplest, most straightforward
interface configuration the default one, since studies have shown that casual users
don
’
tc
us
t
o
mi
s
et
he
i
ri
nt
e
r
f
a
c
e
s(
t
y
pi
c
a
l
l
yf
orf
e
a
rof“
br
e
a
k
i
ngs
ome
t
hi
ng
”
)e
v
e
n
when a configuration capability is available.
The ability to select basic and advanced versions of the user interface helps reduce
usability problems by giving most users a set of sensible (and safe) defaults without
overloading them with complexity while still allowing power users to tweak settings
t
ot
he
i
rhe
a
r
t
’
sc
on
t
e
nt
.Fore
x
a
mp
l
ec
e
r
t
i
f
i
c
a
t
ee
nr
ol
me
ntus
i
ngc
r
y
pt
l
i
b
’
spl
ug
-andplay PKI facility can be done with nothing more than a user name and password, or
with dozens of dialog boxes for choosing the algorithm type, key size, X.500
distinguished name components, certificate attributes, key file name, storage location,
and so on and so on, for advanced users that really require this.

Use of Visual Cues
The use of colour can play an important role in alerting users to safe/unsafe
situations. For this reason, Mozilla-based web browsers updated their SSL indication
mechanism from the original easily-overlooked tiny padlock at the bottom of the
screen to changing the backgroun
dc
ol
o
uro
ft
hebr
ows
e
r
’
sl
oc
a
t
i
onb
a
rwhe
nSSLi
s
active and the certificate is verified. Changing the background colour or border of the
object that the user is looking at or working with is an extremely effective way of
communicating security informati
o
nt
ot
he
m,
s
i
nc
et
he
ydo
n’
tha
v
et
or
e
me
mbe
rt
o
explicitly look elsewhere to try and find the information. The colour change also
ma
k
e
si
tv
e
r
ye
x
pl
i
c
i
tt
ha
ts
o
me
t
hi
ngs
pe
c
i
a
lh
a
soc
c
ur
r
e
dwi
t
ht
heo
bj
e
c
tt
h
a
t
’
sbe
i
ng
highlighted (one usability study found that the number of users who were able to
avoid a security problem doubled when different colours were used to explicitly
highlight security properties).
If you decide to use colour or similar highlighting methods in your application,
remember that the user has to be aware of the significance of the different colours in
order to be able to make a decision based on them, that some users may be colourblind to particular colour differences, and that colours have different meanings across
different cultures
.Fore
x
a
mp
l
et
h
ec
ol
ourr
e
dwo
n’
ta
u
t
o
ma
t
i
c
a
l
l
ybei
nt
e
r
pr
e
t
e
dt
o
indicate danger in all parts of the world, or its meaning as a danger/stop signal may
work differently in different countries. In the UK, heavy machinery is started with a
green button (go) and stopped with a red button (stop). Across the channel in France,
i
t
’
ss
t
a
r
t
e
dwi
t
har
e
dbu
t
t
o
n(
ada
ng
e
r
ousc
o
nd
i
t
i
oni
sbe
i
n
gc
r
e
a
t
e
d)a
n
ds
t
o
ppe
d
wi
t
hag
r
e
e
nbut
t
on(
i
t
’
sb
e
i
n
gr
e
nde
r
e
ds
a
f
e
)
.Whe
ni
tc
o
me
st
oc
o
l
o
ur
-blindness,
about 8% of the population will be affected, with the most common type being partial
or complete red-green colour-blindness. Ensuring that your interface also works
without the use of colour, or at least making the colour settings configurable, is one
way of avoiding these problems.
Visual cues can also be used to provide an indication of the absence of security,
although how to effectively indicate the absence of a property is on general a hard
problem to solve. For example password-entry fields in dialog boxes and web pages
always blank out the typed password (typically with asterisks or circles) to give the
impression that the password is secret and/or protected in some manner. Even if the
password is sent in the clear without any protection (which is the case for many web
pa
g
e
s
)
,
i
t
’
ss
t
i
l
lbl
a
nk
e
do
uti
nt
heus
e
rdi
s
pl
a
y
.Conv
e
r
s
e
l
y
,
i
nf
or
ma
t
i
o
ns
uc
ha
s
credit card numbers, which are usually sent encrypted over SSL connections, are
di
s
p
l
a
y
e
dt
ot
heus
e
r
.Bynotbl
a
nk
i
ngt
hepa
s
s
wor
df
i
e
l
dwhe
nt
he
r
e
’
snopr
ot
e
c
t
i
on
be
i
ngus
e
d,
y
ou’
r
epr
ov
i
di
ngi
ns
t
a
nt
,
u
n
mi
s
t
a
k
e
a
b
l
ef
e
e
d
ba
c
kt
ot
heus
e
rt
ha
tt
h
e
r
e
’
s
no security active.
The fact that their password is being shown in the clear will no doubt make many
us
e
r
sne
r
v
ous
,
be
c
a
us
et
he
y
’
v
ebe
e
nc
o
ndi
t
i
on
e
dt
os
e
e
i
ngi
tma
s
k
e
dout. However,
making users nervous is exactly what this measure is meant to do: a password
di
s
p
l
a
y
e
di
nt
hi
sma
n
ne
rma
ynowbev
ul
ne
r
a
bl
et
os
ho
ul
de
rs
ur
f
i
ng
,
buti
t
’
se
v
e
n
more vulnerable to network sniffing and similar attacks (this is disregarding the
question of why a user would be accessing sensitive information in a password-

Security and Usability
pr
ot
e
c
t
e
da
c
c
ou
nti
na
ne
nv
i
r
on
me
ntt
ha
t
’
sv
ul
ne
r
a
b
l
et
os
hou
l
d
e
r
-surfing in the first
place).
Displaying the password in the clear makes real and present what the user cannot see,
that there is no security active to protect either their password or any sensitive
information that the password will unlock. To avoid adverse user reaction, you
s
hou
l
da
ddat
oo
l
t
i
p“
Whyi
smypa
s
s
wor
ds
h
owi
ng
”t
ot
h
epa
s
s
wor
d-entry box when
the passwor
di
s
n
’
tma
s
k
e
d,
e
x
pl
a
i
ni
ngt
ous
e
r
swha
t
’
sg
oi
n
gona
ndt
hep
ot
e
nt
i
a
l
consequences of their actions. This combination of measures provides both
appropriate warning and enough information for the user to make an informed
decision about what to do next.
When you use measures like this, make sure that you display the security state in a
ma
nne
rwhe
r
ei
tc
a
n’
tbes
p
o
of
e
dbya
na
t
t
a
c
k
e
r
.Fore
x
a
mp
l
ewe
bbr
ows
e
r
sa
r
e
vulnerable to many levels of user interface spoofing using methods such as HTML to
change the appearance of the browser or web page, or Javascript or XUL to modify or
over-draw browser UI elements. To protect against these types of attack, you should
ensure that your security-s
t
a
t
usdi
s
p
l
a
yme
c
h
a
ni
s
mc
a
n
’
tb
es
poo
f
e
dorov
e
r
r
i
d
de
nby
external means.

Usability Testing
Usability testing is a two-phase process, pre-implementation testing (trying to figure
out what you want to build) and post-implementation testing (verifying that what you
eventually built — which given the usual software development process could be
quite different from what was planned — is actually the right thing). This section
covers both pre- and post-implementation testing of the security usability of an
application.

Pre-implementation Testing
Testing at the design stage (before you even begin implementation, for example using
a mockup on paper or a GUI development kit) can be enormously useful in assessing
t
heus
e
r
s
’r
e
a
c
t
i
o
nst
ot
hei
nt
e
r
f
a
c
ea
nda
sadr
i
v
e
rf
orf
ur
t
h
e
rde
s
i
g
ne
f
f
or
t(
Ca
r
ol
y
n
Sny
de
r
’
sb
ookPaper Prototyping: The Fast and Easy Way to Design and Refine User
Interfaces provides further guidance in this area). Consider having the
designers/developers play the part of the computer when interacting with test users, to
allow them to see what their planned interface needs to cope with. Although users
a
r
e
n’
tpr
o
f
e
s
s
i
on
a
lus
e
ri
nt
e
r
f
a
c
ede
s
i
g
ne
r
s
,
t
he
ya
r
ev
e
r
yg
ooda
tr
e
a
c
t
i
ngt
ode
s
i
g
ns
t
ha
tt
he
yd
on
’
tl
i
k
e
,
ort
ha
twon
’
twor
ki
npr
a
c
t
i
c
e
.
Another useful pre-implementation testing technique is to imagine a stereotypical end
user (or several types of stereotypical users if this applies) and think about how
t
he
y
’
dus
et
hes
o
f
t
wa
r
e
.Wha
ts
or
to
ft
h
i
ng
swoul
dt
h
e
ywa
ntt
odowi
t
hi
t
?How
well would they cope with the security mechanisms? How would they react to
security wa
r
ni
ng
s
?Thei
mp
o
r
t
a
ntt
hi
nghe
r
ei
st
ha
ty
ous
h
oul
dn
’
tj
us
ta
ddapi
l
eo
f
features that you think are cool and then try and figure out how to justify their use by
t
hee
ndus
e
r
,
butt
ha
ty
o
ul
o
o
ka
ti
tf
r
o
mt
heus
e
r
’
spo
i
n
to
fv
i
e
wa
nda
d
don
l
yt
hos
e
fea
t
ur
e
st
ha
tt
he
y
’
l
la
c
t
u
a
l
l
yn
e
e
da
ndb
ea
bl
et
oun
de
r
s
t
a
nd
.
Note though that you should never employ the technique of stereotypical users as a
substitute for studying real users if such access is available. An amazing amount of
time is wasted at the design stage of many projects as various contributors argue over
what users might in theory do if they were to use the system, rather than simply going
to the users and seeing what they actually do.
Al
lt
o
of
r
e
q
ue
nt
l
y
,
us
e
ri
n
t
e
r
f
a
c
e
sg
oa
g
a
i
ns
tt
heus
e
r
’
sn
a
t
ural expectations of how
something is supposed to work. For example a survey of a range of users from
different backgrounds on how they expected public keys and certificates to be
managed (PKI Technology Survey and Blueprint) produced results that were very,
very different from how X.509 says it should be done, suggesting at least one reason
f
orX.
50
9’
sf
a
i
l
ur
et
oa
c
hi
e
v
ea
nyr
e
a
lpe
n
e
t
r
a
t
i
o
n.

Usability Testing

Asking users how they think that something should work is therefore an extremely
useful design technique. Considert
h
equ
e
s
t
i
onofs
t
or
i
ngus
e
r
s
’pr
i
v
a
t
ek
e
y
s
.Shoul
d
they be stored in one big file on disk? Multiple files? In the registry (if the program
is running under Windows)? On a USB token? In their home directory? In a hidden
directory underneath their home directory? What happens if users click on one of
these files? What if they want to move a particular key to another machine? How
about all of their keys? What happens when they stop using the machine or account
where the keys are stored? How are the keys protected? How are they backed up?
Should they even be backed up?
Al
loft
he
s
eque
s
t
i
onsc
a
nbede
b
a
t
e
di
n
f
i
ni
t
e
l
y
,
bu
tt
h
e
r
e
’
saf
a
rs
i
mp
l
e
r(
a
ndmor
e
effective) way to resolve things. Go and ask the users how they would expect them to
be done. Ma
nyus
e
r
swon’
tk
now,
orwon’
tc
a
r
e
,
b
ute
v
e
n
t
ua
l
l
yy
ou’
l
ls
e
es
o
mes
or
t
of common model for key use and handling start to appear. This model will be the
onet
ha
tmos
tc
l
e
a
r
l
yma
t
c
he
st
heus
e
r
’
sna
t
ur
a
le
x
p
e
c
t
a
t
i
on
sofh
owt
hi
ng
sa
r
e
supposed to work, andt
he
r
e
f
or
et
heonet
ha
tt
h
e
y
’
l
lf
i
ndt
h
ee
a
s
i
e
s
tt
ous
e
.Thi
ss
t
y
l
e
of testing has been in use for some years when developing new user interface
features. For example in the early 1980s whenever a new interface feature was
implemented for the Apple Lisa, Apple developer Larry Tesler would collar an Apple
e
mpl
oy
e
et
ot
r
yi
to
ut
.I
ft
h
e
yc
oul
dn
’
tf
i
g
ur
ei
to
ut
,
t
h
ef
e
a
t
ur
ewa
sr
e
de
s
i
g
ne
dor
removed.
Another advantage of asking users what they want is that they frequently come up
with issues that the devel
op
e
r
sha
v
e
n’
te
v
e
ndr
e
a
me
da
bo
ut
.I
fy
oudot
h
i
st
h
oug
h,
make sure that you occasionally refresh your user pool, because as users spend more
and more time with your interface they become less and less representative of the
typical user, and therefore less able to pick up potential usability problems.

Post-implementation Testing
Onc
ey
ou
’
v
ef
i
ni
s
he
dy
o
ura
p
pl
i
c
a
t
i
o
n,
t
a
k
eaf
e
wn
on-technical people, sit them in a
room with a copy of the software running, and see how they handle it. Which parts
take them the longest? At what points do they have to refer to the manual, or even
ask for help? Did they manage to get the task done in a secure manner, meaning that
their expectations of security (not just yours) were met? Can a section that caused
them problems be redesigned or even eliminated by using a safe default setting? Real
testing before deployment (rather than shipping a version provisionally tagged as a
beta release and waiting for user complaints) is an important part of the security
usability evaluation process.
Log
g
i
ngofus
e
r
s
’a
c
t
i
o
nsdur
i
ngt
hi
spr
oc
e
s
sc
a
nhe
l
ps
ho
wuppr
ob
l
e
ma
r
e
a
s
,
e
i
t
he
r
because users take a long time to do something or because their actions generate
many error messages. Logging also has the major advantage that (except for privacy
c
on
c
e
r
ns
)i
t
’
st
o
t
a
l
l
yno
n-invasive, so that users can ignore the logging and just get on
wi
t
hwha
tt
he
y
’
r
edo
i
ng
.
As an example of the conflict between user expectations and security design, security
usability studies have shown that email users ty
pi
c
a
l
l
ya
r
e
n
’
ta
wa
r
et
ha
t(
a
)me
s
s
a
g
e
s
c
a
nb
emod
i
f
i
e
da
st
he
ymov
ea
c
r
os
st
heI
n
t
e
r
ne
t
,
(
b)e
nc
r
y
pt
i
ngame
s
s
a
g
edoe
s
n’
t
provide any protection against such modification, and (c) signing a message does
protect it. The users had assumed that encrypting a message provided integrity
protection but signing it simply appended the equivalent of a pen-and-paper signature
to the end of it. Real-world testing and user feedback is required to identify these
issues so that they can be addressed, for example by explaining signing as protecting
the message from tampering rather than the easily-mi
s
u
nd
e
r
s
t
ood“
s
i
g
ni
ng
”
.
Si
mi
l
a
r
l
y
,
t
hef
a
c
tt
h
a
te
n
c
r
y
pt
i
o
nd
oe
s
n
’
tpr
ov
i
dei
nt
e
g
r
i
t
ypr
ot
e
c
t
i
onc
a
nb
e
addressed either at the user interface level by warning the user that the encrypted
me
s
s
a
g
ei
s
n’
tpr
o
t
e
c
t
e
df
r
o
m mo
di
f
i
c
a
t
i
o
n,
ora
tt
h
et
e
c
hn
i
c
a
ll
e
v
e
lbya
d
di
ngaMDC
(modification detection code) inside the encryption layer or a MAC (message
authentication code) outside it. Of these two, the latter is the better option since it
“
f
i
x
e
s
”t
hee
nc
r
y
pt
i
ont
od
owha
tus
e
r
se
x
pe
c
twi
t
h
ou
ta
d
di
t
i
o
na
l
l
ybur
de
ni
ngt
he
user.

Security and Usability

Post-implementation testing can often turn up highly surprising results arising from
issues that would never have occurred to implementers. For example the developers
of the Tor anonymity system found that Tor users were mailing out their private keys
to other Tor users, despite the fact that they were supposed to know not to do this.
Changing the key filename to include a secret_ prefix at the front solved the problem
byma
k
i
ngi
te
x
pl
i
c
i
tt
ous
e
r
st
ha
tt
h
i
swa
ss
ome
t
h
i
ngt
ha
ts
hou
l
d
n
’
tbes
ha
r
e
d. PGP
solves the problem in a similar manner by only allowing the public key components
to be exported from a PGP keyring, even if the user specifies that the PGP private
keyring be used as the source for the export. Conversely, Windows/PKCS #12 takes
exactly the opposite approach, blurring any distinction between the two in the form of
as
i
ng
l
e“
di
g
i
t
a
li
d
e
n
t
i
t
y
”orPKCS#12/
PFXf
i
l
e
, so that users are unaware that
t
he
y
’
r
eha
n
di
ngov
e
rt
he
i
rpr
i
v
a
t
ek
e
y
sa
spa
r
toft
h
e
i
rdi
g
i
t
a
li
d
e
nt
i
t
y(
onepa
p
e
r
l
i
k
e
nst
hi
spr
a
c
t
i
c
et
o“
po
ur
i
n
gwe
e
dk
i
l
l
e
ri
n
t
oaf
r
ui
tj
ui
c
ebot
t
l
ea
nds
t
or
i
ngi
tona
n
easily accessible shelf in the kitchen cupboard”
)
.
User interface design is usually a highly iterative process, so that the standard
{ design, implement, test }c
y
c
l
ede
s
c
r
i
be
da
bov
epr
o
ba
bl
ywon’
tbee
no
ug
ht
os
ha
k
e
out all potential problems, particularly in the case of something as complex and hard
to predict as security user interface design. Instead of a single cycle, you may need to
use multiple cycles of user testing, starting with a relatively generic design
(sometimes known as low-fi prototyping) and then refining it based on user feedback
and experience.
Thi
st
e
s
t
i
ngpr
oc
e
s
sne
e
d
n’
tb
ec
o
mp
l
e
xore
x
pe
ns
i
v
e
.Us
a
bi
l
i
t
ye
x
pe
r
tJ
a
k
obNi
e
l
s
e
n
has shownt
ha
to
nc
ey
oug
obe
y
onda
bo
utf
i
v
eus
e
r
st
e
s
t
e
d,
y
ou’
r
en
otg
e
t
t
i
ngmuc
h
more information in terms of usability results. This phenomenon occurs because as
y
oua
d
dmor
ea
n
dmor
eus
e
r
s
,
t
he
r
e
’
si
nc
r
e
a
s
i
ngov
e
r
l
a
pi
nwha
tt
he
yd
o,
s
ot
h
a
ty
ou
learn less and less from each new user that you add. So if you have (say) 20 test
us
e
r
s
,
i
t
’
sb
e
t
t
e
rt
ous
et
he
mi
nf
o
urdi
f
f
e
r
e
n
ts
e
t
so
ft
e
s
t
s(
pe
r
haps on different
versions of the interface) than to commit all 20 to a single test. A variation of this
situation occurs when a single group contains highly distinct subgroups of users, such
as one where half the users are technical and the other half are non-technical. In this
case you should treat each subgroup as a separate unit for 5-user test purposes, since
t
he
y
’
r
el
i
k
e
l
yt
opr
od
uc
ev
e
r
ydi
f
f
e
r
e
ntt
e
s
tr
e
s
ul
t
s
.
A useful tool to employ during this iterative design process is to encourage users to
thinkoutl
o
uda
st
he
y
’
r
eus
i
n
gt
hes
of
t
wa
r
e
.Thi
sv
e
r
ba
l
i
s
a
t
i
ono
fus
e
r
s
’t
h
oug
ht
s
helps track not just what users are doing but why t
he
y
’
r
ed
oi
ngi
t
,
a
l
l
owi
ngy
out
o
locate potential stumbling blocks and areas that cause confusion. Make sure though
that youa
c
t
ua
l
l
ya
na
l
y
s
eaus
e
r
’
sc
o
mme
nt
sa
b
ou
tp
ot
e
nt
i
a
lpr
ob
l
e
ms
.I
faus
e
r
misses an item in a dialog or misreads a message, they may end up in trouble at some
point further down the road, and come up with complex rationalisations about why
the application i
sbr
ok
e
na
tt
h
epoi
ntwhe
r
et
he
yr
e
a
l
i
s
et
h
a
tt
he
y
’
r
ei
nt
r
o
ubl
e
,
r
a
t
he
r
than at the point where they originally made the error.
Note also that the very act of verbalising (and having to provide an explanation for)
their actions can make a user think muchmor
ea
bo
utwha
tt
he
y
’
r
ed
oi
ng
,
a
nda
sa
r
e
s
ul
tc
ha
ng
et
he
i
rbe
h
a
v
i
our
.Te
s
t
swi
t
hus
e
r
sha
v
es
h
ownt
ha
tt
he
y
’
r
emu
c
hbe
t
t
e
r
a
tpe
r
f
or
mi
ngaus
e
ri
nt
e
r
f
a
c
et
a
s
kwhe
nt
he
y
’
r
er
e
qu
i
r
e
dt
ot
hi
nkoutl
ou
da
b
ou
twha
t
t
he
y
’
r
edoi
ng
.
To get around this, you can allow the user to perform less thinking out loud, and
i
ns
t
e
a
dpr
o
mptt
he
ma
tv
a
r
i
ou
spoi
nt
sf
ort
h
oug
ht
sonwha
tt
he
y
’
r
edoi
ng
.As
k
i
ng
que
s
t
i
o
nsl
i
k
e“
Wh
a
td
oy
oue
x
pe
c
twi
l
lha
pp
e
ni
fy
oud
ot
hi
s
?
”or“
I
st
ha
twha
ty
ou
e
x
pe
c
t
e
dwou
l
dh
a
p
pe
n
?
”a
r
ee
x
c
e
l
l
ent ways of turning up flawed assumptions in
your design.
A variation of thinking out loud is constructive interaction, in which two users use a
s
y
s
t
e
mt
og
e
t
he
ra
ndc
o
mme
n
tone
a
c
hot
he
r
’
sa
c
t
i
o
ns(
i
ma
g
i
ney
ourp
a
r
e
nt
ss
i
t
t
i
ngi
n
front of their PC trying to figure out how to send a photo attachment via their Hotmail
account). This type of feedback-gathering is somewhat more natural than thinking
outl
o
ud,
s
ot
he
r
e
’
sl
e
s
sc
ha
nc
eofe
x
p
e
r
i
me
n
t
a
lbi
a
sb
e
i
ngi
nt
r
o
duc
e
d.

Usability Testing

Post-delivery Reviews
A final stage of testing is the post-delivery review, sometimes referred to as a
retrospective. Most advocates of this process suggest that 3-12 months after release
is the best time to carry out this type of review, this being the point at which users
have become sufficiently familiar with the software to locate problem areas, and at
which point the software has had sufficient exposure to the real world to reveal any
flaws in the design or its underlying assumptions.
Post-delivery reviews are important for shaking out emergent properties unanticipated
by the designers that even post-i
mpl
e
me
n
t
a
t
i
o
nt
e
s
t
i
ngwi
t
hus
e
r
sc
a
n
’
tl
oc
a
t
e
.For
example when the folks who wrote RFC 1738 provided for URLs of the form
user@hostname, they never considered that an opponent could use this to
construct URLs like http://www.bankofamerica.com@1234567/, which
points to a server whose numeric IP address is 1234567 while appearing to users to be
al
e
g
i
t
i
ma
t
eb
a
nks
e
r
v
e
r
’
sa
dd
r
e
s
s
.Te
s
t
i
ngi
nahos
t
i
l
ee
nv
i
r
on
me
n
t(
t
her
e
a
lwor
l
d)
provides addition
a
lf
e
e
dba
c
kons
e
c
ur
eus
e
ri
n
t
e
r
f
a
c
ede
s
i
g
n.Al
t
ho
ug
hi
t
’
su
nl
i
k
e
l
y
that attackers will cooperate in performing this type of testing for you, over the years
a large body of knowledge has been established that you can use to ensure that your
application doe
s
n’
ts
u
f
f
e
rf
r
o
mt
hes
a
mewe
a
k
ne
s
s
e
s
.Bo
o
k
sons
e
c
ur
epr
og
r
a
mmi
ng
like Building Secure Software by John Viega and Gary McGraw and Writing Secure
Software by Michael Howard and David LeBlanc contain in-depth discussions of
“
f
e
a
t
ur
e
s
”t
oa
v
o
i
dwhe
ny
ouc
reate an application that needs to process or display
security-relevant information.

Data Enveloping

Data Enveloping
Encryption envelopes are the easiest way to use cryptlib. An envelope is a container
object whose behaviour is modified by the data and resources that you push into it.
To use an envelope, you add to it other container and action objects and resources
such as passwords that control the actions performed by the envelope, and then push
in data and pop out data which is processed according to the resources you
’
v
ep
us
he
d
i
n.c
r
y
pt
l
i
bt
a
k
e
sc
a
r
eo
ft
her
e
s
t
.Fore
x
a
mpl
et
oe
nc
r
y
ptt
heme
s
s
a
g
e“
Thi
si
sa
s
e
c
r
e
t
”wi
t
ht
h
epa
s
s
wor
d“
Se
c
r
e
tpa
s
s
wor
d
”y
ouwou
l
dd
ot
hef
ol
l
owi
ng
:
create the envelope;
add the password attribute "Secret password" to the envelope;
push data "This is a secret" into the envelope;
pop encrypted data from the envelope;
destroy the envelope;

Tha
t
’
sa
l
lt
h
a
t
’
sne
c
e
s
s
a
r
y
.Si
nc
ey
ou
’
v
ea
d
de
dapa
s
s
wor
da
t
t
r
i
bu
t
e
,
c
r
y
pt
l
i
bk
nows
that you want to encrypt the data in the envelope with the password, so it encrypts the
data and returns it to you. This process is referred to as enveloping the data.
The opposite, de-enveloping process consists of:
create the envelope;
push encrypted data into the envelope;
add the password attribute "Secret password" to the envelope;
pop decrypted data from the envelope;
destroy the envelope;

c
r
y
pt
l
i
bk
nowst
het
y
p
eo
fe
n
c
r
y
pt
e
dd
a
t
at
ha
ti
t
’
swor
k
i
ngwi
t
h(
i
tc
a
ni
nf
or
my
o
u
t
ha
ty
oune
e
dt
opus
hi
napa
s
s
wor
di
fy
oudo
n’
tk
nowt
ha
ti
na
dv
a
nc
e
)
,
de
c
r
y
p
t
si
t
with the provided password, and returns the result to you.
This example illustrates a feature of the de-enveloping process that may at first seem
slightly unusual: You have to push in some encrypted data before you can add the
password attribute needed to decrypt it. This is because cryptlib will automatically
determine what to do with the data you give it, so if you added a password before you
pus
h
e
di
nt
h
ee
n
c
r
y
pt
e
dda
t
ac
r
y
pt
l
i
bwoul
dn
’
tk
n
owwha
tt
od
owi
t
ht
hep
a
s
s
wor
d.
Signing data is almost identical, except that you add a signature key attribute instead
of a password. You can also add a number of other encryption attributes depending
on the type of functionality you want. Since all of these require further knowledge of
c
r
y
pt
l
i
b’
sc
a
pa
bi
l
i
t
i
e
s
,
on
l
yb
a
s
i
cda
ta, compressed-data, and password-based
enveloping will be covered in this section.
Duet
oc
ons
t
r
a
i
n
t
si
nt
heu
nd
e
r
l
y
i
ngda
t
af
or
ma
t
st
ha
tc
r
y
pt
l
i
bs
u
pp
or
t
s
,
y
ouc
a
n
’
t
perform more than one of compression, encryption, or signing using a single
envelope (ther
e
s
ul
t
i
ngda
t
as
t
r
e
a
mc
a
n
’
tb
ee
nc
od
e
dus
i
ngmos
to
ft
h
ec
o
mmo
nda
t
a
formats supported by cryptlib). If you want to perform more than one of these
operations, you need to use multiple envelopes, one for each of the processing steps
you want to perform. If you try and add an encryption attribute to an envelope which
is set up for signing, or a signing attribute to an envelope which is set up for
encryption, or some other conflicting combination, cryptlib will return a parameter
error to indicate that the attribute type is invalid for this envelope since it is already
being used for a different purpose.

Creating/Destroying Envelopes
Envelopes are accessed through envelope objects that work in the same general
manner as the other container objects used by cryptlib. Before you can envelope or
de-envelope data you need to create the appropriate type of envelope for the job. If
you want to envelope some data, you would create the envelope with
cryptCreateEnvelope, specifying the user who is to own the device object or
CRYPT_UNUSED for the default, normal user, and the format for the enveloped data
(for now you should use CRYPT_FORMAT_CRYPTLIB, the default format):

The Data Enveloping Process

CRYPT_ENVELOPE cryptEnvelope;
cryptCreateEnvelope( &cryptEnvelope, cryptUser,
CRYPT_FORMAT_CRYPTLIB );
/* Perform enveloping */
cryptDestroyEnvelope( cryptEnvelope );

The Visual Basic version is:
Dim cryptEnvelope As Long
cryptCreateEnvelope cryptEnvelope, cryptUser, CRYPT_FORMAT_CRYPTLIB
' Perform enveloping
cryptDestroyEnvelope cryptEvelope

The C#, Java, and Python versions (here as elsewhere) migrate the output value to the
return value, and return errors by throwing exceptions. The Python version is:
cryptEnvelope = cryptCreateEnvelope( cryptUser,
CRYPT_FORMAT_CRYPTLIB )

The C# and Java version is:
int cryptEnvelope;
cryptEnvelope = crypt.CreateEnvelope( cryptUser,
crypt.FORMAT_CRYPTLIB );

If you want to de-envelope the result of the previous enveloping process, you would
create the envelope with format CRYPT_FORMAT_AUTO, which tells cryptlib to
automatically detect and use the appropriate format to process the data:
CRYPT_ENVELOPE cryptEnvelope;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
/* Perform de-enveloping */
cryptDestroyEnvelope( cryptEnvelope );

Note that the CRYPT_ENVELOPE is passed to the cryptCreateEnvelope by
reference as the function modifies it when it creates the envelope. In all other
routines in cryptlib, CRYPT_ENVELOPE is passed by value.
Some
t
i
me
swhe
ny
ou
’
r
epr
oc
e
s
s
i
ngda
t
ai
na
ne
nv
e
l
o
pe
,
y
oumay not be able to add
a
l
lo
ft
heda
t
ai
na
ne
nv
e
l
o
pe
,
f
ore
x
a
mpl
ewh
e
ny
ou
’
r
et
r
y
i
ngt
ode
-envelope a
me
s
s
a
g
et
ha
tha
sbe
e
nt
r
u
nc
a
t
e
dd
uet
oat
r
a
ns
mi
s
s
i
one
r
r
or
,
orwhe
ny
oudo
n
’
t
retrieve all of the processed data in the envelope before destroying it. When you
destroy the envelope cryptlib will return CRYPT_ERROR_INCOMPLETE as a
warning that not all of the data has been processed. The envelope will be destroyed
as usual, but the warning is returned to indicate that you should have added further
data or retrieved processed data before destroying the envelope.

The Data Enveloping Process
Although this section only covers basic data and password-based enveloping, the
concepts it covers apply to all the other types of enveloping as well, so you should
famil
i
a
r
i
s
ey
our
s
e
l
fwi
t
ht
hi
ss
e
c
t
i
one
v
e
ni
fy
o
u’
r
eonl
yp
l
a
nn
i
ngt
ous
et
h
emor
e
advanced types of enveloping such as digitally signed data enveloping. The general
model for enveloping data is:
add any attributes such as passwords or keys
push in data
pop out processed data

To de-envelope data:

Data Enveloping

push in data
(cryptlib will inform you what resource(s) it needs to process the
data)
add the required attribute such as a password or key
pop out processed data

The enveloping/de-enveloping functions perform a lot of work in the background.
For example when you add a password attribute to an envelope and follow it with
some data, the function hashes the variable-length password down to create a fixedlength key for the appropriate encryption algorithm, generates a temporary session
k
e
yt
ous
et
oe
nc
r
y
ptt
h
eda
t
ay
ou’
l
lbepus
hi
ngi
nt
ot
hee
nv
e
l
o
pe
,
us
e
st
hef
i
x
e
dlength key to encrypt the session key, encrypts the data (taking into account the fact
t
ha
tmos
te
nc
r
y
pt
i
onmo
de
sc
a
n’
te
n
c
r
y
pti
n
di
v
i
dua
lby
t
e
sbutr
e
qui
r
edata to be
present in fixed-length blocks), and then cleans up by erasing any keys and other
s
e
ns
i
t
i
v
ei
n
f
or
ma
t
i
o
ns
t
i
l
li
nme
mor
y
.Thi
si
swhyi
t
’
sr
e
c
omme
n
de
dt
ha
ty
ouus
et
he
envelope interface rather than trying to do the same thing yourself.
The cryptPushData and cryptPopData functions are used to push data into and pop
da
t
aou
to
fa
ne
nv
e
l
o
pe
.Fore
x
a
mp
l
et
opus
ht
heme
s
s
a
g
e“
He
l
l
owor
l
d”i
nt
oa
n
envelope, you would use:
cryptPushData( envelope, "Hello world", 11, &bytesCopied );

The same operation in C# and Java is:
int bytesCopied = crypt.PushData( envelope, "Hello world" );

In Python this is:
bytesCopied = cryptPushData( envelope,

"Hello world" )

The function will return an indication of how many bytes were copied into the
envelope in bytesCopied. Usually this is the same as the number of bytes you
pus
h
e
di
n,
bu
ti
ft
hee
nv
e
l
opei
sa
l
mos
tf
ul
lory
ou
’
r
et
r
y
i
n
gt
opus
hi
nav
e
r
yl
a
r
g
e
amount of data, only some of the data may be copied in. This is useful when you
want to process a large quantity of data in multiple sections, which is explained
further on.
Popping data works similarly to pushing data:
cryptPopData( envelope, buffer, bufferSize, &bytesCopied );

In this case you supply a buffer to copy the data to, and an indication of how many
bytes you want to accept, and the function will return the number of bytes actually
copied in bytesCopied. This could be anything from zero up to the full buffer
size, depending on how much data is present in the envelope.
Onc
ey
ou
’
v
epus
he
dt
hee
nt
i
r
equa
nt
i
ty of data that you want to process into an
envelope, you need to use cryptFlushData to tell the envelope object to wrap up the
data processing. If you try to push in any more data after this point, cryptlib will
return a CRYPT_ERROR_COMPLETE error to indicate that processing of the data
in the envelope has been completed and no more data can be added. Since the
enveloped data contains all the information necessary to de-e
nv
e
l
o
pei
t
,
i
ti
s
n
’
t
necessary to perform the final flush during de-enveloping.
You can add enveloping and de-enveloping attributes to an envelope in the usual
manner with cryptSetAttribute and cryptSetAttributeString. For example to add
t
hep
a
s
s
wor
d“
p
a
s
s
wor
d”t
oa
ne
nv
e
l
ope
,
y
ouwo
ul
ds
e
tt
heCRYPT_ENVI
NFO_PASSWORD attribute:
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
"password", 8 );

The same operation in Visual Basic is:
cryptSetAttributeString cryptEnvelope, CRYPT_ENVINFO_PASSWORD, _
"password", 8

The various types of attributes that you can add are explained in more detail further
on.

The Data Enveloping Process

Data Size Considerations
When you add data to an envelope, cryptlib processes and encodes it in a manner that
allows arbitrary amounts of data to be added. If cryptlib knows in advance how much
data will be pushed into the envelope, it can use a more efficient encoding method
s
i
nc
ei
td
oe
s
n
’
tha
v
et
ot
a
k
ei
nt
oa
c
c
o
un
ta
ni
nd
e
f
i
n
i
t
e
l
yl
o
ngda
t
as
t
r
e
a
m.Youc
a
n
notify cryptlib of the overall data size by setting the CRYPT_ENVINFO_DATASIZE
attribute:
cryptSetAttribute( envelope, CRYPT_ENVINFO_DATASIZE, dataSize );

This tells cryptlib how much data will be added, and allows it to use the more
efficient encoding format. If you push in more data than this before you wrap up the
processing with cryptFlushData, cryptlib will return CRYPT_ERROR_OVERFLOW; if you push in less, it will return CRYPT_ERROR_UNDERFLOW.
The
r
ei
so
nee
x
c
e
p
t
i
ont
ot
hi
sr
ul
ewhi
c
hoc
c
ur
swhe
ny
ou
’
r
eus
i
ngt
he
PGP/OpenPGP data format. PGP requires that the length be indicated at the start of
every message, so you always have to set the CRYPT_ENVINFO_DATASIZE
attribute when you perform PGP enveloping. If you try and push data into a PGP
envelope without setting the data size, cryptlib will return CRYPT_ERROR_NOTI
NI
TEDt
ot
e
l
ly
out
ha
ti
tc
a
n
’
te
nv
e
l
o
pet
hed
a
t
awi
t
h
out knowing its overall
s
i
z
ei
na
dv
a
n
c
e
.PGP/
Ope
n
PGPe
nv
e
l
opi
ngi
se
x
pl
a
i
ne
di
nmor
ede
t
a
i
li
n“
PGP”on
page 95.
The amount of data popped out of an envelope never matches the amount pushed in,
because the enveloping process adds encryption headers, digital signature
information, and assorted other paraphernalia which is required to process a message.
In many cases the overhead involved in wrapping up a block of data in an envelope
can be noticeable, so you should always push and pop as much data at once into and
out of an envelope as you can. For example if you have a 100-byte message and push
it in as 10 lots of 10 bytes, this is much slower than pushing a single lot of 100 bytes.
This behaviour is identical to the behaviour in applications like disk or network I/O,
where writing a single big file to disk is a lot more efficient than writing 10 smaller
files, and writing a single big network data packet is more efficient than writing 10
smaller data packets.
Push and popping unnecessarily small blocks of data when the total data size is
unk
nownc
a
na
l
s
oa
f
f
e
c
tt
heo
v
e
r
a
l
le
nv
e
l
ope
dda
t
as
i
z
e
.I
fy
ouha
v
e
n
’
tt
ol
dc
r
y
pt
l
i
b
how much data you plan to process with CRYPT_ENVINFO_DATASIZE then each
time you pop a block of data from an envelope, cryptlib has to wrap up the current
block and add header information to it to allow it to be de-enveloped later on.
Because this encoding overhead consumes extra space, you should again try to push
and pop a single large data block rather than many small ones (to prevent worst-case
behaviour, cryptlib will coalesce adjacent small blocks into a minimum block size of
10by
t
e
s
,
s
oi
twon
’
tr
e
t
ur
na
ni
nd
i
v
i
du
a
lb
l
oc
kc
o
nt
a
i
ni
ngl
e
s
st
ha
n10by
t
e
sun
l
e
s
s
i
t
’
st
hel
a
s
tb
l
oc
kin the envelope). This is again like disk data storage or network
I/O, where many small files or data packets lead to greater fragmentation and wasted
storage space or network overhead than a single large file or packet.
By default the envelope object which is created will have a 16K data buffer on DOS
and 16-bit Windows systems, and a 32K buffer elsewhere. The size of the internal
buffer affects the amount of extra processing that cryptlib needs to perform; a large
buffer will reduce the amount of copying to and from the buffer, but will consume
more memory (the ideal situation to aim for is one in which the data fits completely
within the buffer, which means that it can be processed in a single operation). Since
the process of encrypting and/or signing the data can increase its overall size, you
should make the buffer 1-2K larger than the total data size if you want to process the
data in one go. The minimum buffer size is 4K, and on 16-bit systems the maximum
buffer size is 32K-1.
If want to use a buffer which is smaller or larger than the default size, you can specify
its size using the CRYPT_ATTRIBUTE_BUFFERSIZE attribute after the envelope
has been created. For example if you knew you were going to be processing a single

Data Enveloping
80K message on a 32-bit syste
m(
y
ouc
a
n
’
tpr
o
c
e
s
smor
et
ha
n32K-1 bytes at once on
a 16-bit system) you would use:
CRYPT_ENVELOPE cryptEnvelope;
cryptCreateEnvelope( &cryptEnvelope, cryptUser,
CRYPT_FORMAT_CRYPTLIB );
cryptSetAttribute( cryptEnvelope, CRYPT_ATTRIBUTE_BUFFERSIZE,
90000L );
/* Perform enveloping */
cryptDestroyEnvelope( cryptEnvelope );

(the extra 10K provides a generous safety margin for message expansion due to the
enveloping process). When you specify the size of the buffer, you should try and
make it as large as pos
s
i
bl
e
,
u
nl
e
s
sy
ou
’
r
epr
e
t
t
yc
e
r
t
a
i
ny
o
u’
l
lo
nl
ybes
e
e
i
ng
messages up to a certain size. Remember, the larger the buffer, the less processing
overhead is involved in handling data. However, if you make the buffer excessively
large it increases the pro
ba
bi
l
i
t
yt
ha
tt
heda
t
ai
ni
twi
l
lbes
wa
ppe
dou
tt
odi
s
k
,
s
oi
t
’
s
ag
oodi
de
an
ott
og
oov
e
r
boa
r
donb
uf
f
e
rs
i
z
e
.Youdo
n’
tha
v
et
opr
oc
e
s
st
hee
n
t
i
r
e
message at once, cryptlib provides the ability to envelope or de-envelope data in
multiple sections to allow processing of arbitrary amounts of data even on systems
with only small amounts of memory available.

Basic Data Enveloping
In the simplest case the entire message you want to process will fit into the
e
nv
e
l
o
pe
’
si
n
t
e
r
n
a
lb
uf
f
e
r
.Thes
i
mp
l
e
s
tt
y
p
eo
fenveloping does nothing to the data
at all, but just wraps it and unwraps it:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
/* Create the envelope */
cryptCreateEnvelope( &cryptEnvelope, cryptUser,
CRYPT_FORMAT_CRYPTLIB );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
/* Destroy the envelope */
cryptDestroyEnvelope( cryptEnvelope );

The Visual Basic equivalent is:
Dim cryptEnvelope As Long
Dim bytesCopied As Long
' Create the envelope
cryptCreateEnvelope cryptEnvelope, cryptUser, CRYPT_FORMAT_CRYPTLIB
' Add the data size information and data, wrap up the processing, and
' pop out the processed data
cryptSetAttribute cryptEnvelope, CRYPT_ENVINFO_DATASIZE, messageLength
cryptPushData cryptEnvelope, message, messageLength, bytesCopied
cryptFlushData cryptEnvelope
cryptPopData cryptEnvelope, envelopedData, envelopedDataBufferSize, _
bytesCopied
' Destroy the envelope
cryptDestroyEnvelope cryptEnvelope

The Python version is:
# Create the envelope
cryptEnvelope = cryptCreateEnvelope( cryptUser,
CRYPT_FORMAT_CRYPTLIB )

The Data Enveloping Process

# Add the data size information and data, wrap up the processing, and
# pop out the processed data
cryptEnvelope.ENVINFO_DATASIZE = len( message )
bytesCopied = cryptPushData( cryptEnvelope, message )
cryptFlushData( cryptEnvelope )
bytesCopied = cryptPopData( cryptEnvelope, envelopedData,
envelopedDataBufferSize )
# Destroy the envelope
cryptDestroyEnvelope( cryptEnvelope )

The C# or Java version is:
int bytesCopied;
// Create the envelope
cryptEnvelope = crypt.CreateEnvelope( cryptUser,
crypt.FORMAT_CRYPTLIB );
// Add the data size information and data, wrap up the processing, and
// pop out the processed data
crypt.SetAttribute( cryptEnvelope, crypt.ENVINFO_DATASIZE,
message.Length );
bytesCopied = crypt.PushData( cryptEnvelope, message );
crypt.FlushData( cryptEnvelope );
bytesCopied = crypt.PopData( cryptEnvelope, envelopedData,
envelopedDataBufferSize );
// Destroy the envelope
crypt.DestroyEnvelope( cryptEnvelope );

(the above code is for C#, the Java version is virtually identical except that the
message.Length of a C# byte array is message.length in Java).
To de-envelope the resulting data you would use:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
/* Create the envelope */
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
/* Push in the enveloped data and pop out the recovered message */
cryptPushData( cryptEnvelope, envelopedData, envelopedDataSize,
&bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, message, messageBufferSize,
&bytesCopied );
/* Destroy the envelope */
cryptDestroyEnvelope( cryptEnvelope );

The Visual Basic form is:
Dim cryptEnvelope As Long
Dim bytesCopied As Long
' Create the envelope
cryptCreateEnvelope cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO
' Push in the enveloped data and pop out the recovered message
cryptPushData cryptEnvelope, envelopedData, envelopedDataSize, _
bytesCopied
cryptFlushData cryptEnvelope
cryptPopData cryptEnvelope, message, messageBufferSize, bytesCopied
' Destroy the envelope
cryptDestroyEnvelope cryptEnvelope

Thi
st
y
peofe
nv
e
l
o
pi
ngi
s
n’
tt
e
r
r
i
bl
yus
e
f
u
l
,
bu
ti
td
oe
sd
e
mo
ns
t
r
a
t
eh
owt
he
enveloping process works.

Compressed Data Enveloping
A variation of basic data enveloping is compressed data enveloping which
compresses or decompresses data during the enveloping process. Compressing data

Data Enveloping

before signing or encryption improves the overall enveloping throughput
(compressing data and encrypting the compressed data is faster than just encrypting
the larger, uncompressed data), increases security by removing known patterns in the
data, and saves storage space and network bandwidth.
To tell cryptlib to compress data that you add to an envelope, you should set the
CRYPT_ENVINFO_COMPRESSION attribute before you add the data. This
a
t
t
r
i
bu
t
ed
oe
s
n
’
tt
a
k
eav
a
l
ue
,
s
oy
ous
ho
ul
ds
e
ti
tt
oCRYPT_UNUSED.Thec
odet
o
compress a message is then:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser,
CRYPT_FORMAT_CRYPTLIB );
/* Tell cryptlib to compress the data */
cryptSetAttribute ( cryptEnvelope, CRYPT_ENVINFO_COMPRESSION,
CRYPT_UNUSED );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

De-enveloping compressed data works exactly like decompressing normal data,
cryptlib will transparently decompress the data for you and return the decompressed
result when you call cryptPopData.
The compression/decompression process can cause a large change in data size
between what you push and what you pop back out, so you typically end up pushing
much more than you pop or popping much more than you push. In particular, you
may end up pushing multiple lots of data before you can pop any compressed data
out, or pushing a single lot of compressed data and having to pop multiple lots of
decompressed data. This applies particularly to the final stages of enveloping when
you flush through any remaining data, which signals the compressor to wrap up
processing and move any remaining data into the envelope. This means that the flush
can return CRYPT_ERROR_OVERFLOW to indicate that there is more data to be
flushed, requiring multiple iterations of flushing and copying out data:
/* ... */
/* Flush out any remaining data */
do
{
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, outBuffer, BUFFER_SIZE, &bytesCopied
);
}
while( bytesCopied );

To handle this in a more general manner, you should use the processing techniques
de
s
c
r
i
be
di
n“
Enveloping Large Data Quantities”onpa
g
e71.

Password-based Encryption Enveloping
To do something useful (security-wise) to the data, you need to add a container or
action object or other type of attribute to tell the envelope to secure the data in some
way. For example if you wanted to encrypt a message with a password you would
use:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser,
CRYPT_FORMAT_CRYPTLIB );

The Data Enveloping Process

/* Add the password */
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
password, passwordLength );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

The same operation in Java (for C# replace the .length with .Length) is:
int cryptEnvelope = crypt.CreateEnvelope( cryptUser,
crypt.FORMAT_CRYPTLIB );
/* Add the password */
crypt.SetAttributeString( cryptEnvelope, crypt.ENVINFO_PASSWORD,
password );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
crypt.SetAttribute( cryptEnvelope, crypt.ENVINFO_DATASIZE,
message.length );
int bytesCopied = crypt.PushData( cryptEnvelope, message );
crypt.FlushData( cryptEnvelope );
bytesCopied = crypt.PopData( cryptEnvelope, envelopedData,
envelopedData.length );
crypt.DestroyEnvelope( cryptEnvelope );

To de-envelope the resulting data you would use:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
/* Push in the enveloped data and the password required to de-envelope
it, and pop out the recovered message */
cryptPushData( cryptEnvelope, envelopedData, envelopedDataLength,
&bytesCopied );
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
password, passwordLength );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, message, messageBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

The de-enveloping process in Java is:
int cryptEnvelope = crypt.CreateEnvelope( cryptUser,
crypt.FORMAT_AUTO );
int bytesCopied;
// Push in the enveloped data and the password required to
// de-envelope it, and pop out the recovered message
try {
bytesCopied = crypt.PushData( cryptEnvelope, envelopedData );
}
catch ( CryptException e ) {
if( e.getStatus() != crypt.ENVELOPE_RESOURCE )
throw e;
}
crypt.SetAttributeString( cryptEnvelope, crypt.ENVINFO_PASSWORD,
password );
crypt.FlushData( cryptEnvelope );
crypt.PopData( cryptEnvelope, messageBuffer, messageBuffer.length );
// Destroy the envelope
crypt.DestroyEnvelope( cryptEnvelope );

Data Enveloping

The Visual Basic equivalent is:
Dim cryptEnvelope As Long
Dim bytesCopied As Long
cryptCreateEnvelope cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO
' Push in the enveloped data and the password required to
' de-envelope it, and pop out the recovered message
cryptPushData cryptEnvelope, envelopedData, envelopedDataSize, _
bytesCopied
cryptSetAttributeString cryptEnvelope, CRYPT_ENVINFO_PASSWORD, _
password, Len( password )
cryptFlushData cryptEnvelope
cryptPopData cryptEnvelope, message, messageBufferSize, bytesCopied
' Destroy the envelope
cryptDestroyEnvelope cryptEnvelope

If you add the wrong password, cryptlib will return a CRYPT_ERROR_WRONGKEY error. You can use this to request a new password from the user and
try again. For example to give the user the traditional three attempts at getting the
password right you would replace the code to add the password with:
for( i = 0; i < 3; i++ )
{
password = ...;
if( cryptSetAttributeString( envelope, CRYPT_ENVINFO_PASSWORD,
password, passwordLength ) == CRYPT_OK )
break;
}

Conventional Encryption Enveloping
I
na
dd
i
t
i
ont
oe
nc
r
y
pt
i
nge
nve
l
o
pe
dda
t
awi
t
hapa
s
s
wor
d,
i
t
’
spos
s
i
bl
et
oby
p
a
s
st
he
password step and encrypt the data directly using an encryption context. This context
can either be used to encrypt the data directly (CRYPT_ENVINFO_SESSIONKEY)
or indirectly by wrapping up a session key (CRYPT_ENVINFO_KEY). For example
to encrypt data directly using IDEA with a raw session key you would do the
following:
CRYPT_ENVELOPE cryptEnvelope;
CRYPT_CONTEXT cryptContext;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser,
CRYPT_FORMAT_CRYPTLIB );
/* Create the session key context and add it */
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_IDEA );
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_KEY,
"0123456789ABCDEF", 16 );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_SESSIONKEY,
cryptContext );
cryptDestroyContext( cryptContext );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

To de-envelope the resulting data you would use:
CRYPT_ENVELOPE cryptEnvelope;
CRYPT_CONTEXT cryptContext;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );

The Data Enveloping Process

/* Push in the enveloped data and the session key context required to
de-envelope it, and pop out the recovered message */
cryptPushData( cryptEnvelope, envelopedData, envelopedDataLength,
&bytesCopied );
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_IDEA );
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_KEY,
"0123456789ABCDEF", 16 );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_SESSIONKEY,
cryptContext );
cryptDestroyContext( cryptContext );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, message, messageBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

Encrypting the data directly by using the context to wrap up the session key and then
encrypting the data with that functions identically, except that the context is added as
CRYPT_ENVINFO_KEY rather than CRYPT_ENVINFO_SESSIONKEY. The
only real difference between the two is the underlying data format that cryptlib
generates.
Raw session-k
e
yba
s
e
de
nv
e
l
opi
ngi
s
n’
tr
e
c
omme
n
de
ds
i
n
c
ei
tby
p
a
s
s
e
smuc
hoft
he
automated key management which is performed by the enveloping code, and requires
the direct use of low-level encryption contexts. If all you want to do is change the
und
e
r
l
y
i
nge
nc
r
y
pt
i
o
na
l
g
or
i
t
hmus
e
df
r
o
mt
h
ede
f
a
ul
tt
r
i
p
l
eDES,
i
t
’
se
a
s
i
e
rt
odo
this by setting the CRYPT_OPTION_ENCR_ALGO attribute for the envelope as
de
s
c
r
i
be
di
n“
Working with Configuration Options”o
npa
g
e 274.

De-enveloping Mixed Data
Some
t
i
me
sy
ouwo
n
’
tk
nowe
x
a
c
t
l
ywha
tt
y
peo
fpr
oc
e
s
s
i
n
gha
sbe
e
na
pp
l
i
e
dt
ot
he
da
t
ay
o
u’
r
et
r
y
i
ngt
ode
-envelope, so you can let cryptlib tell you what to do. When
cryptlib needs some sort of resource (such as a password or an encryption key) to
pr
oc
e
s
st
hed
a
t
at
ha
ty
o
u’
v
ep
us
he
di
n
t
oa
ne
nv
e
l
op
e
,
i
twi
l
lr
e
t
ur
naCRYPT_ENVELOPE_RESOURCE error if you try and push in any more data or pop out the
processed data. This error code is returned as soon as cryptlib knows enough about
t
hed
a
t
ay
o
u’
r
ep
us
h
i
ngi
nt
ot
hee
nv
e
l
op
et
obea
b
l
et
opr
oc
e
s
si
tpr
o
pe
r
l
y
.Ty
pi
c
a
l
l
y
,
as soon as you start pushing in encrypted, signed, or otherwise processed data,
cryptPushData will return CRYPT_ENVELOPE_RESOURCE to tell you that it
needs some sort of resource in order to continue.
If you knew that the data you were processing was either plain, unencrypted or
compressed data or password-encrypted data created using the code shown earlier,
you could de-envelope it with:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied, status;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
/* Push in the enveloped data and pop out the recovered message */
status = cryptPushData( cryptEnvelope, envelopedData,
envelopedDataLength, &bytesCopied );
if( status == CRYPT_ENVELOPE_RESOURCE )
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
password, passwordLength );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, message, messageBufferSize, &bytesCopied
);
cryptDestroyEnvelope( cryptEnvelope );

If the data is enveloped without any processing or is compressed data, cryptlib will
de-envelope it without requiring any extra input. If the data is enveloped using
password-based encryption, cryptlib will return CRYPT_ENVELOPE_RESOURCE
to indicate that it needs a password before it can continue.
This illustrates the manner in which the enveloped data contains enough information
to allow cryptlib to process it automatically. If the data had been enveloped using

Data Enveloping

some other form of processing (for example public-key encryption or digital
signatures), cryptlib would ask you for the private decryption key or the signature
c
he
c
kk
e
ya
tt
hi
st
i
me(
i
t
’
sa
c
t
ua
l
l
ys
l
i
g
ht
l
ymor
ec
o
mpl
e
xt
ha
nt
hi
s
,
t
hede
t
a
i
l
sa
re
e
x
pl
a
i
ne
di
n“
Enveloping with Multiple Attributes”onpa
g
e81).

De-enveloping with a Large Envelope Buffer
I
fy
ou’
v
ei
nc
r
e
a
s
e
dt
hee
nv
e
l
opebu
f
f
e
rs
i
z
et
oa
l
l
owt
hepr
oc
e
s
s
i
ngofl
a
r
g
eda
t
a
quantities, the de-enveloping process may be slightly different. When de-enveloping
data, cryptlib only reads an initial fixed amount of data before stopping and asking for
user input such as the password or private key which is required to process the data.
This is to avoid the situation where an envelope absorbs megabytes or even gigabytes
ofd
a
t
aon
l
yt
or
e
por
tt
ha
ti
tc
a
n’
te
v
e
nb
e
g
i
nt
opr
oc
e
s
si
tf
orl
a
c
kofade
c
r
y
pt
i
o
n
key. In this case the envelope will return CRYPT_ERROR_RESOURCE to indicate
that it re
q
ui
r
e
sf
ur
t
he
ri
n
f
or
ma
t
i
oni
nor
de
rt
oc
o
nt
i
n
ue
.Onc
ey
ou
’
v
ea
d
de
dt
he
necessary de-e
nv
e
l
o
pi
nga
t
t
r
i
but
e
(
s
)
,
y
ouc
a
ne
i
t
he
rp
opwha
t
’
sa
l
r
e
a
dybe
e
n
pr
oc
e
s
s
e
da
n
dc
o
nt
i
n
uea
sn
or
ma
l(
s
e
e“
Enveloping Large Data Quantities”o
npa
g
e
71) or, for a sufficiently large envelope buffer, push in the remaining data before
popping it all at once:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied, status;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
/* Push in the enveloped data and see if we need any special handling
*/
status = cryptPushData( cryptEnvelope, envelopedData,
envelopedDataLength, &bytesCopied );
if( status == CRYPT_ENVELOPE_RESOURCE )
{
/* Add the necessary de-enveloping attributes */
/* ... */
/* If only some of the data was accepted because the envelope
stopped to request further instructions, push in the rest now */
if( bytesCopied < envelopedDataLength )
{
int remainingBytesCopied;
status = cryptPushData( cryptEnvelope, envelopedData + bytesIn,
envelopedDataLength - bytesIn, &remainingBytesCopied );
bytesIn += remainingBytesCopied;
}
}
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, message, messageBufferSize, &bytesCopied
);
cryptDestroyEnvelope( cryptEnvelope );

This code checks whether the envelope has absorbed all of the enveloped data and, if
not, pushes the remainder after adding the attribute(s) necessary for processing it.
Once all the data has been pushed, it pops the result as usual.

Obtaining Envelope Security Parameters
If you want to know the details of the encryption mechanism which is being used to
protect the enveloped data, you can read various CRYPT_CTXINFO_xxx attributes
from the envelope object which will return information from the encryption
c
on
t
e
x
t
(
s
)t
ha
ta
r
ebe
i
ngus
e
dt
os
e
c
ur
et
heda
t
a
.Fore
x
a
mp
l
ei
fy
o
u’
r
ee
nc
r
y
pt
i
ngor
decrypting data you can get the encryption algorithm and mode and the key size
being used with:
CRYPT_ALGO_TYPE cryptAlgo;
CRYPT_MODE_TYPE cryptMode;
int keySize;
cryptGetAttribute( cryptEnvelope, CRYPT_CTXINFO_ALGO, &cryptAlgo );
cryptGetAttribute( cryptEnvelope, CRYPT_CTXINFO_MODE, &cryptMode );
cryptGetAttribute( cryptEnvelope, CRYPT_CTXINFO_KEYSIZE, &keySize );

Enveloping Large Data Quantities

Enveloping Large Data Quantities
Sometimes, a message may be too big to process in one go or may not be available in
its entirety, an example being data which is being sent or received over a network
interface where only the currently transmitted or received portion is available.
Al
t
ho
ug
hi
t
’
smuc
he
a
s
i
e
rt
opr
oc
e
s
same
s
s
a
g
ei
non
eg
o,i
t
’
sa
l
s
op
os
s
i
bl
et
o
envelope and de-envelope it a piece at a time (bearing in mind the earlier comment
that the enveloping is most efficient when you push and pop data a single large block
at a time rather than in many small blocks). With unknown amounts of data to be
pr
oc
e
s
s
e
di
tg
e
ne
r
a
l
l
yi
s
n
’
tpo
s
s
i
bl
et
ous
eCRYPT_ENVI
NFO_DATASI
ZE,
s
oi
n
the sample code below this is omitted.
There are several strategies for processing data in multiple parts. The simplest one
simply pushes and pops a fixed amount of data each time:
loop
push data
pop data

Si
nc
et
he
r
e
’
sal
i
t
t
l
eov
e
r
he
a
da
dde
dbyt
hee
nv
e
l
op
i
ngpr
oc
e
s
s
,
y
ous
ho
ul
da
l
wa
y
s
push in slightly less data than the envelope buffer size. Alternatively, you can use the
CRYPT_ATTRIBUTE_BUFFERSIZE to specify an envelope buffer which is slightly
larger than the data block size you want to use. The following code uses the first
technique to password-encrypt a file in blocks of BUFFER_SIZE –4K bytes:
CRYPT_ENVELOPE cryptEnvelope;
void *buffer;
int bufferCount;
/* Create the envelope with a buffer of size BUFFER_SIZE and add the
password attribute */
cryptCreateEnvelope( &cryptEnvelope, cryptUser,
CRYPT_FORMAT_CRYPTLIB );
cryptSetAttribute( cryptEnvelope, CRYPT_ATTRIBUTE_BUFFERSIZE,
BUFFER_SIZE );
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
password, passwordLength );
/* Allocate a buffer for file I/O */
buffer = malloc( BUFFER_SIZE );
/* Process the entire file */
while( !endOfFile( inputFile ) )
{
int bytesCopied;
/* Read a (BUFFER_SIZE - 4K) block from the input file, envelope
it, and write the result to the output file */
bufferCount = readFile( inputFile, buffer, BUFFER_SIZE - 4096 );
cryptPushData( cryptEnvelope, buffer, bufferCount, &bytesCopied );
cryptPopData( cryptEnvelope, buffer, BUFFER_SIZE, &bytesCopied );
writeFile( outputFile, buffer, bytesCopied );
}
/* Flush the last lot of data out of the envelope */
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, buffer, BUFFER_SIZE, &bytesCopied );
if( bytesCopied )
writeFile( outputFile, buffer, bytesCopied );
free( buffer );
cryptDestroyEnvelope( cryptEnvelope );

The Visual Basic version is:
Dim cryptEnvelope As Long
Dim buffer() As Byte
Dim bufferCount As Integer
Dim bytesCopied As Long

Data Enveloping

' Create the envelope with a buffer of size BUFFER_SIZE and add the
' password attribute
cryptCreateEnvelope cryptEnvelope, cryptUser, CRYPT_FORMAT_CRYPTLIB
cryptSetAttribute cryptEnvelope, CRYPT_ATTRIBUTE_BUFFERSIZE, _
BUFFER_SIZE
cryptSetAttributeString cryptEnvelope, CRYPT_ENVINFO_PASSWORD, _
password, Len( password )
' Allocate a buffer for file I/O
buffer = String( BUFFER_SIZE, vbNullChar )
Do While Not EndOfFile( inputFile )
' Read a (BUFFER_SIZE - 4K) block from the input file, envelope
' it, and write the result to an output file
bufferCount = ReadFile inputFile, buffer, BUFFERSIZE - 4096
cryptPushData cryptEnvelope, buffer, bufferCount, bytesCopied
cryptPopData cryptEnvelope, buffer, BUFFER_SIZE, bytesCopied
WriteFile outputFile, buffer, bytesCopied
Loop
cryptFlushData cryptEnvelope, buffer, BUFFER_SIZE, bytesCopied
If bytesCopied > 0 Then WriteFile outputFile, buffer, bytesCopied
cryptDestroyEnvelope cryptEnvelope

The code allocates a BUFFER_SIZE byte I/O buffer, reads up to BUFFER_SIZE –
4K bytes from the input file, and pushes it into the envelope. It then tells cryptlib to
pop up to BUFFER_SIZE bytes of enveloped data back out into the buffer, takes
whatever is popped out, and writes it to the output file. When it has processed the
entire file, it pushes in the usual zero-length data block to flush any remaining data
out of the buffer.
Not
et
h
a
tt
heu
ppe
rl
i
mi
tonBUFFER_SI
ZEde
pe
n
dsont
hes
y
s
t
e
my
ou
’
r
er
unn
i
ng
the code on. If you need to run it on a 16-bit system, BUFFER_SIZE is limited to
32K–
1 bytes because of the length limit imposed by 16-bit integers, and the default
envelope buffer size is 16K bytes unless you specify a larger default size using the
CRYPT_ATTRIBUTE_BUFFERSIZE attribute.
Going to a lot of effort to exactly match a certain data size such as a power of two
whe
np
us
hi
nga
ndpo
pp
i
ngda
t
ai
s
n
’
tr
e
a
l
l
ywor
t
hwhi
l
e
,
s
i
n
c
et
heov
e
r
he
a
da
d
de
dby
the envelope encoding will always change the final encoded data length.
Whe
ny
ou
’
r
epe
r
f
or
mi
ngc
ompr
e
s
s
e
dd
a
t
ae
nv
e
l
o
pi
ngorde
-enveloping, the
processing usually results in a large change in data size, in which case you may need
to use the technique described below that can handle arbitrarily-sized input and
output quantities.

Alternative Processing Techniques
A slightly more complex technique is to always stuff the envelope as full as possible
before trying to pop anything out of it:
loop
do
push data
while push status != CRYPT_ERROR_OVERFLOW
pop data

Thi
sr
e
s
ul
t
si
nt
hemos
te
f
f
i
c
i
e
ntus
eo
ft
hee
nv
e
l
ope
’
si
nt
e
r
na
lb
u
f
f
e
r
,
buti
spr
oba
bl
y
overkill for the amount of code complexity required:
CRYPT_ENVELOPE cryptEnvelope;
void *inBuffer, *outBuffer;
int bytesCopiedIn, bytesCopiedOut, bufferCount;
cryptCreateEnvelope( &cryptEnvelope, cryptUser,
CRYPT_FORMAT_CRYPTLIB );
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
password, passwordLength );
/* Allocate input and output buffers */
inBuffer = malloc( BUFFER_SIZE );
outBuffer = malloc( BUFFER_SIZE );

Enveloping Large Data Quantities

/* Process the entire file */
while( !endOfFile( inputFile ) )
{
int offset = 0;
/* Read a buffer full of data from the file and push and pop it
to/from the envelope */
bufferCount = readFile( inputFile, inBuffer, BUFFER_SIZE );
while( bufferCount )
{
/* Push as much as we can into the envelope */
cryptPushData( cryptEnvelope, inBuffer + offset, bufferCount,
&bytesCopiedIn );
offset += bytesCopiedIn;
bufferCount -= bytesCopiedIn;
/* If we couldn't push everything in, the envelope is full, so
we empty a buffers worth out */
if( bufferCount )
{
cryptPopData( cryptEnvelope, outBuffer, BUFFER_SIZE,
&bytesCopiedOut );
writeFile( outputFile, outBuffer, bytesCopiedOut );
}
}
}
/* Flush out any remaining data */
do
{
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, outBuffer, BUFFER_SIZE,
&bytesCopiedOut );
if( bytesCopiedOut)
writeFile( outputFile, outBuffer bytesCopiedOut );
}
while( bytesCopiedOut );
free( inBuffer );
free( outBuffer );
cryptDestroyEnvelope( cryptEnvelope );

Running the code to fill/empty the envelope in a loop is useful when a transformation
such as data compression, which dramatically changes the length of the
enveloped/de-e
nv
e
l
op
e
dda
t
a
,
i
sbe
i
nga
ppl
i
e
d.I
nt
hi
sc
a
s
ei
t
’
sn
otpos
s
i
bl
et
ot
e
l
l
how much data can still be pushed into or popped out of the envelope because the
length is transformed by the compr
e
s
s
i
ono
pe
r
a
t
i
o
n.I
t
’
sa
l
s
og
e
ne
r
a
l
l
yg
oodpr
a
c
t
i
c
e
to not write code that makes assumptions about the amount of internal buffer space
available in the envelope, the above code will make optimal use of the envelope
buffer no matter what its size.

Enveloping with Many Enveloping Attributes
There may be a special-case condition when you begin the enveloping that occurs if
you have added a large number of password, encryption, or keying attributes to the
envelope so that the header prepended to the enveloped data is particularly large. For
example if you encrypt a message with different keys or passwords for several dozen
recipients, the header information for all the keys could become large enough that it
oc
c
upi
e
sano
t
i
c
e
a
b
l
ep
or
t
i
onoft
hee
nv
e
l
o
pe
’
sbu
f
f
er. In this case you can push in a
small amount of data to flush out the header information, and then push and pop data
as usual:
add many password/encryption/keying attributes;
push a small amount of data;
pop data;
loop
push data;
pop data;

If you use this strategy then you can trim the difference between the envelope buffer
size and the amount of data you push in at once down to about 1K; the 4K difference

Data Enveloping

shown earlier took into account the fact that a little extra data would be generated the
first time data was pushed due to the overhead of adding the envelope header:
CRYPT_ENVELOPE cryptEnvelope;
void *buffer;
int bufferCount;
/* Create the envelope and add many passwords */
cryptCreateEnvelope( &cryptEnvelope, cryptUser,
CRYPT_FORMAT_CRYPTLIB );
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
password1, password1Length );
/* ... */
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
password100, password100Length );
buffer = malloc( BUFFER_SIZE );
/* Read up to 100 bytes from the input file, push it into the envelope
to flush out the header data, and write all the data in the
envelope to the output file */
bufferCount = readFile( inputFile, buffer, 100 );
cryptPushData( cryptEnvelope, buffer, bufferCount, &bytesCopied );
cryptPopData( cryptEnvelope, buffer, BUFFER_SIZE, &bytesCopied );
writeFile( outputFile, buffer, bytesCopied );
/* Process the entire file */
while( !endOfFile( inputFile ) )
{
int bytesCopied;
/* Read a BUFFER_SIZE block from the input file, envelope it, and
write the result to the output file */
bufferCount = readFile( inputFile, buffer, BUFFER_SIZE );
cryptPushData( cryptEnvelope, buffer, bufferCount, &bytesCopied );
cryptPopData( cryptEnvelope, buffer, BUFFER_SIZE, &bytesCopied );
writeFile( outputFile, buffer, bytesCopied );
}
/* Flush the last lot of data out of the envelope */
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, buffer, BUFFER_SIZE, &bytesCopied );
if( bytesCopied )
writeFile( outputFile, buffer, bytesCopied );
free( buffer );
cryptDestroyEnvelope( cryptEnvelope );

In the most extreme case (hundreds or thousands of passwords, encryption, or keying
attributes added to an envelope), the header could fill the entire envelope buffer, and
you would need to pop the initial data in multiple sections before you could process
any more data using the usual push/pop loop. If you plan to use this many resources,
i
t
’
sbe
t
t
e
rt
os
p
e
c
i
f
yt
heus
eo
fal
a
r
g
e
re
nv
e
l
opeb
u
f
f
e
rus
i
ng
CRYPT_ATTRIBUTE_BUFFERSIZE in order to eliminate the need for such
special-case processing for the header.
De-enveloping data that has been enveloped with multiple keying resources also has
special requirements and is covered in the next section.

Public-Key Encrypted Enveloping

Advanced Enveloping
The previous chapter covered basic enveloping concepts and simple password-based
enveloping. Extending beyond these basic forms of enveloping, you can also
envelope data using public-key encryption or digitally sign the contents of the
envelope. These types of enveloping require the use of public and private keys that
are explained in various other chapters that cover key generation, key databases, and
certificates.
cryptlib automatically manages objects such as public and private keys and keysets,
s
oy
ouc
a
nde
s
t
r
oyt
he
ma
ss
o
ona
sy
ou
’
v
epus
he
dt
h
e
minto the envelope. Although
the object will appear to have been destroyed, the envelope maintains its own
reference to it which it can continue to use for encryption or signing. This means that
instead of the obvious:
create the key object;
create the envelope;
add the key object to the envelope;
push data into the envelope;
pop encrypted data from the envelope;
destroy the envelope;
destroy the key object;

i
t
’
sa
l
s
oq
ui
t
es
a
f
et
ous
es
o
me
t
h
i
ngl
i
k
e
:
create the envelope;
create the key object;
add the key object to the envelope;
destroy the key object;
push data into the envelope;
pop encrypted data from the envelope;
destroy the envelope;

Keeping an object active for the shortest possible time makes it much easier to track,
i
t
’
sal
ote
a
s
i
e
rt
ol
e
tc
r
y
p
t
l
ib manage these things for you by handing them off to the
envelope.

Public-Key Encrypted Enveloping
Public-key based enveloping works just like password-based enveloping except that
instead of adding a password attribute you add a public key or certificate (when
encrypting) or a private decryption key (when decrypting). For example if you
wanted to encrypt data using a public key contained in pubKeyContext, you
would use:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser,
CRYPT_FORMAT_CRYPTLIB );
/* Add the public key */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_PUBLICKEY,
pubKeyContext );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

You can also use a certificate in place of the public key, the envelope will handle both
in the same way. The certificate is typically obtained by reading it from a keyset,
either directly using cryptGetPublicKey as describedi
n“
Reading a Key from a
Keyset”onp
a
g
e141, or by setting the CRYPT_ENVINFO_RECIPIENT attribute as
de
s
c
r
i
be
di
n“
S/MIME Enveloping”onpa
g
e86. Using the CRYPT_ENVINFO_-

Advanced Enveloping

RECIPIENT attribute is the preferred option since it lets cryptlib handle a number of
the complications that arise from reading keys for you.
When cryptlib encrypts the data in the envelope, it will use the algorithm specified
with the CRYPT_OPTION_ENCR_ALGO option. If you want to change the
encryption algorithm which is used, you can set the CRYPT_OPTION_ENCR_ALGO attribute for the envelope (or as a global configuration option) to the algorithm
type you want, as described in “
Working with Configuration Options”o
npa
g
e274.
Alternatively, you can push a raw session-key context into the envelope before you
push in a public key, in which case cryptlib will use the context to encrypt the data
rather than generating one itself.
The same operation in Java (for C# replace the .length with .Length) is:
int cryptEnvelope = crypt.CreateEnvelope( cryptUser,
crypt.FORMAT_CRYPTLIB );
/* Add the public key */
crypt.SetAttribute( cryptEnvelope, crypt.ENVINFO_PUBLICKEY,
pubKeyContext );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
crypt.SetAttribute( cryptEnvelope, crypt.ENVINFO_DATASIZE,
message.length );
int bytesCopied = crypt.PushData( cryptEnvelope, message );
crypt.FlushData( cryptEnvelope );
bytesCopied = crypt.PopData( cryptEnvelope, envelopedData,
envelopedData.length );
crypt.DestroyEnvelope( cryptEnvelope );

De-enveloping is slightly more complex since, unlike password-based enveloping,
there are different keys used for enveloping and de-enveloping. In the simplest case
if you know in advance which private decryption key is required to decrypt the data,
you can add it to the envelope in the same way as with password-based enveloping:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
/* Push in the enveloped data and the private decryption key required
to de-envelope it, and pop out the recovered message */
cryptPushData( cryptEnvelope, envelopedData, envelopedDataLength,
&bytesCopied );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_PRIVATEKEY,
privKeyContext );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, message, messageBufferSize, &bytesCopied
);
cryptDestroyEnvelope( cryptEnvelope );

Al
t
ho
ug
ht
hi
sl
e
a
dst
ov
e
r
ys
i
mp
l
ec
ode
,
i
t
’
ss
o
me
wha
ta
wk
wa
r
ds
i
nc
ey
ouma
ynot
know in advance which private key is required to decrypt a message. To make the
private key handling process easier, cryptlib provides the ability to automatically
fetch decryption keys from a private key keyset for you, so that instead of adding a
private key, you add a private key keyset object and cryptlib takes care of obtaining
the key for you. Alternatively, you can use a crypto device such as a smart card or
Fortezza card to perform the decryption.
Using a private key from a keyset is slightly more complex than pushing in the
private key directly since the private key stored in the keyset is usually encrypted or
PIN-protected and will require a password or PIN supplied by the user to access it.
This means that you have to supply a password to the envelope before the private key
can be used to decrypt the data in it. This works as follows:

Public-Key Encrypted Enveloping

create the envelope;
add the decryption keyset;
push encrypted data into the envelope;
if( required resource = private key )
add password to decrypt the private key;
pop decrypted data from the envelope;
destroy the envelope;

When you add the password, cryptlib will use it to try to recover the private key
stored in the keyset you added previously. If the password is incorrect, cryptlib will
return CRYPT_ERROR_WRONGKEY, otherwise it will recover the private key and
then use that to decrypt the data. The full code to decrypt public-key enveloped data
is therefore:
CRYPT_ENVELOPE cryptEnvelope;
CRYPT_ATTRIBUTE_TYPE requiredAttribute;
int bytesCopied, status;
/* Create the envelope and add the private key keyset and data */
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_KEYSET_DECRYPT,
privKeyKeyset );
cryptPushData( cryptEnvelope, envelopedData, envelopedDataLength,
&bytesCopied );
/* Find out what we need to continue and, if it's a private key, add
the password to recover it from the keyset */
cryptGetAttribute( cryptEnvelope, CRYPT_ATTRIBUTE_CURRENT,
&requiredAttribute );
if( requiredAttribute != CRYPT_ENVINFO_PRIVATEKEY )
/* Error */;
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
password, passwordLength );
cryptFlushData( cryptEnvelope );
/* Pop the data and clean up */
cryptPopData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

The Visual Basic equivalent is:
Dim cryptEnvelope As Long
Dim requiredAttribute As CRYPT_ATTRIBUTE_TYPE
Dim bytesCopied As Long
Dim status As Long
' Create the envelope and add the private key and data
cryptCreateEnvelope cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO
cryptSetAttribute cryptEnvelope, CRYPT_ENVINFO_KEYSET_DECRYPT, _
privateKeyset
cryptPushData cryptEnvelope, envelopedData, envelopedDataLength, _
bytesCopied
' Find out what we need to continue, and if it's a private key,
' add the password to recover it from the keyset
cryptGetAttribute cryptEnvelope, CRYPT_ATTRIBUTE_CURRENT, _
requiredAttribute
If ( requredAttribute <> CRYPT_ENVINFO_PRIVATEKEY ) Then
' Error
End If
cryptSetAttributeString cryptEnvelope, CRYPT_ENVINFO_PASSWORD, _
password, len( password )
cryptFlushData cryptEnvelope
' Pop the data and clean up
cryptPopData cryptEnvelope, message, messageLength, bytesCopied
cryptDestroyEnvelope cryptEnvelope

I
nt
heu
nus
ua
lc
a
s
ewhe
r
et
hepr
i
v
a
t
ek
e
yi
s
n’
tpr
ot
e
c
t
e
dbyapa
s
s
wor
dorPI
N,
t
he
r
e
’
snone
e
dt
oa
ddt
hepa
s
s
wor
ds
i
nc
ec
r
y
pt
l
i
bwi
l
lus
et
hepr
i
v
a
t
ek
e
yas soon as
you access the attribute information by reading it using cryptGetAttribute.
In order to ask the user for a password, it can be useful to know the name or label
attached to the private key so you can display it as part of the password request

Advanced Enveloping

message. You can obtain the label for the required private key by reading the
e
nv
e
l
o
pe
’
sCRYPT_ENVI
NFO_PRI
VATEKEY_LABELa
t
t
r
i
b
ut
e
:
char label[ CRYPT_MAX_TEXTSIZE + 1 ];
int labelLength;
cryptGetAttributeString( cryptEnvelope,
CRYPT_ENVINFO_PRIVATEKEY_LABEL, label, &labelLength );
label[ labelLength ] = '\0';

You can then use the key label when you ask the user for the password for the key.
Using a crypto device to perform the decryption is somewhat simpler since the PIN
will already have been entered after cryptDeviceOpen wa
sc
a
l
l
e
d,
s
ot
h
e
r
e
’
sn
one
e
d
to supply it as CRYPT_ENVINFO_PASSWORD. To use a crypto device, you add
the device in place of the private key keyset:
CRYPT_ENVELOPE cryptEnvelope;
CRYPT_ATTRIBUTE_TYPE requiredAttribute;
int bytesCopied, status;
/* Create the envelope and add the crypto device and data */
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_KEYSET_DECRYPT,
cryptDevice );
cryptPushData( cryptEnvelope, envelopedData, envelopedDataLength,
&bytesCopied );
/* Find out what we need to continue. Since we've told the envelope
to use a crypto device, it'll perform the decryption as soon as we
ask it to using the device, so we shouldn't have to supply anything
else */
cryptGetAttribute( cryptEnvelope, CRYPT_ATTRIBUTE_CURRENT,
&requiredAttribute );
if( requiredAttribute != CRYPT_ATTRIBUTE_NONE )
/* Error */;
cryptFlushData( cryptEnvelope );
/* Pop the data and clean up */
cryptPopData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

Note how cryptGetAttribute nowr
e
por
t
st
ha
tt
he
r
e
’
sn
ot
h
i
ngf
ur
t
he
rr
e
qu
i
r
e
d(
s
i
n
c
e
the envelope has used the private key in the crypto device to performed the
decryption), and you can continue with the de-enveloping process.
Code that can handle the use of either a private key keyset or a crypto device for the
decryption is a straightforward extension of the above:
CRYPT_ENVELOPE cryptEnvelope;
CRYPT_ATTRIBUTE_TYPE requiredAttribute;
int bytesCopied, status;
/* Create the envelope and add the keyset or crypto device and data */
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_KEYSET_DECRYPT,
cryptKeysetOrDevice );
cryptPushData( cryptEnvelope, envelopedData, envelopedDataLength,
&bytesCopied );
/* Find out what we need to continue. If what we added was a crypto
device, the decryption will occur once we query the envelope. If
what we added was a keyset, we need to supply a password for the
decryption to happen */
cryptGetAttribute( cryptEnvelope, CRYPT_ATTRIBUTE_CURRENT,
&requiredAttribute );
if( requiredAttribute != CRYPT_ATTRIBUTE_NONE )
{
char label[ CRYPT_MAX_TEXTSIZE + 1 ];
int labelLength;
if( requiredAttribute != CRYPT_ENVINFO_PASSWORD )
/* Error */;

Digitally Signed Enveloping

/* Get the label for the private key and obtain the required
password from the user */
cryptGetAttributeString( cryptEnvelope,
CRYPT_ENVINFO_PRIVATEKEY_LABEL, label, &labelLength );
label[ labelLength ] = '\0';
getPassword( label, password, &passwordLength );
/* Add the password required to decrypt the private key */
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
password, passwordLength );
}
cryptFlushData( cryptEnvelope );
/* Pop the data and clean up */
cryptPopData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

Digitally Signed Enveloping
Digitally signed enveloping works much like the other enveloping types except that
instead of adding an encryption or decryption attribute you supply a private signature
key (when enveloping) or a public key or certificate (when de-enveloping). For
example if you wanted to sign data using a private signature key contained in
sigKeyContext, you would use:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser,
CRYPT_FORMAT_CRYPTLIB );
/* Add the signing key */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE,
sigKeyContext );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

The signature key could be a native cryptlib key, but it could also be a key from a
crypto device such as a smart card or Fortezza card. They both work in the same way
for signing data.
The Java version of the signed enveloping process (for C# replace the .length with
.Length) is:
int cryptEnvelope = crypt.CreateEnvelope( cryptUser,
crypt.FORMAT_CRYPTLIB );
/* Add the public key */
crypt.SetAttribute( cryptEnvelope, crypt.ENVINFO_SIGNATURE,
sigKeyContext );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
crypt.SetAttribute( cryptEnvelope, crypt.ENVINFO_DATASIZE,
message.length );
int bytesCopied = crypt.PushData( cryptEnvelope, message );
crypt.FlushData( cryptEnvelope );
bytesCopied = crypt.PopData( cryptEnvelope, envelopedData,
envelopedData.length );
crypt.DestroyEnvelope( cryptEnvelope );

The Visual Basic equivalent is:
cryptCreateEnvelope cryptEnvelope, cryptUser, CRYPT_FORMAT_CRYPTLIB

Advanced Enveloping

' Add the signing key
cryptSetAttribute cryptEnvelope, CRYPT_ENVINFO_SIGNATURE, _
sigKeyContext
' Add the data size information and data, wrap up the processing,
' and pop out the processed data
cryptSetAttribute cryptEnvelope, CRYPT_ENVINFO_DATASIZE, messageLength
cryptPushData cryptEnvelope, message, messageLength, bytesCopied
cryptFlushData cryptEnvelope
cryptPopData cryptEnvelope, envelopedData, envelopedDataBufferSize, _
bytesCopied
cryptDestroyEnvelope cryptEnvelope

When cryptlib signs the data in the envelope, it will hash it with the algorithm
specified with the CRYPT_OPTION_ENCR_HASH option. If you want to change
the hashing algorithm which is used, you can set the CRYPT_OPTION_ENCR_HASH attribute for the envelope (or as a global configuration option) to the algorithm
t
y
pey
ouwa
nt
,
a
sd
e
s
c
r
i
b
e
di
n“
Working with Configuration Options”o
npa
g
e274.
Alternatively, you can push a hash context into the envelope before you push in a
signature key, in which case cryptlib will associate the signature key with the last
hash context you pushed in.
I
fy
ou’
r
ewor
r
i
e
da
b
ou
ts
o
meobs
c
ur
e(
a
ndr
a
t
he
ru
nl
i
k
e
l
y
)a
t
t
a
c
k
sonpr
i
v
a
t
ek
e
y
s
,
you can enable the CRYPT_OPTION_MISC_SIDECHANNELPROTECTION
opt
i
o
na
se
x
pl
a
i
n
e
di
n“
Working with Configuration Options”onpa
g
e274. Note that
enabling this option will slow down all private-key operations by up to 10%.
As with public-key based enveloping, verifying the signed data requires a different
key for this part of the operation, in this case a public key or key certificate. In the
simplest case if you know in advance which public key is required to verify the
signature, you can add it to the envelope in the same way as with the other envelope
types:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
/* Add the enveloped data and the signature check key required to
verify the signature, and pop out the recovered message */
cryptPushData( cryptEnvelope, envelopedData, envelopedDataLength,
&bytesCopied );
cryptFlushData( cryptEnvelope );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE,
sigCheckKeyContext );
cryptPopData( cryptEnvelope, message, messageBufferSize, &bytesCopied
);
cryptDestroyEnvelope( cryptEnvelope );

Al
t
ho
ug
ht
hi
sl
e
a
dst
ov
e
r
ys
i
mp
l
ec
ode
,
i
t
’
ss
o
me
wha
ta
wk
wa
r
ds
i
nc
ey
ouma
ynot
know in advance which public key or key certificate is required to verify the
signature on the message. To make the signature verification process easier, cryptlib
provides the ability to automatically fetch signature verification keys from a publickey keyset for you, so that instead of supplying a public key or key certificate, you
add a public-key keyset object before you start de-enveloping and cryptlib will take
care of obtaining the key for you. This option works as follows:
create the envelope;
add the signature check keyset;
push signed data into the envelope;
pop plain data from the envelope;
if( required resource = signature check key )
read signature verification result;

The full code to verify signed data is therefore:

Enveloping with Multiple Attributes

CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied, signatureResult, status;
/* Create the envelope and add the signature check keyset */
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_KEYSET_SIGCHECK,
sigCheckKeyset );
/* Push in the signed data and pop out the recovered message */
cryptPushData( cryptEnvelope, envelopedData, envelopedDataLength,
&bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, message, messageBufferSize,
&bytesCopied );
/* Determine the result of the signature check */
cryptGetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE_RESULT,
&signatureResult );

The same process in Java (for C# replace the .length with .Length) is:
/* Create the envelope and add the signature check keyset */
int cryptEnvelope = crypt.CreateEnvelope(cryptUser,
crypt.FORMAT_AUTO );
crypt.SetAttribute( cryptEnvelope, crypt.ENVINFO_KEYSET_SIGCHECK,
sigCheckKeyset );
/* Push in the signed data and pop out the recovered message */
int bytesCopied = crypt.PushData( cryptEnvelope, envelopedData );
crypt.FlushData( cryptEnvelope );
bytesCopied = crypt.PopData( cryptEnvelope, message, message.length );
/* Determine the result of the signature check */
int signatureResult = crypt.GetAttribute( cryptEnvelope,
crypt.ENVINFO_SIGNATURE_RESULT );

The Visual Basic version is:
Dim signatureResult As Long
' Create the envelope and add the signature check keyset
cryptCreateEnvelope cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO
cryptSetAttribute cryptEnvelope, CRYPT_ENVINFO_KEYSET_SIGCHECK, _
sigCheckKeyset
' Push in the signed data and pop out the recovered message
cryptPushData cryptEnvelope, envelopedData, envelopedDataLength, _
bytesCopied
cryptPopData cryptEnvelope, message, messageBufferSize, bytesCopied
' Determine the result of the signature check
cryptGetAttribute cryptEnvelope, CRYPT_ENVINFO_SIGNATURE_RESULT, _
signatureResult

The signature result will typically be CRYPT_OK (the signature verified), CRYPT_ERROR_SIGNATURE (the signature did not verify), or CRYPT_ERROR_NOTFOUND (the key needed to check the si
g
na
t
ur
ewa
s
n
’
tf
o
un
di
nt
hek
e
y
s
e
t
)
.
Most signed data in use today uses a format popularised in S/MIME that includes the
signature verification key with the data being signed as a certificate chain. For this
t
y
peo
fda
t
ay
oud
on
’
tne
e
dt
opr
ov
i
deas
i
g
na
t
ur
ev
e
r
i
f
i
c
a
t
i
onk
e
y
,
s
i
nc
ei
t
’
sa
l
r
e
a
dy
included with the signed data. Details on creating and processing data in this format
i
sg
i
v
e
ni
n“
S/MIME Enveloping”onpa
g
e86.

Enveloping with Multiple Attributes
Sometimes enveloped data can have multiple sets of attributes applied to it, for
example encrypted data might be encrypted with two different passwords to allow it
to be decrypted by two different people:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied
cryptCreateEnvelope( &cryptEnvelope, cryptUser,
CRYPT_FORMAT_CRYPTLIB );

Advanced Enveloping

/* Add two different passwords to the envelope */
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
password1, password1Length );
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
password2, password2Length );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

In this case either of the two passwords can be used to decrypt the data. This can be
extended indefinitely, so that 5, 10, 50, or 100 passwords could be used (of course
wi
t
h1
00d
i
f
f
e
r
e
ntpa
s
s
wor
dsa
bl
et
od
e
c
r
y
ptt
heda
t
a
,
i
t
’
sq
ue
s
t
i
on
a
b
l
ewhe
t
he
ri
t
’
s
worth the effort of encrypting it at all, however this sort of multi-user encryption
could be useful for public-key encrypting messages sent to collections of people such
as mailing lists). The same applies for public-key enveloping, in fact the various
encryption types can be mixed if required so that (for example) either a private
decryption key or a password could be used to decrypt data.
Similarly, an envelope can have multiple signatures applied to it:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied
cryptCreateEnvelope( &cryptEnvelope, cryptUser,
CRYPT_FORMAT_CRYPTLIB );
/* Add two different signing keys to the envelope */
cryptSetAttribute ( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE,
cryptSigKey1 );
cryptSetAttribute ( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE,
cryptSigKey2 );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

In this case the envelope will be signed by both keys. As with password-based
enveloping, this can also be extended indefinitely to allow additional signatures on
the data, although it would be somewhat unusual to place more than one or two
signatures on a piece of data.
When de-enveloping data that has been enveloped with a choice of multiple
attributes, cryptlib builds a list of the attributes required to decrypt or verify the
signature on the data, and allows you to query the required attribute information and
choose the one you want to work with.

Processing Multiple De-enveloping Attributes
The attributes required for de-enveloping are managed through the use of an attribute
c
ur
s
ora
sde
s
c
r
i
be
di
n“
Attribute Lists and ”onpa
g
e37. You can use the attribute
cursor to determine which attribute is required for the de-enveloping process. Once
y
ou’
r
ei
t
e
r
a
t
i
ngt
hr
oug
ht
hea
t
t
r
i
bu
t
e
s
,
a
l
lt
ha
t
’
sl
e
f
tt
odoi
st
op
l
ugi
nt
hea
ppr
o
pr
i
a
t
e
handler routines to manage each attribute requirement that could be encountered. As
soon as one of the attributes required to continue is added to the envelope, cryptlib
will delete the required-attribute list and continue, so the attempt to move the cursor
to the next entry in the list will fail and the program will drop out of the processing

Enveloping with Multiple Attributes

loop. For example to try a password against all of the possible passwords that might
decrypt the message that was enveloped above, you would use:
int status
/* Get the decryption password from the user */
password = ...;
if( cryptSetAttribute( envelope, CRYPT_ATTRIBUTE_CURRENT_GROUP,
CRYPT_CURSOR_FIRST ) == CRYPT_OK )
do
{
CRYPT_ATTRIBUTE_TYPE requiredAttribute;
/* Get the type of the required attribute at the cursor position
*/
cryptGetAttribute( envelope, CRYPT_ATTRIBUTE_CURRENT,
&requiredAttribute );
/* Make sure we really do require a password resource */
if( requiredAttribute != CRYPT_ENVINFO_PASSWORD )
/* Error */;
/* Try the password. If everything is OK, we'll drop out of the
loop */
status = cryptSetAttributeString( envelope,
CRYPT_ENVINFO_PASSWORD, password, passwordLength );
}
while( status == CRYPT_WRONGKEY && \
cryptSetAttribute( envelope, CRYPT_ATTRIBUTE_CURRENT_GROUP,
CRYPT_CURSOR_NEXT ) == CRYPT_OK );

This steps through each required attribute in turn and tries the supplied password to
see if it matches. As soon as the password matches, the data can be decrypted, and
we drop out of the loop and continue the de-enveloping process.
Toe
x
t
e
n
dt
h
i
sabi
tf
ur
t
h
e
r
,
l
e
t
’
sa
s
s
u
met
ha
tt
h
eda
t
ac
o
ul
dbee
nv
e
l
ope
dus
i
nga
password or a public key (requiring a private decryption key to decrypt it, either one
from a keyset or a crypto device such as a smart card or Fortezza card). The code
inside the loop above then becomes:
CRYPT_ATTRIBUTE_TYPE requiredAttribute;
/* Get the type of the required resource at the cursor position */
cryptGetAttribute( envelope, CRYPT_ATTRIBUTE_CURRENT,
&requiredAttribute );
/* If the decryption is being handled via a crypto device, we don't
need to take any further action, the data has already been
decrypted */
if( requiredAttribute != CRYPT_ATTRIBUTE_NONE )
{
/* Make sure we really do require a password attribute */
if( requiredAttribute != CRYPT_ENVINFO_PASSWORD && \
requiredAttribute != CRYPT_ENVINFO_PRIVATEKEY )
/* Error */;
/* Try the password. If everything is OK, we'll drop out of the
loop */
status = cryptSetAttributeString( envelope, CRYPT_ENVINFO_PASSWORD,
password, passwordLength );
}

I
fwha
t
’
sr
e
qu
i
r
e
di
saCRYPT_ENVI
NFO_PASSWORD,c
r
y
pt
l
i
bwi
l
la
pp
l
yi
t
di
r
e
c
t
l
yt
od
e
c
r
y
ptt
heda
t
a
.I
fwha
t
’
sr
e
q
ui
r
e
di
saCRYPT_ENVI
NFO_PRIVATEKEY, cryptlib will either use thec
r
y
pt
ode
v
i
c
et
ode
c
r
y
ptt
heda
t
ai
fi
t
’
s
available, or otherwise use the password to try to recover the private key from the
keyset and then use that to decrypt the data.
Iterating through each required signature attribute when de-enveloping signed data is
similar, but instead of trying to provide the necessary decryption information you
would provide the necessary signature check information (if requested, many
envelopes carry their own signature verification keys with them) and display the

Advanced Enveloping

resulting signature information. Unlike encryption de-enveloping attributes, cryptlib
won’
tde
l
e
t
et
hes
i
g
na
t
ur
ei
n
f
or
ma
t
i
ono
nc
ei
tha
sbe
e
npr
o
c
e
s
s
e
d,
s
oy
ouc
a
nr
e
-read
the information multiple times:
int status
if( cryptSetAttribute( envelope, CRYPT_ATTRIBUTE_CURRENT_GROUP,
CRYPT_CURSOR_FIRST ) == CRYPT_OK )
do
{
CRYPT_ATTRIBUTE_TYPE requiredAttribute;
int sigResult;
/* Get the type of the required attribute at the cursor position
*/
cryptGetAttribute( envelope, CRYPT_ATTRIBUTE_CURRENT,
&requiredAttribute );
/* Make sure we really do have signature */
if( requiredAttribute != CRYPT_ENVINFO_SIGNATURE )
/* Error */;
/* Get the signature result */
status = cryptSetAttribute( envelope,
CRYPT_ENVINFO_SIGNATURE_RESULT, & sigResult );
}
while( cryptStatusOK( status ) && \
cryptSetAttribute( envelope, CRYPT_ATTRIBUTE_CURRENT_GROUP,
CRYPT_CURSOR_NEXT ) == CRYPT_OK );

This steps through each signature in turn and reads the result of the signature
verification for that signature, stopping when an invalid signature is found or when all
signatures are processed.

Nested Envelopes
Sometimes it may be necessary to apply multiple levels of processing to data, for
example you may want to both sign and encrypt data. cryptlib allows enveloped data
to be arbitrarily nested, with each nested content type being either further enveloped
data or (finally) the raw data payload. For example to sign and encrypt data you
would do the following:
create the envelope;
add the signature key;
push in the raw data;
pop out the signed data;
destroy the envelope;
create the envelope;
add the encryption key;
push in the previously signed data;
pop out the signed, encrypted data;
destroy the envelope;

This nesting process can be extended arbitrarily with any of the cryptlib content
types.
Since cryptl
i
b’
se
nv
e
l
o
pi
ngi
s
n’
ts
e
ns
i
t
i
v
et
ot
hec
on
t
e
ntt
y
pe(
t
ha
ti
s
,
y
ouc
a
npus
hi
n
a
nyt
y
peo
fda
t
aa
n
di
t
’
l
lbee
nv
e
l
o
pe
di
nt
hes
a
mewa
y
)
,
youn
e
e
dt
on
ot
i
f
yc
r
y
pt
l
i
b
oft
hea
c
t
u
a
lc
o
nt
e
n
tt
y
pebe
i
nge
nv
e
l
ope
di
fy
o
u’
r
eus
i
ngne
s
t
e
de
nv
e
l
o
pe
s
.Youc
a
n
set the content type being enveloped using the CRYPT_ENVINFO_CONTENTTYPE attribute, giving as value the appropriate CRYPT_CONTENT_type. For example to specify that the data being enveloped is signed data, you would
use:
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_CONTENTTYPE,
CRYPT_CONTENT_SIGNEDDATA );

Thede
f
a
ul
tc
o
nt
e
ntt
y
p
ei
spl
a
i
nd
a
t
a
,
s
oi
fy
oudo
n’
te
x
pl
i
c
i
t
l
ys
e
tac
on
t
e
n
tt
y
pe
c
r
y
pt
l
i
bwi
l
la
s
s
umei
t
’
sj
us
tr
a
wda
t
a
.Theo
t
h
e
rc
on
t
e
n
tt
y
pe
sa
r
ede
s
c
r
i
be
di
n
“
Other Certificate Object Extensions”onp
a
g
e253.

Nested Envelopes

Using the nested enveloping example shown above, the full enveloping procedure
would be:
create the envelope;
add the signature key;
(cryptlib sets the content type to the default 'plain data')
push in the raw data;
pop out the signed data;
destroy the envelope;
create the envelope;
set the content type to 'signed data';
add the encryption key;
push in the previously signed data;
pop out the signed, encrypted data;
destroy the envelope;

This will mark the innermost content as plain data (the default), the next level as
signed data, and the outermost level as encrypted data.
Unwrapping nested enveloped data is the opposite of the enveloping process. For
each level of enveloped data, you can obt
a
i
ni
t
st
y
pe(
o
nc
ey
ou’
v
ep
us
he
de
n
oug
hof
it into the envelope to allow cryptlib to decode it) by reading the
CRYPT_ENVINFO_CONTENTTYPE attribute:
CRYPT_ATTRIBUTE_TYPE contentType;
cryptGetAttribute( cryptEnvelope, CRYPT_ENVINFO_CONTENTTYPE,
&contentType );

Processing nested enveloped data therefore involves unwrapping successive layers of
data until you finally reach the raw data content type.

S/MIME

S/MIME
S/MIME is a standard format for transferring signed, encrypted, or otherwise
processed data as a MIME-encoded message (for example as email or embedded in a
web page). The MIME-encoding is only used to make the result palatable to mailers,
i
t
’
sa
l
s
op
os
s
i
bl
et
opr
o
c
e
s
st
h
eda
t
awi
t
h
outt
heMI
MEe
n
c
odi
ng
.
The exact data formatting and terminology used requires a bit of further explanation.
In the beginning there was PKCS #7, a standard format for signed, encrypted, or
otherwise processed data. When the earlier PEM secure mail standard failed to take
off, PKCS #7 was wrapped up in MIME encoding and christened S/MIME version 2.
Eventually PKCS #7 was extended to become the Cryptographic Message Syntax
(
CMS)
,
a
ndwhe
nt
ha
t
’
swr
a
p
pe
di
nMI
MEi
t
’
sc
a
l
l
e
dS/
MI
MEv
e
r
s
i
on3.
I
npr
a
c
t
i
c
ei
t
’
ss
o
me
wha
tmor
ec
o
mp
l
i
c
a
t
e
dt
h
a
nt
hi
ss
i
nc
et
he
r
e
’
ss
i
g
ni
f
i
c
a
n
tbl
ur
r
i
ng
between S/MIME version 2 and 3 (and PKCS #7 and CMS). The main effective
difference between the two is that PKCS #7/SMIME version 2 is completely tied to
X.509 certificates, certification authorities, certificate chains, and other paraphernalia,
CMS can be used without requiring all these extras if necessary, and S/MIME version
3 restricts CMS back to requiring X.509 for S/MIME version 2 compatibility.
Thec
r
y
pt
l
i
bn
a
t
i
v
ef
or
ma
ti
sCMSus
e
di
nt
hec
o
n
f
i
g
ur
a
t
i
o
nt
ha
td
oe
s
n
’
tt
i
ei
tt
ot
he
use of certificates (
s
oi
t
’
l
lwor
kwi
t
hPGP/
Op
e
n
PGPk
e
y
s
,
r
a
wpub
l
i
c
/
pr
i
v
a
t
ek
e
y
s
,
and other keying information as well as with X.509 certificates). In addition to this
format, cryptlib also supports the S/MIME format which is tied to X.509 — this is
just the cryptlib native format restricted so that the full range of key management
opt
i
o
nsa
r
e
n
’
ta
v
a
i
l
a
bl
e
.I
fy
ouwa
n
tt
oi
nt
e
r
ope
r
a
t
ewi
t
ho
t
he
ri
mp
l
e
me
nt
a
t
i
ons
,
y
ou
s
hou
l
dus
et
h
i
sf
or
ma
ts
i
n
c
ema
nyi
mpl
e
me
nt
a
t
i
onsc
a
n
’
twor
kwi
t
ht
hene
we
rk
e
y
management options that were added in CMS.
You can specify the use of the restricted CMS/SMIME format when you create an
envelope with the formatting specifier CRYPT_FORMAT_CMS or CRYPT_FORMAT_SMI
ME(
t
he
y
’
r
ea
l
mos
ti
de
nt
i
c
a
l
,
t
hef
e
wmi
n
ordi
f
f
e
r
e
nc
e
sa
r
ee
x
pl
a
i
ne
d
i
n“
Extra Signature Information”onp
a
g
e92), which tells cryptlib to use the restricted
CMS/SMIME rather than the (default) unrestricted CMS format. You can also use
the format specifiers with cryptExportKeyEx and cryptCreateSignatureEx (which
t
a
k
ea
st
he
i
rt
hi
r
da
r
g
ume
ntt
h
ef
or
ma
ts
pe
c
i
f
i
e
r
)a
se
x
pl
a
i
n
e
di
n“
Exchanging Keys”
on page 193,
a
nd“
Signing Data”o
npa
g
e199.

S/MIME Enveloping
Al
t
ho
ug
hi
t
’
sp
os
s
i
b
l
et
ous
et
heS/
MI
MEf
or
ma
tdi
r
e
c
t
l
ywi
t
ht
hemi
d-level signature
and encryption functions, S/MIME requires a considerable amount of extra
pr
oc
e
s
s
i
nga
bov
ea
ndbe
y
on
dt
ha
tr
e
qui
r
e
dbyc
r
y
pt
l
i
b
’
sde
f
a
u
l
tf
or
ma
t
,
s
oi
t
’
se
a
s
i
e
s
t
to let cryptlib take care of this extra work for you by using the enveloping functions
to process S/MIME data.
To create an envelope that uses the S/MIME format, call cryptCreateEnvelope as
usual but specify a format type of CRYPT_FORMAT_SMIME instead of the usual
CRYPT_FORMAT_CRYPTLIB:
CRYPT_ENVELOPE cryptEnvelope;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_SMIME );
/* Perform enveloping */
cryptDestroyEnvelope( cryptEnvelope );

Creating the envelope in this way restricts cryptlib to using the standard X.509-based
S/MIME data format instead of the more flexible data format which is used for
envelopes by default.

S/MIME Enveloping

Encrypted Enveloping
S/MIME supports password-based enveloping in the same way as ordinary cryptlib
envelopes (in fact the two formats are identical). Public-key encrypted enveloping is
supported only when the public key is held in an X.509 certificate. Because of this
restriction the private decryption key must also have a certificate attached to it. Apart
from these restrictions, public-key based S/MIME enveloping works the same way as
standard cryptlib enveloping. For example to encrypt data using the key contained in
an X.509 certificate you would use:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_SMIME );
/* Add the certificate */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_PUBLICKEY,
certificate );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

Since the certificate will originally come from a keyset, a simpler alternative to
reading the certificate yourself and explicitly adding it to the envelope is to let
cryptlib do it for you by first adding the keyset to the envelope and then specifying
the email address of the recipient or recipients of the message with the CRYPT_ENVINFO_RECIPIENT attribute:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_SMIME );
/* Add the encryption keyset and recipient email address */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_KEYSET_ENCRYPT,
cryptKeyset );
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_RECIPIENT,
"person@company.com", 18 );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

The same thing in Java (for C# replace the .length with .Length) is:
int cryptEnvelope = crypt.CreateEnvelope( cryptUser,
crypt.FORMAT_SMIME );
/* Add the encryption keyset and recipient email address */
crypt.SetAttribute( cryptEnvelope, crypt.ENVINFO_KEYSET_ENCRYPT,
cryptKeyset );
crypt.SetAttributeString( cryptEnvelope, crypt.ENVINFO_RECIPIENT,
"person@company.com" );

S/MIME

/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
crypt.SetAttribute( cryptEnvelope, crypt.ENVINFO_DATASIZE,
message.length );
int bytesCopied = crypt.PushData( cryptEnvelope, message );
crypt.FlushData( cryptEnvelope );
bytesCopied = crypt.PopData( cryptEnvelope, envelopedData,
envelopedData.length );
crypt.DestroyEnvelope( cryptEnvelope );

The Visual Basic equivalent is:
cryptCreateEnvelope cryptEnvelope, cryptUser, CRYPT_FORMAT_SMIME
' Add the encryption keyset and recipient email address
cryptSetAttribute cryptEnvelope, CRYPT_ENVINFO_KEYSET_ENCRYPT, _
cryptKeyset
cryptSetAttributeString cryptEnvelope, CRYPT_ENVINFOR_RECIPIENT, _
"person@company.com", 18
' Add the data size information and data, wrap up the processing,
' and pop out the processed data
cryptSetAttribute cryptEnvelope, CRYPT_ENVINFO_DATASIZE, messageLength
cryptPushData cryptEnvelope, message, messageLength, bytesCopied
cryptFlushData cryptEnvelope
cryptPopData cryptEnvelope, envelopedData, envelopedDataBufferSize, _
bytesCopied
cryptDestroyEnvelope cryptEnvelope

For each message recipient that you add, cryptlib will look up the key in the
encryption keyset and add the appropriate information to the envelope to encrypt the
message to that person. This is the recommended way of handling public-key
encrypted enveloping, since it lets cryptlib handle the certificate details for you and
makes it possible to manage problem areas such as cases where the same email
address is present in multiple certificates of which only one is valid for message
encryption. If you want to handle this case yourself, you have to use a keyset query
to search the duplicate certificates and select the appropriate one as described in
“
Handling Multiple Certificates with the Same Name”onp
a
g
e145.
Thee
n
c
r
y
pt
i
onk
e
y
s
e
tdo
e
s
n
’
tha
v
et
obel
o
c
a
l
.I
fy
ouus
ea
nHTTPk
e
y
s
e
ta
s
de
s
c
r
i
be
di
n“
HTTP Keysets”onpa
g
e136, cryptlib will fetch the required certificate
directly from the remote CA, saving you the effort of having to maintain and update a
local set of certificates. This use of HTTP keysets makes it very easy to distribute
certificates over the Internet.
De-enveloping works as for standard enveloping:
CRYPT_ENVELOPE cryptEnvelope;
CRYPT_ATTRIBUTE_TYPE requiredAttribute;
int bytesCopied, status;
/* Create the envelope and add the private key keyset and data */
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_KEYSET_DECRYPT,
privKeyKeyset );
cryptPushData( cryptEnvelope, envelopedData, envelopedDataLength,
&bytesCopied );
/* Find out what we need to continue and, if it's a private key, add
the password to recover it */
cryptGetAttribute( cryptEnvelope, CRYPT_ATTRIBUTE_CURRENT,
&requiredAttribute );
if( requiredAttribute != CRYPT_ENVINFO_PRIVATEKEY )
/* Error */;
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PASSWORD,
password, passwordLength );
cryptFlushData( cryptEnvelope );
/* Pop the data and clean up */
cryptPopData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

S/MIME Enveloping

More information on public-key encrypted enveloping, including its use with crypto
de
v
i
c
e
ss
u
c
ha
ss
ma
r
tc
a
r
dsa
ndFor
t
e
z
z
ac
a
r
ds
,
i
sg
i
v
e
ni
n“
Public-Key Encrypted
Enveloping”onpa
g
e75.

Digitally Signed Enveloping
S/MIME digitally signed enveloping works just like standard enveloping except that
the signing key is restricted to one that has a full chain of X.509 certificates (or at
least a single certificate) attached to it. For example if you wanted to sign data using
a private key contained in sigKeyContext, you would use:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_SMIME );
/* Add the signing key */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE,
sigKeyContext );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

When you sign data in this manner, cryptlib includes any certificates attached to the
signing key alongside the message. Although you can sign a message using a key
wi
t
has
i
ng
l
ec
e
r
t
i
f
i
c
a
t
ea
t
t
a
c
h
e
dt
oi
t
,
i
t
’
ss
a
f
e
rt
ous
eon
et
ha
th
a
saf
ul
lc
e
r
t
i
f
i
c
a
t
e
chain associated with it because including only the key certificate with the message
requires that the recipient locate any other certificates that are required to verify the
s
i
g
na
t
ur
e
.Si
nc
et
h
e
r
e
’
snoe
a
s
ywa
yt
odot
hi
s
,
s
i
g
ni
ngame
s
s
a
g
eus
i
ngonl
ya
standalone certificate can cause problems when the recipient tries to verify the
signature.
Verifying the signature on the data works slightly differently from the normal
signature verification process since the signed data already carries with it the
c
o
mp
l
e
t
ec
e
r
t
i
f
i
c
a
t
ec
ha
i
nr
e
q
ui
r
e
df
orv
e
r
i
f
i
c
a
t
i
o
n.Thi
sme
a
nst
ha
ty
o
udo
n’
tha
v
e
to push a signature verification keyset or key into the envelope because the required
certificate is already included with the data:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied, sigCheckStatus;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
/* Push in the enveloped data and pop out the recovered message */
cryptPushData( cryptEnvelope, envelopedData, envelopedDataLength,
&bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, message, messageBufferSize, &bytesCopied
);
/* Determine the result of the signature check */
cryptGetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE_RESULT,
&sigCheckStatus );
cryptDestroyEnvelope( cryptEnvelope );

Since the certificate is included with the data, anyone could alter the data, re-sign it
with their own certificate, and then attach their certificate to the data. To avoid this
problem, cryptlib provides the ability to verify the chain of certificates, which works
i
nc
o
mbi
na
t
i
o
nwi
t
hc
r
y
pt
l
i
b’
sc
e
r
t
i
f
i
c
a
t
et
r
us
tma
na
g
e
r
.Youc
a
no
bt
a
i
nt
he
certificate object containing the signing certificate chain with:

S/MIME

CRYPT_CERTIFICATE cryptCertChain;
cryptGetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE,
&cryptCertChain );

You can work with this certificate chain as usual, for example you may want to
display the certificates and any related information to the user. At the least, you
should verify the chain using cryptCheckCert. You may also want to perform a
validity check using RTCS, revocation checking using CRLs or OCSP, and any other
certificate checks that you consider necessary. More details on working with
c
e
r
t
i
f
i
c
a
t
ec
ha
i
nsa
r
eg
i
v
e
ni
n“
Certificate Chains”onpa
g
e225, details on basic
signed enveloping (including its use with crypto devices like smart cards and
For
t
e
z
z
ac
a
r
ds
)a
r
eg
i
v
e
ni
n“
Digitally Signed Enveloping”onpa
g
e79, details on
v
a
l
i
di
t
yc
he
c
k
i
ngwi
t
hRTCSa
r
eg
i
v
e
ni
n“
Certificate Status Checking using RTCS”
on page 162,
a
ndde
t
a
i
l
so
nr
e
v
oc
a
t
i
onc
he
c
k
i
ngwi
t
hOCSPa
r
eg
i
v
e
ni
n“
Certificate
Revocation Checking using OCSP”o
npa
g
e167.

Detached Signatures
So far, the signature for the signed data has always been included with the data itself,
allowing it to be processed as a single blob. cryptlib also provides the ability to
create detached signatures in which the signature is held separate from the data. This
leaves the data being signed unchanged and produces a standalone signature as the
result of the encoding process.
To specify that an envelope should produce a detached signature rather than standard
s
i
g
ne
dda
t
a
,
y
ous
h
ou
l
ds
e
tt
h
ee
nv
e
l
o
pe
’
sCRYPT_ENVI
NFO_DETACHEDSIGNATURE a
t
t
r
i
bu
t
et
o‘
t
r
u
e
’(
a
nyno
nz
e
r
ov
a
l
ue
)b
e
f
or
ey
oupus
hi
na
nyda
t
a
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DETACHEDSIGNATURE,
1 );

Apart from that, the creation of detached signatures works just like the creation of
standard signed data, with the result of the enveloping process being the standalone
signature (without the data attached):
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_SMIME );
/* Add the signing key and specify that we're using a detached
signature */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE,
sigKeyContext );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DETACHEDSIGNATURE,
1 );
/* Add the data size information and data, wrap up the processing, and
pop out the detached signature */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, detachedSignature,
detachedSignatureBufferSize, &bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

Verifying a detached signature requires an extra processing step since the signature is
no longer bundled with the data. First, you need to push in the detached signature (to
t
e
l
lc
r
y
p
t
l
i
bwha
tt
od
owi
t
ha
nyf
ol
l
owi
ngda
t
a
)
.Af
t
e
ry
ou’
v
epus
he
di
nt
he
signature and followed it up with the usual cryptFlushData to wrap up the
processing, you need to push in the data that was signed by the detached signature as
the second processing step:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied, sigCheckStatus;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );

S/MIME Enveloping

/* Push in the detached signature */
cryptPushData( cryptEnvelope, detachedSignature, detachedSigLength,
&bytesCopied );
cryptPushData( cryptEnvelope, NULL, 0, NULL );
/* Push in the data */
cryptPushData( cryptEnvelope, data, dataLength, NULL );
cryptFlushData( cryptEnvelope );
/* Determine the result of the signature check */
cryptGetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE_RESULT,
&sigCheckStatus );
cryptDestroyEnvelope( cryptEnvelope );

Si
nc
et
hed
a
t
awa
s
n
’
te
nv
e
l
op
e
dt
obe
g
i
nwi
t
h,
t
h
e
r
e
’
sn
ot
hi
ngt
ode
-envelope, which
me
a
nst
h
e
r
e
’
snot
hi
ngt
opopoutoft
hee
nv
e
l
o
pea
pa
r
tf
r
o
mt
hes
i
g
ni
ngc
e
r
t
ificate
chain that you can obtain as before by reading the CRYPT_ENVINFO_SIGNATURE
attribute.
I
nc
a
s
ey
ou
’
r
eno
ts
ur
ewhe
t
h
e
ras
i
g
na
t
ur
ei
nc
l
ud
e
sda
t
aornot
,
y
ouc
a
nq
ue
r
yi
t
s
status by checking the value of the CRYPT_ENVINFO_DETACHEDSIGNATURE
attribute a
f
t
e
ry
ou
’
v
epus
he
di
nt
hes
i
g
na
t
ur
e
:
int isDetachedSignature;
/* Push in the signed enveloped data */
cryptPushData( cryptEnvelope, signedData, signedDataLength,
&bytesCopied );
/* Check the signed data type */
cryptGetAttribute( cryptEnvelope, CRYPT_ENVINFO_DETACHEDSIGNATURE,
&isDetachedSignature );
if( isDetachedSignature )
/* Detached signature */;
else
/* Signed data + signature */;

Alternative Detached Signature Processing
Besides the method described above there is a second way to verify a detached
signature which involves hashing the data yourself and then adding the hash to the
envelope rather than pushing the data into the envelope and having it hashed for you.
This is useful in situations where the signed data is present separate from the
signature, or is in a non-standard format (for example an AuthentiCode signed file)
t
ha
tc
a
n
’
tber
e
c
og
ni
s
e
dbyt
h
ee
nv
e
l
o
pi
ngc
ode
.
Verifying a detached signature in this manner is a slight variation of the standard
detached signature verification process in which you first add to the envelope the
hash value for the signed data and then push in the detached signature:
CRYPT_CONTEXT hashContext;
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied, sigCheckStatus;
/* Create the hash context and hash the signed data */
cryptCreateContext( &hashContext, cryptUser, CRYPT_ALGO_SHA );
cryptEncrypt( hashContext, signedData, dataLength );
cryptEncrypt( hashContext, signedData, 0 );
/* Create the envelope and add the hash */
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_HASH, hashContext );
cryptDestroyContext( hashContext );
/* Add the detached signature */
cryptPushData( cryptEnvelope, signatureData, signatureDataLength,
&bytesCopied );
cryptFlushData( cryptEnvelope );
/* Determine the result of the signature check */
cryptGetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE_RESULT,
&sigCheckStatus );

S/MIME

cryptDestroyEnvelope( cryptEnvelope );

When you push in the detached signature cryptlib will verify that the hash
i
n
f
or
ma
t
i
o
ni
nt
hes
i
g
na
t
ur
ema
t
c
h
e
st
heha
s
ht
ha
ty
ou
’
v
es
upp
l
i
e
d.I
ft
h
et
wod
on
’
t
match, cryptlib will return CRYPT_ERROR_SIGNATURE to indicate that the
s
i
g
na
t
ur
ec
a
n
’
tbev
e
r
i
f
i
e
dus
i
ngt
heg
i
v
e
nv
a
l
ue
s
.Be
c
a
us
eoft
hi
sc
h
e
c
k
,
y
oumus
t
add the hash before you push in the detached signature.

Extra Signature Information
S/MIME signatures can include with them extra information such as the time at
which the message was signed. Normally cryptlib will add and verify this
information for you auto
ma
t
i
c
a
l
l
y
,
wi
t
ht
hed
e
t
a
i
l
so
fwha
t
’
sa
d
de
dba
s
e
dont
he
setting of the CRYPT_OPTION_CMS_DEFAULTATTRIBUTES option as
de
s
c
r
i
be
di
n“
Working with Configuration Options”o
npa
g
e274. If this option is set
t
of
a
l
s
e(
z
e
r
o)
,
c
r
y
pt
l
i
bwo
n’
ta
dda
nya
dd
i
t
i
on
a
ls
i
g
na
t
ur
ei
nf
or
ma
t
i
on,
whi
c
h
minimises the size of the resulting signature. If this option is set to true (any nonzero
value), cryptlib will add default signing attributes such as the signing time for you.
You can also handle the extra signing information yourself if you require extra
c
on
t
r
olov
e
rwha
t
’
si
nc
l
ud
e
dwi
t
ht
hes
i
g
na
t
ur
e
.Thee
x
t
r
ai
n
f
or
ma
t
i
o
ni
ss
pe
c
i
f
i
e
da
s
a CRYPT_CERTTYPE_CMS_ATTRIBUTES certificate object. To include this
information with the signature you should add it to the envelope alongside the signing
key as CRYPT_ENVINFO_SIGNATURE_EXTRADATA:
CRYPT_ENVELOPE cryptEnvelope;
CRYPT_CERTIFICATE cmsAttributes;
/* Create the CMS attribute object */
cryptCreateCert( &cmsAttributes, cryptUser,
CRYPT_CERTTYPE_CMS_ATTRIBUTES );
/* ... */
/* Create the envelope and add the signing key and signature
information */
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_CMS );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE,
sigKeyContext );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE_EXTRADATA,
cmsAttributes );
cryptDestroyCert( cmsAttributes );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

You can also use this facility to extend or overwrite the attributes added by cryptlib.
For example if you wanted to add a security label to the data being signed, you would
add it to the CMS attribute object and add that to the envelope. cryptlib will then add
any additional required information (for example the signing time) and finally
generate the signature using the combined collection of attributes. This means that
you can fill in whatever attributes you want, and cryptlib till take care of the rest for
you.
Verifying a signature that includes this extra information works just like standard
signature verification since cryptlib handles it all for you. Just as you can obtain a
certificate chain from a signature, you can also obtain the extra signature information
from the envelope:
CRYPT_CERTIFICATE cmsAttributes;
cryptGetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE_EXTRADATA,
&cmsAttributes );

Timestamping

You can now work with the signing attributes as in the same manner as standard
certificate attributes, for example you may want to display any relevant information
t
ot
heus
e
r
.Mor
ed
e
t
a
i
l
so
nwor
k
i
ngwi
t
ht
he
s
ea
t
t
r
i
bu
t
e
sa
r
eg
i
v
e
ni
n“
Certificate
Extensions”o
np
a
g
e234,
a
ndt
hea
t
t
r
i
b
ut
e
st
he
ms
e
l
v
e
sa
r
ec
ov
e
r
e
di
n“
Other
Certificate Object Extensions”onp
a
g
e253.
The example above created a CRYPT_FORMAT_CMS envelope, which means that
cryptlib will add certain default signing attributes to the signature when it creates it.
If the envelope is created with CRYPT_FORMAT_SMIME instead of
CRYPT_FORMAT_CMS, cryptlib will add an extra set of S/MIME-specific
attributes that indicate the preferred encryption algorithms for use when an S/MIME
enabled mailer is used to send mail to the signer. This information is used for
backwards-compatibility reasons because many S/MIME mailers will quietly default
to using very weak 40-bi
tk
e
y
si
ft
h
e
y
’
r
en
ote
x
pl
i
c
i
t
l
yt
o
l
dt
ous
epr
op
e
re
nc
ryption
such as triple DES or AES (cryptlib will never use weakened encryption since it
doe
s
n’
te
v
e
npr
ov
i
det
hi
sc
a
p
a
bi
l
i
t
y
)
.
Because of this default-to-insecure encryption problem, cryptlib includes with a
CRYPT_FORMAT_SMIME signature additional information to indicate that the
sender should use a non-weakened algorithm such as triple DES, AES, CAST-128, or
IDEA. With a CRYPT_FORMAT_CMS signature this additional S/MIME-specific
i
n
f
or
ma
t
i
o
ni
s
n
’
tne
e
de
ds
oc
r
y
pt
l
i
bdo
e
s
n
’
ti
nc
l
ud
ei
t
.

Timestamping
In addition to the standard signature information which is provided by the signer,
cryptlib also supports the use of a message timestamp which is provided by an
external timestamp authority (TSA). Timestamping signed data in an envelope is
very simple and requires only the addition of a CRYPT_ENVINFO_TIMESTAMP
attribute to tell cryptlib which TSA to obtain the timestamp from. The TSA is
s
pe
c
i
f
i
e
da
saTSPs
e
s
s
i
o
nob
j
e
c
ta
sde
s
c
r
i
be
di
n“
Secure Sessions”onp
a
g
e105. For
example to specify a TSA located at http://www.timestamp.com/tsa/request.cgi, you would create the TSP session with:
CRYPT_SESSION cryptSession;
/* Create the TSP session and add the server name */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_TSP );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
"http://www.timestamp.com/tsa/request.cgi", 40 );

You can also specify additional session information in the usual manner for cryptlib
sessions, after which you add thes
e
s
s
i
ont
ot
hee
nv
e
l
o
pe
.Onc
ey
ou
’
v
ea
dd
e
di
t
,
y
ou
c
a
nd
e
s
t
r
oyi
ts
i
nc
ei
t
’
snowma
na
g
e
dbyt
hee
nv
e
l
o
pe
:
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_TIMESTAMP,
cryptSession );
cryptDestroySession( cryptSession );

When cryptlib signs the data in the envelope, it will communicate with the TSA to
obtain a timestamp on the signature, which is then included with the other signed
data. This timestamp can be verified at a later date to prove that the envelope was
indeed signed at the indicated time.
Since communicating with a TSA over a network can be a slow process, the signature
generation may take somewhat longer than usual. When the timestamp is created
c
r
y
pt
l
i
bdo
e
s
n
’
tc
o
mmun
i
c
a
t
ea
nypa
r
to
ft
heme
s
s
a
g
eora
n
yi
ndi
c
a
t
i
onofi
t
s
contents to the TSA, it merely sends it the message signature information which is
then countersigned by the TSA. In this way no confidential or sensitive information
is leaked to the outside world through the timestamping process.
A time-stamped message appears the same as a standard signed message, with the
exception that the timestamp data is present as additional signature information of
type CRYPT_ENVINFO_TIMESTAMP. You can read the timestamp data in the
same way that you read other extra signature information:

S/MIME

CRYPT_ENVELOPE timeStamp;
cryptGetAttribute( cryptEnvelope, CRYPT_ENVINFO_TIMESTAMP,
&timestamp );

The returned timestamp is a standard signed envelope object that you can check in the
usual manner, for example by verifying the signature on the timestamp data and
checking the certificates used for the timestamp signature.

PGP Enveloping

PGP
PGP is a standard format for encrypting, signing, and compressing data. The original
format, PGP 2.x or PGP classic, has since been superseded by OpenPGP, partially
implemented in PGP 5.0 and later fully in NAI PGP, GPG, and various variations
such as the ckt builds. cryptlib can read both the PGP 2.x and OpenPGP formats,
including handling for assorted variations and peculiarities of different
implementations. As output cryptlib produces data in the OpenPGP format, which
can be read by any recent PGP implementation. Note that PGP 2.x used the patented
I
DEAe
nc
r
y
pt
i
ona
l
g
or
i
t
h
m(
s
e
e“
Algorithms”onpa
g
e302 f
orde
t
a
i
l
s
)
,
i
fy
ou
’
r
e
using the code for commercial purposes you need to either obtain a license for IDEA
or use only the OpenPGP format (which cryptlib does by default anyway, so this
us
ua
l
l
yi
s
n
’
tac
onc
e
r
n)
.
You can specify the use of the PGP format when you create an envelope with the
formatting specifier CRYPT_FORMAT_PGP, which tells cryptlib to use the PGP
f
or
ma
tr
a
t
he
rt
ha
nt
he(
d
e
f
a
ul
t
)CMSf
or
ma
t
.c
r
y
pt
l
i
bdoe
s
n’
tr
e
s
t
r
i
c
tt
heus
eo
fPGP
envelopes to PGP keys. Any type of keys, including standard cryptlib keys and
X.509 ce
r
t
i
f
i
c
a
t
e
s
,
c
a
nbeus
e
dwi
t
hPGPe
nv
e
l
o
pe
s
.Bye
xt
e
ns
i
oni
t
’
sa
l
s
opos
s
i
bl
e
to use smart cards, crypto accelerators, and Fortezza cards with PGP envelopes (as an
e
x
t
r
e
mee
x
a
mp
l
e
,
i
t
’
sp
os
s
i
b
l
et
ous
eaFor
t
e
z
z
ac
a
r
dt
oc
r
e
a
t
eaPGPe
nv
e
l
op
e
)
.

PGP Enveloping
To create an envelope that uses the PGP format, call cryptCreateEnvelope as usual
but specify a format type of CRYPT_FORMAT_PGP instead of the usual
CRYPT_FORMAT_CRYPTLIB:
CRYPT_ENVELOPE cryptEnvelope;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_PGP );
/* Perform enveloping */
cryptDestroyEnvelope( cryptEnvelope );

Creating the envelope in this way restricts cryptlib to using the PGP data format
instead of the more flexible data format which is used for envelopes by default. This
imposes a number of restrictions on the use of envelopes that are described in more
detail in the sections that cover individual PGP enveloping types. One restriction that
applies to all enveloping types is that PGP requires the presence of the
CRYPT_ENVINFO_DATASIZE attribute before data can be enveloped. This
a
t
t
r
i
bu
t
ei
sde
s
c
r
i
be
di
nmor
ede
t
a
i
li
n“
Data Size Considerations”o
np
a
g
e63. If you
try to push data into an envelope without setting the CRYPT_ENVINFO_DATASIZE attribute, cryptlib will return CRYPT_ERROR_NOTINITED to indicate
t
ha
ty
ouha
v
e
n’
tpr
ov
i
d
e
dt
hei
n
f
or
ma
t
i
o
nwhi
c
hi
sne
e
de
df
ort
hee
nv
e
l
o
pi
ngt
o
proceed.

Encrypted Enveloping
PGP supports password-based enveloping in the same general way as ordinary
c
r
y
pt
l
i
be
nv
e
l
op
e
s
.Howe
v
e
r
,duet
oc
o
ns
t
r
a
i
nt
si
mpos
e
db
yt
hePGPf
or
ma
t
,
i
t
’
snot
possible to mix password- and public-key-based key exchange actions in the same
e
nv
e
l
o
pe
.I
na
d
di
t
i
o
ni
t
’
sn
otpos
s
i
bl
et
os
pe
c
i
f
ymor
et
ha
nonepa
s
s
wor
df
or an
envelope. If you try to add more than one password, or try to add a password when
y
ou’
v
ea
l
r
e
a
dya
d
de
dapu
bl
i
ck
e
yorv
i
c
ev
e
r
s
a
,
c
r
y
pt
l
i
bwi
l
lr
e
t
ur
n
CRYPT_ERROR_INITED to indicate that the key exchange action has already been
set.
Public-key based PGP enveloping works the same way as standard cryptlib
enveloping. For example to encrypt data using the a public key you would use:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_PGP );

PGP

/* Add the public key */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_PUBLICKEY,
publicKey );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

Since the key will originally have come from a keyset, a simpler alternative to
reading the key yourself and explicitly adding it to the envelope is to let cryptlib do it
for you by first adding the keyset to the envelope and then specifying the email
address of the recipient or recipients of the message with the CRYPT_ENVINFO_RECIPIENT attribute:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_PGP );
/* Add the encryption keyset and recipient email address */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_KEYSET_ENCRYPT,
cryptKeyset );
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_RECIPIENT,
"person@company.com", 18 );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

PGP Enveloping

/* Pop the data and clean up */
cryptPopData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

More information on public-key encrypted enveloping, including its use with crypto
de
v
i
c
e
ss
u
c
ha
ss
ma
r
tc
a
r
ds
,
i
sg
i
v
e
ni
n“
Public-Key Encrypted Enveloping”onpa
g
e
75.

Digitally Signed Enveloping
PGP digitally signed enveloping works just like standard enveloping. For example if
you wanted to sign data using a private key contained in sigKeyContext, you
would use:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_PGP );
/* Add the signing key */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE,
sigKeyContext );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

Verifying the signature works in the usual way:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied, signatureResult, status;
/* Create the envelope and add the signature check keyset */
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_KEYSET_SIGCHECK,
sigCheckKeyset );
/* Push in the signed data and pop out the recovered message */
cryptPushData( cryptEnvelope, envelopedData, envelopedDataLength,
&bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, message, messageBufferSize,
&bytesCopied );
/* Determine the result of the signature check */
cryptGetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE_RESULT,
&signatureResult );

The signature result will typically be CRYPT_OK (the signature verified), CRYPT_ERROR_SIGNATURE (the signature did not verify), or CRYPT_ERROR_NOTFOUND(
t
hek
e
yne
e
de
dt
oc
he
c
kt
h
es
i
g
na
t
ur
ewa
s
n
’
tf
o
un
di
nt
hek
e
y
s
e
t
)
.
When you sign data in the PGP format, the nested content type is always set to plain
data. This is a limitation of the PGP format that always signs data as the innermost
s
t
e
p,
s
ot
ha
twha
t
’
ss
i
g
ne
di
sa
l
wa
y
spl
a
i
nda
t
a
.I
na
dd
i
t
i
o
nt
ot
hi
sr
e
s
t
r
i
c
t
i
on,
i
t
’
sn
ot
possible to have more than one signer per envelope. Multiple signers requires the use
ofn
e
s
t
e
de
nv
e
l
op
e
s
,
howe
v
e
ri
t
’
sn
e
c
e
s
s
a
r
yt
oi
nt
e
r
s
pe
r
s
eal
a
y
e
rofe
n
c
r
y
pt
i
onor
c
o
mpr
e
s
s
i
onbe
t
we
e
ne
a
c
hs
i
g
na
t
ur
epa
s
ss
i
nc
ePGPc
a
n
’
te
a
s
i
l
ydi
s
t
i
ng
ui
s
hwhi
c
h
s
i
g
na
t
ur
ebe
l
ong
st
owhi
c
hs
i
g
na
t
ur
epa
s
s
.I
ng
e
ne
r
a
li
t
’
sb
e
s
tno
tt
ot
r
yt
oa
pp
l
y
multiple signatures to a piece of data.

PGP

leaves the data being signed unchanged and produces a standalone signature as the
result of the encoding process.
To specify that an envelope should produce a detached signature rather than standard
s
i
g
ne
dda
t
a
,
y
ous
h
ou
l
ds
e
tt
h
ee
nv
e
l
o
pe
’
sCRYPT_ENVI
NFO_DETACHEDSI
GNATUREa
t
t
r
i
bu
t
et
o‘
t
r
u
e
’(
a
nyno
nz
e
r
ov
a
l
ue
)b
e
f
or
ey
oupus
hi
na
nyda
t
a
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DETACHEDSIGNATURE, 1
);

Apart from that, the creation of detached signatures works just like the creation of
standard signed data, with the result of the enveloping process being the standalone
signature (without the data attached):
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_PGP );
/* Add the signing key and specify that we're using a detached
signature */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE,
sigKeyContext );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DETACHEDSIGNATURE, 1
);
/* Add the data size information and data, wrap up the processing, and
pop out the detached signature */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, detachedSignature,
detachedSignatureBufferSize, &bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

Verifying a detached signature works somewhat differently from standard cryptlib
detache
ds
i
g
na
t
ur
epr
oc
e
s
s
i
ngs
i
nc
et
hePGPf
or
ma
td
oe
s
n
’
tdi
f
f
e
r
e
nt
i
a
t
ebe
t
we
e
n
s
t
a
n
da
r
da
ndd
e
t
a
c
he
ds
i
g
na
t
u
r
e
s
.Be
c
a
us
eo
ft
hi
sl
a
c
kofd
i
f
f
e
r
e
nt
i
a
t
i
on,
i
t
’
sn
ot
possible for cryptlib to automatically determine whether a signature should have data
associated with it or not. Normally, cryptlib assumes that a signature is associated
with the data being signed, which is the most common case. When verifying a
detached signature, you need to use the alternative signature processing technique
that involves hashing the data yourself and then adding the hash to the envelope
rather than pushing the data into the envelope and having it hashed for you. Since
PGPh
a
s
he
sf
ur
t
he
ri
n
f
or
ma
t
i
ona
f
t
e
rh
a
s
hi
ngt
heda
t
at
ob
es
i
g
ne
d,
y
ous
hou
l
d
n’
t
complete the hashing before you push the hash context into the envelope. This is in
contrast to standard cryptlib detached signature processing which requires that you
complete the hashing before pushing the context into the envelope:
CRYPT_CONTEXT hashContext;
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied, sigCheckStatus;
/* Create the hash context and hash the signed data without completing
the hashing */
cryptCreateContext( &hashContext, cryptUser, CRYPT_ALGO_SHA );
cryptEncrypt( hashContext, data, dataLength );
/* Create the envelope and add the signature check keyset */
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_AUTO );
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_KEYSET_SIGCHECK,
sigCheckKeyset );
/* Add the hash and follow it with the detached signature */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_HASH, hashContext );
cryptPushData( cryptEnvelope, data, dataLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptDestroyContext( hashContext );

PGP Enveloping

/* Determine the result of the signature check */
cryptGetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE_RESULT,
&sigCheckStatus );
cryptDestroyEnvelope( cryptEnvelope );

100

From Envelopes to email

From Envelopes to email
The enveloping process produces binary data as output that then needs to be wrapped
up in the appropriate MIME headers and formatting before it can really be called
S/MIME or PGP mail. The exact mechanisms used depend on the mailer code or
softwa
r
ei
nt
e
r
f
a
c
et
ot
hema
i
ls
y
s
t
e
my
ou
’
r
eus
i
ng
.Ge
ne
r
a
lg
ui
de
l
i
ne
sf
ort
he
different enveloped data types are given below.
Note that cryptlib is a security toolkit and not a mail client or server. Although
cryptlib provides all the crypto functionality needed to implement S/MIME and PGP,
it cannot send or receive email, process MIME message parts or base64 or PGP
ASCII encoding, or otherwise act as a mail agent. These functions are performed y
mail-handling software. For mail-processing operations you need to combine it with
mail-handling software of the kind described further on.

S/MIME email
MIME is the Internet standard for communicating complex data types via email, and
provides for tagging of message contents and safe encoding of data to allow it to pass
over data paths that would otherwise damage or alter the message contents. Each
MIME message has a top-level type, subtype, and optional parameters. The top-level
types are application, audio, image, message, multipart, text, and
video.
Most of the S/MIME secured types have a content type of application/pkcs7mime, except for detached signatures that have a content type of
application/pkcs7-signature. The content type usually also includes an
additional smime-type parameter whose value depends on the S/MIME type and is
de
s
c
r
i
be
di
nf
ur
t
h
e
rde
t
a
i
lbe
l
ow.I
na
ddi
t
i
o
ni
t
’
sus
ua
lt
oi
nc
l
udeac
on
t
e
nt
disposition field whose value is also explained below.
Si
nc
eMI
MEme
s
s
a
g
e
sa
r
ec
ommo
nl
yt
r
a
ns
f
e
r
r
e
dv
i
ae
ma
i
la
ndt
hi
sd
oe
s
n
’
tha
ndl
e
the binary data produc
e
dbyc
r
y
pt
l
i
b
’
se
nv
e
l
o
pi
ng
,
MI
MEa
l
s
ode
f
i
ne
same
a
nso
f
encoding binary data as text. This is known as content-transfer-encoding.

Data
The innermost, plain data content should be converted to canonical MIME format and
have a standard MIME header which is appropriate to the data content, with optional
encoding as required. For the most common type of content (plain text), the header
would have a content-type of text/plain, and possibly optional extra information
such as a content transfer encoding (in this case quoted-printable), content
disposition, and whatever other MIME headers are appropriate. This formatting is
normally handled for you by the mailer code or software interface to the mail system
y
ou’
r
eus
i
ng
.

Signed Data
For signed data the MIME type is application/pkcs7-mime, the smime-type
parameter is signed-data, and the extensions for filenames specified as
parameters is .p7m. A typical MIME header for signed data is therefore:
Content-Type: application/pkcs7-mime; smime-type=signed-data;
name=smime.p7m
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename=smime.p7m
encoded signed data

Detached Signature
Detached signatures represent a special instance of signed data in which the data to be
signed is carried as one MIME body part and the signature is carried as another body
part. The message is encoded as a multipart MIME message with the overall message
having a content type of multipart/signed and a protocol parameter of

PGP email

101

application/pkcs7-signature, and the signature part having a content type
of application/pkcs7-signature.
Si
nc
et
hed
a
t
apr
e
c
e
de
st
h
es
i
g
na
t
ur
e
,
i
t
’
sus
e
f
ult
oi
n
c
l
u
det
heh
a
s
ha
l
g
or
i
t
hmus
e
d
for the data as a parameter with the content type (cryptlib processes the signature
be
f
or
et
heda
t
as
oi
tdo
e
s
n
’
trequire it, but other implementations may not be able to
do this). The hash algorithm parameter is given by micalg=sha1 or
micalg=md5 as appropriate. When receiving S/MIME messages you can ignore
this value since cryptlib will automatically use the correct type based on the
signature.
A typical MIME header for a detached signature is therefore:
Content-Type: multipart/signed; protocol=application/pkcs7-signature;
micalg=sha1; boundary=boundary
--boundary
Content-Type: text/plain Content-Transfer-Encoding: quoted-printable
signed text
--boundary
Content-Type: application/pkcs7-signature; name=smime.p7s
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename=smime.p7s
encoded signature
--boundary—

Encrypted Data
For encrypted data the MIME type is application/pkcs7-mime, the smimetype parameter is enveloped-data, and the extension for filenames specified as
parameters is .p7m. A typical MIME header for encrypted data is therefore:
Content-Type: application/pkcs7-mime; smime-type=enveloped-data;
name=smime.p7m
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename=smime.p7m
encoded encrypted data

Nested Content
Unlike straight CMS nested content, S/MIME nested content requires a new level of
MIME encoding for each nesting level. For the minimum level of nesting (straight
signed or encrypted data) you need to first MIME-encode the plain data, then
envelope it to create CMS signed or encrypted data, and then MIME-encode it again.
For the typical case of signed, encrypted data you need to MIME-encode, sign,
MIME-encode again, encrypt, and then MIME-encode yet again (rumours that
S/MIME was designed by a consortium of network bandwidth vendors and disk drive
manufacturers are probably unfounded).
Since the nesting inf
or
ma
t
i
o
ni
sc
ont
a
i
ne
di
nt
heMI
MEhe
a
de
r
s
,
y
oudo
n
’
th
a
v
et
o
specify the nested content type using CRYPT_ENVINO_CONTENTTYPE as you do
with straight CMS enveloped data (this is one of the few actual differences between
CRYPT_FORMAT_CMS and CRYPT_FORMAT_SMIME), cryptlib will
automatically set the correct content type for you. Conversely, you need to use the
MIME header information rather than CRYPT_ENVINFO_CONTENTTYPE when
de-enveloping data (this will normally be handled for you by the mailer code or
softwa
r
ei
nt
e
r
f
a
c
et
ot
hema
i
ls
y
s
t
e
my
ou
’
r
eus
i
ng
)
.

PGP email
Traditionally, PGP has employed its own email encapsulation format that predates
MI
MEa
n
di
s
n
’
tdi
r
e
c
t
l
yc
o
mpa
t
i
bl
ewi
t
hi
t
.APGPme
s
s
a
g
ei
sde
l
i
mi
t
e
dwi
t
ht
he
string -----BEGIN PGP MESSAGE----- and -----END PGP MESSAGE----, with the (binary) message body present in base64-encoded format between the

102

From Envelopes to email

delimiters. The body is followed by a base64-encoded CRC24 checksum calculated
on the message body before base64-encoding. In addition the body may be preceded
by one or more lines of type-and-value pairs containing additional information such
as software version information, and separated from the body by a blank line. More
details on the format are given in the PGP standards documents.
An example of a PGP email message is:
-----BEGIN PGP MESSAGE----Version: cryptlib 3.1
base64-encoded message body
base64-encoded CRC24 checksum
-----END PGP MESSAGE-----

Signed data with a detached signature is delimited with -----BEGIN PGP
SIGNED MESSAGE----- at the start of the message, followed by -----BEGIN
PGP SIGNATURE----- and -----END PGP SIGNATURE----- around the
signature that follows. The signature follows the standard PGP message-encoding
rules given above:
-----BEGIN PGP SIGNED MESSAGE----Hash: SHA1
message body
-----BEGIN PGP SIGNATURE----Version: cryptlib 3.1
base64-encoded signature
base64-encoded CRC24 checksum
-----END PGP SIGNATURE-----

The example above shows another use for the type-and-value lines, in this case to
indicate the hashing algorithm used in the signature to allow one-pass processing of
the message.
In addition to the traditional PGP format, there exists a mechanism for encapsulating
t
het
r
a
di
t
i
o
na
lPGPf
or
ma
ti
na
na
d
di
t
i
o
na
ll
a
y
e
rofMI
MEwr
a
ppi
ng
.Thi
si
s
n’
tt
r
ue
MIME message handling since it merely wraps MIME headers around the existing
PGP email encapsulation rather than using the full MIME capabilities directly as does
S/MIME. This format is almost never used, with software expected to use the
traditional PGP format instead. If you need more information about PGP/MIME, you
can find it in the PGP standards documentation.

Implementing S/MIME and PGP email using cryptlib
Most of the MIME processing and encoding issues described above will be handled
for you by the mail software that cryptlib is used with. To use cryptlib to handle
S/MIME and PGP email messages, you would typically register the various MIME
types with the mail software and, when they are encountered, the mailer will hand the
message content (the data that remains after the MIME wrapper has been removed) to
cryptlib. cryptlib can then process the data and hand the processed result back to the
mailer. The same applies for generating S/MIME and PGP email messages.
Note that cryptlib is a security toolkit and not a mail client or server. Although
cryptlib provides all the crypto functionality needed to implement S/MIME and PGP,
it cannot send or receive email, process MIME message parts, or otherwise act as a
mail agent. For mail-processing operations you need to combine it with mailhandling software of the kind described below.

c-client/IMAP4
c-client is a portable Swiss army chainsaw interface to a wide variety of mail and
news handling systems. One of the services it provides is full handling of MIME
message parts which involves breaking a message down into a sequence of BODY
structures each of which contains one MIME body part. The type member contains
the content type (typically TYPEMULTIPART or TYPEAPPLICATION for the
types used in S/MIME or PGP), the subtype member contains the MIME subtype,

Implementing S/MIME and PGP email using cryptlib

103

the parameter list contains any required parameters, and the
contents.binary member contains outgoing binary data straight from the
cryptlib envelope (c-client will perform any necessary encoding such as base64 if
required). All of this information is converted into an appropriately-formatted MIME
message by c-client before transmission.
Since IMAP supports the fetching of individual MIME body parts from a server,
contents.binary c
a
n’
tb
eus
e
dt
oa
c
c
e
s
si
nc
o
mi
ngme
ssage data since only the
header information may have been fetched, with the actual content still residing on
the server. To fetch a particular body part, you need to use mail_fetchbody. If
the body part is base64-encoded (denoted by the encoding member of the BODY
having the value ENCBASE64) then you also need to call rfc822_base64 to
decode the data so cryptlib can process it. In the unlikely event that the binary data is
encoded as quoted-printable (denoted by ENCQUOTEDPRINTABLE, at least one
broken mailer occasionally does this) you need to call rfc822_qprint instead. In
either case the output can be pushed straight into a cryptlib envelope.

Eudora
Eudora handles MIME content types through plug-in translators that are called
through two functions, ems_can_translate and ems_translate_file.
Eudora calls ems_can_translate with an emsMIMEtype parameter that
contains information on the MIME type contained in the message. If this is an
S/MIME or PGP type (for example application/pkcs7-mime) the function
should return EMSR_NOW to indicate that it can process this MIME type, otherwise is
returns EMSR_CANT_TRANSLATE.
Once the translator has indicated that it can process a message, Eudora calls
ems_translate_file with input and output files to read the data from and write
the processed result to. The translation is just the standard cryptlib enveloping or deenveloping process depending on whether the translator is an on-arrival or on-display
one (used for de-enveloping incoming messages) or a Q4-transmission or Q4completion one (used for enveloping outgoing messages).

MAPI
MAPI(
Mi
c
r
os
of
t
’
sma
i
lAPI
)de
f
i
ne
st
wot
y
pe
so
fma
i
l
e
re
x
t
e
ns
i
o
nst
ha
ta
l
l
ow
cryptlib-based S/MIME and PGP functionality to be added to Windows mail
applications. The first type is a spooler hook or hook provider, which can be called
on delivery of incoming messages and on transmission of outgoing messages. The
second type is a preprocessor, which is less useful and operates on outgoing messages
only. The major difference between the two in terms of implementation complexity
is that hook providers are full (although simple) MAPI service providers while prepr
oc
e
s
s
or
sa
r
ee
x
t
e
ns
i
onst
ot
r
a
ns
por
tpr
ov
i
d
e
r
s(
t
ha
ti
s
,
i
fy
ou’
v
ea
l
r
e
a
dywr
i
t
t
e
na
transport provider you can add the preprocessor wi
t
ho
utt
o
omuc
he
f
f
or
t
;i
fy
oud
on
’
t
ha
v
eat
r
a
ns
por
tpr
ov
i
de
ra
v
a
i
l
a
b
l
e
,
i
t
’
squ
i
t
eabi
tmor
ewor
k
)
.I
ng
e
ne
r
a
li
t
’
s
probably easiest to use a single spooler hook to handle inbound and outbound
messages. You can do this by setting both the HOOK_INBOUND and
HOOK_OUTBOUNDf
l
a
g
si
nt
heho
ok
’
sPR_RESOURCE_FLAGSv
a
l
ue
.
Messages are passed to hooks via ISpoolerHook::OutboundMsgHook (for
outgoing messages) and ISpoolerHook::InboundMsgHook (for incoming
messages). The hook implementation itself is contained in a DLL that contains the
HPProviderInit entry point and optional further entry points used to configure it,
for example a message service entry point for program-based configuration and a
WIZARDENTRY for user-based configuration.

Windows 95/98/ME and NT/2000/XP Shell
Windows allows a given MIME content type to be associated with an application to
process it. You can set up this association by calling MIMEAssociationDialog
and setting the MIMEASSOCDLG_FL_REGISTER_ASSOC flag in the
dwInFlags parameter, which will (provided the user approves it) create an

104

From Envelopes to email

association between the content type you specify in the pcszMIMEContentType
parameter and the application chosen by the user. This provides a somewhat crude
but easy to set up mechanism for processing S/MIME and PGP data using a cryptlibbased application.

Creating/Destroying Session Objects

105

Secure Sessions
c
r
y
pt
l
i
b’
ss
e
c
ur
es
e
s
s
i
oni
nt
e
r
f
a
c
epr
ov
i
d
e
sas
e
s
s
i
o
n-oriented equivalent to envelope
objects that can be used to secure a communications link with a host or server or
otherwise communicate with another system over a network. Secure sessions can
include SSH, SSL, and TLS sessions, general request/response-style communications
sessions can include protocols such as the certificate management protocol (CMP),
simple certificate enrolment protocol (SCEP), real-time certificate status protocol
(RTCS), online certificate status protocol (OCSP), and timestamping protocol (TSP).
As with envelopes, cryptlib takes care of all of the session details for you so that all
you need to do is provide basic communications information such as the name of the
server or host to connect to and any other information required for the session such as
a password or certificate. cryptlib takes care of establishing the session and
managing the details of the communications channel and its security parameters.
Secure sessions are very similar to envelopes, with the main difference being that
while an envelope is a pure data object into which you can push data and pop the
processed form of the same data, a session is a communications object into which you
push data and then pop data that constitutes a response from a remove server or
client. This means that a session object can be viewed as a bottomless envelope
through which you can push or pop as much data as the other side can accept or
provide.
As with an envelope, you use a session object by adding to it action objects and
resources such as user names and passwords that control the interaction with the
remote server or client and then push in data intended for the remote system and pop
out data coming from the remote system. For example to connect to a server using
SSH and obtain a directory of files using the ls command you would do the
following:
create the session;
add the server name, user name, and password;
activate the session;
push data "ls";
pop the result of the ls command;
destroy the session

Tha
t
’
sa
l
lt
h
a
t
’
sne
c
e
s
s
a
r
y
.Si
nc
ey
ou
’
v
ea
d
de
daus
e
rna
mea
ndpa
s
s
wor
d,
c
r
y
pt
l
i
b
knows that it should establish an encrypted session with the remote server and log on
using the given user name and password. From then on all data which is exchanged
with the server is encrypted and authenticated using the SSH protocol.
Creating an SSH server session is equally simple. In this case all you need is the
server key:
create the session;
add the server key;
activate the session;
pop client data;
push server response;
destroy the session

When you activate the session, cryptlib will listen for an incoming connection from a
client and return once a secure connection has been negotiated, at which point
communication proceeds as before.

Creating/Destroying Session Objects
Secure sessions are accessed as session objects that work in the same general manner
as other cryptlib objects. You create a session using cryptCreateSession, specifying
the user who is to own the session object or CRYPT_UNUSED for the default,
normal user, and the type of session that you want to create. This creates a session
object ready for use in securing a communications link or otherwise communicating
wi
t
har
e
mot
es
e
r
v
e
rorc
l
i
e
n
t
.Onc
ey
ou’
v
ef
i
n
i
s
he
dwi
t
ht
hes
e
s
s
i
o
n,
y
ouus
e
cryptDestroySession to end the session and destroy the session object:

106

Secure Sessions

CRYPT_SESSION cryptSession;
cryptCreateSession( &cryptSession, cryptUser, sessionType );
/* Communicate with the remote server or client */
cryptDestroySession( cryptSession );

The available session types are:
Session

Description

CRYPT_SESSION_CMP Certificate management protocol (CMP).
CRYPT_SESSION_OCSP Online certificate status protocol (OCSP).
CRYPT_SESSION_RTCS Real-time certificate status protocol (RTCS).
CRYPT_SESSION_SCEP Simple certificate enrolment protocol (SCEP).
CRYPT_SESSION_SSH

Secure shell (SSH).

CRYPT_SESSION_SSL

Secure sockets layer (SSL and TLS).

CRYPT_SESSION_TSP

Timestamping protocol (TSP).

This section will mainly cover the secure communications session types such as SSH,
SSL, and TLS. CMP, SCEP, RTCS, and OCSP client sessions are certificate
ma
na
g
e
me
n
ts
e
r
v
i
c
e
st
h
a
ta
r
ec
ov
e
r
e
di
n“
Obtaining Certificates using CMP”
,
“
Obtaining Certificates using SCEP”
,
“
Certificate Status Checking using RTCS”
,
a
nd
“
Certificate Revocation Checking using OCSP”onpa
g
e
s167, 162, 162, and 168, and
aTSPc
l
i
e
n
ts
e
s
s
i
o
ni
sa
nS/
MI
MEs
e
r
v
i
c
ewhi
c
hi
sc
ov
e
r
e
di
n“
Timestamping”on
page 93. RTCS, OCSP and TSP server sessions are standard session types and are
also covered here. CMP and SCEP server sessions are somewhat more complex and
a
r
ec
ov
e
r
e
di
n“
Managing a CA using CMP or SCEP”o
np
a
g
e176. The general
principles covering sessions apply to all of these session types, so you should
familiarise yourself with the operation of session objects and associated issues such
as network proxies and timeouts before trying to work with these other session types.
By default the secure communications session object which is created will have an
internal buffer whose size is appropriate for the type of security protocol which is
being employed. The size of the buffer may affect the amount of extra processing
that cryptlib needs to perform, so that a large buffer can reduce the amount of
copying to and from the buffer, but will consume more memory. If want to use a
buffer for a secure communications session which is larger than the default size, you
can specify its size using the CRYPT_ATTRIBUTE_BUFFERSIZE attribute after
y
ou’
v
ec
r
e
a
t
e
dt
hes
e
s
s
i
on.Fore
x
a
mp
l
ei
fy
ouwa
n
t
e
dt
os
e
tt
h
ebu
f
f
e
rf
ora
nSSH
session to 64 kB you would use:
CRYPT_SESSION cryptSession;
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_SSH );
cryptSetAttribute( cryptSession, CRYPT_ATTRIBUTE_BUFFERSIZE, 65536L );
/* Communicate with the remote server or client */
cryptDestroySession( cryptSession );

Since cryptlib streams data through the session object, the int
e
r
n
a
lb
uf
f
e
rs
i
z
edo
e
s
n
’
t
limit how much data you can push and pop (for example you could push 1 MB of
da
t
ai
nt
oas
e
s
s
i
ono
bj
e
c
twi
t
ha32k
Bi
nt
e
r
na
lbu
f
f
e
r
)
,
t
heonl
yr
e
a
s
o
ny
ou
’
dwa
n
tt
o
change the size is to provide tighter control over memory usage by session objects.
Unl
e
s
sy
ou
’
r
ea
bs
o
l
u
t
e
l
yc
e
r
t
a
i
nt
ha
tt
heot
h
e
rs
i
dewi
l
lo
nl
ys
e
ndv
e
r
ys
ma
l
lda
t
a
qua
nt
i
t
i
e
s
,
y
ous
ho
ul
dn
’
ts
hr
i
nkt
heb
uf
f
e
rb
e
l
owt
hede
f
a
u
l
ts
i
z
es
e
tbyc
r
y
pt
l
i
bs
i
n
c
e
the protocols that cryptlib implements have certain fixed bounds on packet sizes that
need to be met, making the buffer too small would make it impossible to process data
being sent by the other side.

Client vs. Server Sessions

107

Note that the CRYPT_SESSION is passed to cryptCreateSession by reference as the
function modifies it when it creates the session. In all other routines in cryptlib,
CRYPT_SESSION is passed by value.

Client vs. Server Sessions
cryptlib distinguishes between two types of session objects, client sessions and server
sessions. Client sessions establish a connection to a remote server while server
sessions wait for incoming communications from a remote client. To distinguish
between client and server objects, you use a session type ending in _SERVER when
you create the session object. For example to create an SSL/TLS server object
instead of an SSL/TLS client you would specify its type on creation as CRYPT_SESSION_SSL_SERVER instead of CRYPT_SESSION_SSL.
Because server sessions wait for an incoming connection request to arrive, you need
to run each one in its own thread if you want to handle multiple connections
simultaneously (cryptlib is fully thread-s
a
f
es
ot
he
r
e
’
sn
opr
obl
e
m wi
t
hh
a
v
i
ng
multiple threads processing incoming connections). For example to handle up to 10
connections at once you would do the following:
for i = 1 to 10 do
start_thread( server_thread );

where the server_thread is:
loop
create the session;
add required information to the session;
activate the session;
process client request(s);
destroy the session;

More information on using cryptlib with multipl
et
hr
e
a
dsi
sg
i
v
e
ni
n“
Multi-threaded
cryptlib Operation”o
npa
g
e45.
Binding to the default ports used by the various session protocols may require special
pr
i
v
i
l
e
g
e
sons
o
mes
y
s
t
e
mst
h
a
tdo
n
’
ta
l
l
ownormal users to bind to ports below 1024.
I
fy
oune
e
dt
obi
ndt
oar
e
s
e
r
v
e
dp
or
ty
ous
h
oul
dc
o
ns
u
l
ty
o
urope
r
a
t
i
ngs
y
s
t
e
m’
s
documentation for details on any restrictions that may apply, and may need to take
special precautions if binding to one of these ports requires the use of elevated
security privileges. Alternatively, you can bind to a non-default port outside the
reserved range by specifying the port using the CRYPT_SESSINFO_SERVER_PORT attribute. You can also specify which interface you want to bind to if the
system has more than one by using the CRYPT_SESSINFO_SERVER_NAME
a
t
t
r
i
bu
t
e
.I
fy
ou’
r
et
e
s
t
i
ngc
odebe
f
or
ede
p
l
oy
i
ngi
t
,
i
t
’
sag
oodi
de
at
os
p
e
c
i
f
yt
h
a
t
you want to bind to localhost to avoid listening on arbitrary externally-visible
interfaces. For example to listen on local port 2000 you would use:
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
"localhost", 9 );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_SERVER_PORT, 2000 );

Server Names/URLs
Server names can be given using IP addresses (in dotted-decimal form for IPv4 or
colon-delimited form for IPv6), DNS names, or full URLs, with optional ports and
other information provided in the usual manner. You can specify the server name or
URL using the CRYPT_SESSINFO_SERVER_NAME attribute and the port (if
y
ou’
r
en
otus
i
ngt
hede
f
a
ul
tp
or
tf
r
ot
hepr
ot
o
c
o
la
n
di
ti
s
n’
ta
l
r
e
a
dys
pe
c
i
f
i
e
di
nt
h
e
URL) using the CRYPT_SESSINFO_SERVER_PORT attribute. For example to
specify a connection to the server www.server.com on port 80 you would use:
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
"www.server.com", 14 );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_SERVER_PORT, 80 );

Alternatively, you could specify both in the same name:
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
"www.server.com:80", 17 );

108

Secure Sessions

Since this is a web server for which port 80 is the default port, you could also use the
more common:
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
"http://www.server.com", 20 );

SSL and TLS use a predefined port and are often used in conjunction with HTTP, so
you can specify these URLs with or without the http:// or https:// schema
prefixes. SSH similarly uses a predefined port and can be used with or without the
ssh://, scp://, or sftp:// schema prefixes. All of these protocols allow you
t
os
pe
c
i
f
yus
e
ri
n
f
or
ma
t
i
o
nbe
f
or
et
heh
os
tn
a
me
,
s
e
pa
r
a
t
e
dwi
t
ha
n‘
@’s
i
g
n.For
e
x
a
mp
l
et
oc
o
nn
e
c
ta
s“
us
e
r
”t
ot
heSSHs
e
r
v
e
rssh.server.com you could use:
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
"ssh://user@ssh.server.com", 25 );

which saves having to explicitly specify the user name with the CRYPT_SESSINFO_USERNAME attribute.
All of the PKI protocols use HTTP as their transport mechanism, so cryptlib will
automatically default to using HTTP transport whether you include the http://
schema specifier or not. The CMP and TSP protocols also have alternative,
deprecated transport mechanisms identified by cmp://…(for CMP) and tcp://…
(for TSP) instead of http://…. These are occasionally used by CAs or timestamp
servers, you may need to use these instead of the HTTP default.

Server Private Keys
Most server sessions require the use of a private key in one form or another to decrypt
data from the client or sign responses returned to the client. The server key is
typically stored in a private key file, but for extra security may be held in a crypto
device such as a crypto coprocessor or accelerator. In addition, for most session
types the server key needs to be associated with a certificate or certificate chain
l
e
a
d
i
ngupt
oat
r
us
t
e
dr
ootc
e
r
t
i
f
i
c
a
t
e
,
s
ot
h
a
ty
ouc
a
n
’
tus
ej
us
tar
a
wpr
i
v
a
t
ek
e
ya
s
the server key. You can obtain the required certificate or certificate chain by creating
it yourself using cryptli
borb
yobt
a
i
ni
ngi
tf
r
om ac
o
mme
r
c
i
a
lCA(
i
t
’
sg
e
ne
r
a
l
l
y
much cheaper and easier to create it yourself than to obtain one from a third-party
CA).
When you create or obtain the certificate for your server, you may need to specify the
server name in the common name field of the certificate (the intricacies of certificate
na
me
sa
n
dh
owt
oc
r
e
a
t
ey
ourownc
e
r
t
i
f
i
c
a
t
e
sa
r
ee
x
p
l
a
i
ne
di
n“
Certificates”onpa
g
e
203). For example if your server was www.companyname.com then the certificate
for the server would contain this as its common name component (you can actually
put in anything you like as the common name component, but this will result in some
web browsers that use your server displaying a warning message when they connect).
SSH server sessions require a raw RSA (or optionally DSA for SSHv2) key, although
you can also use one with a certificate or certificate chain attached. All other session
types require one with certificate(s) attached. You add the server key as the
CRYPT_SESSINFO_PRIVATEKEY attribute, for example to use a private key held
in a crypto device as the server key you would use:
CRYPT_CONTEXT privateKey;
cryptGetPrivateKey( cryptDevice, &privateKey, CRYPT_KEYID_NAME,
serverKeyName, NULL );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_PRIVATEKEY,
privateKey );
cryptDestroyContext( privateKey );

Not
et
h
a
t
,
a
swi
t
he
nv
e
l
ope
s
,
t
hepr
i
v
a
t
ek
e
yobj
e
c
tc
a
nbede
s
t
r
oy
e
da
ss
oo
na
si
t
’
s
added to the session, since the session maintains its own copy of the object internally.
I
fy
ou’
r
ewor
r
i
e
da
b
ou
ts
o
meobs
c
ur
e(
a
ndr
a
t
he
ru
nl
i
k
e
l
y
)a
t
t
a
c
k
sonpr
i
v
a
t
ek
e
y
s
,
you can enable the CRYPT_OPTION_MISC_SIDECHANNELPROTECTION
opt
i
o
na
se
x
pl
a
i
n
e
di
n“
Working with Configuration Options”onpa
g
e274. Note that
enabling this option will slow down all private-key operations by up to 10%.

Establishing a Session

109

Establishing a Session
Much of the secure session process is identical to the enveloping process, so you
should familiarise yourself with the general concept of enveloping as described in
“
Data Enveloping”onpa
g
e60 i
fy
o
uha
v
e
n
’
ta
l
r
e
a
dydon
es
o.Thes
e
c
ur
es
e
s
s
i
on
establishment process involves adding the information which is required to connect to
the remote server as a client or to establish a server, and then activating the session to
establish the secure session or wait for incoming connections. This process of
activating the session has no real equivalent for envelopes because envelopes are
activated automatically the first time data is pushed into them.
Client sessions can also be activated automatically, however the initial handshake
process which is required to activate a session with a remote server is usually lengthy
a
ndc
o
mp
l
e
xs
oi
t
’
sg
e
ne
r
a
l
l
ybe
t
t
e
rt
oe
x
p
l
i
c
i
t
l
ya
c
t
i
v
a
t
et
h
es
e
s
s
i
onun
de
rc
o
nt
r
o
l
l
e
d
conditions and have the ability to react to errors in an appropriate manner rather than
to have the session auto-activate itself the first time that data is pushed. Server
sessions that wait for an incoming connection must be explicitly activated, which
causes them to wait for a client connection.
You can activate a session by setting its CRYPT_SESSINFO_ACTIVE attribute to
true (any nonzero value). You can also determine the activation state of a session by
r
e
a
di
ngt
hi
sa
t
t
r
i
b
ut
e
,
i
fi
t
’
ss
e
tt
ot
r
u
et
h
e
nt
hes
e
s
s
i
oni
sa
c
t
i
v
e
,
ot
he
r
wi
s
ei
t
’
snot
active.

Persistent Connections
Some cryptlib session types such as CMP, SCEP, RTCS, OCSP, and TSP provide
request/response protocols rather than continuous secure sessions like SSH and
SSL/
TLS.I
nma
nyc
a
s
e
si
t
’
spos
s
i
bl
et
op
e
r
f
or
mmor
et
ha
non
er
e
qu
e
s
t
/
r
e
s
po
ns
e
transaction per session, avoiding the overhead of creating a new connection for each
transaction. To handle persistent connections for client sessions, cryptlib uses the
CRYPT_SESSINFO_CONNECTIONACTIVE attribute to indicate that the
connection is still active and is ready to accept further transactions. Transactions
after the initial one are handled in exactly the same way as the first one, except that
t
he
r
e
’
snone
e
dt
oc
r
e
a
t
eane
ws
e
s
s
i
ono
bj
e
c
tf
ort
he
m:
CRYPT_SESSION cryptSession;
int connectionActive;
/* Create the session and add the server name */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_xxx );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
serverName, serverNameLength );
/* Perform the first transaction */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_REQUEST,
cryptRequest1 );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );
cryptGetAttribute( cryptSession, CRYPT_SESSINFO_RESPONSE,
&cryptResponse1 );
/* Check whether the session connection is still open */
cryptGetAttribute( cryptSession, CRYPT_SESSINFO_CONNECTIONACTIVE,
&connectionActive );
if( !connectionActive )
/* The other side has closed the connection, exit */;
/* Perform the second transaction */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_REQUEST,
cryptRequest2 );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );
cryptGetAttribute( cryptSession, CRYPT_SESSINFO_RESPONSE,
&cryptResponse2 );

Note the check of the CRYPT_SESSINFO_CONNECTIONACTIVE attribute. Since
not all servers support persistent connections or may time out and close the
connection after a period of inactivit
y
,
i
t
’
sag
oodi
de
at
oc
he
c
kt
ha
tt
h
ec
o
nn
e
c
t
i
o
ni
s
s
t
i
l
lope
nb
e
f
or
et
r
y
i
ngt
os
ub
mi
tf
ur
t
he
rt
r
a
ns
a
c
t
i
o
ns
.Not
ea
l
s
ot
h
a
tt
he
r
e
’
snone
e
d
to explicitly delete the request from the first activation of the session, cryptlib

110

Secure Sessions

automatically does this for you once the session activation has completed. This does
mean, however, that if you want to repeat the session transaction using the same data
as before (which would be somewhat unusual), you need to re-add the request to the
session, since the previous activation will have cleared it in preparation for the next
activation.
The process on the server side is similar, after a successfully-completed client
transaction you can either destroy the session or, if you want to support persistent
connections, recycle the connection as for the client-side example above.

SSH Sessions
SSH is a secure data transfer protocol that provides confidentiality, integrityprotection, protection against replay attacks, and a variety of other services. The SSH
server is authenticate
dv
i
at
hes
e
r
v
e
r
’
spubl
i
ck
e
ya
ndt
hec
l
i
e
n
ti
sa
u
t
he
nt
i
c
a
t
e
de
i
t
he
r
via a user name and password or (less frequently) a public key-based digital
signature. cryptlib supports both versions 1 and 2 of the SSH protocol, although the
obsolete version 1 is disabled by default.
The SSH protocol exhibits a design flaw (informally known as the SSH performance
handbrake) that can lead to poor performance when transferring data, which is
particularly noticeable with applications such as SFTP. Although cryptlib avoids the
ha
n
dbr
a
k
e
,
ma
nyot
he
ri
mp
l
e
me
nt
a
t
i
onsd
on
’
t
,
r
e
s
t
r
i
c
t
i
ngda
t
at
r
a
ns
f
e
rr
a
t
e
st
oa
s
little as one tenth of the network link speed (the actual slowdown depends on the link
characteristics and varies from one situation to another). In order to obtain the
maximum performance from SSH, you need to either use cryptlib at both ends of the
link (that is, both the client and server must be ones that avoid the performance
ha
n
dbr
a
k
e
)
,
orus
ea
n
ot
he
rpr
ot
o
c
o
ll
i
k
eSSLt
ha
tdoe
s
n
’
th
a
v
et
heha
nd
br
a
k
e
.

SSH Client Sessions
Establishing a session with an SSH server requires adding the server name or IP
a
ddr
e
s
s
,
a
nopt
i
o
na
lpor
tnu
mbe
ri
fi
ti
s
n
’
tus
i
ngt
hes
t
a
nd
a
r
dSSHpor
t
,
a
ndt
heus
e
r
name and password which is needed to log on to the server via the CRYPT_SESSINFO_USERNAME and CRYPT_SESSINFO_PASSWORD attributes
(occasionally the server will use public-key based authentication instead of a
pa
s
s
wor
d,
whi
c
hi
sc
ov
e
r
e
dl
a
t
e
r
)
.Onc
ey
ou’
v
ea
d
de
dt
hi
si
n
f
or
ma
t
i
o
n,
y
ouc
a
n
activate the session and establish the connection:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_SSH );
/* Add the server name, user name, and password */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
serverName, serverNameLength );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
username, usernameLength );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_PASSWORD,
password, passwordLength );
/* Activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

The equivalent operation in Java or C# is:
/* Create the session */
int cryptSession = crypt.CreateSession( cryptUser,
crypt.SESSION_SSH );
/* Add the server name, user name, and password */
crypt.SetAttributeString( cryptSession, crypt.SESSINFO_SERVER_NAME,
serverName );
crypt.SetAttributeString( cryptSession, crypt.SESSINFO_USERNAME,
username );
crypt.SetAttributeString( cryptSession, crypt.SESSINFO_PASSWORD,
password );

SSH Sessions

111

/* Activate the session */
crypt.SetAttribute( cryptSession, crypt.SESSINFO_ACTIVE, 1 );

In Visual Basic this is:
Dim cryptSession As Long
' Create the session
cryptCreateSession cryptSession, cryptUser, CRYPT_SESSION_SSH
' Add the server name, user name, and password
cryptSetAttributeString cryptSession, CRYPT_SESSINFO_SERVER_NAME, _
serverName, Len( serverName )
cryptSetAttributeString cryptSession, CRYPT_SESSINFO_USERNAME, _
userName, Len( userName )
cryptSetAttributeString cryptSession, CRYPT_SESSINFO_PASSWORD, _
password, Len( password )
' Activate the session
cryptSetAttribute cryptSession, CRYPT_SESSINFO_ACTIVE, 1

When it connects, cryptlib will automatically negotiate the highest protocol version
supported by the server and use that to secure the session. You can determine which
version is in use once the session has been established by reading the CRYPT_SESSINFO_VERSION attribute, a value of 1 indicates SSH version 1 and a value of
2 indicates SSH version 2. You can also force the use of a particular version
(
t
y
pi
c
a
l
l
yy
ou’
dwa
ntt
oe
ns
ure that SSHv2 is used) by setting the protocol version
attribute before you activate the connection.
Activating a session results in cryptlib performing a lot of work in the background.
For example when activating the SSH session shown above cryptlib will connect to
the remote host, read the host and server keys used for authentication and encryption,
generate a secret data value to exchange with the host using its host and server keys,
create the appropriate encryption contexts and load keys based on the secret data
value into them, negotiate general session parameters, and log on over the encrypted
link using the given user name and password.
I
ft
hes
e
r
v
e
rt
ha
ty
ou
’
r
ec
o
nn
e
c
t
i
ngt
or
e
qui
r
e
sp
ub
l
i
c
-key authentication instead of
password authentication, you need to provide a private key via the CRYPT_SESSINFO_PRIVATEKEY attribute to authenticate yourself to the server before you
activate the session. The private key could be a native cryptlib key, but it could also
be a key from a crypto device such as a smart card or Fortezza card:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_SSH );
/* Add the server name, user name, and client key and activate the
session */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
serverName, serverNameLength );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
username, usernameLength );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_PRIVATEKEY,
cryptPrivateKey );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

When cryptlib connects to the server, it will use the provided private key as part of
the SSH handshake to authenticate the client to the server, with the private key taking
the place of the more usual passwor
d.I
fy
ou’
r
eno
ts
ur
ewh
i
c
ho
ft
het
woopt
i
o
ns
you need, you can provide both and cryptlib will use the appropriate one when it
connects to the server.

SSH Server Sessions
Establishing an SSH server session requires specifying that the session is a server
s
e
s
s
i
ona
nda
dd
i
ngt
heSSHs
e
r
v
e
rk
e
y
.Onc
ey
ou’
v
ea
dde
dt
h
i
si
n
f
or
ma
t
i
o
ny
ouc
a
n
activate the session and wait for incoming connections:

112

Secure Sessions

CRYPT_SESSION cryptSession;
int bytesCopied;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser,
CRYPT_SESSION_SSH_SERVER );
/* Add the server key and activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_PRIVATEKEY,
privateKey );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );
/* Process any remaining control messages from the client */
cryptPopData( cryptSession, buffer, bufferSize, &bytesCopied );

The Visual Basic form is:
Dim cryptSession As Long
Dim bytesCopied as Long
' Create the session
cryptCreateSession cryptSession, cryptUser, _
CRYPT_SESSION_SSH_SERVER
' Add the server key and activate the session
cryptSetAttribute cryptSession, CRYPT_SESSINFO_PRIVATEKEY, privateKey
cryptSetAttribute cryptSession, CRYPT_SESSINFO_ACTIVE, 1
' Process any remaining control messages from the client
cryptPopData cryptSession, buffer, bufferSize, bytesCopied

Note the use of the data pop call after the activation has been completed. SSH clients
often send additional session control information such as channel requests or port
forwarding information after the session has been activated. Telling cryptlib to try
and read any additional messages that may have arrived from the client allows it to
process these requests and respond to them as appropriate. In particular, your server
s
hou
l
d
n’
ts
e
n
dda
t
at
ot
h
ec
l
i
e
nti
mme
di
a
t
e
l
ya
f
t
e
rthe session has been established
without first performing a data pop to respond to client requests, since the client may
interpret the data that you send as an (incorrect) response to its request.
cryptlib supports both SSH version 1 and 2 (although the obsolete version 1 is
disabled by default) and by default will function as a version 2 server. If you want to
use the (obsolete) SSH version 1 protocol, you need to enable SSHv1 in the build and
then set the CRYPT_SESSINFO_VERSION attribute to 1 to have the server respond
as a version 1 rather than version 2 server.
Once you activate the session, cryptlib will block until an incoming client connection
arrives, at which point it will negotiate a secure connection with the client. When the
client connects, cryptlib will ask for a user name and password before it allows the
connection to proceed. The handling of the user authentication process is controlled
by the CRYPT_SESSINFO_AUTHRESPONSE attribute, by default cryptlib will
return a CRYPT_ENVELOPE_RESOURCE status when it receives the user name
a
ndpa
s
s
wor
d,
a
l
l
owi
ngy
out
ov
e
r
i
f
yt
hei
n
f
or
ma
t
i
o
nbe
f
or
ec
on
t
i
nui
ng
.I
fi
t
’
sv
a
l
i
d,
you should set the CRYPT_SESSINFO_AUTHRESPONSE attribute to true and
resume the session activation by setting the CRYPT_SESSINFO_ACTIVE response
to true again. If not, you can either set the CRYPT_SESSINFO_AUTHRESPONSE
attribute to false and resume the session activation (which will give the user another
chance to authenticate themselves), or close the session:
int status;
status = cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );
if( status == CRYPT_ENVELOPE_RESOURCE )
{
char username[ CRYPT_MAX_TEXTSIZE + 1 ];
char password[ CRYPT_MAX_TEXTSIZE + 1 ];
int usernameLength, passwordLength

SSH Sessions

113

/* Get the user name and password */
cryptGetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
username, &usernameLength );
cryptGetAttributeString( cryptSession, CRYPT_SESSINFO_PASSWORD,
password, &passwordLength );
username[ usernameLength ] = '\0';
password[ passwordLength ] = '\0';
/* Check the user details and allow or deny the response as
appropriate */
if( checkUser( username, password ) )
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_AUTHRESPONSE,
1 );
else
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_AUTHRESPONSE,
0 );
/* Resume the session activation, sending the authentication
response to the client and completing the handshake */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );
}

To give the user the traditional three attempts at getting their name and password
right, you would run the session activation code in a loop:
int status;
for( i = 0; i < 3; i++ )
{
status = cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE,
1 );
if( cryptStatusOK( status ) )
break;
/* User authenticated, exit */
if( status == CRYPT_ENVELOPE_RESOURCE )
/* Perform password check as before */;
else
break;
/* Some other type of error, exit */
}

Alternatively, you can set the CRYPT_SESSINFO_AUTHRESPONSE attribute to
true before you activate the session and cryptlib will automatically allow the access
a
ndc
o
mp
l
e
t
et
hea
c
t
i
v
a
t
i
on,
s
oy
ou’
l
ln
e
v
e
rne
e
dt
oh
a
n
dl
et
heCRYPT_ENVELOPE_RESOURCE response. In this case you need to check the user details
after the session has been activated and shut it down if the authorisation check fails.

SSH Channels
By default, cryptlib provides the most frequently-used SSH service, a direct
encrypted connection from client to server. When you establish the SSH connection,
c
r
y
pt
l
i
bc
r
e
a
t
e
sa
nSSHc
ommu
ni
c
a
t
i
o
nsc
ha
nn
e
lt
ha
t
’
sus
e
dt
oe
x
c
ha
ng
eda
t
a
.This
pr
oc
e
s
si
se
nt
i
r
e
l
yt
r
a
ns
p
a
r
e
nt
,
a
ndy
oud
on
’
tha
v
et
owor
r
ya
bo
uti
ti
fy
o
udo
n’
twa
nt
to — just treat the SSH session as a secure data pipe from one system to another.
There are however cases where you may need to explicitly deal with SSH channels,
a
ndt
ha
t
’
swhe
ny
ou
’
r
eus
i
ngs
pe
c
i
a
l
-purpose SSH facilities such as port forwarding,
subsystems, or even user-defined channel types. In this case you need to explicitly
create the special-purpose channel and add information describing its use before the
channel can be activated. This process consists of three steps, creating the channel
using the CRYPT_SESSINFO_SSH_CHANNEL attribute, specifying its type using
the CRYPT_SESSINFO_SSH_CHANNEL_TYPE attribute, and finally specifying
any optional channel arguments using the CRYPT_SESSINFO_SSH_CHANNEL_ARG1 and CRYPT_SESSINFO_SSH_CHANNEL_ARG2 attributes. For example to
create a channel of the default type (which is normally done automatically by
cryptlib, and that has no optional arguments) you would use:
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_SSH_CHANNEL,
CRYPT_UNUSED );
cryptSetAttributeString( cryptSession,
CRYPT_SESSINFO_SSH_CHANNEL_TYPE, "session", 7 );

Setting the CRYPT_SESSINFO_SSH_CHANNEL attribute to CRYPT_UNUSED
tells cryptlib to create a new channel (rather than trying to select an existing one,

114

Secure Sessions

which is what the attribute is normally used for), and the CRYPT_SESSINFO_SSH_CHANNEL_TYPEa
t
t
r
i
b
ut
es
pe
c
i
f
i
e
si
t
st
y
p
e
.Onc
ey
ou’
v
ec
r
e
a
t
e
dane
wc
h
a
n
ne
li
n
this manner you can read back the CRYPT_SESSINFO_SSH_CHANNEL attribute to
get the channel ID that was assigned for the newly-created channel:
int channelID;
cryptGetAttribute( cryptSession, CRYPT_SESSINFO_SSH_CHANNEL,
&channelID );

This value is used to uniquely identify a particular channel, buti
t
’
son
l
yne
e
d
e
di
nt
h
e
pr
e
s
e
nc
eo
fmul
t
i
p
l
ec
ha
n
ne
l
s
,
whi
c
ha
r
ede
s
c
r
i
be
di
n“
SSH Multiple Channels”on
page 116.
Ont
hes
e
r
v
e
rs
i
de
,
r
e
a
d
i
ngt
hede
t
a
i
l
so
fac
ha
n
ne
lt
ha
t
’
sb
e
e
no
pe
ne
dbyt
hec
l
i
e
nt
works similarly:
char channelType[ CRYPT_MAX_TEXTSIZE + 1 ];
char channelArg1[ CRYPT_MAX_TEXTSIZE + 1 ];
int channelID, channelTypeLength, channelArg1Length, status;
/* Get the channel ID and type */
cryptGetAttribute( cryptSession, CRYPT_SESSINFO_SSH_CHANNEL,
&channelID );
cryptGetAttributeString( cryptSession,
CRYPT_SESSINFO_SSH_CHANNEL_TYPE, channelType, &channelTypeLength );
channelType[ channelTypeLength ] = '\0';
/* Get the optional channel argument */
status = cryptGetAttributeString( cryptSession,
CRYPT_SESSINFO_SSH_CHANNEL_ARG1, channelArg1, &channelArg1Length );
if( cryptStatusOK( status ) )
channelArg1[ channelArg1Length ] = '\0';

I
fy
oudo
n
’
ts
pe
c
i
f
yot
h
e
r
wi
s
e
,
c
r
y
pt
l
i
bwi
l
lo
pe
nac
ha
nn
e
loft
hed
e
f
a
u
l
tt
y
pewh
e
n
it connects. If you want to instead use a special-purpose SSH facility, you should
provide the information necessary for creating it before you activate the connection.
You can also open further channels after the connection has been completed, the
pr
oc
e
s
si
sd
e
s
c
r
i
b
e
di
n“
SSH Multiple Channels”o
npa
g
e116. If you try to specify
the use of more than one channel before the session has been activated, cryptlib will
return CRYPT_ERROR_INITED when you try to create any channel after the first
one
,
s
i
nc
ei
t
’
sonl
yp
os
s
i
b
l
et
or
e
que
s
tf
ur
t
h
e
rc
ha
nne
l
son
c
et
hei
ni
t
i
a
lc
h
a
n
ne
lha
s
been successfully established.

SSH Subsystems
Alongside the default encrypted link service, SSH provides additional services such
as SFTP, an application-level file transfer protocol tunnelled over the SSH link via a
subsystem channel. If you plan to use SFTP, note the comment about the SSH
performance handbrake at the start of this section. Although cryptlib avoids this
problem, non-cryptlib implementations f
r
e
qu
e
n
t
l
ydo
n’
t
,
s
ot
ha
tt
h
epe
r
f
or
ma
n
c
eo
f
SFTP can be quite poor (as much as ten times slower than the network link speed) in
some cases.
Youc
a
ns
pe
c
i
f
yt
h
eus
eo
fas
ubs
y
s
t
e
m bys
e
t
t
i
ngt
hec
ha
n
ne
lt
y
p
et
o“
s
ubs
y
s
t
e
m”
and the first channel argument tot
hes
u
bs
y
s
t
e
mna
me
,
i
nt
h
i
sc
a
s
e“
s
f
t
p
”
:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_SSH );
/* Add the server name, user name, and password */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
serverName, serverNameLength );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
username, usernameLength );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_PASSWORD,
password, passwordLength );

SSH Sessions

115

/* Request the creation of the subsystem channel */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_SSH_CHANNEL,
CRYPT_UNUSED );
cryptSetAttributeString( cryptSession,
CRYPT_SESSINFO_SSH_CHANNEL_TYPE, "subsystem", 9 );
cryptSetAttributeString( cryptSession,
CRYPT_SESSINFO_SSH_CHANNEL_ARG1, "sftp", 4 );
/* Activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

Note that SFTP is not a part of the SSH protocol (it can also be run over SSL or
IPsec, or directly over raw sockets), but simply an RPC mechanism for the Posix
filesystem API. The handling of this RPC mechanism, and support for features such
as translation of filenames, types, attributes, and operations to and from the Posix
interface, is an application-specific issue outside the scope of cryptlib.

SSH Port Forwarding
Al
ong
s
i
des
t
a
n
da
r
dSSHc
on
n
e
c
t
i
onsa
ndSSHs
ubs
y
s
t
e
ms
,
i
t
’
sa
l
s
op
os
s
i
bl
et
o
perform port-forwarding using SSH channels. Port forwarding allows you to tunnel
an arbitrary network connection over SSH to avoid having the data being sent over
the network in the clear. For example you could use this to tunnel mail (SMTP to
send, POP3 or IMAP to receive) over SSH to and from a remote host. SSH provides
two types of port forwarding, forwarding from the client to the server, identified by a
c
ha
nne
lt
y
peo
f“
di
r
e
c
t
-t
c
p
i
p
”
,
a
ndf
or
wa
r
di
ngf
r
omt
hes
e
r
v
e
rt
ot
hec
l
i
e
nt
,
i
d
e
nt
i
f
i
e
d
byac
ha
n
ne
lt
y
peo
f“
t
c
pi
p-f
o
r
wa
r
d”
.Theonl
yo
net
h
a
t
’
sn
or
ma
l
l
yus
e
di
sc
l
i
e
n
t
-toserver forwarding.
For client-to-server forwarding with a channelt
y
peo
f“
d
i
r
e
c
t
-t
c
pi
p
”
,
t
hef
i
r
s
tc
ha
n
ne
l
argument is the remote host and port that you want to forward to. For example if you
wanted to tunnel SMTP mail traffic to mailserver.com with SMTP being on port 25
(so the forwarding string would be mailserver.com:25), you would use:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_SSH );
/* Add the server name, user name, and password */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
serverName, serverNameLength );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
username, usernameLength );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_PASSWORD,
password, passwordLength );
/* Request the creation of the port-forwarding channel */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_SSH_CHANNEL,
CRYPT_UNUSED );
cryptSetAttributeString( cryptSession,
CRYPT_SESSINFO_SSH_CHANNEL_TYPE, "direct-tcpip", 12 );
cryptSetAttributeString( cryptSession,
CRYPT_SESSINFO_SSH_CHANNEL_ARG1, "mailserver.com:25", 17 );
/* Activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

When cryptlib activates the connection, it will indicate to the remote SSH server that
it should forward data sent over the SSH link to port 25 on mailserver.com. You
can now either push data directly into the session to tunnel it to the remote server, or
create a socket to listen on port 25 on the local machine and push data received on it
into the session, creating a local to remote system port forwarding over the SSH
channel.
Before you forward the data on the server as requested by the client, you should
check to make sure that the requested forwarding is in fact permitted. For example a
malicious user could use port forwarding to attack a machine inside your firewall by
forwarding connections through the firewall over an SSH tunnel. Because of this,
cryptlib will never open a forwarded connection by itself, but requires that you

116

Secure Sessions

explicitly forward the data. In other words it will indicate that port forwarding has
been requested, but will never of its own volition open and/or forward arbitrary ports
just because a client has requested it.
I
fy
oudo
n
’
twa
ntt
oa
l
l
owt
hepor
tf
or
wa
r
di
ng
,
a
l
ly
oune
e
dt
odoi
si
g
nor
et
hep
or
t
for
wa
r
di
ngc
ha
nne
l
.c
r
y
pt
l
i
b’
sde
f
a
ul
ta
c
t
i
o
ni
st
ono
ta
l
l
o
wf
or
wa
r
de
dc
on
ne
c
t
i
o
ns
,
making it impossible for a client to remotely access internal machines or ports unless
you explicitly allow it.

SSH Multiple Channels
Although SSH is usually used to provide a straightforward secure link from one
s
y
s
t
e
mt
oa
n
ot
h
e
r
,
i
t
’
sa
l
s
op
o
s
s
i
bl
et
ous
ei
tt
omul
t
i
p
l
e
xmul
t
i
p
l
ev
i
r
t
ua
ls
e
s
s
i
o
ns
across a single logical session. This is done by tunnelling multiple data channels
across the SSH link.
SSH implements this using in-band signalling, which means that control information
a
ndda
t
as
ha
r
et
h
es
a
mel
i
nk
.Wi
t
has
i
ng
l
eda
t
ac
h
a
n
ne
l(
t
hes
t
a
nda
r
dc
a
s
e
)t
h
i
si
s
n
’
t
a problem, but with multiple data channels control information for one channel can be
impeded by data being sent or received on another channel. For example if you need
to send or receive control information (channel close/channel open/status
i
n
f
or
ma
t
i
o
n)a
ndt
he
r
e
’
sada
t
at
r
a
ns
f
e
ri
npr
og
r
e
s
sona
not
he
rc
ha
nn
e
l
,
t
h
ec
o
nt
r
o
l
i
n
f
or
ma
t
i
o
nc
a
n
’
tbes
e
ntorr
e
c
e
ived until the data transfer has been completed. This
is why virtually all networking protocols use out-of-band signalling, with a separate
me
c
ha
ni
s
mf
orc
o
nt
r
o
ls
i
g
na
l
l
i
ngt
ha
tc
a
n
’
tbei
mpe
d
e
dbyda
t
at
r
a
ns
f
e
r
sont
hel
i
nk
.
Because of the in-band signalling problem, there are a number of special-case
considerations that you need to take into account when using multiple SSH data
c
ha
nne
l
s
.Thepr
i
ma
r
yonei
s
:Don’
td
oi
t
.Unl
e
s
sy
our
e
a
l
l
yha
v
eas
t
r
ongne
e
dt
o
run with multiple channels, just stick to a single channel and everything will be OK.
If you really need to use multiple channels, your code will need to take some extra
s
t
e
pst
oha
nd
l
et
h
epr
o
bl
e
msc
a
us
e
dbySSH’
si
n-band signalling. The standard
approach to this problem is to run the SSH implementation as a standalone service or
daemon, with a full-time thread or task dedicated to nothing but handling any control
messages that may arrive. These standalone applications are capable of opening ports
to local and remote systems, logging on users, initiating data transfers, and so on.
Si
nc
ei
t
’
spr
ob
a
bl
yn
otag
oodi
de
af
orc
r
y
pt
l
i
bt
oo
pe
na
r
bi
t
r
a
r
ypor
t
sort
r
a
ns
f
e
rf
i
l
e
s
without any additional checking, your application needs to explicitly manage these
control messages. This requires doing the following:

 Try and open all channels and send all control messages right after the connect,
before any data transfers are initiated. This means that the control signalling
won’
tbes
t
a
l
l
e
db
e
hi
ndda
t
as
i
g
na
l
l
i
ng
.

 Avoid using the session in non-blocking mode or with a very small timeout.
Using a very short timeout increases the chances of some data remaining
unwritten or unread, which will cause control information to become stalled
behind it.

 Periodically try and pop data to handle any new control messages that may have
arrived on other channels. In standalone SSH implementations that run as
services or daemons, this is handled by having a full-time thread or task
dedicated to this function. If you want to take this approach in your application,
you can use a user-supplied socket that you can wait on in your application as
de
s
c
r
i
be
di
n“
Network Issues”onp
a
g
e127.

 Trying to perform channel control actions can result in a CRYPT_ERROR_INCOMPLETE status ift
h
e
r
e
’
sda
t
as
t
i
l
lwa
i
t
i
ngt
ober
e
a
dorwr
i
t
t
e
n.Thi
s
oc
c
ur
sbe
c
a
us
ei
t
’
sn
otp
os
s
i
b
l
et
os
e
ndorr
e
c
e
i
v
ec
o
nt
r
o
li
nf
or
ma
t
i
onf
ora
n
ot
he
r
channel until the data for the current channel has been cleared. Since new data
c
a
na
r
r
i
v
ea
f
t
e
ry
ou
’
v
ec
l
e
a
r
e
dt
he existing data but before you can send the
control message, you may need to run this portion of your code in a loop to
ensure that the channel is clear so that you can send the control information.

SSL/TLS Sessions

117

Note that both the send and receive sides of the channel have to be cleared to
allow the control message to be sent and a response received.
I
fy
ou’
v
ed
e
c
i
de
dt
ha
ty
our
e
a
l
l
ydon
e
e
dt
ous
emul
t
i
p
l
eSSHc
ha
nn
e
l
s
,
y
ouc
a
n
manage them using the CRYPT_SESSINFO_SSH_CHANNEL attribute, which
contains an integer value that uniquely identifies each channel. You can select the
channel to send on by setting this attribute before you push data, and determine the
channel that data is being received on by reading it before you pop data:
int receiveChannelID, bytesCopied;
/* Send data over a given channel */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_SSH_CHANNEL,
sendChannelID );
cryptPushData( cryptSession, data, dataSize, &bytesCopied );
/* Receive data sent over a channel */
cryptGetAttribute( cryptSession, CRYPT_SESSINFO_SSH_CHANNEL,
&receiveChannelID );
cryptPopData( cryptSession, buffer, bufferSize, &bytesCopied );

Re
a
da
ndwr
i
t
ec
ha
nn
e
l
sa
r
ed
i
s
t
i
nc
t
,
s
os
e
t
t
i
ngt
hewr
i
t
ec
h
a
nn
e
ld
oe
s
n
’
tc
ha
ng
et
he
read channel, which is specified in incoming data messages that arrive.
I
fy
ou’
r
eope
ni
nga
ddi
t
i
on
a
lc
ha
n
ne
l
sa
f
t
e
rt
hes
e
s
s
i
onha
nd
s
ha
k
eha
sc
o
mpl
e
t
e
d,
y
ou
need to tell cryptlib when to activate the newly-created channel. To do this, you set
its CRYPT_SESSINFO_SSH_CHANNEL_ACTIVE attribute to true, which activates
the channel by sending the details to the remote system. Using the previous example
of a port-forwarding channel, if you wanted to open this additional channel after the
session had already been established you would use:
/* Request the creation of the port-forwarding channel */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_SSH_CHANNEL,
CRYPT_UNUSED );
cryptSetAttributeString( cryptSession,
CRYPT_SESSINFO_SSH_CHANNEL_TYPE, "direct-tcpip", 12 );
cryptSetAttributeString( cryptSession,
CRYPT_SESSINFO_SSH_CHANNEL_ARG1, "mailserver.com:25", 17 );
/* Activate the newly-created channel */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_SSH_CHANNEL_ACTIVE,
1 );

If you want to close one of the additional channels, you can select it in the usual
manner and then deactivate it by setting its CRYPT_SESSINFO_SSH_CHANNEL_ACTIVE attribute to false:
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_SSH_CHANNEL,
channelID );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_SSH_CHANNEL_ACTIVE,
0 );

If you try to deactivate the last remaining channel, which corresponds to the session
itself, cryptlib will return a CRYPT_ERROR_PERMISSION status. To close the
final channel, you need to close the overall session.

SSL/TLS Sessions
SSL/TLS is a secure data transfer protocol that provides confidentiality, integrityprotection, protection against replay attacks, and a variety of other services. The SSL
s
e
r
v
e
ri
sa
ut
he
nt
i
c
a
t
e
dv
i
aac
e
r
t
i
f
i
c
a
t
e
,
a
n
dt
h
ec
l
i
e
n
ti
s
n
’
ta
ut
he
n
t
i
c
a
t
e
d(
i
nr
a
r
e
circumstances client certificates may be used, but these are usually avoided due to the
high degree of difficulty involved in working with them). Alternatively, the client
and server may be mutually authenticated via a secret-key mechanism such as a user
name and password, which avoids the need for certificates altogether. cryptlib
supports SSL version 3, TLS version 1.0 (a.k.a SSL version 3.1), and TLS version 1.1
(a.k.a SSL version 3.2).
SSL and TLS are actually variations of the same protocol, the protocol known by the
generic term SSL is SSL v3.0 and TLS is SSL v3.1. A newer revision of TLS, TLS
version 1.1, is SSL v3.2. cryptlib will automatically negotiate the highest protocol

118

Secure Sessions

version supported by the other side and use that to secure the session. You can
determine which version is in use once the session has been established by reading
the CRYPT_SESSINFO_VERSION attribute, a value of 0 indicates version 3.0 or
SSL, a value of 1 indicates version 3.1 or TLS, and a value of 2 indicates version 3.2
or TLS version 1.1. You can also force the use of a particular version by setting the
protocol version attribute before you activate the connection, for example you can
have cryptlib function as an SSL-only server by setting the CRYPT_SESSINFO_VERSION to 0 to indicate the use of SSL version 3.0 rather than TLS version 3.1. A
(fortunately) small number of buggy servers will fail the SSL handshake if the
protocol version is advertised as TLS, if you receive a handshake failure alert when
you try to activate the session (as indicated by the CRYPT_ATTRIBUTE_INT_ERRORMESSAGE attribute) you can try forcing the use of SSL to see if the server
can handle a connect using only the older protocol version.
Because TLS v1.1 is relatively new and not widely supported yet (meaning that some
clients and servers will break if they encounter a server or client that advertises this
protocol version), cryptlib by default advertises TLS v1.0 as its highest protocol level.
If you want to explicitly advertise TLS v1.1, you can set the CRYPT_SESSINFO_VERSION attribute to 2 before you activate the session to indicate the use of SSL
v3.2 or TLS v1.1.

SSL/TLS Client Sessions
Establishing a session with an SSL/TLS server requires adding the server name or IP
a
ddr
e
s
sa
nda
nop
t
i
ona
lp
or
tn
umbe
ri
fi
ti
s
n’
tus
i
ngt
hes
t
a
n
da
r
dSSL/
TLS port.
Onc
ey
ou
’
v
ea
dd
e
dt
hi
si
nf
or
ma
t
i
o
n,
y
ouc
a
na
c
t
i
v
a
t
et
hes
e
s
s
i
ona
n
de
s
t
a
bl
i
s
ht
h
e
connection:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_SSL );
/* Add the server name and activate the session */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
serverName, serverNameLength );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

The same operation in Java or C# is:
/* Create the session */
int cryptSession = crypt.CreateSession( cryptUser,
crypt.SESSION_SSL );
/* Add the server name and activate the session */
crypt.SetAttributeString( cryptSession, crypt.SESSINFO_SERVER_NAME,
serverName );
crypt.SetAttribute( cryptSession, crypt.SESSINFO_ACTIVE, 1 );

The Visual Basic form of the code is:
Dim cryptSession As Long
' Create the session
cryptCreateSession cryptSession, cryptUser, CRYPT_SESSION_SSL
' Add the server name and activate the session
cryptSetAttributeString cryptSession, CRYPT_SESSIONFO_SERVER_NAME, _
serverName, Len( serverName )
cryptSetAttribute cryptSession, CRYPT_SESSINFO_ACTIVE, 1

Activating a session results in cryptlib performing a lot of work in the background.
For example when activating the SSL/TLS session shown above cryptlib will connect
t
ot
her
e
mot
ehos
t
,
r
e
a
dt
h
es
e
r
v
e
r
’
sc
e
r
t
i
f
i
c
a
t
e
,
g
e
ne
r
a
t
eas
e
c
r
e
tda
t
av
a
l
u
et
o
exchange with the server using the key contained in the certificate, create the
appropriate encryption contexts and load keys based on the secret data value into
them, negotiate general session parameters, and complete negotiating the encrypted
link with the server.

SSL/TLS Sessions

119

SSL/TLS with Shared Keys
Note: The use of SSL/TLS sessions using shared keys is based on a draft standard
from the TLS working group that may be subject to further changes before the final
standard is adopted. You should avoid deploying solutions based on this mechanism
until the standard has been finalised by the TLS working group.
I
ft
hes
e
r
v
e
ry
ou’
r
ec
on
ne
c
t
i
n
gt
ous
e
ss
ha
r
e
dk
e
y
s(
f
ore
x
a
mp
l
eaus
e
rna
me and
password), you need to provide this information via the CRYPT_SESSINFO_USERNAME and CRYPT_SESSINFO_PASSWORD attributes to authenticate
yourself to the server before you activate the connection:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_SSL );
/* Add the server name, user name, and password */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
serverName, serverNameLength );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
username, usernameLength );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_PASSWORD,
password, passwordLength );
/* Activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

The equivalent operation in Java or C# is:
/* Create the session */
int cryptSession = crypt.CreateSession( cryptUser,
crypt.SESSION_SSL );
/* Add the server name, user name, and password */
crypt.SetAttributeString( cryptSession, crypt.SESSINFO_SERVER_NAME,
serverName );
crypt.SetAttributeString( cryptSession, crypt.SESSINFO_USERNAME,
username );
crypt.SetAttributeString( cryptSession, crypt.SESSINFO_PASSWORD,
password );
/* Activate the session */
crypt.SetAttribute( cryptSession, crypt.SESSINFO_ACTIVE, 1 );

In Visual Basic this is:
Dim cryptSession As Long
' Create the session
cryptCreateSession cryptSession, cryptUser, CRYPT_SESSION_SSL
' Add the server name, user name, and password
cryptSetAttributeString cryptSession, CRYPT_SESSINFO_SERVER_NAME, _
serverName, Len( serverName )
cryptSetAttributeString cryptSession, CRYPT_SESSINFO_USERNAME, _
userName, Len( userName )
cryptSetAttributeString cryptSession, CRYPT_SESSINFO_PASSWORD, _
password, Len( password )
' Activate the session
cryptSetAttribute cryptSession, CRYPT_SESSINFO_ACTIVE, 1

Authenticating yourself using shared keys avoids the need for both server and client
certificates, providing mutual authentication for both client and server (conventional
SSL only authenticates the server using a server certificate). This type of key
management also avoids the high CPU overhead of public-key encryption, making it
ideal for use in resource-c
ons
t
r
a
i
n
e
de
nv
i
r
on
me
nt
soro
ne
swhe
r
ey
ou’
r
ec
ha
r
g
e
df
or
CPU usage.

SSL/TLS with Client Certificates
I
ft
hes
e
r
v
e
ry
ou’
r
ec
on
ne
c
t
i
n
gt
orequires a client certificate, you need to provide a
private key with an attached signing certificate via the CRYPT_SESSINFO_-

120

Secure Sessions

PRIVATEKEY attribute to authenticate yourself to the server before you activate the
session. The private key could be a native cryptlib key, but it could also be a key
from a crypto device such as a smart card or Fortezza card. They both work in the
same way for client authentication:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_SSL );
/* Add the server name and client key/certificate and activate the
session */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
serverName, serverNameLength );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_PRIVATEKEY,
cryptPrivateKey );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

When cryptlib connects to the server, it will use the provided private key and
certificate as part of the SSL/TLS handshake to authenticate the client to the server.
If thes
e
r
v
e
rdoe
s
n
’
tr
e
q
ui
r
et
heus
eo
fac
l
i
e
ntc
e
r
t
i
f
i
c
a
t
e
,
c
r
y
pt
l
i
bwo
n’
td
oa
ny
t
h
i
ng
wi
t
ht
hepr
i
v
a
t
ek
e
y
,
s
oi
t
’
sOKt
oa
ddt
hi
se
v
e
ni
fy
o
u’
r
en
ots
ur
ewhe
t
he
ri
t
’
l
lb
e
needed or not.
Note that client certificates are very rarely used in practice because of the high level
of difficulty involved in working with them. If you require client authentication, a far
better solution is to either use a traditional authentication mechanism such as sending
an authenticator like a password over the SSL connection, or to use SSL with shared
keys, which provides mutual authentication of both client and server.

SSL/TLS Server Sessions
Establishing an SSL/TLS server session requires adding the server key/certificate,
activating the session, and waiting for incoming connections:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser,
CRYPT_SESSION_SSL_SERVER );
/* Add the server key/certificate and activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_PRIVATEKEY,
privateKey );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

The same procedure in Visual Basic is:
Dim cryptSession As Long
' Create the session
cryptCreateSession cryptSession, cryptUser, _
CRYPT_SESSION_SSL_SERVER
' Add the server key/certificate and activate the session
cryptSetAttribute cryptSession, CRYPT_SESSIONFO_PRIVATEKEY, privateKey
cryptSetAttribute cryptSession, CRYPT_SESSINFO_ACTIVE, 1

Once you activate the session, cryptlib will block until an incoming client connection
arrives, at which point it will negotiate a secure connection with the client.

SSL/TLS Servers with Shared Keys
Note: The use of SSL/TLS sessions using shared keys is based on a draft standard
from the TLS working group that may be subject to further changes before the final
standard is adopted. You should avoid deploying solutions based on this mechanism
until the standard has been finalised by the TLS working group.
I
fy
ou’
r
eus
i
ngs
ha
r
e
dk
e
y
s(
f
ore
x
a
mp
l
eaus
e
rn
a
mea
n
dp
a
s
s
wor
d)t
opr
ov
i
de
security, you need to provide this information via the CRYPT_SESSINFO_USERNAME and CRYPT_SESSINFO_PASSWORD attributes. For example if you
have a server that allows one of three users/clients to connect to it you would use:

SSL/TLS Sessions

121

CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser,
CRYPT_SESSION_SSL_SERVER );
/* Add the user names and passwords */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
username1, username1Length );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_PASSWORD,
password1, password1Length );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
username2, username2Length );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_PASSWORD,
password2, password2Length );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
username3, username3Length );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_PASSWORD,
password3, password3Length );
/* Activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

Using shared keys in this manner avoids the need for both server and client
certificates, providing mutual authentication for both client and server (conventional
SSL only authenticates the server via a server certificate). This type of key
management also avoids the high CPU overhead of public-key encryption, making it
ideal for use in resource-c
ons
t
r
a
i
n
e
de
nv
i
r
on
me
nt
soro
ne
swhe
r
ey
ou’
r
ec
ha
r
g
e
df
or
CPU usage.
If you have clients who need to connect without providing a user name and password,
you can still provide a server certificate in the usual manner using the CRYPT_SESSI
NFO_PRI
VATEKEYa
t
t
r
i
bu
t
e
,
a
n
dc
l
i
e
nt
swh
od
on
’
tpr
ov
i
deaus
e
rna
mea
nd
password will connect using public-key encryption. Note though that a client that
uses the server certificate rather than a user name and password loses the benefits of
mutual client/server authentication, as well as incurring a higher CPU overhead due
to the use of public-key encryption.
Once a client has authenticated themselves using a shared key, you can determine
their identity by reading back the CRYPT_SESSINFO_USERNAME attribute:
char username[ CRYPT_MAX_TEXTSIZE + 1 ];
int usernameLength
/* Get the user name */
cryptGetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
username, &usernameLength );
username[ usernameLength ] = '\0';

If the attempt by the client to connect fails (typically due to the use of an incorrect
password), the password information for that user will be reset to prevent passwordguessing attacks in which an attacker repeatedly reconnects using every possible
password until they succeed. If the password is reset, you need to re-add the user and
password to the session before that particular user can connect again. In order to
protect against password-guessing attacks you should employ standard precautions
such as allowing a maximum of three incorrect attempts or inserting a time delay
before another connect attempt is allowed.

SSL/TLS Servers with Client Certificates
If you want to use client certificates to authenticate incoming connections, you need
to provide a public-key keyset or certificate store for cryptlib to use to check
certificates provided by client connections. When a client tries to establish a
connection, cryptlib will check that their certificate is pres
e
nti
nt
hek
e
y
s
e
t
.I
fi
ti
s
n’
t
pr
e
s
e
n
t
,
t
hec
on
ne
c
t
i
oni
s
n’
tp
e
r
mi
t
t
e
d.Thi
spr
ov
i
de
sav
e
r
yf
i
ne
-grained level of
access control through which individual end users can be permitted or denied access
to the host. Since cryptlib uses the keyset to verify incoming connections, you can
control who is allowed in by adding or removing their certificate to or from the
keyset. Note that you must provide a public-key keyset that stores certificates (not a

122

Secure Sessions

private-key keyset) to the session since SSL/TLS uses certificates for the access
control functionality.
You can specify the public-key keyset to use for checking incoming connections with
the CRYPT_SESSINFO_KEYSET attribute:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser,
CRYPT_SESSION_SSL_SERVER );
/* Add the server key and public-key keyset and activate the
session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_PRIVATEKEY,
privateKey );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_KEYSET, cryptKeyset );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

When you set this attribute for a server session, cryptlib will require the use of client
c
e
r
t
i
f
i
c
a
t
e
sf
orc
o
nn
e
c
t
i
o
nst
ot
hes
e
r
v
e
r
,
a
ndwon
’
ta
l
l
owc
onn
e
c
t
i
o
nsf
r
o
mc
l
i
e
nt
s
t
ha
ta
r
e
n
’
ta
bl
eto authenticate themselves using a certificate that was previously
added to the keyset.

Request/Response Protocol Sessions
cryptlib supports a variety of request/response protocols including protocols such as
the certificate management protocol (CMP), simple certificate enrolment protocol
(SCEP), real-time certificate status protocol (RTCS), online certificate status protocol
(OCSP), and timestamping protocol (TSP). CMP, SCEP, RTCS, and OCSP client
sessions are certificate management services that are cove
r
e
di
n“
Obtaining
Certificates using CMP”
,
“
Obtaining Certificates using SCEP”
,
“
Certificate Status
Checking using RTCS”
,
a
nd“
Certificate Revocation Checking using OCSP”on
pages 167, 162, 162, and 168, and a TSP client session is an S/MIME service which
i
sc
ov
e
r
e
di
n“
Timestamping”onpa
g
e93. RTCS, OCSP and TSP server sessions are
standard session types and are also covered here, CMP and SCEP server sessions are
s
ome
wha
tmor
ec
o
mp
l
e
xa
n
da
r
ec
ov
e
r
e
di
n“
Managing a CA using CMP or SCEP”
on page 176.

RTCS Server Sessions
An RTCS server session is a protocol-specific session type that returns a real-time
certificate status to a client. RTCS client sessions are used for certificate status
c
he
c
k
sa
n
da
r
ede
s
c
r
i
be
di
n“
Certificate Status Checking using RTCS”onpa
g
e162.
Establishing an RTCS server session requires adding a certificate store that cryptlib
can query for certificate status information, specified as the CRYPT_SESSINFO_KEYSET attribute, and an optional RTCS responder key/certificate if you want
cryptlib to sign the responses it provides. Certificate stores are described in more
de
t
a
i
li
n“
Managing a Certification Authority”onpa
g
e171.Onc
ey
ou’
v
ea
d
de
dt
h
i
s
information you can activate the session and wait for incoming connections:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser,
CRYPT_SESSION_RTCS_SERVER );
/* Add the certificate store and activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_KEYSET,
cryptCertStore );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

Once you activate the session, cryptlib will block until an incoming client connection
arrives, at which point it will read the RTCS request from the client and return a
response optionally signed with the RTCS responder key.

Request/Response Protocol Sessions

123

OCSP Server Sessions
An OCSP server session is a protocol-specific session type that returns certificate
revocation information to a client. OCSP client sessions are used for certificate
r
e
v
oc
a
t
i
onc
he
c
k
sa
n
da
r
ede
s
c
r
i
be
di
n“
Certificate Revocation Checking using
OCSP”onpa
g
e162.
The difference between RTCS and OCSP is that RTCS provides real-time, live
certificate status information while OCSP provides delayed revocation information,
us
ua
l
l
yba
s
e
donCRLs
.I
not
he
rwor
dsRTCSa
ns
we
r
st
heque
s
t
i
o
n“
I
s this
c
e
r
t
i
f
i
c
a
t
eOKt
ous
er
i
g
htno
w?
”whi
l
eOCSPa
ns
we
r
st
heque
s
t
i
o
n“
Wa
st
hi
s
c
e
r
t
i
f
i
c
a
t
er
e
v
ok
e
da
ts
o
mep
oi
n
ti
nt
hepa
s
t
?
”
.OCSPc
a
n
’
tr
e
t
ur
nt
r
uev
a
l
i
di
t
y
information, so that if fed a freshly-i
s
s
ue
dc
e
r
t
i
f
i
c
a
t
ea
n
da
s
k
e
d“
I
st
hi
sav
a
l
i
d
certific
a
t
e
”
,
i
tc
a
n'
ts
a
y“
Ye
s
”(
aCRLc
a
nonl
ya
ns
we
r“
r
e
v
ok
e
d”
)
,
a
n
di
ff
e
daf
or
g
e
d
c
e
r
t
i
f
i
c
a
t
ei
tc
a
n'
ts
a
y“
No”(
i
twon’
tbepr
e
s
e
nti
na
nyCRL)
.I
na
ddi
t
i
onOCSPwi
l
l
often return a status result drawn from stale information hours or even days old, while
RTCS (as the name implies) will always return real-time information. Finally, OCSP
uses a peculiar means of identifying certificates that some implementations disagree
ov
e
r
,
wi
t
ht
her
e
s
u
l
tt
ha
tac
e
r
t
i
f
i
c
a
t
ema
yber
e
g
a
r
de
da
sv
a
l
i
de
v
e
ni
fi
ti
s
n
’
tbe
c
a
use
client and server are talking about different things. In contrast RTCS returns an
unambiguous yes-or-no response drawn from live certificate data. For these reasons
RTCS is the cryptlib preferred certificate status protocol.
Establishing an OCSP server session requires adding the OCSP responder
key/certificate and a certificate store that cryptlib can query for certificate status
information, specified as the CRYPT_SESSINFO_KEYSET attribute. Certificate
s
t
or
e
sa
r
ede
s
c
r
i
be
di
nmor
ed
e
t
a
i
li
n“
Managing a Certification Authority”onp
a
g
e
171.Onc
ey
o
u’
v
ea
dde
dt
hi
si
n
f
or
ma
t
i
o
ny
ouc
a
na
c
t
i
v
a
t
et
hes
e
s
s
i
o
na
n
dwa
i
tf
or
incoming connections:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser,
CRYPT_SESSION_OCSP_SERVER );
/* Add the OCSP responder key/certificate and certificate store and
activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_PRIVATEKEY,
privateKey );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_KEYSET,
cryptCertStore );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

Once you activate the session, cryptlib will block until an incoming client connection
arrives, at which point it will read the OCSP request from the client and return a
response signed with the OCSP responder key.

TSP Server Sessions
A TSP server session is a protocol-specific session type that returns timestamp
information to a client. TSP client sessions are used with S/MIME and are described
i
n“
Timestamping”onpa
g
e93. Establishing a TSP server session requires adding the
timestamping authority (TSA) key/certificate, activating the session, and waiting for
incoming connections:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser,
CRYPT_SESSION_TSP_SERVER );
/* Add the TSA key/certificate and activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_PRIVATEKEY, privateKey
);
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

The TSA certificate must be one that has the CRYPT_CERTINFO_EXTKEY_TIMESTAMPING extended key usage attribute set to indicate that it can be used for

124

Secure Sessions
generating timestamps. Extended key usagea
t
t
r
i
but
e
sa
r
ede
s
c
r
i
be
di
n“
Key Usage,
Extended Key Usage, and Netscape certificate type”onp
a
g
e241. If you add a
key/certificate without this attribute, cryptlib will return CRYPT_ERROR_PARAM3
to indicate that the key parameter is invalid.
Once you activate the session, cryptlib will block until an incoming client connection
arrives, at which point it will read the timestamp request from the client and return a
timestamp signed with the TSA key.

Obtaining Session Status Information
When a session is established a lot of state information is exchanged between the
client and server and status information is generated by both sides. After the session
has been activated you can query the session object for information such as the
session status, which security parameters are being used, the identity of the remote
client that connected to your server (the identity of the remote server is already
k
nowni
fy
o
u’
r
et
hec
l
i
e
nt
)
,
a
nda
ut
h
e
n
t
i
c
a
t
i
ona
ndi
de
nt
i
f
i
cation information that was
obtained from the client or server during the session establishment process.

Obtaining Session Security Parameters
If you want to know the details of the encryption mechanism which is being used to
protect the session, you can read various CRYPT_CTXINFO_xxx attributes from the
session object, which will return information from the encryption context(s) that are
be
i
ngus
e
dt
os
e
c
ur
et
hes
e
s
s
i
on.Fore
x
a
mp
l
eo
nc
ey
o
u’
v
ea
c
t
i
v
a
t
e
dt
hes
e
s
s
i
ony
ou
can get the encryption algorithm, mode, and the key size being used with:
CRYPT_ALGO_TYPE cryptAlgo;
CRYPT_MODE_TYPE cryptMode;
int keySize;
cryptGetAttribute( cryptSession, CRYPT_CTXINFO_ALGO, &cryptAlgo );
cryptGetAttribute( cryptSession, CRYPT_CTXINFO_MODE, &cryptMode );
cryptGetAttribute( cryptSession, CRYPT_CTXINFO_KEYSIZE, &keySize );

Authenticating the Host with Key Fingerprints
Onc
ey
ou
’
v
ec
on
ne
c
t
e
dt
oas
e
r
v
e
r
,y
ouc
a
nv
e
r
i
f
yt
hes
e
r
v
e
r
’
sc
e
r
t
i
f
i
c
a
t
eork
e
y
fingerprint by reading the CRYPT_SESSINFO_SERVER_FINGERPRINT attribute,
whic
hc
on
t
a
i
nsaf
i
ng
e
r
pr
i
ntv
a
l
uet
ha
tun
i
q
ue
l
yi
de
n
t
i
f
i
e
st
hes
e
r
v
e
r
’
sc
e
r
t
i
f
i
c
a
t
eor
key. You can compare this to a stored copy of the fingerprint, or format it for display
to the user.
If you set the CRYPT_SESSINFO_SERVER_FINGERPRINT attribute before you
connect to the server, cryptlib will verify it against the server key when it connects
and break off the connection attempt with a CRYPT_ERROR_WRONGKEY status if
t
hes
e
r
v
e
r
’
sc
e
r
t
i
f
i
c
a
t
eork
e
ydoe
s
n’
tma
t
c
ht
h
ef
i
ng
e
r
pr
i
nty
ou’
v
es
pe
c
i
f
i
e
d.Thi
s
allows you to filter out bogus servers and/or keys before you try to send any sensitive
information to them.
Tode
t
e
r
mi
net
hes
e
r
v
e
r
’
sk
e
yf
i
ng
e
r
pr
i
nt(
wi
t
ho
utha
v
i
ngt
oc
o
nne
c
tt
oi
tf
i
r
s
t
)
,
y
ou
can read the CRYPT_SESSINFO_SERVER_FINGERPRINT attribute from the SSH
s
e
r
v
e
rs
e
s
s
i
ona
f
t
e
ry
ou
’
v
ea
d
de
dt
hes
e
r
v
e
r
’
spr
i
v
a
t
ek
e
y
,
a
ndt
heCRYPT_CERTINFO_FINGERPRINT attribute from the SSL/TLS server certificate.
Using fingerprints for authentication is the most reliable of the methods covered here,
since it provides a gua
r
a
nt
e
e
dma
t
c
ht
oak
nownk
e
yt
ha
tc
a
n’
tbes
p
oo
f
e
dorf
or
g
e
d.

Authenticating the Host or Client using Certificates
In addition to providing integrity and privacy protection for a communications
session, some session protocols also provide a means of verifying that the host or
c
l
i
e
nty
ou
’
r
ec
on
ne
c
t
i
ngt
or
e
a
l
l
yi
swhot
he
yc
l
a
i
mt
obe
.Fore
v
e
r
y
t
hi
ngbutt
he
SSH protocol this authentication is performed by having the host supply a certificate
or certificate chain signed by a trusted CA which is used during the protocol
initialisation phase to establish the session. The general idea is that the certificate
c
on
t
a
i
nst
h
ena
meoft
heh
os
tt
ha
ty
ou’
r
ec
on
ne
c
t
i
ngt
oort
hena
meoft
hee
nt
i
t
y

Exchanging Data

125

which is providing a particular service (for example an RTCS responder), so you can
use the returned certificate to verify that you really are communicating with this host
and not a machine that has been set up by an attacker to masquerade as the host. In
a
dd
i
t
i
oni
fy
o
u’
r
eus
i
ngSSLorTLSwi
t
hc
l
i
e
ntc
e
r
t
i
f
i
c
a
t
e
s
,
y
ouc
a
nuse the
certificate provided by the client when they connect to verify their identity, and if
y
ou’
r
eus
i
ngSSLorTLSwi
t
hs
ha
r
e
dk
e
y
sy
oua
l
r
e
a
dyha
v
emut
ua
la
ut
he
nt
i
c
a
t
i
o
no
f
client and server without the need for certificates.
In practice due to factors such as outsourcing of web hosting services and the
r
e
l
oc
a
t
i
ono
fs
e
r
v
e
r
s
,
t
heh
os
tc
e
r
t
i
f
i
c
a
t
ef
r
e
qu
e
n
t
l
ydo
e
s
n
’
tc
or
r
e
s
po
ndt
ot
h
es
e
r
v
e
r
y
ou’
r
es
u
pp
os
e
dt
ob
ec
o
nne
c
t
i
ngt
o(
whi
c
hi
swhymos
tbr
ows
e
r
sonl
ydi
s
pl
a
ya
warning and then connect anyway, or don’
te
v
e
nwa
r
n)
.c
r
y
pt
l
i
bdo
e
s
n
’
tp
l
a
c
ea
ny
r
e
s
t
r
i
c
t
i
onsonwha
ti
twi
l
la
n
dwon
’
tc
o
nn
e
c
tt
oora
c
c
e
p
tr
e
s
po
ns
e
sf
r
o
m,
l
e
a
v
i
ngi
t
upt
oy
out
ode
t
e
r
mi
newh
e
t
h
e
ry
ouwa
ntt
oc
on
t
i
nuet
hes
e
s
s
i
oni
ft
hes
e
r
v
e
rdoe
s
n’
t
ma
t
c
hwha
t
’
sg
i
v
e
ni
nt
heh
os
tc
e
r
t
i
f
icate or expected by the client.
Onc
et
h
es
e
s
s
i
o
nha
sb
e
e
na
c
t
i
v
a
t
e
d,
y
ouc
a
nr
e
a
dt
h
ehos
torc
l
i
e
nt
’
sc
e
r
t
i
f
i
c
a
t
ec
h
a
i
n
as the CRYPT_SESSINFO_RESPONSE attribute:
CRYPT_CERTIFICATE cryptCertificate;
cryptGetAttribute( cryptSession, CRYPT_SESSINFO_RESPONSE,
&cryptCertificate );

You can then work with the certificate chain as usual, for example you can verify it
using cryptCheckCert or fetch the subject name information as explained in
“
Certificate Identification Information”onp
a
ge 214.

Authenticating the Client via Port and Address
In addition to the stronger fingerprint and certificate authentication mechanisms, you
c
a
na
l
s
ode
t
e
r
mi
net
h
eI
Pa
d
d
r
e
s
sa
ndp
or
tt
h
a
tac
l
i
e
nti
sc
onn
e
c
t
i
ngf
r
om i
fy
ou
’
r
e
r
unn
i
nga
sas
e
r
v
e
r(
i
fy
ou’
r
et
hec
l
i
e
nt
,
y
oua
l
r
e
a
dyk
nownwhi
c
hs
e
r
v
e
ra
ndp
or
t
y
ou’
r
ec
on
ne
c
t
i
ngt
o)
.Youc
a
no
bt
a
i
nt
hi
si
nf
or
ma
t
i
onbyr
e
a
di
ngt
heCRYPT_SESSINFO_CLIENT_NAME and CRYPT_SESSINFO_CLIENT_PORT attributes,
which work in a similar manner to the CRYPT_SESSINFO_SERVER_NAME and
CRYPT_SESSINFO_SERVER_PORT attributes:
char name[ CRYPT_MAX_TEXTSIZE + 1 ];
int nameLength, port
cryptGetAttributeString( cryptSession, CRYPT_SESSINFO_CLIENT_NAME,
name, &nameLength );
name[ nameLength ] = '\0';
cryptGetAttribute( cryptSession, CRYPT_SESSINFO_CLIENT_PORT, &port );

The same operation in Visual Basic is:
Dim name as String
Dim nameLength as Long
Dim port as Long
name = String( CRYPT_MAX_TEXTSIZE, vbNullChar );
cryptGetAttributeString cryptSession, CRYPT_SESSINFO_CLIENT_NAME, _
name, nameLength
name = Left( name, nameLength )
cryptGetAttribute cryptSession, CRYPT_SESSINFO_CLIENT_PORT, port

Not
et
h
a
tc
r
y
pt
l
i
br
e
t
ur
nst
hec
l
i
e
nt
’
sI
Pa
ddr
e
s
si
ndo
t
t
e
d-decimal form (for IPv4) or
colon-delimited form (for IPv6) rather than its full name, since a single IP address can
be aliased to multiple names and may require complex name resolution strategies. If
y
our
e
qu
i
r
eaf
ul
lna
mer
a
t
he
rt
ha
na
nI
Pa
ddr
e
s
sy
ou
’
l
lne
e
dt
or
e
s
o
l
v
ei
ty
our
s
e
l
f
,
taking into account the multiple hostname issue, the fact that the client may be using
NAT, and the possibility of DNS spoofing.

Exchanging Data
Once a general-purpose secure communications session has been established, you can
exchange data with the remote client or server over the encrypted, authenticated link
that it provides. This works exactly like pushing and popping data to and from an

126

Secure Sessions

envelope, except that the session is effectively a bottomless envelope that can accept
or return (depending on the remote system) an endless stream of data. In many cases
the overhead involved in wrapping up a block of data and exchanging it with a remote
client or server can be noticeable, so you should always push and pop as much data at
once into and out of a session as you can. For example if you have a 100-byte
message and communicate it to the remote host as 10 lots of 10 bytes, this is much
slower than sending a single lot of 100 bytes. This behaviour is identical to the
behaviour in applications like disk I/O, where writing a single big file to disk is a lot
more efficient than writing 10 smaller files.
cryptlib helps to eliminate this problem as much as possible by not wrapping up and
dispatching session data until you explicitly tell it to by flushing the data through just
as you would with an envelope:
cryptPushData( cryptSession, data, dataSize, &bytesCopied );
cryptFlushData( cryptSession );

In Visual Basic this is:
cryptPushData cryptSession, data, dataSize, bytesCopied
cryptFlushData cryptSession

This means that cryptlib will a
c
c
u
mul
a
t
ea
smuc
hda
t
aa
sp
os
s
i
b
l
ei
nt
hes
e
s
s
i
o
n’
s
internal buffer before encrypting and integrity-protecting it and sending it through to
the remote system, avoiding the inefficiency of processing and sending many small
blocks of data. Note that you only need to flush data through in this manner when
you explicitly want to force all of the data in the session buffer to be sent to the
r
e
mo
t
es
y
s
t
e
m.I
fy
oudo
n’
tf
or
c
eaf
l
us
hc
r
y
pt
l
i
bha
nd
l
e
st
hi
sa
u
t
o
ma
t
i
c
a
l
l
yi
nt
he
most efficient manner possible using its built-in buffering mechanisms.
When you close a session, cryptlib will immediately shut down the session as is,
without flushing data in internal session buffers. This is done to handle cases where a
session is aborted (for example because the user cancels the transaction or because of
a network error), and it becomes necessary to exit without sending further data. If
you want to send any remaining data before destroying the session, you need to
explicitly flush the data through before you destroy the session object (remember to
check the return status of the final flush to make sure that all of your data was indeed
sent).
Reading the response from the remote client or server works in a similar manner:
cryptPopData( cryptSession, buffer, bufferSize, &bytesCopied );

Unl
e
s
sy
ous
pe
c
i
f
yot
h
e
r
wi
s
e
,
a
l
lo
fc
r
y
pt
l
i
b
’
sne
t
wor
kope
r
a
t
i
onsa
r
en
on-blocking
and near-asynchronous, waiting only the minimum amount of time for data to be sent
or received before returning to the caller (you can make this fully asynchronous if
you want, see the next section). cryptlib will provide whatever data is available from
the remote client or server or write whatever is possible to the remote client or server
and then return, which is particularly important for interactive sessions where small
amounts of data are flowing back and forth simultaneously. The amount of data
which is returned is indicated by the bytesCopied parameter. If this value is zero
then no data is available or was written at the current time. Since the interface is nonblocking, your application can perform other processing while it waits for data to
arrive.
I
fy
ou’
dpr
e
f
e
rt
oha
v
ec
r
y
pt
l
i
bno
tbl
oc
ka
ta
l
lorbl
oc
kf
oral
ong
e
ra
mo
un
to
ft
i
me
when waiting for data to arrive or be sent, you can enable this behaviour as described
i
n“
Network Issues”onpa
g
e127. With blocking network operations enabled,
cryptlib will wait for a user-defined amount of time for data to arrive before returning
to the caller. If data arrives or is sent during the timeout interval, cryptlib returns
immediately. With non-blocking behaviour it will return immediately without
waiting for data to become available.
Si
nc
ec
r
y
pt
l
i
br
e
a
dsa
n
dwr
i
t
e
sa
r
ea
s
y
nc
hr
on
ous
,
y
ous
h
ou
l
dn
’
tassume that all the
da
t
ay
o
u’
v
er
e
q
ue
s
t
e
dh
a
sbe
e
nt
r
a
ns
f
e
r
r
e
dwhe
nt
h
epus
ho
rpopr
e
t
ur
ns
.c
r
y
pt
l
i
b
will only transfer as much data as it can before the timeout, which may be less than

Network Issues

127

the total amount. In particular if data is flowing in both directions at once (that is,
both sides are writing data and not reading it), the network buffers will eventually fill
up, resulting in no more data being written. If this happens you need to occasionally
interleave a read with the writes to drain the buffers and allow further data to be
transferred.

Network Issues
Some
t
i
me
sama
c
hi
newon
’
tc
on
ne
c
tdi
r
e
c
t
l
yt
ot
heI
n
t
e
r
ne
tbu
tha
st
oa
c
c
e
s
si
t
through a proxy. cryptlib supports common proxy servers such as socks, and also
supports HTTP proxies if the protocol being used is HTTP-based. In addition it may
be necessary to adjust other network-related parameters such as timeout values in
order to accommodate slow or congested network links or slow clients or servers.
The following sections explain how to work with the various network-related options
to handle these situations.

Secure Sessions with Proxies
Using a socks proxy requires that you tell cryptlib the name of the socks server and
a
no
pt
i
on
a
lus
e
rn
a
me(
mos
ts
e
r
v
e
r
sdon’
tbo
t
h
e
rwi
t
ht
heu
s
e
rna
me
)
.Youc
a
nset
the socks server name with the CRYPT_OPTION_NET_SOCKS_SERVER attribute
and the optional socks user name with the CRYPT_OPTION_NET_SOCKS_USERNAME attribute. For example to set the socks proxy server to the host called
socks (which is the name traditionally given to socks servers) you would use:
cryptSetAttributeString( CRYPT_UNUSED, CRYPT_OPTION_NET_SOCKS_SERVER,
"socks", 5 );

before activating the session. When you activate the session, cryptlib will
communicate with the proxy using the socks protocol.
Using an HTTP proxy works in a similar manner, with the name of the proxy being
specified with the CRYPT_OPTION_NET_HTTP_PROXY attribute. Note that
HTTP proxies require that the protocol being used employs HTTP as its transport
me
c
ha
ni
s
m,
s
ot
h
e
y
’
r
en
ot used with any other protocol type.
Howe
v
e
r
,
i
t
’
sa
l
s
op
os
s
i
bl
et
omov
eSSL/
TLSt
r
a
f
f
i
ct
hr
o
u
g
hmos
tt
y
pe
so
fHTTP
proxies, since SSL is frequently used to carry HTTP data. If you enable the use of an
HTTP proxy, cryptlib will also use it for SSL/TLS sessions.
Under Windows, cryptlib provides automatic proxy discovery and support. You can
enable this by setting the proxy server to Autodetect:
cryptSetAttributeString( CRYPT_UNUSED, CRYPT_OPTION_HTTP_PROXY,
"Autodetect", 10 );

which instructs cryptlib to automatically detect and use whatever proxy is being
employed. Since the proxy-discovery process can take a few seconds, you should
onl
ye
n
a
b
l
ea
u
t
o
de
t
e
c
t
i
o
ni
fy
ou
’
r
es
ur
et
h
a
tapr
ox
yi
sa
c
t
u
a
l
l
ypr
e
s
e
n
t
.Ena
b
l
i
ngi
t
unconditionally will result in cryptlib spending a lot of time trying to find a proxy that
may not exist, which slows down the network connection setup process.

Network Timeouts
When connecting to a server and carrying out other portions of a protocol such as
security parameter and session key negotiation (for which cryptlib knows that a
response must arrive within a certain time) cryptlib sets an interval timer and reports
a connect or read error if no response arrives within that time interval. This means
t
ha
ti
ft
he
r
e
’
sane
t
wor
kpr
obl
e
m such as a host being down or a network outage,
c
r
y
pt
l
i
bwon
’
th
a
ngf
or
e
v
e
rbutwi
l
lg
i
v
eupa
f
t
e
rac
e
r
t
a
i
na
mou
nto
ft
i
me
,
de
f
a
u
l
t
i
ng
to 30 seconds. You can change the connect timeout value using the CRYPT_OPTION_NET_CONNECTTIMEOUT attribute, which specifies the connect timeout
delay in seconds. For example to set a longer timeout for a remote host or client
which is slow in responding you would use:
cryptSetAttribute( CRYPT_UNUSED, CRYPT_OPTION_NET_CONNECTTIMEOUT,
60 );

128

Secure Sessions

to set a one minute timeout when activating the session. If you want to set the
connect timeout for a specific session rather than system-wide for all sessions, you
can set the attribute only for the session object in question:
cryptSetAttribute( cryptSession, CRYPT_OPTION_NET_CONNECTTIMEOUT,
60 );

In addition to the connect timeout cryptlib has a separate timeout setting for network
communications, specified using the CRYPT_OPTION_NET_READTIMEOUT and
CRYPT_OPTION_NET_WRITETIMEOUT attributes. Since cryptlib session
objects normally use non-blocking I/O once the session has been established and data
is being exchanged, the read and write timeouts are set to minimal values during any
general data exchanges that occur after the connection negotiation process has
completed. This means that all communications after that point are nearasynchronous and non-blocking, however by changing the read/write timeout settings
you can make cryptlib wait for a certain amount of time for data to arrive or be
written before returning. For example to wait up to 30 seconds for data to arrive you
would use:
cryptSetAttribute( CRYPT_UNUSED, CRYPT_OPTION_NET_READTIMEOUT, 30 );

If data arrives during the wait interval, cryptlib will return as soon as the data
be
c
ome
sa
v
a
i
l
a
bl
e
,
ot
he
r
wi
s
ei
t
’
l
lwa
i
tf
orupt
o30seconds for data to arrive.
As with the connect timeout, you can also apply these options directly to session
obj
e
c
t
s
,
whi
c
hme
a
nst
h
a
tt
he
y
’
l
lo
nl
ya
p
pl
yt
ot
ha
tpa
r
t
i
c
u
l
a
rs
e
s
s
i
onr
a
t
he
rt
h
a
n
being a system-wide setting for all session objects:
cryptSetAttribute( cryptSession, CRYPT_OPTION_NET_READTIMEOUT, 30 );

If you need the quickest possible response (usually only interactive sessions need
this), you can set network read/write timeouts of zero, which will result in cryptlib
returning immediately if no data can be read or written. The downside to using a zero
timeout is that it reduces data transfers to polled I/O, requiring repeated read or write
a
t
t
e
mpt
st
ot
r
a
ns
f
e
rda
t
a
.Forwr
i
t
et
i
me
out
si
t
’
sbe
t
t
e
rt
os
e
ta
tl
e
a
s
tas
ma
l
lno
n-zero
timeout rather than a zero timeout to ensure that the data is successfully written. In
almost all cases the write will complete immediately even with a non-zero timeout,
only in very rare cases such as when network congestion occurs will it be necessary
to wait for data to be sent. In other words during a read wait the session is frequently
j
us
ti
dl
i
ngwa
i
t
i
ngf
ors
ome
t
h
i
ngt
oha
p
pe
n,
b
utd
ur
i
ngawr
i
t
ewa
i
ti
t
’
sa
c
t
i
v
e
l
yt
r
y
i
ng
to move the data out, so setting a non-zero timeout will increase the chances of the
network layer moving the data out during the current write attempt rather than having
to retry the write later.
A second problem with very short timeouts occurs when you close a session. Since
writes are fully asynchronous, the network session can be closed before all of the data
i
swr
i
t
t
e
n.Al
t
h
oug
ht
hene
t
wor
ks
t
a
c
kt
r
i
e
st
of
l
us
ht
heda
t
at
hr
o
ug
h,
i
ft
he
r
e
’
sa
n
e
r
r
ordur
i
ngt
r
a
ns
mi
s
s
i
o
nt
h
e
r
e
’
sn
owa
yt
oi
n
di
c
a
t
et
hi
ss
i
n
c
et
hes
e
s
s
i
o
nha
sa
l
r
e
a
dy
been closed. cryptlib tries to mitigate this by setting a minimum (non-zero) network
t
i
me
o
utwhe
ni
tc
l
os
e
sas
e
s
s
i
on,
bu
tt
he
r
e
’
snowa
yt
og
ua
r
a
nt
e
et
h
a
te
v
e
r
y
t
hi
ngwi
l
l
be sent during the timeout interval (in general this is an unsolveable problem, for
example if an intermediate router crashes and is rebooted or the routing protocols
hunt around for an alternative route, the transfer will eventually complete, but it could
take several minutes for this to happen, which would require an excessively long
timeout setting).
To avoid this issue, you should avoid writing a large amount of data with a very small
network timeout setting and then immediately closing the session. You can do this by
writing data at a measured pace (with a non-zero timeout) during the session or by
setting a reasonable write timeout before you flush the last lot of data through and
close the session.

Managing your Own Network Connections and I/O
I
ns
t
e
a
dofha
v
i
ngc
r
y
pt
l
i
ba
ut
oma
t
i
c
a
l
l
yma
na
g
ene
t
wor
kc
onn
e
c
t
i
o
ns
,
i
t
’
spos
s
i
bl
e
for you to manage them yourself. This can be useful when you want to customise

Network Issues

129

session establishment and connection management, for example to handle a
STARTTLS upgrade during an SMTP or IMAP session, an STLS upgrade during a
POP session, or an AUTH TLS upgrade during an FTP session. You can also use this
facility if you want to use any high-performance I/O capabilities provided by your
system, for example asynchronous I/O or hardware-accelerated I/O in which a
dedicated subsystem manages all network transfers and posts a completion
notification to your application when the transfer is complete. This allows you to use
your own connection-management/socket-multiplexing/read-write code rather than
using the facilities provided by cryptlib.
The following discussion refers to network sockets because this is the most common
abs
t
r
a
c
t
i
ont
ha
t
’
sus
e
df
orne
t
wor
kI
/
O,howe
v
e
rc
r
y
pt
l
i
bwi
l
lwor
kwi
t
ha
nyne
t
wor
k
I/O identifier that can be represented by an integer value or handle. If your network
abstraction requires more than a straightforward handle, you can pass in a reference
or index to an array of whatever data structures your system requires to handle
network I/O.
You can handle your own network connections by adding them to a cryptlib session
as the CRYPT_SESSINFO_NETWORKSOCKET attribute before you activate the
session. Wheny
oua
c
t
i
v
a
t
et
h
es
e
s
s
i
on,
c
r
y
pt
l
i
bwi
l
lus
et
h
es
oc
k
e
tt
ha
ty
ou
’
v
e
supplied rather than opening its own connection. Once you shut down the session,
you can continue to use the socket or close it as required:
int socket;
/* Connect the network socket */
socket = ...;
/* Add the socket to the session and activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_NETWORKSOCKET,
socket );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

Before you hand the socket over to cryptlib, y
ous
ho
ul
ddi
s
a
bl
eNa
g
l
e
’
sa
l
g
or
i
t
h
m,
since cryptlib provides its own optimised packet management. cryptlib leaves this
t
a
s
kt
ot
h
ec
a
l
l
e
rt
oe
ns
ur
et
ha
ti
td
oe
s
n
’
tha
v
et
oma
k
ea
nyc
ha
ng
e
st
ot
hes
oc
k
e
t
settings itself. In other words, it will leave the socket exactly as it found it. In
a
dd
i
t
i
oni
fy
o
u’
r
er
u
nni
ngunde
rWi
nd
owsy
oune
e
dt
ous
eabl
oc
k
i
ngs
oc
k
e
tt
oa
v
oi
d
false reports of the other side closing the connection. This is due to bugs in some
versions of Winsock, cryptlib does its own timeout ha
nd
l
i
n
ga
nddo
e
s
n
’
tn
e
e
dno
nblocking sockets. Note that if you use certain Winsock functions such as
WSAAsyncSelect and WSAEventSelect on the socket, Windows will quietly
switch the socket back to non-blocking mode, so you need to be careful about
inadve
r
t
e
n
t
l
yc
ha
ng
i
ngt
hes
t
a
t
eo
fas
oc
k
e
tb
e
h
i
n
dc
r
y
pt
l
i
b
’
sba
c
k
.
In addition to managing the connection process, you can also use externally-supplied
sockets to handle network reads and writes. There are two general mechanisms used
for external network I/O, the Berkeley sockets select()-style mechanism:
select( ... );
…
read( ... );

and the posted-read/posted-write mechanism used by high-performance and
hardware-accelerated I/O subsystems:
read_async( ... );
…
wait_completion( ... );

An example of the latteri
sWi
nd
ows
’I
/
Oc
o
mp
l
e
t
i
o
np
or
t
s
,
whi
c
ha
l
l
owac
e
n
t
r
a
l
dispatcher to initiate I/Os and a pool of client threads to manage them as required
whe
ne
v
e
rar
e
qu
e
s
tc
o
mpl
e
t
e
s
.Thee
qu
i
v
a
l
e
n
tu
nde
rUni
x(
a
l
t
h
oug
hi
t
’
sl
e
s
sa
t
t
un
e
d
towards high-performance server operation, being targeted mainly at file I/O) is Posix
asynchronous I/O. Other operating systems provide similar facilities, for example
Tandem NSK has the RECV_NW and AWAITIOX calls to perform posted reads and
writes.

130

Secure Sessions

The more widely-used I/O model, using the select()-style mechanism, would
wait until data is available to be read on the socket and then call cryptPopData:
/* Wait for data to become available */
select( ... );
/* Read data from the session */
cryptPopData( cryptSession, ... );

The posted-read/posted-write mechanism would have a read or write initiated by a
central dispatcher (in the example below this is illustrated with Windows-style I/O
handling):
/* Create an I/O completion port associated with the socket */
hCompletionPort = CreateIOCompletionPort( hSocket, ... );
/* Initiate the read request */
ReadFile( hSocket, ... );

Once the read request has been completed by the underlying I/O system, a thread
f
r
o
mt
h
et
hr
e
a
dp
oo
lt
h
a
t
’
swa
i
t
i
ngont
hec
ompl
e
t
i
onpor
ti
swok
e
nupa
ndh
a
n
dl
e
s
the result:
/* Wait for data to arrive */
GetQueuedCompletionStatus( hCompletionPort, ... );
/* Read data from the session */
cryptPopData( cryptSession, ... );

The Windows kernel contains a number of special optimisations to provide the best
possible perfor
ma
nc
ef
ort
hi
st
y
peo
fI
/
O.I
fy
ou’
r
er
un
ni
ngahi
g
h-performance
server, you should consider using this style of I/O instead of the standard sockets
i
nt
e
r
f
a
c
ef
orbe
t
t
e
rpe
r
f
or
ma
n
c
e
.I
nf
a
c
tt
hi
ss
t
y
l
eofI
/
Oi
st
heo
net
ha
t
’
sus
e
dby
servers like IIS to maximise performance.
The Unix equivalent would be:
/* Initiate the read request */
aio_read( &aiocb );
/* Wait for data to arrive */
aio_suspend( &aiocb, ... );
/* Read data from the session */
cryptPopData( cryptSession, ... );

Unix asynchronous I/O is often used for high-performance I/O when the overhead of
the standard BSD select() is unacceptable. A typical select implementation, for
example, has to first copy and validate the socket descriptor masks for read, write,
and exception conditions, then c
a
l
lt
heun
de
r
l
y
i
ngde
v
i
c
e
’
spol
lr
out
i
n
ef
ore
a
c
h
socket descriptor in each mask to let the device know that an I/O operation is being
requested for that descriptor, and finally wait for a notification on any of the
descriptors from the lower-level devicedr
i
v
e
r
s
.The
r
e
’
sa
ddi
t
i
ona
lov
e
r
he
a
dc
r
e
a
t
e
d
byt
hef
a
c
tt
ha
tt
hek
e
r
ne
lc
a
n
’
ta
f
f
or
dt
ol
o
c
koutI
/
Owhi
l
ea
l
lo
ft
h
i
spo
l
l
i
ngi
s
taking place, so the select code has to be able to handle the case of I/O occurring
during the polling process, usually by restarting the poll.
Asynchronous I/O, on the other hand, avoids all of this overhead by simply posting a
read or write and then waiting for the kernel to notify it that the operation has
completed. It therefore provides much better performance than an equivalent selectbased implementation.
If you supply the network socket yourself and the socket is a server socket, you can
no longer read the CRYPT_SESSINFO_CLIENT_NAME and CRYPT_SESSINFO_CLIENT_PORT attributes, since these are recorded when the incoming client
c
on
ne
c
t
i
oni
se
s
t
a
b
l
i
s
h
e
d,
a
n
dwon’
tbepr
e
s
e
ntwi
t
haus
e
r
-supplied socket.

Creating/Destroying Encryption Contexts

131

Key Generation
The previous sections on enveloping and secure sessions mentioned the use of
encryption contexts containing public and private keys. The creation and generation
of public/private keys in encryption contexts is covered in this section. More
advanced uses of contexts such as the direct loading of key data and conventional
e
nc
r
y
pt
i
o
na
n
dha
s
h
i
nga
r
ec
ov
e
r
e
di
n“
Encryption and Decryption”onpa
g
e183.

Creating/Destroying Encryption Contexts
To create an encryption context, you must specify the user who is to own the object
or CRYPT_UNUSED for the default, normal user, and the algorithm you want to use
for that context. The available public-k
e
ya
l
g
or
i
t
h
msa
r
eg
i
v
e
ni
n“
Algorithms”o
n
page 295. For example, to create and destroy an RSA context you would use:
CRYPT_CONTEXT cryptContext;
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_RSA );
/* Load key, perform en/decryption */
cryptDestroyContext( cryptContext );

Note that the CRYPT_CONTEXT is passed to cryptCreateContext by reference, as
cryptCreateContext modifies it when it creates the encryption context. In almost all
other cryptlib routines, CRYPT_CONTEXT is passed by value. The contexts that
will be created are standard cryptlib contexts, to create a context which is handled via
a crypto device such as a smart card or Fortezza card, you should use
cryptDeviceCreateContext, which tells cryptlib to create a context in a crypto
de
v
i
c
e
.Theus
eo
fc
r
y
pt
ode
v
i
c
e
si
se
x
pl
a
i
ne
di
n“
Encryption Devices and Modules”
on page 265.

Generating a Key into an Encryption Context
Onc
ey
ou
’
v
ec
r
e
a
t
e
da
ne
nc
r
y
pt
i
onc
on
t
e
x
tt
h
ene
x
ts
t
e
pi
st
og
e
ne
r
a
t
eak
e
yi
nt
oi
t
.
Before you can generate the key you need to set the CRYPT_CTXINFO_LABEL
a
t
t
r
i
bu
t
ewhi
c
hi
sl
a
t
e
rus
e
dt
oi
de
nt
i
f
yt
hek
e
ywhe
ni
t
’
swr
i
t
t
e
nt
oorr
e
a
df
rom a
keyset or a crypto device such as a smart card or a Fortezza card using functions like
cryptAddPrivateKey and cryptGetPrivateKey. If you try to generate a key into a
context without first setting the key label, cryptlib will return CRYPT_ERROR_NOTINI
TEDt
oi
ndi
c
a
t
et
ha
tt
hel
a
be
lha
s
n’
tbe
e
ns
e
ty
e
t
.Thepr
o
c
e
s
so
fg
e
ne
r
a
t
i
ng
a public/private key pair is then:
CRYPT_CONTEXT privKeyContext;
cryptCreateContext( &privKeyContext, cryptUser, CRYPT_ALGO_RSA );
cryptSetAttributeString( privKeyContext, CRYPT_CTXINFO_LABEL, label,
labelLength );
cryptGenerateKey( privKeyContext );

To do this in Java or C# you would use:
int privKeyContext = crypt.CreateContext( cryptUser, crypt.ALGO_RSA );
crypt.SetAttributeString( privKeyContext, crypt.CTXINFO_LABEL,
label );
crypt.GenerateKey( privKeyContext );

The Visual Basic equivalent is:
Dim privKeyContext As Long
cryptCreateContext privKeyContext, cryptUser, CRYPT_ALGO_RSA
cryptSetAttributeString privKeyContext, CRYPT_CTXINFO_LABEL, label, _
Len( label )
cryptGenerateKey privKeyContext

If you want to generate a key of a particular length, you can set the CRYPT_CTXINFO_KEYSIZE attribute before calling cryptGenerateKey. For example to
generate a 1536-bit (192-byte) key you would use:

132

Key Generation

CRYPT_CONTEXT privKeyContext;
cryptCreateContext( &privKeyContext, cryptUser, CRYPT_ALGO_RSA );
cryptSetAttributeString( privKeyContext, CRYPT_CTXINFO_LABEL, label,
labelLength );
cryptSetAttribute( cryptContext, CRYPT_CTXINFO_KEYSIZE, 1536 / 8 );
cryptGenerateKey( cryptContext );

You can also change the default encryption and signature key sizes using the cryptlib
configuration options CRYPT_OPTION_PKC_KEYSIZE and CRYPT_OPTION_SI
G_KEYSI
ZEa
se
x
pl
a
i
ne
di
n“
Working with Configuration Options”o
npa
g
e274.
Onc
eak
e
yi
sg
e
ne
r
a
t
e
di
nt
oac
on
t
e
x
t
,
y
ouc
a
n’
tl
o
a
dorg
e
ne
r
a
t
eane
wk
e
yov
e
rt
he
top of it. If you try to do this, cryptlib will return CRYPT_ERROR_INITED to
indicate that a key is already loaded into the context.
Although cryptlib can work directly with public/private keys, other formats like
X.509 certificates, S/MIME messages, and SSL require complex and convoluted
na
mi
nga
ndi
de
n
t
i
f
i
c
a
t
i
o
ns
c
h
e
me
sf
ort
he
i
rk
e
y
s
.Be
c
a
us
eoft
hi
s
,
y
ouc
a
n
’
t
immediately use a newly-generated private key with these formats for anything other
than signing a certification request or a self-signed certificate. To use it for any other
purpose, you need to obtain an X.509 certificate that identifies the key and then store
the certificate alongside the private key in a cryptlib private key file or crypto device.
The process of obtaining a certificate and updating a keyset or device with it is
c
ov
e
r
e
di
nmor
ede
t
a
i
li
n“
Certificates and Certificate Management”onp
a
g
e149.
Onc
ey
ou
’
v
eob
t
a
i
ne
dt
hec
e
r
t
i
f
i
c
a
t
e
,
y
ouc
a
na
d
di
tt
ot
hek
e
y
s
e
torde
v
i
c
ei
nwh
i
c
h
the key is stored, and cryptlib will automatically associate it with the key when you
read the key.

Asynchronous Key Generation
Because the generation of larger public/private keys may take some time, cryptlib
provides an asynchronous key generation capability that allows the key to be
generated as a background task or thread on those systems that provide this
capability. You can generate a key asynchronously with cryptGenerateKeyAsync,
which works in the same way as cryptGenerateKey. You can check the status of an
asynchronous key generation with cryptAsyncQuery, which will return
CRYPT_ERROR_TIMEOUT if the key generation operation is in progress or
CRYPT_OK if the operation has completed. Any attempt to use the context while the
key generation operation is still in progress will also return CRYPT_ERROR_TIMEOUT:
cryptGenerateKeyAsync( privKeyContext );
do
{
/* Perform other task(s) */
/* ... */
}
while( cryptAsyncQuery( privKeyContext ) == CRYPT_ERROR_TIMEOUT );

You can cancel the asynchronous key generation using cryptAsyncCancel.
Since the background key generation depends on how the operating system schedules
t
hr
e
a
ds
,
y
ous
ho
ul
dn
’
tc
a
l
lcryptAsyncQuery immediately after calling
cryptGenerateKeyAsync because the thread that performs the key generation may
not have had time to run yet. The code example given above (which performs other
work before querying the key generation progress) avoids any OS thread scheduling
issues by performing another task while the OS starts the key generation thread in the
background.
In general generating a (weak) 512-bit key is instantaneous, generating a 1024 bit key
typically takes a second or two, and generating a 2048 bit key takes anywhere from
seconds to minutes depending on the algorithm type and machine speed.

Keyset Types

133

Key Storage
The most practical way of working with public and private keys is to generate them in
the context and then store them in a keyset, an abstract container that can hold one or
more keys. In practice a keyset might be a cryptlib key file, a PGP/OpenPGP key
ring, a database, an LDAP directory, or a URL accessed via HTTP. cryptlib accesses
all of these keyset types using a uniform interface that hides all of the background
details of the underlying keyset implementations. In addition you can generate and
store keys in crypto devices such as smart cards, crypto accelerators, and Fortezza
c
a
r
ds
.Cr
y
pt
ode
v
i
c
e
sa
r
ee
x
pl
a
i
ne
di
nmor
ede
t
a
i
li
n“
Encryption Devices and
Modules”o
npa
g
e265.

Keyset Types
cryptlib supports a wide variety of keyset types. Most of these are public-key
keysets, which means that you can only store X.509 certificates (and by extension the
public keys associated with them) in them, but not private keys. These keyset types
include database keysets (the cryptlib native format for storing certificates), LDAP
directories, and web pages accessed via HTTP.
In addition to the public-key keysets, cryptlib also supports the storage of private
keys in cryptlib private key files (which use the PKCS #15 crypto token format) and
crypto devices such as smart cards, Fortezza cards, and hardware crypto accelerators.
cryptlib keysets can also be used to store certificates, but only those that already have
ac
or
r
e
s
po
nd
i
ngpr
i
v
a
t
ek
e
ys
t
or
e
di
nt
hek
e
y
s
e
t
.c
r
y
pt
l
i
bp
r
i
v
a
t
ek
e
yk
e
ys
e
t
sc
a
n
’
tbe
used as general-purpose public-key or certificate stores, they can only store
certificates associated with an existing private key.
The following table summarises the different keyset types and the operations that are
pos
s
i
bl
ewi
t
he
a
c
ho
ne
.Unl
e
s
sy
ouha
v
eas
t
r
ongr
e
a
s
onn
ott
odos
o,
i
t
’
s
recommended that you use cryptlib private key files to store private keys and their
associated certificates and database keysets to store standalone certificates.
Type

Access Allowed

cryptlib

Read/write access to public/private keys and any associated
certificates stored in a file using the PKCS #15 crypto token
format, with the private key portion encrypted. This is the
cryptlib native keyset format for private keys.

Crypto
device

Read access to public/private keys and read/write access to
c
e
r
t
i
f
i
c
a
t
e
ss
t
or
e
di
nt
hede
v
i
c
e
.De
v
i
c
e
sa
r
e
n’
tg
e
ne
r
a
l
purpose keysets but can act like them for keys contained
within them. More information on crypto devices and on
g
e
ne
r
a
t
i
ngpr
i
v
a
t
ek
e
y
si
nt
he
mi
sg
i
v
e
ni
n“
Encryption
Devices and Modules”o
npa
g
e265.

Database

Read/write access to X.509 certificates stored in a database.
This is the cryptlib native keyset format for public keys and
certificates and provides a fast, scalable key storage
mechanism. The exact database format used depends on the
platform, but would typically include any ODBC database
under Windows, and Informix, Ingres, Oracle, Postgres, and
Sybase databases under other platforms.

HTTP

Read access to X.509 certificates and CRLs accessed via
URLs.

LDAP

Read/write access to X.509 certificates and CRLs stored in an
LDAP directory.

PGP

Read access to PGP/OpenPGP key rings.

The recommended method for certificate storage is to use a database keyset, which
usually outperforms the other keyset types by a large margin, is highly scalable, and

134

Key Storage

is well suited for use in cases where data is already administered through existing
database servers.

Creating/Destroying Keyset Objects
Keysets are accessed as keyset objects that work in the same general manner as the
other container objects used by cryptlib. You create a keyset object with
cryptKeysetOpen, specifying the user who is to own the device object or
CRYPT_UNUSED for the default, normal user, the type of keyset you want to attach
it to, the location of the keyset, and any special options you want to apply for the
k
e
y
s
e
t
.Thi
sope
nsac
on
ne
c
t
i
ont
ot
h
ek
e
y
s
e
t
.Onc
ey
ou’
v
ef
i
ni
s
h
e
dwi
t
ht
h
ek
e
y
s
e
t
,
you use cryptKeysetClose to sever the connection and destroy the keyset object:
CRYPT_KEYSET cryptKeyset;
cryptKeysetOpen( &cryptKeyset, cryptUser, keysetType, keysetLocation,
keysetOptions );
/* Load/store keys */
cryptKeysetClose( cryptKeyset );

The available keyset types are:
Keyset Type

Description

CRYPT_KEYSET_FILE

A flat-file keyset, either a cryptlib
private key file or a PGP/OpenPGP key ring.

CRYPT_KEYSET_HTTP

URL specifying the location of a
certificate or CRL.

CRYPT_KEYSET_LDAP

LDAP directory.

CRYPT_KEYSET_PLUGIN

Generic RDBMS accessed via the
database network plugin interface
Generic RDBMS interface.
Generic ODBC RDBMS
interface.

CRYPT_KEYSET_DATABASE
CRYPT_KEYSET_ODBC
CRYPT_KEYSET_DATABASE_STORE
CRYPT_KEYSET_PLUGIN_STORE
CRYPT_KEYSET_ODBC_STORE

As for the basic keyset types, but
representing a certificate store for
use by a CA rather than a simple
keyset. The user who creates and
updates these keyset types must
be a CA user.

These keyset types and any special conditions and restrictions on their use are
covered in more detail below.
The keyset location varies depending on the keyset type and is explained in more
detail below. Note that the CRYPT_KEYSET is passed to cryptKeysetOpen by
reference, as the function modifies it when it creates the keyset object. In all other
routines, CRYPT_KEYSET is passed by value.
The keyset options are:
Keyset Option

Description

CRYPT_KEYOPT_CREATE

Create a new keyset. This option is only valid
for writeable keyset types, which includes
keysets implemented as databases and cryptlib
key files.

CRYPT_KEYOPT_NONE No special access options (this option implies
read/write access).
CRYPT_KEYOPT_-

Read-only keyset access. This option is

Creating/Destroying Keyset Objects

Keyset Option
READONLY

135

Description
automatically enabled by cryptlib for keyset
types that have read-only restrictions enforced
by the nature of the keyset, the operating
system, or user access rights.
Unless you specifically require write access to
the keyset, you should use this option since it
allows cryptlib to optimise its buffering and
access strategies for the keyset.

These options are also covered in more detail below.

File Keysets
For cryptlib private key files and PGP/OpenPGP key rings, the keyset location is the
path to the disk file. For example to open a connection to a cryptlib key file key.p15
located in /users/dave/, you would use:
CRYPT_KEYSET cryptKeyset;
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_FILE,
"/users/dave/keys.p15", CRYPT_KEYOPT_READONLY );

cryptlib will automatically determine the file type and access it in the appropriate
manner. Since cryptlib uses the PKCS #15 crypto token format to store private keys,
the files are given a .p15 extension or an appropriate equivalent as dictated by the
operating system being used. As another example, to open a connection to a cryptlib
private key file located in the Keys share on the Windows server FileServer, you
would use:
CRYPT_KEYSET cryptKeyset;
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_FILE,
"\\FileServer\Keys\key.p15", CRYPT_KEYOPT_READONLY );

The same operation in Visual Basic is:
Dim cryptKeyset As Long
cryptKeysetOpen cryptKeyset, cryptUser, CRYPT_KEYSET_FILE, _
"\\FileServer\Keys\key.p15", CRYPT_KEYOPT_READONLY

When you open a PGP/OpenPGP keyset, cryptlib will automatically set the access
mode to read-o
nl
ye
v
e
ni
fy
o
udo
n’
ts
pe
c
i
f
yt
heCRYPT_
KEYOPT_READONLY
opt
i
o
n,
s
i
nc
ewr
i
t
e
st
ot
hi
sk
e
y
s
e
tt
y
pea
r
e
n
’
ts
u
pp
or
t
e
d.I
fy
out
r
yt
owr
i
t
eak
e
yt
o
this keyset type, cryptlib will return CRYPT_ERROR_PERMISSION to indicate that
y
oudo
n’
tha
v
ep
e
r
mi
s
s
i
o
nt
owr
i
t
et
ot
hef
i
l
e
.Theon
l
yf
i
l
ek
e
y
s
e
tt
y
pet
ha
tc
a
nbe
written to is a cryptlib private key file. This keyset contains one or more encrypted
private keys and any associated certificates. To create a new cryptlib keyset you
would use:
CRYPT_KEYSET cryptKeyset;
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_FILE,
"Private key file.p15", CRYPT_KEYOPT_CREATE );

The equivalent in Java or C# is:
int cryptKeyset = crypt.KeysetOpen( cryptUser, crypt.KEYSET_FILE,
"Private key file.p15", crypt.KEYOPT_CREATE );

If a cryptlib keyset of the given name already exists and you open it with CRYPT_KEYOPT_CREATE, cryptlib will erase it before creating a new one in its place. The
erasure process involves overwriting the original keyset with random data and
committing the write to disk to ensure that the data really is overwritten, truncating its
length to 0 bytes, resetting the file timestamp and attributes, and deleting the file to
ensure that no trace of the previous key remains. The new keyset is then created in its
place.

136

Key Storage
Fors
e
c
ur
i
t
yr
e
a
s
o
ns
,
c
r
y
pt
l
i
bwon’
twr
i
t
et
oaf
i
l
ei
fi
ti
s
n
’
tanor
ma
lf
i
l
e(
f
ore
x
a
mp
l
e
i
fi
t
’
sah
a
r
dors
y
mb
ol
i
cl
i
nk
,
i
fi
t
’
sadevice name, or if it has other unusual
properties such as having a stream fattach()’
dt
oi
t
)
.
Where the operating system supports it, cryptlib will set the security options on the
keyset so that only the person who created it (and, in some cases, the system
administrator) can access it. For example under Unix the file access bits are set to
allow only the file owner to access the file, and under Windows NT/2000/XP the
f
i
l
e
’
sa
c
c
e
s
sc
ont
r
oll
i
s
ti
ss
e
ts
ot
ha
ton
l
yt
heus
e
rwhoown
st
hef
i
l
ec
a
na
c
c
e
s
sor
change it. Since not even the system administrator can access the keyset under
Windows NT/2000/XP, you may need to manually enable access for others to allow
the file to be backed up or copied.
If your application is running as another user (for example ifi
t
’
sr
un
ni
nga
sadæmo
n
under Unix or a service under Windows), the keyset will be owned by the dæmon or
service that creates it, following standard security practice. If you want to make the
keyset accessible to standard users, you need to either change the security options to
allow the required user access (for example by changing the file access permissions
or running in the context of the intended user when you create it), or provide an
interface to your dæmon/service to allow access to the keyset. The latter is generally
the preferred option, since it allows your dæmon/service to control exactly what the
user can do with the keyset.
I
na
dd
i
t
i
oni
fy
ou
’
r
ei
ns
t
a
l
l
i
n
gorc
onf
i
g
ur
i
ngc
r
y
pt
l
i
ba
so
neus
e
rf
orus
ebya
n
ot
he
r
us
e
r
,
y
ou’
l
lne
e
dt
oa
d
j
us
tt
he access for any files that are created during the install or
configuration process to allow access by the target user. For example if you install
a
ndc
on
f
i
g
ur
ec
r
y
pt
l
i
ba
saWi
nd
owsa
d
mi
ni
s
t
r
a
t
ort
or
una
sas
y
s
t
e
ms
e
r
v
i
c
e
,
y
ou’
l
l
need to change the ownership of any key and configuration files to the system
account:
cacls filename /e /g system:f

I
fy
oudo
n
’
td
ot
h
i
st
h
e
nt
hes
e
r
v
i
c
e(
r
unni
ngunde
rt
h
es
y
s
t
e
ma
c
c
o
un
t
)c
a
n
’
ta
c
c
e
s
s
the key/configuration files created under the administrator account.
When you open a keyset that contains private keys, you should bind it to the current
thread for added security to ensure that no other threads can access the file or the keys
read from it:
CRYPT_KEYSET cryptKeyset;
/* Open a keyset and claim it for exclusive use */
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_FILE,
"Private key file.p15", CRYPT_KEYOPT_READONLY );
cryptSetAttribute( cryptKeyset, CRYPT_PROPERTY_OWNER, threadID );

Youc
a
nf
i
ndo
utmor
ea
bo
utbi
n
di
ngobj
e
c
t
st
ot
hr
e
a
dsi
n“
Object Security”o
npa
g
e
41.

HTTP Keysets
For keys accessed via an HTTP URL, the keyset name is the URL:
CRYPT_KEYSET cryptKeyset;
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_HTTP, url,
CRYPT_KEYOPT_READONLY );

HTTPk
e
y
s
e
t
snor
ma
l
l
ybe
ha
v
ej
us
tl
i
k
ea
nyot
he
rk
e
y
s
e
t
s
,
howe
v
e
ri
fy
ou
’
r
er
e
a
d
i
ng
a key from a fixed URL (with no per-key ID) you need to use the special ID [none]
to indicate that the keyset URL points directly at the certificate. For example to read
a certificate from the static URL http://www.server.com/cert.der you
would use:

Creating/Destroying Keyset Objects

137

CRYPT_KEYSET cryptKeyset;
CRYPT_HANDLE publicKey;
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_HTTP,
"http://www.server.com/cert.der", CRYPT_KEYOPT_READONLY );
cryptGetPublicKey( cryptKeyset, &cryptCertificate, CRYPT_KEYID_NAME,
"[none]" );

The CRLs provided by some CAs can become quite large, so you may need to play
with timeouts in order to allow the entire CRL to be downloaded if the link is slow or
congested.
If you want to publish certificates online, the best way to do this is with an HTTP
keyset. The server side of HTTP certificate access is handled as a standard cryptlib
s
e
s
s
i
on,
a
ndi
sc
ov
e
r
e
di
n“
Making Certificates Available Online”o
npa
g
e177.

Database Keysets
For keys (strictly speaking, X.509 certificates) that are stored in a database, the keyset
location is the access path to the database. The nature of the access path depends on
the database type, and ranges from an alias or label that identifies the database (for
example an ODBC data source) through to a complex combination of the name or
address of the server that contains the database, the name of the database on the
server, and the user name and password required to access the database.
The exact keyset type also depends on the operating system with which cryptlib is
being used. Under Windows, all database keyset types are accessed as ODBC data
sources with the keyset type CRYPT_KEYSET_ODBC. The ODBC interface is also
available for most database types under Unix through various Unix ODBC drivers.
Fort
hef
e
ws
y
s
t
e
mt
h
a
td
on
’
tpr
ov
i
deav
e
n
dor
-independent database access system,
database keysets are accessed either directly or via a generic network plugin interface
that allows cryptlib to communicate with any type of database backend. The direct
database interface, which compiles the database interface into cryptlib, has a keyset
type CRYPT_KEYSET_DATABASE. All other databases are accessed through an
RPC mechanism specified using a keyset type of CRYPT_KEYSET_PLUGIN. With
s
omes
y
s
t
e
mst
ha
tdo
n’
ts
up
p
or
ta
nyt
y
peo
fda
t
a
ba
s
ea
c
c
e
s
s(
f
ore
x
a
mp
l
es
o
me
e
mbe
d
de
ds
y
s
t
e
msha
v
enod
a
t
a
b
a
s
ec
a
pa
b
i
l
i
t
y
)
,
c
r
y
pt
l
i
bc
a
n’
tbeus
e
dwi
t
ha
database keyset and is restricted to the simpler keyset types such as cryptlib private
key files.
The simplest type of keyset to access is a local database that requires no extra
parameters such as a user name or password. An example of this is an ODBC data
source on the local machine. For example if the keyset is stored in a database such as
Ingres, MySQL, Oracle, SQL Server, Sybase, or Postgres, which is accessed through
t
he“
Pu
bl
i
c
Ke
y
s
”da
t
as
our
c
e
,
y
ouwoul
da
c
c
e
s
si
twi
t
h
:
CRYPT_KEYSET cryptKeyset;
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_ODBC,
"PublicKeys", CRYPT_KEYOPT_READONLY );

The same operation in Visual Basic is:
Dim cryptKeyset As Long
cryptKeysetOpen cryptKeyset, cryptUser, CRYPT_KEYSET_ODBC,
"PublicKeys", CRYPT_KEYOPT_READONLY

The second type of database keyset is one which is accessed through a plugin that
converts cryptlib data accesses to the format used by the database backend. The
generic plugin interface takes as parameters the name of the server that cryptlib is to
connect to and an optional port number separated by a colon. For example if the
database ran on the server keyserver.company.com, the keyset would be accessed
with:
CRYPT_KEYSET cryptKeyset;
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_PLUGIN,
"keyserver.company.com", CRYPT_KEYOPT_READONLY );

138

Key Storage

Through the use of the plugin interface, cryptlib can access any type of database
across any OS platform. Details on writing the required plugin are given in
“
Database and Networking Plugins”onpa
ge 295.
The database name parameter used above was a simple ODBC data source or
database name, but this can also contain a user name, password, and server name, in
the format user:pass@server. For example, you can specify a combination of
database user name and password as user:pass, and a user name and server as
user@server. Other, database-specific combinations and parameters may also be
pos
s
i
bl
e
,
d
e
pe
nd
i
ngont
heda
t
a
ba
s
eba
c
k
e
ndy
ou
’
r
eus
i
ng
.
In the examples shown above, the keyset was opened with the CRYPT_KEYOPT_READONLYopt
i
on.Theus
eoft
hi
so
pt
i
o
ni
sr
e
c
o
mme
nd
e
dwhe
ny
o
u’
l
lus
et
he
keyset to retrieve a certificate but not store one (which is usually the case) since it
allows cryptlib to optimise its transaction management with the database backend.
This can lead to significant performance improvements due to the different data
buffering and locking strategies that can be employed if the back-end knows that the
da
t
a
ba
s
ewo
n’
tbeup
da
t
e
d.I
fy
out
r
yt
owr
i
t
eac
e
r
t
i
ficate to a keyset that has been
opened in read-only mode, cryptlib will return CRYPT_ERROR_PERMISSION to
i
nd
i
c
a
t
et
ha
ty
o
udo
n’
tha
v
ep
e
r
mi
s
s
i
ont
owr
i
t
et
ot
h
eda
t
a
ba
s
e
.
To create a new certificate database, you can use the CRYPT_KEYOPT_CREATE
option. If a keyset of the given name already exists, cryptlib will return CRYPT_ERROR_DUPLICATE, otherwise it will create a new certificate database ready to
have certificates added to it.
Database keysets can also be used as certificate stores, an extended type of keyset
which is required in order to perform CA operations such as issuing certificates and
CRLs. In order to create this type of keyset instead of a conventional one you must
be a CA user and you need to specify its type as CRYPT_KEYSET_DATABASE_STORE, CRYPT_KEYSET_ODBC_STORE, or CRYPT_KEYSET_PLUGIN_STORE instead of the basic database keyset type. Certificate stores have a higher
overhead than normal keysets because they meet a number of special CA-specific
requirements, so you should only create one if you are using it to run a CA. In
a
dd
i
t
i
on,
c
e
r
t
i
f
i
c
a
t
e
sa
ndCRLsc
a
n’
tbedi
r
e
c
t
l
ya
d
de
dt
oorde
l
e
t
e
df
r
o
m ac
e
r
t
i
f
i
c
a
t
e
s
t
or
eb
utha
v
et
obepr
oc
e
s
s
e
dus
i
ngc
r
y
pt
l
i
b
’
sc
e
r
t
i
f
i
c
a
t
ema
na
g
e
me
n
tf
un
c
t
i
on
a
l
i
t
y
.
More information on certificate stores andt
he
i
rus
ei
sg
i
v
e
ni
n“
Managing a
Certification Authority”o
np
a
g
e171.
In order to create or open a certificate store, you must be a CA user. If you try to
a
c
c
e
s
sac
e
r
t
i
f
i
c
a
t
es
t
or
ea
n
da
r
e
n’
taCA user, cryptlib will return
CRYPT_ERROR_PARAM2t
oi
ndi
c
a
t
et
h
a
tt
heus
e
rt
y
pei
s
n’
tv
a
l
i
df
ora
c
c
e
s
s
i
ng
t
hi
st
y
p
eo
fk
e
y
s
e
t
.Nor
ma
lu
s
e
r
sc
a
n’
tup
da
t
eac
e
r
t
i
f
i
c
a
t
es
t
or
ei
na
nywa
y
,
howe
v
e
r
they can access them in read-only mode as normal database keysets. For example
while a CA could open a certificate store as:
CRYPT_KEYSET cryptKeyset;
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_PLUGIN_STORE,
"certstore.company.com", CRYPT_KEYOPT_NONE );

and perform updates on the store, a non-CA user could only access it in read-only
mode as a standard database keyset:
CRYPT_KEYSET cryptKeyset;
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_PLUGIN,
"certstore.company.com", CRYPT_KEYOPT_READONLY );

When opened in this manner the certificate store appears as a standard database
keyset rather than as a full certificate store.
To provide additional security alongside the precautions taken by cryptlib, you should
apply standard database security measures to ensure that all database keyset accesses
are carried out with least privileges. For example if your application only needs read
access to a keyset, you can use the SQL GRANT/REVOKE mechanism to allow

Creating/Destroying Keyset Objects

139

read-only access of the appropriate kind for the application. An SQL statement like
REVOKE ALL ON certificates FROM user; GRANT SELECT ON certificates TO
user would allow only read accesses to the certificate keyset. You can also use

server-s
pe
c
i
f
i
cs
e
c
ur
i
t
yme
a
s
ur
e
ss
uc
ha
sa
c
c
e
s
s
i
ngt
hek
e
y
s
e
tt
hr
oug
hSQLSe
r
v
e
r
’
s
built-in db_datareader account, which only allows read access to tables, and the
ability to run the application under a dedicated low-privilege account (a standard
feature of Unix systems).

LDAP Keysets
For keys stored in an LDAP directory, the keyset location is the name of the LDAP
server, with an optional port if access is via a non-standard port. For example if the
LDAP server was called directory.ldapserver.com, you would access the
keyset with:
CRYPT_KEYSET cryptKeyset;
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_LDAP,
"directory.ldapserver.com", CRYPT_KEYOPT_READONLY );

If the server is configured to allow access on a non-standard port, you can append the
por
tt
ot
h
es
e
r
v
e
rna
mei
nt
heus
ua
lma
nn
e
rf
orURL’
s
.Fore
x
a
mp
l
ei
ft
h
es
e
r
v
e
r
mentioned above listened on port 8389 instead of the usual 389 you would use:
CRYPT_KEYSET cryptKeyset;
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_LDAP,
"directory.ldapserver.com:8389", CRYPT_KEYOPT_READONLY );

You can also optionally include the ldap:// protocol specifier in the URL, this is
ignored by cryptlib.
The storage of certificates in LDAP directories is haphazard and vendor-dependent,
a
ndy
o
uma
yne
e
dt
oa
d
j
us
tc
r
y
pt
l
i
b’
sLDAPc
on
f
i
g
ur
a
t
i
o
nopt
i
o
nst
owor
kwi
t
ha
pa
r
t
i
c
ul
a
rv
e
ndor
’
si
d
e
ao
fh
o
wc
e
r
t
i
f
i
c
a
t
e
sa
n
dCRLss
hou
ld be stored on a server.
I
nor
de
rt
oma
k
ei
te
a
s
i
e
rt
oa
da
p
tc
r
y
pt
l
i
bt
owor
kwi
t
hdi
f
f
e
r
e
n
tv
e
nd
or
’
swa
y
sof
storing information in a directory, cryptlib provides various LDAP-related
configuration options that allow you to specify the X.500 objects and attributes used
for certificate storage. These options are:
Configuration Option

Description

CRYPT_OPTION_KEYS_LDAP_CERTNAME
CRYPT_OPTION_KEYS_LDAP_CACERTNAME

The X.500 attribute that certificates are stored
as. For some reason certificates belonging to
certification authorities (CAs) are stored
under their own attribute type, so if a search
for a certificate fails cryptlib will try again
us
i
ngt
heCAc
e
r
t
i
f
i
c
a
t
ea
t
t
r
i
b
ut
e(
t
h
e
r
e
’
sno
easy way to tell in advance how a certificate
will be stored, so it’
sne
c
e
s
s
a
r
yt
odoi
tt
hi
s
way). In addition a number of other attribute
types have been invented to hide certificates
under, it may require a bit of experimentation
t
ode
t
e
r
mi
neh
owt
hes
e
r
v
e
ryou
’
r
eus
i
ng
stores things.
The default settings for these options are
userCertificate;binary and
cACertificate;binary, a variety of other
choices also exist. Note the use of the
binary qualifier, this is required for a
number of directories that would otherwise
try and encode the returned information as
text rather than returning the raw certificate.

CRYPT_OPTION_KEYS_-

The X.500 attribute that certificate revocation
lists (CRLs) are stored as, defaulting to

140

Key Storage

Configuration Option
LDAP_CRLNAME

Description

CRYPT_OPTION_KEYS_LDAP_EMAILNAME

The X.500 attribute that email addresses are
stored as, defaulting to mail. Since X.500
never defined an email address attribute,
various groups defined their own ones, mail
is the most common one but there are a
number of other alternatives around,
including emailAddress, rfc822Name,
rfc822MailBox, and email. As usual,
some experimentation will be necessary to
find out what works.

CRYPT_OPTION_KEYS_LDAP_FILTER

The filter used to selected returned LDAP
attributes during a query, defaulting to
(objectclass=*). Experimentation will
bene
c
e
s
s
a
r
yt
ode
t
e
r
mi
n
ewh
a
t
’
sr
e
q
ui
r
e
df
or
this value.

CRYPT_OPTION_KEYS_LDAP_OBJECTCLASS

The X.500 object class, defaulting to
inetOrgPerson. Again, there is no
consistency among servers, the usual amount
of guesswork will be required to find out
what works.

CRYPT_OPTION_KEYS_LDAP_OBJECTTYPE

The object type to fetch, defaulting to
CRYPT_CERTTYPE_NONE to fetch all
object types. Setting this to CRYPT_CERTTYPE_CERTIFICATE or CRYPT_CERTTYPE_CRL will fetch only certificates
or CRLs.

certificateRevocationList;binary.

These configuration options apply to all LDAP keysets, you can also apply them to an
individual keyset object rather than as a general configuration option, which means
t
ha
tt
he
y
’
l
la
f
f
e
c
to
nl
yt
heon
eLDAPk
e
y
s
e
tobj
e
c
t
.
There is no consistency in the configuration of LDAP directories, and since the query
us
e
dt
or
e
t
r
i
e
v
eac
e
r
t
i
f
i
c
a
t
ed
e
pe
ndso
nhowt
hed
i
r
e
c
t
or
yi
sc
on
f
i
g
ur
e
d,
i
t
’
sof
t
e
n
impossible to tell what to submit without asking the directory administrators for the
correct formula. Since the actual values depend on the server configuration, there is
no way that cryptlib can determine which ones to use for a given server.
Two examples of magic formulae that are required by different CAs running LDAP
di
r
e
c
t
or
i
e
sa
r
e“
s
e
a
r
c
hDN=CN=Nor
wa
yPos
tOr
g
a
ni
z
a
t
i
ona
lCA,
O=CA, C=NO,
filter = (&(objectclass=*)(pssSubjectDNString=CN=RTV EDI-server 2, O=RTV,
C=NO)
)
,a
t
t
r
i
b
ut
e
s=c
e
r
t
i
f
i
c
a
t
e
Re
v
o
c
a
t
i
o
nLi
s
t
;
b
i
na
r
y
”a
n
d“
(
&(
|
(
&(
obj
e
c
t
c
l
a
s
s
=inetorgperson)(objectclass=organizationalperson)) (objectClass=StrongAuthenticationUser))(usercertificate;binary=*)(|(commonname=name)(rfc822mailbox=email address)
)
)
”
.I
nor
de
rt
oha
ndl
es
o
meo
ft
he
s
ec
o
mbi
na
t
i
onsy
ouwi
l
l
have to set a selection of the CRYPT_OPTION_KEYSET_LDAP_xxx attributes as
well as modifying the key ID you use when you actually read a key.
To allow even more flexibility in specifying LDAP access parameters, cryptlib will
a
l
s
oa
c
c
e
p
tRFC1
95
9LDAPURLsa
sk
e
yI
Ds(
s
e
e“
Obtaining a Key for a User”on
page 141). These have the general form ldap://host:port/dn?attributes?scope?filter, and can be used to specify arbitrarily complex
combinations of DN components (see RFC 1485), search scope, and filter (see RFC
1558). For example to specify the Norway post magic formula above as a key ID the
LDAP URL would be ldap:///CN=Norway%20Post%20Organizational%20CA,%20O=CA,%20C=NO?certificateRevocationList;binary??(&(objectclass=*)(pssSubjectDNString=%20CN=RTV%20EDI-server%202,%20O=RTV,%20C=NO)). Note

Reading a Key from a Keyset

141

that the ability to use an LDAP URL for lookup in this manner may not be available
in some LDAP client implementations.
The default settings used by cryptlib have been chosen to provide the best chance of
working, however given that everyone who stores certificates in an LDAP server
c
on
f
i
g
ur
e
si
tdi
f
f
e
r
e
nt
l
yi
t
’
sa
l
mos
tg
ua
r
a
nt
e
e
dt
h
a
tt
r
y
i
ngt
ous
eLDAPt
os
t
or
e
certificates will require reconfiguration of the client, the server, the certificates being
stored, or several of the above in order to function. In effect the LDAP configuration
acts as a form of access control mechanism that makes it impossible to access
certificates or CRLs until the CA reveals the correct magic formula. For this reason
the use of LDAP is not recommended for storing certificates.

Reading a Key from a Keyset
Onc
ey
ou
’
v
es
e
tupac
o
nne
c
t
i
ont
oak
e
y
s
e
t
,
y
ouc
a
nr
e
a
doneormor
ek
e
y
sf
r
o
mi
t
.
Some keysets such as HTTP URLs can contain only one key, whereas cryptlib private
key files, PGP/OpenPGP key rings, databases, and LDAP keysets may contain
multiple keys.
You can also use a crypto device such as a smart card, Fortezza card, or crypto
hardware accelerator as a keyset. Reading a key from a device creates an encryption
context which is handled via the crypto device, so that although it looks just like any
other encryption context it uses the device to perform any encryption or signing.
The two functions that are used to read keys are cryptGetPublicKey and
cryptGetPrivateKey, which get a public and private key respectively. The key to be
read is identified through a key identifier, either the name or the email address of the
k
e
y
’
sowne
r
,
s
pe
c
i
f
i
e
da
sCRYPT_KEYI
D_NAMEa
ndCRYPT_KEYI
D_EMAI
L,
or
t
hel
a
be
la
s
s
i
g
ne
dt
ot
hek
e
ya
st
heCRYPT_CTXI
NFO_LABELa
t
t
r
i
bu
t
ewhe
ni
t
’
s
generated or loaded into a context, also specified as CRYPT_KEYID_NAME.
cryptGetPublicKey returns a generic CRYPT_HANDLE that can be either a
CRYPT_CONTEXT or a CRYPT_CERTIFICATE depending on the keyset type.
Most public-key keysets will return an X.509 certificate, but some keysets (like
PGP/Ope
n
PGPk
e
yr
i
ng
s
)don’
ts
t
or
et
hef
ul
lc
e
r
t
i
f
i
c
a
t
ei
n
f
or
ma
t
i
ona
ndwi
l
lr
e
t
ur
n
onl
ya
ne
nc
r
y
pt
i
o
nc
o
nt
e
x
tr
a
t
he
rt
ha
nac
e
r
t
i
f
i
c
a
t
e
.Youd
o
n’
tha
v
et
owor
r
ya
bout
the difference between the two, they are interchangeable in most cryptlib functions.

Obtaining a Key for a User
The rules used to match the key ID to a key depend on the keyset type, and are as
follows:
Type

User ID Handling

Cryptlib

The key ID is a label attached to the key via the CRYPT_CTXI
NFO_LABELa
t
t
r
i
bu
t
ewhe
ni
t
’
sg
e
ne
r
a
t
ed or loaded
into the context, and is specified using CRYPT_KEYID_NAME. Alternatively, if a certificate is associated with the
key, the key ID can also be the name or email address
indicated in the certificate.

Crypto
device

The key ID is matched in full in a case-insensitive manner.
Database

The key ID is either the name or the email address of the key
owner, and is matched in full in a case-insensitive manner.

HTTP

The key ID is either the name or the email address of the key
owner, and is matched in full in a case-sensitive manner. The
one exception is when the location is specified by a static
URL, in which case the key ID has the special value [none].

LDAP

The key ID is an X.500 distinguished name (DN), which is
neither a name nor an email address but a peculiar
construction that (in theory) uniquely identifies a key in the
X.
500di
r
e
c
t
or
y
.Si
nc
eaDNi
s
n’
tr
e
a
l
l
yana
meora
ne
ma
i
l

142

Key Storage

Type

User ID Handling
a
ddr
e
s
s
,
i
t
’
sp
os
s
i
b
l
et
oma
t
c
ha
ne
nt
r
yus
i
nge
i
t
he
r
CRYPT_KEYID_NAME or CRYPT_KEYID_EMAIL.
The key ID is matched in a manner which is controlled by the
way the LDAP server is configured (usually the match is caseinsensitive).
You can also specify an LDAP URL as the key ID as
de
s
c
r
i
be
di
n“
LDAP Keysets”onpa
g
e139.

PGP

The key ID is a name with an optional email address which is
usually given inside angle brackets. Since PGP keys usually
c
o
mb
i
net
hek
e
yowne
r
’
sn
a
mea
nde
ma
i
la
ddr
e
s
si
nt
oas
i
ng
l
e
v
a
l
ue
,
i
t
’
sp
os
s
i
b
l
et
oma
t
c
ha
ne
ma
i
la
ddr
e
s
sus
i
ng
CRYPT_KEYID_NAME, and vice versa.
The key ID is matched as a substring of any of the names and
email addresses attached to the key, with the match being
performed in a case-insensitive manner. This is the same as
the matching performed by PGP.
Note that, like PGP, this will return the first key in the keyset
for which the name or email address matches the given key
ID. This may result in unexpected matches if the key ID that
y
ou’
r
eus
i
ngi
sas
ubs
t
r
i
ngofanu
mb
e
rofna
me
sore
ma
i
l
addresses that are present in the key ring. Since email
a
ddr
e
s
s
e
sa
r
emor
el
i
k
e
l
yt
ob
euni
qu
et
h
a
nn
a
me
s
,
i
t
’
sag
ood
idea to specify the email address to guarantee a correct match.

As
s
umi
ngt
ha
ty
ouwa
nt
e
dt
or
e
a
dNok
iCr
ow’
sp
ub
l
i
ck
e
yf
r
o
m ak
e
y
s
e
t
,
y
ouwoul
d
use:
CRYPT_HANDLE publicKey;
cryptGetPublicKey( cryptKeyset, &publicKey, CRYPT_KEYID_NAME,
"Noki S.Crow" );

In Java or C# this is:
int publicKey = crypt.GetPublicKey( cryptKeyset, crypt.KEYID_NAME,
"Noki S.Crow" );

In Visual Basic the operation is:
Dim publicKey As Long
cryptGetPublicKey cryptKeyset, publicKey, CRYPT_KEYID_NAME, _
"Noki S.Crow"

Note that the CRYPT_HANDLE is passed to cryptGetPublicKey by reference, as
the function modifies it when it creates the public key context. Reading a key from a
crypto device works in an identical fashion:
CRYPT_HANDLE publicKey;
cryptGetPublicKey( cryptDevice, &publicKey, CRYPT_KEYID_NAME,
"Noki S.Crow" );

The only real difference is that any encryption performed with the key is handled via
the crypto device, although cryptlib hides all of the details so that the key looks and
functions just like any other encryption context.
You can use cryptGetPublicKey not only on straight public-key keysets but also on
private key keysets, in which case it will return the public portion of the private key
or the certificate associated with the key.
The other function which is used to obtain a key is cryptGetPrivateKey, which
differs from cryptGetPublicKey in that it expects a password alongside the user ID
if the key is being read from a keyset. This is required because private keys are
usually stored encrypted and the function needs a password to decrypt the key. If the

Reading a Key from a Keyset

143

key is held in a crypto device (which requires a PIN or password when you open a
session with it, but not when you read a key), you can pass in a null pointer in place
oft
hep
a
s
s
wor
d.Fore
x
a
mp
l
ei
fNok
iCr
ow’
se
ma
i
la
ddr
e
s
swa
snoki@crow.com
a
ndy
o
uwa
nt
e
dt
or
e
a
dt
he
i
rpr
i
v
a
t
ek
e
y
,
pr
ot
e
c
t
e
dbyt
hepa
s
s
wor
d“
Pa
s
s
wor
d”
,
from a keyset, you would use:
CRYPT_CONTEXT privKeyContext;
cryptGetPrivateKey( cryptKeyset, &privKeyContext, CRYPT_KEYID_EMAIL,
"noki@crow.com", "Password" );

The same operation in Visual Basic is:
Dim privKeyContext As Long
cryptGetPrivateKey cryptKeyset, privKeyContext, CRYPT_KEYID_EMAIL, _
"noki@crow.com", "Password"

If you supply the wrong password to cryptGetPrivateKey, it will return CRYPT_ERROR_WRONGKEY. You can use this to automatically handle the case where the
k
e
ymi
g
htnotbepr
ot
e
c
t
e
dbyapa
s
s
wor
d(
f
ore
x
a
mp
l
ei
fi
t
’
ss
t
or
e
di
nac
r
y
pt
o
device or a non-cryptlib keyset t
h
a
td
oe
s
n
’
tpr
ot
e
c
tpr
i
v
a
t
ek
e
y
s
)byf
i
r
s
tt
r
y
i
ngt
he
call without a password and then retrying it with a password if the first attempt fails
with CRYPT_ERROR_WRONGKEY. cryptlib caches key reads, so the overhead of
the second key access attempt is negligible:
CRYPT_CONTEXT privKeyContext;
/* Try to read the key without a password */
if( cryptGetPrivateKey( cryptKeyset, &privKeyContext,
CRYPT_KEYID_NAME, name, NULL ) == CRYPT_ERROR_WRONGKEY )
{
/* Ask the user for the keys' password and retry the read */
password = ...;
cryptGetPrivateKey( cryptKeyset, &privKeyContext, CRYPT_KEYID_NAME,
name, password );
}

cryptGetPrivateKey always returns an encryption context.

General Keyset Queries
Where the keyset is implemented as a standard database, you can use cryptlib to
perform general queries to obtain one or more certificates that fit a given match
criterion. For example you could retrieve a list of all the keys that are set to expire
within the next fortnight (to warn their owners that they need to renew them), or that
belong to a company or a division within a company. You can also perform more
complex queries such as retrieving all certificates from a division within a company
that are set to expire within the next fortnight. cryptlib will return all certificates that
match the query you provide, finally returning CRYPT_ERROR_COMPLETE once
all matching certificates have been obtained.
The general strategy for performing queries is as follows:
submit query
repeat
read query result
while query status != CRYPT_COMPLETE

You can cancel a query in progress at any time by submitting a new query consisting
oft
hec
o
mma
n
d“
c
a
nc
e
l
”
.
Queries are submitted by setting the CRYPT_KEYINFO_QUERY attribute for a
k
e
y
s
e
t
,
whi
c
ht
e
l
l
si
th
owt
op
e
r
f
or
mt
h
equ
e
r
y
.Le
t
’
sl
o
oka
ta very simple query
which is equivalent to a straight cryptGetPublicKey:

144

Key Storage

CRYPT_CERTIFICATE certificate;
cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY,
"$email='noki@crow.com'", 22 );
do
status = cryptGetPublicKey( keyset, &certificate, CRYPT_KEYID_NONE,
NULL );
while( cryptStatusOK( status ) );

This will read each certificate corresponding to the given email address from the
database. Note that the key ID is unused because the keys that are returned are
selected by the initial query and not by the key identifier.
Thi
se
x
a
mpl
ei
sa
na
r
t
i
f
i
c
i
a
l
l
ys
i
mp
l
eo
ne
,
i
t
’
sp
os
s
i
b
l
et
os
ub
mi
tqu
e
r
i
e
so
fa
r
bi
t
r
a
r
y
complexity in the form of full SQL queries. Since the key databases that are being
queried can have arbitrary names for the certificate attributes (corresponding to
database columns), cryptlib provides a mapping from certificate attribute to database
field names. An example of this mapping is shown in the code above, in which
$email is used to specify the email address attribute, which may have a completely
different name once it reaches the database backend. The certificate attribute names
are as follows:
Attribute

Field

$C, $SP, $L, $O,
$OU, $CN

Certificate country, state or province, locality,
organisation, organisational unit, and common name.

$date

Certificate expiry date

$email

Certificate email address

You can use these attributes to build arbitrarily complex queries to retrieve particular
groups of certificates from a key database. For example to retrieve all certificates
issued for US users (obviously this is only practical with small databases) you would
use:
cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY, "$C='US'", 7 );

Extending this one stage further, you could retrieve all certificates issued to
Californian users with:
cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY, "$C='US' AND
$SP='CA'", 20 );

Going another step beyond this, you could retrieve all certificates issued to users in
San Francisco:
cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY, "$C='US' AND
$SP='CA' AND $L='San Francisco'", 43 );

Going even further than this, you could retrieve all certificates issued to users in San
Fr
a
nc
i
s
c
owhos
en
a
me
sbe
g
i
nwi
t
ha
n‘
a
’
:
cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY, "$C='US' AND
$SP='CA' AND $L='San Francisco' AND $CN LIKE 'A%'", 61 );

These queries will return the certificates in whatever order the underlying database
returns them in. You can also specify that they be returned in a given order, for
example to order the certificates in the previous query by user name you would use:
cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY, "$C='US' AND
$SP='CA' AND $L='San Francisco' ORDER BY $CN", 56 );

To return them in reverse order, you would use:
cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY, "$C='US' AND
$SP='CA' AND $L='San Francisco' ORDER BY $CN DESCENDING", 67 );

The ability to selectively extract collections of certificates provides a convenient
mechanism for implementing a hierarchical certificate database browsing capability.
You can also use it to perform general-purposes queries and certificate extractions,
for example to return all certificates that will expire within the next week (and that
therefore need to be replaced or renewed), you would use:

Reading a Key from a Keyset

145

cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY, "$date < today +
1 week", length );

To sort the results in order of urgency of replacement, you would use:
cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY, "$date < today +
1 week ORDER BY $date", length );

To retrieve all certificates that do
n’
tne
e
dr
e
p
l
a
c
e
me
ntwi
t
h
i
nt
hene
x
twe
e
k
,
y
ou
could negate the previous query to give:
cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY, "NOT $date <
today + 1 week", length );

Ast
he
s
ee
x
a
mpl
e
ss
how,
c
r
y
pt
l
i
b
’
sk
e
y
s
e
tque
r
yc
a
p
a
b
i
l
i
t
ypr
ov
i
de
st
hea
bility to
perform arbitrary general-purpose queries on keysets.
Once a query has begun running, it can return a considerable number of certificates.
If you try to initiate another query while the first one is in progress or perform a
standard read, write, or delete operation, cryptlib will return a CRYPT_ERROR_INCOMPLETE error to indicate that the query is still active. You can cancel the
currently active query at any point by setting the CRYPT_KEYINFO_QUERY
a
t
t
r
i
bu
t
et
o“
c
a
n
c
e
l
”
:
cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY, "cancel", 6 );

This will clear the current query and prepare the keyset for another query or an
alternative operation such as a key read, write, or delete.

Handling Multiple Certificates with the Same Name
Sometimes a keyset may contain multiple certificates issued to the same person.
Whe
t
h
e
rt
hi
ss
i
t
u
a
t
i
onwi
l
loc
c
urv
a
r
i
e
sbyCA,
s
omeCAswon’
ti
s
s
uemul
t
i
p
l
e
certificates with the same name, some will, and some may modify the name to
eliminate conflicts, for example by adding unique ID values to the name or using
middle initials to disambiguate names. If multiple certificates exist, you can perform
a keyset query to read each in turn and try and find one that matches your
requirements, for example you might be able to filter them based on key usage or
some other parameter held in the certificate. The general idea is to issue a query
based on the name and then read each certificate that matches the query until you find
an appropriate one:
cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY, "…", … );
while( cryptGetPublicKey( &certificate, keyset, … ) == CRYPT_OK && \
certificate doesn't match required usage )
/* Continue */;
cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY, "cancel", 6 );

This use of general queries allows the maximum flexibility in selecting certificates in
cases when multiple choices are present.

Key Group Management
Sometimes it may be desirable to treat a group of keys in the same way. For example
if a collection of servers use keys to protect their communications with each other
then compromise of one key may require the revocation of all keys in the group and
the issuance of a new group of keys. The easiest way to handle key groups is by
assigning a common identifier to all the keys in the group when you issue certificates
for them, and then replacing all keys with that identifier when it comes time to update
the key group.
The first part of the process involves assigning a key group identifier to certificates.
The easiest way to do this is to s
pe
c
i
f
yi
ta
spa
r
to
ft
h
ePKIus
e
ri
n
f
or
ma
t
i
o
nt
h
a
t
’
s
used with the CMP and SCEP protocols. For example to specify that a PKI user
belongs to the remote access users key group using the organisational unit portion of
the user DN, you would use:

146

Key Storage

/* ... */
/* Add PKI user identification information */
cryptSetAttributeString( cryptPKIUser, CRYPT_CERTINFO_COUNTRYNAME,
countryName, 2 );
cryptSetAttributeString( cryptPKIUser,
CRYPT_CERTINFO_ORGANIZATIONNAME, organizationName,
organizationNameLength );
cryptSetAttributeString( cryptPKIUser,
CRYPT_CERTINFO_ORGANIZATIONALUNITNAME, "Remote access key group",
23 );
cryptSetAttributeString( cryptPKIUser, CRYPT_CERTINFO_COMMONNAME,
commonName, commonNameLength );
/* ... */

When the user requests their certificate, the key group will be given as the
organisational unit component (alongside the other components such as the
organisation name and country) in their DN. More information on working with PKI
us
e
r
si
sg
i
v
e
ni
n“
Initialising PKI User Information”onp
a
g
e173. Alternatively, you
can manually set the key group identifier when you issue a certificate to someone in
t
hek
e
yg
r
oupi
fy
o
u’
r
ema
nu
a
l
l
yi
s
s
ui
ngc
e
r
t
i
f
i
c
a
t
e
sr
a
t
he
rt
ha
nus
i
nga
na
ut
o
ma
t
e
d
mechanism like CMP or SCEP.
The second part of the process involves identifying all of the certificates in a key
g
r
oupt
h
a
tn
e
e
dt
ober
e
v
ok
e
dorr
e
pl
a
c
e
d.Thi
si
sh
a
n
dl
e
dt
hr
o
ug
hc
r
y
pt
l
i
b
’
sk
e
y
s
e
t
query capability, retrieving each certificate in the group in turn:
CRYPT_CERTIFICATE certificate;
cryptSetAttributeString( keyset, CRYPT_KEYINFO_QUERY, "$OU='Remote
access key group'", 30 );
do
status = cryptGetPublicKey( keyset, &certificate, CRYPT_KEYID_NONE,
NULL );
while( cryptStatusOK( status ) );

Once the certificate has been fetched, you can revoke it or notify the owner that they
need to replace it as required. More information on keyset queries is given in
“
General Keyset Queries”onpa
g
e143.

Writing a Key to a Keyset
Wr
i
t
i
ngak
e
yt
oak
e
y
s
e
ti
s
n’
ta
sc
o
mp
l
e
xa
sr
e
a
di
ngi
ts
i
nc
et
he
r
e
’
sn
one
e
dt
o
specify the key identification information which is needed to read a key, however
there are some restrictions on the type of key you can write to a keyset. Public-key
keysets such as database and LDAP keysets store full certificates, so the object that
you write to these keysets must be a CRYPT_CERTIFICATE and not just a
CRYPT_CONTEXT. In contrast, keysets such as cryptlib private key files primarily
store public/private key pairs but can also store the certificate or certificates that are
associated with the private key. If you try to write the incorrect type of object to a
keyset (for example a private key to a certificate keyset), cryptlib will return a
CRYPT_ERROR_PARAM2 error to indicate that the object you are trying to add is
of the incorrect type for this keyset.
If you try to write a key to a read-only keyset, cryptlib will return CRYPT_ERROR_PERMI
SSI
ONt
oi
nd
i
c
a
t
et
ha
ty
ouc
a
n
’
twr
i
t
et
ot
hek
e
y
s
e
t
.I
fyou try to write a
c
e
r
t
i
f
i
c
a
t
et
oac
r
y
pt
l
i
bpr
i
v
a
t
ek
e
yf
i
l
eorac
r
y
pt
ode
v
i
c
et
ha
td
oe
s
n’
ta
l
r
e
a
dyha
v
ea
corresponding private key present, cryptlib will return CRYPT_ERROR_PARAM2
t
oi
ndi
c
a
t
et
h
a
ty
ouc
a
n
’
ta
ddt
hi
st
y
p
eo
fob
j
e
c
ti
ft
he
r
ei
s
n
’
ta
l
r
e
a
dy a matching
private key present. If you just want to write a certificate to a file, you can use
cryptExportCert to obtain the certificate and then write that to a file.
You can write a certificate to a public key keyset with cryptAddPublicKey, which
takes as parameters the keyset and the key certificate to write:
cryptAddPublicKey( cryptKeyset, cryptCertificate );

Si
nc
ea
l
li
de
n
t
i
f
i
c
a
t
i
o
ni
n
f
or
ma
t
i
oni
sc
on
t
a
i
ne
di
nt
hec
e
r
t
i
f
i
c
a
t
e
,
t
he
r
e
’
sn
one
e
dt
o
s
pe
c
i
f
ya
nye
x
t
r
ada
t
as
uc
ha
st
hec
e
r
t
i
f
i
c
a
t
eown
e
r
’
sname or email address.

Writing a Key to a Keyset

147

Writing a private key requires one extra parameter, the password which is used to
encrypt the private key components. cryptlib will use the default encryption method
(usually three-key triple DES) to encrypt the key with the given pa
s
s
wor
d.I
fy
ou
’
r
e
writing the private key to a crypto device, the password parameter should be set to
NULL since the device provides its own protection for the key (not all devices
support direct key loading, some require the key to be generated inside the device).
To write a private key to a keyset you would use the corresponding
cryptAddPrivateKey function:
cryptAddPrivateKey( cryptKeyset, privKeyContext, password );

If the certificate you are trying to write is already present in the keyset, cryptlib will
return CRYPT_ERROR_DUPLICATE. If the keyset is a public-key keyset, you can
use cryptDeleteKey to delete the existing certificate so you can write the new one in
its place. If the keyset is a cryptlib key file or crypto device, this would delete both
t
hec
e
r
t
i
f
i
c
a
t
ea
ndt
hek
e
yi
tc
or
r
e
s
po
ndst
o.Fi
na
l
l
y
,
c
e
r
t
i
f
i
c
a
t
es
t
or
e
sc
a
n
’
tbe
directly manipulated by adding or deleting certificates and CRLs but must be
ma
na
g
e
dus
i
ngc
r
y
pt
l
i
b
’
sc
e
r
t
i
f
i
c
a
t
ema
na
g
e
me
ntf
u
nc
t
i
o
na
l
i
t
y
.I
fy
out
r
yt
odi
r
e
c
t
l
y
insert or delete a certificate or CRL, cryptlib will return CRYPT_ERROR_PERMI
SSI
ONt
oi
nd
i
c
a
t
et
ha
tt
hi
sope
r
a
t
i
oni
s
n’
ta
l
l
owe
d.
The
r
ei
so
nei
ns
t
a
nc
ei
nwhi
c
hi
t
’
spos
s
i
bl
et
oa
ddane
wc
e
r
t
i
f
i
c
a
t
et
oac
r
y
p
t
l
i
b
pr
i
v
a
t
ek
e
yf
i
l
ewhe
nt
he
r
e
’
sa
l
r
e
a
dya
ne
x
i
s
t
i
ngc
e
r
t
i
f
i
c
a
t
epr
e
s
e
nt
,
a
ndt
ha
t
’
swhe
n
the new certificate updates the existing one. For example some CAs will re-issue a
certificate with a newer expiry date (rather than using a new key and certificate), if
you add this new certificate to the keyset cryptlib will replace the existing, older
certificate with the newer one and use the newer one in all future operations.
Youc
a
n
’
tc
r
e
a
t
eak
e
yi
ns
i
deas
t
a
n
da
r
dc
r
y
pt
l
i
bc
on
t
e
x
ta
n
dt
he
nmov
ei
tt
ot
he
device later on since the security features of the devi
c
ewon
’
ta
l
l
owt
hi
s
,
a
n
dy
ou
c
a
n
’
tt
a
k
eak
e
yc
r
e
a
t
e
dv
i
aac
r
y
pt
ode
v
i
c
ea
n
dwr
i
t
ei
tt
oak
e
y
s
e
t
,
be
c
a
us
ei
tc
a
n
’
t
bee
x
por
t
e
df
r
o
mt
h
ede
v
i
c
e
.Byus
i
ngc
r
y
pt
oha
r
dwa
r
et
oha
n
dl
ey
o
urk
e
y
sy
ou’
r
e
guaranteeing that the key is never exposed outside the hardware, keeping it safe from
any malicious code that might be present in your system.
Although cryptlib can work directly with private keys, other formats like X.509
certificates, S/MIME messages, and SSL require complex and convoluted naming
and identific
a
t
i
o
ns
c
h
e
me
sf
o
rt
he
i
rk
e
y
s
.Be
c
a
us
eo
ft
h
i
s
,
y
ouc
a
n
’
ti
mme
di
a
t
e
l
yus
e
a newly-generated private key with these formats for anything other than signing a
certification request or a self-signed certificate. To use it for any other purpose, you
need to obtain an X.509 certificate that identifies the key and then store the certificate
alongside the private key in a cryptlib private key file or crypto device. The process
of obtaining a certificate and updating a keyset or device with it is covered in more
de
t
a
i
li
n“
Certificates and Certificate Management”onp
a
g
e149.Onc
ey
ou’
v
e
obtained the certificate, you can add it to the keyset or device and cryptlib will
automatically associate it with the key when you read the key.
If you are working with a database keyset, you can also add a certificate revocation
l
i
s
t(
CRL)t
ot
hek
e
y
s
e
t
.Si
nc
eaCRLi
s
n’
ta
na
c
t
ua
lk
e
y
,
youc
a
n’
tr
e
a
di
tba
c
kout
oft
hek
e
y
s
e
t(
t
he
r
e
’
sn
ot
hi
ngt
or
e
a
d)
,
b
uty
ouc
a
nus
ei
tt
ocheck the revocation state
ofc
e
r
t
i
f
i
c
a
t
e
s
.CRLsa
ndt
he
i
rus
e
sa
r
ee
x
pl
a
i
ne
di
nmor
ed
e
t
a
i
li
n“
Certificate
Revocation using CRLs”onpa
g
e228.

Changing a Private Key Password
Changing the password on a private key file involves reading the key from a keyset
using the old password, deleting the key from the keyset, and writing the in-memory
copy back again using the new password:
read key from keyset using old password;
delete key from keyset;
re-write key to keyset using new password;

All cryptlib key file updates are atomic all-or-nothing operations, which means that if
the computer crashes between deleting the old key and writing the new one, the old

148

Key Storage

key will still be present when the machine is rebooted (specifically, all changes are
committed when the keyset is closed, which minimises the risk of losing data due to a
system crash or power outage in the middle of a long sequence of update operations).
To update a private key with a new password, you would use:
CRYPT_KEYSET cryptKeyset;
CRYPT_CONTEXT cryptKey;
/* Read the key from the keyset using the old password */
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_FILE,
keysetName, CRYPT_KEYOPT_NONE );
cryptGetPrivateKey( cryptKeyset, &cryptKey, CRYPT_KEYID_NAME, label,
oldPassword );
/* Delete the current copy of the key from the keyset */
cryptDeleteKey( cryptKeyset, label );
/* Write the key back to the keyset using the new password */
cryptAddPrivateKey( cryptKeyset, cryptKey, newPassword );
cryptKeysetClose( cryptKeyset );

The same operation in Visual Basic is:
Dim cryptKeyset As Long
Dim cryptKey As Long
' Read the key from the keyset using the old password
cryptKeysetOpen cryptKeyset, cryptUser, CRYPT_KEYSET_FILE, keysetName,
CRYPT_KEYOPT_NONE
cryptGetPrivateKey cryptKeyset, cryptKey, CRYPT_KEYID_NAME, label,
oldPassword
' Delete the current copy of the key from the keyset
cryptDeleteKey cryptKeyset, label
' Write the key back to the keyset using the new password
cryptAddPrivateKey cryptKeyset, cryptKey, newPassword
cryptKeysetClose cryptKeyset

Deleting a Key
Deleting a key with cryptDeleteKey works in the same manner as reading a key,
with the key to delete being identified by a key ID in the usual manner. For example
if you wanted to del
e
t
eS.
Cr
o
w’
sk
e
yf
r
om ak
e
y
s
e
t
,
y
ouwoul
dus
e
:
cryptDeleteKey( cryptKeyset, CRYPT_KEYID_NAME, "S.Crow" );

Deleting a key from a crypto device is identical:
cryptDeleteKey( cryptDevice, CRYPT_KEYID_NAME, "S.Crow" );

In the case of an LDAP directory, this will delete the entire entry, not just the
certificate attribute or attributes for the entry. In the case of a cryptlib private key file
or crypto device, this will delete the key and any certificates that may be associated
with it. If you try to delete a key from a read-only keyset, cryptlib will return
CRYPT_ERROR_PERMI
SSI
ON.I
ft
hek
e
yy
ou’
r
et
r
y
i
ngt
ode
l
e
t
ei
s
n
’
tpr
e
s
e
nti
n
the keyset, cryptlib will return CRYPT_ERROR_NOTFOUND.

High-level vs. Low-level Certificate Operations

149

Certificates and Certificate Management
Although cryptlib can work directly with private keys, other formats like X.509
certificates, S/MIME messages, and SSL require complex and convoluted naming
a
ndi
de
nt
i
f
i
c
a
t
i
o
ns
c
h
e
me
sf
o
rt
he
i
rk
e
y
s
.Be
c
a
us
eo
ft
h
i
s
,
y
ouc
a
n
’
ti
mme
di
a
t
e
l
yus
e
a newly-generated private key with these formats for anything other than signing a
certification request or a self-signed certificate. To use it for any other purpose, you
ne
e
dt
oo
bt
a
i
na
nX.
50
9c
e
r
t
i
f
i
c
a
t
et
ha
ti
de
n
t
i
f
i
e
st
hek
e
y
.Onc
ey
ou
’
v
eob
t
a
i
ne
dt
he
certificate, you can update the keyset or device that contains the basic public/private
key data with additional certificate information. This additional information can be a
standalone certificate or a full certificate chain from a trusted root CA down to the
end user certificate. This chapter covers the details of obtaining a certificate or
certificate chain and attaching it to a private key.
The certificate management message exchange is usually carried out via HTTP or
email or through some other unspecified mechanism, however cryptlib also supports
the Certificate Management Protocol (CMP) and Simple Certificate Enrolment
Protocol (SCEP), which define a mechanism for communicating with a CA to obtain
certificates and request the revocation of existing certificates. This chapter explains
how to use CMP and SCEP to obtain a certificate or request a revocation from a CA.
I
nor
de
rt
oc
he
c
kac
e
r
t
i
f
i
c
a
t
e
’
ss
t
a
t
us
,
y
ouc
a
nus
et
her
e
a
l
-time certificate status
protocol (RTCS) to perform a certificate status check, or the online certificate status
protocol (OCSP) to perform a certificate revocation check only. The RTCS and
OCSP checking processes are also covered in this chapter.

High-level vs. Low-level Certificate Operations
As with the general cryptlib programming interface, cryptlib supports certificate
management operations at three levels:

Plug-and-play PKI
The highest level is the plug-and-play PKI level, which is the easiest one to use and
therefore the recommended one. At this level, cryptlib handles all certificate
processing and management operations for you, requiring no special knowledge of
certificate formats, protocols, or operations. Because of its simplicity and ease of use,
i
t
’
ss
t
r
ong
l
yr
e
c
omme
nde
dt
h
a
ty
ouus
et
hi
si
nt
e
r
f
a
c
ei
fa
ta
l
lp
os
s
i
b
l
e
.

Mid-level Certificate Management
The intermediate level requires some knowledge of key generation procedures and
certificate management operations. This level involves the use of CMP and SCEP to
obtain certificates and manage a CA, and RTCS and OCSP for certificate status
checking. Most of the details of certificate management are taken care of for you by
c
r
y
pt
l
i
b,
bu
ty
ou’
l
ln
e
e
dt
op
e
r
f
or
ms
o
mema
n
ua
lha
n
dl
i
ngofc
e
r
t
i
f
i
c
a
t
ema
na
g
e
me
n
t
operations.

Low-level Certificate Management
The lowest level involves manually managing certificates and certificate revocations,
and requires dealing with an entire range of arcane, difficult-to-use, and largely
dysfunctional mechanisms such as Distinguished Names, X.500 directories,
certificate revocation lists, and assorted other paraphernalia. Working with
certificates at this level is extraordinarily difficult, and you should be absolutely
c
e
r
t
a
i
nt
h
a
ty
ou
’
r
epr
e
pa
r
e
df
ort
hel
a
r
g
ea
moun
to
fe
f
f
or
tt
ha
twi
l
lber
e
q
ui
r
e
dt
o
make anything work. At a minimum, you should read through and understand the
ce
r
t
i
f
i
c
a
t
et
ut
or
i
a
l
sme
nt
i
o
ne
di
n“
Recommended Reading”onp
a
g
e15 before trying
to do anything with low-level certificate operations.
I
fy
ou’
r
ea
bs
o
l
u
t
e
l
yc
e
r
t
a
i
nt
h
a
ty
oumus
twor
kwi
t
hc
e
r
t
i
f
i
c
a
t
e
sa
ta low level, and
that you understand just how much effort will be involved, you can find out more
about low-l
e
v
e
lc
e
r
t
i
f
i
c
a
t
eo
p
e
r
a
t
i
onsi
n“
Certificates in Detail”onpa
g
e203 and
“
Certificate Extensions”onp
a
g
e234.

150

Certificates and Certificate Management

Certificates and Keys
Once a public/private key pair is saved to a private key keyset, cryptlib allows extra
certificate information to be added to the keyset. For example the process of creating
a keyset containing a certificate and private key is:
generate public/private key pair;
write key pair to keyset;
submit certification request to CA;
receive certificate from CA;
update keyset to include certificate;

If the certificate is a self-s
i
g
ne
dCAc
e
r
t
i
f
i
c
a
t
e
,
t
he
r
e
’
snone
e
dt
oo
bt
a
i
nt
he
certificate from an external CA and you can add it directly to the keyset after you
create it. If the key pair is being generated in a crypto device such as a smart card or
Fortezza card, this process is:
generate public/private key pair;
submit certification request to CA;
receive certificate from CA;
update device to include certificate;

This example assumes that the certificate is immediately available from a CA, which
is not always the case. The full range of possibilities are covered in more detail
further on.
Onc
ey
ou
’
v
eup
da
t
e
dt
hepr
i
v
a
t
ek
e
ywi
t
hac
e
r
t
i
f
i
c
a
t
e(
whi
c
hi
st
h
eon
l
yt
i
mey
ou
can write a public key certificate to a private key keyset), cryptlib will automatically
associate the certificate with the private key so that when you read it with
cryptGetPrivateKey cryptlib will recreate the certificate alongside the key and
attach it to the key. You can then use the combined certificate and key to perform
operations that require the use of certificates such as certificate signing, S/MIME
email decryption and signing, and user authentication. If you update the private key
with a complete certificate chain instead of just a single certificate, cryptlib will
attach the full certificate chain to the key when you read it with
cryptGetPrivateKey.
The update process involves adding the certificate information to the keyset or
device, which updates it with the certificate object (either a certificate or a certificate
chain):
cryptAddPublicKey( cryptKeyset, cryptCertificate );

The certificate object which is being written must match a private key stored in the
k
e
y
s
e
torde
v
i
c
e
.I
fi
td
oe
s
n
’
tma
t
c
ha
ne
x
i
s
t
i
ngpr
i
v
a
t
ek
e
y,
c
r
y
pt
l
i
bwi
l
lr
e
t
ur
na
CRYPT_ERROR_PARAM2 error to indicate that the information in the certificate
obj
e
c
tbe
i
nga
dde
di
si
nc
or
r
e
c
t
.I
ft
he
r
e
’
sa
l
r
e
a
dyac
e
r
t
i
f
i
c
a
t
ef
ort
h
i
sk
e
ypr
e
s
e
nt
,
cryptlib will return a CRYPT_ERROR_DUPLICATE error to indicate that one key
c
a
n
’
th
a
v
et
wodi
f
f
e
r
e
n
tc
e
r
t
i
f
i
c
a
t
e
sa
s
s
oc
i
a
t
e
dwi
t
hi
t
.Se
e“
Writing a Key to a
Keyset”onp
a
g
e146 for more on writing keys to keysets.

Using Separate Signature and Encryption Certificates
I
t
’
sg
oods
e
c
ur
i
t
ypr
a
c
t
i
c
et
ous
edi
f
f
e
r
e
n
tk
e
y
sf
ors
i
g
ni
nga
nde
nc
r
y
pt
i
o
n,
and most
digital signature laws contain some requirement that the two capabilities be
implemented with separate keys. cryptlib supports the use of two (or more) keys
belonging to a single user, the only issue to be aware of is that you should give each
key a distinct label to allow it to be selected with cryptGetPrivateKey. For example
the process of creating a keyset containing separate signature and encryption keys
wi
t
ht
hes
i
g
na
t
ur
ek
e
yl
a
be
l
l
e
d“
Mys
i
g
na
t
ur
ek
e
y
”a
ndt
hee
nc
r
y
pt
i
onk
e
yl
a
be
l
l
e
d
“
Mye
nc
r
y
pt
i
onk
e
y
”woul
db
e
:

Plug-and-play PKI

151

set key label to "Signature key";
generate public/private signature key pair;
set key label to "Encryption key";
generate public/private encryption key pair;
write key pairs to keyset;
submit certification requests to CA;
receive signature certificate from CA;
receive encryption certificate from CA;
update keyset to include certificates;

When you want to sign data, you would call cryptGetPrivateKey specifying the use
of“
Si
g
na
t
ur
ek
e
y
”
;whe
ny
ouwa
ntt
od
e
c
r
y
ptd
a
t
ay
ouwo
ul
dc
a
l
l
cryptGetPrivateKey s
pe
c
i
f
y
i
ngt
heus
eo
f“
En
c
r
y
pt
i
onk
e
y
”(
orc
r
y
pt
l
i
b’
sa
ut
o
ma
t
i
c
k
e
yma
na
g
e
me
n
twi
l
lf
i
ndi
tf
ory
oui
fy
o
u’
r
eus
i
ngi
twi
t
hac
r
y
pt
l
i
be
nv
e
l
op
e
)
.

Plug-and-play PKI
Thee
a
s
i
e
s
twa
yt
os
e
tu
pk
e
y
sa
ndc
e
r
t
i
f
i
c
a
t
e
si
st
hr
oug
hc
r
y
pt
l
i
b’
spl
ug
-and-play
PKI facility, which performs the operations described above for you. To set up keys
and certificates in this manner, cryptlib requires a private-key keyset or crypto token
such as a smart card or Fortezza card to store keys and certificates in, the URL of a
plug-and-play PKI-capable CA, and a user name and password to authorise the
issuing of the certificates. The session type for the plug-and-play PKI is CRYPT_SESSION_CMP, the same type as a standard CMP session except that cryptlib
manages everything for you. The private-key keyset or crypto token is specified as
CRYPT_SESSINFO_CMP_PRIVKEYSET, and the user name and password to
authorise the operation are provided as the CRYPT_SESSINFO_USERNAME and
CRYPT_SESSINFO_PASSWORD:
CRYPT_SESSION cryptSession;
CRYPT_KEYSET cryptKeyset;
/* Create the CMP session and private-key keyset */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_CMP );
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_FILE,
keysetName, CRYPT_KEYOPT_CREATE );
/* Add the server name/address */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER, server,
serverLength );
/* Add the username, password, and private-key keyset */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
userName, userNameLength );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_PASSWORD,
password, passwordLength );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_CMP_PRIVKEYSET,
cryptKeyset );
/* Activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, TRUE );

The same operation in Visual Basic is:
Dim cryptSession As Long
Dim cryptKeyset As Long
' Create the CMP session and private-key keyset
cryptCreateSession cryptSession, cryptUser, CRYPT_SESSION_CMP
cryptKeysetOpen cryptKeyset, cryptUser, CRYPT_KEYSET_FILE, _
keysetName, CRYPT_KEYOPT_CREATE
' Add the server name/address
cryptSetAttributeString cryptSession CRYPT_SESSINFO_SERVER, _
server, Len( server )
' Add the username, password, and private-key keyset
cryptSetAttributeString cryptSession, CRYPT_SESSINFO_USERNAME, _
userName, Len( userName )
cryptSetAttributeString cryptSession, CRYPT_SESSINFO_PASSWORD, _
password, Len( password )
cryptSetAttribute cryptSession, CRYPT_SESSINFO_CMP_PRIVKEYSET, _
cryptKeyset

152

Certificates and Certificate Management

' Activate the session
cryptSetAttribute cryptSession, CRYPT_SESSINFO_ACTIVE, 1

Once this process has been completed, the private-key keyset or crypto token that you
pr
ov
i
de
dwi
l
lc
on
t
a
i
nas
i
g
na
t
ur
ek
e
yi
de
nt
i
f
i
e
dbyt
hel
a
be
l“
Si
g
na
t
ur
ek
e
y
”
,
a
nda
n
encryption key identified by the labe
l“
Enc
r
y
pt
i
o
nk
e
y
”i
ft
hep
ubl
i
c
-key algorithm
being used is capable of encryption, along with any additional certificates and CA
certificates that are required to use the keys. Both keys will be protected using the
password that you provided to authenticate the certification process. If you want to
c
ha
ng
et
hepa
s
s
wor
df
ore
i
t
he
roft
h
ek
e
y
sy
ouc
a
ndos
oa
sde
s
c
r
i
b
e
di
n“
Changing a
Private Key Password”onpa
g
e147 before you close the keyset and commit the data
to disk. Alternatively, if you want to retain the password that you used for the
certificate issue to protect the keys and certificates, you can close the keyset
immediately after you add it to the session and cryptlib will manage it for you.
If the CA is issuing you a CA certificate of your own, the keyset or crypto token will
c
on
t
a
i
nas
i
ng
l
eCAs
i
g
ni
ngke
yi
de
n
t
i
f
i
e
dbyt
hel
a
b
e
l“
Si
g
na
t
ur
ek
e
y
”
.Si
nc
eCA
k
e
y
sc
a
n’
tb
eus
e
df
ore
nc
r
y
pt
i
onorg
e
ne
r
a
l
-purpose signing but only for signing
other certificates, only the single CA signing key is created.
In addition to returning your own certificates, the plug-and-play PKI mechanism also
performs a PKIBoot certificate bootstrap operation that downloads an initial trusted
certificate set for you to use. This trusted certificate set only contains a small number
of known-good certificates trusted by the CA that provided you with your own
c
e
r
t
i
f
i
c
a
t
e
s
,
r
a
t
he
rt
ha
nt
he1
0
0+c
e
r
t
i
f
i
c
a
t
e
st
ha
ty
ou
’
dbef
or
c
e
dt
oa
u
t
o
ma
t
i
c
a
l
l
y
trust when you use a web browser (some of these browser certificates have weak 512bit keys, or are owned by CAs that have gone out of business, or whose private keys
have been on-sold to third parties when the original owner went bankrupt, sometimes
passing through multiple owners). The PKIBoot operation allows an end user,
starting with nothing more than the user name and password used for the plug-andplay PKI operation to acquire all of the information necessary to use the PKI, without
having to manually download and install certificates, or being forced to trust a large
collection of certificates from unknown CAs.
Once the PKIBoot process has completed, the trusted certificates will be present in
me
mor
ya
ss
t
a
nda
r
dc
r
y
p
t
l
i
bt
r
us
t
e
dc
e
r
t
i
f
i
c
a
t
e
s(
s
e
e“
Certificate Trust Management”
on page 231). To commit them to permanent storage and make them available for
future cryptlib sessions, you need to save the cryptlib configuration data as explained
i
n“
Working with Trust Settings”onpa
g
e232:
cryptSetAttribute( CRYPT_UNUSED, CRYPT_OPTION_CONFIGCHANGED, FALSE );

I
fy
oudo
n
’
twa
ntt
or
e
l
yont
hePKI
Bo
ott
r
us
t
e
dc
e
r
t
i
f
i
c
a
t
e
s
,
don
’
tc
ommi
tt
he
configuration data to permanent storage a
ndt
he
y
’
l
lb
ede
l
e
t
e
df
r
o
mme
mor
yt
hene
x
t
time cryptlib is restarted.
At this point the keys are ready for use for encryption, signing, email protection,
authentication, and so on. Because of the ease of use provided by the plug-and-play
PKI facility, i
t
’
ss
t
r
o
ng
l
yr
e
c
omme
nde
dt
h
a
ty
ouus
et
h
i
si
npl
a
c
eo
fa
nyot
he
r
certificate management process, since the alternatives require significantly larger
amounts of effort in order to do more or less the same thing.

Simple Certificate Creation
The process of creating a certificate is a rather complicated task that can be somewhat
daunting when all you want to do is exchange a public key with someone. In order to
simplify the process, cryptlib provides a facility to create simplified certificates that
don
’
tr
e
quire you to go through all of the steps outlined in the following sections.
These simplified certificates are valid for any type of usage (including encryption,
signing, use in SSL servers and S/MIME, and issuing other certificates and CRLs)
and have a longe
noug
hl
i
f
e
t
i
met
ha
ty
o
udo
n
’
th
a
v
et
owo
r
r
ya
boutt
h
e
me
x
pi
r
i
ngor
be
c
omi
ngi
nv
a
l
i
dwh
i
l
ey
o
u’
r
es
t
i
l
lus
i
ngt
he
m.

Simple Certificate Creation

153

To create one of these simplified certificates, you set the CRYPT_CERTINFO_XYZZY attribute after creating the certificate object to tell cryptlib to create a
simplified certificate, add a name via the CRYPT_CERTINFO_COMMONNAME
attribute (and an email address via the CRYPT_CERTINFO_RFC822NAME
attribute if you plan to use the certificate for email purposes), and sign it. The name
is usually the name of the certificate owner, but if you want to use it with an SSL
s
e
r
v
e
rt
he
ni
t
’
st
hena
meoft
h
eSSLs
e
r
v
e
r
.Fore
x
a
mpl
et
oc
r
e
a
t
eas
i
mp
l
i
f
i
e
d
certificate for Dave Smith you would use:
CRYPT_CERTIFICATE cryptCertificate;
/* Create a simplified certificate */
cryptCreateCert( &cryptCertificate, cryptUser,
CRYPT_CERTTYPE_CERTIFICATE );
cryptSetAttribute( cryptCertificate, CRYPT_CERTINFO_XYZZY, 1 );
/* Add the public key and certificate owner name and sign the
certificate with the private key */
cryptSetAttribute( cryptCertificate,
CRYPT_CERTINFO_SUBJECTPUBLICKEYINFO, pubKeyContext );
cryptSetAttributeString( cryptCertificate, CRYPT_CERTINFO_COMMONNAME,
"Dave Smith", 10 );
cryptSignCert( cryptCertificate, cryptContext );

To create a simplified certificate for the SSL server www.sslserver.com you would
g
ot
hr
oug
ht
hes
a
mes
t
e
psb
utg
i
v
et
hes
e
r
v
e
rna
mei
ns
t
e
a
doft
heus
e
r
’
sna
me
:
/* ... */
cryptSetAttributeString( cryptCertificate, CRYPT_CERTINFO_COMMONNAME,
"www.sslserver.com", 17 );
/* ... */

Finally, if you wanted to use the certificate for email purposes you also need to add
t
hec
e
r
t
i
f
i
c
a
t
eowne
r
’
se
ma
i
la
ddr
e
s
s
:
/* ... */
cryptSetAttributeString( cryptCertificate, CRYPT_CERTINFO_RFC822NAME,
"dave@smith.com", 14 );
/* ... */

The same operation in Java or C# is:
/* Create a simplified certificate */
int cryptCertificate = crypt.CreateCert( cryptUser,
crypt.CERTTYPE_CERTIFICATE );
crypt.SetAttribute( cryptCertificate, crypt.CERTINFO_XYZZY, 1 );
/* Add the public key and certificate owner name and sign the
certificate with the private key */
crypt.SetAttribute( cryptCertificate,
crypt.CERTINFO_SUBJECTPUBLICKEYINFO, pubKeyContext );
crypt.SetAttributeString( cryptCertificate, crypt.CERTINFO_COMMONNAME,
"Dave Smith" );
crypt.SignCert( cryptCertificate, cryptContext );

The Visual Basic version is:
Dim cryptCertificate As Long
' Create a simplified certificate
cryptCreateCert cryptCertificate, cryptUser,
CRYPT_CERTTYPE_CERTIFICATE
cryptSetAttribute cryptCertificate, CRYPT_CERTINFO_XYZZY, 1
' Add the public key and certificate owner name and
' sign the certificate with the private key
cryptSetAttribute cryptCertificate,
CRYPT_CERTINFO_SUBJECTPUBLICKEYINFO, _ pubKeyContext
cryptSetAttributeString cryptCertificate, CRYPT_CERTINFO_COMMONNAME, _
"Dave Smith", 10
cryptSignCert cryptCertificate, cryptContext

Since these certificates can be used for any purpose and (effectively) never expire,
you can use them without having to worry about certificate requests, communicating
with (and paying money to) a CA, proof of possession protocols, X.500 distinguished

154

Certificates and Certificate Management

names, key usages, certificate extensions, and all the other paraphernalia that comes
with X.509 certificates.
In order to distinguish these simplified certificates from normal certificates, cryptlib
indicates that they were issued under a simplified-certificate policy using the
c
e
r
t
i
f
i
c
a
t
e
Pol
i
c
i
e
sa
t
t
r
i
but
e
,
whi
c
hi
sde
s
c
r
i
be
di
nmor
ede
t
a
i
li
n“
Certificate Policies,
Policy Mappings, and Policy Constraints”o
npa
g
e239.

The Certification Process
Creating a private key and an associated certificate involves two separate processes:
generating the public/private key pair, and obtaining a certificate for the public key
which is then attached to the public/private key. The key generation process is:
generate public/private key pair;
write key pair to keyset;

For a crypto device such as a smart card or Fortezza card, the key is generated inside
the device, so this step simplifies to:
generate public/private key pair;

Theg
e
ne
r
a
t
e
dk
e
yi
sa
l
r
e
a
dys
t
or
e
di
ns
i
det
hede
v
i
c
e
,
s
ot
h
e
r
e
’
sn
one
e
dt
oe
x
pl
i
c
i
t
l
y
write it to any storage media.
The certification process varies somewhat, a typical case has already been presented
earlier:
create certification request;
submit certification request to CA;
receive certificate from CA;
update keyset or device to include certificate;

Now that the general outline has been covered, we can look at the individual steps in
more detail. Generating a public/private key pair and saving it to a keyset is
relatively simple:
CRYPT_CONTEXT cryptContext;
CRYPT_KEYSET cryptKeyset;
/* Create an RSA public/private key context, set a label for it, and
generate a key into it */
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_RSA );
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_LABEL,
"Private key", 11 );
cryptGenerateKey( cryptContext );
/* Save the generated public/private key pair to a keyset */
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_FILE, fileName,
CRYPT_KEYOPT_CREATE );
cryptAddPrivateKey( cryptKeyset, cryptContext, password );
cryptKeysetClose( cryptKeyset );
/* Clean up */
cryptDestroyContext( cryptContext );

The same operation in Java or C# is:
/* Create an RSA public/private key context, set a label for it, and
generate a key into it */
int cryptContext = crypt.CreateContext( cryptUser, crypt.ALGO_RSA );
crypt.SetAttributeString( cryptContext, crypt.CTXINFO_LABEL, "Private
key" );
crypt.GenerateKey( cryptContext );
/* Save the generated public/private key pair to a keyset */
int cryptKeyset = crypt.KeysetOpen( cryptUser, crypt.KEYSET_FILE,
fileName, crypt.KEYOPT_CREATE );
crypt.AddPrivateKey( cryptKeyset, cryptContext, password );
crypt.KeysetClose( cryptKeyset );
/* Clean up */
crypt.DestroyContext( cryptContext );

The Visual Basic equivalent is:

The Certification Process

155

Dim cryptContext As Long
Dim cryptKeyset As Long
' Create an RSA public/private key context, set a label for it,
' and generate a key into it
cryptCreateContext cryptContext, cryptUser, CRYPT_ALGO_RSA
cryptSetAttributeString cryptContext, CRYPT_CTXINFO_LABEL, _
"Private key", 11
cryptGenerateKey cryptContext
' Save the generated public/private key pair to a keyset
cryptKeysetOpen cryptKeyset, cryptUser, CRYPT_KEYSET_FILE, filename, _
CRYPT_KEYOPT_CREATE
cryptAddPrivateKey cryptKeyset, cryptContext, password
' Clean up
cryptKeysetClose cryptKeyset
cryptDestroyContext cryptContext

The process for a crypto device is identical except that the keyset write is omitted,
since the key is already held inside the device.
In practic
ey
ou
’
dpr
ob
a
b
l
yus
ecryptGenerateKeyAsync so that the user can perform
other actions while the key is being generated, although for typical key sizes on a
modern PC the key generation is practically instantaneous. If you want to use
cryptGenerateKeyAsync,
y
ou
’
dr
u
nt
h
ek
e
yg
e
ne
r
a
t
i
o
na
ndt
hec
e
r
t
i
f
i
c
a
t
i
onr
e
q
ue
s
t
creation in parallel so that by the time the certificate details have been filled in the
key is ready for use.
At the same time that you create and save the public/private key pair, you would
create a certification request:
CRYPT_CERTIFICATE cryptCertRequest;
/* Create a certification request */
cryptCreateCert( &cryptCertRequest, cryptUser,
CRYPT_CERTTYPE_CERTREQUEST );
/* Fill in the certification request details */
/* ... */
/* Sign the request */
cryptSignCert( cryptCertRequest, cryptContext );

The equivalent in Visual Basic is:
Dim cryptCertRequest As Long
' Create a certification request
cryptCreateCert cryptCertRequest, cryptUser, _
CRYPT_CERTTYPE_CERTREQUEST
' Fill in the certification request details
'...
' Sign the request
cryptSignCert cryptCertRequest, cryptContext

The next step depends on the speed with which the certification request can be turned
i
nt
oac
e
r
t
i
f
i
c
a
t
e
.I
ft
heCA’
st
ur
na
r
ou
ndt
i
mei
sv
e
r
yqui
c
k(
f
ore
x
a
mpl
ei
fi
t
’
s
operated in-house) then you can submit the request directly to the CA to convert it
into a certificate. In this case you can keep the keyset that you wrote the key to open
and update it immediately with the certificate:
CRYPT_CERTIFICATE cryptCertificate;
/* Send the certification request to the CA and obtain the returned
certificate */
/* ... */
/* Import the certificate and check its validity */
cryptImportCert( cert, certLength, cryptUser, &cryptCertificate );
cryptCheckCert( cryptCertificate, caCertificate );

156

Certificates and Certificate Management

/* Update the still-open keyset with the certificate */
cryptAddPublicKey( cryptKeyset, cryptCertificate );
/* Clean up */
cryptKeysetClose( cryptKeyset );
cryptDestroyCert( cryptCertificate );

Again, the Visual Basic equivalent for this is:
Dim cryptCertificate As Long
' Send the certification request to the CA and obtain the
' returned certificate
' ...
' Import the certificate and check its validity
cryptImportCert cert, certLength, cryptUser, cryptCertificate
cryptCheckCert cryptCertificate, caCertificate
' Update the still-open keyset with the certificate
cryptAddPublicKey cryptKeyset, cryptCertificate
' Clean up
cryptKeysetClose cryptKeyset
cryptDestroyCert cryptCertificate

Since a device acts just like a keyset for certificate updates, you can write a certificate
to a device in the same manner.
If, as will usually be the case, the certification turnaround time is somewhat longer,
you will need to wait awhile to receive the certificate back from the CA. Once the
certificate arrives from the CA, you update the keyset as before:
CRYPT_CERTIFICATE cryptCertificate;
CRYPT_KEYSET cryptKeyset;
/* Obtain the returned certificate from the CA */
/* ... */
/* Import the certificate and check its validity */
cryptImportCert( cert, certLength, cryptUser, &cryptCertificate );
cryptCheckCert( cryptCertificate, caCertificate );
/* Open the keyset for update and add the certificate */
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_FILE, fileName,
CRYPT_KEYOPT_NONE );
cryptAddPublicKey( cryptKeyset, cryptCertificate );
cryptKeysetClose( cryptKeyset );
/* Clean up */
cryptDestroyCert( cryptCertificate );

The Visual Basic equivalent is:
Dim cryptCertificate As Long
Dim cryptKeyset As Long
' Obtain the returned certificate from the CA
' ...
' Import the certificate and check its validity
cryptImportCert cert, certLength, cryptUser, cryptCertificate
cryptCheckCert cryptCertificate, caCertificate
' Open the keyset for update and add the certificate
cryptKeysetOpen cryptKeyset, cryptUser, CRYPT_KEYSET_FILE, fileName, _
CRYPT_KEYOPT_NONE
cryptAddPublicKey cryptKeyset, cryptCertificate
cryptKeysetClose cryptKeyset
' Clean up
cryptDestroyCert cryptCertificate

Again, device updates work in the same manner.
A final case involves self-signed certificates that are typically CA root certificates.
Since self-signed CA certificates can be created on the spot, you can immediately

Obtaining Certificates using CMP

157

update the still-open keyset with the self-signed certificate without any need to go
through the usual certification process. When you create a CA certificate you need to
set the CRYPT_CERTINFO_CA attribute to true (any nonzero value) to indicate that
the certificate (and by extension the private key associated with it) is a CA certificate.
I
fy
oudo
n
’
td
ot
h
i
sa
n
dt
h
e
nt
r
yt
os
i
g
n a certificate using the key, cryptlib will return
CRYPT_ERROR_I
NVALI
Dt
oi
ndi
c
a
t
et
h
a
tt
hek
e
yc
a
n’
ts
i
g
nc
e
r
t
i
f
i
c
a
t
e
sbe
c
a
us
ei
t
i
s
n’
taCAk
e
y
.Toc
r
e
a
t
eas
e
l
f
-signed CA certificate you would do the following:
CRYPT_CERTIFICATE cryptCertificate;
/* Create a self-signed CA certificate */
cryptCreateCert( &cryptCertificate, cryptUser,
CRYPT_CERTTYPE_CERTIFICATE );
cryptSetAttribute( cryptCertificate, CRYPT_CERTINFO_SELFSIGNED, 1 );
cryptSetAttribute( cryptCertificate, CRYPT_CERTINFO_CA, 1 );
/* ... */
/* Sign the certificate with the private key and update the still-open
keyset with it*/
cryptSignCert( cryptCertificate, cryptContext );
cryptAddPublicKey( cryptKeyset, cryptCertificate );
/* Clean up */
cryptKeysetClose( cryptKeyset );
cryptDestroyCert( cryptCertificate );

When you sign a certificate for which the CRYPT_CERTINFO_CA attribute has
been set, cryptlib will enable the key usages CRYPT_KEYUSAGE_KEYCERTSIGN
and CRYPT_KEYUSAGE_CRLSIGN to indicate that the key can be used to sign
certificates and CRLs. Since this is a CA key it will by default only be usable for
these purposes and not for any other purpose such as encryption or general-purpose
signing. You can override this by setting the key usage yourself, however CA keys
s
hou
l
d
n’
tr
e
a
l
l
ybeused for a purpose other than one or both of certificate and/or
CRL signing.

Obtaining Certificates using CMP
The discussion so far has covered the means of communicating with the CA in very
general terms. Typically the message exchange is carried out via HTTP or email or
through some other, unspecified mechanism. In addition to these very flexible
communications options, cryptlib also supports the Certificate Mismanagement
Protocol (CMP), which defines a mechanism for communicating with a CA to obtain
certificates and request the revocation of existing certificates. CMP makes use of
s
e
s
s
i
onob
j
e
c
t
sa
sde
s
c
r
i
be
di
n“
Secure Sessions”onp
a
g
e105, the following
de
s
c
r
i
pt
i
ona
s
s
u
me
st
h
a
ty
ou
’
r
ef
a
mi
l
i
a
rwi
t
hthe operation and use of cryptlib session
objects.
The general process involved in a CMP session is a two-step one of which the first
step is creating the appropriate request, for example a request for a new, updated, or
additional certificate or a revocation of an existing certificate, and the second step is
submitting it to a CA for processing. The result of the processing (typically a signed
certificate) is returned at the end of the session:
create a CMP request;
fill in the request details;
sign the request;
create a CMP session;
add the CMP server address and request type;
add user name and password or signature key;
add the issuing CA's certificate;
add the CMP request;
activate the CMP session;
obtain the result from the CMP session;
destroy the CMP session;

The process involved in creating a request for use in CMP is mostly identical to
creating a normal certification request (although the formats are incompatible cryptlib
hides the details so the programming interface is identical) and is covered below.

158

Certificates and Certificate Management

cryptlib also implements a full CMP server that allows you to issue certificates using
CMP.Th
i
spr
oc
e
s
si
sde
s
c
r
i
b
e
di
n“
Managing a CA using CMP or SCEP”onp
a
g
e
176.

CMP Certificate Requests
CMP uses a generic certificate request object to handle requests for new certificates
and certificate renewals and updates. The creation of a CMP certificate request of
type CRYPT_CERTTYPE_REQUEST_CERT is as follows:
CRYPT_CERTIFICATE cryptCMPRequest;
/* Create a certification request */
cryptCreateCert( &cryptCMPRequest, cryptUser,
CRYPT_CERTTYPE_REQUEST_CERT );
/* Fill in the standard certification request details */
/* ... */
/* Sign the request */
cryptSignCert( cryptCMPRequest, cryptContext );

If you’
r
er
e
que
s
t
i
ngane
wc
e
r
t
i
f
i
c
a
t
e
,
y
oug
e
ne
r
a
l
l
yon
l
yne
e
dt
opr
ov
i
d
et
hepu
bl
i
c
key to be certified. Since cryptlib will only copy across the appropriate key
c
o
mp
one
nt
s
,
t
he
r
e
’
snon
e
e
dt
oha
v
eas
e
p
a
r
a
t
ep
ub
l
i
ca
ndpr
i
v
a
t
ek
e
yc
ont
e
x
t
,
y
ou
can add the s
a
mepr
i
v
a
t
ek
e
yc
on
t
e
x
tt
h
a
ty
ou
’
l
lbeus
i
ngt
os
i
g
nt
hec
e
r
t
i
f
i
c
a
t
i
on
request to supply the CRYPT_CERTINFO_SUBJECTPUBLICKEYINFO
i
n
f
or
ma
t
i
o
na
n
dc
r
y
pt
l
i
bwi
l
lus
et
h
ea
p
pr
opr
i
a
t
eda
t
af
r
o
mi
t
.I
ft
heCAd
oe
s
n
’
t
handle the certificate identification informa
t
i
onf
ory
ou,
y
o
u’
l
la
l
s
one
e
dt
opr
ov
i
de
t
ha
t
.Thi
si
sr
a
t
h
e
rmor
ec
o
mpl
e
x
,
a
ndi
se
x
pl
a
i
ne
di
n“
Certificate Identification
Information”onp
a
g
e214.
I
fy
ou’
r
er
e
que
s
t
i
nga
nup
da
t
eofa
ne
x
i
s
t
i
ngcertificate, you can add information
from the existing certificate to the request for use in the new certificate. If you want
to renew only the public key in the existing certificate, you should add it as
CRYPT_CERTINFO_SUBJECTPUBLICKEYINFO, if you want to renew the entire
certificate you should add it as a CRYPT_CERTINFO_CERTIFICATE. For example
to renew an entire certificate you would use:
CRYPT_CERTIFICATE cryptCMPRequest;
/* Create a certification request and add the existing certificate
details */
cryptCreateCert( &cryptCMPRequest, cryptUser,
CRYPT_CERTTYPE_REQUEST_CERT );
cryptSetAttribute( cryptCMPRequest, CRYPT_CERTINFO_CERTIFICATE,
cryptCertificate );
/* Sign the request */
cryptSignCert( cryptCMPRequest, cryptContext );

When you add a CRYPT_CERTINFO_CERTIFICATE cryptlib only copies across
the public key and certificate owner DN, but not any other attributes such as key
usage information (if everything was copied across then the new certificate would be
identical to the existing one). This allows you to configure the new certificate in
whichever manner you choose, for example to set new or different options from those
present in the original certificate.
Requesting the revocation of an existing certificate is very similar to requesting a
certificate using a CMP request, the only difference being that the request type is now
CRYPT_CERTTYPE_REQUEST_REVOCATION. Creating a revocation request
involves adding the certificate to be revoked to the request and adding any extra
information such as the revocation reason that must be present in the CRL which is
issued by the CA:
CRYPT_CERTIFICATE cryptCMPRequest;
/* Create a revocation request */
cryptCreateCert( &cryptCMPRequest, cryptUser,
CRYPT_CERTTYPE_REQUEST_REVOCATION );

Obtaining Certificates using CMP

159

/* Fill in the revocation request details */
cryptSetAttribute( cryptCMPRequest CRYPT_CERTINFO_CERTIFICATE,
certToRevoke );
cryptSetAttribute( cryptCMPRequest, CRYPT_CERTINFO_CRLREASON,
revocationReason );

Not
et
h
a
tar
e
v
oc
a
t
i
onr
e
q
ue
s
ti
s
n’
ts
i
g
ne
ds
i
nc
et
hek
e
yr
e
q
ui
r
e
dt
os
i
g
ni
tmay not be
available any more (loss of the corresponding private key is one of the reasons for
revoking a certificate). Once the revocation request has been completed you can
submit it to the CA as usual.

CMP Operation Types
The CMP protocol provides for a confusing variety of certificate issue operations
with in some cases no clear distinction as to which request type is appropriate for
which situation. Because of this, cryptlib will always generate the most generic
request type possible, as with other certificate operations it may be necessary to
experiment with request types in order to determine the type which is being expected
by a CA (some CAs may behave differently for different request types even if the
request data is otherwise identical). Since the same uncertainty over which CMP
r
e
que
s
tt
y
pet
ous
ee
x
i
s
t
sa
mo
ngCAs
,
i
t
’
squ
i
t
el
i
k
e
l
yt
ha
tt
heCAsy
ou’
l
lb
e
interacting with will also accept a variety of requests for a particular situation, so that
the generic type generated by cryptlib should work in most cases.
The different CMP certificate request operations are:
Operation

Description

CRYPT_REQUESTTYPE_- Initial request to a CA, protected by a user
INITIALISATION
name and password supplied by the CA.
CRYPT_REQUESTTYPE_CERTIFICATE
CRYPT_REQUESTTYPE_KEYUPDATE

Subsequent requests to the CA, protected by
a signature created with an existing CAcertified key. The message contents for these
two request types are identical, the only
difference is that one is called a certificate
request and the other a key update request.

CRYPT_REQUESTTYPE_- Request for revocation of an existing
REVOCATION
certificate, protected either by a password
supplied by the CA or by a signature created
with an existing CA certified key.
When you submit a CMP request, you need to specify the request type before you
a
c
t
i
v
a
t
et
h
es
e
s
s
i
o
n.I
fi
t
’
sa
ni
ni
t
i
a
l
i
s
a
t
i
o
nor(
f
ors
o
meCAs
)r
e
v
oc
a
t
i
onr
e
q
ue
s
tt
he
session is authenticated using a user name and password that was previously obtained
f
r
o
mt
h
eCA.I
fi
t
’
sac
e
r
t
i
f
i
c
a
t
eork
e
y update or (for some CAs) revocation request,
the session is authenticated using a signature created with a key that was previously
certified by the CA.
Note that some CAs will treat the password which is used during the initialisation
stage as a one-time password, so that all subsequent requests have to be signed
certificate or key update requests. In addition some CAs require the DN used in
subsequent certificates to be the same as the one used in the initialisation request
whi
l
eo
t
h
e
r
sdon
’
t
,
s
omeCAsallow a user-specified DN while others require the use
of a fixed DN or set it themselves (overriding the user-supplied value), and some CAs
require revocation requests to be protected by a signature rather than a password,
which means that if no signature certificate is available (for example you want to
r
e
v
ok
eac
e
r
t
i
f
i
c
a
t
ebe
c
a
us
ey
ou
’
v
el
os
tt
hepr
i
v
a
t
ek
e
y
,
ory
ouha
v
ea
ne
nc
r
y
pt
i
o
nonl
yc
e
r
t
i
f
i
c
a
t
e
)
,
t
hec
e
r
t
i
f
i
c
a
t
ec
a
n
’
tb
er
e
v
ok
e
d.CAswi
l
la
l
s
op
e
r
f
or
m CApo
l
i
c
y
specific operations during the certificate issue process, for example some CAs will
automatically revoke a certificate which is superseded by a new one via an update
request to prevent a situation in which two otherwise identical certificates exist at the
same time.

160

Certificates and Certificate Management

CMP Sessions
Once a CMP r
e
q
ue
s
th
a
sbe
e
npr
e
pa
r
e
d,
i
t
’
sr
e
a
dyf
ors
u
b
mi
s
s
i
o
nt
ot
heCA.Thi
si
s
done via a CMP session object, which manages the details of communicating with the
CA, authenticating the user, and verifying the data being exchanged. You need to
provide the CA server using the CRYPT_SESSINFO_SERVER attribute and either a
user name and password using the CRYPT_SESSINFO_USERNAME and CRYPT_SESSINFO_PASSWORD attributes (for an initialisation or revocation request) or a
private signing key using the CRYPT_SESSINFO_PRIVATEKEY attribute (for a
certificate or key update or revocation request). Finally, you need to provide the
certificate of the issuing CA and the request type and data. Once all of this is done,
you can activate the session to request the certificate or revocation.
You can submit an initialisation request and obtain an initial certificate from a CA as
follows:
CRYPT_SESSION cryptSession;
/* Create the CMP session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_CMP );
/* Add the server name/address and request type */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER, server,
serverLength );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_CMP_REQUESTTYPE,
CRYPT_REQUESTTYPE_INITIALISATION );
/* Add the username and password or private signing key. Since this
is an initialisation request, we add the user name and password */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
userName, userNameLength );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_PASSWORD,
password, passwordLength );
/* Add the certificate of the CA who is to issue the certificate or
revocation and the request itself */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_CACERTIFICATE,
cryptCACert );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_REQUEST,
cryptCmpRequest );
/* Activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, TRUE );

The same operation in Visual Basic is:
Dim cryptSession As Long
' Create the CMP session
cryptCreateSession cryptSession, cryptUser, CRYPT_SESSION_CMP
' Add the server name/address and request type
cryptSetAttributeString cryptSession CRYPT_SESSINFO_SERVER, _
server, Len( server )
cryptSetAttribute cryptSession CRYPT_SESSINFO_CMP_REQUESTTYPE, _
CRYPT_REQUESTTYPE_INITIALIZATION
' Add the username and password or private signing key. Since this
' is an initialisation request, we add the user name and password.
cryptSetAttributeString cryptSession, CRYPT_SESSINFO_USERNAME, _
userName, Len( userName )
cryptSetAttributeString cryptSession, CRYPT_SESSINFO_PASSWORD, _
password, Len( password )
' Add the certificate of the CA who is to issue the certificate or
' revocation and the request itself
cryptSetAttribute cryptSession, CRYPT_SESSINFO_CACERTIFICATE, _
cryptCACert
cryptSetAttribute cryptSession, CRYPT_SESSINFO_REQUEST, _
cryptCmpRequest
' Activate the session
cryptSetAttribute cryptSession, CRYPT_SESSINFO_ACTIVE, 1

Obtaining Certificates using CMP

161

I
ft
hes
e
r
v
e
rt
ha
ty
ou
’
r
ec
o
mmu
ni
c
a
t
i
ngwi
t
hi
sac
r
y
pt
l
i
bCMPs
e
r
v
e
r
,
t
heus
e
r
na
me
and password contain a built-in checksum mechanism which is used by cryptlib to
check for data entry errors. If cryptlib returns a CRYPT_ERROR_BADDATA when
you set the CRYPT_SESSINFO_USERNAME or CRYPT_SESSINFO_PASSWORD attributes then the user has made a mistake when they entered the name
or password. More details on the format and error checking process used for user
na
me
sa
n
dpa
s
s
wor
dsi
sg
i
v
e
ni
n“
PKI User IDs”onpa
g
e175.
You can submit subsequent certificate or key update requests to obtain further
certificates from a CA as follows:
CRYPT_SESSION cryptSession;
/* Create the CMP session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_CMP );
/* Add the server name/address and request type */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER, server,
serverLength );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_CMP_REQUESTTYPE,
CRYPT_REQUESTTYPE_CERTIFICATE );
/* Add the username and password or private signing key. Since this
is a certification request, we add the private key */
cryptSetAttribute ( cryptSession, CRYPT_SESSINFO_PRIVATEKEY,
privateKey );
/* Add the certificate of the CA who is to issue the certificate or
revocation and the request itself */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_CACERTIFICATE,
cryptCACert );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_REQUEST,
cryptCmpRequest );
/* Activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, TRUE );

The Java or C# equivalent is:
/* Create the CMP session */
int cryptSession = crypt.CreateSession( cryptUser,
crypt.SESSION_CMP );
/* Add the server name/address and request type */
crypt.SetAttributeString( cryptSession, crypt.SESSINFO_SERVER,
server );
crypt.SetAttribute( cryptSession, crypt.SESSINFO_CMP_REQUESTTYPE,
crypt.REQUESTTYPE_CERTIFICATE );
/* Add the username and password or private signing key. Since this is
a certification request, we add the private key */
crypt.SetAttribute ( cryptSession, crypt.SESSINFO_PRIVATEKEY,
privateKey );
/* Add the certificate of the CA who is to issue the certificate or
revocation and the request itself */
crypt.SetAttribute( cryptSession, crypt.SESSINFO_CACERTIFICATE,
cryptCACert );
crypt.SetAttribute( cryptSession, crypt.SESSINFO_REQUEST,
cryptCmpRequest );
/* Activate the session */
crypt.SetAttribute( cryptSession, crypt.SESSINFO_ACTIVE, 1 );

Submitting a request for a certificate revocation works in an identical manner, with
authentication being performed using a user name and password as it is for an
initialisation request or a private key as it is for a certification request.
If the session is successfully activated the CMP object will contain the response from
the CA, typically a newly-issued certificate. Revocation requests return no data
except the status code resul
t
i
n
gf
r
om t
hea
c
t
i
v
a
t
i
o
noft
hes
e
s
s
i
on.I
fy
ou
’
r
e
requesting a certificate you can read it from the session as a CRYPT_SESSINFO_RESPONSE attribute:

162

Certificates and Certificate Management

CRYPT_CERTIFICATE cryptCertificate;
int status;
/* Activate the session */
status = cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE,
TRUE );
if( cryptStatusError( status ) )
/* Couldn't obtain certificate from CA */;
/* Get the returned certificate */
cryptGetAttribute( cryptSession, CRYPT_SESSINFO_RESPONSE,
&cryptCertificate );

Onc
ey
ou
’
v
eob
t
a
i
ne
dt
hec
e
r
t
i
f
i
c
a
t
e
,
y
ous
h
ou
l
ds
a
v
ei
twi
t
ht
hepr
i
v
a
t
ek
e
yi
t
’
s
a
s
s
oc
i
a
t
e
dwi
t
ha
sde
s
c
r
i
be
di
n“
Certificates and Keys”onpa
g
e150. Because CMP
is a complex protocol with a large number of variations and options, it can fail for a
variety of reasons. The error-ha
n
dl
i
ngt
e
c
hn
i
q
ue
sde
s
c
r
i
be
di
n“
Secure Sessions”o
n
page 105 may be useful in determining the exact nature of the problem.

Obtaining Certificates using SCEP
Obtaining a certificate using the Simple Certificate Enrolment Protocol (SCEP)
works much like it does for CMP. The general process involved in an SCEP session
is a two-step one of which the first step is creating a certification request and the
second step is submitting it to a CA for processing. The result of the processing
(typically a signed certificate) is returned at the end of the session. SCEP makes use
ofs
e
s
s
i
onobj
e
c
t
sa
sde
s
c
r
i
be
di
n“
Secure Sessions”on page 105, the following
de
s
c
r
i
pt
i
ona
s
s
u
me
st
h
a
ty
ou
’
r
ef
a
mi
l
i
a
rwi
t
ht
heo
pe
r
a
t
i
o
na
ndus
eo
fc
r
y
pt
l
i
bs
e
s
s
i
on
objects:
create a PKCS #10 request;
fill in the request details;
create an SCEP session;
add the SCEP server address;
add user name and password;
add the issuing CA's certificate;
add the PKCS #10 request;
add the private key matching the PKCS #10 request;
activate the SCEP session;
obtain the result from the SCEP session;
destroy the SCEP session;

The process involved in creating a request for use in SCEP is mostly identical to the
one for CMP, with a few differences as noted below. cryptlib also implements a full
SCEP server that allows you to issue certificates using SCEP. This process is
de
s
c
r
i
be
di
n“
Managing a CA using CMP or SCEP”onpa
g
e176.

SCEP Certificate Requests
SCEP uses a PKCS #10 certificate request object to handle requests for certificates.
The creation of a PKCS #10 certificate request of type CRYPT_CERTTYPE_CERTREQUEST is as follows:
CRYPT_CERTIFICATE cryptCertRequest;
/* Create a certification request */
cryptCreateCert( &cryptCertRequest, cryptUser,
CRYPT_CERTTYPE_CERTREQUEST );
/* Fill in the standard certification request details */
/* ... */

Not
et
h
a
t
,
u
nl
i
k
eCMPr
e
que
s
t
s
,
t
heSCEPr
e
qu
e
s
ti
s
n
’
ts
i
g
ne
d.Thi
si
sbe
c
a
us
e
cryptlib has to fill in further details in the request as part of the SCEP message
exchange process.

SCEP Sessions
Onc
eaPKCS#
10r
e
q
ue
s
tha
sbe
e
npr
e
pa
r
e
d,
i
t
’
sr
e
a
dyfor submission to the CA.
This is done via a SCEP session object, which manages the details of communicating

Obtaining Certificates using SCEP

163

with the CA, authenticating the user, and verifying the data being exchanged. You
need to specify the CA server and a user name and password using the CRYPT_SESSINFO_SERVER, CRYPT_SESSINFO_USERNAME and CRYPT_SESSINFO_PASSWORD attributes in the usual manner. In addition you need to
supply the private key that was used to create the request using the CRYPT_SESSINFO_PRIVATEKEY attribute. The private key is never sent to the server, but
is used to for signing and encryption purposes by the SCEP client. Finally, you need
to provide the certificate of the issuing CA and the request data. Once all of this is
done, you can activate the session to obtain the certificate:
CRYPT_SESSION cryptSession;
/* Create the SCEP session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_SCEP );
/* Add the server name/address */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER, server,
serverLength );
/* Add the username, password, and private key */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_USERNAME,
userName, userNameLength );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_PASSWORD,
password, passwordLength );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_PRIVATEKEY, privateKey
);
/* Add the certificate of the CA who is to issue the certificate and
the request itself */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_CACERTIFICATE,
cryptCACert );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_REQUEST, cryptRequest
);
/* Activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, TRUE );

The same operation in Visual Basic is:
Dim cryptSession As Long
' Create the SCEP session
cryptCreateSession cryptSession, cryptUser, CRYPT_SESSION_SCEP
' Add the server name/address
cryptSetAttributeString cryptSession CRYPT_SESSINFO_SERVER, _
server, Len( server )
' Add the username, password, and private key.
cryptSetAttributeString cryptSession, CRYPT_SESSINFO_USERNAME, _
userName, Len( userName )
cryptSetAttributeString cryptSession, CRYPT_SESSINFO_PASSWORD, _
password, Len( password )
cryptSetAttribute cryptSession, CRYPT_SESSINFO_PRIVATEKEY, _
privateKey
' Add the certificate of the CA who is to issue the certificate and
the request itself
cryptSetAttribute cryptSession, CRYPT_SESSINFO_CACERTIFICATE, _
cryptCACert
cryptSetAttribute cryptSession, CRYPT_SESSINFO_REQUEST, _
cryptRequest
' Activate the session
cryptSetAttribute cryptSession, CRYPT_SESSINFO_ACTIVE, 1

I
ft
hes
e
r
v
e
rt
ha
ty
ou
’
r
ec
o
mmu
ni
c
a
t
i
ngwi
t
hi
sac
r
y
pt
l
i
bSCEPs
e
r
v
e
r
,
t
heus
e
r
n
a
me
and password contain a built-in checksum mechanism which is used by cryptlib to
check for data entry errors. If cryptlib returns a CRYPT_ERROR_BADDATA when
you set the CRYPT_SESSINFO_USERNAME or CRYPT_SESSINFO_PASSWORD attributes then the user has made a mistake when they entered the name
or password. More details on the format and error checking process used for user

164

Certificates and Certificate Management
na
me
sa
n
dpa
s
s
wor
dsi
sg
i
v
e
ni
n“
Managing a CA using CMP or SCEP”o
npa
g
e
176.
Unlike CMP, SCEP only recognises a basic certification request for a new certificate,
s
ot
he
r
e
’
sn
one
e
dt
os
pe
c
i
f
yar
e
que
s
tt
y
pebe
f
or
ey
oua
c
t
i
v
a
t
et
hes
e
s
s
i
o
n.I
n
addition, SCEP can only certify keys capable of both encryption and signing, which
means that you can only certify RSA keys with no usage restrictions that would limit
them to being used only for encryption or only for signing. The returned certificate
will contain a combined key usage allowing both encryption and signing.
TheSCEPCAc
e
r
t
i
f
i
c
a
t
emus
ta
l
s
ob
ec
a
pa
b
l
eo
fe
n
c
r
y
pt
i
o
na
n
ds
i
g
ni
ng
,whi
c
hi
s
n
’
t
normally done with a CA certificate but is required by the SCEP protocol. If you add
a CA certificate orpr
i
v
a
t
ek
e
yt
ha
ti
s
n
’
tc
a
pa
bl
eo
fbo
t
he
n
c
r
y
pt
i
o
na
n
ds
i
g
ni
ng
,
cryptlib will return a CRYPT_ERROR_PARAM3 to indicate that the CA certificate
ork
e
yc
a
n’
tb
eus
e
df
orSCEP.
If the session is successfully activated the SCEP object will contain the response from
the CA, which will be a newly-issued certificate that you can read from the session as
a CRYPT_SESSINFO_RESPONSE attribute:
CRYPT_CERTIFICATE cryptCertificate;
int status;
/* Activate the session */
status = cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, TRUE
);
if( cryptStatusError( status ) )
/* Couldn't obtain certificate from CA */;
/* Get the returned certificate */
cryptGetAttribute( cryptSession, CRYPT_SESSINFO_RESPONSE,
&cryptCertificate );

Onc
ey
ou
’
v
eob
t
a
i
ne
dt
hec
e
r
t
i
f
i
c
a
t
e
,
y
ous
h
ou
l
ds
a
v
ei
twi
t
ht
hepr
i
v
a
t
ek
e
yi
t
’
s
a
s
s
oc
i
a
t
e
dwi
t
ha
sde
s
c
r
i
be
di
n“
Certificates and Keys”onpa
g
e150. Because SCEP
is a complex protocol with a large number of variations and options, it can fail for a
variety of reasons. The error-ha
n
dl
i
ngt
e
c
hn
i
q
ue
sde
s
c
r
i
be
di
n“
Secure Sessions”o
n
page 105 may be useful in determining the exact nature of the problem.

Certificate Status Checking using RTCS
In order to check the validity of a certificate, cryptlib supports the real-time certificate
status protocol (RTCS). The simplest way to use RTCS is with cryptCheckCert,
which returns a straightforward valid/not valid status and is described in the next
section. More complex RTCS usage, including obtaining detailed status information
and querying the status of multiple certificates at once is covered in the sections that
follow.

Basic RTCS Queries
The simplest way to work with RTCS is to use it with cryptCheckCert to check the
validity of a certificate. Since RTCS is an online protocol, communicating with the
responder requires the use of a cryptlib session object which is described in more
de
t
a
i
li
n“
Secure Sessions”o
npa
g
e105, the following description assumes that
y
ou’
r
ef
a
mi
l
i
a
rwi
t
ht
heope
r
a
t
i
o
na
n
dus
eo
fc
r
y
pt
l
i
bs
e
s
s
i
o
nob
j
e
c
t
s
.Es
t
a
bl
i
s
hi
nga
n
RTCS client session requires adding the RTCS responder name or IP address and an
optional port numb
e
ri
fi
ti
s
n
’
tus
i
ngt
hes
t
a
nda
r
dpor
t
.On
c
et
h
i
si
sdo
ne
,
y
ouc
a
n
check the certificate using cryptCheckCert, with the second parameter being the
RTCS responder.
CRYPT_SESSION cryptSession;
int status;
/* Create the RTCS session and add the responder name */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_RTCS );
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
serverName, serverNameLength );

Certificate Status Checking using RTCS

165

/* Check the certificate */
status = cryptCheckCert( cryptCertificate, cryptSession );
if( cryptStatusOK( status ) )
/* Certificate is OK */;
/* Clean up the session object */
cryptDestroySession( cryptSession );

Not
et
h
a
tt
heRTCSs
e
s
s
i
oni
s
n’
ta
c
t
i
v
a
t
e
di
nt
heus
ua
lma
n
ne
rbys
e
t
t
i
ngt
he
CRYPT_SESSINFO_ACTIVE attribute to true, since this is done by
cryptCheckCert when it performs the validity check.
If cryptCheckCert returns OK this means that the certificate is valid right now. If it
r
e
t
ur
nsCRYPT_ERROR_I
NVALI
D(
ors
omeot
he
re
r
r
or
)t
hec
e
r
t
i
f
i
c
a
t
ei
s
n’
tv
a
l
i
d,
either because it has expired, has been revoked, is a forged certificate, or for some
other reason. Usually all that matters is whether a certificate is OK to use or not, but
i
fy
our
e
qui
r
ede
t
a
i
l
e
di
nf
or
ma
t
i
ona
st
owhyac
e
r
t
i
f
i
c
a
t
ei
s
n’
tOKt
ous
ey
oune
e
dt
o
perform a manual RTCS check without the help of cryptCheckCert, as described
below.

Creating an RTCS Request
Performing an RTCS status check without the help of cryptCheckCert involves
creating an RTCS request object, adding a copy of the certificate to be checked to the
r
e
que
s
t
,
s
ub
mi
t
t
i
ngt
her
e
que
s
tt
ot
heRTCSr
e
s
p
on
de
ra
n
dr
e
c
e
i
v
i
ngt
her
e
s
pon
de
r
’
s
r
e
pl
y
,
a
ndf
i
n
a
l
l
yc
he
c
k
i
ngt
h
ec
e
r
t
i
f
i
c
a
t
e
’
ss
t
a
t
usi
nt
h
eRTCSr
e
pl
y
:
create RTCS request;
add certificate to be checked to request;
exchange data with RTCS responder;
check certificate using RTCS response;

An RTCS request is a standard certificate object of type CRYPT_CERTTYPE_RTCS_REQUEST. You create this in the usual manner and add the certificate as a
CRYPT_CERTINFO_CERTIFICATE attribute. Since RTCS queries don’
tha
v
et
o
bes
i
g
ne
d,
t
he
r
e
’
sn
one
e
dt
ope
r
f
or
ma
nyf
ur
t
he
ro
pe
r
a
t
i
o
n
sont
h
er
e
qu
e
s
to
bj
e
c
t
,
a
ndi
t
’
sr
e
a
dyf
ors
u
b
mi
s
s
i
ont
ot
her
e
s
po
nd
e
r
:
CRYPT_CERTIFICATE cryptRTCSRequest;
/* Create the RTCS request */
cryptCreateCert( &cryptRTCSRequest, cryptUser,
CRYPT_CERTTYPE_RTCS_REQUEST );
/* Add the certificate to be queried to the request */
cryptSetAttribute( cryptRTCSRequest, CRYPT_CERTINFO_CERTIFICATE,
cryptCertificate );

Some
t
i
me
saus
e
r
’
sc
e
r
t
i
f
i
c
a
t
ewi
l
lc
o
nt
a
i
nt
hei
nf
or
ma
t
i
onr
e
qu
i
r
e
df
orc
r
y
pt
l
i
bt
o
communicate with the responder, but often this is missing or incorrect. You can
check for the presence of RTCS information in the certificate by checking for the
existence of the CRYPT_CERTINFO_AUTHORITYINFO_RTCS attribute, which
contains information about the RTCS responder, usually in the form of a URL. If you
want to read the location of the responder, you can obtain it by reading the
CRYPT_CERTINFO_UNIFORMRESOURCEIDENTIFIER attribute from within
the RTCS information. Since the RTCS attribute is a composite GeneralName field,
you need to first select it and then read the URL from within the GeneralName:
char url[ CRYPT_MAX_TEXTSIZE + 1 ];
int urlLength;
cryptSetAttribute( cryptCertificate,
CRYPT_CERTINFO_AUTHORITYINFO_RTCS, CRYPT_UNUSED );
cryptGetAttributeString( cryptCertificate,
CRYPT_CERTINFO_UNIFORMRESOURCEIDENTIFIER, url, &urlLength );
url[ urlLength ] = '\0';

I
ft
heRTCSr
e
s
po
nde
rl
oc
a
t
i
oni
s
n’
tpr
e
s
e
ntori
si
nc
or
r
e
c
t
,
y
ou’
l
lne
e
dt
oa
ddt
he
responder URL manually before you can submit the request, as explained in the next
section.

166

Certificates and Certificate Management

Communicating with an RTCS Responder
Since RTCS is an online protocol, communicating with the responder requires the use
ofac
r
y
pt
l
i
bs
e
s
s
i
o
no
bj
e
c
twhi
c
hi
sde
s
c
r
i
be
di
nmor
ede
t
a
i
li
n“
Secure Sessions”on
page 105,
t
hef
o
l
l
owi
ngde
s
c
r
i
pt
i
o
na
s
s
u
me
st
ha
ty
o
u’
r
ef
a
mi
l
i
a
rwi
t
ht
h
eop
e
r
a
t
i
on
and use of cryptlib session objects. If the name of the RTCS responder is specified in
the certificate which is being checked you can directly submit the request to an RTCS
session object as a CRYPT_SESSINFO_REQUEST attribute without requiring any
f
ur
t
he
rs
e
t
upo
ft
hes
e
s
s
i
ono
b
j
e
c
t
.I
ft
her
e
s
po
nd
e
ri
s
n
’
ts
p
e
c
i
f
i
e
di
nt
hec
e
r
t
i
f
i
c
a
t
e
,
y
ou’
l
lha
v
et
os
pe
c
i
f
yi
ty
our
s
e
l
fa
sde
s
c
ribed further on. In either case cryptlib will
contact the responder, submit the status query, and obtain the response from the
responder. If the query was successful, the session object will contain the RTCS
response object in the form of a CRYPT_SESSINFO_RESPONSE that contains the
reply from the server:
CRYPT_SESSION cryptSession;
CRYPT_CERTIFICATE cryptRTCSResponse;
int status;
/* Create the RTCS session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_RTCS );
/* Add the RTCS request and activate the session with the RTCS
responder */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_REQUEST,
cryptRTCSRequest );
status = cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE,
TRUE );
if( cryptStatusError( status ) )
/* Couldn't establish session with RTCS responder */;
/* Clean up the RTCS request object, which isn't needed any more */
cryptDestroyCert( cryptRTCSRequest );
/* Obtain the response information */
status = cryptGetAttribute( cryptSession, CRYPT_SESSINFO_RESPONSE,
&cryptRTCSResponse );
if( cryptStatusError( status ) )
/* No response available from responder */;
/* Clean up the session object */
cryptDestroySession( cryptSession );

Onc
ey
ou
’
v
eg
ott
her
e
s
po
ns
ef
r
o
mt
hes
e
r
v
e
r
,
y
ouc
a
ng
e
tt
hec
e
r
t
i
f
i
c
a
t
es
t
a
t
usf
r
om
it by reading the CRYPT_CERTINFO_CERTSTATUS attribute:
int certStatus;
cryptGetAttribute( cryptRTCSResponse, CRYPT_CERTINFO_CERTSTATUS,
&certStatus );
if( certStatus == CRYPT_CERTSTATUS_VALID )
/* Certificate is valid */;
/* Clean up the RTCS response */
cryptDestroyCert( cryptRTCSResponse );

The possible certificate status values are CRYPT_CERTSTATUS_VALID,
CRYPT_CERTSTATUS_NOTVALID, and CRYPT_CERTSTATUS_UNKNOWN,
with obvious meanings.
Asme
nt
i
o
ne
da
b
ov
e
,
y
ouma
yne
e
dt
os
e
tt
h
eRTCSr
e
s
po
nde
rURLi
fi
ti
s
n’
tpr
e
s
e
nt
in the certificate or if the value given in the certificate is incorrect. You can set the
responder URL as the CRYPT_SESSINFO_SERVER_NAME:
CRYPT_SESSION cryptSession;
/* Create the RTCS session */
cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_RTCS );

Certificate Status Checking using RTCS

167

/* Add the responder URL and RTCS request and activate the session
with the RTCS responder */
cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME,
serverName, serverNameLength );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_REQUEST,
cryptRTCSRequest );
/* ... */

Advanced RTCS Queries
In addition to querying the status of individual certificates, you can query the status of
a number of certificates at once by adding more than one certificate to the RTCS
request. The response will contain information for each certificate in the query,
which you can use to verify each certificate using cryptCheckCert. If the response
information indicates that the certificate is invalid, cryptlib will return CRYPT_ERROR_INVALID and leave the entry for the certificate in the RTCS response as
the selected one, allowing you to obtain further information about the certificate if
any is available:
CRYPT_CERTIFICATE cryptRTCSResponse;
time_t revocationTime;
int revocationReason;
/* Check the certificate against the RTCS response */
cryptCheckCert( cryptCertificate, cryptRTCSResponse );
if( status == CRYPT_ERROR_INVALID )
{
int revocationTimeLength;
/* The certificate has been revoked, get the revocation time and
reason */
cryptGetAttributeString( cryptRTCSResponse,
CRYPT_CERTINFO_REVOCATIONDATE, &revocationTime,
&revocationTimeLength );
cryptGetAttribute( cryptRTCSResponse, CRYPT_CERTINFO_CRLREASON,
&revocationReason );
}

I
fa
l
ly
ou
’
r
ei
nt
e
r
e
s
t
e
di
ni
sa
nov
e
r
a
l
lv
a
l
i
di
t
yi
nd
i
c
a
t
i
onf
orac
ol
l
e
c
t
i
o
nof
c
e
r
t
i
f
i
c
a
t
e
st
he
na
na
l
t
e
r
n
a
t
i
v
et
e
c
h
ni
quet
ha
tdo
e
s
n
’
tr
e
q
ui
r
ec
a
l
l
i
ngcryptCheckCert
for each certificate is to step through the responses using the extension cursor
management, checking the status for each certificate and recording whether any one
indicates that the certificate is invalid:
int certsValid = TRUE;
cryptSetAttribute( cryptRTCSResponse,
CRYPT_CERTINFO_CURRENT_CERTIFICATE, CRYPT_CURSOR_FIRST );
do
{
int certStatus;
/* Check the status of the currently selected certificate */
cryptGetAttribute( cryptRTCSResponse, CRYPT_CERTINFO_CERTSTATUS,
&certStatus );
if( certStatus != CRYPT_CERTSTATUS_VALID )
certsValid = FALSE;
}
while( certsValid &&
cryptSetAttribute( cryptRTCSResponse,
CRYPT_CERTINFO_CURRENT_CERTIFICATE, CRYPT_CURSOR_NEXT ) ==
CRYPT_OK );
if( !certsValid )
/* At least one certificate is invalid */;

This will step through all of the responses checking for an indication that a certificate
is invalid. Once the loop terminates, the certsValid variable will contain the
composite status of the complete set of certificates.

168

Certificates and Certificate Management

Certificate Revocation Checking using OCSP
In order to check whether a certificate is present in a CRL, cryptlib supports the
online certificate status protocol (OCSP). The simplest way to use OCSP is with
cryptCheckCert, which returns a straightforward revoked/not revoked status
c
or
r
e
s
po
nd
i
ngt
oac
e
r
t
i
f
i
c
a
t
e
’
spr
e
s
e
nc
ei
naCRL,
a
ndi
sd
e
s
c
r
i
be
di
nt
hene
x
t
section. More complex OCSP usage, including obtaining detailed status information
and querying the status of multiple certificates at once is covered in the sections that
f
o
l
l
ow.Not
et
ha
tOCSPc
a
nonl
yr
e
t
ur
na
na
ppr
ox
i
ma
t
ec
e
r
t
i
f
i
c
a
t
es
t
a
t
us(
i
tc
a
n
’
t
truly determine whether a certificate is really valid), and will often return a response
based on out-of-date CRL information. If you require a true online certificate validity
check, you should use the real-time certificate status protocol (RTCS) as described in
“
Certificate Status Checking using RTCS”onp
a
g
e162.

Basic OCSP Queries
The simplest way to work with OCSP is to use it with cryptCheckCert to check the
revocation status of a certificate. The process is identical to the one used for the
RTCSs
t
a
t
usc
he
c
kde
s
c
r
i
b
e
di
n“
Certificate Status Checking using RTCS”onpa
g
e
162, except that the session type is CRYPT_SESSION_OCSP instead of
CRYPT_SESSION RTCS.
If cryptCheckCert r
e
t
ur
nsCRYPT_OKt
hi
sme
a
nst
ha
tt
h
ec
e
r
t
i
f
i
c
a
t
eha
s
n
’
tbe
e
n
revoked. This doesn’
tme
a
nt
hes
a
mea
ss
a
y
i
ngt
ha
tt
hec
e
r
t
i
f
i
c
a
t
ei
sOK,
abog
us
c
e
r
t
i
f
i
c
a
t
et
ha
te
x
i
s
t
sbu
ti
s
n
’
tr
e
c
og
ni
s
e
dbyt
heCAa
sha
v
i
ngbe
e
ni
s
s
ue
d,
ora
n
e
x
pi
r
e
dc
e
r
t
i
f
i
c
a
t
e
,
orac
e
r
t
i
f
i
c
a
t
ewhi
c
hi
si
nv
a
l
i
df
ors
o
meot
he
rr
e
a
s
onori
s
n’
te
v
e
n
a certificate (for e
x
a
mpl
ea
nEx
c
e
ls
pr
e
a
ds
he
e
t
)woul
da
l
s
obeg
i
v
e
nas
t
a
t
uso
f“
not
r
e
v
ok
e
d”s
i
nc
et
h
a
t
’
sa
l
lt
ha
tt
her
e
s
po
nd
e
ri
sc
a
p
a
bl
eo
fs
a
y
i
nga
bouti
t
.I
na
dd
i
t
i
on
OCSP responders are often fed from stale CRL information, so a not-revoked
r
e
s
pons
edo
e
s
n
’
tn
e
c
e
s
s
a
rily mean that the certificate is really not revoked, merely
t
ha
ta
tt
het
i
met
hei
n
f
or
ma
t
i
o
nwa
sl
a
s
tu
pda
t
e
di
tha
dn
’
tb
e
e
nr
e
v
ok
e
d.OCSPi
s
purely an online CRL query mechanism, not a general-purpose certificate validity
checker.

Creating an OCSP Request
OCSPr
e
que
s
t
swor
kj
us
tl
i
k
eRTCSr
e
que
s
t
sde
s
c
r
i
be
di
n“
Creating an RTCS
Request”onp
a
g
e165, except that the request type is CRYPT_CERTTYPE_OCSP_REQUEST instead of CRYPT_CERTTYPE_RTCS_REQUEST, however in addition
to the certificate being queried an OCSP request also needs to have the CA certificate
that issued the certificate being queried added to the request before the certificate
itself is added. The CA certificate is added as a CRYPT_CERTINFO_CACERTIFICATE attribute:
CRYPT_CERTIFICATE cryptOCSPRequest;
/* Create the OCSP request */
cryptCreateCert( &cryptOCSPRequest, cryptUser,
CRYPT_CERTTYPE_OCSP_REQUEST );
/* Add the certificate to be queried and the CA certificate that
issued it to the request */
cryptSetAttribute( cryptOCSPRequest, CRYPT_CERTINFO_CACERTIFICATE,
cryptCACert );
cryptSetAttribute( cryptOCSPRequest, CRYPT_CERTINFO_CERTIFICATE,
cryptCertificate );

As with RTCS requests, the certificate being queried may contain responder details in
the CRYPT_CERTINFO_AUTHORITYINFO_OCSP attribute, or you may need to
a
ddt
he
mma
n
ua
l
l
ya
se
x
pl
a
i
n
e
di
n“
Creating an RTCS Request”onp
a
g
e165.
OCSPr
e
que
s
t
sc
a
na
l
s
ob
es
i
g
ne
d,
i
fy
ou’
r
ewor
k
i
ngwith a CA that uses this
capability then you can sign the request before submitting it in the standard way using
cryptSignCert:

Certificate Revocation Checking using OCSP

169

CRYPT_CERTIFICATE cryptOCSPRequest;
/* Create the OCSP request */
cryptCreateCert( &cryptOCSPRequest, cryptUser,
CRYPT_CERTTYPE_OCSP_REQUEST );
/* Add the certificate to be queried to the request and sign it */
cryptSetAttribute( cryptOCSPRequest, CRYPT_CERTINFO_CERTIFICATE,
cryptCertificate );
cryptSignCert( cryptOCSPRequest, privateKey );

OCSP requests can also include signing certificates alongside the signature, you can
specify the amount of additional information to include with the signature by setting
the CRYPT_CERTINFO_SIGNATURELEVEL attribute as described in
“
Signing/Verifying Certificates”onp
a
g
e223.

Communicating with an OCSP Responder
Communicating with an OCSP responder works in exactly the same way as
c
o
mmu
ni
c
a
t
i
ngwi
t
ha
nRTCSr
e
s
pond
e
rde
s
c
r
i
be
di
n“
Communicating with an
RTCS Responder”on page 166, except that the session type is CRYPT_SESSION_OCSPr
a
t
he
rt
ha
nCRYPT_SESSI
ON_RTCS.Onc
ey
ou’
v
es
uc
c
e
s
s
f
u
l
l
ya
c
t
i
v
a
t
e
dt
he
session, you can read the certificate revocation status from the returned OCSP
response by reading the CRYPT_CERTINFO_REVOCATIONSTATUS attribute:
int revocationStatus;
cryptGetAttribute( cryptOCSPResponse, CRYPT_CERTINFO_REVOCATIONSTATUS,
&revocationStatus );
if( revocationStatus == CRYPT_OCSPSTATUS_NOTREVOKED )
/* Certificate hasn't been revoked */;
/* Clean up the OCSP response */
cryptDestroyCert( cryptOCSPResponse );

The possible certificate status values are CRYPT_OCSPSTATUS_NOTREVOKED,
CRYPT_OCSPSTATUS_REVOKED, and CRYPT_OCSPSTATUS_UNKNOWN.
Note that since OCSP is purely a revocation checking protocol, CRYPT_OCSPSTATUS_NOTREVOKEDme
a
nse
x
a
c
t
l
yt
ha
t
,
t
ha
tt
hec
e
r
t
i
f
i
c
a
t
eh
a
s
n
’
tb
e
e
n
r
e
v
ok
e
d.Thi
sdoe
s
n
’
tme
a
nt
hes
a
mea
ss
a
y
i
ngt
ha
tt
hec
e
r
t
i
f
i
c
a
t
ei
sOK,
abog
us
c
e
r
t
i
f
i
c
a
t
et
ha
te
x
i
s
t
sbu
ti
s
n
’
tr
e
c
og
ni
s
e
dbyt
heCAa
sha
v
i
ngbe
e
ni
s
s
ued (for
example a forged certificate created by an attacker), or an expired certificate, or a
c
e
r
t
i
f
i
c
a
t
ewh
i
c
hi
si
nv
a
l
i
df
o
rs
omeo
t
he
rr
e
a
s
onori
s
n’
te
v
e
nac
e
r
t
i
f
i
c
a
t
e(
f
or
e
x
a
mp
l
ea
nEx
c
e
ls
pr
e
a
ds
he
e
t
)woul
da
l
s
obeg
i
v
e
nas
t
a
t
usof“
n
otr
e
v
ok
e
d
”s
i
nce
t
ha
t
’
sa
l
lt
ha
tt
her
e
s
p
on
de
ri
sc
a
pa
bl
eo
fs
a
y
i
nga
bo
uti
t
.I
na
d
di
t
i
o
nOCSP
responders are often fed from stale CRL information, so a not-revoked response
doe
s
n’
tne
c
e
s
s
a
r
i
l
yme
a
nt
h
a
tt
hec
e
r
t
i
f
i
c
a
t
ei
sr
e
a
l
l
ynotr
e
v
ok
e
d,
me
r
e
l
yt
h
a
ta
tt
he
time thei
n
f
or
ma
t
i
onwa
sl
a
s
tupd
a
t
e
di
tha
d
n
’
tb
e
e
nr
e
v
ok
e
d.OCSPi
spur
e
l
ya
n
online CRL query mechanism, not a general-purpose certificate validity checker.
In addition to the certificate status, the OCSP response also contains information
relating to the CRL that the responder used to create the response, including
CRYPT_CERTINFO_THISUPDATE, the time of the current CRL, an optional
CRYPT_CERTINFO_NEXTUPDATE, the time of the next CRL, and CRYPT_CERTINFO_REVOCATIONDATE, the time at which the certificate was revoked. If
the OCSP responder is using a direct query of a certificate store rather than
assembling the information indirectly using CRLs then the current CRL time will
us
ua
l
l
ybes
e
tt
ot
hec
ur
r
e
ntt
i
mee
v
e
ni
fi
t
’
sa
s
s
e
mbl
e
df
r
o
ms
t
a
l
ei
nf
or
ma
t
i
onho
ur
s
or days old. In addition the next update time may be set to the current time, or to a
future time. None of these fields are particularly useful and different CAs assign
different meanings to them, so they can be ignored in most circumstances, they relate
mainly to the CRL-based origins of certain portions of OCSP. In addition, while
RTCS uses times relative to the local system time, OCSP uses the absolute time on
the responder, so time values will vary based on time differences between the OCSP
responder and the local machine.

170

Certificates and Certificate Management

Advanced OCSP Queries
Some OCSP responders can resolve multiple certificate status queries in a single
r
e
que
s
t
,
howe
v
e
rbe
c
a
us
eo
ft
heda
t
af
or
ma
tus
e
di
nOCSPt
hi
sd
oe
s
n’
twor
kpr
ope
r
l
y
f
orOCSPv
e
r
s
i
o
n1r
e
s
po
nd
e
r
ss
oi
t
’
sbe
t
t
e
rto submit a number of separate queries
rather than trying to query the status of a set of certificates in a single request. In
a
dd
i
t
i
ons
omer
e
s
po
nd
e
r
sc
a
n
’
th
a
n
dl
emu
l
t
i
pl
ec
e
r
t
i
f
i
c
a
t
e
s
,
orwi
l
li
g
nor
ea
l
lb
utt
he
first certificate, making it even more advisable to restrict queries to a single
certificate. Although a planned future revision of OCSP may not have this problem,
i
t
’
ss
t
i
l
lpr
u
de
n
tt
oonl
yq
ue
r
yas
i
ng
l
ec
e
r
t
i
f
i
c
a
t
epe
rr
e
q
ue
s
tun
l
e
s
sy
ou
’
r
es
ur
et
h
a
t
t
her
e
s
p
on
de
ry
ou
’
r
eus
i
ngwi
l
lha
nd
l
emulti-certificate queries correctly.
If you submit a query containing multiple certificates, the response from the
responder constitutes a mini-CRL that contains revocation information only for the
certificates submitted in the query (assuming that the responder can handle multiple
certificates in a query). Because of this you can treat the response as if it were a
normal CRL and check the certificates you submitted against it with cryptCheckCert
just like a CRL. If the certificate has been revoked, cryptlib will return
CRYPT_ERROR_I
NVALI
Da
ndl
e
a
v
et
h
ec
e
r
t
i
f
i
c
a
t
e
’
sr
e
v
oc
a
t
i
o
ne
n
t
r
yi
nt
heOCSP
response as the selected one, allowing you to obtain further information on the
revocation (for example the revocation date or reason):
CRYPT_CERTIFICATE cryptOCSPResponse;
time_t revocationTime;
int revocationReason;
/* Check the certificate against the OCSP response */
cryptCheckCert( cryptCertificate, cryptOCSPResponse );
if( status == CRYPT_ERROR_INVALID )
{
int revocationTimeLength;
/* The certificate has been revoked, get the revocation time and
reason */
cryptGetAttributeString( cryptOCSPResponse,
CRYPT_CERTINFO_REVOCATIONDATE, &revocationTime,
&revocationTimeLength );
cryptGetAttribute( cryptOCSPResponse, CRYPT_CERTINFO_CRLREASON,
&revocationReason );
}

Note that, as with standard CRLs, the revocation reason is an optional component and
ma
yno
tbepr
e
s
e
n
ti
nt
heOCSPr
e
s
po
ns
e
.I
ft
her
e
v
oc
a
t
i
o
nr
e
a
s
oni
s
n
’
tpr
e
s
e
nt
,
c
r
y
pt
l
i
bwi
l
lr
e
t
ur
nCRYPT_
ERROR_NOTFOUND.I
fa
l
ly
ou’
r
ei
nt
e
r
e
s
t
e
di
ni
sa
revoked/not revoked status for a collection of certificates then you can step through
the responses checking the status for each one in turn in the same way as for RTCS.

Creating the Top-level (Root) CA Key

171

Managing a Certification Authority
Al
t
ho
ug
hi
t
’
sp
os
s
i
b
l
et
oma
n
ua
l
l
yma
n
a
g
et
heope
r
a
t
i
ono
faCAa
ndissue
certificates and CRLs using cryptSignCert,
i
t
’
smu
c
he
a
s
i
e
rt
ous
ec
r
y
pt
l
i
b
’
sb
ui
l
t
-in
CA management capabilities to do this for you. In order to use the CA management
c
a
pa
bi
l
i
t
i
e
sy
oun
e
e
dt
oc
r
e
a
t
eac
e
r
t
i
f
i
c
a
t
es
t
or
ea
se
x
pl
a
i
n
e
di
n“
Creating/Destroying
Keyset Objects”onp
a
g
e134. The keyset type for a certificate store can only be
CRYPT_KEYSET_DATABASE_STORE, CRYPT_KEYSET_ODBC_STORE, or
CRYPT_KEYSET_PLUGIN_STORE, since cryptlib requires a full relational
database with transaction processing capabilities in order to manage the CA
operations. The use of a transaction-capable certificate store results in a high degree
of scalability and provides the level of reliability, availability, and error recovery
required of such an application and stipulated in a number of standards that cover CA
operation.
Onc
ey
ou
’
v
ec
r
e
a
t
e
dac
e
r
t
i
f
i
c
a
t
es
t
or
e
,
y
ouc
a
nop
e
nac
on
ne
c
t
i
o
nt
oi
tl
i
k
eanor
ma
l
keyset. Since all accesses that open the keyset for write acces
sa
r
el
og
g
e
d,
i
t
’
sbe
t
t
e
r
to open the connection to the keyset once and then leave it open for ongoing
operations than to open and close it for each operation, since this would lead to an
excessive number of log entries.
Ac
e
r
t
i
f
i
c
a
t
es
t
or
ed
oe
s
n’
two
r
kl
i
k
eas
t
a
nda
r
dk
e
y
s
e
ti
nwhi
c
hi
t
’
sp
os
s
i
b
l
et
oi
ns
e
r
t
a
ndde
l
e
t
ec
e
r
t
i
f
i
c
a
t
e
sa
ndCRLsa
tr
a
ndo
m.I
ns
t
e
a
d,
i
t
’
sus
e
di
nc
o
mb
i
na
t
i
onwi
t
h
various certificate management functions that use the certificate store as a mechanism
for managing the operations performed by a CA. The CA operations consist of
recording incoming certificate requests, converting them into certificates, and issuing
CRLs for revoked certificates. All of these operations are managed automatically for
you by cryptlib using the transaction processing capabilities of the certificate store to
handle the data storage, reliability, and auditing requirements of the CA.
There are two ways in which you can run a CA. The easiest option is to use
c
r
y
pt
l
i
b’
sb
ui
l
t
-in CMP or SCEP servers to handle all CA operations. The more
c
o
mp
l
e
xopt
i
o
ni
st
ous
ec
r
y
p
t
l
i
b’
sCAma
n
a
g
e
me
ntf
u
nc
t
i
onst
oha
ndl
et
h
eCA
operations yourself. Of the two CA management protocols, CMP is the more
complete, allowing you to request new certificates, update/replace existing ones, and
revoke existing certificates, works with special-purpose certificates such as signingonly or encryption-only types, and provides flexibility in the authorisation
mechanisms used, with the request authorised either with a user name and password
or signed with an existing certificate. SCEP on the other hand is a relatively simple
protocol that allows for a single type of operation, issuing a new certificate, and a
single certificate type, an RSA certificate capable of both encryption and signing,
with the request authorised with a user name and password.
Be
f
or
ey
oub
e
g
i
ny
ou’
l
lne
e
dt
ode
c
i
dewhi
c
ho
ft
h
et
wobe
s
tme
e
t
sy
ourne
e
ds
.
Us
ua
l
l
yi
t
’
l
lbeCMP,
whi
c
hi
smor
ef
l
e
x
i
bl
et
ha
nSCEP.Al
t
e
r
na
t
i
v
e
l
y
,
y
ouc
a
nr
u
n
both a CMP and SCEP server, althoug
hy
ou’
l
lha
v
et
or
unt
he
m ondi
f
f
e
r
e
n
tpor
t
s
since both protocols use HTTP for their communications.

Creating the Top-level (Root) CA Key
The first thing that you need to do when you set up your CA is to create your toplevel (root) CA key. This involves creating the public/private key pair, adding
identification information to it, signing it to create the CA root certificate, and
opt
i
o
na
l
l
ys
t
or
i
ngi
tt
od
i
s
ki
ty
ou’
r
en
othol
di
ngi
ti
nac
r
y
pt
ot
ok
e
ns
uc
ha
sas
ma
r
t
card or hardware security module (HSM). You can generate the root CA key as
follows:

172

Managing a Certification Authority

CRYPT_CONTEXT cryptContext;
/* Create an RSA public/private key context, set a label for it, and
generate a key into it */
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_RSA );
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_LABEL,
"Private key", 11 );
cryptGenerateKey( cryptContext );

Mor
ede
t
a
i
l
so
nk
e
y
sa
ndk
e
yg
e
ne
r
a
t
i
ona
r
eg
i
v
e
ni
n“
Key Generation”onpa
g
e131.
Onc
ey
ou
’
v
eg
e
ne
r
a
t
e
dt
h
e key, you can create the root CA certificate and add the
CA’
si
de
nt
i
f
i
c
a
t
i
oni
nf
or
ma
t
i
ont
oi
t
,
whi
c
hus
ua
l
l
yc
ons
i
s
t
soft
h
ec
o
un
t
r
y
,
organisation name, organisational unit name, and finally the actual CA name, referred
to as the common name in PKI terminology:
CRYPT_CERTIFICATE cryptCertificate;
/* Create the CA certificate */
cryptCreateCert( &cryptCertificate, cryptUser,
CRYPT_CERTTYPE_CERTIFICATE );
/* Add identification information */
cryptSetAttributeString( cryptCertificate, CRYPT_CERTINFO_COUNTRYNAME,
countryName, 2 );
cryptSetAttributeString( cryptCertificate,
CRYPT_CERTINFO_ORGANIZATIONNAME, organizationName,
organizationNameLength );
cryptSetAttributeString( cryptCertificate,
CRYPT_CERTINFO_ORGANIZATIONALUNITNAME, organizationalUnitName,
organizationalUnitNameLength );
cryptSetAttributeString( cryptCertificate, CRYPT_CERTINFO_COMMONNAME,
commonName, commonNameLength );

Mor
ede
t
a
i
l
so
nc
e
r
t
i
f
i
c
a
t
ena
mi
nga
r
eg
i
v
e
ni
n“
Certificate Identification
Information”onp
a
g
e214.
Once the CA name is set, you need to mark the certificate as a self-signed CA
certificate:
cryptSetAttribute( cryptCertificate, CRYPT_CERTINFO_SELFSIGNED, 1 );
cryptSetAttribute( cryptCertificate, CRYPT_CERTINFO_CA, 1 );

Finally, you may want to add two URLs that indicate to users where further CA
services may be found, in particular CRYPT_CERTINFO_AUTHORITYINFO_CERTSTORE to tell users where to go to find further certificates and CRYPT_CERTINFO_AUTHORITYINFO_RTCS to tell users where to go for real-time
certificate status information: Since these attributes are a composite GeneralName
field, you need to first select them and then add the URL as a CRYPT_CERTINFO_UNIFORMRESOURCEIDENTIFIER attribute within the GeneralName:
cryptSetAttribute( cryptCertificate,
CRYPT_CERTINFO_AUTHORITYINFO_CERTSTORE, CRYPT_UNUSED );
cryptSetAttributeString( cryptCertificate,
CRYPT_CERTINFO_UNIFORMRESOURCEIDENTIFIER, certstoreUrl,
certstoreUrlLength );
cryptSetAttribute( cryptCertificate,
CRYPT_CERTINFO_AUTHORITYINFO_RTCS, CRYPT_UNUSED );
cryptSetAttributeString( cryptCertificate,
CRYPT_CERTINFO_UNIFORMRESOURCEIDENTIFIER, rtcsUrl, rtcsUrlLength );

With the URLs present in the resulting certificate, users will automatically know
where to go to obtain further certificate-related information.
You can also set these URLs on a per-us
e
rba
s
i
swhe
ny
ous
e
tupe
a
c
hus
e
r
’
s
information, although putting it in the CA certificate allows you to set it just once
without having to set it up for each user (cryptlib will automatically propagate it from
t
heCAc
e
r
t
i
f
i
c
a
t
et
ot
heus
e
rc
e
r
t
i
f
i
c
a
t
e
swhe
nt
h
e
y
’
r
ei
s
s
u
e
d)
.Mor
ede
t
a
i
l
son
c
e
r
t
i
f
i
c
a
t
es
t
or
ea
c
c
e
s
sa
r
eg
i
ve
ni
n“
HTTP Keysets”o
npa
g
e136, and details on realt
i
mec
e
r
t
i
f
i
c
a
t
es
t
a
t
usc
he
c
k
i
n
ga
r
eg
i
v
e
ni
n“
Certificate Status Checking using
RTCS”onpa
g
e164.
Your root CA certificate is now ready to be signed:

Initialising PKI User Information

173

cryptSignCert( cryptCertificate, cryptContext );

I
fy
ou’
r
es
t
or
i
ngt
heCAi
n
f
or
ma
t
i
o
no
ndi
s
k
,
y
ounown
e
e
dt
os
a
v
et
h
ek
e
y
sa
nd
certificates to a password-protected private-key file:
CRYPT_KEYSET cryptKeyset;
/* Save the generated public/private key pair to a keyset */
cryptKeysetOpen( &cryptKeyset, cryptUser, CRYPT_KEYSET_FILE, fileName,
CRYPT_KEYOPT_CREATE );
cryptAddPrivateKey( cryptKeyset, cryptContext, password );
cryptAddPublicKey( cryptKeyset, cryptCertificate );
cryptKeysetClose( cryptKeyset );
/* Clean up */
cryptDestroyContext( cryptContext );
cryptDestroyCert( cryptCertificate );

I
fy
ou’
r
es
t
or
i
ngt
hei
n
f
or
ma
t
i
oni
nac
r
y
pt
ode
v
i
c
e
,
t
hek
e
y
swi
l
la
l
r
e
a
dybei
nt
he
device, and all you need to do is update it with the newly-created certificate:
cryptAddPublicKey( cryptDevice, cryptCertificate );
/* Clean up */
cryptDestroyCert( cryptCertificate );

At this point your root CA key is ready to use for issuing certificates.

Initialising PKI User Information
In order to be able to issue certificates to an end user (called a PKI user in CMP
terminology), cryptlib first needs to know various pieces of information about them.
You supply this information via a PKI user certificate object, providing a partial or
c
o
mp
l
e
t
eDNf
ort
hei
s
s
u
e
dc
e
r
t
i
f
i
c
a
t
e
,
a
swe
l
la
sa
nyot
he
ri
nf
or
ma
t
i
ont
ha
t
’
s
required for the certificate such as an email address or URL, an indication as to
whether the user is a CA capable of issuing their own certificates, and so on. Once
y
ou’
v
epr
ov
i
de
dt
hei
n
f
or
ma
t
i
onf
ort
h
ePKIus
e
r
,
y
oua
ddi
tt
ot
hec
e
r
t
i
f
i
c
a
t
es
t
or
e
that will be used by the CMP or SCEP CA session, after which the CA server will
consult the certificate store when it needs to issue a certificate. cryptlib will
a
ut
o
ma
t
i
c
a
l
l
yg
e
ne
r
a
t
et
heus
e
rI
Da
ndpa
s
s
wor
df
ory
ouwhe
ny
o
u’
v
ef
i
n
i
s
he
d
creating the PKI user object.
When you add the DN information to the PKI user object, you can specify either a
c
o
mp
l
e
t
eDNorapa
r
t
i
a
lDNt
ha
to
mi
t
st
heus
e
r
’
sc
ommonna
me
.ThePKIus
e
r
obj
e
c
ta
c
t
sb
ot
ha
sat
e
mp
l
a
t
ef
ort
heDNi
nt
heus
e
r
’
sc
e
r
t
i
f
i
c
a
t
ea
n
da
sac
o
ns
t
r
a
i
nt
on the actual DN that a user can choose, preventing them from choosing an arbitrary
DNf
ort
he
i
rc
e
r
t
i
f
i
c
a
t
e
.I
t
’
ss
t
r
ong
l
yr
e
c
omme
n
de
dt
h
a
ty
o
us
pe
c
i
f
yt
h
eus
e
r
’
sf
u
l
l
DNi
nt
hePKIus
e
rob
j
e
c
t
,
s
ot
ha
tt
he
ya
r
e
n
’
tr
e
q
ui
r
e
dt
ok
nowt
h
eDNbutc
a
n
simply submit a request and have the CA take care of assigning a DN for them.
Alternatively, you can specify all DN components except the common name and let
the user specify the common name in the request. The least preferable option, since it
both requires that the user know their full DN and specify it in the request, and allows
them to request any type of DN, is to omit setting a DN in the PKI user object, which
allows the user to specify any DN value. However, omitting the DN from the PKI
user template can lead to problems later if you want to read the PKI user object back
f
r
o
mt
h
ec
e
r
t
i
f
i
c
a
t
es
t
or
e
,
s
i
nc
et
he
r
e
’
sn
ona
mepr
e
s
e
ntt
oi
de
n
t
i
f
yi
t
.
Ta
k
i
ngt
hes
i
mpl
e
s
top
t
i
on,
i
nwhi
c
ht
heCAs
up
pl
i
e
st
h
ef
u
l
lDNa
ndt
h
eus
e
rd
oe
s
n
’
t
need to know any DN details, you would use:
CRYPT_CERTIFICATE cryptPKIUser;
/* Create the PKI user */
cryptCreateCert( &cryptPKIUser, cryptUser, CRYPT_CERTTYPE_PKIUSER );

174

Managing a Certification Authority

/* Add identification information */
cryptSetAttributeString( cryptPKIUser, CRYPT_CERTINFO_COUNTRYNAME,
countryName, 2 );
cryptSetAttributeString( cryptPKIUser,
CRYPT_CERTINFO_ORGANIZATIONNAME, organizationName,
organizationNameLength );
cryptSetAttributeString( cryptPKIUser,
CRYPT_CERTINFO_ORGANIZATIONALUNITNAME, organizationalUnitName,
organizationalUnitNameLength );
cryptSetAttributeString( cryptPKIUser, CRYPT_CERTINFO_COMMONNAME,
commonName, commonNameLength );
/* Add the user information to the certificate store */
cryptCAAddItem( cryptCertStore, cryptPKIUser );
/* Clean up */
cryptDestroyCert( cryptPKIUser );

The same operation in Visual Basic is:
Dim cryptPKIUser As Long
' Create the PKI user
cryptCreateCert cryptPKIUser, cryptUser, CRYPT_CERTTYPE_PKIUSER
' Add identification information
cryptSetAttributeString cryptPKIUser, CRYPT_CERTINFO_COUNTRYNAME, _
countryName, 2
cryptSetAttributeString cryptPKIUser, _
CRYPT_CERTINFO_ORGANIZATIONNAME, organizationName, _
organizationNameLength
cryptSetAttributeString cryptPKIUser, _
CRYPT_CERTINFO_ORGANIZATIONALUNITNAME, organizationalUnitName, _
organizationalUnitNameLength
cryptSetAttributeString cryptPKIUser, CRYPT_CERTINFO_COMMONNAME, _
commonName, commonNameLength
' Add the user information to the certificate store
cryptCAAddItem cryptCertStore, cryptPKIUser
' Clean up
cryptDestroyCert cryptPKIUser

A simple way to handle this type of operation is to automatically populate the
certificate store with information from a source such as a personnel database
containing all of the required user information.

Other PKI User Information
In addition to the user DN, you can may also want to add further information to allow
the user to automatically locate resources such as further certificates issued by the CA
and RTCS responders. By adding these URLs to the PKI user information (which
e
ns
ur
e
st
ha
ti
t
’
l
lbepr
e
s
e
nti
nt
hec
e
r
t
i
f
i
c
a
t
eo
nc
ei
t
’
si
s
s
ue
d)
,
a
ny
oneus
i
ngt
he
certificate can automatically determine where to go to find further certificates and
certificate status information without requiring any manual configuration.
The easiest way to get this information into user certificates is to add it to the issuing
CA’
sc
e
r
t
i
f
i
c
a
t
e
,
f
r
o
m whi
c
hi
t
’
l
lbea
ut
o
ma
t
i
c
a
l
l
ypr
op
a
g
a
t
e
di
n
t
oa
nyc
e
r
t
i
f
i
c
a
t
e
s
that the CA issues. You can however also add this information on a per-user basis as
the CRYPT_CERTINFO_AUTHORITYINFO_CERTSTORE and CRYPT_CERTINFO_AUTHORITYINFO_RTCS attributes, which contain information about
the location of the certificate store and RTCS responder, usually in the form of a
URL. Since these attributes are composite GeneralName fields, you need to first
select them and then add the URL as a CRYPT_CERTINFO_UNIFORMRESOURCEIDENTIFIER attribute within the GeneralName:

Initialising PKI User Information

175

cryptSetAttribute( cryptPKIUser,
CRYPT_CERTINFO_AUTHORITYINFO_CERTSTORE, CRYPT_UNUSED );
cryptSetAttributeString( cryptPKIUser,
CRYPT_CERTINFO_UNIFORMRESOURCEIDENTIFIER, certstoreUrl,
certstoreUrlLength );
cryptSetAttribute( cryptPKIUser, CRYPT_CERTINFO_AUTHORITYINFO_RTCS,
CRYPT_UNUSED );
cryptSetAttributeString( cryptPKIUser,
CRYPT_CERTINFO_UNIFORMRESOURCEIDENTIFIER, rtcsUrl, rtcsUrlLength );

With the URL present in the resulting certificate, users will automatically know
where to go to obtain further certificates and certificate status information.
In addition to the CA-related information, you can also specify additional user
information that will appear in the issued certificate. The most common additional
i
n
f
or
ma
t
i
o
nwoul
dbea
ne
ma
i
la
d
dr
e
s
st
h
a
t
’
sus
e
dt
oi
de
n
t
i
f
yt
heus
e
ra
l
o
ng
s
i
det
he
i
r
DN:
cryptSetAttributeString( cryptPKIUser, CRYPT_CERTINFO_RFC822NAME,
emailAddr, emailAddrLength );

although since this may change over time you may want to let the user specify it in
their certificate request. A downside of this flexibility is that the user can then
r
e
que
s
tac
e
r
t
i
f
i
c
a
t
ewi
t
ha
nye
ma
i
la
ddr
e
s
st
he
ywa
ntr
a
t
he
rt
ha
nt
heo
net
ha
ty
o
u’
v
e
got recorded for them.
In addition to the standard identification information, you can also specify other
information that should appear in all certificates issued to this particular user. One
piece of certificate information that can only be specified in the PKI user data is
whether the user is to be a CA or not. To create a CA user, you set the CA flag for
the user:
cryptSetAttribute( cryptPKIUser, CRYPT_CERTINFO_CA, 1 );

This is the only way in which a CA certificate can be issued, since allowing a user to
specify the issuing of a CA certificate in a user request would allow any user to make
themselves a CA. If cryptlib receives a request from a user for the creation of a CA
certificate it will either reject the request, since the CA capability can only be
permitted by the issuing CA and not the requesting user.
Because a CA-enabled user has special privileges, you should take extra care in
managing passwords and related information for them, and may want to delete the
user after their CA certificate has been issued to prevent them from being re-used to
obtain further CA certificates. This makes the sub-CA creation capability a one-shot
process that requires explicit manual intervention by the issuing CA every time a subCA is created.

PKI User IDs
Certificate initialisation requests are identified through a user ID (to locate the
appropriate PKI user information) and a password (to authenticate the request). Once
the user information has been entered into the certificate store, you can read back the
PKI user ID, identified by CRYPT_CERTINFO_PKIUSER_ID, the password used to
authenticate the initialisation operation, identified by CRYPT_CERTINFO_PKIUSER_ISSUEPASSWORD, and the password used to authenticate certificate
r
e
v
oc
a
t
i
on(
i
fy
ou
’
r
eus
i
ngCMP)
,
CRYPT_CERTI
NFO_PKI
USER_REVPASSWORD. Use of the revocation password is optional, the CA may use
signed revocation requests rather than password-protected ones:
char userID[ CRYPT_MAX_TEXTSIZE + 1 ];
char issuePW[ CRYPT_MAX_TEXTSIZE + 1 ];
char revPW[ CRYPT_MAX_TEXTSIZE + 1 ];
int userIDlength, issuePWlength, revPWlength;
cryptGetAttributeString( cryptPKIUser, CRYPT_CERTINFO_PKIUSER_ID,
userID, &userIDlength );
userID[ userIDlength ] = '\0';
cryptGetAttributeString( cryptPKIUser,
CRYPT_CERTINFO_PKIUSER_ISSUEPASSWORD, issuePW, &issuePWlength );
issuePW[ issuePWlength ] = '\0';

176

Managing a Certification Authority

cryptGetAttributeString( cryptPKIUser,
CRYPT_CERTINFO_PKIUSER_REVPASSWORD, revPW, &revPWlength );
revPW[ revPWlength ] = '\0';

The CA needs to communicate this information to the user via some out-of-band
means, typically through the use of a PIN mailer or via some other direct
communication means during the certificate sign-up process. Once this information
is communicated, the user can use it to obtain their initial certificate. Any further
certificates are typically obtained by signing the request with the initial certificate or
with subsequently-obtained certificates.
cryptlib uses a standard format for the user ID and password that follows the style
used for software registration codes and serial numbers. The user ID is in the form
XXXXX-XXXXX-XXXXX and the password is in the form XXXXX-XXXXXXXXXX-XXXXX. Characters that might cause confusion (for example O and 0 or 1
a
ndl
)a
r
e
n’
tpr
e
s
e
nt
,
a
n
dt
h
eda
t
ac
on
t
a
i
nsac
h
e
c
k
s
u
m whi
c
hi
sus
e
dt
oc
a
t
c
ht
y
pi
ng
errors when the user enters the information. An example of a user ID and password
is:
user ID = 293XU-NZMSN-DC5J3
password = G3DKZ-DR79M-L6AGY-X6H6X

If the user enters either of these incorrectly, the cryptlib client will return
CRYPT_ERROR_BADDATA when you try to set the user name or password
attribute for the CMP or SCEP client session.

Managing a CA using CMP or SCEP
CMP and SCEP servers that allow you to issue certificates to a CMP or SCEP client
ma
k
eus
eofs
e
s
s
i
onob
j
e
c
t
sa
sde
s
c
r
i
be
di
n“
Secure Sessions”onpa
g
e105, the
f
o
l
l
owi
ngde
s
c
r
i
pt
i
o
na
s
s
u
me
st
ha
ty
ou
’
r
ef
a
mi
l
i
a
rwi
t
ht
heope
r
a
t
i
o
na
n
dus
eo
f
cryptlib session objects. Once the PKI user information has been set up for each user,
t
he
r
ei
s
n’
ta
nything further that needs to be done. Because the CA management
process is completely automated and entirely handled by cryptlib, the CA more or
less runs itself. The only operations that you still need to perform yourself are
periodic ones such as expiring old certificates with CRYPT_CERTACTION_EXPIRE_CERT, issuing CRLs with CRYPT_CERTACTION_ISSUE_CRL
(
a
s
s
umi
ngy
ou’
r
eno
tus
i
ngt
hemu
c
hmor
es
e
ns
i
bl
eo
pt
i
o
nofa
l
l
owi
ngonl
i
neq
ue
r
i
e
s
of the certificate store which is used by the CA), and handling restart recoveries with
CRYPT_CERTACTION_CLEANUP (the manual certificate management operations
a
r
ede
s
c
r
i
be
di
n“
CA Management Operations”o
npa
g
e180). All other operations
are handled for you by the CMP or SCEP server.
Establishing a CMP or SCEP server session requires adding the CA certificate store
and CA server key/certificate as the CRYPT_SESSINFO_KEYSET and CRYPT_SESSINFO_PRIVATEKEY attributes, activating the session, and waiting for
incoming connections. The CMP server session is denoted by CRYPT_SESSION_CMP_SERVER, the SCEP server session is denoted by CRYPT_SESSION_SCEP_SERVER:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser,
CRYPT_SESSION_CMP_SERVER );
/* Add the CA certificate store and CA server key and activate the
session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_KEYSET,
cryptCertStore );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_PRIVATEKEY,
privateKey );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

The same operation in Java or C# is:

Making Certificates Available Online

177

/* Create the session */
int cryptSession = crypt.CreateSession( cryptUser,
crypt.SESSION_CMP_SERVER );
/* Add the CA certificate store and CA server key and activate the
session */
crypt.SetAttribute( cryptSession, crypt.SESSINFO_KEYSET,
cryptCertStore );
crypt.SetAttribute( cryptSession, crypt.SESSINFO_PRIVATEKEY,
privateKey );
crypt.SetAttribute( cryptSession, crypt.SESSINFO_ACTIVE, 1 );

The Visual Basic equivalent is:
' Create the session
cryptCreateSession cryptSession, cryptUser, CRYPT_SESSION_CMP_SERVER
' Add the CA certificate store and CA server key and activate the
' session
cryptSetAttribute cryptSession, CRYPT_SESSINFO_KEYSET, cryptCertStore
cryptSetAttribute cryptSession, CRYPT_SESSINFO_PRIVATEKEY, privateKey
cryptSetAttribute cryptSession, CRYPT_SESSINFO_ACTIVE, 1

Once you activate the session, cryptlib will block until an incoming client connection
arrives, at which point it will negotiate the certificate issue or revocation process with
the client. All checking and certificate processing operations are taken care of by
cryptlib. There is no need for you to perform any further processing operations when
running a CA in this way, although you may want to occasionally perform some of
t
hema
i
nt
e
na
nc
eope
r
a
t
i
onsd
e
s
c
r
i
be
di
n“
Managing a CA Directly”o
npa
g
e179.
If you plan to use the PKIBoot certificate bootstrap mechanism to communicate
trusted certificates to the user, you need to mark the certificates that you want cryptlib
t
os
u
ppl
yt
ot
heus
e
ra
st
r
us
t
e
dc
e
r
t
i
f
i
c
a
t
e
sa
sde
s
c
r
i
be
di
n“
Certificate Trust
Management”onpa
g
e231. At a minimum, you should mark y
ourCA’
sc
e
r
t
i
f
i
c
a
t
e
s
as trusted to ensure that the user will get the CA certificates alongside their own
certificates when they have a certificate issued for them. In addition you can supply
additional certificates (for example ones for certificate status responders or timestamp
servers) to the user by marking them as trusted by the CA.
The cryptlib CMP and SCEP implementations run on top of a certificate store that
implements consistent transactions (as far as the underlying software and hardware
allows it), so that any incomplete CA transaction which is aborted by a software or
ha
r
dwa
r
ef
a
i
l
ur
eorne
t
wor
ke
r
r
orwi
l
lbee
i
t
he
rc
l
e
a
n
l
yr
ol
l
e
dba
c
ki
fi
tha
s
n
’
tbe
e
n
confirmed yet (for example a certificate issue request for which no acknowledgement
was received from the user) or completed if it was confirmed (for example a
revocation request that has been validated by cryptlib). This means that if (for
example) the server on which the CA is running crashes halfway through a revocation
operation, the revocation will be cleanly completed after the server is restarted. This
behaviour may differ from the behaviour exhibited by other CAs, which (depending
on CA policy) may simply abort all incomplete transactions, or may try and complete
some transactions.
In addition to ensuring transactional integrity, cryptlib also enforces certificate status
integrity constraints, which means that if it receives and successfully processes an
update request for a certificate, it will revoke the certificate that was being updated to
prevent two otherwise identical certificates from existing at the same time. As with
the other transaction types, the replacement operation is atomic so that either the new
certificate will cleanly replace the old one, or no overall change will take place.

Making Certificates Available Online
Onc
ey
ou
’
v
ei
s
s
ue
dac
e
r
t
i
f
i
c
a
t
e
,
y
ouc
a
nma
k
ei
ta
v
a
i
l
a
b
l
eonl
i
neus
i
ngas
t
a
nda
r
d
HTTP keyset. This allows users to fetch certificates over the Internet by performing a
standard keyset access. Although the i
nt
e
r
f
a
c
ei
st
oak
e
y
s
e
t
,
i
t
’
sha
n
dl
e
da
sa
cryptlib session of type CRYPT_SESSION_CERTSTORE_SERVER because it
wor
k
swi
t
hav
a
r
i
e
t
yofs
e
s
s
i
o
ni
n
t
e
r
f
a
c
e
sa
n
da
t
t
r
i
b
ut
e
st
ha
ta
r
e
n
’
tn
or
ma
l
l
yus
e
d
with keysets.

178

Managing a Certification Authority
Si
nc
eac
e
r
ts
t
or
es
e
s
s
i
ond
oe
s
n’
tpe
r
f
or
ma
nycrypto operations like the other session
types, all that you need to add before you activate the session is the cert store keyset:
CRYPT_SESSION cryptSession;
/* Create the session */
cryptCreateSession( &cryptSession, cryptUser,
CRYPT_SESSION_CERTSTORE_SERVER );
/* Add the CA certificate store and activate the session */
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_KEYSET,
cryptCertStore );
cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

The Visual Basic equivalent is:
' Create the session
cryptCreateSession cryptSession, cryptUser, _
CRYPT_SESSION_CERTSTORE_SERVER
' Add the CA certificate store and activate the
' session
cryptSetAttribute cryptSession, CRYPT_SESSINFO_KEYSET, cryptCertStore
cryptSetAttribute cryptSession, CRYPT_SESSINFO_ACTIVE, 1

Since the client-side of this session is a standard HTTP keyset, you can use it directly
in crypto operations like signed or encrypted enveloping:
CRYPT_ENVELOPE cryptEnvelope;
int bytesCopied;
cryptCreateEnvelope( &cryptEnvelope, cryptUser, CRYPT_FORMAT_SMIME );
/* Add the encryption keyset and recipient email address */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_KEYSET_ENCRYPT,
cryptKeyset );
cryptSetAttributeString( cryptEnvelope, CRYPT_ENVINFO_RECIPIENT,
"person@company.com", 18 );
/* Add the data size information and data, wrap up the processing, and
pop out the processed data */
cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_DATASIZE,
messageLength );
cryptPushData( cryptEnvelope, message, messageLength, &bytesCopied );
cryptFlushData( cryptEnvelope );
cryptPopData( cryptEnvelope, envelopedData, envelopedDataBufferSize,
&bytesCopied );
cryptDestroyEnvelope( cryptEnvelope );

Although the interface is identical to the standard enveloping interface with a local
keyset, in this case crypt
l
i
bi
sf
e
t
c
h
i
ngt
hec
e
r
t
i
f
i
c
a
t
et
ha
t
’
sr
e
qui
r
e
df
ore
nc
r
y
pt
i
o
n
from the remote CA. Having the keyset available online and managed directly by the
CA avoids requiring each user to manage their own individual store of certificates,
and allows a single consistent certificate collection to be maintained at a central
location.
For both security and performance reasons, you should always open the keyset in
read-only mode and access it as a general certificate keyset (CRYPT_KEYSET_DATABASE, CRYPT_KEYSET_ODBC, or CRYPT_KEYSET_PLUGIN) rather
than a CA certificate store (CRYPT_KEYSET_DATABASE_STORE, CRYPT_KEYSET_ODBC_STORE, or CRYPT_KEYSET_PLUGIN_STORE). cryptlib will
c
he
c
kt
oma
k
es
ur
et
ha
ti
t
’
sar
e
a
d-only standard keyset when you add it to the
session, and retur
naCRYPT_ERROR_PARAM3e
r
r
ori
fi
t
’
so
ft
hei
n
c
or
r
e
c
tt
y
pe
.
For additional security, you can apply standard database security measures to protect
the certificate database against (potentially malicious) access. Some ways of doing
this include using the da
t
a
ba
s
e
’
sREVOKE/
GRANTc
a
pa
b
i
l
i
t
yt
oa
l
l
owon
l
y
SELECT access (read-only, no write or update capability), and accessing the database
as a low-privilege user with only read access. cryptlib will automatically use the
lowest level of access available to perform the task, in this case minimal read-only
access combined with basic SELECT point queries (no views, joins, or other

Managing a CA Directly

179

complexity). Finally, cryptlib both filters its input data and uses parameterised
queries/bound query data to prevent hostile users from inserting malicious escape
sequences into the query.
The CRYPT_SESSION_CERTSTORE_SERVER server type employs cryptlib as
little more than a web interface to a certificate store. Since most databases are webenabled, a simpler option is to use the database itself to provide certificate access to
users — i
t
’
sj
us
tas
t
r
a
i
g
htHTTPq
ue
r
yoft
heda
t
a
ba
s
e
.Thi
sme
a
nst
ha
ty
ouc
a
n
create standalone HTTP certificate store servers using nothing more than the database
engine that you use to store the certificates.

Managing a CA Directly
In addition to the mostly-automated process of running a CA via CMP or SCEP,
cryptlib also lets you manage a CA directly using various certificate management
ope
r
a
t
i
ons
.Thi
spr
oc
e
s
si
s
n
’
ta
sc
onv
e
n
i
e
n
ta
sus
i
ngCMPorSCEPs
i
n
c
ea lot of the
a
ut
o
ma
t
i
o
npr
ov
i
d
e
dbyc
r
y
pt
l
i
b
’
sa
u
t
o
ma
t
e
dCAha
n
dl
i
ngi
sl
os
tbywor
k
i
nga
tt
hi
s
lower level.
A CA issues certificates and certificate revocations in response to requests from
users, so that when an incoming request arrives the first thing you need to do is store
it in the certificate store so that cryptlib can work with it. After that you can use the
CA management functions to convert the request into a certificate or revocation and
optionally return the result of the operation to the user.

Recording Incoming Requests
To store an incoming request you use cryptCAAddItem, which takes the request and
adds it to the store, updating the audit log and performing any other necessary
ma
na
g
e
me
n
top
e
r
a
t
i
o
ns
.Onc
ei
t
’
ss
t
or
e
d,
c
r
y
pt
l
i
bg
e
ne
r
a
t
e
sal
og entry recording the
arrival of the request and can use it to recover the request or any subsequent data such
as certificates created from it even in the event of a system crash or failure, so that no
information will be lost once it has entered the store:
CRYPT_CERTIFICATE cryptCertRequest;
/* Obtain the cert request from the user */
cryptCertRequest = ...;
/* Verify that the request is in order */
/* ... */
/* Add the request to the cert store */
cryptCAAddItem( cryptCertStore, cryptCertRequest );

Once this process has been completed the request has been entered into the store and
will be subject to the CA management operations provided by cryptlib. This step
must be completed before the certificate management process can be applied to the
request, eve
ni
fi
t
’
l
li
mme
di
a
t
e
l
ybeus
e
dt
og
e
ne
r
a
t
eac
e
r
t
i
f
i
c
a
t
eorr
e
v
oc
a
t
i
on,
s
i
nc
e
i
t
’
sne
e
de
dt
oe
ns
ur
et
ha
tt
heope
r
a
t
i
ono
ft
heCAc
a
nber
e
c
ov
e
r
e
da
ndc
ont
i
n
ue
di
n
the event of a software or system failure.

Retrieving Stored Requests
Once a request has been recorded in the store, some time may elapse before it can be
processed, during which time the certificate object that contains the request may be
destroyed. When the certificate is ready for issue, you can recreate the request by
retrieving it from the store using cryptCAGetItem in the same way that you can use
cryptGetPublicKey to obtain a certificate from a standard certificate store:
CRYPT_CERTIFICATE cryptCertRequest;
/* Obtain the cert request from the user */
cryptCertRequest = ...;
/* Verify that the request is in order */
/* ... */

180

Managing a Certification Authority

/* Add the request to the cert store and destroy it */
cryptCAAddItem( cryptCertStore, cryptCertRequest );
cryptDestroyCert( cryptCertRequest );
/* Perform other operations */
/* ... */
/* Recreate the request so that it can be processed */
cryptCAGetItem( cryptCertStore, &cryptCertRequest,
CRYPT_CERTTYPE_REQUEST_CERT, CRYPT_CERTINFO_CRYPT_KEYID_NAME,
name );

Once the request has been recreated, you can subject it to the CA management
process in the usual manner.

CA Management Operations
cryptlib provides a wide variety of CA management operations that include issuing
and revoking certificates and creating CRLs, as well as general management
operations such as clearing up expired certificates and CRL entries. All of these
operations are performed by cryptlib using cryptCACertManagement with no
further input necessary from the user. The general concept of the certificate
management function is:
CRYPT_CERTIFICATE cryptCertificate;
cryptCACertManagement( &cryptCertificate, action, cryptCertStore,
cryptCAKey, cryptCertRequest );

with some of the parameters being optional depending on the type of action being
performed. The certificate management actions that can be performed are:
Cert Management Action Description
CRYPT_CERTACTION_- Remove all expired certificates from the active
EXPIRE_CERT
certificate collection and remove all expired
CRL entries from the active CRL entry
collection in the certificate store.
CRYPT_CERTACTION_- Perform certificate store cleanup/recovery
CLEANUP
actions after a restart (for example a system
crash), processing or deleting any leftover
incomplete actions as appropriate.
CRYPT_CERTACTION_- Issue a certificate by signing a certificate
ISSUE_CERT
request with the given CA key, updating the
certificate store to contain the newly-issued
certificate.
CRYPT_CERTACTION_- Issue a CRL for the CA indicated by the given
ISSUE_CRL
CA key.
CRYPT_CERTACTION_- Revoke the certificate indicated in the
REVOKE_CERT
revocation request. Since submitting the
corresponding revocation request requires
interaction with the CMP protocol this action
c
a
n
’
tb
epe
r
f
or
me
ddi
r
e
c
t
l
yb
uti
si
ni
t
i
a
t
e
di
n
conjunction with CMP.
The first parameter for the function can optionally return the newly-issued certificate
or CRL, if youdo
n’
twa
ntt
odoa
ny
t
hi
ngwi
t
ht
hi
sa
tt
hec
ur
r
e
ntt
i
mey
ouc
a
ns
e
ti
tt
o
null and read it later with cryptGetPublicKey. In all cases cryptlib will carry out the
operations in a safe, all-or-nothing manner that leaves the certificate store in a
consistent state after the operation has completed. This guarantees the reliable
operation of the CA even in the presence of hardware or software failures in the
underlying components.
The details of each type of CA management operation are given in the following
sections.

Managing a CA Directly

181

Issuing and revoking a Certificate
The process of issuing a certificate converts a previously stored certificate request
into a certificate via the certificate store. To issue a certificate, you need to provide a
certificate store, a CA key to use to sign the certificate, and a copy of the (previously
stored) certificate request:
CRYPT_CERTIFICATE cryptCertificate;
cryptCACertManagement( &cryptCertificate, CRYPT_CERTACTION_ISSUE_CERT,
cryptCertStore, cryptCAKey, cryptCertRequest );

Once the operation has completed, the new certificate will be available as the
cryptCertificate value.
Revoking a certificate works in a similar manner, except that it takes a revocation
request rather than a certificate request. Since this operation updates the certificate
store without creating any kind of certificate object, the first parameter is set to null:
cryptCACertManagement( NULL, CRYPT_CERTACTION_REVOKE_CERT,
cryptCertStore, cryptCAKey, cryptRevocationRequest );

This operation requires the use of a revocation request that can only be processed as
pa
r
to
ft
h
eCMPpr
o
t
o
c
ol
,
s
oi
t
’
sn
otp
os
s
i
bl
et
od
i
r
e
c
t
l
ys
ub
mi
tar
e
v
oc
a
t
i
o
nr
e
qu
e
s
t
to the store.

Issuing a CRL
The process of issuing a CRL takes the revocation information held in the certificate
store and turns it into a finished CRL. To issue a CRL, you need to provide a
certificate store and a CA key (specifically, one capable of signing CRLs) to use to
s
i
g
nt
heCRL.Si
nc
et
he
r
e
’
sn
or
e
que
s
ti
nv
o
l
v
e
d,
t
h
er
e
qu
e
s
tpa
r
a
me
t
e
ri
ss
e
tt
o
CRYPT_UNUSED. If you t
r
yt
ous
eaCAk
e
yt
ha
tc
a
n
’
ts
i
g
nCRLs
,
c
r
y
pt
l
i
bwi
l
l
return CRYPT_ERROR_PARAM4 to indicate that the key is invalid for issuing
CRLs:
CRYPT_CERTIFICATE cryptCRL;
cryptCACertManagement( &cryptCRL, CRYPT_CERTACTION_ISSUE_CRL,
cryptCertStore, cryptCAKey, CRYPT_UNUSED );

The CA key must be the one that issued the certificates that are in the CRL (this is a
requirement of the way certificates in CRLs are identified). If you try and use a key
from a different CA, the resulting CRL will either be empty (since no revocation
entries for the other CA will be present) or will contain only entries for the other CA
(if both CAs are sharing the same certificate store, and entries from the other CA are
present in it).

Expiring Certificates
Expiring certificates is a pas
s
i
v
epr
oc
e
s
st
h
a
td
oe
s
n
’
tc
r
e
a
t
eorde
s
t
r
oya
nyc
e
r
t
i
f
i
c
a
t
e
objects, but merely updates the certificate store state information so that expired
certificates are no longer considered active. You can run this as a background or lowpriority operation at periodic intervals to keep the certificate store up to date:
cryptCACertManagement( &cryptCRL, CRYPT_CERTACTION_EXPIRE_CERT,
cryptCertStore, CRYPT_UNUSED, CRYPT_UNUSED );

This will remove any expired certificates from the store and also removes any CRL
entrie
sf
orc
e
r
t
i
f
i
c
a
t
e
st
ha
tha
v
ee
x
pi
r
e
da
ny
wa
y
.De
pe
ndi
ngony
ourCA’
spol
i
c
yon
expiry you can run this frequently to ensure only current certificates and CRL entries
a
r
epr
e
s
e
n
torl
e
s
sf
r
e
que
nt
l
yi
nc
a
s
et
he
r
e
’
ss
o
mer
e
a
s
ont
ok
e
e
pe
x
pi
r
e
dc
e
r
t
i
f
i
c
a
t
e
s
around.

Recovering after a Restart
Some
t
i
me
st
hema
c
hi
neo
nwhi
c
hy
ou
’
r
er
un
ni
ngy
ourCAma
yg
odownduet
o
problems like a hardware failure or a system crash. cryptlib carries out all operations
i
nama
n
ne
rt
h
a
te
ns
ur
e
st
hec
e
r
t
i
f
i
c
a
t
es
t
or
ewon
’
tb
el
e
f
tin an inconsistent state, but
having the machine die in the middle of an update can leave some requests in an

182

Managing a Certification Authority

incomplete state (for example if an incoming request is received and system power is
lost before the corresponding certificate is issued, the unprocessed request will be left
in the certificate store). In order to clean up any leftover requests you can tell cryptlib
to clean up the state of the certificate store by removing or processing any leftover
requests as appropriate:
cryptCACertManagement( &cryptCRL, CRYPT_CERTACTION_CLEANUP,
cryptCertStore, CRYPT_UNUSED, CRYPT_UNUSED );

I
fape
n
di
ngr
e
que
s
tha
s
n’
tbe
e
na
p
pr
ov
e
dy
e
t
,
i
twi
l
lber
o
l
l
e
db
a
c
k
;i
far
e
qu
e
s
th
a
s
be
e
na
p
pr
ov
e
db
utwa
s
n
’
tf
u
l
l
ypr
oc
e
s
s
e
d,
i
twi
l
lbec
o
mp
l
e
t
e
d.
I
ng
e
ne
r
a
li
t
’
sag
ood idea to perform this action when you start your CA (if you shut
i
td
ownf
ora
nyr
e
a
s
on)
,
a
n
dy
ous
h
ou
l
dd
oi
ti
ft
he
r
e
’
sas
y
s
t
e
mf
a
i
l
ur
eorot
he
r
problem that causes the CA to shut down without cleaning up. Note that you should
never perform this opera
t
i
o
nwhi
l
et
heCAi
sr
un
ni
ng
,
s
i
nc
ei
t
’
l
lc
l
e
a
nupa
ny
currently un-processed requests and operations, including ones that may currently be
awaiting processing by the CA.

Creating/Destroying Encryption Contexts

183

Encryption and Decryption
Although envelope, session, and keyset container objects provide an easy way to
wor
kwi
t
he
nc
r
y
pt
e
dda
t
a
,
i
t
’
ss
ome
t
i
me
sd
e
s
i
r
a
b
l
et
owor
ka
tal
owe
rl
e
v
e
l
,
e
i
t
he
r
be
c
a
us
ei
tpr
ov
i
d
e
smor
ec
o
nt
r
olov
e
re
nc
r
y
pt
i
o
npa
r
a
me
t
e
r
sorbe
c
a
us
ei
t
’
smor
e
efficient than the use of the higher-level functions. The objects that you use for
lower-level encryption functionality are encryption contexts. Internally, more
complex objects such as envelope, session, and certificate objects also use encryption
contexts, although these are hidden and not accessible from the outside.
Onc
ey
ou
’
v
eg
e
ne
r
a
t
e
dap
ubl
i
c
/
pr
i
v
a
t
ek
e
ypa
i
r
,
y
oupr
o
ba
bl
ywa
ntt
oc
o
mmu
ni
c
a
t
e
the public key to others. To do this, you need to encode the key components in a
standard form that other applications can understand. The standard form for public
keys is a c
e
r
t
i
f
i
c
a
t
e
,
d
e
s
c
r
i
b
e
di
n“
Certificates and Certificate Management”o
npa
g
e
149.I
fa
l
ly
ouwa
n
tt
odoi
sc
ommun
i
c
a
t
ep
ubl
i
ck
e
yda
t
aa
ndy
oud
on
’
tc
a
r
ea
b
ou
t
the other certificate details, you can use a simplified certificate as described in
“
Simple Certificate Creation”onpa
g
e152. This encodes the key in a universal
certificate format, but without the management overhead of having to deal with
certificates.
Alongside the portable, universal certificate format, there exist a number of nonportable, often proprietary formats that various vendors have invented for encoding
keys. If you want to use one of these non-portable, non-standard formats, you need to
c
on
t
a
c
tt
hev
e
nd
ort
ha
tc
r
e
a
t
e
di
tt
ode
t
e
r
mi
n
et
hef
or
ma
td
e
t
a
i
l
sa
n
dwha
t
’
sr
e
qu
i
r
e
d
to convert a key to and from that format.

Creating/Destroying Encryption Contexts
To create an encryption context, you must specify the user who is to own the object
or CRYPT_UNUSED for the default, normal user, the encryption algorithm, and
optionally the encryption mode you want to use for that context. The available
e
nc
r
y
pt
i
o
na
l
g
or
i
t
h
msa
n
dmo
de
sa
r
eg
i
v
e
ni
n“
Algorithms”onpa
g
e295. For
example, to create and destroy an encryption context for DES you would use the
following code:
CRYPT_CONTEXT cryptContext;
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_DES );
/* Load key, perform en/decryption */
cryptDestroyContext( cryptContext );

The context will use the default encryption mode of CBC, which is the most secure
and efficient encryption mode. If you want to use a different mode, you can set the
c
on
t
e
x
t
’
sCRYPT_CTXI
NFO_MODEa
t
t
r
i
but
et
os
pecify the mode to use. For
example to change the encryption mode used from CBC to CFB you would use:
cryptSetAttribute( cryptContext, CRYPT_CTXINFO_MODE, CRYPT_MODE_CFB );

I
ng
e
ne
r
a
ly
ous
h
ou
l
d
n’
tne
e
dt
oc
ha
ng
et
hee
nc
r
y
pt
i
o
nmo
de
,
t
heot
he
rc
r
y
pt
l
i
b
functions will automatically handle the mode choice for you. Public-key, hash, and
MACc
on
t
e
x
t
swor
ki
nt
hes
a
mewa
y
,
e
x
c
e
ptt
ha
tt
he
ydo
n
’
th
a
v
edi
f
f
e
r
e
n
tmode
sof
us
es
ot
h
eCRYPT_CTXI
NFO_MODEa
t
t
r
i
b
ut
ei
s
n
’
tpr
e
s
e
ntf
ort
h
e
s
et
y
pe
so
f
contexts. The availability of certain algorithms and encryption modes in cryptlib
does not mean that their use is recommended. Some are only present because they
are needed for certain protocols or required by some standards.
Note that the CRYPT_CONTEXT is passed to cryptCreateContext by reference, as
cryptCreateContext modifies it when it creates the encryption context. In almost all
other cryptlib routines, CRYPT_CONTEXT is passed by value. The contexts that
will be created are standard cryptlib contexts, to create a context which is handled via
a crypto device such as a smart card or Fortezza card, you should use
cryptDeviceCreateContext, which tells cryptlib to create a context in a crypto

184

Encryption and Decryption
de
v
i
c
e
.Theus
eo
fc
r
y
pt
ode
v
i
c
e
si
se
x
pl
a
i
ne
di
n“
Encryption Devices and Modules”
on page 265.
cryptDestroyContext has a generic equivalent function cryptDestroyObject that
takes a CRYPT_HANDLE parameter instead of a CRYPT_CONTEXT. This is
intended for use with objects that are referred to using generic handles, but can also
be used to specifically destroy encryption contexts — c
r
y
p
t
l
i
b’
sobj
e
c
tma
na
g
e
me
n
t
routines will automatically sort out what to do with the handle or object.

Generating a Key into an Encryption Context
Onc
ey
ou
’
v
ec
reated an encryption context, the next step is to generate a key into it.
These keys will typically be either one-off session keys that are discarded after use, or
long-term storage keys that are used to protect fixed data such as files or private keys.
You can generate a key with cryptGenerateKey:
cryptGenerateKey( cryptContext );

which will generate a key of a size which is appropriate for the encryption algorithm.
If you want to generate a key of a particular length, you can set the CRYPT_CTXINFO_KEYSIZE attribute before calling cryptGenerateKey. For example to
generate a 256-bit (32-byte) key you would use:
cryptSetAttribute( cryptContext, CRYPT_CTXINFO_KEYSIZE, 256 / 8 );
cryptGenerateKey( cryptContext );

Keys generated by cryptlib are useful when used with cryptExportKey/
cryptImportKey. Since cryptExportKey usually encrypts the generated key using
public-k
e
ye
nc
r
y
pt
i
o
n,
y
ous
h
oul
dn
’
tma
k
ei
tt
o
ol
o
ngori
t
’
l
lbet
oobi
gt
obe
e
nc
r
y
pt
e
d.Unl
e
s
st
h
e
r
e
’
sas
pe
c
i
f
i
cr
e
a
s
o
nf
orc
ho
os
i
ngt
hek
e
yl
e
ng
t
h you should
use the cryptGenerateKey function and let cryptlib choose the correct key length for
you.
Theo
nl
yt
i
mewhe
ny
ouma
yne
e
dt
oe
x
p
l
i
c
i
t
l
ys
pe
c
i
f
yak
e
yl
e
ng
t
hi
swhe
ny
ou’
r
e
using very short (in the vicinity of 512 bits) public keys to export Blowfish, RC2,
RC4,
orRC5k
e
y
s
.I
nt
hi
sc
a
s
et
hep
ub
l
i
ck
e
yi
s
n
’
tl
a
r
g
ee
noug
ht
oe
x
p
or
tt
h
ef
ul
l
length keys for these algorithms, and cryptExportKey will return the error code
CRYPT_ERROR_OVERFLOW t
oi
nd
i
c
a
t
et
h
a
tt
he
r
e
’
st
o
omuc
hda
t
at
oe
x
p
or
t
.The
solution is to either specify a shorter key length using the CRYPT_CTXINFO_KEYSIZE attribute or, preferably, to use a longer public key. This is only a problem
with very short public keys, when using the minimum recommended public key size
of 1024 bits this situation will never occur.
Calling cryptGenerateKey only makes sense for conventional, public-key, or MAC
contexts and will return the error code CRYPT_ERROR_NOTAVAIL for a hash
context to indicate that this operation is not available for hash algorithms. The
generation of public/private key pairs has special requirements and is covered in
“
Key Generation”o
npa
g
e131.
To summarise the steps so far, you can set up an encryption context in its simplest
f
or
ms
ot
ha
ti
t
’
sr
e
a
dyt
oe
nc
r
y
ptda
t
awi
t
h
:
CRYPT_CONTEXT cryptContext;
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_3DES );
cryptGenerateKey( cryptContext );
/* Encrypt data */
cryptDestroyContext( cryptContext );

Once a key is generated i
nt
oac
on
t
e
x
t
,
y
ouc
a
n’
tl
o
a
dorg
e
ne
r
a
t
eane
wk
e
yov
e
rt
he
top of it or change the encryption mode (for conventional encryption contexts). If
you try to do this, cryptlib will return CRYPT_ERROR_INITED to indicate that a
key is already loaded into the context.

Deriving a Key into an Encryption Context

185

Deriving a Key into an Encryption Context
Sometimes you will need to obtain a fixed-format encryption key for a context from a
variable-length password or passphrase, or from any generic keying material. You
can do this by deriving a key into a context rather than loading it directly. Deriving a
key converts arbitrary-format keying information into the particular form required by
the context, as well as providing extra protection against password-guessing attacks
and other attacks that might take a
dv
a
nt
a
g
eofk
nowl
e
dg
eoft
hek
e
y
i
ngma
t
e
r
i
a
l
s
’
format.
The key derivation process takes two sets of input data, the keying material itself
(typically a password), and a salt value which is combined with the password to
ensure that the key is different each time (so even if you reuse the same password
multiple times, the key obtained from it will change each time). This ensures that
even if one password-based key is compromised, all the others remain secure.
The salt attribute is identified by CRYPT_CTXINFO_KEYING_SALT and ranges in
length from 64 bits (8 bytes) up to CRYPT_MAX_HASHSIZE. Using an 8-byte salt
is a good choice. The keying information attribute is identified by CRYPT_CTXINFO_KEYING_VALUE and can be of any length. To derive a key into a
context you would use:
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_KEYING_SALT,
salt, saltLength );
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_KEYING_VALUE,
passPhrase, passPhraseLength );

which takes the supplied passphrase and salt and converts them into an encryption
key in a format suitable for use with the encryption context. Use of the key
derivation capability is strongly recommended over loading keys directly into an
encryption context by setting the CRYPT_CTXINFO_KEY attribute since this often
requires intimate knowledge of algorithm details such as how keys of different
lengths are handled, how key bits are used, special considerations for key material,
and so on.
Note that you have to set a salt value before you set the keying information attribute.
I
fy
oudo
n
’
ts
u
pp
l
yas
a
l
t
,
c
r
y
pt
l
i
bwi
l
lr
e
t
ur
nCRYPT_ERROR_NOTI
NI
TEDwhe
n
y
out
r
yt
os
up
pl
yt
hek
e
y
i
ngi
nf
or
ma
t
i
ont
oi
ndi
c
a
t
et
h
a
tt
h
es
a
l
th
a
s
n
’
tb
e
e
ns
e
ty
e
t
.
I
fy
oudo
n
’
twa
ntt
oma
na
g
eauni
qu
es
a
l
tv
a
l
uep
e
rk
e
y
,youc
a
ns
e
tthe salt to a fixed
value (for example 64 bits of zeroes), although this is strongly discouraged since it
means each use of the password will produce the same encryption key.
By default the key derivation process will repeatedly hash the input salt and keying
information with the HMAC-SHA1 MAC function to generate the key, and will
iterate the hashing process 500 times to make a passphrase-guessing attack more
difficult2. If you want to change these values you can set the CRYPT_CTXINFO_KEYING_ALGO and CRYPT_CTXINFO_KEYING_ITERATIONS attributes for
the context before setting the salt and keying information attributes. For example to
change the number of iterations to 1000 for extra security before setting the salt and
key you would use:
cryptSetAttribute( cryptContext, CRYPT_CTXINFO_KEYING_ITERATIONS,
1000 );
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_KEYING_SALT,
salt, saltLength );
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_KEYING_VALUE,
passPhrase, passPhraseLength );

cryptlib will then use this value when deriving the key. You can also change the
default hash algorithm and iteration count using the cryptlib configuration options
CRYPT_OPTION_KEYING_ALGO and CRYPT_OPTION_KEYING_I
TERATI
ONSa
se
x
pl
a
i
ne
di
n“
Working with Configuration Options”o
npa
g
e274.

It actually does a lot more than just hashing the passphrase, including performing processing steps designed to
defeat various sophisticated attacks on the key-hashing process.

186

Encryption and Decryption

To summarise the steps so far, you can set up an encryption context in its simplest
f
or
ms
ot
ha
ti
t
’
sr
e
a
dyt
oe
nc
r
y
ptda
t
awi
t
h
:
CRYPT_CONTEXT cryptContext;
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_3DES );
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_KEYING_SALT,
salt, saltLength );
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_KEYING_VALUE,
passPhrase, strlen( passPhrase ) );
/* Encrypt data */
cryptDestroyContext( cryptContext );

Since public-key encryption uses a different type of key than other context types, you
c
a
n
’
td
e
r
i
v
eak
e
yi
nt
oap
ub
l
i
corpr
i
v
a
t
ek
e
yc
ont
e
x
t
.
Onc
eak
e
yi
sde
r
i
v
e
di
n
t
oac
ont
e
x
t
,
y
ouc
a
n
’
tl
oa
dorg
e
ne
r
a
t
eane
wk
e
yover the
top of it or change the encryption mode (for conventional encryption contexts). If
you try to do this, cryptlib will return CRYPT_ERROR_INITED to indicate that a
key is already loaded into the context.

Loading a Keys into an Encryption Context
If necessary you can also manually load a raw key into an encryption context by
setting the CRYPT_CTXINFO_KEY attribute. For example to load a raw 128-bit
k
e
y“
0123
45
67
89ABCDEF”i
nt
oa
nI
DEAc
onv
e
n
t
i
ona
le
n
c
r
y
pt
i
o
nc
o
nt
e
x
ty
o
u
would use:
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_KEY,
"0123456789ABCDEF", 16 );

Unless you need to perform low-level key management yourself, you should avoid
loading keys directly in this manner. The previous key load should really have been
done by setting the CRYPT_CTXINFO_KEYING_SALT and CRYPT_CTXINFO_KEYING_VALUE attributes to derive the key into the context.
For public-key encryption a key will typically have a number of components so you
c
a
n
’
ts
e
tt
hek
e
ydi
r
e
c
t
l
y
.Mo
r
ei
nf
or
ma
t
i
ononwor
k
i
ngwi
t
hCRYPT_
PKCI
NFO
da
t
as
t
r
uc
t
ur
e
si
sg
i
v
e
ni
n“
Loading Public/Private Keys”o
npa
g
e187.
Onc
eak
e
yi
sl
oa
de
di
nt
oac
o
nt
e
x
t
,
y
ouc
a
n
’
tl
oa
dorg
e
ne
r
a
t
eane
wk
e
yov
e
rt
het
o
p
of it or change the encryption mode (for conventional encryption contexts). If you try
to do this, cryptlib will return CRYPT_ERROR_INITED to indicate that a key is
already loaded into the context.
If you need to reserve space for conventional and public/private keys, you can use the
CRYPT_MAX_KEYSIZE and CRYPT_MAX_PKCSIZE defines to determine the
mount of memory you need. No key used by cryptlib will ever need more storage
than the settings given in these defines. Note that the CRYPT_MAX_PKCSIZE
value specifies the maximum size of an individual key component. Since
public/private keys are usually composed of a number of components the overall size
is larger than this.

Working with Initialisation Vectors
For conventional-key encryption contexts you can also load an initialisation vector
(IV) into the context if the encryption mode being used supports an IV, although
whe
ny
ou
’
r
eus
i
ngac
ont
e
x
tt
oe
nc
r
y
ptda
t
ay
ouc
a
nl
e
a
v
et
hi
st
oc
r
y
p
t
l
i
bt
ope
r
f
or
m
automatically when you call cryptEncrypt for the first time. IVs are required for the
CBC, CFB, and OFB encryption modes. To load an IV you set the
CRYPT_CTXINFO_IV attribute:
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_IV, iv, ivSize );

To retrieve the IV that you have loaded or that has been generated for you by cryptlib
you read the value of the attribute:

Loading Public/Private Keys

187

unsigned char iv[ CRYPT_MAX_IVSIZE ];
int ivSize;
cryptGetAttributeString( cryptContext, CRYPT_CTXINFO_IV, iv,
&ivSize );

Trying to get or set the value of this attribute will return the error code CRYPT_ERROR_NOTAVAIL for a hash, MAC, or public key encryption context or
c
onv
e
nt
i
on
a
le
n
c
r
y
pt
i
onc
on
t
e
x
twi
t
ha
ne
nc
r
y
pt
i
o
nmodet
ha
td
oe
s
n’
tus
ea
nI
Vt
o
indicate that these operations are not available for this type of context.
If you need to reserve space for IVs, you can use the CRYPT_MAX_IVSIZE define
to determine the mount of memory you need. No IV used by cryptlib will ever need
more storage than the setting given in this define.

Loading Public/Private Keys
Si
nc
ep
ub
l
i
c
/
pr
i
v
a
t
ek
e
y
st
y
pi
c
a
l
l
yha
v
emu
l
t
i
pl
ec
o
mp
on
e
nt
s
,
y
ouc
a
n’
tset them
directly as a CRYPT_CTXINFO_KEY attribute. Instead, you load them into a
CRYPT_PKCINFO structure and then set that as a CRYPT_CTXINFO_KEY_COMPONENTS attribute. There are several CRYPT_PKCINFO structures, one for
each class of public-key algorithm supported by cryptlib. The CRYPT_PKCINFO
s
t
r
uc
t
ur
e
sa
r
ede
s
c
r
i
be
di
n“
CRYPT_PKCINFO_xxx Structures”onpa
g
e313.
As with public/private key pair generation, you need to set the CRYPT_CTXINFO_LABEL attribute to a unique value used to identify the key before you can load a key
value. If you try to load a key into a context without first setting the key label,
c
r
y
pt
l
i
bwi
l
lr
e
t
ur
nCRYPT_
ERROR_NOTI
NI
TEDt
oi
nd
i
c
a
t
et
ha
tt
hel
a
be
lha
s
n
’
t
been set yet.
Onc
eak
e
yi
sl
oa
de
di
nt
oac
o
nt
e
x
t
,
y
ouc
a
n
’
tl
oa
dorg
e
ne
r
a
t
eane
wk
e
yov
e
rt
het
o
p
of it. If you try to do this, cryptlib will return CRYPT_ERROR_INITED to indicate
that a key is already loaded into the context.
If you need to reserve space for public/private key components, you can use the
CRYPT_MAX_PKCSIZE define to determine the mount of memory you need. No
key used by cryptlib will ever need more storage than the settings given in these
defines. Note that the CRYPT_MAX_PKCSIZE value specifies the maximum size
of an individual key component, Since public/private keys are usually composed of a
number of components the overall size is larger than this.
Unless you explicitly need to load raw public/private key components into an
encryption context, you should avoid loading keys directly in this manner and should
instead either generate the key inside the context or use the key database access
f
u
nc
t
i
o
nst
ol
oa
dt
h
ek
e
yf
ory
ou.The
s
eo
pe
r
a
t
i
o
nsa
r
ede
s
c
r
i
be
di
n“
Key
Generation”on page 131 a
n
d“
Key Storage”onpa
g
e133.
In addition, because the public key component manipulation functions need to
perform low-level access to the CRYPT_PKCINFO data structures, they are
i
mpl
e
me
nt
e
da
sCpr
e
pr
oc
e
s
s
orma
c
r
osa
n
dc
a
n
’
tbet
r
a
ns
l
a
t
e
di
nt
oot
he
rl
a
ng
ua
g
e
s
s
uc
ha
sVi
s
u
a
lBa
s
i
ca
n
dDe
l
phi
.I
fy
ou
’
r
epr
og
r
a
mmi
ngi
nal
a
ng
ua
g
eot
he
rt
ha
nC
or C++, you should always use key generation or keyset objects to load and store
keys rather than trying to load them using CRYPT_CTXINFO_KEY_COMPONENTS.

Loading Multibyte Integers
The multibyte integer strings that make up public and private keys are stored in bigendian format with the most significant digit first:
0000000000000000000000000000000xxxxxxxxxxxxxxxxxxx

For example the number 123456789 would be stored in big-endian format as:
00000000000000000000000000000000000000000123456789

(
wi
t
ht
her
e
ma
i
n
de
ro
ft
h
ev
a
l
uepa
dd
e
dwi
t
hz
e
r
oe
s
)
.I
npr
a
c
t
i
c
et
h
en
umbe
r
swon
’
t
be stored with excessively long precision as they are in the above examples, so

188

Encryption and Decryption

instead of being stored with 50 digits of precision of which 41 bytes contain zero
padding, they would be stored with 9 digits of precision:
123456789

A multibyte integer therefore consists of two parameters, the data itself and the
precision to which it is stored, specified in bits. When you load multibyte integer
components into a CRYPT_PKCINFO structure you need to specify both of these
parameters.
Before you can use the CRYPT_PKCINFO structure, you need to initialise it with
cryptInitComponents(), which takes as parameters a pointer to the
CRYPT_PKCINFO structure and the type of the key, either CRYPT_KEYTYPE_PRIVATE or CRYPT_KEYTYPE_PUBLIC:
CRYPT_PKCINFO_RSA rsaKey;
cryptInitComponents( &rsaKey, CRYPT_KEYTYPE_PRIVATE );

Now you can load the multibyte integer strings by using cryptSetComponent(),
specifying a pointer to the value to be loaded, the multibyte integer data, and the
integer length in bits:
cryptSetComponent( ( &rsaKey )->n, modulus, 1024 );
cryptSetComponent( ( &rsaKey )->e, pubExponent, 17 );
cryptSetComponent( ( &rsaKey )->d, privExponent, 1024 );

Since cryptSetComponent() takes as parameter a pointer to the value to be
l
oa
de
d,
i
t
’
sne
c
e
s
s
a
r
yt
opa
s
si
nt
hea
d
dr
e
s
sa
sshown above when the
CRYPT_PKCI
NFOs
t
r
uc
t
ur
ei
sde
c
l
a
r
e
ds
t
a
t
i
c
a
l
l
y
.I
fi
t
’
sd
y
na
mi
c
a
l
l
ya
l
l
oc
a
t
e
da
si
n
t
hee
x
a
mp
l
eb
e
l
ow,
t
h
i
se
x
t
r
as
t
e
pi
s
n’
tne
c
e
s
s
a
r
y
.
Once all the parameters are set up, you can use the result as the CRYPT_CTXINFO_KEY_COMPONENTS ase
xpl
a
i
ne
da
b
ov
e
.Onc
ey
ou’
v
ef
i
ni
s
h
e
dwor
k
i
ngwi
t
ht
he
CRYPT_PKCINFO information, use cryptDestroyComponents to destroy the
information:
cryptDestroyComponents( &rsaKey );

The Diffie-Hellman, DSA, and Elgamal algorithms share the same key format and all
use the CRYPT_PKCINFO_DLP structure to store their key components. DLP is
short for Discrete Logarithm Problem, the common underlying mathematical
operation for the three cryptosystems.
When loading key components, cryptlib performs a validity check on the data to
detect invalid or suspicious key values. These can be used to compromise the
security of the key, for example to leak the private key in signatures made with it. If
cryptlib detects suspicious key components, it will return CRYPT_ERROR_PARAM3 to indicate that the key components are invalid.
To summarise the steps so far, you would load a public key into a DSA context with:
CRYPT_CONTEXT cryptContext;
CRYPT_PKCINFO_DLP *dlpKey;
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_DSA );
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_LABEL, "DSA key",
7 );
dlpKey = malloc( sizeof( CRYPT_PKCINFO_DLP ) );
cryptInitComponents( dlpKey, CRYPT_KEYTYPE_PUBLIC );
cryptSetComponent( dlpKey->p, ... );
cryptSetComponent( dlpKey->g, ... );
cryptSetComponent( dlpKey->q, ... );
cryptSetComponent( dlpKey->y, ... );
cryptSetAttributeString ( cryptContext, CRYPT_CTXINFO_KEY_COMPONENTS,
dlpKey, sizeof( CRYPT_PKCINFO_DLP ) );
cryptDestroyComponents( dlpKey );

The context is now ready to be used to verify a DSA signature on a piece of data. If
you wanted to load a DSA private key (which consists of one extra component), you
would add:

Querying Encryption Contexts

189

cryptSetComponent( dlpKey->x, ... );

after the y component is loaded. This context can then be used to sign a piece of data.

Querying Encryption Contexts
A context has a number of attributes whose values you can get to obtain information
about it. These attributes contain details such as the algorithm type and name, the key
size (if appropriate), the key label (if this has been set), and various other details. The
information attributes are:
Value

Type Description

CRYPT_CTXINFO_ALGO
CRYPT_CTXINFO_MODE

Algorithm and mode

CRYPT_CTXINFO_BLOCKSIZE

Cipher block size in bytes

CRYPT_CTXINFO_IVSIZE

Cipher IV size in bytes

CRYPT_CTXINFO_KEYING_ALGO
CRYPT_CTXINFO_KEYING_ITERATIONS
CRYPT_CTXINFO_KEYING_SALT

N/S The algorithm and number of
iterations used to transform a
user-supplied key or password
into an algorithm-specific key for
the context, and the salt value
used in the transformation process

CRYPT_CTXINFO_KEYSIZE

Key size in bytes

CRYPT_CTXINFO_LABEL

Key label

CRYPT_CTXINFO_NAME_ALGO
CRYPT_CTXINFO_NAME_MODE

Algorithm and mode name

For example to obtain the algorithm and mode used by an encryption context, you
would use:
CRYPT_ALGO_TYPE cryptAlgo;
CRYPT_MODE_TYPE cryptMode;
cryptGetAttribute( cryptContext, CRYPT_CTXINFO_ALGO, &cryptAlgo );
cryptGetAttribute( cryptContext, CRYPT_CTXINFO_MODE, &cryptMode );

Although these attributes are listed as context attributes, they also apply to anything
else that can act as a context action object, for example you can obtain algorithm,
mode, and key size values from a certificate since it can be used to encrypt or sign
just like a context:
CRYPT_ALGO_TYPE cryptAlgo;
CRYPT_MODE_TYPE cryptMode;
cryptGetAttribute( cryptCertificate, CRYPT_CTXINFO_ALGO, &cryptAlgo );
cryptGetAttribute( cryptCertificate, CRYPT_CTXINFO_MODE, &cryptMode );

If any of the user-s
up
pl
i
e
da
t
t
r
i
but
e
sha
v
e
n
’
tbe
e
ns
e
ta
ndy
out
r
yt
or
e
a
dt
he
i
rv
a
l
ue
,
cryptlib will return CRYPT_ERROR_NOTINITED.

Using Encryption Contexts to Process Data
To encrypt or decrypt a block of data using an encryption context action object you
use:
cryptEncrypt( cryptContext, buffer, length );

and:
cryptDecrypt( cryptContext, buffer, length );

The data is encrypted in place, so that plaintext data is replaced by encrypted data and
v
i
c
ev
e
r
s
a
.I
ft
hee
nc
r
y
pt
i
o
nc
on
t
e
x
td
oe
s
n
’
ts
up
por
tt
heo
pe
r
a
t
i
o
ny
oua
r
et
r
y
i
ngt
o
perform (for example calling cryptEncrypt with a DSA public key), the function will
return CRYPT_ERROR_NOTAVAIL to indicate that this functionality is not

190

Encryption and Decryption
a
v
a
i
l
a
bl
e
.I
ft
hek
e
yl
oa
de
di
nt
oa
ne
n
c
r
y
pt
i
onc
on
t
e
x
tdo
e
s
n’
ta
l
l
owt
heope
r
a
t
i
on
you are trying to perform (for example calling cryptDecrypt with an encrypt-only
key), the function will return CRYPT_ERROR_PERMISSION to indicate that the
c
on
t
e
x
td
oe
s
n
’
tha
v
et
h
er
e
qu
i
r
e
dk
e
ype
r
mi
s
s
i
o
nst
op
e
r
f
or
mt
her
e
q
ue
s
t
e
do
pe
r
a
t
i
o
n.

Conventional Encryption
I
fy
ou’
r
eus
i
ngabl
oc
kc
i
phe
ri
nECBorCBCmod
e
,
t
hee
n
c
r
y
pt
e
dd
a
t
a length must
be a multiple of the block size. If the encrypted data length is not a multiple of the
block size, the function will return CRYPT_ERROR_PARAM3 to indicate that the
length is invalid. To encrypt a byte at a time you should use a stream encryption
mode such as CFB or OFB, or better yet use an envelope which avoids the need to
handle algorithm-specific details.
I
fa
nI
Vi
sr
e
qui
r
e
df
ort
hed
e
c
r
y
pt
i
o
na
n
dy
ouh
a
v
e
n’
tl
oa
d
e
do
nei
n
t
ot
hec
on
t
e
x
tby
setting the CRYPT_CTXINFO_IV attribute, cryptDecrypt will return CRYPT_ERROR_NOTINITED to indicate that you need to load an IV before you can decrypt
t
hed
a
t
a
.I
ft
hef
i
r
s
t8by
t
e
so
fde
c
r
y
p
t
e
dda
t
aa
r
ec
or
r
up
t
e
dt
he
ny
o
uha
v
e
n
’
ts
e
tu
p
the IV properly for the decryption. More information on setting up IVs is given in
“
Working with Initialisation Vectors”o
npa
g
e186. The general concept behind
using IVs (in this case with automatic IV generation) is:
unsigned char iv[ CRYPT_MAX_IVSIZE ];
int ivSize;
/* Encrypt data */
cryptEncrypt( cryptContext, data, dataLength );
cryptGetAttributeString( cryptContext, CRYPT_CTXINFO_IV, iv, &ivSize
);
/* Communicate the encrypted data and IV to the recipient */
/* ... */
/* Decrypt data */
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_IV, iv, ivSize );
cryptDecrypt( cryptContext, data, dataLength )

Once an encryption context is set up, it can only be used for processing a single data
stream in an operation such as encrypting data, decrypting data, or hashing a
me
s
s
a
g
e
.Ac
ont
e
x
tc
a
n
’
tber
e
us
e
dt
oe
n
c
r
y
ptas
e
c
o
ndme
s
s
a
g
ea
f
t
e
rt
hef
i
r
s
to
ne
has been encrypted, or to decrypt data after having encrypted data. This is because
the internal state of the context is determined by the operation being performed with
it, and performing two different operations with the same context causes the state
from the first operation to affect the second operation. For example if you use an
encryption context to encrypt two different files, cryptlib will see a single continuous
da
t
as
t
r
e
a
m(
s
i
nc
ei
td
oe
s
n
’
tk
noworc
a
r
ea
b
ou
tt
h
es
t
r
uc
t
ur
eoft
hed
a
t
abe
i
ng
encrypted). As a result the second file is treated as a continuation of the first one, and
c
a
n
’
tb
ede
c
r
y
p
t
e
dunl
e
s
st
hec
on
t
e
x
ti
sus
e
dt
ode
c
r
y
ptt
hef
i
r
s
tf
i
l
ebe
f
or
edecrypting
the second one. Because of this you should always create a new encryption context
for each discrete data stream you will be processing, and never reuse contexts to
pe
r
f
or
md
i
f
f
e
r
e
ntope
r
a
t
i
ons
.Theon
ee
x
c
e
p
t
i
o
nt
ot
h
i
sr
ul
ei
swhe
ny
ou
’
r
eus
i
ng
c
r
y
pt
l
i
be
nv
e
l
op
e
s(
de
s
c
r
i
b
e
di
n“
Data Enveloping”onpa
g
e60), where you can push
a single encryption context into as many envelopes as you like. This is because an
envelope takes its own copy of the encryption context, leaving the original
untouched.
I
npr
a
c
t
i
c
et
hi
si
s
n
’
ts
t
r
i
c
t
l
ya
c
c
ur
a
t
e
,
y
ouc
a
ne
nc
r
y
ptmu
l
t
i
pl
ei
n
de
p
e
n
de
n
tda
t
a
streams with a single context by loading a new IV for each new stream using the
CRYPT_CTXINFO_IV attribute:
/* Set an IV and encrypt data */
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_IV, iv1,
iv1Length );
cryptEncrypt( cryptContext, data1, data1Length );

Using Encryption Contexts to Process Data

191

/* Set a new IV and encrypt more data */
cryptSetAttributeString( cryptContext, CRYPT_CTXINFO_IV, iv2,
iv2Length );
cryptEncrypt( cryptContext, data2, data2Length );

I
fy
oudo
n
’
tu
nde
r
s
t
a
n
dh
owt
hi
swou
l
dwor
kt
he
ni
t
’
spr
o
b
a
bl
ybe
s
tt
ous
eane
w
context for each data stream.

Public-key Encryption
The public-key algorithms encrypt a single block of data equal in length to the size of
the public key being used. For example if you are using a 1024-bit public key then
the length of the data to be encrypted should be 128 bytes. If the encrypted data
l
e
ng
t
hi
s
n
’
tt
hes
a
mea
st
hek
e
ys
i
z
e
,
t
hef
un
c
t
i
o
nwi
l
l return CRYPT_ERROR_PARAM3 to indicate that the length is invalid. Preparation of the block of data to be
encrypted requires special care and is covered in appropriate security standards. If
c
r
y
pt
l
i
bde
t
e
c
t
st
ha
ti
t
’
sbe
i
ngpa
s
s
e
di
nc
or
r
e
c
t
l
y
-formatted input data, it will return
CRYPT_ERROR_BADDATA to indicate that the data being passed to the
en/decryption function is invalid. In general you should use high-level functions such
as cryptExportKey/cryptImportKey and cryptCreateSignature/
cryptCheckSignature rather than cryptEncrypt and cryptDecrypt when working
with public-key algorithms.
I
fy
ou’
r
eus
i
ngapub
l
i
corpr
i
v
a
t
ek
e
yc
ont
e
x
twhi
c
hi
st
i
e
dt
oac
e
r
t
i
f
i
c
a
t
eorc
r
y
pt
o
device, the direct use of cryptEncrypt and cryptDecrypt could be used to bypass
security constraints placed on the context (for example by changing the data
formatting used with an encryption-o
nl
yRSApr
i
v
a
t
ek
e
yc
ont
e
x
ti
t
’
spos
s
i
b
l
et
o
misuse it to generate signatures even if the context is specifically intended for nonsignature use). Because of this, if a context is tied to a certificate or a crypto device,
i
tc
a
n’
tbeus
e
dd
i
r
e
c
t
l
ywi
t
ht
he
s
el
ow-level functions but only with a higher-level
function like cryptCreateSignature or with the enveloping code, which guarantee
that a co
nt
e
x
tc
a
n
’
tb
emi
s
us
e
df
orad
i
s
a
l
l
owe
dpur
pos
e
.I
fy
out
r
yt
ous
ea
constrained context of this type directly, the function will return CRYPT_ERROR_PERMI
SSI
ONt
oi
nd
i
c
a
t
et
ha
tt
hec
on
t
e
x
td
oe
s
n
’
tha
v
et
h
er
e
qui
r
e
dpe
r
mi
s
s
i
o
nst
o
perform the requested operation.

Hashing
Ha
s
ha
ndMACa
l
g
or
i
t
h
msd
on
’
ta
c
t
u
a
l
l
ye
n
c
r
y
ptt
h
eda
t
abe
i
ngha
s
he
da
n
dc
a
nbe
called via cryptEncrypt or cryptDecrypt. They require a final call with the length
set to 0 as a courtesy call to indicate to the hash or MAC function that this is the last
data block and that the function should take whatever special action is necessary for
this case:
cryptEncrypt( hashContext, buffer, length );
cryptEncrypt( hashContext, buffer, 0 );

If you call cryptEncrypt or cryptDecrypt after making the final call with the length
set to 0, the function will return CRYPT_ERROR_COMPLETE to indicate that the
hashing has completed and cannot be continued. Once the hashing is complete, the
hash value is made available as the CRYPT_CTXINFO_HASHVALUE attribute that
you can read in the usual manner:
unsigned char hash[ CRYPT_MAX_HASHSIZE ];
int hashLength;
cryptGetAttributeString( cryptContext, CRYPT_CTXINFO_HASHVALUE, hash,
&hashLength );

You can reset a hash or MAC context by deleting the CRYPT_CERTINFO_HASHVALUE attribute, which allows you to reuse the context to generate another
hash or MAC value. Reusing a context in this manner avoids the overhead of
creating a context, and in the case of a MAC context the somewhat complex key
processing which is required when the context is first used:

192

Encryption and Decryption

unsigned char hash1[ CRYPT_MAX_HASHSIZE ];
unsigned char hash2[ CRYPT_MAX_HASHSIZE ];
int hash1Length, hash2Length;
/* Hash or MAC data */
/* ... */
cryptGetAttributeString( cryptContext, CRYPT_CTXINFO_HASHVALUE, hash1,
&hash1Length );
/* Delete the attribute to allow the context to be reused */
cryptDeleteAttribute( cryptContext, CRYPT_CTXINFO_HASHVALUE );
/* Hash or MAC more data */
/* ... */
cryptGetAttributeString( cryptContext, CRYPT_CTXINFO_HASHVALUE, hash2,
&hash2Length );

Exporting a Key

193

Exchanging Keys
Although you can encrypt/decrypt or MAC data with an encryption context, the key
y
ou’
r
eus
i
ngi
sl
oc
k
e
di
ns
i
d
et
hec
o
nt
e
x
ta
nd(
i
fy
ouus
e
dcryptGenerateKey to
c
r
e
a
t
ei
t
)won’
tbek
n
ownt
oy
ouort
hepe
r
s
ony
o
u’
r
et
r
y
i
n
gt
oc
o
mmun
icate with.
To share the key with another party, you need to export it from the context in a secure
manner and the other party needs to import it into an encryption context of their own.
Be
c
a
us
et
h
ek
e
yi
sav
e
r
ys
e
ns
i
t
i
v
ea
n
dv
a
l
u
a
bl
er
e
s
our
c
e
,
y
ouc
a
n
’
t just read it out of
the context, but need to take special steps to protect the key once it leaves the context.
This is taken care of by the key export/import functions.
These functions deal only with the export and import of keys for conventional
encryption or MAC contexts. Public/private keys have specialised requirements and
c
a
n
’
tb
ee
x
por
t
e
dd
i
r
e
c
t
l
yi
nt
hes
a
mema
n
ne
ra
sc
o
nv
e
nt
i
o
na
le
nc
r
y
pt
i
onorMAC
keys. Public keys, which are composite values consisting of multiple components,
must be converted into certificates in order to be shared with another party.
Ce
r
t
i
f
i
c
a
t
e
sa
r
ec
ov
e
r
e
di
n“
Certificates and Certificate Management”o
npa
g
e149.
Pr
i
v
a
t
ek
e
y
sc
a
n
’
tb
ee
x
por
t
e
da
ss
uc
h,
b
utc
a
no
nl
ybestored in keysets or crypto
de
v
i
c
e
s
.Ke
y
s
e
t
sa
r
ec
ov
e
r
e
di
n“
Key Storage”onpa
g
e133, and crypto devices are
c
ov
e
r
e
di
n“
Encryption Devices and Modules”onpa
g
e265.

Exporting a Key
To exchange a conventional encryption or MAC key with another party, you use the
cryptExportKey and cryptImportKey functions in combination with a conventional
or public-key encryption context or public key certificate.Le
t
’
ss
a
yy
ou’
v
ec
r
e
a
t
e
da
key in an encryption context cryptContext and want to send it to someone whose
public key is in the encryption context pubKeyContext (you can also pass in a
private key if you want, cryptExportKey will only use the public key components).
Todot
hi
sy
o
u’
dus
e
:
CRYPT_CONTEXT pubKeyContext, cryptContext;
void *encryptedKey;
int encryptedKeyLength;
/* Generate a key */
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_3DES );
cryptGenerateKey( cryptContext );
/* Allocate memory for the encrypted key */
encryptedKey = malloc( encryptedKeyMaxLength );
/* Export the key using a public-key encrypted blob */
cryptExportKey( encryptedKey, encryptedKeyMaxLength,
&encryptedKeyLength, pubKeyContext, cryptContext );

The resulting public-key encrypted blob is placed in the memory buffer pointed to by
encryptedKey of maximum size encryptedKeyMaxLength, and the actual
length is stored in encryptedKeyLength. This leads to a small problem: How do
you know how big to make the buffer? The answer is to use cryptExportKey to tell
you. If you pass in a null pointer for encryptedKey, the function will set
encryptedKeyLength to the size of the resulting blob, but not do anything else.
You can then use code like:
cryptExportKey( NULL, 0, &encryptedKeyMaxLength, pubKeyContext,
cryptContext );
encryptedKey = malloc( encryptedKeyMaxLength );
cryptExportKey( encryptedKey, encryptedKeyMaxLength,
&encryptedKeyLength, pubKeyContext, cryptContext );

to create the exported key blob. Note that due to encoding issues for some algorithms
the final exported blob may be one or two bytes smaller than the size which is
i
ni
t
i
a
l
l
yr
e
por
t
e
d,
s
i
n
c
et
het
r
ues
i
z
ec
a
n
’
tb
ede
t
e
r
mi
n
e
du
nt
i
lt
h
ek
e
yi
sa
c
t
ua
l
l
y
exported. Alternatively, you can just reserve a reasonably sized block of memory and
us
et
h
a
tt
oho
l
dt
hee
nc
r
y
pt
e
dk
e
y
.“
Re
a
s
on
a
bl
ys
i
z
e
d”me
a
nsaf
e
wKb,
a4Kbl
oc
k

194

Exchanging Keys

is plenty (an encrypted key blob for a 1024-bit public key is only about 200 bytes
long).
You can also use a public key certificate to export a key. If, instead of a public key
context, you had a key certificate contained in the certificate object
cryptCertificate, the code for the previous example would become:
CRYPT_CERTIFICATE cryptCertificate;
CRYPT_CONTEXT cryptContext;
void *encryptedKey;
int encryptedKeyLength;
/* Generate a key */
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_3DES );
cryptGenerateKey( cryptContext );
/* Allocate memory for the encrypted key */
encryptedKey = malloc( encryptedKeyMaxLength );
/* Export the key using a public-key encrypted blob */
cryptExportKey( encryptedKey, encryptedKeyMaxLength,
&encryptedKeyLength, cryptCertificate, cryptContext );

Theus
eofk
e
yc
e
r
t
i
f
i
c
a
t
e
si
se
x
pl
a
i
ne
di
n“
Certificates and Certificate Management”
on page 149.
If the encryption context contains too much data to encode using the given public key
(for example trying to export an encryption context with a 600-bit key using a 512-bit
public key) the function will return CRYPT_ERROR_OVERFLOW. As a rule of
thumb a 1024-bit public key should be large enough to export the default key sizes
for any encryption context.
If the public key is stored in an encryption context with a certificate associated with it
or in a key certificate, there may be constraints on the key usage that are imposed by
t
hec
e
r
t
i
f
i
c
a
t
e
.I
ft
h
ek
e
yc
a
n’
tbeus
e
df
ort
hee
x
p
or
to
pe
r
a
t
i
on,
t
hef
un
c
t
i
o
nwi
l
l
r
e
t
ur
nCRYPT_ERROR_
PERMI
SSI
ONt
oi
nd
i
c
a
t
et
h
a
tt
hek
e
yi
s
n’
tv
a
l
i
df
ort
hi
s
operation, you can find out more about the exact nature of the problem by reading the
error-r
e
l
a
t
e
da
t
t
r
i
bu
t
e
sa
se
x
pl
a
i
ne
di
n“
Extended Error Reporting”onp
a
g
e284.

Exporting using Conventional Encryption
Youdo
n
’
tne
e
dt
ous
epublic-k
e
ye
nc
r
y
pt
i
o
nt
oe
x
p
or
tak
e
ybl
ob,
i
t
’
sa
l
s
op
os
s
i
b
l
et
o
use a conventional encryption context to export the key from another conventional
encryption context. For example if you were using the key derived from the
pa
s
s
p
hr
a
s
e“
Th
i
si
sas
e
c
r
e
tk
e
y
”(which was also known to the other party) in an
encryption context keyContext you would use:
CRYPT_CONTEXT sharedContext, keyContext;
void *encryptedKey;
int encryptedKeyLength;
/* Derive the export key into an encryption context */
cryptCreateContext( &keyContext, cryptUser, CRYPT_ALGO_3DES );
cryptSetAttributeString( keyContext, CRYPT_CTXINFO_KEYING_SALT, salt,
saltLength );
cryptSetAttributeString( keyContext, CRYPT_CTXINFO_KEYING_VALUE, "This
is a secret key", 20 );
/* Generate a key */
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_3DES );
cryptGenerateKey( cryptContext );
/* Allocate memory for the encrypted key */
encryptedKey = malloc( encryptedKeyMaxLength );
/* Export the key using a conventionally encrypted blob */
cryptExportKey( encryptedKey, encryptedKeyMaxLength,
&encryptedKeyLength, keyContext, cryptContext );

Youdo
n
’
tne
e
dt
ous
eade
r
i
v
e
dk
e
yt
oe
x
por
tt
hes
e
s
s
i
onk
e
y
,
y
ouc
oul
dha
v
el
oa
d
e
d
the context in some other manner (for example from a crypt device such as a smart

Importing a Key

195

card), but the sample code shown above, and further on for the key import phase,
a
s
s
ume
st
h
a
ty
ou
’
l
lbed
e
r
i
v
i
n
gt
hee
x
por
t
/
i
mp
or
tk
e
yf
r
omapa
s
s
wor
d.
Thi
sk
i
n
dofk
e
ye
x
por
ti
s
n’
ta
sc
onv
e
n
i
e
nta
sus
i
ngpubl
i
ck
e
y
ss
i
nc
ei
tr
e
q
ui
r
e
st
h
a
t
both sides know the encryption key in keyContext (or at least know how to derive
i
tf
r
o
ms
o
meot
he
rk
e
y
i
ngma
t
e
r
i
a
l
)
.Onec
a
s
ewhe
r
ei
t
’
su
s
e
f
u
li
swhe
ny
o
uwa
ntt
o
encrypt data such as a disk file that will be decrypted later by the same person who
originally encrypted it. By prepending the key blob to the start of the encrypted file,
you can ensure that each file is encrypted with a different session key (this is exactly
what the cryptlib enveloping functions do). It also means you can change the
password on the file by changing the exported key blob, without needing to decrypt
and re-encrypt the entire file.

Importing a Key
Nowt
ha
ty
ou
’
v
ee
x
por
t
e
dt
hec
onv
e
n
t
i
ona
le
n
c
r
y
pt
i
o
norMACk
e
y
,
t
heot
he
rp
a
r
t
y
needs to import it. This is done using the cryptImportKey function and the private
key corresponding to the public key used by the sender:
CRYPT_CONTEXT privKeyContext, cryptContext;
/* Create a context for the imported key */
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_3DES );
/* Import the key from the public-key encrypted blob */
cryptImportKey( encryptedKey, encryptedKeyLength, privKeyContext,
cryptContext );

Note the use of CRYPT_ALGO_3DES when creating the context for the imported
key, this assumes that both sides have agreed in advance on the use of a common
encryption algorithm to use (in this case triple DES). If the algorithm information
i
s
n’
ta
v
a
i
l
a
b
l
e
,
y
ou
’
l
lha
v
et
one
g
ot
i
a
t
et
hede
t
a
i
l
si
ns
o
meot
h
e
rwa
y
.Thi
si
s
nor
ma
l
l
ydon
ef
ory
oubyc
r
ypt
l
i
b
’
se
nv
e
l
op
i
ngc
odeb
uti
s
n’
ta
v
a
i
l
a
bl
ewhe
n
operating at this lower level.
To summarise, sharing an encryption context between two parties using public-key
encryption involves the following steps:
/* Party A creates the required encryption context and generates a key
into it */
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_3DES );
cryptGenerateKey( cryptContext );
/* Party A exports the key using party B's public key */
cryptExportKey( encryptedKey, encryptedKeyMaxLength,
&encryptedKeyLength, pubKeyContext, cryptContext );
/* Party B creates the encryption context to import the key into */
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_3DES );
/* Party B imports the key using their private key */
cryptImportKey( encryptedKey, encryptedKeyLength, privKeyContext,
cryptContext );

If the public key is stored in an encryption context with a certificate associated with it
or in a key certificate, there may be constraints on the key usage that are imposed by
t
hec
e
r
t
i
f
i
c
a
t
e
.I
ft
h
ek
e
yc
a
n’
tbeus
e
df
ort
hei
mpor
top
e
r
a
t
i
o
n,
t
hef
u
nc
t
i
o
nwill
r
e
t
ur
nCRYPT_ERROR_
PERMI
SSI
ONt
oi
nd
i
c
a
t
et
h
a
tt
hek
e
yi
s
n’
tv
a
l
i
df
ort
hi
s
operation. You can find out more about the exact nature of the problem by reading
the error-r
e
l
a
t
e
da
t
t
r
i
but
e
sa
se
x
pl
a
i
ne
di
n“
Extended Error Reporting”onpa
g
e284.

Importing using Conventional Encryption
If the key has been exported using conventional encryption, you can again use
conventional encryption to import it. Using the same key derived from the
pa
s
s
p
hr
a
s
e“
Th
i
si
sas
e
c
r
e
tk
e
y
”t
ha
twa
sus
e
di
nt
hek
e
ye
x
por
te
x
a
mpl
e
,
y
ouwo
ul
d
use:

196

Exchanging Keys

CRYPT_CONTEXT keyContext, cryptContext;
/* Derive the import key into an encryption context */
cryptCreateContext( &keyContext, cryptUser, CRYPT_ALGO_3DES );
cryptSetAttributeString( keyContext, CRYPT_CTXINFO_KEYING_SALT, salt,
saltLength );
cryptSetAttributeString( keyContext, CRYPT_CTXINFO_KEYING_VALUE, "This
is a secret key", 20 );
/* Create a context for the imported key */
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_3DES );
/* Import the key from the conventionally encrypted blob */
cryptImportKey( encryptedKey, encryptedKeyLength, keyContext,
cryptContext );

Si
nc
et
hes
a
l
ti
sar
a
n
do
mv
a
l
uet
h
a
tc
ha
ng
e
sf
ore
a
c
hk
e
yy
oude
r
i
v
e
,
y
ouwon
’
t
k
nowi
ti
na
dv
a
nc
es
oy
ou
’
l
lhave to obtain it by querying the exported key object as
e
x
pl
a
i
ne
dbe
l
ow.Onc
ey
ou’
v
eque
r
i
e
dt
heo
bj
e
c
t
,
y
ouc
a
nus
et
h
es
a
l
twh
i
c
hi
s
returned with the query information to derive the import key as shown in the above
code.

Querying an Exported Key Object
Sof
a
ri
t
’
sbe
e
na
s
s
u
me
dt
ha
ty
ouk
nowwha
t
’
sr
e
qu
i
r
e
dt
oi
mp
or
tt
hee
x
por
t
e
dk
e
y
bl
o
by
ou
’
r
eg
i
v
e
n(
t
ha
ti
s
,
y
ouk
nowwhi
c
ht
y
peo
fpr
oc
e
s
s
i
ngt
ous
et
oc
r
e
a
t
et
he
encryption context needed to import a conventionally encrypted blob). However
sometimes you may not know this in advance, which is where the cryptQueryObject
function comes in. cryptQueryObject is used to obtain information on the exported
key blob that might be required to import it. You can also use cryptQueryObject to
obtain information o
ns
i
g
na
t
u
r
ebl
o
bs
,
a
se
x
pl
a
i
ne
di
n“
Querying a Signature Object”
on page 200.
The function takes as parameters the object you want to query, and a pointer to a
CRYPT_OBJECT_INFO structure which is describ
e
di
n“
CRYPT_OBJECT_INFO
Structure”onpa
g
e313. The object type will be either a CRYPT_OBJECT_ENCRYPTED_KEY for a conventionally encrypted exported key, a CRYPT_OBJECT_PKCENCRYPTED_KEY for a public-key encrypted exported key, or a
CRYPT_OBJECT_KEYAGREEMENT for a key-agreement key. If you were given
a
na
r
bi
t
r
a
r
yobj
e
c
to
fa
nunk
n
ownt
y
pey
ou
’
dus
et
hef
ol
l
o
wi
ngc
odet
oha
nd
l
ei
t
:
CRYPT_OBJECT_INFO cryptObjectInfo;
cryptQueryObject( object, objectLength, &cryptObjectInfo );
if( cryptObjectInfo.objectType == CRYPT_OBJECT_ENCRYPTED_KEY )
/* Import the key using conventional encryption */;
else
if( cryptObjectInfo.objectType == CRYPT_OBJECT_PKCENCRYPTED_KEY ||
cryptObjectInfo.objectType == CRYPT_OBJECT_KEYAGREEMENT )
/* Import the key using public-key encryption */;
else
/* Error */;

AnyCRYPT_OBJ
ECT_I
NFOf
i
e
l
dst
ha
ta
r
e
n
’
tr
e
l
e
v
a
ntf
ort
hi
st
y
p
eofob
j
e
c
ta
r
es
e
t
to null or zero as appropriate.
Onc
ey
ou
’
v
ef
o
un
do
utwha
tt
y
peofo
bj
e
c
ty
o
uha
v
e
,
y
ouc
a
nuse the other
information returned by cryptQueryObject to process the object. For both
conventional and public-key encrypted exported objects you can find out which
encryption algorithm and mode were used to export the key using the cryptAlgo
and cryptMode fields. For conventionally encrypted exported objects you can
obtain the salt needed to derive the import key from the salt and saltSize fields.

Extended Key Export/Import
The cryptExportKey and cryptImportKey functions described above export and
import conventional encryption or MAC keys in the cryptlib default format (which,
for the technically inclined, is the Cryptographic Message Syntax format with key
identifiers used to denote public keys). The default cryptlib format has been chosen

Key Agreement

197

to be independent of the underlying key format, so that it works equally well with any
key type including X.509 certificates, PGP/OpenPGP keys, and any other key storage
format.
Alongside the default format, cryptlib supports the export and import of keys in other
formats using cryptExportKeyEx. cryptExportKeyEx works like cryptExportKey
but takes an extra parameter that specifies the format to use for the exported keys.
The formats are:
Format

Description

CRYPT_FORMAT_CMS
CRYPT_FORMAT_SMIME

These are variations of the Cryptographic
Message Syntax and are also known as
S/MIME version 2 or 3 and PKCS #7.
This format only allows public-key-based
export, and the public key must be stored
as an X.509 certificate.

CRYPT_FORMAT_CRYPTLIB This is the default cryptlib format and can
be used with any type of key. When used
for public-key based key export, this
format is also known as a newer variation
of S/MIME version 3.
CRYPT_FORMAT_PGP

This is the OpenPGP format and can be
used with any type of key.

cryptImportKeyEx takes one extra parameter, a pointer to the imported key, which
is required for OpenPGP key import. For all other formats this value is set to NULL,
for OpenPGP the imported key parameter is set to CRYPT_UNUSED and the key is
returned in the extra parameter:
/* Import a non-PGP format key */
cryptImportKeyEx( encryptedKey, encryptedKeyLength, importContext,
cryptContext, NULL );
/* Import a PGP-format key */
cryptImportKeyEx( encryptedKey, encryptedKeyLength, importContext,
CRYPT_UNUSED, &cryptContext );

This i
sr
e
q
ui
r
e
dbe
c
a
us
ePGP’
sha
nd
l
i
ngofk
e
y
sdi
f
f
e
r
ss
o
me
wh
a
tf
r
omt
ha
tus
e
d
with other formats.

Key Agreement
The Diffie-Hellman key agreement capability is currently disabled since, unlike RSA
andc
o
nv
e
nt
i
on
alk
e
ye
x
c
ha
n
ge
,
t
he
r
e
’
snowi
de
l
y
-accepted standard format for it
(SSL/TLS and SSHv2 are handled internally by cryptlib and CMS is never used by
anything). If a widely-accepted standard emerges, cryptlib will use that format.
Previous versions of cryptlib used a combination of PKCS #3, PKCS #5, and PKCS
#7 formats and mechanisms to handle DH key agreement.
c
r
y
pt
l
i
bs
up
por
t
sat
hi
r
dk
i
ndofk
e
ye
x
por
t
/
i
mpor
tt
ha
td
oe
s
n’
ta
c
t
ua
l
l
ye
x
por
tor
import a key but merely provides a means of agreeing on a shared secret key with
a
no
t
he
rp
a
r
t
y
.Youdon
’
tha
v
et
oexplicitly load of generate a session key for this one
since the act of performing the key exchange will create a random, secret shared key.
To use this form of key exchange, both parties call cryptExportKey to generate the
blob to send to the other party, and then both in turn call cryptImportKey to import
the blob sent by the other party.
The use of cryptExportKey/cryptImportKey for key agreement rather than key
exchange is indicated by the use of a key agreement algorithm for the context that
would normally be used to export the key. The key agreement algorithm used by
cryptlib is the Diffie-Hellman (DH) key exchange algorithm, CRYPT_ALGO_DH.
In the following code the resulting Diffie-Hellman context is referred to as
dhContext.

198

Exchanging Keys
Si
nc
et
he
r
e
’
sat
wo-way exchange of messages, both parties must create an identical
“
t
e
mp
l
a
t
e
”e
n
c
r
y
pt
i
onc
on
t
e
x
ts
ocryptExportKey knows what kind of key to export.
Le
t
sa
s
s
umet
ha
tbo
t
hs
i
de
sk
nowt
h
e
y
’
l
lbeus
i
ngBl
owf
i
s
hi
nCFBmo
de
.Thef
i
r
s
t
step of the key exchange is therefore:
/* Create the key template */
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_BLOWFISH );
cryptSetAttribute( cryptContext, CRYPT_CTXINFO_MODE, CRYPT_MODE_CFB );
/* Export the key using the template */
cryptExportKey( encryptedKey, encryptedKeyMaxLength,
&encryptedKeyLength, dhContext, cryptContext );
cryptDestroyContext( cryptContext );

Not
et
h
a
tt
he
r
e
’
snone
e
dt
ol
oa
dak
e
yi
nt
ot
h
et
e
mpl
a
t
e
,
s
i
nc
et
hi
si
sg
e
ne
r
a
t
e
d
automatically as part of the export/import process. In addition the template is
de
s
t
r
oy
e
don
c
et
h
ek
e
yha
sbe
e
ne
x
por
t
e
d,
s
i
n
c
et
he
r
e
’
snof
ur
t
he
rus
ef
ori
t— it
merely acts as a template to tell cryptExportKey what to do.
Both parties now exchange encryptedKey blobs, and then use:
cryptImportKey( encryptedKey, encryptedKeyLength, dhContext,
cryptContext );

to create the cryptContext containing the shared key.
The agreement process requires that both sides export their own encryptedKey
blobs before they import the other sides encryptedKey blob. A side-effect of this
is that it allows additional checking on the key agreement process to be performed to
guard against things like triple DES turning into 40-bit RC4 during transmission. If
y
out
r
yt
oi
mpor
ta
n
ot
h
e
rpa
r
t
y
’
sencryptedKey blob without having first exported
your own encryptedKey blob, cryptImportKey will return
CRYPT_ERROR_NOTINITED.

Key Agreement

199

Signing Data
Most public-key encryption algorithms can be used to generate digital signatures on
data. A digital signature is created by signing the contents of a hash context with a
private key to create a signature blob, and verified by checking the signature blob
with the corresponding public key.
To do this, you use the cryptCreateSignature and cryptCheckSignature functions
in combination with a public-k
e
ye
nc
r
y
pt
i
o
nc
o
nt
e
x
t
.Le
t
’
ss
a
yy
ou’
v
eha
s
he
ds
o
me
data with an SHA-1 hash context hashContext and want to sign it with your
private key in the encryption context sigKeyContext.Todot
hi
sy
o
u’
dus
e
:
CRYPT_CONTEXT sigKeyContext, hashContext;
void *signature;
int signatureLength;
/* Create a hash context */
cryptCreateContext( &hashContext, cryptUser, CRYPT_ALGO_SHA );
/* Hash the data */
cryptEncrypt( hashContext, data, dataLength );
cryptEncrypt( hashContext, data, 0 );
/* Allocate memory for the signature */
signature = malloc( signatureMaxLength );
/* Sign the hash to create a signature blob */
cryptCreateSignature( signature, signatureMaxLength, &signatureLength,
sigKeyContext, hashContext );
cryptDestroyContext( hashContext );

The resulting signature blob is placed in the memory buffer pointed to by
signature of maximum size signatureMaxLength, and the actual length is
stored in signatureLength. This leads to the same problem with allocating the
buffer that was described for cryptExportKey, and the solution is again the same:
You use cryptCreateSignature to tell you how big to make the buffer. If you pass in
a null pointer for signature, the function will set signatureLength to the size
of the resulting blob, but not do anything else. You can then use code like:
cryptCreateSignature( NULL, 0, &signatureMaxLength, sigKeyContext,
hashContext );
signature = malloc( signatureMaxLength );
cryptCreateSignature( signature, signatureMaxLength, &signatureLength,
sigKeyContext, hashContext );

to create the signature blob. Note that due to encoding issues for some algorithms the
final exported blob may be one or two bytes smaller than the size which is initially
r
e
por
t
e
d,
s
i
nc
et
h
et
r
ues
i
z
ec
a
n’
tbede
t
e
r
mi
ne
du
nt
i
lt
h
es
i
g
na
t
ur
ei
sa
c
t
u
a
l
l
y
generated. Alternatively, you can just allocate a reasonably sized block of memory
a
ndus
et
h
a
tt
oho
l
dt
hes
i
g
na
t
ur
e
.“
Re
a
s
o
na
bl
ys
i
z
e
d”me
a
nsaf
e
wKb,
a4Kbl
o
c
ki
s
plenty (a signature blob for a 1024-bit public key is only about 200 bytes long).
Nowt
ha
ty
ou
’
v
ec
r
e
a
t
e
dt
hes
i
g
na
t
ur
e
,
t
heo
t
h
e
r party needs to check it. This is done
using the cryptCheckSignature function and the public key or key certificate
corresponding to the private key used to create the signature (you can also pass in a
private key if you want, cryptCheckSignature will only use the public key
c
o
mp
one
nt
s
,
a
l
t
h
oug
hi
t
’
sno
tc
l
e
a
rwhyy
ou’
dbei
npos
s
e
s
s
i
onofs
o
me
o
nee
l
s
e
’
s
pr
i
v
a
t
ek
e
y
)
.Tope
r
f
or
mt
hec
he
c
kus
i
ngapubl
i
ck
e
yc
ont
e
x
ty
ou’
dus
e
:
CRYPT_CONTEXT sigCheckContext, hashContext;
/* Create a hash context */
cryptCreateContext( &hashContext, cryptUser, CRYPT_ALGO_SHA );
/* Hash the data */
cryptEncrypt( hashContext, data, dataLength );
cryptEncrypt( hashContext, data, 0 );

200

Signing Data

/* Check the signature using the signature blob */
cryptCheckSignature( signature, signatureLength, sigCheckContext,
hashContext );
cryptDestroyContext( hashContext );

If the signature is invalid, cryptlib will return CRYPT_ERROR_SIGNATURE. A
signature check using a key certificate is similar, except that it uses a public key
certificate object rather than a public key context. The use of certificates is explained
i
n“
Certificates and Certificate Management”onpa
g
e149.
If the public key is stored in an encryption context with a certificate associated with it
or in a key certificate, there may be constraints on the key usage that are imposed by
t
hec
e
r
t
i
f
i
c
a
t
e
.I
ft
h
ek
e
yc
a
n’
tbeus
e
df
ort
hes
i
g
na
t
ur
eors
i
g
na
t
ur
ec
he
c
ko
pe
r
a
t
i
o
n,
the function will return CRYPT_ERROR_PERMISSION to indicate t
ha
tt
hek
e
yi
s
n
’
t
valid for this operation, you can find out more about the exact nature of the problem
by reading the error-r
e
l
a
t
e
da
t
t
r
i
bu
t
e
sa
se
x
pl
a
i
ne
di
n“
Extended Error Reporting”on
page 284. Note that the entire physical universe, including cryptlib, may one day
collapse back into an infinitely small space. Should another universe subsequently
re-emerge, the integrity of cryptlib signatures in that universe cannot be guaranteed.

Querying a Signature Object
Just as you can query exported key blobs, you can also query signature blobs using
cryptQueryObject, which is used to obtain information on the signature. You can
also use cryptQueryObject to obtain information on exported key blobs as explained
i
n“
Querying an Exported Key Object”o
npa
g
e196.
The function takes as parameters the object you want to query, and a pointer to a
CRYPT_OBJ
ECT_I
NFOs
t
r
uc
t
ur
ewhi
c
hi
sd
e
s
c
r
i
b
e
di
n“
CRYPT_OBJECT_INFO
Structure”onpa
g
e313. The object type will be a CRYPT_OBJECT_SIGNATURE
for a signature object. If you were given an arbitrary object of an unknown type
y
ou’
dus
et
hef
ol
l
owi
ngc
odet
oha
nd
l
ei
t
:
CRYPT_OBJECT_INFO cryptObjectInfo;
cryptQueryObject( object, objectLength, &cryptObjectInfo );
if( cryptObjectInfo.objectType == CRYPT_OBJECT_SIGNATURE )
/* Check the signature */;
else
/* Error */;

AnyCRYPT_OBJ
ECT_I
NFOf
i
e
l
dst
ha
ta
r
e
n
’
tr
e
l
e
v
a
ntf
ort
hi
stype of object are set
to null or zero as appropriate.
Onc
ey
ou
’
v
ef
o
un
do
utwha
tt
y
peofo
bj
e
c
ty
o
uha
v
e
,
y
ouc
a
nus
et
heo
t
h
e
r
information returned by cryptQueryObject to process the object. The information
that you need to obtain from the blob is the hash algorithm that was used to hash the
signed data, which is contained in the hashAlgo field. To hash a piece of data
before checking the signature on it you would use:
CRYPT_CONTEXT hashContext;
/* Create the hash context from the query info */
cryptCreateContext( &hashContext, cryptUser,
cryptObjectInfo.hashAlgo );
/* Hash the data */
cryptEncrypt( hashContext, data, dataLength );
cryptEncrypt( hashContext, data, 0 );

Extended Signature Creation/Checking
The cryptCreateSignatureEx and cryptCheckSignatureEx functions described
above create and verify signatures in the cryptlib default format (which, for the
technically inclined, is the Cryptographic Message Syntax format with key identifiers
used to denote public keys). The default cryptlib format has been chosen to be
independent of the underlying key format, so that it works equally well with any key
type including raw keys, X.509 certificates, PGP/OpenPGP keys, and any other key
storage format.

Extended Signature Creation/Checking

201

Alongside the default format, cryptlib supports the generation and checking of
signatures in other formats using cryptCreateSignatureEx and
cryptCheckSignatureEx. cryptCreateSignatureEx works like
cryptCreateSignature but takes two extra parameters, the first of which specifies the
format to use for the signature. The formats are:
Format

Description

CRYPT_FORMAT_CMS
CRYPT_FORMAT_SMIME

These are variations of the Cryptographic
Message Syntax and are also known as
S/MIME version 2 or 3 and PKCS #7.
The key used for signing must have an
associated X.509 certificate in order to
generate this type of signature.

CRYPT_FORMAT_CRYPTLIB This is the default cryptlib format and can
be used with any type of key. This format
is also known as a newer variation of
S/MIME version 3.
CRYPT_FORMAT_PGP

This is the OpenPGP format and can be
used with any type of key.

The second extra parameter required by cryptCreateSignatureEx depends on the
signature format being used. With CRYPT_FORMAT_CRYPTLIB and
CRYPT_FORMAT_
PGPt
hi
spa
r
a
me
t
e
ri
s
n’
tus
e
da
n
ds
ho
ul
dbes
e
tt
oCRYPT_UNUSED. With CRYPT_FORMAT_CMS/CRYPT_FORMAT_SMIME, this
parameter specifies optional additional information which is included with the
signature. The only real difference between the CRYPT_FORMAT_CMS and
CRYPT_FORMAT_SMIME signature format is that CRYPT_FORMAT_SMIME
adds a few extra S/MIME-s
pe
c
i
f
i
ca
t
t
r
i
b
ut
e
st
ha
ta
r
e
n
’
ta
dd
e
dbyCRYPT_FORMAT_CMS. This additional information includes things like the type of data
be
i
ngs
i
g
ne
d(
s
ot
ha
tt
hes
i
g
ne
dc
o
nt
e
ntc
a
n
’
tb
ei
n
t
e
r
pr
e
t
e
dt
hewr
ongwa
y
)
,t
he
signing time (
s
ot
ha
ta
no
l
ds
i
g
ne
dme
s
s
a
g
ec
a
n’
tber
e
us
e
d
)
,
a
nda
nyot
he
r
information that the signer might consider worth including.
The easiest way to handle this extra information is to let cryptlib add it for you. If
you set the parameter to CRYPT_USE_DEFAULT, cryptlib will generate and add the
extra information for you:
void *signature;
int signatureMaxLength, signatureLength;
cryptCreateSignatureEx( NULL, 0, &signatureMaxLength,
CRYPT_FORMAT_CMS, sigKeyContext, hashContext, CRYPT_USE_DEFAULT );
signature = malloc( signatureMaxLength );
cryptCreateSignatureEx( signature, signatureMaxLength,
&signatureLength, CRYPT_FORMAT_CMS, sigKeyContext, hashContext,
CRYPT_USE_DEFAULT );

If you need more precise control over the extra information, you can specify it
yourself in the form of a CRYPT_CERTTYPE_CMS_ATTRIBUTES certificate
obj
e
c
t
,
whi
c
hi
sd
e
s
c
r
i
b
e
di
nmor
ede
t
a
i
li
n“
CMS/SMIME Attributes”o
npa
g
e253.
By default cryptlib will include the default signature attributes CRYPT_CERTINFO_CMS_SIGNINGTIME and CRYPT_CERTINFO_CMS_CONTENTTYPEf
ory
oui
fy
oud
on
’
ts
p
e
c
i
f
yi
ty
our
s
e
l
f
,
a
ndf
orS/
MI
MEs
i
g
na
t
ur
e
s
it will also include CRYPT_CERTINFO_CMS_SMIMECAPABILITIES. You can
disable this automatic including with the cryptlib configuration option CRYPT_OPTION_CMS_DEFAULTATTRIBUTES/CRYPT_OPTION_SMIME_DEFAULTATTRI
BUTESa
se
x
pl
a
i
ne
di
n“
Working with Configuration Options”o
n
page 274, this will simplify the signature somewhat and reduce its size and
processing overhead:

202

Signing Data

CRYPT_CERTIFICATE signatureAttributes;
void *signature;
int signatureMaxLength, signatureLength;
/* Create the signature attribute object */
cryptCreateCert( &signatureAttributes, cryptUser,
CRYPT_CERTTYPE_CMS_ATTRIBUTES );
/* ... */
/* Create the signature including the attributes as extra information
*/
cryptCreateSignatureEx( NULL, 0, &signatureMaxLength,
CRYPT_FORMAT_CMS, sigKeyContext, hashContext, signatureAttributes
);
signature = malloc( signatureMaxLength );
cryptCreateSignatureEx( signature, signatureMaxLength,
&signatureLength, CRYPT_FORMAT_CMS, sigKeyContext, hashContext,
signatureAttributes );
cryptDestroyCert( signatureAttributes );

I
ng
e
ne
r
a
li
fy
ou
’
r
es
e
n
di
ngs
i
g
ne
dda
t
at
oar
e
c
i
p
i
e
ntwhoi
s also using cryptlibbased software, you should use the default cryptlib signature format which is more
flexible in terms of key handling and far more space-efficient (CMS/SMIME
signatures are typically ten times the size of the default cryptlib format while
providing little extra information, and have a much higher processing overhead than
cryptlib signatures).
As with encrypted key export, PGP handles signing somewhat differently to any other
f
or
ma
t
.I
npa
r
t
i
c
ul
a
r
,
whe
ny
ouh
a
s
ht
heda
t
ay
ouc
a
n
’
tc
o
mp
l
ete the processing by
hashing a zero-length value as with normal signatures, since PGP needs to hash in
assorted other data before it writes the signature. The same holds for signature
verification.
Extended signature checking follows the same pattern as extended signature
generation, with the extra parameter to the function being a pointer to the location
that receives the additional information included with the signature. With the
CRYPT_FORMAT_CRYPTLI
Bf
or
ma
tt
y
p
e
,
t
he
r
e
’
sn
oe
x
t
r
ai
nf
or
ma
t
i
onpr
e
s
e
n
t
and the parameter should be set to null. With CRYPT_FORMAT_CMS/
CRYPT_FORMAT_SMI
ME,
y
ouc
a
na
l
s
os
e
tt
hep
a
r
a
me
t
e
rt
onul
li
fy
ou
’
r
eno
t
interested in the additional information, and cryptlib will discard it after using it as
part of the signature checking process. If you are interested in the additional
information, you should set the parameter to a pointer to a CRYPT_CERTIFICATE
object that cryptlib will create for you and populate with the additional signature
information. If the signature check succeeds, you can work with the resulting
i
n
f
or
ma
t
i
o
na
sde
s
c
r
i
be
di
n“
Other Certificate Object Extensions”o
npa
g
e253:
CRYPT_CERTIFICATE signatureAttributes;
int status;
status = cryptCheckSignatureEx( signature, signatureLength,
sigCheckCertificate, hashContext, &signatureAttributes );
if( cryptStatusOK( status ) )
{
/* Work with extra signature information in signatureAttributes */
/* ... */
/* Clean up */
cryptDestroyCert( signatureAttributes );
}

Overview of Certificates

203

Certificates in Detail
Al
t
ho
ug
hapub
l
i
c
/
pr
i
v
a
t
ek
e
yc
ont
e
x
tc
a
nbeus
e
dt
os
t
or
eba
s
i
ck
e
yc
o
mp
on
e
nt
s
,
i
t
’
s
notc
a
pa
bl
eo
fs
t
or
i
nga
nya
ddi
t
i
o
na
li
n
f
or
ma
t
i
o
ns
uc
ha
st
hek
e
yowne
r
’
sna
me
,
usage restrictions, and key validity information. This type of information is stored in
a key certificate, which is encoded according to the X.509 standard and sundry
amendments, corrections, extensions, profiles, and related standards. A certificate
consists of the encoded public key, information to identify the owner of the
certificate, other data such as usage and validity information, and a digital signature
that binds all this information to the key.
There are a number of different types of certificate objects, including actual
certificates, certification requests, certificate revocation lists (CRLs), certification
authority (CA) certificates, certificate chains, attribute certificates, and others. For
simplicity the following text refers to all of these items using the general term
“
c
e
r
t
i
f
i
c
a
t
e
”
.Onl
ywhe
r
eas
pe
c
i
f
i
ctype of item such as a CA certificate or a
certification request is required will the actual name be used.
cryptlib stores all of these items in a generic CRYPT_CERTIFICATE container
object into which you can insert various items such as identification information and
key attributes, as well as public-key encryption contexts or other certificate objects.
Once everything has been added, you can fix the state of the certificate by signing it,
a
f
t
e
rwhi
c
hy
o
uc
a
n
’
tc
ha
ng
ei
te
x
c
e
p
tbys
t
a
r
t
i
nga
g
a
i
nwi
t
haf
r
esh certificate object.
Working with certificates at the level described in this and the following chapters is
extraordinarily difficult and painful. Before you decide to work with certificates at
t
hi
sl
e
v
e
l
,
y
ous
ho
ul
dr
e
a
d“
High-level vs. Low-level Certificate Operations”onpa
g
e
149 t
oma
k
ea
bs
ol
ut
e
l
yc
e
r
t
a
i
ny
oudo
n
’
twa
n
tt
ous
ec
r
y
pt
l
i
b
’
shi
g
h-level certificate
management capabilities instead.

Overview of Certificates
Public key certificates are objects that bind information about the owner of a public
key to the key itself. The binding is achieved by having the information in the
certificate signed by a certification authority (CA) that protects the integrity of the
certificate information and allows it to be distributed over untrusted channels and
stored on untrusted systems.
You can request a certificate from a CA with a certification request, which encodes a
public key and identification information and binds them together for processing by
the CA. The CA responds to a certificate request with a signed certificate.
In addition to creating certificates, you may occasionally need to revoke them.
Revoked keys are handled via certificate revocation lists (CRLs), which work like
197
0
’
s
-vintage credit card blacklists by providing users with a list of certificates that
s
hou
l
d
n’
tbeho
no
ur
e
da
nymor
e
.I
npr
a
c
t
i
c
et
h
ebl
a
c
k
l
i
s
ta
ppr
o
a
c
hwa
sne
v
e
r
practical (it was for this reason that it was abandoned by credit card vendors twenty
years ago), has little support in actual implementations, and is typically handled by
g
oi
ngt
hr
oug
ht
hemot
i
o
nsofaCRLc
he
c
kf
orf
or
m’
ss
a
k
ewi
t
ho
utr
e
a
l
l
yt
a
k
i
ngi
t
seriously. Revocations can only be issued by a CA, so to revoke a certificate you
either have to be a CA or have the co-operation of a CA. This chapter covers the
details of creating and issuing CRLs.

Certificates and Standards Compliance
The key certificates used by most software today were originally specified in the
CCITT (now ITU) X.509 standard, and have been extended via assorted ISO, ANSI,
I
TU,
I
ETF,
a
ndna
t
i
o
na
ls
t
a
n
da
r
ds(
g
e
ne
r
a
l
l
yr
e
f
e
r
r
e
dt
oa
s“
X.
509pr
o
f
i
l
e
s
”
)
,
a
l
ong
with sundry amendments, meeting notes, draft standards, committee drafts, working
drafts, and other work-in-progress documents. X.509 version 1 (X.509v1) defined
the original, very basic certificate format, the latest version of the standard is version
4 (X.509v4), which defines all manner of extensions and additions and is still in the
process of being finalised and profiled. Compliance with the various certificate

204

Certificates in Detail

standards varies greatly. Most implementations manage to get the decade-old
X.509v1 more or less correct, and cryptlib includes special code to allow it to process
many incorrectly-formatted X.509v1-style certificates as well as all correctly
formatted ones. However compliance with X.509v3 and X.509v4 profiles is
extremely patchy. Because of this, it is strongly recommended that you test the
certificates you plan to produce with cryptlib against any other software you want to
interoperate with. Although cryptlib produces certificates that comply fully with
X.509v3 and X.509v4 and related standards and recommendations, many other
pr
og
r
a
ms(
i
nc
l
u
di
ngs
e
v
e
r
a
lc
ommonwe
bbr
ows
e
r
sa
nds
e
r
v
e
r
s
)e
i
t
he
rc
a
n
’
tpr
oc
e
s
s
these certificates or will process them incorrectly. Note that even if the other
s
of
t
wa
r
el
oa
dsy
ourc
e
r
t
i
f
i
c
a
t
e
,
i
tf
r
e
q
ue
nt
l
ywon
’
tpr
oc
e
s
st
hei
nf
or
ma
t
i
o
nc
o
nt
a
i
ne
d
i
ni
tc
or
r
e
c
t
l
y
,
s
oy
ous
hou
l
dv
e
r
i
f
yt
ha
ti
t
’
sha
n
dl
i
ngi
ti
nt
hewa
yy
oue
x
pe
c
ti
tt
o.
If you need to interoperate with a variety of other programs, you may need to find the
lowest common denominator that all programs can accept, which is usually X.509v1,
sometimes with one or two basic X.509v3 extensions. Alternatively, you can issue
different certificates for different software, a technique which is currently used by
some CAs that have a different certificate issuing process for Netscape, MSIE, and
everything else.
Much current certificate management software produces an amazing collection of
garbled, invalid, and just plain broken certificates that will be rejected by cryptlib as
notc
o
mp
l
y
i
ngwi
t
ht
her
e
l
e
v
a
nts
e
c
ur
i
t
ys
t
a
n
da
r
ds
.Toby
p
a
s
st
hi
spr
o
bl
e
m,
i
t
’
s
possible to disable various portions of the certificate checking code in order to allow
these certificates to be processed. If a certificate fails to load you can try disabling
more and more certificate checking in cryptlib until the certificate can be loaded,
although disabling these checks will also void any guarantees about correct certificate
handling.
Finally, implementations are free to stuff anything they feel like into certain areas of
the certificate. cryptlib goes to some lengths to take this into account and process the
certificate no matter what data it finds in there, however sometimes it may find
s
ome
t
h
i
ngt
ha
ti
tc
a
n
’
tha
ndl
e
.I
fy
our
e
qui
r
es
u
pp
or
tf
ors
pe
c
i
a
lc
e
r
t
i
f
i
c
a
t
e
components (either to generate them or to process them), please contact the cryptlib
developers.

Certificate Compliance Level Checking
In order to allow cryptlib to process broken certificates, you can vary the level of
standards compliance checking that it performs on certificates. The level of checking
is controlled by the CRYPT_OPTION_CERT_COMPLIANCELEVEL configuration
option, with configuration options being e
x
pl
a
i
ne
di
nmor
ede
t
a
i
li
n“
Working with
Configuration Options”o
npa
g
e274. This option can be set to one of the following
values:
Compliance Level

Description

CRYPT_Full compliance with X.509 and PKIX
COMPLIANCELEVEL_ standards. This checks and enforces all PKIX
PKIX_FULL
extensions and requirements (note the warning
further down about what this entails). This level
of checking will reject a significant number of
certificates/certificate chains in use today.

Overview of Certificates

205

CRYPT_Reduced level of compliance with X.509 and
COMPLIANCELEVEL_ PKIX standards. This omits handling of
PKIX_PARTIAL
problematic extensions such as name and policy
constraints, whose semantics no-one can quite
agree on, and a few other problematic
extensions defined in various certificate
standards, but checks and enforces all other
PKIX requirements. As with CRYPT_COMLPIANCELEVEL_PKIX_FULL, this
level of checking will reject a number of
certificates in use today.
CRYPT_Moderate level of checking equivalent to that
COMPLIANCELEVEL_ performed by most software in use today. Many
STANDARD
of the more complex and/or obscure extensions
are ignored, which makes it possible to process
certificates generated by other software that
similarly ignores them. In addition many X.509
and PKIX compliance requirements are
significantly relaxed, so that (for example) the
mandatory key usage extension, if absent, may
be synthesised from other information present in
the certificate.
CRYPT_Minimal level of checking required to handle
COMPLIANCELEVEL_ severely broken certificates. All extensions
REDUCED
except the ones controlling certificate and
certificate key usage are ignored, allowing
certificates with invalid or garbled contents to
be processed.
CRYPT_No checking of certificate contents except for a
COMPLIANCELEVEL_ minimal check of the certificate key usage. This
OBLIVIOUS
level of checking merely confirms that the
object looks vaguely like a certificate, and that
its signature verifies. This allows expired and
otherwise invalid certificates to be processed.
These reduced levels of checking are required in order to successfully process
certificates generated by other software. Although cryptlib-generated certificates can
be processed at the CRYPT_COMPLIANCELEVEL_PKIX_FULL compliance level,
it may be necessary to lower the level all the way down to CRYPT_COMPLIANCELEVEL_OBLIVIOUS in order to handle certificates from other
a
pp
l
i
c
a
t
i
ons
.I
fy
oue
nc
o
un
t
e
rac
e
r
t
i
f
i
c
a
t
et
h
a
tc
a
n
’
tbepr
oc
e
s
s
e
da
ta given
compliance level, for example one that generates a CRYPT_ERROR_BADDATA on
import or a CRYPT_ERROR_INVALID when checked, you can either request that
the originator of the certificate fix it (this is unlikely to happen) or lower the
compliance level until the certificate can be imported/checked.
At reduced compliance levels, cryptlib skips potentially problematic certificate
extensions, so that these will seem to disappear from the certificate as the compliance
level is lowered. For example, the name constraints extension will be decoded at
CRYPT_COMPLIANCELEVEL_PKIX_FULL, but not at any lower level, so that
unless the certificate is processed at that level the extension will appear to be absent.
I
ns
omer
a
r
ec
a
s
e
sCAsma
ypl
a
c
et
h
eus
e
r
’
se
ma
i
la
ddr
ess in the subject altName
instead of the subject DN. Setting the compliance level to one where this extension is
skipped will cause the email address to appear to vanish from the certificate, which
you need to take into account when you add the certificat
et
oak
e
y
s
e
t
,
s
i
nc
ey
ou
’
l
lno
longer be able to fetch it from the keyset based on the email address. Conversely,
extra extensions that were skipped at lower levels may appear as the compliance level
is increased and they are processed by cryptlib.

206

Certificates in Detail

One significant difference between CRYPT_COMPLIANCELEVEL_PKIX_FULL
and the levels below it is that this level implements every quirk and peculiarity
required by the standard. As a result, the levels below this one process certificates in
a straightforward, consistent manner, while CRYPT_COMPLIANCELEVEL_PKIX_FULL can produce apparently inconsistent and illogical results when the more
unusual and peculiar requirements of the standard are applied. Compliance levels
be
l
owt
heh
i
g
he
s
tonea
r
e
n
’
tf
ul
l
yc
o
mpl
i
a
n
twi
th the standard but will never produce
unexpected results, while the highest compliance level is fully compliant but will
produce unexpected results where the standard mandates odd behaviour in handling
certain types of extensions or certificate paths.

The Certification Process
Obtaining a public key certificate involves generating a public key, creating a
certificate request from it, transmitting it to a CA who converts the certification
request into a certificate and signs it, and finally retrieving the completed certificate
from the CA:

User

Generate
certificate request

Convert certificate
request to certificate

Verify new
certificate

Add (optional) attributes
and sign certificate

These steps can be broken down into a number of individual operations. The first
step, generating a certification request, involves the following:
generate public/private key pair;
create certificate object;
add public key to certificate object;
add identification information to certificate object;
sign certificate object with private key;
export certification request for transmission to CA;
destroy certificate object;

The CA receives the certification request and turns it into a certificate as follows:
import certification request;
check validity and signature on certification request;
create certificate object;
add certification request to certificate object;
add any extra information (e.g. key usage constraints) to certificate
object;
sign certificate object;
export certificate for transmission to user;
destroy certificate objects;

Finally, the user receives the signed certificate from the CA and processes it as
required, typically writing it to a public key keyset or updating a private key keyset:
import certificate;
check validity and signature on certificate;
write certificate to keyset;
destroy certificate object;

The details on performing these operations are covered in the following sections.

Creating/Destroying Certificate Objects
Certificates are accessed as certificate objects that work in the same general manner
as the other container objects used by cryptlib. You create the certificate object with
cryptCreateCert, specifying the user who is to own the device object or
CRYPT_UNUSED for the default, normal user, the type of certificate you want to

Working with Certificate Attributes

207

c
r
e
a
t
e
.Onc
ey
ou
’
v
ef
i
n
i
s
he
dwi
t
ht
heo
bj
e
c
t
,
y
ouus
ecryptDestroyCert to destroy
it:
CRYPT_CERTIFICATE cryptCertificate;
cryptCreateCert( &cryptCertificate, cryptUser, certificateType );
/* Work with the certificate */
cryptDestroyCert( cryptCertificate );

The available certificate types are:
Certificate Type

Description

CRYPT_CERTTYPE_ATTRCERT

Attribute certificate.

CRYPT_CERTTYPE_CERTCHAIN

Certificate chain

CRYPT_CERTTYPE_CERTIFICATE

Certificate or CA certificate.

CRYPT_CERTTYPE_CERTREQUEST Certification request
CRYPT_CERTTYPE_CRL

Certificate revocation.

Note that the CRYPT_CERTIFICATE is passed to cryptCreateCert by reference, as
the function modifies it when it creates the certificate object. In all other routines,
CRYPT_CERTIFICATE is passed by value.
You can also create a certificate object by reading a certificate from a public key
da
t
a
ba
s
e
,
a
se
x
pl
a
i
ne
di
n“
Reading a Key from a Keyset”o
npa
g
e141. Unlike
cryptCreateCert, this will read a complete certificate into a certificate object, while
cryptCreateCert only creates a certificate template that still needs various details
s
uc
ha
st
hep
ub
l
i
ck
e
ya
ndk
e
yowne
r
’
sna
mef
i
l
l
e
di
n.
A third way to create a certificate object is to import an encoded certificate using
cryptImportCert,
whi
c
hi
se
x
pl
a
i
ne
di
nmor
ed
e
t
a
i
li
n“
Importing/Exporting
Certificates”on page 221. Like the public key read functions, this imports a
complete certificate into a certificate object.

Working with Certificate Attributes
Certificate objects contain a number of basic attributes and an optional collection of
often complex data structures and components. cryptlib provides a variety of
mechanisms for working with them. The attributes in a certificate object can be
broken up into three basic types:
1.

Basic certificate attributes such as the public key and timestamp/validity
information.

2. Identification information such as the certificate subject and issuer name.
3. Certificate extensions that can contain almost anything. These are covered in
“
Certificate Extensions”onp
a
g
e234.
Although cryptlib provides the ability to manipulate all of these attributes, in practice
you only need to handle a small subset of them yourself. The rest will be set to
sensible defaults by cryptlib.
Apart from this, certificate attributes are handled in the standard way described in
“
Working with Object Attributes”onp
a
g
e33.

Certificate Structures
Certificates, attribute certificates, certification requests, and CRLs have their own,
often complex, structures that are encoded and decoded for you by cryptlib.
Although cryptlib provides the ability to control the details of each certificate object
in great detail if you require this, in practice you should leave the certificate
ma
na
g
e
me
n
tt
oc
r
y
pt
l
i
b.
I
fy
oudo
n’
tf
i
l
li
nt
hen
on-mandatory fields, cryptlib will fill
them in for you with default values when you sign the certificate object.

208

Certificates in Detail

Certificate chains are composite objects that contain within them one or more
c
o
mp
l
e
t
ec
e
r
t
i
f
i
c
a
t
e
s
.The
s
ea
r
ec
ov
e
r
e
di
nmor
ede
t
a
i
li
n“
Certificate Chains”on
page 225.

Attribute Certificate Structure
An X.509 attribute certificate has the following structure:
Field

Description

Version

The version number defines the attribute certificate
version and is filled in automatically by cryptlib when
the certificate is signed.

HolderName

The holder name identifies the holder of the attribute
certificate and is explained in more detail further on. If
you add a certificate request using CRYPT_CERTINFO_CERTREQUEST or a certificate using
CRYPT_CERTINFO_CERTIFICATE, this field will
be filled in for you.
This is a composite field that you must fill in yourself
unless it has already been filled in from a certification
request or certificate.

IssuerName

The issuer name identifies the attribute certificate
signer (usually an authority, the attribute-certificate
version of a CA), and is filled in automatically by
cryptlib when the certificate is signed.

SignatureAlgorithm The signature algorithm identifies the algorithm used to
sign the attribute certificate, and is filled in
automatically by cryptlib when the certificate is signed.
SerialNumber

The serial number is unique for each attribute
certificate issued by an authority, and is filled in
automatically by cryptlib when the certificate is signed.
You can obtain the value of this field with
CRYPT_CERTINFO_SERIALNUMBER, but you
c
a
n
’
ts
e
ti
t
.I
fy
out
r
yt
os
e
ti
t
,
c
r
y
pt
l
i
bwi
l
lr
e
t
urn
CRYPT_ERROR_PERMISSION to indicate that you
don
’
tha
v
epe
r
mi
s
s
i
o
nt
os
e
tt
hi
sf
i
e
l
d.Thes
e
r
i
a
l
number is returned as a binary string and not as a
numeric value, since it is often 15-20 bytes long.
c
r
y
pt
l
i
bdo
e
s
n
’
tus
es
t
r
i
c
ts
e
q
ue
n
t
i
a
lnu
mbe
r
i
ngf
ort
he
certificates it issues since this would make it very easy
for a third party to determine how many certificates a
CA is issuing at any time.

Validity

The validity period defines the period of time over
which an attribute certificate is valid. CRYPT_CERTINFO_VALIDFROM specifies the validity start
period, and CRYPT_CERTINFO_VALIDTO specifies
t
hev
a
l
i
di
t
ye
ndp
e
r
i
o
d.I
fy
oudo
n’
ts
e
tt
he
s
e
,
c
r
y
pt
l
i
b
will set them for you when the attribute certificate is
signed so that the certificate validity starts on the day of
issue and ends one year later. You can change the
default validity period using the cryptlib configuration
option CRYPT_OPTION_CERT_VALIDITY as
e
x
pl
a
i
ne
di
n“
Working with Configuration Options”o
n
page 274.
cryptlib enforces validity period nesting when
generating an attribute certificate, so that the validity
period of an attribute certificate will be constrained to

Certificate Structures

Field

Description
lie within the validity period of the authority certificate
that signed it
.I
ft
h
i
si
s
n
’
td
o
ne
,
s
o
mes
o
f
t
wa
r
ewi
l
l
treat the certificate as being invalid, or will regard it as
having expired once the authority certificate that signed
it expires.
Due to the vagaries of international time zones and
daylight savings time adjustment
s
,
i
ti
s
n
’
tp
os
s
i
b
l
et
o
accurately compare two local times from different time
zones, or made across a DST switch (consider for
example a country switching to DST, which has two
2am times while another country only has one).
Because of this ambiguity, times read from objects
such as certificates may be out by an hour or two.

Attributes

The attributes field contains a collection of attributes
for the certificate owner. Since no standard attributes
had been defined at the time of the last X.509 attribute
c
e
r
t
i
f
i
c
a
t
ec
o
mmi
t
t
e
edr
a
f
t
,
c
r
y
pt
l
i
bdo
e
s
n
’
tc
ur
r
e
nt
l
y
support attributes in this field. When attributes are
defined, cryptlib will support them.

IssuerUniqueID

The issuer unique ID was added in X.509v2, but its use
has been discontinued. If this string field is present in
existing attribute certificates you can obtain its value
using CRYPT_CERTINFO_ISSUERUNIQUEID, but
y
ouc
a
n
’
ts
e
ti
t
.I
fy
out
r
yt
os
e
ti
t
,
c
r
y
pt
l
i
bwi
l
lr
e
t
ur
n
CRYPT_ERROR_PERMISSION to indicate that you
have no permission to set this field.

Extensions

Certificate extensions allow almost anything to be
added to an attribute certificate and are covered in more
de
t
a
i
li
n“
Certificate Extensions”onpa
g
e234.

Certificate Structure
An X.509 certificate has the following structure:
Field

Description

Version

The version number defines the certificate version and
is filled in automatically by cryptlib when the
certificate is signed. It is used mainly for marketing
purposes to claim that software is X.509v3 compliant
(
e
v
e
nwhe
ni
ti
s
n
’
t
)
.

SerialNumber

The serial number is unique for each certificate issued
by a CA, and is filled in automatically by cryptlib when
the certificate is signed. You can obtain the value of
this field with CRYPT_CERTINFO_SERI
ALNUMBER,
buty
ouc
a
n’
ts
e
ti
t
.I
fy
out
r
yt
o
set it, cryptlib will return CRYPT_ERROR_PERMI
SSI
ONt
oi
nd
i
c
a
t
et
ha
ty
oudo
n
’
tha
v
e
permission to set this field. The serial number is
returned as a binary string and not as a numeric value,
since it is often 15-20 bytes long.
c
r
y
pt
l
i
bdo
e
s
n
’
tus
es
t
r
i
c
ts
e
q
ue
n
t
i
a
lnu
mbe
r
i
ngf
ort
he
certificates it issues since this would make it very easy
for a third party to determine how many certificates a
CA is issuing at any time.

SignatureAlgorithm The signature algorithm identifies the algorithm used to
sign the certificate, and is filled in automatically by

209

210

Certificates in Detail

Field

Description
cryptlib when the certificate is signed.

IssuerName

The issuer name identifies the certificate signer
(usually a CA), and is filled in automatically by
cryptlib when the certificate is signed.

Validity

The validity period defines the period of time over
which a certificate is valid. CRYPT_CERTINFO_VALIDFROM specifies the validity start period, and
CRYPT_CERTINFO_VALIDTO specifies the validity
e
ndpe
r
i
o
d.I
fy
oud
on
’
ts
e
tt
he
s
e
,
c
r
y
pt
l
i
bwi
l
ls
e
t
them for you when the certificate is signed so that the
certificate validity starts on the day of issue and ends
one year later. You can change the default validity
period using the cryptlib configuration option
CRYPT_OPTION_CERT_VALIDITY as explained in
“
Working with Configuration Options”o
npa
g
e274.
cryptlib enforces validity period nesting when
generating a certificate, so that the validity period of a
certificate will be constrained to lie within the validity
pe
r
i
o
do
ft
h
eCAc
e
r
t
i
f
i
c
a
t
et
h
a
ts
i
g
ne
di
t
.I
ft
h
i
si
s
n
’
t
done, some software will treat the certificate as being
invalid, or will regard it as having expired once the CA
certificate that signed it expires.
Due to the vagaries of international time zones and
da
y
l
i
g
hts
a
v
i
ng
st
i
mea
d
j
us
t
me
nt
s
,
i
ti
s
n
’
tp
os
s
i
b
l
et
o
accurately compare two local times from different time
zones, or made across a DST switch (consider for
example a country switching to DST, which has two
2am times while another country only has one).
Because of this ambiguity, times read from objects
such as certificates may be out by an hour or two.

SubjectName

The subject name identifies the owner of the certificate
and is explained in more detail further on. If you add
the subject public key info from a certification request
using CRYPT_CERTINFO_CERTREQUEST, this
field will be filled in for you.
This is a composite field that you must fill in yourself
unless it has already been filled in from a certification
request.

SubjectPublicKey- The subject public key info contains the public key for
Info
this certificate. You can specify the public key with
CRYPT_CERTINFO_SUBJECTPUBLICKEYINFO,
and provide either an encryption context or a certificate
object that contains a public key. You can also add a
certification request with CRYPT_CERTINFO_CERTREQUEST, which fills in the subject public key
info, subject name, and possibly some certificate
extensions.
This is a numeric field that you must fill in yourself.
IssuerUniqueID
SubjectUniqueID

The issuer and subject unique ID were added in
X.509v2, but their use has been discontinued. If these
string fields are present in existing certificates you can
obtain their values using CRYPT_CERTINFO_ISSUERUNIQUEID and CRYPT_CERTINFO_SUBJ
ECTUNI
QUEI
D,
buty
ouc
a
n’
ts
e
tt
he
m.I
fy
ou

Certificate Structures

Field

Description
try to set them, cryptlib will return CRYPT_ERROR_PERMISSION to indicate that you have no permission
to set these fields.

Extensions

Certificate extensions were added in X.509v3.
Extensions allow almost anything to be added to a
c
e
r
t
i
f
i
c
a
t
ea
nda
r
ec
ov
e
r
e
di
nmor
ede
t
a
i
li
n“
Certificate
Extensions”o
np
a
g
e234.

Certification Request Structure
PKCS #10 and CRMF certification requests have the following structure:
Field

Description

Version

The version number defines the certification request
version and is filled in automatically by cryptlib when
the request is signed.

SubjectName

The subject name identifies the owner of the
certification request and is explained in more detail
further on.
This is a composite field that you must fill in yourself.

SubjectPublicKey- The subject public key info contains the public key for
Info
this certification request. You can specify the public
key with CRYPT_CERTINFO_SUBJECTPUBLICKEYINFO, and provide either an
encryption context or a certificate object that contains a
public key.
This is a composite field that you must fill in yourself.
Extensions

Extensions allow almost anything to be added to a
certification request and are covered in more detail in
“
Certificate Extensions”onp
a
g
e234.

CRL Structure
An X.509 CRL has the following structure:
Field

Description

Version

The version number defines the CRL version and is
filled in automatically by cryptlib when the CRL is
signed.

SignatureAlgorithm The signature algorithm identifies the algorithm used to
sign the CRL, and is filled in automatically by cryptlib
when the CRL is signed.
IssuerName

The issuer name identifies the CRL signer, and is filled
in automatically by cryptlib when the CRL is signed.

ThisUpdate
NextUpdate

The update time specifies when the CRL was issued,
and the next update time specifies when the next CRL
will be issued. CRYPT_CERTINFO_THISUPDATE
specifies the current CRL issue time, and
CRYPT_CERTINFO_NEXTUPDATE specifies the
ne
x
tCRLi
s
s
uet
i
me
.I
fy
oudon
’
ts
e
tt
he
s
e
,
c
r
y
pt
l
i
b
will set them for you when the CRL is signed so that
the issue time is the day of issue and the next update
time is 90 days later. You can change the default
update interval using the cryptlib configuration option
CRYPT_OPTION_CERT_UPDATEINTERVAL as

211

212

Certificates in Detail

Field

Description
e
x
pl
a
i
ne
di
n“
Working with Configuration Options”o
n
page 274.
Due to the vagaries of international time zones and
da
y
l
i
g
hts
a
v
i
ng
st
i
mea
d
j
us
t
me
nt
s
,
i
ti
s
n
’
tp
os
s
i
b
l
et
o
accurately compare two local times from different time
zones, or made across a DST switch (consider for
example a country switching to DST, which has two
2am times while another country only has one).
Because of this ambiguity, times read from objects
such as certificates may be out by an hour or two.

UserCertificate

The user certificate identifies the certificates that are
being revoked in this CRL. The certificates must be
ones that were issued using the CA certificate which is
being used to issue the CRL. If you try to revoke a
certificate that was issued using a different CA
certificate, cryptlib will return a CRYPT_ERROR_INVALID error when you add the certificate or sign
t
heCRLt
oi
nd
i
c
a
t
et
ha
tt
hec
e
r
t
i
f
i
c
a
t
ec
a
n
’
tber
e
v
ok
e
d
using this CRL. You can specify the certificates to be
revoked with CRYPT_CERTINFO_CERTIFICATE.
This is a numeric field, and the only one that you must
fill in yourself.

RevocationDate

The revocation date identifies the date on which a
certificate was revoked. You can specify the
revocation date with CRYPT_CERTINFO_REVOCATI
ONDATE.I
fy
oudo
n’
ts
e
t it, cryptlib will
set it for you to the date on which the CRL was signed.
The revocation date you specify applies to the last
certificate added to the list of revoked certificates. If
no certificates have been added yet, it will be used as a
default date that applies to all certificates for which no
revocation date is explicitly set.
Due to the vagaries of international time zones and
da
y
l
i
g
hts
a
v
i
ng
st
i
mea
d
j
us
t
me
nt
s
,
i
ti
s
n
’
tp
os
s
i
b
l
et
o
accurately compare two local times from different time
zones, or made across a DST switch (consider for
example a country switching to DST, which has two
2am times while another country only has one).
Because of this ambiguity, times read from objects
such as certificates may be out by an hour or two.

Basic Certificate Management
Wi
t
ht
hei
nf
or
ma
t
i
onf
r
o
mt
h
epr
e
v
i
ouss
e
c
t
i
on,
i
t
’
sn
owp
os
s
i
b
l
et
os
t
a
r
tc
r
e
a
t
i
ng
basic certificate objects. To create a PKCS #10 certification request, you would do
the following:
CRYPT_CERTIFICATE cryptCertRequest;
void *certRequest;
int certRequestMaxLength, certRequestLength;
/* Create a certification request and add the public key to it */
cryptCreateCert( &cryptCertRequest, cryptUser,
CRYPT_CERTTYPE_CERTREQUEST );
cryptSetAttribute( cryptCertRequest,
CRYPT_CERTINFO_SUBJECTPUBLICKEYINFO, pubKeyContext );
/* Add identification information */
/* ... */

Basic Certificate Management

213

/* Sign the certification request with the private key and export it
*/
cryptSignCert( cryptCertRequest, privKeyContext );
cryptExportCert( NULL, 0, &certRequestMaxLength,
CRYPT_CERTFORMAT_CERTIFICATE, cryptCertRequest );
certRequest = malloc( certRequestMaxLength );
cryptExportCert( certRequest, certRequestMaxLength,
&certRequestLength, CRYPT_CERTFORMAT_CERTIFICATE, cryptCertRequest
);
/* Destroy the certification request */
cryptDestroyCert( cryptCertRequest );

This simply takes a public key, adds some identification information to it (the details
of this will be covered later), signs it, and exports the encoded certification request
for transmission to a CA. Since cryptlib will only copy across the appropriate key
c
o
mp
one
nt
s
,
t
he
r
e
’
snon
e
e
dt
oha
v
eas
e
p
a
r
a
t
ep
ub
l
i
ca
ndpr
i
v
a
t
ek
e
yc
ont
e
x
t
,
y
ou
c
a
na
ddt
hes
a
mepr
i
v
a
t
ek
e
yc
on
t
e
x
tt
h
a
ty
ou
’
l
lbeus
i
ngt
os
i
g
nt
hec
e
r
t
i
f
i
c
a
t
i
on
request to supply the CRYPT_CERTINFO_SUBJECTPUBLICKEYINFO
information and cryptlib will use the appropriate data from it.
To process the certification request and convert it into a certificate, the CA does the
following:
CRYPT_CERTIFICATE cryptCertificate, cryptCertRequest;
void *cert;
int certMaxLength, certLength;
/* Import the certification request and check its validity */
cryptImportCert( certRequest, certRequestLength, cryptUser,
&cryptCertRequest );
cryptCheckCert( cryptCertRequest, CRYPT_UNUSED );
/* Create a certificate and add the information from the certification
request to it */
cryptCreateCert( &cryptCertificate, cryptUser,
CRYPT_CERTTYPE_CERTIFICATE );
cryptSetAttribute( cryptCertificate, CRYPT_CERTINFO_CERTREQUEST,
cryptCertRequest );
/* Sign the certificate with the CA’s private key and export it */
cryptSignCert( cryptCertificate, caPrivateKey );
cryptExportCert( NULL, 0, &certMaxLength,
CRYPT_CERTFORMAT_CERTIFICATE, cryptCertificate );
cert = malloc( certMaxLength );
cryptExportCert( cert, certMaxLength, &certLength,
CRYPT_CERTFORMAT_CERTIFICATE, cryptCertificate );
/* Destroy the certificate and certification request */
cryptDestroyCert( cryptCertificate );
cryptDestroyCert( cryptCertRequest );

In this case the CA has put together a minimal certificate that can be processed by
most software but which is rather limited in the amount of control that the CA and
end user has over the certificate, since no specific control information has been added
to the certificate. By default cryptlib adds the necessary fields for a full X.509v3
certificate, but t
hi
swon
’
tc
o
nt
a
i
na
l
lt
hei
n
f
or
ma
t
i
ont
ha
twoul
dbea
v
a
i
l
a
bl
ei
ft
heCA
explicitly handles the fields for the certificate itself. Creating full X.509v3
certificates involves the use of certificate extensions and is covered in more detail
later.
To check the signed certificate returned from the CA and add it to a keyset, the user
does the following:
CRYPT_CERTIFICATE cryptCertificate;
/* Import the certificate and check its validity */
cryptImportCert( cert, certLength, cryptUser, &cryptCertificate );
cryptCheckCert( cryptCertificate, caCertificate );
/* Add the certificate to a keyset */
/* ... */

214

Certificates in Detail

/* Destroy the certificate */
cryptDestroyCert( cryptCertificate );

To obtain information about the key contained in a certificate you can read the
appropriate attributes just like an encryption context, for example
CRYPT_CTXINFO_ALGO will return the encryption/signature algorithm type,
CRYPT_CTXINFO_NAME_ALGO will return the algorithm name, and
CRYPT_CTXINFO_KEYSIZE will return the key size.

Certificate Identification Information
Traditionally, certificate objects have been identified by a construct called an X.500
Distinguished Name (DN). In ISO/ITU terminology, the DN defines a path through
an X.500 directory information tree (DIT) via a sequence of Relative Distinguished
Name (RDN) components which in turn consist of a set of one or more Attribute
Value Assertions (AVAs) per RDN. The description then goes on in this manner for
another hundred-odd pages, and includes diagrams that are best understood when
held upside down in front of a mirror.
To keep things manageable, cryptlib goes to some lengths to hide the complexity
involved by handling the processing of DNs for you. A cryptlib DN can contain the
following text string components:
Component

Description

CountryName (C)

The two-letter international country code (specified
in ISO 3166 in case you ever need to look it up).
Ex
a
mp
l
e
so
fc
o
un
t
r
yc
ode
sa
r
e‘
US’a
n
d‘
NZ’
.You
can specify the country with
CRYPT_CERTINFO_COUNTRYNAME.
This is a field that you must fill in.

Organization (O)

The organisation for which the certificate will be
i
s
s
ue
d.Ex
a
mpl
e
so
for
g
a
ni
s
a
t
i
o
nsa
r
e‘
Mi
c
r
os
o
f
t
Cor
por
a
t
i
on
’a
n
d‘
Ve
r
i
s
i
g
n,
I
nc
’
.Youc
a
ns
p
e
c
i
f
y
the organisation with CRYPT_CERTINFO_ORGANIZATIONNAME.

OrganisationalUnitName (OU)

The division of the organisation for which the
certificate will be issued. Examples of
or
g
a
ni
s
a
t
i
o
na
lun
i
t
sa
r
e‘
Sa
l
e
sa
ndMa
r
k
e
t
i
ng
’a
nd
‘
Pur
c
h
a
s
i
ng
’
.Youc
a
ns
p
e
c
i
f
yt
heor
g
a
ni
s
a
t
i
o
na
l
unit with CRYPT_CERTINFO_ORGANIZATIONALUNITNAME.

StateOrProvinceName The state or province in which the certificate owner
(SP)
is located. Examples of state or province names are
‘
Ut
a
h
’
,
‘
St
e
y
r
ma
r
k
’
,
a
n
d‘
PuydeDôme
’
.Youc
a
n
specify the state or province with CRYPT_CERTINFO_STATEORPROVINCENAME.
LocalityName (L)

The locality in which the certificate owner is
l
oc
a
t
e
d.Ex
a
mpl
e
so
fl
o
c
a
l
i
t
i
e
sa
r
e‘
Sa
nJ
os
e
’
,
‘
Se
y
di
s
f
j
ör
dur
’
,
a
nd‘
Mön
c
he
ng
l
a
dba
c
h’
.Youc
a
n
specify the locality with CRYPT_CERTINFO_LOCALITYNAME.

CommonName (CN)

The name of the certificate owner, which can be
e
i
t
he
rape
r
s
o
ns
uc
ha
s‘
J
o
hnDoe
’
,
ab
us
i
n
e
s
sr
ol
e
s
uc
ha
s‘
Ac
c
o
un
t
sMa
n
a
g
e
r
’
,ore
v
e
na
ne
nt
i
t
yl
i
k
e
‘
La
s
e
rPr
i
nt
e
r#6
’
.Youc
a
ns
pe
c
i
f
yt
h
ec
o
mmo
n
name with CRYPT_CERTINFO_COMMONNAME.

Certificate Identification Information

Component

215

Description
This is a field that you must fill in.

All DN components except the country name are limited to a maximum of 64
characters (this is a requirement of the X.500 standard that defines the certificate
format and use). cryptlib provides the CRYPT_MAX_TEXTSIZE constant for this
limit. Note that this defines the number of characters and not the number of bytes, so
that a Unicode string could be several times as long in bytes as it would be in
characters, depending on which data type the system uses to represent Unicode
characters.
The complete DN can be used for a personal key used for private purposes (for
example to perform home banking or send private email) or for a key used for
business purposes (for example to sign business agreements). The difference
between the two key types is that a personal key will identify someone as a private
individual, whereas a business key will identify someone terms of the organisation for
which they work.
A DN must always contain a country name and a common name, and should
generally also contain one or more of the other c
o
mp
one
nt
s
.I
faDNdoe
s
n
’
tc
on
t
a
i
n
at least the two minimum components, cryptlib will return CRYPT_ERROR_NOTINITED with an extended error indicating the missing component when you try
to sign the certificate object.
Realising that DNs are too complex and specialised to handle many types of current
certificate usage, more recent revisions of the X.509 standard were extended to
include a more generalised name format called a GeneralName, which is explained in
mor
ede
t
a
i
li
n“
Extended Certificate Identification Information”onpa
g
e219.

DN Structure for Business Use
For business use, the DN should include the country code, the organisation name, an
optional organisational unit name, and the common name. An example of a DN
structured for business use would be:
C = US
O = Cognitive Cybernetics Incorporated
OU = Research and Development
CN = Paul Johnson
This is a key which is used by an individual within an organisation. It might also
describe a role within the organisation, in this case a class of certificate issuer in a
CA:
C = DE
O = Kommunikationsnetz Franken e.V. Certification Authority
CN = Class 1 CA
It might even describe an entity with no direct organisational role:
C = AT
O = Erste Allgemeine Verunsicherung
CN = Mail Gateway
In this last case the certificate might be used by the mail gateway machine to
authenticate data transmitted through it.

DN Structure for Private Use
For private, non-business use, the DN should include the country code, an optional
state or province name, the locality name, and the common name. An example of a
DN structured for private use would be:
C = US
SP = California
L = El Cerrito
CN = Dave Taylor

216

Certificates in Detail

DN Structure for Use with a Web Server
For use with a web server the DN should include whatever is appropriate for the
country and state, province, or organisation, and the domain name of the web server
as the common name. An example of a DN for a web server certificate for the server
www.servername.com, used by the organisation given in the earlier example,
would be:
C = US
O = Cognitive Cybernetics Incorporated
OU = Research and Development
CN = www.servername.com

Other DN Structures
I
t
’
sa
l
s
opos
s
i
bl
et
oc
o
mb
i
nec
o
mp
one
nt
so
ft
hea
bov
eDNs
t
r
uc
t
ur
e
s
,
f
ore
x
a
mpl
ei
f
an organisation has divisions in multiple states you might want to include the state or
province name component in the DN:
C = US
SP = Michigan
O = Last National Bank
CN = Personnel Manager
Another example would be:
C = US
L = Area 51
O = Hanger 18
OU = X.500 Standards Designers
CN = John Doe

Working with Distinguished Names
Now that the details of DNs have been covered, you can use them to add
identification information to certification requests and certificates. For example to
add the business DN shown earlier to a certification request you would use:
CRYPT_CERTIFICATE cryptCertRequest;
/* Create certification request and add other components */
/* ... */
/* Add identification information */
cryptSetAttributeString( cryptCertRequest, CRYPT_CERTINFO_COUNTRYNAME,
"US", 2 );
cryptSetAttributeString( cryptCertRequest,
CRYPT_CERTINFO_ORGANIZATIONNAME, "Cognitive Cybernetics
Incorporated", 34 );
cryptSetAttributeString( cryptCertRequest,
CRYPT_CERTINFO_ORGANIZATIONALUNITNAME, "Research and Development",
24 );
cryptSetAttributeString( cryptCertRequest, CRYPT_CERTINFO_COMMONNAME,
"Paul Johnson", 12 );
/* Sign certification request and transmit to CA */
/* ... */

The same process applies for adding other types of identification information to a
certification request or certificates. Note that cryptlib sorts the DN components into
t
hec
or
r
e
c
tor
d
e
rwhe
ni
tc
r
e
a
t
e
st
hec
e
r
t
i
f
i
c
a
t
i
onr
e
q
ue
s
torc
e
r
t
i
f
i
c
a
t
e
,
s
ot
he
r
e
’
sno
need to specify them in strict order as in the above code.
By default, cryptlib will work with the subject name, if you want to access the issuer
name you need to select it first so that DN components can be read from it instead of
the subject name (issuer names are only present in some certificate object types, for
example the certification request a
b
ov
edoe
s
n
’
tc
o
nt
a
i
na
ni
s
s
ue
rna
me
)
.Tot
e
l
l
cryptlib to use the issuer name, you set the currently active DN attribute to the issuer
name:

Certificate Identification Information

217

cryptSetAttribute( certificate, CRYPT_CERTINFO_ISSUERNAME,
CRYPT_UNUSED );

Since there are no arguments to this selection attribute, the value that you supply is
s
e
tt
oCRYPT_UNUSED.Onc
ey
ou
’
v
es
e
l
e
c
t
e
dadi
f
f
e
r
e
n
tDNi
nt
hi
sma
n
ne
r
,
i
t
remains selected until you select a different one, so if you wanted to move back to
wor
k
i
ngwi
t
ht
hes
u
bj
e
c
tn
a
mey
ou’
dne
e
dt
ous
e:
cryptSetAttribute( certificate, CRYPT_CERTINFO_SUBJECTNAME,
CRYPT_UNUSED );

otherwise attempts to query further DN attributes will apply to the selected issuer
name attribute instead of the subject name.

Creating Customised DNs
Although the DN-handling mechanisms provided by cryptlib are extremely flexible,
they enforce a few restrictions on the format of the DN to ensure that the resulting
value can be processed properly by other applications. Sometimes it may be
necessary to create customised, non-standard DNs for certain applications that require
an unusual DN structure or the use of odd DN components. cryptlib allows the
creation of arbitrary DNs by specifying them as a string representation of the
complete DN, identified by CRYPT_CERTINFO_DN. The following section is
intended for advanced users and assumes some knowledge of X.500 terminology.
Complete DNs are specified using the LDAP-style string representation of the DN
t
ha
tc
o
nt
a
i
nso
neormor
e“
l
a
be
l=v
a
l
u
e
”pa
i
r
ss
pe
c
i
f
y
i
ngaDNc
omp
one
nta
ndits
value, for example the DN:
C = US
O = Cognitive Cybernetics Incorporated
OU = Research and Development
CN = Paul Johnson
t
ha
twa
sus
e
de
a
r
l
i
e
rwou
l
db
er
e
pr
e
s
e
n
t
e
di
ns
t
r
i
ngf
or
ma
s“
c
n=Pa
u
lJ
oh
ns
o
n,
ou=Research and Development, o=Cognitive Cybernetics I
nc
or
p
or
a
t
e
d,
c
=US”
,
wi
t
h
each RDN being separated by a comma. Note that the encoding of the RDNs in the
string is backwards, this is a requirement of the LDAP DN string format. To set the
DN for the previous certificate request in one step using a DN string you would use:
CRYPT_CERTIFICATE cryptCertRequest;
/* Create certification request and add other components */
/* ... */
/* Add identification information */
cryptSetAttributeString( cryptCertRequest, CRYPT_CERTINFO_DN, "cn=Paul
Johnson, ou=Research and Development, o=Cognitive Cybernetics
Incorporated, c=US", 88 );
/* Sign certification request and transmit to CA */
/* ... */

This sets the entire DN at once rather than setting it component by component. Once
y
ou’
v
es
e
tt
heDNi
nt
h
i
sma
n
ne
ry
ouc
a
n’
tmod
i
f
yorde
l
e
t
ea
nyc
o
mp
one
nt
sbe
c
a
us
e
cryptlib preserves the exact ordering and format of the DN components, an ordering
that would be destroyed with some of the more complex DNs that will be presented
further down. You can also obtain the complete DN in string form by reading the
value of this attribute.
The string DN form contains a number of special-case characters that are used to
break up the RDNs and AVAs, if you want to use these in a DN component you need
t
oe
s
c
a
pet
he
m wi
t
h‘
\’s
ot
ha
tf
ore
x
a
mp
l
e‘
c
n=a=b
’wo
ul
dbes
pe
c
i
f
i
e
da
s‘
c
n=a\=
b’
.c
r
y
pt
l
i
bwi
l
la
ut
o
ma
t
i
c
a
l
l
ya
ddt
he
s
ee
s
c
a
pes
e
q
ue
nc
e
st
ot
heDNc
ompo
ne
n
t
si
f
required when you read the attribute value.
The example shown above will result in the creation of a DN which is no different to
one created in the usual manner, however since the DN string can contain arbitrary
nu
mb
e
r
sofRDNsi
na
r
b
i
t
r
a
r
yor
de
r
,
i
t
’
spos
s
i
bl
et
oc
r
e
a
t
eDNst
ha
twoul
dn
’
tbe

218

Certificates in Detail
pos
s
i
bl
ei
nt
heus
ua
lma
nne
r
.Fore
x
a
mpl
et
oa
ddas
e
c
on
dOU“
AILa
b”t
ot
heDN
givena
bov
ey
ouwo
ul
ds
pe
c
i
f
yt
heDNa
s“
c
n=Pa
ulJ
o
hns
o
n,
ou=Re
s
e
a
r
c
ha
n
d
De
v
e
l
op
me
nt
,
o
u=AILa
b,
o=Cog
ni
t
i
v
eCy
be
r
n
e
t
i
c
sI
nc
or
p
or
a
t
e
d,
c
=US”
.Not
e
a
g
a
i
nt
heba
c
k
wa
r
dse
nc
o
di
n
g
,
whi
c
hme
a
nst
ha
t“
AILa
b”oc
c
ur
sh
i
g
he
rupi
nt
he
hi
e
r
a
r
c
hyt
ha
n“
Re
s
e
a
r
c
ha
ndDe
v
e
l
op
me
n
t
”e
v
e
nt
h
oug
hi
tc
o
me
sa
f
t
e
ri
ti
nt
heDN
string.
I
t
’
sa
l
s
opos
s
i
bl
et
og
r
oupmu
l
t
i
pl
eAVAsi
nt
oa
nRDNbyc
on
ne
c
t
i
ngt
he
m wi
t
ha‘
+’
i
ns
t
e
a
do
ft
heus
ua
lc
o
mma
,
f
ore
x
a
mp
l
et
oa
d
dPa
ulJ
o
hns
on
’
ss
e
r
i
a
lnu
mb
e
rt
ot
he
a
bov
eDNy
ouwoul
dus
e“
c
n
=Pa
ul Johnson + sn=12345678, ou=Research and
De
v
e
l
op
me
nt
,
o=Cog
ni
t
i
v
eCy
be
r
ne
t
i
c
sI
nc
or
por
a
t
e
d,
c
=US”
.Onc
ee
nc
o
de
di
nt
he
certificate, the final RDN will contain two AVAs, one with the common name and
the other with the serial number.
The labels that are used to identify DN components are:
Label

Component

businessCategory

countryName

commonName

Description

domainComponent

emailAddress (PKCS #9)

givenName

Initials

isdn

internationalISDNNumber

Locality

organisationName

organisationalUnitName

Surname

serialNumber

stateOrProvinceName

streetAddress

Title

There exist many more DN components beyond those shown in the table above, but
l
a
be
l
sf
ort
he
m we
r
ene
v
e
rde
f
i
ne
da
ndi
t
’
sne
c
e
s
s
a
r
yt
or
e
f
e
rt
ot
h
e
mbyobject
identifier with the prefix oid. to denote the use of an OID rather than a text label.
The remaining DN components and their OID labels are aliasObjectName,
oid.2.5.4.1, communicationsNetwork oid.2.5.4.67,
communicationsService oid.2.5.4.66, destinationIndicator, oid.2.5.4.27,
distinguishedName, oid.2.5.4.49, dnQualifier, oid.2.5.4.46,
facsimileTelephoneNumber, oid.2.5.4.23, generationQualifier,
oid.2.5.4.44, houseIdentifier, oid.2.5.4.51, knowledgeInformation,
oid.2.5.4.2, member, oid.2.5.4.31, name, oid.2.5.4.41,
nameDistinguisher, oid.0.2.262.1.10.7.20, owner, oid.2.5.4.32,
physicalDeliveryOfficeName, oid.2.5.4.19, postalAddress, oid.2.5.4.16,
postalCode, oid.2.5.4.17, postOfficeBox, oid.2.5.4.18,
preferredDeliveryMethod, oid.2.5.4.28, presentationAddress,
oid.2.5.4.29, pseudonym oid.2.5.4.65, registeredAddress,
oid.2.5.4.26, rfc822Mailbox, oid.0.9.2342.19200300.100.1.3,
roleOccupant, oid.2.5.4.33, searchGuide, oid.2.5.4.14, seeAlso,

Extended Certificate Identification Information

219

oid.2.5.4.34, supportedApplicationContext, oid.2.5.4.30, telephoneNumber, oid.2.5.4.20, telexNumber, oid.2.5.4.21, teletexTerminalIdentifier, oid.2.5.4.22, uniqueIdentifier, oid.2.5.4.45, uniqueMember,
oid.2.5.4.50, userid, oid.0.9.2342.19200300.100.1.1, and
x121Address, oid.2.5.4.24.
Note that a number of different and often incompatible naming schemes for X.500
attributes exist. X.500 only defined a handful of names, and as a result many other
standards and implementations invented their own, a number of which conflict with
each other, and several of which conflict with the original X.500 names. cryptlib uses
the names that are most widely used with certificates. Since many of the names used
bydi
f
f
e
r
e
nts
t
a
nd
a
r
dsc
o
n
f
l
i
c
t
,
i
t
’
sn
otp
os
s
i
b
l
et
oha
v
ec
r
y
p
t
l
i
bha
nd
l
emul
t
i
pl
e
aliases for the same attribute, however if you require custom names to conform to a
particular standard or interpretation of a standard, you can change the values in the
code to reflect whatever names you want.
The CRYPT_CERTINFO_DN provides a powerful means of creating completely
custom DNs, not
et
h
oug
ht
ha
tt
hi
sc
a
nr
e
s
ul
ti
nDNst
ha
tc
a
n’
tbec
or
r
e
c
t
l
ypr
o
c
e
s
s
e
d
or displayed by many applications, so you should only create non-standard DNs in
t
hi
sma
nne
rwhe
r
ei
t
’
sa
bs
o
l
u
t
e
l
yne
c
e
s
s
a
r
y
.

Extended Certificate Identification Information
In the earl
yt
omi
d1
99
0
’
swhe
ni
tbe
c
a
mec
l
e
a
rt
ha
tt
heI
n
t
e
r
ne
twa
sg
oi
ngt
obet
he
driving force behind certificate technology, X.509 was amended to allow a more
general-purpose type of identification than the complex and specialised DN. This
new form was called the GeneralName, since it provided far more flexibility than the
original DN. A GeneralName can contain an email address, a URL, an IP address, an
a
l
t
e
r
na
t
i
v
eDNt
ha
tdo
e
s
n
’
tf
o
l
l
owt
hes
t
r
i
c
tr
ul
e
sf
ort
h
ema
i
nc
e
r
t
i
f
i
c
a
t
eDN(
i
tc
ou
l
d
for example contain a postal or street address), less useful components like X.400 and
EDI addressing information, and even user-defined information that might be used in
ac
e
r
t
i
f
i
c
a
t
e
,
f
ore
x
a
mpl
eme
d
i
c
a
lpa
t
i
e
n
t
,
t
a
x
pa
y
e
r
,
ors
oc
i
a
ls
e
c
ur
i
t
yI
D’
s
.
As with DNs, cryptlib goes to some lengths to hide the complexity involved in
handling GeneralNames (recall the previous technical description of a DN, and then
consider that this constitutes only a small portion of the entire GeneralName). Like a
DN, a GeneralName can contain a number of components. Unless otherwise noted,
the components are all text strings.
Component

Description

DirectoryName

A DN that can contain supplementary information
t
ha
tdo
e
s
n
’
tf
i
te
a
s
i
l
yi
n
t
ot
hema
i
nc
e
r
t
i
f
i
c
a
t
eDN.
You can specify this value with CRYPT_CERTINFO_DIRECTORYNAME.

DNSName

AnI
nt
e
r
ne
thos
t
’
sf
u
l
l
y
-qualified domain name.
You can specify this value with CRYPT_CERTINFO_DNSNAME.

EDIPartyName.NameAssigner
EDIPartyName.PartyName

An EDI assigner-and-value pair with the EDI name
assigner specified by CRYPT_CERTINFO_EDIPARTYNAME_NAMEASSIGNER and the
party name specified by CRYPT_CERTINFO_EDIPARTYNAME_PARTYNAME.

IPAddress

An IP address as per RFC 791, containing a 4-byte
binary string in network byte order. You can
specify this value with CRYPT_CERTINFO_IPADDRESS.

OtherName.TypeID
OtherName.Value

A user-defined type-and-value pair with the type
specified by CRYPT_CERTINFO_OTHERNAME_TYPEID and the value specified
by CRYPT_CERTINFO_OTHERNAME_VALUE.

220

Certificates in Detail

Component

Description
The type is an ISO object identifier and the
corresponding value is a binary string that can
contain anything, identified by the object identifier
(if you know what this is then you should also know
how to obtain one).

RegisteredID

An object identifier (again, if you know what this is
then you should know how to obtain one). You can
specify this value with CRYPT_CERTINFO_REGISTEREDID.

RFC822Name

An email address. You can specify this value with
CRYPT_CERTINFO_RFC822NAME. For
compatibility with the older (obsolete) PKCS #9
emailAddress attribute, cryptlib will also accept
CRYPT_CERTINFO_EMAIL to specify this field.

UniformResourceIdentifier

A URL for either FTP, HTTP, or LDAP access as
per RFC 1738. You can specify this value with
CRYPT_CERTINFO_UNIFORMRESOURCEIDENTIFIER.

Of the above GeneralName components, the most useful ones are the RFC822Name
(to specify an email address), the DNSName (to specify a server address), and the
UniformResourceIdentifier (to specify a web page or FTP server). Somewhat less
useful is the DirectoryName,
whi
c
hc
a
ns
p
e
c
i
f
ya
dd
i
t
i
o
na
li
nf
or
ma
t
i
ont
ha
tdo
e
s
n
’
tf
i
t
easily into the main certificate DN. The other components should be avoided unless
y
ouha
v
eag
oodr
e
a
s
ont
or
e
q
ui
r
et
h
e
m(
t
ha
ti
s
,
do
n’
tus
et
h
e
mj
us
tb
e
c
a
us
et
h
e
y
’
r
e
there).

Working with GeneralName Components
Now that the details of GeneralNames have been covered, you can use them to add
additional identification information to certificate requests and certificates. For
example to add an email address and home page URL to the certification request
shown earlier you would use:
CRYPT_CERTIFICATE cryptCertRequest;
/* Create certification request and add other components */
/* ... */
/* Add identification information */
/* ... */
/* Add additional identification information */
cryptSetAttributeString( cryptCertRequest, CRYPT_CERTINFO_RFC822NAME,
"paul@cci.com", 12 );
cryptSetAttributeString( cryptCertRequest,
CRYPT_CERTINFO_UNIFORMRESOURCEIDENTIFIER,
"http://www.cci.com/~paul", 23 );
/* Sign certification request and transmit to CA */
/* ... */

Although GeneralNames are commonly used to identify a certificates owner just like
a DN, they are in fact a certificate extension rather than a basic attribute. Each
certificate can contain multiple extensions that contain GeneralNames. The various
extens
i
onst
ha
tc
a
nc
on
t
a
i
nGe
ne
r
a
l
Na
me
sa
r
ec
ov
e
r
e
di
n“
Certificate Extensions”on
page 234,
a
n
dt
hede
t
a
i
l
sofwor
k
i
ngwi
t
ht
h
e
ma
r
ee
x
pl
a
i
ne
di
n“
Composite
Extension Attributes”on page 237.

Certificate Fingerprints
Ce
r
t
i
f
i
c
a
t
e
sa
r
es
o
me
t
i
me
si
d
e
nt
i
f
i
e
dt
hr
o
ug
h“
f
i
ng
e
r
pr
i
nt
s
”t
ha
tc
o
ns
t
i
t
u
t
ee
i
t
he
ra
n
MD5 or SHA-1 hash of the certificate data (the most common form is an MD5 hash).
You can obtain a certi
f
i
c
a
t
e
’
sf
i
ng
e
r
pr
i
ntbyr
e
a
di
ngi
t
sCRYPT_CERTI
NFO_-

Importing/Exporting Certificates

221

FINGERPRINT attribute, which yields the default (MD5) fingerprint for the
certificate. You can also explicitly query a particular fingerprint type with CRYPT_CERTINFO_FINGERPRINT_MD5 and CRYPT_CERTINFO_FINGERPRINT_SHA:
unsigned char fingerprint[ CRYPT_MAX_HASHSIZE ]
int fingerprintSize;
cryptGetAttributeString( certificate, CRYPT_CERTINFO_FINGERPRINT,
&fingerprint, &fingerprintSize );

This will return the certificate fingerprint.

Importing/Exporting Certificates
If you have an encoded certificate that was obtained elsewhere, you can import it into
a certificate object using cryptImportCert. There are more than a dozen mostly
incompatible formats for communicating certificates, of which cryptlib will handle all
the generally useful and known ones. This includes straight binary certification
requests, certificates, attribute certificates, and CRLs (usually stored with a .der file
extension when they are saved to disk), PKCS #7 certificate chains, and Netscape
certificate sequences. Certificates can also be protected with base64 armouring and
BEGIN/END CERTIFICATE delimiters, which is the format used by some web
browsers and other applications. When transferred via HTTP using the Netscapespecific format, certificates, certificate chains, and Netscape certificate sequences are
identified with have the MIME content types application/x-x509-usercert, application/x-x509-ca-cert, and application/x-x509email-cert, depending on the certificate type (cryptlib doe
s
n’
tus
et
heMI
ME
content type since the certificate itself provides a far more reliable indication of its
intended use than the easily-altered MIME content type).. Finally, certification
requests and certificate chains can be encoded with the MIME / S/MIME content
types application/pkcs-signed-data, application/x-pkcssigned-data, application/pkcs-certs-only, application/xpkcs-certs-only, application/pkcs10, or application/x-pkcs10.
These are usually stored with a .p7c extension (for pure certificate chains), a .p7s
extension (for signatures containing a certificate chain), or a .p10 extension (for
certification requests) when they are saved to disk.
cryptlib will import any of the previously described certificate formats if they are
encoded in this manner. To import a certificate object you would use:
CRYPT_CERTIFICATE cryptCertificate;
/* Import the certificate object from the encoded certificate */
cryptImportCert( cert, certLength, cryptUser, &cryptCertificate );

Note that the CRYPT_CERTIFICATE is passed to cryptImportCert by reference, as
the function modifies it when it creates the certificate object.
Some certificate objects may contain unrecognised critical extensions (certificate
e
x
t
e
ns
i
onsa
r
ec
ov
e
r
e
di
n“
Certificate Extensions”onpa
g
e234) which require that
the certificate be rejected by cryptlib. If a certificate contains an unrecognised critical
extension, cryptlib will return a CRYPT_ERROR_PERMISSION error to indicate
that you have no permission to use this object.
All the parameters and information needed to create the certificate object are a part of
the certificate, and cryptImportCert takes care of initialising the certificate object
and setting up the attributes and information inside it. The act of importing a
certificate simply decodes the information and initialises a certificate object, it
doe
s
n’
tc
h
e
c
kt
hes
i
g
na
t
ur
eo
nt
hec
e
r
t
i
f
i
c
a
t
e
.Toc
he
c
kt
h
ec
e
r
t
i
f
i
c
a
t
e
’
ss
i
g
na
t
ur
ey
ou
need to use cryptCheckCert, which is ex
pl
a
i
ne
di
n“
Signing/Verifying Certificates”
on page 223.
The
r
ema
ybei
ns
t
a
n
c
e
si
nwhi
c
hy
ou
’
r
en
ote
x
a
c
t
l
yc
e
r
t
a
i
noft
het
y
p
eofc
e
r
t
i
f
i
c
a
t
e
object you have imported (for example importing a file with a .der or .cer extension
could create a certificate request, a certificate, an attribute certificate, or a certificate

222

Certificates in Detail

chain object depending on the file contents). In order to determine the exact type of
the object, you can read its CRYPT_CERTINFO_CERTTYPE attribute:
CRYPT_CERTTYPE_TYPE certType;
cryptGetAttribute( certificate, CRYPT_CERTINFO_CERTTYPE, &certType );

This will return the type of the imported object.
You can export a signed certificate from a certificate object using cryptExportCert:
CRYPT_CERTIFICATE cryptCertificate;
void *certificate;
int certLength
/* Allocate memory for the encoded certificate */
certificate = malloc( certMaxLength );
/* Export the encoded certificate from the certificate object */
cryptExportCert( certificate, certMaxLength, &certLength,
certFormatType, cryptCertificate );

cryptlib will export certificates in any of the formats in which it can import them.
The available certFormat types are:
Format Type

Description

CRYPT_CERTFORMAT_CERTCHAIN

A certificate encoded as a PKCS #7
certificate chain.

CRYPT_CERTFORMAT_CERTIFICATE

A certification request, certificate, or CRL in
binary data format. The certificate object is
encoded according to the ASN.1
distinguished encoding rules. This is the
normal certificate encoding format.

CRYPT_CERTFORMAT_TEXT_CERTCHAIN

As CRYPT_CERTFORMAT_CERTCHAIN
but with base64 armouring of the binary
data.

CRYPT_CERTFORMAT_TEXT_CERTIFICATE

As CRYPT_CERTFORMAT_CERTIFICATE but with base64 armouring
of the binary data.

If the object that y
ou
’
r
ee
x
por
t
i
ngi
sac
ompl
e
t
ec
e
r
t
i
f
i
c
a
t
ec
ha
i
nr
a
t
h
e
rt
ha
na
n
individual certificate then these options work somewhat differently. The details of
e
x
por
t
i
ngc
e
r
t
i
f
i
c
a
t
ec
ha
i
nsa
r
ec
ov
e
r
e
di
n“
Exporting Certificate Chains”o
npa
g
e
228.
The resulting encoded certificate is placed in the memory buffer pointed to by
certificate of maximum size certificateMaxLength, and the actual
length is stored in certLength. This leads to a small problem: How do you know
how big to make the buffer? The answer is to use cryptExportCert to tell you. If
you pass in a null pointer for certificate, the function will set certLength to
the size of the resulting encoded certificate, but not do anything else. You can then
use code like:
cryptExportCert( NULL, 0, &certMaxLength, certFormatType,
cryptCertificate );
certificate = malloc( certMaxLength );
cryptExportCert( certificate, certMaxLength, &certLength,
certFormatType, cryptCertificate );

to create the encoded certificate.
Alternatively, you can just reserve a reasonably sized block of memory and use that
t
oh
ol
dt
hee
nc
ode
dc
e
r
t
i
f
i
c
a
t
e
.“
Re
a
s
o
na
b
l
ys
i
z
e
d
”me
a
nsaf
e
wKb,
a4Kbl
oc
ki
s
plenty (a certificate for a 1024-bit key without certificate extensions is typically about
700 bytes long if encoded using any of the binary formats, or 900 bytes long if
encoded using any of the text formats).

Signing/Verifying Certificates

223

I
ft
hec
e
r
t
i
f
i
c
a
t
ei
sonet
ha
ty
ou’
v
ec
r
e
a
t
e
dy
o
ur
s
e
l
fr
a
t
he
rt
ha
ni
mpor
t
i
ngi
tf
r
o
ma
n
external source, you need to add various data items to the certificate and then sign it
before you can export it. If you try to export an incompletely prepared certificate
s
uc
ha
sac
e
r
t
i
f
i
c
a
t
ei
nwhi
c
hs
omer
e
qu
i
r
e
df
i
e
l
dsh
a
v
e
n
’
tbe
e
nf
i
l
l
e
di
noron
et
ha
t
ha
s
n
’
tbe
e
ns
i
g
ne
d,
cryptExportCert will return the error CRYPT_ERROR_NOTI
NI
TEDt
ot
e
l
ly
out
ha
tt
hec
e
r
t
i
f
i
c
a
t
ei
n
f
or
ma
t
i
onha
s
n’
tbe
e
nc
o
mpl
e
t
e
l
ys
e
t
up.

Signing/Verifying Certificates
Once a certificate object contains all the information you want to add to it, you need
to sign it in order to transform it into its final state in which the data in it can be
wr
i
t
t
e
nt
oak
e
y
s
e
t(
i
ft
heo
bj
e
c
t
’
sf
i
na
ls
t
a
t
ei
sak
e
yc
e
r
t
i
f
i
c
a
t
eorCAc
e
r
t
i
f
i
c
a
t
e
)or
exported from the object. Before you sign the certificate, the information within it
exists only in a very generic and indeterminate state. After signing it, the information
is turned into a fixed certificate, CA certificate, certification request, or CRL, and no
further changes can be made to it.
You can sign the information in a certificate object with cryptSignCert:
CRYPT_CONTEXT privKeyContext;
/* Sign the certificate object */
cryptSignCert( cryptCertificate, privKeyContext );

There are some restrictions on the types of keys that can be used to sign certificate
objects. These restrictions are imposed by the way in which certificates and
certificate-related items are encoded, and are as follows:
Certificate
Type

Can be Signed By

Attribute
certificate

Private key associated with an authority certificate.

Certificate

Private key associated with a CA certificate. This can also
be a self-signed (non-CA) certificate, but some software will
then decide that the resulting certificate is a CA certificate
e
v
e
nt
h
oug
hi
ti
s
n
’
t
.

CA certificate Private key associated with a CA certificate (when one CA
certifies another) or the private key from which the
certificate being signed was created (when the CA certifies
itself).
Certification
request

Private key associated with the certification request.

Certificate
chain

Private key associated with a CA certificate.

CRL

Private key associated with the CA certificate that was used
to issue the certificates that are being revoked.

OCSP request/ Private key associated with a certificate and authorised or
response
trusted to sign requests/responses.
In order to sign any type of certificate object other than a self-signed one, you must
use a private key belonging to a CA. This means that the certificate associated with
the signing key must have its CRYPT_CERTINFO_CA attribute set to true (a
nonzero value) and must have a key usage value that i
nd
i
c
a
t
e
st
ha
ti
t
’
sv
a
l
i
df
or
signing certificates (or CRLs if the object being signed is a CRL). If you try to sign
an object other than a self-signed certificate or cert request with a non-CA key,
cryptlib will return an error status indicating the nature of the problem. If the status is
CRYPT_ERROR_PARAM2,
t
hepr
i
v
a
t
ek
e
yy
ou’
r
eus
i
ngdoe
s
n’
tha
v
eac
e
r
t
i
f
i
c
a
t
e
a
s
s
oc
i
a
t
e
dwi
t
hi
t(
t
ha
ti
s
,
y
ou
’
r
et
r
y
i
ngt
os
i
g
nt
hec
e
r
t
i
f
i
c
a
t
ewi
t
har
a
wpr
i
v
a
t
ek
e
y
without an associated CA certificate). If the status is CRYPT_ERROR_INVALID,

224

Certificates in Detail
t
hek
e
yy
ou’
r
eus
i
ngdoe
s
n
’
tha
v
et
hea
bi
l
i
t
yt
os
i
g
nc
e
r
t
i
f
i
c
a
t
e
s
,
f
ore
x
a
mpl
ebe
c
a
us
e
i
ti
s
n
’
taCAk
e
yorbe
c
a
us
ei
tdoe
s
n
’
tc
o
nt
a
i
nak
e
yus
a
g
ev
a
l
uethat i
nd
i
c
a
t
e
st
h
a
ti
t
’
s
valid for signing certificates or CRLs. In the latter case you can read the CRYPT_ATTRIBUTE_ERRORTYPE and CRYPT_ATTRIBUTE_ERRORLOCUS attributes
t
og
e
tmor
ei
nf
or
ma
t
i
ona
bo
utt
hena
t
ur
eoft
hepr
obl
e
ma
sde
s
c
r
i
be
di
n“
Error
Handling”onpa
g
e282.
Some certificate objects (for example OCSP requests and responses) can have signing
certificate information included with the object, although by default only the
signature itself is included. You can specify the amount of information which is
included using the CRYPT_CERTINFO_SIGNATURELEVEL attribute. Setting this
to CRYPT_SIGNATURELEVEL_NONE (the default) includes only the signature,
setting it to CRYPT_SIGNATURELEVEL_SIGNERCERT includes the immediate
signing certificate, and setting it to CRYPT_SIGNATURELEVEL_ALL includes all
relevant information, for example the complete certificate chain. You should always
use the default signing level unless you specifically know that you need to provide
extra information such as signing certificates or a certificate chain.
Once a certificate item has been signed, it can no longer be modified or updated using
the usual certificate manipulation functions, and any attempt to update information in
it will return CRYPT_ERROR_PERMISSION to indicate that you have no
permission to modify the object. If you want to add or delete data to or from the
certificate item, you have to start again with a new certificate object. You can
determine whether a certificate item has been signed and can therefore no longer be
changed by reading its CRYPT_CERTINFO_IMMUTABLE attribute:
int isImmutable;
cryptGetAttribute( certificate, CRYPT_CERTINFO_IMMUTABLE,
&isImmutable );

If the result is set to true (a nonzero value), the certificate item can no longer be
changed.
I
fy
ou’
r
ec
r
e
a
t
i
ngas
e
l
f
-signed certificate signed by a raw private key with no
certificate information associated with it, you need to set the CRYPT_CERTINFO_SELFSIGNED attribute before you sign it otherwise cryptlib will flag the attempt to
sign using a non-certificate key as an error. Non-certificate private keys can only be
used to create self-signed certificates (if CRYPT_CERTINFO_SELFSIGNED is set)
or certification requests.
If the object being signed contains unrecognised extensions, cryptlib will not include
them in the signed object (signing extensions of unknown significance is a risky
practice for a CA, which in some jurisdictions can be held liable for any arising
problems). If you want to be able to sign unrecognised extensions, you can enable
this with the cryptlib configuration option CRYPT_OPTION_CERT_SI
GNUNRECOGNI
SEDATTRI
BUTESa
se
x
pl
a
i
n
e
di
n“
Working with
Configuration Options”o
npa
g
e274.
You can verify the signature on a certificate object using cryptCheckCert and the
public key or certificate corresponding to the private key that was used to sign the
certificate (you can also pass in a private key if you want, cryptCheckCert will only
use the public key components, although yous
hou
l
d
n’
tr
e
a
l
l
ybei
np
os
s
e
s
s
i
ono
f
s
ome
o
nee
l
s
e
’
spr
i
v
a
t
ek
e
y
)
.Tope
r
f
or
mt
hec
he
c
kus
i
ngapub
l
i
ck
e
yc
ont
e
x
ty
ou
’
d
use:
CRYPT_CONTEXT pubKeyContext;
/* Check the signature on the certificate object information using the
public key */
cryptCheckCert( cryptCertificate, pubKeyContext );

A signature check using a certificate is similar, except that it uses a certificate object
rather than a public key context.
If the certificate object is self-signed, you can pass in CRYPT_UNUSED as the
second parameter and cryptCheckCert will use the key contained in the certificate

Certificate Chains

225

object to check its validity. You can determine whether a certificate object is selfsigned by reading its CRYPT_CERTINFO_SELFSIGNED attribute. Certification
requests are always self-signed, and certificate chains count as self-signed if they
contain a self-signed top-level certificate that can be used to recursively check the rest
of the chain. If the certificate object is a CA certificate which is signing itself (in
ot
h
e
rwor
dsi
fi
t
’
sa self-signed certificate), you can also pass the certificate as the
second parameter in place of CRYPT_UNUSED, this has the same effect since the
certificate is both the signed and signing object.
If the certificate is invalid (for example because it has expired or because some
c
e
r
t
i
f
i
c
a
t
eus
a
g
ec
ons
t
r
a
i
nth
a
s
n’
tbe
e
nme
t
)
,
c
r
y
pt
l
i
bwi
l
lr
e
t
ur
nCRYPT_ERROR_I
NVALI
Dt
oi
ndi
c
a
t
et
ha
tt
hec
e
r
t
i
f
i
c
a
t
ei
s
n’
tv
a
l
i
d.Th
i
sv
a
l
uei
sr
e
t
ur
n
e
dr
e
g
a
r
dl
e
s
s
of whether the signature check succeeds or fails. You can find out the exact nature of
t
hepr
obl
e
m byr
e
a
di
ngt
hee
x
t
e
n
de
de
r
r
ora
t
t
r
i
b
ut
e
sa
se
x
pl
a
i
ne
di
n“
Error Handling”
on page 282.
If the signing/signature check key is stored in an encryption context with a certificate
associated with it or in a certificate, there may be constraints on the key usage that are
i
mpos
e
dbyt
h
ec
e
r
t
i
f
i
c
a
t
e
.I
ft
hek
e
yc
a
n
’
tb
eus
e
df
ort
hes
i
g
na
t
ur
eors
i
g
na
t
ur
e
check operation, the function will return CRYPT_ERROR_INVALID to indicate that
t
hek
e
yi
s
n’
tv
a
l
i
df
ort
hi
so
pe
r
a
t
i
o
n.Youc
a
nf
i
ndo
utmor
ea
bo
utt
hee
x
a
c
tna
t
ur
eo
f
t
hepr
obl
e
m byr
e
a
di
ngt
hee
x
t
e
n
de
de
r
r
ora
t
t
r
i
b
ut
e
sa
se
x
pl
a
i
ne
di
n“
Error Handling”
on page 282.
I
fy
ou’
r
ea
c
t
i
nga
saCAa
ndi
s
s
ui
ngs
i
g
ni
f
i
c
a
n
tnu
mbe
r
so
fc
e
r
t
i
f
i
c
a
t
e
st
he
namuc
h
easier alternative to signing each certificate yourself using cryptSignCert is to use
c
r
y
pt
l
i
b’
sc
e
r
t
i
f
i
c
a
t
ema
na
g
e
me
ntc
a
pa
bi
l
i
t
i
e
sa
sde
s
c
r
i
be
di
n“
Managing a
Certification Authority”o
np
a
g
e171.

Certificate Chains
Because of the lack of availability of a general-purpose certificate directory, many
security protocols (most notable S/MIME and SSL) transmit not individual
certificates but entire certificate chains that contain a complete certificate path from
t
hee
ndus
e
r
’
sc
e
r
t
i
f
i
c
a
t
eu
pt
os
o
mewi
de
l
y
-trusted CA certificate (referred to as a
r
ootCAc
e
r
t
i
f
i
c
a
t
ei
fi
t
’
sas
e
l
f
-signed CA certificate) whose trust will be handled for
y
oubyc
r
y
pt
l
i
b’
st
r
us
tma
n
a
g
e
r
.c
r
y
pt
l
i
bs
u
pp
or
t
st
hec
r
e
a
t
i
on,
i
mpor
t
,
e
x
p
or
t
,
a
nd
checking of certificate chains as CRYPT_CERTTYPE_CERTCHAIN objects, with
individual certificates in the chain being accessed as if they were standard certificates
contained in a CRYPT_CERTTYPE_CERTIFICATE object.

Working with Certificate Chains
Individual certificates in a chain are addressed through a certificate cursor that
f
u
nc
t
i
o
nsi
nt
hes
a
mewa
ya
st
hea
t
t
r
i
but
ec
ur
s
ord
i
s
c
us
s
e
di
n“
Attribute Lists and ”
on page 37. Although a certificate chain object appears as a single object, it consists
i
nt
e
r
na
l
l
yofac
ol
l
e
c
t
i
o
no
fc
e
r
t
i
f
i
c
a
t
e
so
fwhi
c
ht
h
ef
i
r
s
ti
nt
hec
ha
i
ni
st
hee
n
dus
e
r
’
s
certificate and the last is a root CA certificate or at least an implicitly trusted CA
certificate.
You can move the certificate cursor using the CRYPT_CERTINFO_CURRENT_CERTIFICATE attribute and the standard cursor movement codes. For example to
move the cursor to the first (end-user) certificate in the chain, you would use:
cryptSetAttribute( certificate, CRYPT_CERTINFO_CURRENT_CERTIFICATE,
CRYPT_CURSOR_FIRST );

To advance the cursor to the next certificate, you would use:
cryptSetAttribute( certificate, CRYPT_CERTINFO_CURRENT_CERTIFICATE,
CRYPT_CURSOR_NEXT );

The certificate cursor and the extension/extension attribute cursor are two completely
independent objects, so moving the certificate cursor from one certificate to another
doe
s
n’
ta
f
f
e
c
tt
hee
x
t
e
ns
i
onc
ur
s
ors
e
t
t
i
ng for each certificate. If you select a
particular extension in a certificate, then move to a different certificate and select an

226

Certificates in Detail

extension in that, and then move back to the first certificate, the original extension
will still be selected.
Onc
ey
ou
’
v
es
e
lected a particular certificate in the chain, you can work with it as if it
were the only certificate contained in the certificate object. The initially selected
c
e
r
t
i
f
i
c
a
t
ei
st
hee
ndus
e
r
’
sc
e
r
t
i
f
i
c
a
t
ea
tt
hes
t
a
r
toft
hec
ha
i
n.Fore
x
a
mpl
et
or
e
a
d
the c
o
mmonNa
mef
r
o
mt
hes
ubj
e
c
tna
mef
ort
h
ee
n
dus
e
r
’
sc
e
r
t
i
f
i
c
a
t
ea
n
df
ort
h
e
next certificate in the chain you would use:
char commonName[ CRYPT_MAX_TEXTSIZE + 1 ];
int commonNameLength;
/* Retrieve the commonName from the end user's certificate */
cryptGetAttributeString( cryptCertChain, CRYPT_CERTINFO_COMMONNAME,
commonName, &commonNameLength );
commonName[ commonNameLength ] = '\0';
/* Move to the next certificate in the chain */
cryptSetAttribute( cryptCertChain, CRYPT_CERTINFO_CURRENT_CERTIFICATE,
CRYPT_CURSOR_NEXT );
/* Retrieve the commonName from the next certificate */
cryptGetAttributeString( cryptCertChain, CRYPT_CERTINFO_COMMONNAME,
commonName, &commonNameLength );
commonName[ commonNameLength ] = '\0';

Apart from this, certificate chains work just like certificates — you can import them,
export them, verify the signatures on them (which verifies the entire chain of
certificates until a trusted certificate is reached), and write them to and read them
from a keyset in exactly the same manner as an individual certificate.

Signing Certificate Chains
When you sign a single subject certificate using cryptSignCert, a small amount of
information is copied from the signing certificate (the issuer cert) to the subject
certificate as part of the signing process, and the result is a single, signed subject
certificate. In contrast signing a single subject certificate contained in a certificate
chain object results in the signing certificates (either a single issuer certificate or an
entire chain of certificates) being copied over to the certificate chain object so that the
signed certificate ends up as part of a complete chain. The exact details are as
follows:
Object to sign

Signing object

Result

Certificate

Certificate chain

Certificate

Certificate chain

Certificate

Certificate chain, length = 2

Certificate chain

Certificate chain, length =
length of signing chain + 1

For example the following code produces a single signed certificate:
CRYPT_CERTIFICATE cryptCertificate;
/* Build a certificate from a cert request */
cryptCreateCert( &cryptCertificate, cryptUser,
CRYPT_CERTTYPE_CERTIFICATE );
cryptSetAttribute( cryptCertificate, CRYPT_CERTINFO_CERTREQUEST,
cryptCertRequest );
/* Read a private key with cert chain from a private key keyset */
/* ... */
/* Sign the certificate */
cryptSignCert( cryptCertificate, caPrivateKey );

In contrast the following code produces a complete certificate chain, since the object
being created is a CRYPT_CERTTYPE_CERTCHAIN (which can hold a complete

Certificate Chains

227

chain) rather than a CRYPT_CERTTYPE_CERTIFICATE (which only holds a single
certificate):
CRYPT_CERTIFICATE cryptCertChain;
/* Build a certificate from a cert request */
cryptCreateCert( &cryptCertChain, cryptUser,
CRYPT_CERTTYPE_CERTCHAIN );
cryptSetAttribute( cryptCertChain, CRYPT_CERTINFO_CERTREQUEST,
cryptCertRequest );
/* Read a private key with cert chain from a private key keyset */
/* ... */
/* Sign the certificate chain */
cryptSignCert( cryptCertChain, caPrivateKey );

By specifying the object type to be signed, you can choose between creating a single
signed certificate or a complete certificate chain.

Checking Certificate Chains
When verifying a certificate chain with cryptCheckCert,
youd
on
’
tha
v
et
os
u
pp
l
y
an issuer certificate since the chain should contain all the issuer certificates up to one
which is trusted by cryptlib:
CRYPT_CERTIFICATE cryptCertChain;
/* Verify an entire cert chain */
cryptCheckCert( cryptCertChain, CRYPT_UNUSED );

As with self-signed certificates, you can also pass in the certificate chain as the
signing certificate instead of using CRYPT_UNUSED, this has the same effect since
the certificate chain is both the signed and signing object.
If a certificate in the chain is invalid or the cha
i
nd
oe
s
n’
tc
o
nt
a
i
nat
r
us
t
e
dc
e
r
t
i
f
i
c
a
t
e
at some point in the chain, cryptlib will return an appropriate error code and leave the
invalid certificate as the currently selected one, allowing you to obtain information
about the nature of the problem by reading the extended error attributes as explained
i
n“
Error Handling”onp
a
g
e282.
I
ft
hee
r
r
ore
n
c
o
un
t
e
r
e
di
st
hef
a
c
tt
ha
tt
h
ec
ha
i
ndoe
s
n’
tc
o
nt
a
i
nat
r
us
t
e
dc
e
r
t
i
f
i
c
a
t
e
somewhere along the line, cryptlib will either mark the top-level certificate as having
ami
s
s
i
ngCRYPT_CERTI
NFO_TRUSTED_I
MPLI
CI
Ta
t
t
r
i
but
ei
fi
t
’
saCAr
oot
c
e
r
t
i
f
i
c
a
t
e(
t
ha
ti
s
,
t
he
r
e
’
sar
o
otc
e
r
t
i
f
i
c
a
t
epr
e
s
e
ntb
uti
ti
s
n
’
tt
r
us
t
e
d)orma
r
kt
he
chain as a whole as having a missing certifica
t
ei
ft
he
r
e
’
sn
oCAr
ootc
e
r
t
i
f
i
c
a
t
e
present and no trusted certificate present either. Certificate trust management is
e
x
pl
a
i
ne
di
nmor
ede
t
a
i
li
n“
Certificate Trust Management”onpa
g
e231.
Certificate chain validation is an extremely complex process that takes into account
an enormous amount of validation information that may be spread across an entire
certificate chain. For example in a chain of 10 certificates, the 3 rd certificate from the
root may pl
a
c
eac
o
ns
t
r
a
i
n
tt
h
a
tdo
e
s
n
’
tt
a
k
ee
f
f
e
c
tun
t
i
lt
h
e7th certificate from the
r
ooti
sr
e
a
c
he
d.Be
c
a
us
eo
ft
hi
s
,
ar
e
por
t
e
dv
a
l
i
da
t
i
o
npr
o
b
l
e
mi
s
n
’
tn
e
c
e
s
s
a
r
yr
e
l
a
t
e
d
to a given certificate and its immediate issuing certificate, but may have been caused
by a different certificate a number of steps further along the chain.
Some certificate chains contain CA certificates that specify certificate policies. By
de
f
a
u
l
tc
r
y
pt
l
i
br
e
qui
r
e
st
ha
tapol
i
c
yt
ha
t
’
ss
e
tbyaCAi
sma
t
c
h
e
dbyt
h
ec
e
r
t
i
f
i
c
a
t
e
s
that the CA issues (in other words the CA sets policies for certificates further down
the chain). If you want to allow policies to change going down the chain once the CA
has set them, you can set the CRYPT_OPTION_CERT_REQUIREPOLICY option to
f
a
l
s
e(
0)
.Whe
ni
t
’
ss
e
tt
ot
h
i
sv
a
l
uec
r
y
pt
l
i
bwon
’
tv
e
r
i
f
yt
ha
tp
ol
i
c
i
e
sma
t
c
hupa
si
t
g
oe
sdownt
hec
h
a
i
n.Youwoul
dn
’
tnor
ma
l
l
yne
e
dt
ous
et
hi
sc
o
n
f
i
g
ur
a
t
i
o
nop
t
i
on,
i
t
’
sus
e
dt
opr
ov
i
dea
nop
t
i
on
a
lc
a
p
a
b
i
l
i
t
yt
ha
t
’
sc
ov
e
r
e
di
ns
omec
e
r
t
i
f
i
c
a
t
es
t
a
n
da
r
ds
documents.
Some certificate chains may not contain or be signed by a trusted CA certificate, but
may end in a root CA certificate with an unknown trust level. Since the cryptlib trust

228

Certificates in Detail
ma
na
g
e
rc
a
n’
tpr
ov
i
dea
nyi
n
f
or
ma
t
i
o
na
b
ou
tt
h
i
sc
e
r
t
i
f
i
c
a
t
e
,
i
twon
’
tb
epos
s
i
bl
et
o
verify the chain. If you want to trust the root CA certificate you can use the cryptlib
t
r
us
tma
n
a
g
e
me
ntme
c
ha
ni
s
mst
oha
ndl
et
h
i
s
,
a
se
x
pl
a
i
ne
di
n“
Certificate Trust
Management”onpa
g
e231.

Exporting Certificate Chains
As is the case when signing certificates and certificate chains, cryptlib gives you a
high degree of control over what part of the chain you want to export. By specifying
an export format of CRYPT_CERTFORMAT_CERTIFICATE or CRYPT_CERTFORMAT_CERTCHAIN, you can control whether a single certificate or an
entire chain is exported. The exact details are as follows:
Object type

Export format

Result

Certificate

Certificate chain

Certificate chain, length = 1

Certificate chain

Certificate

Currently selected certificate in
the chain

Certificate chain

For example the following code exports the currently selected certificate in the chain
as a single certificate:
CRYPT_CERTIFICATE cryptCertChain;
void *certificate;
int certificateLength;
/* Allocate memory for the encoded certificate */
certificate = malloc( certificateMaxLength );
/* Export the currently selected certificate from the certificate
chain */
cryptExportCert( certificate, certificateMaxLength,
&certificateLength, CRYPT_CERTFORMAT_CERTIFICATE, cryptCertChain );

In contrast the following code exports the entire certificate chain:
CRYPT_CERTIFICATE cryptCertChain;
void *certChain;
int certChainLength;
/* Allocate memory for the encoded certificate chain */
certChain = malloc( certChainMaxLength );
/* Export the entire certificate chain */
cryptExportCert( certChain, certChainMaxLength, &certChainLength,
CRYPT_CERTFORMAT_CERTCHAIN, cryptCertChain );

Certificate Revocation using CRLs
Once a certificate has been issued, you may need to revoke it before its expiry date if
the private key it corresponds to is lost or stolen, or if the details given in the
certificate (for example your job role or company affiliation) change. Certificate
revocation is done through a certificate revocation list (CRL) that contains references
to one or more certificates that have been revoked by a CA. cryptlib supports the
creation, import, export, and checking of CRLs as CRYPT_CERTTYPE_CRL
objects, with individual revocation entries accessed as if they were standard
certificate components. Note that these entries are merely references to revoked
certificates and not the certificates themselves, so all they contain is a certificate
reference, the date of revocation, and possibly various optional extras such as the
reason for the revocation.

Working with CRLs
Individual revocation entries in a CRL are addressed through a certificate cursor that
functions in the same way as the attribute c
ur
s
ord
i
s
c
us
s
e
di
n“
Attribute Lists and ”
on page 37. Although a CRL appears as a single object, it consists internally of a

Creating CRLs

229

collection of certificate revocation entries that you can move through using the
standard cursor movement codes. For example to move the cursor to the first entry in
the CRL, you would use:
cryptSetAttribute( cryptCRL, CRYPT_CERTINFO_CURRENT_CERTIFICATE,
CRYPT_CURSOR_FIRST );

To advance the cursor to the next entry, you would use:
cryptSetAttribute( cryptCRL, CRYPT_CERTINFO_CURRENT_CERTIFICATE,
CRYPT_CURSOR_NEXT );

Since each revocation entry can have its own attributes, moving the entry cursor from
one entry to another can change the attributes that are visible. This means that if
y
ou’
r
ewor
k
i
ngwi
t
hapa
r
t
i
c
u
l
a
re
nt
r
y
,
t
hea
t
t
r
i
b
ut
e
sf
ort
ha
te
nt
r
ywi
l
lb
ev
i
s
i
bl
e
,
bu
t
a
t
t
r
i
bu
t
e
sf
orot
h
e
re
nt
r
i
e
swon’
tbe
.Toc
o
mpl
i
c
a
t
et
h
i
sf
ur
t
he
r
,
CRLsc
a
na
l
s
o
contain global attributes that apply to, and are visible for, all entries in the CRL.
cryptlib will automatically handle these for you, allowing access to all attributes (both
per-entry and global) that apply to the currently selected revocation entry.

Creating CRLs
To create a CRL, you first create the CRL certificate object as usual and then push
one or more certificates to be revoked into it.
CRYPT_CERTIFICATE cryptCRL;
/* Create the (empty) CRL */
cryptCreateCert( &cryptCRL, cryptUser, CRYPT_CERTTYPE_CRL );
/* Add the certificates to be revoked */
cryptSetAttribute( cryptCRL, CRYPT_CERTINFO_CERTIFICATE,
revokedCert1 );
cryptSetAttribute( cryptCRL, CRYPT_CERTINFO_CERTIFICATE,
revokedCert2 );
/* ... */
cryptSetAttribute( cryptCRL, CRYPT_CERTINFO_CERTIFICATE,
revokedCertN );
/* Sign the CRL */
cryptSignCertificate( cryptCRL, caPrivateKey );

As has already been mentioned, you must be a CA in order to issue a CRL, and you
can only revoke certificates that you have issued using the certificate used to sign the
CRL(
y
ouc
a
n’
t
,
f
ore
x
a
mpl
e
,
r
e
v
ok
eac
e
r
t
i
f
i
c
a
t
ei
s
s
ue
dbya
not
he
rCA,
orrevoke a
certificate issued with one CA certificate using a different CA certificate). If you try
to add certificates issued by multiple CAs to a CRL, or try to sign a CRL with a CA
certificate that differs from the one that signed the certificates in the CRL, cryptlib
will return a CRYPT_ERROR_INVALID error to indicate that the certificate you are
trying to add to the CRL or sign the CRL with is from the wrong CA. To reiterate:
Every certificate in a given CRL must have been issued using the CA certificate
which is used to sign the CRL. If your CA uses multiple certificates (for example a
Class 1 certificate, a Class 2 certificate, and a Class 3 certificate) then it must issue
one CRL for each certificate class. cryptlib will perform the necessary checking for
y
out
oe
ns
ur
ey
oudo
n’
ti
s
s
uea
ni
nv
a
l
i
dCRL.
I
fy
ou’
r
ea
c
t
i
nga
saCAa
ndi
s
s
ui
ngCRLsf
orc
e
r
t
i
f
i
c
a
t
e
st
he
namu
c
he
a
s
i
e
rwa
yt
o
ha
n
dl
et
hi
si
st
ous
ec
r
y
pt
l
i
b
’
sc
e
r
t
i
f
i
c
a
t
ema
n
a
g
e
me
n
tc
a
p
a
bi
l
i
t
i
e
sa
sde
s
c
r
i
be
di
n
“
Issuing a CRL”onpa
g
e181, since this takes care of all of these details for you.

Advanced CRL Creation
The code shown above creates a relatively straightforward, simple CRL with no extra
information included with the revocation. You can also include extra attributes such
as the time of the revocation (which may differ from the time the CRL was issued, if
y
oudo
n’
ts
pe
c
i
f
yat
i
met
h
e
nc
r
y
pt
l
i
bwi
l
lus
et
heCRLi
s
s
ui
ngt
i
me
)
,
t
her
e
a
s
onf
or
the revocation, and the various other CRL-spec
i
f
i
ci
n
f
or
ma
t
i
ona
sde
s
c
r
i
be
di
n“
CRL
Extensions”o
np
a
g
e245.

230

Certificates in Detail

If you set a revocation time with no revoked certificates present in the CRL, cryptlib
will use this time for any certificates you add tot
heCRLf
o
rwhi
c
hy
oud
on
’
t
explicitly set the revocation time so you can use this to set a default revocation time
for any certificates you add. If you set a revocation time and there are revoked
certificates present in the CRL, cryptlib will set the time for the currently selected
certificate, which will be either the last one added or the one selected with the
certificate cursor commands.
For example to revoke a list of certificates, setting the revocation date for each one
individually, you would use:
CRYPT_CERTIFICATE cryptCRL;
while( moreCerts )
{
CRYPT_CERTIFICATE revokedCert;
time_t revocationTime;
/* Get the certificate to revoke and its revocation time */
revokedCert = ...;
revocationTime = ...;
/* Add them to the CRL */
cryptSetAttribute( cryptCRL, CRYPT_CERTINFO_CERTIFICATE,
revokedCert );
cryptSetAttributeString( cryptCRL, CRYPT_CERTINFO_REVOCATIONDATE,
&revocationTime, sizeof( time_t ) );
/* Clean up */
cryptDestroyCert( revokedCert );
}

You can also add additional attributes such as the reason for the revocation to each
revoked certificate, a number of standards recommend that a reason is given for each
r
e
v
oc
a
t
i
on.Ther
e
v
oc
a
t
i
onc
ode
sa
r
es
p
e
c
i
f
i
e
di
n“
CRL Extensions”o
npa
g
e245.
CRLs can be signed, verified, imported, and exported just like other certificate
objects.

Checking Certificates against CRLs
Verifying a certificate against a CRL with cryptCheckCert works just like a
standard certificate check, with the second parameter being the CRL that the
certificate is being checked against:
CRYPT_CERTIFICATE cryptCRL;
/* Check the certificate against the CRL */
cryptCheckCert( cryptCertificate, cryptCRL );

If the certificate has been revoked, cryptlib will return CRYPT_ERROR_INVALID.
If the certificate has not been revoked (in other words if it is not on the CRL), cryptlib
will return CRYPT_OK. Note that the only thing a CRL can say with certainty is
“
r
e
v
ok
e
d”
,
s
oi
tc
a
n
’
tpr
ov
i
deat
r
uev
a
l
i
d
i
t
yc
he
c
kf
orac
e
r
t
i
f
i
c
a
t
e
.Fore
x
a
mp
le, if
you perform a CRL check on an Excel spreadsheet, a CRL will report it as being a
v
a
l
i
dc
e
r
t
i
f
i
c
a
t
e
,
s
i
n
c
ei
t
’
sn
otl
i
s
t
e
di
nt
heCRL.Si
mi
l
a
r
l
y
,
af
or
g
e
dc
e
r
t
i
f
i
c
a
t
ec
a
n’
t
beha
nd
l
e
dbyaCRLs
i
nc
ei
tc
a
n
’
tb
eha
nd
l
e
dt
hr
o
ug
habl
a
c
k
l
i
s
tme
c
ha
ni
s
m such as
a CRL. If you require a true certificate validity check, you need to use a alternative
mechanism such as RTCS.
I
ft
hec
e
r
t
i
f
i
c
a
t
ei
sr
e
v
ok
e
d,
t
hec
e
r
t
i
f
i
c
a
t
e
’
sr
e
v
oc
a
t
i
one
nt
r
yi
nt
heCRLwi
l
lbel
e
f
t
as the selected one, allowing you to obtain further information on the revocation (for
example the revocation date or reason):
time_t revocationTime;
int revocationReason;
status = cryptCheckCert( cryptCertificate, cryptCRL );
if( status == CRYPT_ERROR_INVALID )
{
int revocationTimeLength;

Certificate Trust Management

231

/* The certificate has been revoked, get the revocation time and
reason */
cryptGetAttributeString( cryptCRL, CRYPT_CERTINFO_REVOCATIONDATE,
&revocationTime, &revocationTimeLength );
cryptGetAttribute( cryptCRL, CRYPT_CERTINFO_CRLREASON,
&revocationReason );
}

Note that the revocation reason is an optional CRL component, so this may not be
pr
e
s
e
n
ti
nt
heCRL.I
ft
her
e
v
oc
a
t
i
o
nr
e
a
s
o
ni
s
n
’
tpr
e
s
e
n
t
,
c
r
y
pt
l
i
bwi
l
lr
e
t
ur
n
CRYPT_ERROR_NOTFOUND.

Automated CRL Checking
As you can see from the description of the revocation checking process above, it
quickly becomes unmanageable as the number of CRLs and the size of each CRL
increases, since what should be a simple certificate validation check now involves
checking the certificate against any number of CRLs (CRLs are generally regarded as
ar
a
t
he
ru
ns
a
t
i
s
f
a
c
t
or
ys
ol
ut
i
o
nt
ot
hepr
o
bl
e
m ofc
e
r
t
i
f
i
c
a
t
er
e
v
oc
a
t
i
on,
b
utwe
’
r
e
stuck with them for the foreseeable future).
In order to ease this complex and long-winded checking process, cryptlib provides the
ability to automatically check a certificate against CRLs stored in a cryptlib database
keyset. To do this you first need to write the CRL or CRLs to the keyset as if they
we
r
enor
ma
lc
e
r
t
i
f
i
c
a
t
e
s
,
a
se
x
pl
a
i
ne
di
n“
Writing a Key to a Keyset”onpa
g
e146.
cryptlib will take each complete CRL and record all of the individual revocations
contained in it for later use.
Once you have a keyset containing revocation information, you can use it to check
the validity of a certificate using cryptCheckCert, giving the keyset as the second
parameter:
CRYPT_KEYSET cryptKeyset;
/* Check the certificate using the keyset */
cryptCheckCert( cryptCertificate, cryptKeyset );

As with the check against a CRL, cryptlib will return CRYPT_ERROR_INVALID if
the certificate has been revoked.
This form of automated checking considerably simplifies the otherwise arbitrarily
complex CRL checking process since cryptlib can handle the check with a simple
keyset query rather than having to locate and search large numbers of CRLs.

Certificate Trust Management
In order to provide extended control over certificate usage, cryptlib allows you to
bot
hf
ur
t
h
e
rr
e
s
t
r
i
c
tt
heus
a
g
eg
i
v
e
ni
nt
h
ec
e
r
t
i
f
i
c
a
t
e
’
sCRYPT_
CERTI
NFO_KEYUSAGE attribute and to specify whether a given certificate should be implicitly
trusted, avoiding the requirement to process a (potentially large) chain of certificates
i
nor
d
e
rt
ode
t
e
r
mi
net
h
ec
e
r
t
i
f
i
c
a
t
e
’
sv
a
l
i
di
t
y
.

Controlling Certificate Usage
You can control the way a certificate can be used by setting its CRYPT_CERTINFO_TRUSTED_USAGE attribute, which provides extended control over the
usage types that a certificate is trusted for. This attribute works by further restricting
the usage specified by the CRYPT_CERTINFO_KEYUSAGE attribute, acting as a
ma
s
kf
ort
hes
t
a
nd
a
r
dk
e
yus
a
g
es
ot
ha
tag
i
v
e
nus
a
g
ei
sonl
ype
r
mi
t
t
e
di
fi
t
’
sa
l
l
owe
d
bybot
ht
h
ek
e
yus
a
g
ea
ndt
r
us
t
e
dus
a
g
ea
t
t
r
i
bu
t
e
s
.I
ft
het
r
us
t
e
dus
a
g
ea
t
t
r
i
b
ut
ei
s
n
’
t
present (which is the default setting) then all usage types specified in the key usage
attribute are allowed.
Fore
x
a
mpl
ea
s
s
u
meac
e
r
t
i
f
i
c
a
t
e
’
sk
e
yus
a
g
ea
t
t
r
i
but
ei
ss
e
tt
oCRYPT_KEYUSAGE_DIGITALSIGNATURE and CRYPT_KEYUSAGE_KEYENCIPHERMENT. By setting the trusted usage attribute to CRYPT_KEYUSAGE_DIGITALSIGNATURE only, you can tell cryptlib that you only trust

232

Certificates in Detail
t
hec
e
r
t
i
f
i
c
a
t
et
obeus
e
df
ors
i
g
na
t
ur
e
s
,
e
v
e
nt
h
oug
ht
hec
e
r
t
i
f
i
c
a
t
e
’
ss
t
a
n
da
r
dus
a
g
e
would also allow encryption. This means that you can control precisely how a
certificate is used at a level beyond that provided by the certificate itself.

Implicitly Trusted Certificates
To handle certificate validation trust issues, cryptlib has a built-in trust manager that
r
e
c
or
dswhe
t
he
rag
i
v
e
nCA’
sore
ndus
e
r
’
sc
e
r
t
i
f
i
c
a
t
ei
si
mpl
i
c
i
t
l
yt
r
us
t
e
d.Whe
n
cryptlib gets to a trusted certificate during the certificate validation process (for
e
x
a
mp
l
ea
si
t
’
sv
a
l
i
da
t
i
ngt
hec
e
r
t
i
f
i
c
a
t
e
si
nac
e
r
t
i
f
i
c
a
t
ec
h
a
i
n)
,
i
tk
nowst
h
a
ti
t
doe
s
n’
tha
v
et
og
oa
nyf
ur
t
he
ri
nt
r
y
i
ngt
og
e
tt
oa
nu
l
t
i
ma
t
e
l
yt
r
us
t
e
dc
e
r
t
i
f
i
c
a
t
e
.I
f
you installed the default cryptlib certificates when you installed cryptlib itself then
y
ou’
l
lha
v
eac
ol
l
e
c
t
i
o
no
ft
o
p
-l
e
v
e
lc
e
r
t
i
f
i
c
a
t
e
sf
r
o
mt
hewor
l
d
’
sl
a
r
g
e
s
tCAsa
l
r
e
a
dy
present and marked as trusted by cryptlib, so that if cryptlib is asked to process a
certificate chain ending in one of these trusted CA certificates, the cryptlib trust
manager will determine that the top-level certificate is implicitly trusted and use it to
verify the lower-level certificates in the chain.
The trust manager provides a convenient mechanism for managing not only CA
certificates but also any certificates that you decide you can trust implicitly. For
e
x
a
mp
l
ei
fy
ou
’
v
eob
t
a
i
ne
dac
e
r
t
i
f
i
c
a
t
ef
r
o
m at
r
us
t
e
ds
o
ur
c
es
uc
ha
sdi
r
e
c
t
communication with the owner or from a trusted referrer, you can mark the certificate
a
st
r
us
t
e
de
v
e
ni
fi
td
oe
s
n’
tha
v
eaf
ul
lc
ha
i
no
fCAc
e
r
t
i
f
i
c
a
t
e
si
nt
ow.Thi
si
sa
natural certificate handling model in many situations (for example trading partners
with an existing trust relationship), and avoids the complexity and expense of using
an external CA to verify something that both parties know already. When scaled up
to thousands of users (and certificates), this can provide a considerable savings both
in terms of managing the certification process and in the cost of obtaining and
renewing huge numbers of certificates each year.

Working with Trust Settings
Youc
a
ng
e
ta
nds
e
tac
e
r
t
i
f
i
c
a
t
e
’
st
r
us
t
e
dus
a
g
eus
i
ngCRYPT_CERTI
NFO_TRUSTED_USAGE, which takes as value the key usage(s) for which the certificate
is trusted. To mark a certificate as trusted only for encryption, you would use:
cryptSetAttribute( certificate, CRYPT_CERTINFO_TRUSTED_USAGE,
CRYPT_KEYUSAGE_KEYENCIPHERMENT );

Thi
ss
e
t
t
i
ngwi
l
lnowbea
pp
l
i
e
da
u
t
o
ma
t
i
c
a
l
l
yt
ot
hec
e
r
t
i
f
i
c
a
t
e
’
sus
a
g
epe
r
mi
s
s
i
o
ns
,
so that even if its CRYPT_CERTINFO_KEYUSAGE attribute allowed signing and
encryption, the CRYPT_CERTINFO_TRUSTED_USAGE attribute would restrict
this to only allow encryption.
To remove any restrictions and allow all usages specified by CRYPT_CERTINFO_KEYUSAGE, delete the CRYPT_CERTINFO_TRUSTED_USAGE attribute, which
allows the full range of usage types that are present in CRYPT_CERTINFO_KEYUSAGE:
cryptDeleteAttribute( cryptCertificate, CRYPT_CERTINFO_TRUSTED_USAGE
);

Youc
a
ng
e
ta
nds
e
tac
e
r
t
i
f
i
c
a
t
e
’
simplicitly trusted status using the CRYPT_CERTINFO_TRUSTED_IMPLICIT attribute, which takes as value a boolean flag
that indicates whether the certificate is implicitly trusted or not. To mark a certificate
as trusted, you would use:
cryptSetAttribute( certificate, CRYPT_CERTINFO_TRUSTED_IMPLICIT, 1 );

Be careful when marking certificate chains (rather than individual certificates) as
implicitly trusted. Since a chain usually contains multiple certificates, setting the
CRYPT_CERTINFO_TRUSTED_IMPLICIT attribute affects the currently selected
certificate in the chain. Typically you want to trust the root CA, while the certificate
which is normally active when the chain is used is the end-user/leaf certificate. In
order to select the root CA certificate, you should move the certificate cursor to it
using the CRYPT_CURSOR_LAST movement code before marking the chain as

Certificate Trust Management

233

trusted. This will explicitly make the top-level CA certificate trusted, rather than
some arbitrary certificate in the chain.
To check whether a certificate is trusted you would use:
int isTrusted;
cryptGetAttribute( certificate, CRYPT_CERTINFO_TRUSTED_IMPLICIT,
&isTrusted );

Since the trust of a CA propagates down to the certificates it issues, the trust setting in
this case applies to the whole chain rather than just one certificate in it. In other
words if the chain is signed by a trusted CA, the entire chain beyond that point will be
regarded as trusted.
If the result is set to true (a nonzero value) then the certificate is implicitly trusted by
c
r
y
pt
l
i
b.I
npr
a
c
t
i
c
ey
ouwon
’
tn
e
e
dt
ob
ot
he
rwi
t
ht
hi
sc
he
c
k
i
ng
,
s
i
nc
ec
r
y
pt
l
i
bwi
l
l
do it for you when it verifies certificate chains.
Thec
e
r
t
i
f
i
c
a
t
et
r
us
ts
e
t
t
i
ng
sa
r
epa
r
to
fc
r
y
pt
l
i
b
’
sc
o
nf
i
g
ur
a
t
i
o
no
pt
i
ons
,
whi
c
ha
r
e
explained in more detail i
n“
Working with Configuration Options”o
npa
g
e274. Like
all configuration options, changes to the trust settings only remain in effect during the
current session with cryptlib unless you explicitly force them to be committed to
permanent storage by resetting the configuration changed flag. For example if you
change the trust settings for various certificates and want the new trust values to be
applied when you use cryptlib in the future, you would use code like:
/* Mark various certificates as trusted and one as untrusted */
cryptSetAttribute( certificate1, CRYPT_CERTINFO_TRUSTED_IMPLICIT, 1 );
cryptSetAttribute( certificate2, CRYPT_CERTINFO_TRUSTED_IMPLICIT, 1 );
cryptSetAttribute( certificate3, CRYPT_CERTINFO_TRUSTED_IMPLICIT, 1 );
cryptSetAttribute( certificate4, CRYPT_CERTINFO_TRUSTED_IMPLICIT, 0 );
/* Save the new settings to permanent storage */
cryptSetAttribute( CRYPT_UNUSED, CRYPT_OPTION_CONFIGCHANGED, FALSE );

Marking a certificate as untr
u
s
t
e
dd
oe
s
n’
tme
a
nt
ha
ti
tc
a
nne
v
e
rbet
r
us
t
e
d,
b
ut
merely that its actual trust status is currently unknown. If the untrusted certificate is
signed by a trusted CA certificate (possibly several levels up a certificate chain) then
the certificate will be regarded as trusted when cryptlib checks the certificate chain.
In practice an untrusted certificate is really a certificate whose precise trust level has
yet to be determined rather than a certificate which is explicitly not trusted. If you
want to explicitly not trust a certificate for one or more types of usage, you can do
this using the CRYPT_CERTINFO_TRUSTED_USAGE attribute.

234

Certificate Extensions

Certificate Extensions
Certificate extensions form by far the most complicated portion of certificates. By
default, cryptlib will add appropriate certificate extension attributes to certificates for
y
oui
fy
o
udo
n
’
ta
d
da
ny
,
bu
ts
ome
t
i
me
sy
ouma
ywa
ntt
oa
ddorc
h
a
ng
et
he
s
e
yourself. cryptlib supports extensions in two ways, through the usual add/get/delete
attribute mechanism for extensions that it recognises, and through
cryptAddCertExtension, cryptGetCertExtension, and cryptDeleteCertExtension
f
org
e
ne
r
a
le
x
t
e
ns
i
o
nst
ha
ti
tdoe
s
n’
tr
e
c
og
ni
s
e
.Theg
e
ne
r
a
le
x
t
e
ns
i
o
nha
nd
l
i
ng
mechanism allows you to add, query, and delete any kind of extension to a certificate,
including ones that you define yourself.

Extension Structure
X.509 version 3 introduced a mechanism by which additional information could be
added to certificates through the use of certificate extensions. The X.509 standard
defined a number of extensions, and over time other standards organisations defined
their own additions and amendments to these extensions. In addition private
organisations, businesses, and individuals have all defined their own extensions, some
of which (for example the extensions from Netscape and Microsoft) have seen a
reasonably wide amount of use. An extension contains three main pieces of
information:
Field

Description

Type

The extension type, a unique identifier called an object
identifier. This is given as a sequence of numbers that trace
a path through an object identifier tree. For example the
object identifier for the keyUsage extension is 2 5 29 15.
The object identifier for cryptlib is 1 3 6 1 4 1 3029 32.

Critical Flag

A flag that defines whether the extension is important
enough that it must be processed by an application. If the
c
r
i
t
i
c
a
lf
l
a
gi
ss
e
ta
nda
na
p
pl
i
c
a
t
i
ondoe
s
n’
tr
e
c
og
ni
s
et
he
extension, it will reject the certificate.
Since some standards (including X.509 itself) allow
implementations to selectively ignore non-critical extensions,
and support for extensions is often haphazard, it may be
necessary to mark an extension as critical in order to ensure
that other implementations process it. As usual, you should
check to see whether your intended target correctly processes
the extensions that you plan to use.

Value

The extension data, corresponding to a cryptlib attribute
group for more complex composite extensions, or a single
cryptlib attribute for a few very simple extensions.

For the extensions that cryptlib recognises, the handling of the critical flag is
a
ut
o
ma
t
i
c
.Fore
x
t
e
ns
i
onst
ha
tc
r
y
pt
l
i
bd
oe
s
n
’
tha
n
dl
ei
t
s
e
l
f
,
y
oune
e
dt
os
e
tt
he
critical flag yourself when you add the extension data using
cryptAddCertExtension.

Working with Extension Attributes
Certificate extensions correspond to cryptlib attribute groups, with individual
components of each certificate extension being represented by attributes within the
group. Since this section applies specifically to certificates, the certificate-specific
terminology referring to extensions rather than the general term attribute group will
be used here.
cryptlib can identify attributes in extensions/attribute groups in one of three ways:

Working with Extension Attributes

235

1. Through an extension identifier that denotes the entire extension/attribute group.
For example CRYPT_CERTINFO_CERTPOLICIES denotes the
certificatePolicies extension/attribute group.
2. Through an attribute identifier that denotes a particular attribute within an
extension/attribute group. For example CRYPT_CERTINFO_CERTPOLICY
denotes the policyIdentifier attribute contained within the certificatePolicies
extension/attribute group.
Some extensions/groups only contain a single attribute, in which case the
extension identifier is the same as the attribute identifier. For example the
CRYPT_CERTINFO_KEYUSAGE extension contains a single attribute which is
also identified by CRYPT_CERTINFO_KEYUSAGE.
3. Through the attribute cursor mechanism that allows you to step through a set of
extensions extension by extension or attribute by attribute. Attribute cursor
ma
na
g
e
me
n
ti
se
x
pl
a
i
n
e
di
nmor
ede
t
a
i
li
n“
Attribute Lists and ”o
npa
g
e37.
You can use the extension/group identifier to determine whether a particular
extension is present with cryptGetAttribute (it will return CRYPT_ERROR_NOTFOUNDi
ft
hee
x
t
e
ns
i
oni
s
n’
tpr
e
s
e
nt
)
,
t
od
e
l
e
t
ea
ne
n
t
i
r
ee
x
t
e
ns
i
o
nwi
t
h
cryptDeleteAttribute, and to position the extension cursor at a particular extension.
Attributes within extensions/group are handled in the usual manner, for example to
retrieve the value of the basicConstraints CA attribute (which determines whether a
certificate is a CA certificate) you would use:
int isCA;
cryptGetAttribute( certificate, CRYPT_CERTINFO_CA, &isCA );

To determine whether the entire basicConstraints extension is present, you would use:
int basicConstraintsPresent;
status = cryptGetAttribute( certificate,
CRYPT_CERTINFO_BASICCONSTAINTS, &basicConstraintsPresent );
if( cryptStatusOK( status ) )
/* basicConstraints extension is present */;

Youdo
n
’
tha
v
et
owor
r
ya
bo
utt
hes
t
r
uc
t
ur
eo
fi
nd
i
v
i
d
ua
le
x
t
e
ns
i
onss
i
nc
ec
r
y
pt
l
i
b
will handle this for you. For example to make a certificate a CA certificate, all that
you need to do is:
cryptSetAttribute( certificate, CRYPT_CERTINFO_CA, 1 );

and cryptlib will construct the basicConstraints extension for you and set up the CA
attribute as required. Because the basicConstraints extension is a fundamental
X.509v3 extension, cryptlib will in fact a
l
wa
y
sa
d
dt
h
i
sbyde
f
a
ul
te
v
e
ni
fy
oud
on
’
t
explicitly specify it.

Extension Cursor Management
Note: Starting with cryptlib 3.2, all cryptlib objects will have a unified cursor
management system. At this point the certificate-specific cursor attributes will be
moved to CRYPT_ATTRIBUTE_CURRENT_GROUP, CRYPT_ATTRIBUTE_CURRENT, and CRYPT_ATTRIBUTE_CURRENT_INSTANCE, in place of the
current CRYPT_CERTINFO_CURRENT_EXTENSION, CRYPT_CERTINFO_CURRENT_FIELD, and CRYPT_CERTINFO_CURRENT_COMPONENT. The new
attributes are already present in the current release, so you should plan to move
existing code to using the new names (this can be done with a simple search and
replace), and use the new attribute names in any new code that you write.
Extensions and extension attributes can also be managed through the use of an
e
x
t
e
ns
i
onc
ur
s
ort
ha
twor
k
sj
us
tl
i
k
et
hea
t
t
r
i
b
ut
ec
ur
s
ordi
s
c
us
s
e
di
n“
Attribute Lists
and ”onp
a
g
e37. Since certificates are significantly more complex than other
cryptlib objects, the cursor is handled through three levels of attributes instead of the
usual one. These attributes are CRYPT_CERTINFO_CURRENT_EXTENSION for
the extension, CRYPT_CERTINFO_CURRENT_FIELD for the attribute within the

236

Certificate Extensions

extension, and CRYPT_CERTINFO_CURRENT_COMPONENT for the component
within the attribute if the attribute can contain more than one value (for example an
altName can contain one or more email addresses, URLs, and other information).
When you set the attribute values, this moves the cursor to the particular extension or
attribute. The attribute value that you specify is the extension or extension attribute
that you want to move the cursor to. For example:
cryptSetAttribute( certificate, CRYPT_CERTINFO_CURRENT_EXTENSION,
CRYPT_CERTINFO_CA );

would move the extension cursor to the start of the extension containing the given
attribute (in this case the start of the basicConstraints extension). In contrast:
cryptSetAttribute( certificate, CRYPT_CERTINFO_CURRENT_FIELD,
CRYPT_CERTINFO_CA );

would move the cursor to the extension attribute (in this case the CA attribute in the
basicConstraints extension). Setting the CRYPT_CERTINFO_CURRENT_COMPONENT attribute is identical to setting the CRYPT_CERTINFO_CURRENT_FIELD except in the special case of using attribute cursor movement
codes, where it can be used to access sub-components within an attribute.
You can also position the cursor using the standard attribute cursor movement codes.
For example to move the cursor to the start of the first extension, you would use:
cryptSetAttribute( certificate, CRYPT_CERTINFO_CURRENT_EXTENSION,
CRYPT_CURSOR_FIRST );

To advance the cursor to the start of the next extension, you would use:
cryptSetAttribute( certificate, CRYPT_CERTINFO_CURRENT_EXTENSION,
CRYPT_CURSOR_NEXT );

To advance the cursor to the next attribute in the extension, you would use:
cryptSetAttribute( certificate, CRYPT_CERTINFO_CURRENT_FIELD,
CRYPT_CURSOR_NEXT );

In some cases multiple instances of the same attribute can be present, in which case
you can use the CRYPT_CERTINFO_CURRENT_COMPONENT attribute and
relative cursor movement to step through the different instances of the attribute.
Since the use of multi-v
a
l
ue
da
t
t
r
i
bu
t
e
si
sr
a
r
e
,
i
t
’
ss
a
f
et
oa
s
s
umeon
ev
a
l
ue per
attribute in most cases, so that stepping through multiple attribute instances is
unnecessary.
Onc
ey
ou
’
v
es
e
tt
h
ec
ur
s
orp
o
s
i
t
i
on,
y
ouc
a
nwor
kwi
t
ht
hee
x
t
e
ns
i
onora
t
t
r
i
but
ea
t
the cursor position in the usual manner. For example to delete the entire extension at
the current cursor position you would use:
cryptDeleteAttribute( certificate, CRYPT_CERTINFO_CURRENT_EXTENSION );

Deleting the extension at the cursor position will move the cursor to the start of the
extension that follows the deleted one, or to the start of the previous extension if the
one being deleted was the last one present. This means that you can delete every
extension simply by repeatedly deleting the one under the cursor.
To obtain the extension or attribute type at the current cursor position, you would use:
CRYPT_ATTRIBUTE_TYPE extensionAttributeID;
cryptGetAttribute( certificate, CRYPT_CERTINFO_CURRENT_EXTENSION,
&extensionAttributeID );

This example obtains the extension, to obtain the attribute type you would substitute
CRYPT_CERTINFO_CURRENT_FIELD in place of CRYPT_CERTINFO_CURRENT_EXTENSION.
The attribute cursor provides a convenient mechanism for stepping through every
extension which is present in a certificate object. For example to iterate through
every extension you would use:

Working with Extension Attributes

237

if( cryptSetAttribute( certificate, CRYPT_CERTINFO_CURRENT_EXTENSION,
CRYPT_CURSOR_FIRST ) == CRYPT_OK )
do
{
CRYPT_ATTRIBUTE_TYPE extensionID;
/* Get the ID of the extension under the cursor */
cryptGetAttribute( certificate,
CRYPT_CERTINFO_CURRENT_EXTENSION, &extensionID );
}
while( cryptSetAttribute( certificate,
CRYPT_CERTINFO_CURRENT_EXTENSION, CRYPT_CURSOR_NEXT ) ==
CRYPT_OK );

To extend this a stage further and iterate through every attribute in every extension in
the certificate object, you would use:
if( cryptSetAttribute( certificate, CRYPT_CERTINFO_CURRENT_EXTENSION,
CRYPT_CURSOR_FIRST ) == CRYPT_OK )
do
{
do
{
CRYPT_ATTRIBUTE_TYPE extensionAttributeID;
/* Get the ID of the extension attribute under the cursor */
cryptGetAttribute( certificate, CRYPT_CERTINFO_CURRENT_FIELD,
&extensionAttributeID );
}
while( cryptSetAttribute( certificate,
CRYPT_CERTINFO_CURRENT_FIELD, CRYPT_CURSOR_NEXT ) == CRYPT_OK
);
}
while( cryptSetAttribute( certificate,
CRYPT_CERTINFO_CURRENT_EXTENSION, CRYPT_CURSOR_NEXT ) ==
CRYPT_OK );

Not
et
h
a
ti
t
e
r
a
t
i
nga
t
t
r
i
bu
t
eb
ya
t
t
r
i
bu
t
ewor
k
swi
t
hi
nt
hec
ur
r
e
nte
x
t
e
ns
i
on,
b
utwon
’
t
jump from one extension to the next — to do that, you need to iterate by extension.
To restrict the above operation slightly so that only the attributes of a single extension
(rather than all extensions) are enumerated, you first select the extension and then
step through the attributes in it. For example to read all extended key usage types you
would use:
if( cryptSetAttribute( certificate, CRYPT_CERTINFO_CURRENT_EXTENSION,
CRYPT_CERTINFO_EXTKEYUSAGE ) == CRYPT_OK )
do
{
CRYPT_ATTRIBUTE_TYPE extensionAttributeID;
/* Get the ID of the extension attribute under the cursor */
cryptGetAttribute( certificate, CRYPT_CERTINFO_CURRENT_FIELD,
&extensionAttributeID );
}
while( cryptSetAttribute( certificate,
CRYPT_CERTINFO_CURRENT_FIELD, CRYPT_CURSOR_NEXT ) == CRYPT_OK );

Composite Extension Attributes
Attributes that contain complete GeneralNames and/or DNs are composite attributes
that have further items within them. These are handled in the standard way using the
attribute cursor: You first move the cursor to the attribute that contains the
GeneralName or DN that you want to work with and then get, set, or delete attributes
within it:
cryptSetAttribute( certificate, CRYPT_CERTINFO_CURRENT_FIELD,
CRYPT_CERTINFO_PERMITTEDSUBTREES );
cryptSetAttributeString( certificate, CRYPT_CERTINFO_RFC822NAME,
rfc822Name, rfc822NameLength );
cryptSetAttributeString( certificate, CRYPT_CERTINFO_DNSNAME, dnsName,
dnsNameLength );

This code first moves the cursor to the nameConstraints permittedSubtrees
GeneralName and then sets the GeneralName attributes as usual. Since a

238

Certificate Extensions

GeneralName contains its own DN, moving the attribute cursor onto a GeneralName
means that any DN accesses will now refer to the DN in the GeneralName rather than
the certificate subject or issuer name:
/* Select the permittedSubtrees GeneralName */
cryptSetAttribute( certificate, CRYPT_CERTINFO_CURRENT_FIELD,
CRYPT_CERTINFO_PERMITTEDSUBTREES );
/* Set the DN components within the GeneralName */
cryptSetAttributeString( certificate, CRYPT_CERTINFO_COUNTRYNAME,
countryName, countryNameLength );
cryptSetAttributeString( certificate, CRYPT_CERTINFO_LOCALITYNAME,
localityName, localityNameLength );

This code first identifies the nameConstraints permittedSubtrees GeneralName as the
one to be modified and then sets the DN components as usual. cryptlib uses this
mechanism to access all DNs and GeneralNames, although this is usually hidden
from you — when yo
umod
i
f
yac
e
r
t
i
f
i
c
a
t
eob
j
e
c
t
’
sDN,
c
r
y
pt
l
i
ba
u
t
o
ma
t
i
c
a
l
l
yus
e
s
t
hes
u
bj
e
c
tDNi
fy
oud
on
’
te
x
pl
i
c
i
t
l
ys
pe
c
i
f
yi
t
,
a
ndwhe
ny
oumod
i
f
yt
h
e
Ge
ne
r
a
l
Na
mec
r
y
pt
l
i
bus
e
st
h
es
ubj
e
c
ta
l
t
Na
mei
fy
oud
on
’
te
x
pl
i
c
i
t
l
ys
pe
c
i
f
yi
t
.I
n
this way you can work with subject names and altNames without having to know
about the DN and GeneralName selection mechanism.
Onc
ey
ou
’
v
es
e
l
e
c
t
e
dadi
f
f
e
r
e
ntGe
n
e
r
a
l
Na
mea
n
d/
orDN,i
tr
e
ma
i
nss
e
l
e
c
t
e
dun
t
i
l
you select a different one or move the attribute cursor off it, so if you wanted to move
back to working with the subject name after performing the operations shown above
y
ou’
dne
e
dt
ous
e
:
cryptSetAttribute( certificate, CRYPT_CERTINFO_SUBJECTNAME,
CRYPT_UNUSED );

otherwise attempts to add, delete, or query further DN (or GeneralName) attributes
will apply to the selected nameConstraints excludedSubtrees attribute instead of the
subject name. Conversely, if you move the attribute cursor off the GeneralName that
y
ou’
r
ewor
k
i
ngwi
t
h,
s
ubs
e
q
u
e
nta
t
t
e
mpt
st
owor
kwi
t
hGe
ne
r
a
l
Na
meorDN fields
wi
l
lf
a
i
lwi
t
haCRYPT_ERROR_NOTFOUND,s
i
nc
et
h
e
r
e
’
sn
oGe
ne
r
a
l
Na
me
currently selected.

X.509 Extensions
X.509 version 3 and assorted additional standards and revisions specify a large
number of extensions, all of which are handled by cryptlib. In addition there are a
number of proprietary and vendor-specific extensions that are also handled by
cryptlib.
In the following descriptions only the generally useful attributes have been described.
The full range of attributes is enormous, requires several hundred pages of standards
specifications to describe them all, and will probably never be used in real life. These
a
t
t
r
i
bu
t
e
sa
r
ema
r
k
e
dwi
t
h“
Se
ec
e
r
t
i
f
i
c
a
t
es
t
a
n
da
r
dsdoc
u
me
nt
s
”t
oi
ndi
c
a
t
et
ha
ty
ou
should refer to other documents to obtain information about their usage (this is also a
g
oodi
nd
i
c
a
t
i
o
nt
h
a
ty
ous
ho
u
l
dn
’
tr
e
a
l
l
ybeus
i
ngt
hi
sa
t
t
r
i
but
e
)
.

Alternative Names
Thes
u
bj
e
c
ta
n
di
s
s
u
e
ra
l
t
Na
me
sa
r
eus
e
dt
os
pe
c
i
f
ya
l
lt
h
et
hi
ng
st
ha
ta
r
e
n
’
ts
u
i
t
a
bl
e
for the main certificate DNs. The issuer altName is identified by CRYPT_CERTINFO_ISSUERALTNAME and the subject altName is identified by CRYPT_CERTINFO_SUBJECTALTNAME. Both consist of a single GeneralName whose
us
ei
se
x
pl
a
i
n
e
di
n“
Extended Certificate Identification Information”o
npa
g
e219.
This extension is valid in certificates, certification requests, and CRLs, and can
contain one of each type of GeneralName component.

Basic Constraints
This is a standard extension identified by CRYPT_CERTINFO_BASICCONSTRAINTS and is used to specify whether a certificate is a CA
c
e
r
t
i
f
i
c
a
t
eornot
.I
fy
oudo
n’
ts
e
tt
h
i
se
x
t
e
ns
i
o
n,
c
r
y
pt
l
i
bwi
l
ls
e
ti
tf
ory
oua
n
dma
r
k

X.509 Extensions

239

the certificate as a non-CA certificate. This extension is valid in certificates, attribute
certificates, and certification requests, and has the following attributes:
Attribute/Description

Type

CRYPT_CERTINFO_CA
Boolean
Whether the certificate is a CA certificate or not. When used with attribute
certificates, the CA is called an authority, so cryptlib will also accept the
alternative CRYPT_CERTINFO_AUTHORITY, which has the same
me
a
ni
nga
sCRYPT_CERTI
NFO_CA.I
ft
hi
sa
t
t
r
i
b
ut
ei
s
n
’
ts
e
t
,
t
he
certificate is treated as a non-CA certificate.
CRYPT_CERTINFO_PATHLENCONSTRAINT
See certificate standards documents.

Numeric

For example to mark a certificate as a CA certificate you would use:
cryptSetAttribute( certificate, CRYPT_CERTINFO_CA, 1 );

Certificate Policies, Policy Mappings, and Policy Constraints, and Policy
Inhibiting
The certificate policy extensions allow a CA to provide information on the policies
governing a certificate, and to control the way in which a certificate can be used. For
example it allows you to check that each certificate in a certificate chain was issued
under a policy you feel comfortable with (certain security precautions taken, vetting
of employees, physical security of the premises, and so on). The certificate policies
attribute is identified by CRYPT_CERTINFO_CERTIFICATEPOLICIES and is
valid in certificates.
The certificate policies attribute is a complex extension that allows for all sorts of
qualifiers and additional modifiers. In general you should only use the
policyIdentifier attribute in this extension, since the other attributes are difficult to
support in user software and are ignored by many implementations:
Attribute/Description

Type

CRYPT_CERTINFO_CERTPOLICYID
String
The object identifier that identifies the policy under which this certificate
was issued.
CRYPT_CERTINFO_CERTPOLICY_CPSURI
String
The URL for the certificate practice statement (CPS) for this certificate
policy.
CRYPT_CERTINFO_CERTPOLICY_ORGANIZATION
String
CRYPT_CERTINFO_CERTPOLICY_NOTICENUMBERS Numeric
CRYPT_CERTINFO_CERTPOLICY_EXPLICITTEXT
String
These attributes contain further qualifiers, modifiers, and text information
that amend the certificate policy information. Refer to certificate standards
documents for more information on these attributes.
Si
nc
ev
a
r
i
o
usCAst
ha
twoul
dl
i
k
et
oa
c
c
e
p
te
a
c
hot
he
r
’
sc
e
r
t
i
f
i
c
a
t
e
sma
y have
differing policies, there is an extension that allows a CA to map its policies to those
of another CA. The policyMappings extension provides a means of mapping one
policy to another (that is, for a CA to indicate that policy A, under which it is issuing
a certificate, is equivalent to policy B, which is required by the certificate user). This
extension is identified by CRYPT_CERTINFO_POLICYMAPPINGS and is valid in
certificates:
Attribute/Description

Type

CRYPT_CERTINFO_ISSUERDOMAINPOLICY
The object identifier for the source (issuer) policy.

String

CRYPT_CERTINFO_SUBJECTDOMAINPOLICY
The object identifier for the destination (subject) policy.

String

240

Certificate Extensions

A CA can also specify acceptable policy constraints for use in certificate chain
validation. The policyConstraints extension is identified by CRYPT_CERTINFO_POLICYCONSTRAINTS and is valid in certificates:
Attribute/Description

Type

CRYPT_CERTINFO_REQUIREEXPLICITPOLICY
See certificate standards documents.

Numeric

CRYPT_CERTINFO_INHIBITPOLICYMAPPING
See certificate standards documents.

Numeric

Finally, a CA can inhibit the use of the special-case anyPolicy policy. The
inhibitAnyPolicy extension is identified by CRYPT_CERTINFO_INHIBITANYPOLICY and is valid in certificates:
Attribute/Description

Type

CRYPT_CERTINFO_INHIBITANYPOLICY
See certificate standards documents.

Numeric

CRL Distribution Points/Freshest CRL and Subject/Authority Information
Access
These extensions specify how to obtain CRL information and information on the CA
that issued a certificate. The cRLDistributionPoint extension is valid in certificates
and is identified by CRYPT_CERTINFO_CRLDISTRIBUTIONPOINT:
Attribute/Description

Type

CRYPT_CERTINFO_CRLDIST_FULLNAME
GeneralName
The location at which CRLs may be obtained. You should use the URL
component of the GeneralName for this, avoiding the other possibilities.
CRYPT_CERTINFO_CRLDIST_REASONS
CRYPT_CERTINFO_CRLDIST_CRLISSUER
See certificate standards documents.

Numeric
GeneralName

Note that the CRYPT_CERTINFO_CRLDIST_REASONS attribute has the same
allowable set of values as the cRLReasons reasonCode, but in this case is given as a
series of bit flags rather than the reasonCode numeric value (because X.509 says so,
t
ha
t
’
swhy
)
.Be
c
a
us
eoft
hi
sy
oumus
tus
eCRYPT_CRLREASONFLAGS_name
instead of CRYPT_CRLREASON_name when getting and setting these values.
If you plan to use this extension, you should be aware of the fact that it exists solely
as a kludge created to work around problems involved in finding CRLs in X.500
directories, and thus presents a rather poor mechanism for distributing and obtaining
r
e
v
oc
a
t
i
oni
n
f
or
ma
t
i
o
n.Unl
e
s
si
t
’
sa
bs
ol
ut
e
l
yi
mpe
r
a
t
i
v
et
ha
ty
ouus
et
h
i
se
x
t
e
ns
i
o
n,
i
t
’
sbe
t
t
e
rt
ous
eRTCSorOCSPa
se
x
pl
a
i
ne
di
n“
Certificate Status Checking using
RTCS”onpa
g
e162,
“
RTCS Server Sessions”onp
a
g
e122,
“
Certificate Revocation
Checking using OCSP”onpa
g
e162,
a
nd“
OCSP Server Sessions”onp
a
g
e122.
The freshestCRL extension is valid in certificates and is identified by CRYPT_CERTINFO_FRESHESTCRL. The structure is identical to cRLDistributionPoint,
with the subfields named with FRESHESTCRL instead of CRLDIST. As with
cRLDistributionPoint, this is a kludge used to work with delta CRLs.
The subjectInfoAccess extension is valid in certificates and is identified by
CRYPT_CERTINFO_SUBJECTINFOACCESS:
Attribute/Description

Type

CRYPT_CERTINFO_SUBJECTINFO_CAREPOSITORY GeneralName
The location at which the CA publishes certificates and CRLs, if the
certificate is for a CA. You should use the URL component of the
GeneralName for this, avoiding the other possibilities.
CRYPT_CERTINFO_SUBJECTINFO_TIMESTAMPING

GeneralName

X.509 Extensions

241

The location at which timestamping services using the timestamp protocol
(TSP) are available. You should use the URL component of the
GeneralName for this, avoiding the other possibilities.
The authorityInfoAccess extension is valid in certificates and CRLs and is identified
by CRYPT_CERTINFO_AUTHORITYINFOACCESS:
Attribute/Description
Type
CRYPT_CERTINFO_AUTHORITYINFO_CAISSUERS
GeneralName
The location at which information on CAs located above the CA that issued
this certificate can be obtained. You should use the URL component of the
GeneralName for this, avoiding the other possibilities.
CRYPT_CERTINFO_AUTHORITYINFO_CERTSTORE GeneralName
The location at which further certificates issued by the CAs that issued this
certificate can be obtained. You should use the URL component of the
GeneralName for this, avoiding the other possibilities.
CRYPT_CERTINFO_AUTHORITYINFO_CRLS
GeneralName
The location at which further certificates issued by the CAs that issued this
certificate can be obtained. You should use the URL component of the
GeneralName for this, avoiding the other possibilities.
CRYPT_CERTINFO_AUTHORITYINFO_OCSP
GeneralName
The location at which certificate revocation information can be obtained.
You should use the URL component of the GeneralName for this, avoiding
the other possibilities.
CRYPT_CERTINFO_AUTHORITYINFO_RTCS
GeneralName
The location at which certificate validity information can be obtained. You
should use the URL component of the GeneralName for this, avoiding the
other possibilities.

Directory Attributes
This extension, identified by CRYPT_CERTINFO_SUBJECTDIRECTORYATTRIBUTES, allows additional X.500 directory attributes to be specified for a
certificate. This extension is valid in certificates, and has the following attributes:
Attribute/Description

Type

CRYPT_CERTINFO_SUBJECTDIR_TYPE
String
The object identifier that identifies the type of the directory attribute.
CRYPT_CERTINFO_SUBJECTDIR_VALUES
The value of the directory attribute.

String

Key Usage, Extended Key Usage, and Netscape certificate type
These extensions specify the allowed usage for the key contained in this certificate.
The keyUsage attribute is a standard extension identified by CRYPT_CERTINFO_KEYUSAGE and is used to specify general-purpose key usages such as key
e
nc
r
y
pt
i
o
n,
di
g
i
t
a
ls
i
g
na
t
ur
e
s
,
a
ndc
e
r
t
i
f
i
c
a
t
es
i
g
ni
ng
.I
fy
oudo
n’
ts
e
tt
hi
sa
t
t
r
i
b
ut
e
,
cryptlib will set it for you to a value appropriate for the key type (for example a key
for a signature-only algorithm such as DSA will be marked as a signature key).
The extKeyUsage attribute is identified by CRYPT_CERTINFO_EXTKEYUSAGE
and is used to specify additional special-case usage such as code signing and SSL
server authentication.
The Netscape certificate type attribute is a vendor-specific attribute identified by
CRYPT_CERTINFO_NS_CERTTYPE and was used to specify certain types of web
browser-specific certificate usage before the extKeyUsage attribute was fully
specified. This attribute has now been superseded by extKeyUsage, but is still found
in a number of certificates.

242

Certificate Extensions

The keyUsage extension has a single numeric attribute with the same identifier as the
extension itself (CRYPT_CERTINFO_KEYUSAGE). This extension is valid in
certificates and certification requests, and contains a bit flag that can contain any of
the following values:
Value

Description

CRYPT_KEYUSAGE_The key can be used for data encryption. This
DATAENCIPHERMENT implies using public-key encryption for bulk
data encryption, which is almost never done.
CRYPT_KEYUSAGE_DIGITALSIGNATURE

The key can be used for digital signature
generation and verification. This is the
standard flag to set for digital signature use.

CRYPT_KEYUSAGE_ENCIPHERONLY
CRYPT_KEYUSAGE_DECIPHERONLY

These flags modify the keyAgreement flag to
allow the key to be used for only one part of
the key agreement process.

CRYPT_KEYUSAGE_KEYAGREEMENT

The key can be used for key agreement. This
is the standard flag to set for key-agreement
algorithms such as Diffie-Hellman.

CRYPT_KEYUSAGE_KEYCERTSIGN
CRYPT_KEYUSAGE_CRLSIGN

The key can be used to sign certificates and
CRLs. Using these flags requires the
basicConstraint CA value to be set.

CRYPT_KEYUSAGE_KEYENCIPHERMENT

The key can be used for key encryption/key
transport. This is the standard flag to set for
encryption use.

CRYPT_KEYUSAGE_NONREPUDIATION

The key can be used for nonrepudiation
purposes. Note that this use is usually
different to CRYPT_KEYUSAGE_DIGITALSIGNATURE and is interpreted in
various incompatible ways by different
standards and profiles.

For example to mark the key in a certificate as being usable for digital signatures and
encryption you would use:
cryptSetAttribute( certificate, CRYPT_CERTINFO_KEYUSAGE,
CRYPT_KEYUSAGE_DIGITALSIGNATURE | CRYPT_KEYUSAGE_KEYENCIPHERMENT );

The extKeyUsage attribute contains a collection of one or more values that specify a
specific type of extended usage that extends beyond the general keyUsage.
This extension is used by applications to determine whether a certificate is meant for
a particular purpose such as timestamping or code signing. The extension is valid in
certificates and certification requests and can contain any of the following values:
Value

Used in

CRYPT_CERTINFO_EXTKEY_CODESIGNING

Code-signing certificate.

CRYPT_CERTINFO_EXTKEY_DIRECTORYSERVICE

Directory service certificate.

CRYPT_CERTINFO_EXTKEY_EMAILPROTECTION

email encryption/signing
certificate.

X.509 Extensions

CRYPT_CERTINFO_EXTKEY_IPSECENDSYSTEM
CRYPT_CERTINFO_EXTKEY_IPSECTUNNEL
CRYPT_CERTINFO_EXTKEY_IPSECUSER

Various IPSEC certificates.

CRYPT_CERTINFO_EXTKEY_MS_CERTTRUSTLISTSIGNING
CRYPT_CERTINFO_EXTKEY_MS_TIMESTAMPSIGNING

Microsoft certificate trust list
signing and timestamping
certificate, used for AuthentiCode
signing.

CRYPT_CERTINFO_EXTKEY_MS_ENCRYPTEDFILESYSTEM

Microsoft encrypted file system
certificate.

CRYPT_CERTINFO_EXTKEY_MS_INDIVIDUALCODESIGNING
CRYPT_CERTINFO_EXTKEY_MS_COMMERCIALCODESIGNING

Microsoft individual and
commercial code-signing
certificate, used for AuthentiCode
signing.

CRYPT_CERTINFO_EXTKEY_MS_SERVERGATEDCRYPTO

Microsoft server-gated crypto
(SGC) certificate, used to enable
strong encryption on non-US
servers.

CRYPT_CERTINFO_EXTKEY_NS_SERVERGATEDCRYPTO

Netscape server-gated crypto
(SGC) certificate, used to enable
strong encryption on non-US
servers.

CRYPT_CERTINFO_EXTKEY_SERVERAUTH
CRYPT_CERTINFO_EXTKEY_CLIENTAUTH

SSL server and client
authentication certificate.

CRYPT_CERTINFO_EXTKEY_TIMESTAMPING

Timestamping certificate.

CRYPT_CERTINFO_EXTKEY_VS_SERVERGATEDCRYPTO_CA

Verisign server-gated crypto CA
certificate, used to sign SGC
certificates.

For example to mark the key in a certificate as being used for SSL server
authentication you would use:
cryptSetAttribute( certificate, CRYPT_CERTINFO_EXTKEY_SERVERAUTH,
CRYPT_UNUSED );

Like the keyUsage extension, the Netscape certificate type extension has a single
numeric attribute with the same identifier as the extension itself (CRYPT_CERTINFO_NS_CERTTYPE). This extension is valid in certificates and
certification requests and contains a bit flag that can contain any of the following
values:
Value

Used in

CRYPT_NS_CERTTYPE_OBJECTSIGNING

Object signing certificate (equivalent to
Mi
c
r
os
of
t
’
sAu
t
he
nt
i
Co
deus
e
)
.

CRYPT_NS_CERTTYPE_SMIME

S/MIME email encryption/signing
certificate.

CRYPT_NS_CERTTYPE_SSLCLIENT
CRYPT_NS_CERTTYPE_SSLSERVER

SSL client and server certificate.

243

244

Certificate Extensions

CRYPT_NS_CERTTYPE_SSLCA
CRYPT_NS_CERTTYPE_SMIMECA
CRYPT_NS_CERTTYPE_OBJECTSIGNINGCA

CA certificates corresponding to the above
certificate types. Using these flags requires
the basicConstraint CA value to be set.

This extension is obsolete and is supported as a read-only attribute by cryptlib. If you
try to set this extension cryptlib will return CRYPT_ERROR_PERMISSION to
i
nd
i
c
a
t
et
ha
ty
o
uc
a
n
’
ts
e
tt
h
i
sa
t
t
r
i
b
ut
ev
a
l
ue
.

Name Constraints
Thena
me
Co
ns
t
r
a
i
nt
se
x
t
e
ns
i
oni
sus
e
dt
oc
o
ns
t
r
a
i
nt
h
ec
e
r
t
i
f
i
c
a
t
e
’
ss
ub
j
e
c
t
Na
mea
n
d
subject altName to lie inside or outside a particular DN subtree or substring, with the
excludedSubtrees attribute taking precedence over the permittedSubtrees attribute.
The principal use for this extension is to allow control of the certificate namespace, so
that a CA can restrict the ability of any CAs it certifies to issue certificates outside a
very restricted domain (for example corporate headquarters might constrain a
divisional CA to only issue certificates for its own business division). This extension
is identified by CRYPT_CERTINFO_NAMECONSTRAINTS, and is valid in
certificates:
Attribute/Description

Type

CRYPT_CERTINFO_PERMITTEDSUBTREES
GeneralName
The subtree within which the subjectName and subject altName of any
issued certificates must lie.
CRYPT_CERTINFO_EXCLUDEDSUBTREES
GeneralName
The subtree within which the subjectName and subject altName of any
issued certificates must not lie.
Due to ambiguities in the encoding rules for strings contained in DNs, it is possible to
avoid the excludedSubtrees for DNs by choosing unusual (but perfectly valid) string
e
nc
odi
ng
st
ha
tdo
n
’
ta
p
pe
a
rto match the excludedSubtrees. Because of this you
should rely on permittedSubtrees rather than excludedSubtrees for DN constraint
enforcement.
The nameConstraints are applied to both the certificate subject name and the subject
altName. For example if a CA run by Cognitive Cybernetics Incorporated wanted to
issue a certificate to a subsidiary CA that was only permitted to issue certificates for
Cog
ni
t
i
v
eCy
be
r
n
e
t
i
c
s
’ma
r
k
e
t
i
ngdi
v
i
s
i
on,
i
twou
l
ds
e
tDNna
mec
ons
t
r
a
i
n
t
swi
t
h
:
cryptSetAttribute( certificate, CRYPT_CERTINFO_PERMITTEDSUBTREES,
CRYPT_UNUSED );
cryptSetAttribute( certificate, CRYPT_CERTINFO_DIRECTORYNAME,
CRYPT_UNUSED );
cryptSetAttributeString( certificate, CRYPT_CERTINFO_COUNTRYNAME,
"US", 2 );
cryptSetAttributeString( certificate, CRYPT_CERTINFO_ORGANIZATIONNAME,
"Cognitive Cybernetics Incorporated", 32 );
cryptSetAttributeString( certificate,
CRYPT_CERTINFO_ORGANIZATIONALUNITNAME, "Marketing", 9 );

This means that the subsidiary CA can only issue certificates to employees of the
marketing division. Note that since the excludedSubtrees attribute is a GeneralName,
the DN is selected through a two-level process, first to select the excludedSubtrees
GeneralName and then to select the DN within the GeneralName.
GeneralName components that have a flat structure (for example email addresses) can
ha
v
ec
o
ns
t
r
a
i
nt
ss
pe
c
i
f
i
e
dt
hr
oug
ht
he‘
*
’wi
l
dc
a
r
d.Fore
x
a
mpl
et
oe
x
t
e
ndt
hea
bov
e
constraint to also include email addresses, the issuing CA would set a name constraint
with:
cryptSetAttribute( certificate, CRYPT_CERTINFO_PERMITTEDSUBTREES,
CRYPT_UNUSED );
cryptSetAttributeString( certificate, CRYPT_CERTINFO_RFC822NAME,
"*@marketing.cci.com", 19 );

CRL Extensions

245

This means that the subsidiary CA can only issue certificates with email addresses
within the marketing division. Note again the selection of the excludedSubtrees
GeneralName followed by the setting of the email address (if the GeneralName is still
s
e
l
e
c
t
e
df
r
o
mt
h
ee
a
r
l
i
e
rc
od
e
,
t
he
r
e
’
sn
on
e
e
dt
or
e
-select it at this point).

Private Key Usage Period
This extensions specifies the date on which the private key for this certificate expires.
This extension is identified by CRYPT_CERTINFO_PRIVATEKEYUSAGEPERIOD and is valid in certificates. This is useful where a
certificate needs to have a much longer lifetime than the private key it corresponds to,
for example a long-term signature might have a lifetime of 10-20 years, but the
private key used to generate it should never be retained for such a long period. The
privateKeyUsagePeriod extension is used to specify a (relatively) short lifetime for
the private key while allowing for a very long lifetime for the signatures it generates:
Attribute/Description

Type

CRYPT_CERTINFO_PRIVATEKEY_NOTBEFORE
Time
CRYPT_CERTINFO_PRIVATEKEY_NOTAFTER
Time
The private key usage period defines the period of time over which the
private key for a certificate object is valid. CRYPT_CERTINFO_PRIVATEKEY_NOTBEFORE specifies the validity start period, and
CRYPT_CERTINFO_PRIVATEKEY_NOTAFTER specifies the validity
end period.

Subject and Authority Key Identifiers
These extensions are used to provide additional identification information for a
certificate, and are usually generated automatically by certificate management code.
For this reason the extensions are marked as read-only.
The authorityKeyIdentifier is identified by CRYPT_CERTINFO_AUTHORITYKEYIDENTIFIER and has the following attributes:
Attribute/Description

Type

CRYPT_CERTINFO_AUTHORITY_KEYIDENTIFIER
Binary data
Binary data identifying the public key in the certificate that was used to sign
this certificate.
CRYPT_CERTINFO_AUTHORITY_CERTISSUER
GeneralName
CRYPT_CERTINFO_AUTHORITY_Binary data
CERTSERIALNUMBER
The issuer name and serial number for the certificate that was used to sign
this certificate. The serial number is treated as a binary string and not as a
numeric value, since it is often 15-20 bytes long.
The subjectKeyIdentifier is identified by CRYPT_CERTINFO_SUBJECTKEYIDENTIFIER and contains binary data identifying the public key in
the certificate.

CRL Extensions
CRLs have a number of CRL-specific extensions that are described below.

CRL Reasons, CRL Numbers, Delta CRL Indicators
These extensions specify various pieces of information about CRLs. The reasonCode
extension is used to indicate why a certificate was revoked. The cRLNumber
extension provides a serial number for CRLs. The deltaCRLIndicator indicates a
delta CRL that contains changes between a base CRL and a delta-CRL (this is used to
reduce the overall size of CRLs).
The reasonCode extension is identified by CRYPT_CERTINFO_CRLREASON and
is valid in CRLs. The extension has a single numeric attribute with the same

246

Certificate Extensions

identifier as the extension itself (CRYPT_CERTINFO_CRLREASON) which
contains a bit flag that can contain one of the following values:
Value

Description

CRYPT_CRLREASON_AFFILIATIONCHANGED

The affiliation of the certificate owner
has changed, so that the subjectName or
subject altName is no longer valid.

CRYPT_CRLREASON_CACOMPROMISE
CRYPTCRLREASON_AACOMPROMISE

The CA or attribute authority that issued
the certificate was compromised.

CRYPT_CRLREASON_CERTIFICATEHOLD

The certificate is to be placed on hold
pending further communication from the
CA (the further communication may be
provided by the holdInstructionCode
extension).

CRYPT_CRLREASON_CESSATIONOFOPERATION

The certificate owner has ceased to
operate in the role that requires the use of
the certificate.

CRYPT_CRLREASON_KEYCOMPROMISE

The key for the certificate was
compromised.

CRYPT_CRLREASON_PRIVILEGEWITHDRAWN

The privilege granted in an attribute
certificate is no longer valid.

CRYPT_CRLREASON_REMOVEFROMCRL

The certificate should be removed from
the certificate revocation list.

CRYPT_CRLREASON_SUPERSEDED

The certificate has been superseded.

CRYPT_CRLREASON_UNSPECIFIED

No reason for the CRL. You should
avoid including a reasonCode at all rather
than using this code.

To indicate that a certificate is being revoked because the key it corresponds to has
been compromised, you would use:
cryptSetAttribute( certificate, CRYPT_CERTINFO_CRLREASON,
CRYPT_CRLREASON_KEYCOMPROMISE );

The cRLNumber extension is identified by CRYPT_CERTINFO_CRLNUMBER and
is valid in CRLs. The extension has a single attribute with the same identifier as the
extension itself (CRYPT_CERTINFO_CRLNUMBER) which contains a
monotonically increasing sequence number for each CRL issued. This allows an
application to check that it has received and processed each CRL that was issued.
The deltaCRLIndicator extension is identified by CRYPT_CERTINFO_DELTACRLINDICATOR and is valid in CRLs. The extension has a single attribute
with the same identifier as the extension itself (CRYPT_CERTINFO_DELTACRLINDICATOR) which contains the cRLNumber of the base CRL from
which this delta CRL is being constructed (see certificate standards documents for
more information on delta CRLs).

Hold Instruction Code
This extension contains a code that specifies what to do with a certificate that has
been placed on hold through a CRL (that is, its revocation reasonCode is
CRYPT_CRLREASON_CERTIFICATEHOLD). The extension is identified by
CRYPT_CERTINFO_HOLDINSTRUCTIONCODE, is valid in CRLs, and can
contain one of the following values:

CRL Extensions

Value

Description

CRYPT_HOLDINSTRUCTION_CALLISSUER

Call the certificate issuer for
details on the certificate hold.

247

CRYPT_HOLDINSTRUCTION_NONE No hold instruction code. You
should avoid including a
holdInstructionCode at all rather
than using this code.
CRYPT_HOLDINSTRUCTION_REJECT

Reject the transaction that the
revoked/held certificate was to be
used for.

As the hold code descriptions indicate, this extension was developed mainly for use
in the financial industry. To indicate that someone should call the certificate issuer
for further information on a certificate hold, you would use:
cryptSetAttribute( certificate, CRYPT_CERTINFO_HOLDINSTRUCTIONCODE,
CRYPT_HOLDINSTRUCTION_CALLISSUER );

Yous
ho
ul
dn
’
tus
et
h
i
se
x
t
e
ns
i
on(
ort
heCRYPT_
CRLREASON_CERTIFICATEHOLD reasonCode) unless you really need to because although a
mechanism was defined for placing a certificate on hold, no-one ever defined one for
r
e
mov
i
ngi
tf
r
om t
hi
ss
t
a
t
e
,
s
oonc
ei
t
’
sonh
ol
di
t
’
sr
e
v
ok
e
dnoma
t
t
e
rwha
tt
he
reasonCode says.

Invalidity Date
This extension contains the date on which the private key for a certificate became
invalid. The extension is identified by CRYPT_CERTINFO_INVALIDITYDATE
and is valid in CRLs:
Attribute/Description

Type

CRYPT_CERTINFO_INVALIDITYDATE
Time
The date on which the key identified in a CRL became invalid.
Note that a CRL contains both its own date and a date for each revoked certificate, so
t
hi
se
x
t
e
ns
i
oni
so
nl
yus
e
f
uli
ft
he
r
e
’
ss
o
mer
e
a
s
o
nf
orc
o
mmu
ni
c
a
t
i
ngt
hef
a
c
tt
h
a
ta
key compromise occurred at a time other than the CRL issue time or the certificate
revocation time.

Issuing Distribution Point and Certificate Issuer
These extensions specify the CRL distribution point for a CRL and provide various
pieces of additional information about the distribution point. The
issuingDistributionPoint specifies the distribution point for a CRL, and the
certificateIssuer specifies the issuer for an indirect CRL as indicated by the
issuingDistributionPoint extension.
The issuingDistributionPoint extension is identified by CRYPT_CERTINFO_ISSUINGDISTRIBUTIONPOINT and is valid in CRLs:
Attribute/Description

Type

CRYPT_CERTINFO_ISSUINGDIST_FULLNAME
GeneralName
The location at which CRLs may be obtained. You should use the URL
component of the GeneralName for this, avoiding the other possibilities.
CRYPT_CERTINFO_ISSUINGDIST_USERCERTSONLY
Boolean
CRYPT_CERTINFO_ISSUINGDIST_CACERTSONLY
Boolean
CRYPT_CERTINFO_ISSUINGDIST_SOMEREASONSONLY Numeric
CRYPT_CERTINFO_ISSUINGDIST_INDIRECTCRL
Boolean
See certificate standards documents.
Note that the CRYPT_CERTINFO_ISSUINGDIST_SOMEREASONSONLY
attribute has the same allowable set of values as the cRLReasons reasonCode, but in
this case is given as a series of bit flags rather than the reasonCode numeric value

248

Certificate Extensions
(
be
c
a
us
eX.
509s
a
y
ss
o,
t
h
a
t
’
swhy
)
.Be
c
a
us
eo
ft
hi
sy
oumus
tus
eCRYPT_CRLREASONFLAGS_name instead of CRYPT_CRLREASON_name when getting
and setting these values.
The certificateIssuer extension contains the certificate issuer for an indirect CRL.
The extension is identified by CRYPT_CERTINFO_CERTIFICATEISSUER and is
valid in CRLs:
Attribute/Description

Type

CRYPT_CERTINFO_CERTIFICATEISSUER
See certificate standards documents.

GeneralName

Digital Signature Legislation Extensions
Various digital signature laws specify extensions beyond the X.509v3 and X.509v4
ones that are described below.

Certificate Generation Date
The German signature law specifies an extension containing the date at which the
certificate was generated. This is necessary for post-dated certificates to avoid
pr
ob
l
e
msi
ft
heCA’
sk
e
yi
sc
ompr
o
mi
s
e
db
e
t
we
e
nt
h
et
i
met
hec
e
r
t
i
f
i
c
a
t
ei
si
s
s
ue
d
and the time it takes effect. The extension is identified by CRYPT_CERTINFO_SIGG_DATEOFCERTGEN and contains the following attributes:
Attribute/Description

Type

CRYPT_CERTINFO_SIGG_DATEOFCERTGEN
The date on which the certificate was issued.

Time

Other Restrictions
The German signature law specifies an extension containing any other general freeform restrictions that may be imposed on the certificate. The extension is identified
by CRYPT_CERTINFO_SIGG_RESTRICTION and contains the following
attributes:
Attribute/Description

Type

CRYPT_CERTINFO_SIGG_RESTRICTION
String
Text containing any further restrictions not already handled via certificate
policies or constraints.

Reliance Limit
The German signature law specifies an extension containing a reliance limit for the
certificate, which specifies the (recommended) monetary reliance limit for the
certificate. The extension is identified by CRYPT_CERTINFO_SIGG_MONETARYLIMIT and contains the following attributes:
Attribute/Description

Type

CRYPT_CERTINFO_SIGG_MONETARY_CURRENCY
The three-letter currency code.

String

CRYPT_CERTINFO_SIGG_MONETARY_AMOUNT
Thea
mo
un
t
,
s
pe
c
i
f
i
e
da
sa
ni
nt
e
g
e
ri
nt
her
a
ng
e1…20
0.

Integer

CRYPT_CERTINFO_SIGG_MONETARY_EXPONENT
Integer
Thee
x
po
ne
ntf
ort
h
ea
mou
nt
,
s
pe
c
i
f
i
e
da
sa
ni
nt
e
g
e
r1…200,
so that the
actual value is amount 10exponent.

Signature Delegation
The German signature law specifies an extension containing details about signature
de
l
e
g
a
t
i
o
n,
i
nwh
i
c
honepa
r
t
yma
ys
i
g
nonbe
ha
l
fo
fa
not
h
e
r(
f
ore
x
a
mp
l
es
o
me
on
e
’
s

Qualified Certificate Extensions

249

secretary signing correspondence on their behalf). The extension is identified by
CRYPT_CERTINFO_SIGG_PROCURATION and contains the following attributes:
Attribute/Description

Type

CRYPT_CERTINFO_SIGG_PROCURE_String
TYPEOFSUBSTITUTION
The type of signature delegation beingpe
r
f
or
me
d(
f
ore
x
a
mp
l
e“
Si
g
ne
do
n
be
h
a
l
fo
f
”
)
.
CRYPT_CERTINFO_SIGG_PROCURE_SIGNINGFOR
GeneralName
The identity of the person or organisation the signer is signing on behalf of.

Qualified Certificate Extensions
Qualified certificates contain additional extensions beyond the X.509v3 ones that are
described below.

Biometric Info
The biometricInfo extension contains biometric information in the form of a hash of a
biometric template. The extension is identified by CRYPT_CERTINFO_BIOMETRICINFO and is valid in certificates and certification requests:
Attribute/Description

Type

CRYPT_CERTINFO_BIOMETRICINFO_TYPE
Numeric
The type of the biometric data, see certificate standards documents.
CRYPT_CERTINFO_BIOMETRICINFO_HASHALGO
String
The object identifier for the hash algorithm used to hash the biometric
template.
CRYPT_CERTINFO_BIOMETRICINFO_HASH
The hash of the biometric template.

String

CRYPT_CERTINFO_BIOMETRICINFO_URL
String
An optional URL at which the biometric data may be found.

QC Statements
The qcStatements extension contains defined statements for a qualified certificate.
The extension is identified by CRYPT_CERTINFO_QCSTATEMENT and is valid in
certificates and certification requests:
Attribute/Description

Type

CRYPT_CERTINFO_QCSTATEMENT_SEMANTICS
String
An object identifier identifying the defined statement for this certificate.
CRYPT_CERTINFO_QCSTATEMENT_REGISTRATIONAUTHORITY
See certificate standards documents.

String

SET Extensions
SET specifies a number of extensions beyond the X.509v3 ones that are described
below.

SET Card Required and Merchant Data
These extensions specify various pieces of general information used in the SET
electronic payment protocol.
The cardRequired extension contains a flag indicating whether a card is required for a
transaction. The extension is identified by CRYPT_CERTINFO_SET_CERTCARDREQUIRED, and is valid in certificates and certification requests. The
extension contains a single boolean attribute with the same identifier as the extension

250

Certificate Extensions

itself (CRYPT_CERTINFO_SET_CARDREQUIRED) which is explained in the SET
standards documents.
The merchantData extension contains further information on a merchant. The
extension is identified by CRYPT_CERTINFO_SET_MERCHANTDATA and is
valid in certificates and certification requests:
Attribute/Description

Type

CRYPT_CERTINFO_SET_MERACQUIRERBIN
String
CRYPT_CERTINFO_SET_MERAUTHFLAG
Boolean
CRYPT_CERTINFO_SET_MERCOUNTRY
Numeric
CRYPT_CERTINFO_SET_MERID
String
Me
r
c
ha
nt
’
s6-digit BIN, authorisation flag, ISO country code, and merchant
ID.
CRYPT_CERTINFO_SET_MERCHANTCITY
String
CRYPT_CERTINFO_SET_MERCHANTCOUNTRYNAME String
CRYPT_CERTINFO_SET_MERCHANTLANGUAGE
String
CRYPT_CERTINFO_SET_MERCHANTNAME
String
CRYPT_CERTINFO_SET_MERCHANTPOSTALCODE
String
CRYPT_CERTINFO_SET_MERCHANTSTATEPROVINCE String
Me
r
c
ha
nt
’
sl
a
ng
ua
g
e
,na
me
,
c
i
t
y
,
s
t
a
t
eorpr
ov
i
nc
e
,
p
os
t
a
lc
ode
,
a
ndc
ou
nt
r
y
name.

SET Certificate Type, Hashed Root Key, and Tunnelling
These extensions specify various pieces of certificate management information used
in the SET electronic payment protocol.
The certificateType extension contains the SET certificate type. The extension is
identified by CRYPT_CERTINFO_SET_CERTIFICATETYPE and is valid in
certificates and certification requests. The extension contains a single bit flag
attribute with the same identifier as the extension itself (CRYPT_CERTINFO_SET_CERTIFICATETYPE) and can contain any of the following values that are explained
in the SET standards documentation:
Value
CRYPT_SET_CERTTYPE_ACQ
CRYPT_SET_CERTTYPE_BCA
CRYPT_SET_CERTTYPE_CARD
CRYPT_SET_CERTTYPE_CCA
CRYPT_SET_CERTTYPE_GCA
CRYPT_SET_CERTTYPE_MCA
CRYPT_SET_CERTTYPE_MER
CRYPT_SET_CERTTYPE_PCA
CRYPT_SET_CERTTYPE_PGWY
CRYPT_SET_CERTTYPE_RCA
The hashedRootKey extension contains a thumbprint (SET-speak for a hash) of a
SET root key. The extension is identified by CRYPT_CERTINFO_SET_HASHEDROOTKEY and is valid in certificates and certification requests. The
extension contains a single attribute:
Attribute/Description

Type

CRYPT_CERTINFO_SET_ROOTKEYTHUMBPRINT
Binary data
Binary string containing the root key thumbprint (see the SET standards
documents).

Application-specific Extensions

251

You can obtain the key hash which is required for the thumbprint from another
certificate by reading its CRYPT_CERTINFO_SUBJECTKEYIDENTIFIER attribute
and t
he
na
d
di
ngi
tt
ot
hec
e
r
t
i
f
i
c
a
t
ey
o
u’
r
ewor
k
i
ngwi
t
ha
st
heCRYPT_CERTINFO_SET_ROOTKEYTHUMBPRINT attribute. cryptlib will perform the
further work required to convert this attribute into the root key thumbprint.
The tunnelling extension contains a tunnelling indicator and algorithm identifier. The
extension is identified by CRYPT_CERTINFO_SET_TUNNELING and is valid in
certificates and certification requests.
Attribute/Description

Type

CRYPT_CERTINFO_SET_TUNNELINGFLAG
CRYPT_CERTINFO_SET_TUNNELINGALGID
See SET standards documents.

Boolean
String

Application-specific Extensions
Various applications such as certificate management protocols have their own
extensions that extend or complement the X.509 ones. These are described below.

OCSP Extensions
These extensions specify various pieces of certificate management information used
in the OCSP certificate management protocol.
The noCheck extension indicates that the certificate should be automatically trusted
when used to sign OCSP responses. The extension is identified by CRYPT_CERTINFO_OCSP_NOCHECK and is valid in certificates and certification requests.
The extension contains a numeric attribute with the same identifier as the extension
itself (CRYPT_CERTINFO_OCSP_NOCHECK) which is always set to
CRYPT_UNUSED since it has no inherent value associated with it.
Attribute/Description

Type

CRYPT_CERTINFO_OCSP_NOCHECK
See OCSP standards documents.

Numeric

Vendor-specific Extensions
A number of vendors have defined their own extensions that extend or complement
the X.509 ones. These are described below.

Netscape Certificate Extensions
Netscape defined a number of extensions that mostly predate the various X.509v3
extensions that now provide the same functionality. The various Netscape certificate
extensions are:
Extension/Description

Type

CRYPT_CERTINFO_NS_BASEURL
String
Aba
s
eURLwhi
c
h,
i
fpr
e
s
e
nt
,
i
sa
dde
dt
oa
l
lp
a
r
t
i
a
lURL’
si
nNe
t
s
c
a
pe
extensions to create a full URL.
CRYPT_CERTINFO_NS_CAPOLICYURL
String
The URL at which the certificate policy under which this certificate was
issued can be found.
CRYPT_CERTINFO_NS_CAREVOCATIONURL
String
The URL at which the revocation status of a CA certificate can be checked.
CRYPT_CERTINFO_NS_CERTRENEWALURL
String
The URL at which a form allowing renewal of this certificate can be found.
CRYPT_CERTINFO_NS_COMMENT
String
A comment which should be displayed when the certificate is viewed.

252

Certificate Extensions

CRYPT_CERTINFO_NS_REVOCATIONURL
String
The URL at which the revocation status of a server certificate can be
checked.
CRYPT_CERTINFO_NS_SSLSERVERNAME
String
A wildcard string containing a shell expression that matches the hostname of
the SSL server using this certificate.
Note that each of these entries represent a separate extension containing a single text
string, they have merely been listed in a single table for readability. You should
avoid using these extensions if possible and instead use one of the standard X.509v3
extensions.

Thawte Certificate Extensions
Thawte Consulting have defined an extension that allows the use of certificates with
secure extranets. This extension is identified by CRYPT_CERTINFO_STRONGEXTRANET and is valid in certificates and certification requests:
Attribute/Description

Type

CRYPT_CERTINFO_STRONGEXTRANET_ZONE
CRYPT_CERTINFO_STRONGEXTRANET_ID
Extranet zone and ID.

Numeric
Binary data

Generic Extensions
Beyond the standardised extensions listed above there exist any number of obscure or
non-standard certificate extensions. cryptlib allows you to work with these
extensions using cryptAddCertExtension, cryptGetCertExtension, and
cryptDeleteCertExtension, which allow you to add, retrieve, or delete a complete
encoded extension identified by its ASN.1 object identifier. The extension data must
be a complete DER-encoded ASN.1 object without the OCTET STRING wrapper
which is used for all extensions (cryptlib will add this itself). For example if you
wanted to add a 4-byte UTF8 string as an extension the data would be 0C 04 xx
xx xx xx. If you pass in extension data to cryptAddCertExtension t
ha
ti
s
n
’
ta
valid ASN.1-encoded object, cryptlib will return CRYPT_ERROR_PARAM4 to
indicate that the data is in an invalid format.
If a certificate object contains a non-s
t
a
n
da
r
de
x
t
e
ns
i
o
n,
c
r
y
pt
l
i
bwo
n’
ti
n
c
l
u
dei
ti
n
the object when you sign it unless you set the CRYPT_OPTION_CERT_SIGNUNRECOGNISEDATTRIBUTES option to true. This is to avoid problems
where a CA could end up signing arbitrary data in an unrecognised certificate
extension.
If the extension you are trying to add is already handled as a standard extension,
c
r
y
pt
l
i
bwi
l
lr
e
t
ur
nCRYPT_
ERROR_
PERMI
SSI
ONt
oi
n
di
c
a
t
et
ha
ty
o
uc
a
n
’
ta
d
d
the extension in this manner but have to add it using cryptSetAttribute/
cryptSetAttributeString.

CMS/SMIME Attributes

253

Other Certificate Object Extensions
Certificate objects other than certificates and CRLs can also contain extensions. In
the following descriptions only the generally useful attributes have been described.
The full range of attributes is enormous and will probably never be used in real life.
These attributes are marked wi
t
h“
Se
es
t
a
n
da
r
dsd
oc
u
me
n
t
s
”t
oi
nd
i
c
a
t
et
ha
ty
ou
should refer to other documents to obtain information about their usage (this is also a
g
oodi
nd
i
c
a
t
i
o
nt
h
a
ty
ous
ho
u
l
dn
’
tr
e
a
l
l
ybeus
i
ngt
hi
sa
t
t
r
i
but
e
)
.

CMS/SMIME Attributes
The CMS and S/MIME standards specify various attributes that can be included with
signatures. In addition there are a variety of proprietary and vendor-specific
attributes that are also handled by cryptlib. In the following description only the
generally useful attributes have been described, the full range of attributes is
enormous and requires a number of standards specifications (often followed by cries
f
orhe
l
ponma
i
l
i
ngl
i
s
t
s
)t
oi
n
t
e
r
pr
e
tt
he
m.The
s
ea
t
t
r
i
bu
t
e
sa
r
ema
r
k
e
dwi
t
h“
Se
e
S/
MI
MEs
t
a
nda
r
dsdoc
u
me
nt
s
”t
oi
n
di
c
a
t
et
hat you should refer to other documents
t
oo
bt
a
i
ni
n
f
or
ma
t
i
o
na
b
ou
tt
h
e
i
rus
e(
t
h
i
si
sa
l
s
oag
oodi
nd
i
c
a
t
i
o
nt
h
a
ty
ous
h
ou
l
d
n’
t
really be using this attribute).

Content Type
This is a standard CMS attribute identified by CRYPT_CERTINFO_CMS_CONTENTTYPE and is used to specify the type of data which is being signed. This
is used because some signed information could be interpreted in different ways
de
p
e
n
di
ngont
h
eda
t
at
y
pei
t
’
ss
upp
os
e
dt
or
e
pr
e
s
e
nt(
f
ore
x
a
mp
l
es
o
me
t
hi
ngv
i
e
we
d
as encrypted data could be interpreted quite differently if viewed as plain data). If
y
oudo
n’
ts
e
tt
hi
sa
t
t
r
i
b
ut
e
,
c
r
y
pt
l
i
bwi
l
ls
e
ti
tf
ory
oua
n
dma
r
kt
hes
i
g
ne
dc
ont
e
n
ta
s
plain data.
The content-type CMS attribute can contain one of the following CRYPT_CONTENT_TYPE values:
Value

Description

CRYPT_CONTENT_DATA

Plain data.

CRYPT_CONTENT_SIGNEDDATA

Signed data.

CRYPT_CONTENT_ENVELOPEDDATA

Data encrypted using a password or
public-key or conventional encryption.

CRYPT_CONTENT_SIGNEDANDENVELOPEDDATA

Data which is both signed and enveloped
(this is an obsolete composite content
t
y
pet
h
a
ts
h
ou
l
d
n’
tbeus
e
d)
.

CRYPT_CONTENT_DIGESTEDDATA

Hashed data.

CRYPT_CONTENT_ENCRYPTEDDATA

Data encrypted directly with a session
key.

CRYPT_CONTENT_COMPRESSEDDATA

Compressed data.

CRYPT_CONTENT_TSTINFO

Timestamp token generated by a
timestamp authority (TSA).

CRYPT_CONTENT_SPCINDIRECTDATACONTEXT

Indirectly signed data used in
Authenticode signatures.

The distinction between the different types arises from the way they are specified in
the standards documents, as a rule of thumb if the data being signed is encrypted then
use CRYPT_CONTENT_ENVELOPEDDATA (rather than CRYPT_CONTENT_-

254

Other Certificate Object Extensions
ENCRYPTEDDATA,whi
c
hi
ss
l
i
g
ht
l
ydi
f
f
e
r
e
nt
)
,
i
fi
t
’
ss
i
g
ne
dt
he
nus
eCRYPT_CONTENT_SI
GNEDDATA,a
ndi
fi
t
’
s anything else then use CRYPT_CONTENT_DATA.Fore
x
a
mp
l
et
oi
d
e
nt
i
f
yt
heda
t
ay
ou
’
r
es
i
g
ni
nga
se
nc
r
y
pt
e
d
data, you would use:
cryptSetAttribute( cmsAttributes, CRYPT_CERTINFO_CMS_CONTENTTYPE,
CRYPT_CONTENT_ENVELOPEDDATA );

I
fy
ou’
r
eg
e
ne
r
a
t
i
ngt
hes
i
g
na
ture via the cryptlib enveloping code then cryptlib will
s
e
tt
hec
or
r
e
c
tt
y
p
ef
ory
ous
ot
he
r
e
’
snon
e
e
dt
os
e
ti
ty
our
s
e
l
f
.

Countersignature
This CMS attribute contains a second signature that countersigns one of the
signatures on the data (that is, it signs the other signature rather than the data). The
attribute is identified by CRYPT_CERTINFO_CMS_COUNTERSIGNATURE:
Attribute/Description

Type

CRYPT_CERTINFO_CMS_COUNTERSIGNATURE
See S/MIME standards documents.

Binary data

Message Digest
This read-only CMS attribute is used as part of the signing process and is generated
automatically by cryptlib. The attribute is identified by CRYPT_CERTINFO_CMS_MESSAGEDIGEST:
Attribute/Description

Type

CRYPT_CERTINFO_CMS_MESSAGEDIGEST
The hash of the content being signed.

Binary data

Signing Description
This CMS attribute contains a short text message with an additional description of the
data being signed. For example if the signed message was a response to a received
signed message, the signing description might contain an indication of the type of
me
s
s
a
g
ei
t
’
sb
e
i
ngs
e
nti
nr
e
s
pons
et
o.Not
et
ha
tCMSha
sanu
mb
e
rofs
p
e
c
i
a
l
purpose signing attributes such as message receipt information that allow automated
processing of messages that contain them, so you should only use this free-form
human-r
e
a
da
bl
ea
t
t
r
i
bu
t
ef
orc
a
s
e
st
h
a
ta
r
e
n
’
tc
ov
e
r
e
dbys
pe
c
i
a
l
-case attributes
designed for the purpose.
The attribute is identified by CRYPT_CERTINFO_CMS_SIGNINGDESCRIPTION:
Attribute/Description

Type

CRYPT_CERTINFO_CMS_SIGNINGDESCRIPTION
Free-form text annotation for the message being signed.

String

Signing Time
This is a standard CMS attribute identified by CRYPT_CERTINFO_CMS_SIGNINGTIME and is used to specify the time at which the signature was generated.
I
fy
oudo
n
’
ts
e
t this attribute, cryptlib will set it for you.
Attribute/Description

Type

CRYPT_CERTINFO_CMS_SIGNINGTIME
The time at which the signature was generated.

Time

Extended CMS/SMIME Attributes
The attributes given above are the standard CMS attributes. Extending beyond this
are further attributes that are defined in additional standards documents and that apply
mostly to S/MIME messages, as well as vendor-specific and proprietary attributes.

Extended CMS/SMIME Attributes

255

Before you use these additional attributes you should ensure that any software you
plan to interoperate with can process them, since currently almost nothing will
r
e
c
og
ni
s
et
he
m(
f
ore
x
a
mpl
ei
t
’
sn
otag
oodi
de
at
opu
tas
e
c
ur
i
t
yl
a
be
lony
ourd
a
t
a
and expect other software to handle it correctly).

AuthentiCode Attributes
AuthentiCode code-signing uses a number of attributes that apply to signed
executable content. These attributes are listed below.
The agency information CMS attribute, identified by CRYPT_CERTINFO_CMS_SPCAGENCYINFO, is used to provide extra information about the signer of the data
and has the following attributes:
Attribute/Description

Type

CRYPT_CERTINFO_CMS_SPCAGENCYURL
String
The URL of a web page containing more information about the signer.
The statement type CMS attribute, identified by CRYPT_CERTINFO_CMS_SPCSTATEMENTTYPE, is used to identify whether the content was signed by an
individual or a commercial organisation, and has the following attributes:
Attribute/Description

Type

CRYPT_CERTINFO_CMS_SPCSTMT_INDIVIDUALCODESIGNING
The data was signed by an individual.

Numeric

CRYPT_CERTINFO_CMS_SPCSTMT_COMMERCIALCODESIGNING
The data was signed by a commercial organisation.

Numeric

The opus info CMS attribute, identified by CRYPT_CERTINFO_CMS_SPCOPUSINFO, is used to identify program details for AuthentiCode use, and has
the following attributes:
Attribute/Description

Type

CRYPT_CERTINFO_CMS_SPCOPUSINFO_NAME
Program name/version.

String

CRYPT_CERTINFO_CMS_SPCOPUSINFO_URL
AuthentiCode information URL.

String

Note that the CRYPT_CERTINFO_CMS_SPCOPUSINFO_NAME attribute is a
Unicode string, as used by Windows NT/2000/XP and Windows CE.
For example to indicate that the data was signed by an individual, you would use:
cryptSetAttribute( cmsAttributes,
CRYPT_CERTINFO_CMS_SPCSTMT_COMMERCIALCODESIGNING, CRYPT_UNUSED );

For example to create an AuthentiCode signature as a commercial organisation you
would use:
CRYPT_CERTIFICATE cmsAttributes;
/* Create the CMS attribute object and add the AuthentiCode attributes
*/
cryptCreateCert( &cmsAttributes, cryptUser,
CRYPT_CERTTYPE_CMS_ATTRIBUTES );
cryptSetAttributeString( cmsAttributes,
CRYPT_CERTINFO_CMS_SPCAGENCYURL,
"http://homepage.organisation.com", 32 );
cryptSetAttribute( cmsAttributes,
CRYPT_CERTINFO_CMS_SPCSTMT_COMMERCIALCODESIGNING, CRYPT_UNUSED );
/* Add the content-type required for AuthentiCode data */
cryptSetAttribute( cmsAttributes, CRYPT_CERTINFO_CMS_CONTENTTYPE,
CRYPT_CONTENT_SPCINDIRECTDATACONTEXT );

256

Other Certificate Object Extensions

/* Sign the data with the attributes included */
cryptCreateSignatureEx( ... );
cryptDestroyCert( cmsAttributes );

The other attributes used when signing are standard attributes that will be added
automatically for you by cryptlib.

Content Hints
This CMS attribute can be supplied in the outer layer of a multi-layer message to
provide information on what the innermost layer of the message contains. The
attribute is identified by CRYPT_CERTINFO_CMS_CONTENTHINTS and has the
following attributes:
Attribute/Description

Type

CRYPT_CERTINFO_CMS_CONTENTHINT_String
DESCRIPTION
A human-readable description that may be useful when processing the
content.
CRYPT_CERTINFO_CMS_CONTENTHINT_TYPE
Numeric
The type of the innermost content, specified as a CRYPT_CONTENT_content-type value.

DOMSEC Attributes
The domain security (DOMSEC) attributes are used to handle delegated signing by
systems such as mail gateways. The signature type CMS attribute, identified by
CRYPT_CERTINFO_CMS_SIGTYPEIDENTIFIER, is used to identify the signature
type, and has the following attributes:
Attribute/Description

Type

CRYPT_CERTINFO_CMS_SIGTYPEID_ADDITIONALATTRIBUTES
Additional attributes for a domain signature.

Numeric

CRYPT_CERTINFO_CMS_SIGTYPEID_DOMAINSIG
Domain signature by a gateway on behalf of a user.

Numeric

CRYPT_CERTINFO_CMS_SIGTYPEID_ORIGINATORSIG Numeric
Indi
c
a
t
i
ont
ha
tt
h
es
i
g
ne
ri
st
heor
i
g
i
na
t
oro
ft
h
eme
s
s
a
g
e
.Thi
sa
t
t
r
i
b
ut
ei
s
n
’
t
normally used, since it corresponds to a standard (non-DOMSEC) signature..
CRYPT_CERTINFO_CMS_SIGTYPEID_REVIEWSIG
Numeric
Review signature to indicate that the domain signer has reviewed the
message.

Mail List Expansion History
This CMS attribute contains information on what happened to a message when it was
processed by mailing list software. It is identified by CRYPT_CERTINFO_CMS_MLEXPANSIONHISTORY and contains the following attributes:

Extended CMS/SMIME Attributes

Attribute/Description

257

Type

CRYPT_CERTINFO_CMS_MLEXP_ENTITYIDENTIFIER Binary data
See S/MIME standards documents.
CRYPT_CERTINFO_CMS_MLEXP_TIME
Time
The time at which the mailing-list software processed the message.
CRYPT_CERTINFO_CMS_MLEXP_NONE
—
CRYPT_CERTINFO_CMS_MLEXP_INSTEADOF
GeneralCRYPT_CERTINFO_CMS_MLEXP_INADDITIONTO
Name
This attribute can have one of the three values specified above, and is used
to indicate a receipt policy that overrides the one given in the original
message. See the S/MIME standards documents for more information.

Nonce
This CMS attribute nonce is used to prevent replay attacks. The attribute is identified
by CRYPT_CERTINFO_CMS_NONCE:
Attribute/Description

Type

CRYPT_CERTINFO_CMS_NONCE
Nonce to prevent replay attacks.

Binary data

Receipt Request
This CMS attribute is used to request a receipt from the recipient of a message and is
identified by CRYPT_CERTINFO_CMS_RECEIPT_REQUEST. As with the
s
e
c
ur
i
t
yl
a
be
la
t
t
r
i
bu
t
e
,
y
ous
hou
l
d
n
’
tr
e
l
yont
her
e
c
i
pient of a message being able to
do anything with this information, which consists of the following attributes:
Attribute/Description

Type

CRYPT_CERTINFO_CMS_RECEIPT_Binary data
CONTENTIDENTIFIER
A magic value used to identify a message, see the S/MIME standards
documents for more information.
CRYPT_CERTINFO_CMS_RECEIPT_FROM
CRYPT_CERTINFO_CMS_RECEIPT_TO

Numeric
GeneralName
An indication of who receipts should come from and who they should go to,
see the S/MIME standards documents for more information.

SCEP Attributes
The Simple Certificate Enrolment Protocol uses a variety of protocol-specific
attributes that are attached to CMS signed data and are used to manage the operation
of the protocol. These attributes are not normally used with CMS but are provided
f
orus
ebyc
r
y
pt
l
i
b
’
sSCEPi
mpl
e
me
nt
a
t
i
on.TheSCEPa
t
t
r
i
but
e
sa
r
e
:

258

Other Certificate Object Extensions

Attribute/Description

Type

CRYPT_CERTINFO_SCEP_MESSAGETYPE
The SCEP message type.

String

CRYPT_CERTINFO_SCEP_PKISTATUS
The processing status of an SCEP request.

String

CRYPT_CERTINFO_SCEP_FAILINFO
String
Extended error information if the SCEP processing status indicates that an
error occurred.
CRYPT_CERTINFO_SCEP_SENDERNONCE
Binary data
CRYPT_CERTINFO_SCEP_RECIPIENTNONCE
Nonce values used to protect against message replay attacks. Note that these
values duplicate the more usual CRYPT_CERTINFO_CMS_NONCE
a
t
t
r
i
bu
t
e
,
whi
c
hs
ho
ul
dbeus
e
di
np
l
a
c
eo
ft
he
s
ea
t
t
r
i
b
ut
e
su
nl
e
s
st
he
y
’
r
e
specifically being used for SCEP.
CRYPT_CERTINFO_SCEP_TRANSACTIONID
String
A value that uniquely identifies the entity requesting a certificate.
In addition to these attributes, SCEP also uses an additional attribute which is added
t
oPKCS#
10r
e
q
ue
s
t
se
v
e
nt
h
oug
hi
t
’
saCMSa
t
t
r
i
bu
t
e
.I
tt
he
r
e
f
or
ea
c
t
sa
sa
certificate attribute rather than a CMS attribute. The attribute is identified by
CRYPT_CERTINFO_CHALLENGEPASSWORD:
Attribute/Description

Type

CRYPT_CERTINFO_CHALLENGEPASSWORD
Password used to authorise certificate issue requests.

String

Security Label, Equivalent Label
These CMS attributes specify security information for the content contained in the
message, allowing recipients to decide how they should process it. For example an
i
mpl
e
me
nt
a
t
i
o
nc
o
ul
dr
e
f
us
et
odi
s
pl
a
yame
s
s
a
g
et
oar
e
c
i
p
i
e
n
twhoi
s
n
’
tc
l
e
a
r
e
dt
o
see it (this assumes that the recipient software is implemented at least in part using
tamper-resistant hardware, since a pure software implementation could be set up to
ignore the security label). These attributes originate (in theory) in X.400 and (in
practice) in DMS, the US DoD secure email system, and virtually no implementations
out
s
i
det
hi
sa
r
e
aun
de
r
s
t
a
ndt
he
ms
oy
ous
h
ou
l
d
n’
tr
e
l
yont
he
mt
oe
ns
ur
epr
o
pe
r
processing of a message.
The basic security label on a message is identified by CRYPT_CERTINFO_CMS_SECURITYLABEL. Since different organisations have different ways of handling
security policies, their labelling schemes may differ, so the equivalent labels CMS
attribute, identified by CRYPT_CERTINFO_CMS_EQUIVALENTLABEL, can be
used to map from one to the other. These contain the following attributes:

Extended CMS/SMIME Attributes

Attribute/Description

259

Type

CRYPT_CERTINFO_CMS_SECLABEL_POLICY
String
The object identifier for the security policy that the security label is issued
under.
CRYPT_CERTINFO_CMS_SECLABEL_Numeric
CLASSIFICATION
The security classification for the content identified relative to the security
policy being used. There are six standard classifications (described below)
and an extended number of user-defined classifications, for more
information see the S/MIME standards documents and X.411.
CRYPT_CERTINFO_CMS_SECLABEL_PRIVACYMARK Numeric
Apr
i
v
a
c
yma
r
kv
a
l
uet
ha
tun
l
i
k
et
hes
e
c
ur
i
t
yc
l
a
s
s
i
f
i
c
a
t
i
oni
s
n’
tus
e
df
or
access control to the message contents. See S/MIME standards documents
for more information.
CRYPT_CERTINFO_CMS_SECLABEL_CATTYPE
CRYPT_CERTINFO_CMS_SECLABEL_CATVALUE
See S/MIME standards documents.

String
Binary data

The security classification can have one of the following predefined values (which
are relative to the security policy and whose interpretation can vary from one
organisation to another), or policy-specific, user-defined values that lie outside this
range:
Value
CRYPT_CLASSIFICATION_UNMARKED
CRYPT_CLASSIFICATION_UNCLASSIFIED
CRYPT_CLASSIFICATION_RESTRICTED
CRYPT_CLASSIFICATION_CONFIDENTIAL
CRYPT_CLASSIFICATION_SECRET
CRYPT_CLASSIFICATION_TOP_SECRET

Signature Policy
This CMS attribute is used to identify the policy under which a signature was
generated, and is identified by CRYPT_CERTINFO_CMS_SIGNATUREPOLICYID. The signature policies extension allows a signer to
provide information on the policies governing a signature, and to control the way in
which a signature can be interpreted. For example it allows you to check that a
signature was issued under a policy you feel comfortable with (certain security
precautions taken, vetting of employees, physical security of the premises, and so on).
The certificate policies attribute is a complex extension that allows for all sorts of
qualifiers and additional modifiers (several of them exist only because this extension
was a cut & paste of a similar-l
ook
i
nge
x
t
e
ns
i
o
nt
ha
t
’
sus
e
dwi
t
hc
e
r
t
i
f
i
c
a
t
e
s
)
.I
n
general you should only use the policyIdentifier attribute in this extension, since the
other attributes are difficult to support in user software and are ignored by many
implementations:
Attribute/Description

Type

CRYPT_CERTINFO_CMS_SIGPOLICYID
String
The object identifier that identifies the policy under which this certificate
was issued.
CRYPT_CERTINFO_CMS_SIGPOLICYHASH
Binary data
The hash algorithm identifier and hash of the signature policy, see signature
standards documents.

260

Other Certificate Object Extensions

CRYPT_CERTINFO_CMS_SIGPOLICY_CPSURI
String
The URL for the certificate practice statement (CPS) for this signature
policy.
CRYPT_CERTINFO_CMS_SIGPOLICY_ORGANIZATION String
CRYPT_CERTINFO_CMS_SIGPOLICY_Numeric
NOTICENUMBERS
String
CRYPT_CERTINFO_CMS_SIGPOLICY_EXPLICITTEXT
These attributes contain further qualifiers, modifiers, and text information
that amend the signature policy information. Refer to signature standards
documents for more information on these attributes.

S/MIME Capabilities
This CMS attribute provides additional information about the capabilities and
preferences of the sender of a message, allowing them to indicate their preferred
encryption algorithm(s) and . The attribute is identified by CRYPT_CERTINFO_CMS_SMIMECAPABILITIES and can contains any of the following values:
Value

Description

CRYPT_CERTINFO_CMS_SMIMECAP_3DES
CRYPT_CERTINFO_CMS_SMIMECAP_AES
CRYPT_CERTINFO_CMS_SMIMECAP_CAST128
CRYPT_CERTINFO_CMS_SMIMECAP_DES
CRYPT_CERTINFO_CMS_SMIMECAP_IDEA
CRYPT_CERTINFO_CMS_SMIMECAP_RC2
CRYPT_CERTINFO_CMS_SMIMECAP_RC5
CRYPT_CERTINFO_CMS_SMIMECAP_SKIPJACK

The sender supports the use of these
algorithms. When encoding them,
cryptlib will order them by algorithm
strength so that triple DES will be
preferred over Skipjack which will be
preferred over DES.

CRYPT_CERTINFO_CMS_SMIMECAP_PREFERSIGNEDDATA

The sender would prefer to be sent
signed data.

CRYPT_CERTINFO_CMS_SMIMECAP_CANNOTDECRYPTANY

The sender can’
tha
nd
l
ea
nyf
or
mo
f
encrypted data.

To indicate that you can support messages encrypted with triple DES and Cast-128,
you would use:
cryptSetAttribute( certificate, CRYPT_CERTINFO_CMS_SMIMECAP_3DES,
CRYPT_UNUSED );
cryptSetAttribute( certificate, CRYPT_CERTINFO_CMS_SMIMECAP_CAST128,
CRYPT_UNUSED );

I
fy
ou’
r
eus
i
ngCRYPT_FORMAT_SMI
MEda
t
a
,
c
r
y
pt
l
i
bwi
l
la
u
t
o
ma
t
i
c
a
l
l
ya
d
dt
he
a
ppr
o
pr
i
a
t
ea
t
t
r
i
b
ut
e
sf
ory
ous
ot
he
r
e
’
sn
one
e
dt
os
e
tt
he
s
ea
t
t
r
i
b
ut
e
sy
our
s
e
l
f
.

Signing Certificate
This CMS attribute provides additional information about the certificate used to sign
a message, is identified by CRYPT_CERTINFO_SIGNINGCERTIFICATE, and
contains the following attributes:

OCSP Attributes

Attribute/Description

Type

CRYPT_CERTINFO_CMS_SIGNINGCERT_ESSCERTID
See S/MIME standards documents.

Binary data

261

CRYPT_CERTINFO_CMS_SIGNINGCERT_POLICIES
String
The object identifier for the policy that applies to the signing certificate.

OCSP Attributes
Like certificates, OCSP requests and responses can contain extensions that contain
additional information relating to the request or response. The ocspNonce extension
is used to prevent replay attacks on OCSP requests and is set automatically by
cryptlib. The ocspArchiveCutoff extension indicates the time limit to which an
OCSP responder will store revocation information for a certificate. The
oc
s
pRe
s
p
ons
e
Ty
p
ee
x
t
e
ns
i
o
ni
nd
i
c
a
t
e
st
h
et
y
peo
fr
e
s
p
ons
ey
ou’
dl
i
k
et
or
e
c
e
i
v
e
from a responder.
The ocspNonce extension is identified by CRYPT_CERTINFO_OCSP_NONCE and
is valid in OCSP requests and responses. The extension has a single binary data
attribute with the same identifier as the extension itself (CRYPT_CERTINFO_OCSP_NONCE)
.Si
nc
ec
r
y
pt
l
i
bs
e
t
st
hi
sv
a
l
u
ea
ut
o
ma
t
i
c
a
l
l
y
,
y
ouc
a
n
’
ts
e
ti
t
yourself:
Attribute/Description

Type

CRYPT_CERTINFO_OCSP_NONCE
Nonce to prevent replay attacks.

Binary data

The ocspArchiveCutoff extension is identified by CRYPT_CERTINFO_OCSP_ARCHIVECUTOFF and is valid in OCSP responses:
Attribute/Description

Type

CRYPT_CERTINFO_OCSP_ARCHIVECUTOFF
Time
The date beyond which revocation information will no longer be archived by
the responder.
The ocspResponseType extension is identified by CRYPT_CERTINFO_OCSP_RESPONSE and is valid in OCSP requests. This extension contains a
collection of one or more values that indicate the type of response which is being
requested from the OCSP responder. The values are:
Value

Description

CRYPT_CERTINFO_OCSP_RESPONSE_OCSP

OCSP response containing only
revocation information but no actual
certificate status.

CRYPT_CERTINFO_OCSP_RESPONSE_RTCS

RTCS response containing OK/not OK
certificate status.

CRYPT_CERTINFO_OCSP_RESPONSE_RTCS_EXTENDED

Extended RTCS response containing
certificate status and additional
information such as revocation
information.

In addition to OCSP-specific attributes, OCSP responses can also contain the CRL
attributes reasonCode, holdInstructionCode, invalidityDate, and certificateIssuer,
whi
c
ha
r
ede
s
c
r
i
be
di
n“
CRL Extensions”o
np
a
g
e245.

262

cryptlib User Interface Components

cryptlib User Interface Components
Under Win32 cryptlib provides user interface functionality via the cryptlib user
interface library cryptui.dll, which contains functions to display certificate objects
and to generate keys and obtain information needed to create or obtain a certificate.
The certificate display function takes the contents of a certificate object and displays
the various fields to the user in a standard resizeable, tabbed dialog, adjusting the
format and contents as required by the certificate object. For example a certificate
chain would be displayed as a collection of certificates, where each certificate has its
contents broken down and displayed as described above.

Displaying Certificates
To display a certificate object, you use cryptUIDisplayCert, passing in the handle of
the certificate object to display and the handle of the owner window, or NULL if the
window has no owner:
cryptUIDisplayCert( cryptCertificate, hWnd );

A certificate might look as follows when displayed by cryptUIDisplayCert:

If you set the certificate parameter for cryptUIDisplayCert to CRYPT_UNUSED, it
will allow the user to choose a certificate file to load with a standard file open dialog:
cryptUIDisplayCert( CRYPT_UNUSED, hWnd );

Key/Certificate Generation
The key generation function is a powerful operation that encompasses much of the
functionality covered in the chapters on key and certificate management, allowing the
generation of keys for the full range of public-key algorithms supported by cryptlib,
with support for the use of crypto devices such as smart cards and Fortezza cards. In

Key/Certificate Generation

263

addition this function obtains from the user all the information needed to create a
certificate or certification request ready for submission to a CA for signing.
The user interface is a standard wizard that takes the user through the steps of
choosing an algorithm, key size, password, and various identification components
needed for a certificate such as a name and email address. The general idea behind
using the wizard is:
create a certificate object to contain the certificate information;
add any fixed certificate details if required;
call the key generation wizard;
make any required changes to the certificate contents;
use the returned key to sign the certificate object;
store the key and/or certificate in a keyset using the returned
password;

One stage in the cryptUIGenerateKey key generation process might look as follows:

In the simplest case, which involves generating a key with a certificate request ready
f
ors
u
bmi
s
s
i
ont
oaCA,
y
ou’
ddot
he following:
CRYPT_CERTIFICATE cryptCertRequest;
CRYPT_CONTEXT cryptContext;
password[ CRYPT_MAX_TEXTSIZE + 1 ];
/* Generate the cert request */
cryptCreateCert( &cryptCertRequest, CRYPT_UNUSED,
CRYPT_CERTTYPE_CERTREQUEST );
/* Generate the key and fill in the cert request via the key
generation wizard */
cryptUIGenerateKey( CRYPT_UNUSED, &cryptContext, cryptCertRequest,
password, hWnd );
/* Sign the cert request */
cryptSignCert( cryptCertRequest, cryptContext );

Once the key has been generated by cryptlib it needs to be saved to a private key
k
e
y
s
e
ta
sde
s
c
r
i
be
di
n“
Certificates and Certificate Management”onp
a
g
e149. The
key can also be generated using a smart card or other crypto device, in which case the
first parameter is the handle to the device object:
cryptUIGenerateKey( cryptDevice, &cryptContext, cryptCertRequest,
password, hWnd );

Since the key is in this case generated and securely stored in the crypto device,
t
he
r
e
’
snone
e
d(
ori
n
de
e
dpossibility) to store it in a keyset.

264

cryptlib User Interface Components

The code presented so far has assumed that the user will be filling in all of the
certificate request details such as the country, location, and organisation. If you want
to use pre-set values for any of the certificate object components, you can fill these in
before calling cryptUIGenerateKey. For example to default to using the company
name Foo Corporation located in Canada with the certificate object you would use:
CRYPT_CERTIFICATE cryptCertRequest;
CRYPT_CONTEXT cryptContext;
password[ CRYPT_MAX_TEXTSIZE + 1 ];
/* Generate the cert request and fill in pre-set values */
cryptCreateCert( &cryptCertRequest, cryptUser,
CRYPT_CERTTYPE_CERTREQUEST );
cryptSetAttributeString( cryptCertRequest,
CRYPT_CERTINFO_ORGANISATIONNAME, "Foo Corporation", 15 );
cryptSetAttributeString( cryptCertRequest, CRYPT_CERTINFO_COUNTRYNAME,
"CA", 2 );
/* Generate the key and fill in the cert request via the key
generation wizard using the pre-set organisation and country name
*/
cryptUIGenerateKey( CRYPT_UNUSED, &cryptContext, cryptCertRequest,
password, hWnd );
/* Sign the cert request */
cryptSignCert( cryptCertRequest, cryptContext );

I
na
dd
i
t
i
ont
oac
e
r
t
i
f
i
c
a
t
i
onr
e
qu
e
s
ti
t
’
sp
os
s
i
b
l
et
ous
eo
t
h
e
rt
y
pe
sofc
e
r
t
i
f
i
c
a
t
e
objects like CMP or SCEP requests and standard certificates with
cryptUIGenerateKey. For example if you wanted to create a self-signed CA
certificate you would create a CRYPT_CERTTYPE_CERTIFICATE object instead
of a CRYPT_CERTTYPE_CERTREQUEST one and set the CRYPT_CERTINFO_CA attribute to true to indicate that this is a CA certificate. Once the key has been
generated and the other certificate details filled in, you can sign the certificate in the
same manner as a cert request and save the result to a cryptlib private key keyset as
de
s
c
r
i
be
di
n“
Certificates”onpa
g
e149.

Creating/Destroying Device Objects

265

Encryption Devices and Modules
c
r
y
pt
l
i
b’
ss
t
a
n
da
r
dc
r
y
pt
og
r
a
phi
cf
unc
t
i
ona
l
i
t
yi
spr
ov
i
de
dt
hr
oug
hi
t
sb
ui
l
t
-in
implementations of the required algorithms and mechanisms, however in some cases
it may be desirable to use external implementations contained in cryptographic
hardware or portable cryptographic devices like smart cards or PCMCIA cards.
Examples of external implementations are:

Cryptographic hardware accelerators

PCMCIA crypto cards such as Fortezza cards

Cryptographic smart cards

Datakeys

PKCS #11 crypto tokens

Dallas iButtons

Software encryption modules
The most common use for an external implementation is one where the hardware
provides secure key storage and management functions, or where it provides specific
algorithms or performance that may not be available in software.
Using an external implementation involves conceptually plugging in the external
hardware or software alongside the built-in capabilities provided by cryptlib and then
creating cryptlib objects (for example encryption contexts) via the device. The
external cryptographic implementation is viewed as a logical device, although the
“
de
v
i
c
e
”ma
ybej
us
ta
n
ot
he
rs
of
t
wa
r
ei
mplementation.
Note that the crypto device interface is intended for use with fairly complete crypto
modules and devices capable of performing their own key and data storage, key
management, and handling of crypto mechanisms. If all you want to do is replace
one(
ormor
e
)o
fc
r
y
pt
l
i
b
’
sbu
i
l
t
-in encryption, signing, or hash algorithms with
c
r
y
pt
oha
r
dwa
r
e
,
ana
t
i
v
ec
r
y
pt
oc
or
e
,
ory
ourowni
mp
l
e
me
nt
a
t
i
on,
y
ou
’
r
ebe
t
t
e
ro
f
f
us
i
ngt
hec
r
y
pt
opl
ug
i
nc
a
pa
b
i
l
i
t
yde
s
c
r
i
b
e
di
n“
The Crypto Plugin Interface”o
npa
g
e
300. At that level all you need to do is unplug the built-in algorithm implementation
and plug in your own replacement, which is much simpler than working with the
device-level interface.

Creating/Destroying Device Objects
Devices are accessed as device objects that work in the same general manner as other
cryptlib objects. You open a connection to a device using cryptDeviceOpen,
specifying the user who is to own the device object or CRYPT_UNUSED for the
default, normal user, the type of device you want to use and the name of the particular
de
v
i
c
ei
fr
e
q
ui
r
e
dornu
l
lo
ft
he
r
e
’
sonl
yo
ned
e
v
i
c
et
y
pep
os
s
i
b
l
e
.Thi
so
pe
nsa
c
on
ne
c
t
i
ont
ot
h
ede
v
i
c
e
.Onc
ey
ou’
v
ef
i
ni
s
h
e
dwi
t
ht
h
ed
e
v
i
c
e
,
y
ouus
e
cryptDeviceClose to sever the connection and destroy the device object:
CRYPT_DEVICE cryptDevice;
cryptDeviceOpen( &cryptDevice, cryptUser, deviceType, deviceName );
/* Use the services provided by the device */
cryptDeviceClose( cryptDevice );

The available device types are:
Device

Description

CRYPT_DEVICE_FORTEZZA

Fortezza PCMCIA card.

CRYPT_DEVICE_PKCS11

PKCS #11 crypto token. These devices
are accessed via their names, see the

266

Encryption Devices and Modules

Device

Description
section on PKCS #11 devices for more
details.

Most of the devices are identifiedi
mp
l
i
c
i
t
l
ys
ot
he
r
e
’
snon
e
e
dt
os
pe
c
i
f
yad
e
v
i
c
e
name and you can pass null as the name parameter (the exception is PKCS #11
de
v
i
c
e
s
,
whi
c
ha
r
ec
ov
e
r
e
di
nmor
ed
e
t
a
i
lf
ur
t
he
ron)
.Onc
ey
ou’
v
ef
i
n
i
s
he
dwi
t
ht
he
device, you use cryptDeviceClose to deactivate it and destroy the device object. For
example to work with a Fortezza card you would use:
CRYPT_DEVICE cryptDevice;
cryptDeviceOpen( &cryptDevice, cryptUser, CRYPT_DEVICE_FORTEZZA,
NULL );
/* Use the services provided by the device */
cryptDeviceClose( cryptDevice );

I
ft
hede
v
i
c
ec
a
n
’
tb
ea
c
c
e
s
s
e
d,
c
r
y
pt
l
i
bwi
l
lr
e
t
ur
nCRYPT_ERROR_OPENt
o
i
nd
i
c
a
t
et
ha
ti
tc
o
ul
dn
’
te
s
t
a
b
l
i
s
hac
o
nn
e
c
t
i
o
na
n
da
c
t
i
v
a
t
et
hed
e
v
i
c
e
.Not
et
ha
tt
he
CRYPT_DEVICE is passed to cryptDeviceOpen by reference, as it modifies it when
it activates the device. In all other routines in cryptlib, CRYPT_DEVICE is passed
by value.
Some devices have built-in real-time clocks, if cryptlib detects that the device has a
built-i
nc
l
oc
ki
t
’
l
lus
et
h
ede
v
i
c
ec
l
oc
kt
oo
bt
a
i
nt
het
i
mef
o
rope
rations such as
creating signed timestamps. Since device clocks can drift over time, cryptlib will
perform a consistency check of the device time against the system time and will fall
back to using the system time if the device time is too far out of step. In addition the
debug build will throw an exception if it detects a problem with the device time.

Activating and Controlling Cryptographic Devices
Once cryptlib has established a connection to the device, you may need to
authenticate yourself to it or perform some other control function with it before it will
allow itself to be used. You can do this by setting various device attributes,
specifying the type of action you want to perform on the device and any additional
information that may be required. In the case of user authentication, the additional
information will consist of a PIN or password that enables access. Many devices
recognise two types of access code, a user-level code that provides standard access
(for example for encryption or signing) and a supervisor-level code that provides
extended access to device control functions, for example key generation and loading.
An example of someone who may require supervisor-level access is a site security
officer (SSO) who can load new keys into a device or re-enable its use after a user has
been locked out.

Device Initialisation
By setting the CRYPT_DEVINFO_INITIALISE attribute, you can initialise the
device. This clears keys and other information in the device and prepares it for use.
In devices that support supervisor access you need to supply the initialisation or
initial supervisor PIN when you call this function:
cryptSetAttributeString( cryptDevice, CRYPT_DEVINFO_INITIALISE,
initialPin, initialPinLength );

Onc
ey
ou
’
v
ei
ni
t
i
a
l
i
s
e
dt
hede
v
i
c
e
,
y
oumay need to set the supervisor PIN if the
device uses a distinct initialisation PIN:
cryptSetAttributeString( cryptDevice,
CRYPT_DEVINFO_SET_AUTHENT_SUPERVISOR, supervisorPin,
supervisorPinLength );

At this point you can carry out device-specific initialisation actions while the device
i
ss
t
i
l
li
nt
hes
u
pe
r
v
i
s
ors
t
a
t
e
.Fore
x
a
mpl
ei
fy
o
u’
r
ewor
k
i
ngwi
t
haFor
t
e
z
z
ac
a
r
d,
you would load the CA root (PAA) certificate at this point, since it can only be loaded
when the card is first moved into the supervisor-initialised state. Since this is the

Activating and Controlling Cryptographic Devices

267

ultimately-trusted certificate in the card, it can only be loaded when the card is in this
state.
Onc
ey
ou
’
v
ef
i
ni
s
he
dpe
r
f
or
mi
nga
nyopt
i
o
na
lf
ur
t
he
ri
ni
t
i
a
l
i
s
a
t
i
on,
y
oune
e
dt
os
e
ta
user PIN, unless the device uses a combined user/supervisor role:
cryptSetAttributeString( cryptDevice, CRYPT_DEVINFO_SET_AUTHENT_USER,
userPin, userPinLength );

Fi
na
l
l
y
,
y
ou’
l
lne
e
dt
ol
ogona
saus
e
rwi
t
ht
hePI
Ny
ou
’
v
ej
us
ts
e
ti
ft
hed
e
v
i
c
e
doe
s
n’
td
ot
h
i
sa
ut
o
ma
t
i
c
a
l
l
ywhe
ny
oui
ni
t
ially set the PIN:
cryptSetAttributeString( cryptDevice, CRYPT_DEVINFO_AUTHENT_USER,
userPin, userPinLength );

The exact initialisation details vary from device to device and driver to driver. Some
de
v
i
c
e
sd
on
’
tdi
s
t
i
ng
ui
s
hb
e
t
we
e
ns
up
e
r
v
i
s
ora
ndus
e
rr
ol
es and so only have a single
role and PIN. Some devices require a PIN to initialise the device and then set the
supervisor PIN using a separate call, others set the supervisor PIN as part of the
initialisation call. Some devices will automatically switch over to user mode when
you set the user PIN while others require you to explicitly log on in user mode after
s
e
t
t
i
ngt
heus
e
rPI
N.Fi
na
l
l
y
,
s
omede
v
i
c
e
sc
a
n
’
tbei
n
i
t
i
a
l
i
s
e
dt
hr
oug
hPKCS#11bu
t
require proprietary vendor software to initialise them.
When the device is initialised, it usually moves through a number of states going
from uninitialised to supervisor initialised to user initialised, with strict restrictions on
what can be done in each state. For example once a supervisor has set the user PIN,
t
he
yc
a
nus
ua
l
l
ynol
o
ng
e
rc
ha
ng
ei
t
,
s
i
nc
et
hes
up
e
r
v
i
s
ori
s
n’
ts
up
pos
e
dt
obea
bl
et
o
take on the user role and manipulate the device. This is why some devices
automatically log the supervisor out once the user PIN has been set. In addition some
maintenance operations such as loading initial trusted certificates can only be
performed after the device has been initialised and is still in the initial supervisorinitialised state. Again, this prevents modification of trusted keys after the user has
been given access to the device.
A general rule of thumb is that when you go through an initialisation you have to
pe
r
f
or
ma
l
lo
ft
hes
t
e
psi
ns
e
q
ue
n
c
ewi
t
h
ou
tl
og
g
i
ngouti
nbe
t
we
e
n,
a
n
don
c
ey
ou
’
v
e
i
ni
t
i
a
l
i
s
e
dt
h
ede
v
i
c
ey
ouus
u
a
l
l
yc
a
n
’
tc
ha
ng
ea
nys
e
t
t
i
ng
swithout re-initialising it
and starting from scratch. Individual devices may diverge from this in places, but in
g
e
ne
r
a
ly
ous
hou
l
d
n’
ta
s
s
u
met
ha
ty
o
uc
a
ng
oba
c
kl
a
t
e
ra
n
dc
ha
ng
et
hi
ng
sonc
e
y
ou’
v
es
e
tt
he
m.

User Authentication
Before you can use the device you generally need to authenticate yourself to it with a
PIN or password. To authenticate yourself as supervisor, set the CRYPT_DEVINFO_AUTHENT_SUPERVISOR attribute; to authenticate yourself as user, set
the CRYPT_DEVINFO_AUTHENT_USER attribute. For example to authenticate
yourself to the device using a PIN as a normal user you would use:
cryptSetAttributeString( cryptDevice, CRYPT_DEVINFO_AUTHENT_USER, pin,
pinLength );

To authenticate yourself to the device using a PIN for supervisor-level access you
would use:
cryptSetAttributeString( cryptDevice,
CRYPT_DEVINFO_AUTHENT_SUPERVISOR, pin, pinLength );

I
ft
hePI
Norpa
s
s
wor
dt
h
a
ty
ou
’
v
es
up
pl
i
e
di
si
nc
or
r
e
c
t
,
c
r
y
pt
l
i
bwi
l
lr
e
t
ur
n
CRYPT_ERROR_WRONGKEY.I
ft
hede
v
i
c
ed
oe
s
n
’
ts
upp
or
tt
hi
st
y
peofa
c
c
e
s
s
, it
will return CRYPT_ERROR_PARAM2. Note that, as is traditional for most PIN and
password checking systems, some devices may only allow a limited number of access
attempts before locking out the user, requiring CRYPT_DEVINFO_AUTHENT_SUPERVISOR access to re-enable user access.

268

Encryption Devices and Modules

Device Zeroisation
The CRYPT_DEVINFO_ZEROISE attribute works much like CRYPT_DEVINFO_INITIALISE except that its specific goal is to clear any sensitive information such as
e
nc
r
y
pt
i
o
nk
e
y
sf
r
om t
hede
v
i
c
e(
i
t
’
sof
t
e
nt
hes
a
mea
sde
vice initialisation, but
sometimes will only specifically erase the keys and in some cases may even disable
the device). In some devices you may need to supply a zeroisation PIN or the initial
supervisor PIN when you call this function, otherwise you should set the data value to
an empty string:
cryptSetAttributeString( cryptDevice, CRYPT_DEVINFO_ZEROISE, "", 0 );

Working with Device Objects
With the device activated and the user authenticated, you can use its cryptographic
capabilities in encryption contexts as if it were a standard part of cryptlib. In order to
s
pe
c
i
f
yt
heus
eo
ft
h
ec
r
y
pt
og
r
a
phi
cde
v
i
c
er
a
t
he
rt
ha
nc
r
y
pt
l
i
b’
sbui
l
t
-in
functionality, cryptlib provides the cryptDeviceCreateContext and
cryptDeviceQueryCapability functions that are identical to cryptCreateContext
and cryptQueryCapability but take as an additional argument the handle to the
device. For example to create a standard RSA encryption context you would use:
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_RSA );

To create an RSA encryption context using an external cryptographic device you
would use:
cryptDeviceCreateContext( cryptDevice, &cryptContext,
CRYPT_ALGO_RSA );

After this you can use the encryption context as usual, both will function in an
identical manner with cryptlib keeping track of whether the implementation is via the
built-in functionality or the external device. In this way the use of any form of
external hardware for encryption is completely transparent after the initial step of
activating and initialising the hardware.
Note that, unlike the other functions that create cryptlib objects,
cryptDeviceCreateContext doe
s
n’
tr
e
qu
i
r
ey
out
os
pe
c
i
f
yt
hei
de
n
t
i
t
yo
ft
heus
e
r
who is to own the context which is being created. This is because the device is
already as
s
o
c
i
a
t
e
dwi
t
haus
e
r
,
s
ot
he
r
e
’
snon
e
e
dt
os
p
e
c
i
f
yt
hi
sa
g
a
i
nwhe
nc
r
e
a
t
i
ng
an object within it.
Fora
ne
x
a
mpl
eofh
owy
oumi
g
htut
i
l
i
s
ee
x
t
e
r
na
lha
r
dwa
r
e
,
l
e
t
’
sus
eag
e
ne
r
i
c
DES/
t
r
i
pl
eDESha
r
dwa
r
ea
c
c
e
l
e
r
a
t
or(
i
de
nt
i
f
i
e
dbyt
hel
a
b
e
l“
DES/
3DES
accelera
t
or
”
)a
c
c
e
s
s
e
da
saPKS#11de
v
i
c
e
.Tous
et
h
et
r
i
pl
eDESha
r
dwa
r
ei
ns
t
e
a
d
ofc
r
y
pt
l
i
b’
sb
ui
l
t
-in triple DES implementation you would use:
CRYPT_DEVICE cryptDevice;
CRYPT_CONTEXT cryptContext;
/* Activate the DES hardware and create a context in it */
cryptDeviceOpen( &cryptDevice, cryptUser, CRYPT_DEVICE_PKCS11,
"DES/3DES accelerator" );
cryptDeviceCreateContext( cryptDevice, &cryptContext,
CRYPT_ALGO_3DES );
/* Generate a key in the DES hardware */
cryptGenerateKey( cryptContext );
/* Encrypt data using the hardware */
cryptEncrypt( cryptContext, data, dataLength );
/* Destroy the context and shut down the DES hardware */
cryptDestroyContext( cryptContext );
cryptDeviceClose( cryptDevice );

After the context has been created with cryptDeviceCreateContext, the use of the
context is identical to a standard encryption context. There is no other (perceptual)
difference between the use of a built-in implementation and an external
implementation.

Working with Device Objects

269

Key Storage in Crypto Devices
When you create a normal public-key context and load or generate a key into it, the
context goes away when you destroy it or shut down cryptlib. If the context is
c
r
e
a
t
e
di
nac
r
y
pt
ode
v
i
c
e
,
t
h
epub
l
i
ca
ndpr
i
v
a
t
ek
e
y
sf
r
o
mt
hec
on
t
e
x
tdo
n
’
tg
oa
wa
y
when the context is destroyed but are stored inside the device for later use. You can
later recreate the context using the key stored in the device by treating the device as a
keyset containing a stored key. For example to create an RSA key in a device you
would use:
CRYPT_CONTEXT privKeyContext;
/* Create the RSA context, set a label for the key, and generate a key
into it */
cryptCreateContext( &privKeyContext, cryptUser, CRYPT_ALGO_RSA );
cryptSetAttributeString( privKeyContext, CRYPT_CTXINFO_LABEL, label,
labelLength );
cryptGenerateKey( privKeyContext );
/* Destroy the context */
cryptDestroyContext( privKeyContext );

Although the context has been destroyed, the key itself is still held inside the device.
To recreate the context at a later date, you can treat the device as if it were a keyset,
using the label as the key ID:
CRYPT_CONTEXT privKeyContext;
cryptGetPrivateKey( cryptDevice, &privKeyContext, CRYPT_KEYID_NAME,
label, NULL );

Si
nc
ey
ou
’
v
ea
l
r
e
a
dya
ut
he
nt
i
c
a
t
e
dy
our
s
e
l
ft
ot
hede
v
i
c
e
,
y
oud
on
’
tne
e
dt
os
p
e
c
i
f
ya
password.
Key storage is crypto devices has additional special considerations that are covered in
“
Considerations when Working with Devices”o
npa
g
e270. The most notable of
t
he
s
ei
st
ha
tma
nyde
v
i
c
e
sdo
n’
ta
l
l
owdirect key loads into devices, and virtually all
don
’
ta
l
l
owt
he
mt
obee
x
t
r
a
c
t
e
d,
s
ot
h
a
tt
hek
e
yha
st
ob
eg
e
ne
r
a
t
e
di
ns
i
det
hede
v
i
c
e
(
a
st
hee
x
a
mpl
ec
o
deg
i
v
e
ne
a
r
l
i
e
rs
hows
)a
ndc
a
n
’
tl
e
a
v
et
hede
v
i
c
ee
x
c
e
p
t(
f
or
conventional encryption keys) in encrypted form.

Querying Device Information
Crypto devices come in a wide range of configurations and with varying capabilities,
which can include facilities that bypass the normal device-handling operations
described here. For example a device may have a built-in keypad or other
authentication mechanism that bypasses the need to provide a PIN or password from
s
of
t
wa
r
e
.I
nt
h
i
sc
a
s
ei
t
’
snotne
c
e
s
s
a
r
yt
ol
ogi
nt
ot
h
ede
v
i
c
ebe
c
a
us
et
hel
og
i
n
process is handled via an external mechanism. You can determine whether a device
i
sa
l
r
e
a
dyl
og
g
e
di
n,
ordoe
s
n
’
tr
e
q
ui
r
eal
og
i
n,
byr
e
a
di
ngt
heCRYPT_DEVI
NFO_LOGGEDIN attribute. If this is set to true (any nonzero value) then the device is
already logged in, otherwise you need to provide a PIN or password to log in to the
device:
int deviceLoggedIn;
/* Check whether we're logged in to the device and if not, log in */
cryptGetAttribute( cryptDevice, CRYPT_DEVINFO_LOGGEDIN,
&deviceLoggedIn );
if( !deviceLoggedIn )
/* Get PIN from user and log in */;

Since some devices re
pr
e
s
e
n
tr
e
mov
a
bl
et
ok
e
nss
u
c
ha
ss
ma
r
tc
a
r
ds
,
i
t
’
spos
s
i
b
l
ef
or
the user to unplug one token and plug in a new one in its place. To help you
determine which token was plugged in at the time it was accessed with
cryptDeviceOpen,
y
ouc
a
nr
e
a
dt
hede
v
i
c
e
’
sCRYPT_DEVINFO_LABEL attribute,
which returns the label or name of the token which is accessible via the device:

270

Encryption Devices and Modules

char label[ CRYPT_MAX_TEXTSIZE ];
int labelLength;
cryptGetAttributeString( cryptDevice, CRYPT_DEVINFO_LABEL, label,
&labelLength );
label[ labelLength ] = '\0';

Onc
ey
ou
’
v
er
e
a
dt
hel
a
be
ly
o
uc
a
nus
ei
tt
ode
t
e
r
mi
newhe
t
he
rt
her
e
qui
r
e
dc
r
y
pt
o
token is available via the device.
Somer
e
a
de
r
sa
n
dde
v
i
c
ei
n
t
e
r
f
a
c
e
sa
r
e
n’
tv
e
r
yg
ooda
tde
t
e
c
t
i
ngt
her
e
mov
a
lofa
crypto token, or the removal of a token and insertion of a new one. For example,
ma
nys
ma
r
tc
a
r
dr
e
a
de
r
so
nl
yha
v
eas
i
mpl
es
e
ns
ort
ode
t
e
c
twhe
t
h
e
rt
he
r
e
’
s
s
ome
t
h
i
ngpr
e
s
e
nti
nt
h
er
e
a
d
e
r
,
butc
a
n’
tt
e
l
lwhe
t
he
rwha
t
’
spr
e
s
e
nti
st
heor
i
g
i
na
l
smart card or a piece of cardboard. In addition some low-l
e
v
e
lr
e
a
de
rdr
i
v
e
r
sc
a
n
’
t
report the presence (or absence) of a card to the higher-level code. cryptlib will try to
c
on
t
a
c
tt
hec
r
y
pt
ot
ok
e
nt
oc
h
e
c
kwhe
t
he
ri
t
’
ss
t
i
l
lpr
e
s
e
n
ta
nda
c
t
i
v
e
,
bu
tc
a
non
l
yg
o
as far as the underlying hardware and software will let it.

Considerations when Working with Devices
There are several considerations to be taken into account when using crypto devices,
the major one being that requiring that crypto hardware be present in a system
automatically limits the flexibility of your application. There are some cases where
the use of certain types of hardware (for example Fortezza cards) may be required,
but in many instances the reliance on specialised hardware can be a drawback.
The use of crypto devices can also complicate key management, since keys generated
orl
oa
de
di
nt
ot
hede
v
i
c
eus
u
a
l
l
yc
a
n
’
tb
ee
x
t
r
a
c
t
e
da
g
a
i
na
f
t
e
r
wa
r
ds
.Thi
si
sa
security feature that makes external access to the key impossible, and works in the
s
a
mewa
ya
sc
r
y
pt
l
i
b’
sowns
t
or
i
ngofk
e
y
si
ns
i
dei
t
’
ss
e
c
ur
i
t
ype
r
i
me
t
e
r
.Thi
sme
a
ns
that if you have a crypto device that supports (say) DES and RSA encryption, then to
export an encrypted DES key from a context stored in the device, you need to use an
RSA context also stored inside the device, since a context located outside the device
won’
tha
v
ea
c
c
e
s
st
ot
heDESc
ont
e
x
t
’
sk
e
y
.
Another consideration that needs to be taken into account is the data processing speed
oft
hed
e
v
i
c
e
.I
nmos
tc
a
s
e
si
t
’
spr
e
f
e
r
a
bl
et
ous
ec
r
y
pt
l
i
b’
sbui
l
t
-in implementation
of an algorithm rather than the one provided by the device because the built-in
implementation will be much faster. For example when hashing data prior to signing
i
t
,
c
r
y
pt
l
i
b
’
sbu
i
l
t
-in hashing capabilities should be used in preference to any provided
by the device, since cryptlib can process data at the full memory bandwidth using a
processor clocked at several gigahertz while a crypto device has to move data over a
slow I/O bus to be processed by a processor typically clocked at tens of megahertz or
e
v
e
naf
e
wme
g
a
he
r
t
z
.I
na
dd
i
t
i
onwhe
ne
n
c
r
y
pt
i
ngorde
c
r
y
pt
i
ngda
t
ai
t
’
sg
e
ne
r
a
l
l
y
pr
e
f
e
r
a
bl
et
ous
ec
r
y
pt
l
i
b
’
shi
g
h-speed encryption capabilities, particularly with
devices such as smart cards and to a lesser extent PCMCIA cards, which are severely
limited by their slow I/O throughput. As a general rule of thumb, if your system
pr
oc
e
s
s
ori
sr
unn
i
nga
t500MHzorhi
g
he
rt
he
ni
t
’
sa
l
wa
y
sf
a
s
t
e
rt
ope
r
f
or
mt
h
e
c
r
y
pt
oi
ns
of
t
wa
r
er
a
t
he
rt
ha
nus
i
ngc
r
y
pt
oha
r
dwa
r
e
.Be
c
a
us
eo
ft
h
i
si
t
’
sus
u
a
lt
o
only perform private-key operations in the crypto device.
A final consideration concerns the limitations of the encryption engine in the device
itself. Although cryptlib provides a great deal of flexibility in its software crypto
implementations, most hardware devices have only a single encryption engine
through which all data must pass (possibly augmented by the ability to store multiple
encryption keys in the device). What this means is that each time a different key is
us
e
d,
i
tha
st
obel
oa
d
e
di
nt
ot
hede
v
i
c
e
’
se
ncryption engine before it can be used to
encrypt or decrypt data, a potentially time-consuming process. For example if two
encryption contexts are created via a device and both are used alternately to encrypt
data, the key corresponding to each context has to be loaded by the device into its
encryption engine before the encryption can begin (while most devices can store
multiple keys, few can keep more than one at a time ready for use in their encryption
engine).

Fortezza Cards

271

As a result of this, although cryptlib will allow you to create as many contexts via a
de
v
i
c
ea
st
heh
a
r
dwa
r
ea
l
l
ows
,
i
t
’
sg
e
ne
r
a
l
l
yno
tag
oodi
de
at
oha
v
emor
et
ha
na
single context of each type in use at any one time. For example you could have a
single conventional encryption context (using thede
v
i
c
e
’
sc
r
y
pt
oe
ng
i
ne
)
,
as
i
ng
l
e
di
g
i
t
a
ls
i
g
na
t
ur
ec
ont
e
x
t(
us
i
n
gt
hede
v
i
c
e
’
sp
ub
l
i
c
-key engine), and a single hash
c
on
t
e
x
t(
us
i
ngt
hede
v
i
c
e
’
sCPUorha
s
he
ng
i
ne
,
orpr
e
f
e
r
a
bl
yc
r
y
pt
l
i
bi
t
s
e
l
f
)a
c
t
i
v
e
,
but not two conventional encryption contexts (which would have to share the
encryption engine) or two digital signature contexts (which would have to share the
public-key engine).

Fortezza Cards
cryptlib provides complete Fortezza card management capabilities, allowing you to
initialise and program a card, generate or load keys into it, add certificates for the
generated/loaded keys, update and change PINs, and perform other management
functions. This provides full certificate authority workstation (CAW) capabilities.
The steps involved in programming a bl
a
nkFor
t
e
z
z
ac
a
r
da
r
eg
i
v
e
ni
n“
Activating
and Controlling Cryptographic Devices”onpa
g
e266. Once the card is in the SSO
i
ni
t
i
a
l
i
s
e
ds
t
a
t
e(
a
f
t
e
ry
ou’
v
es
e
tt
heSSOPI
N)
,
y
ous
houl
di
ns
t
a
l
lt
heCAroot (PAA)
certificate in the card, since this operation is only permitted in the SSO initialised
s
t
a
t
e
.Theus
eo
fPAAc
e
r
t
i
f
i
c
a
t
e
si
ss
o
me
wha
ts
p
e
c
i
f
i
ct
ot
heus
eo
fFor
t
e
z
z
a
’
sby
the US Government, you may want to simply load a dummy certificate at this point
a
ndus
es
t
a
nda
r
dCAc
e
r
t
i
f
i
c
a
t
e
swi
t
ha
nyk
e
y
st
ha
ty
ou’
l
lbes
t
or
i
ngont
hec
a
r
d.
Note that the Fortezza control firmware requires that all of the steps in the
initialisation/programming process be performed in a continuous sequence of
operations, without removing the card or closing the device. If you interrupt the
pr
oc
e
s
sh
a
l
f
wa
yt
hr
oug
h,
y
ou’
l
lne
e
dt
os
t
a
r
ta
g
a
i
n.
After the above programming process has completed, you can generate further keys
into the device, load certificates, and so on. This provides the same functionality as a
Fortezza CAW.

PKCS #11 Devices
Although most of the devices that cryptlib interfaces with have specialised, singlepurpose interfaces, PKCS #11 provides a general-purpose interface that can be used
with a wide selection of parameters and in a variety of ways. The following section
covers the installation of PKCS #11 modules and documents the way in which
cryptlib interfaces to PKCS #11 modules.

Installing New PKCS #11 Modules
You can install new PKCS #11 modules by setting the names of the drivers in
c
r
y
pt
l
i
b’
sc
on
f
i
g
ur
a
t
i
ond
a
t
a
b
a
s
e
.Themod
ul
ena
me
sa
r
es
pe
c
i
f
i
e
dus
i
ngt
he
configuration options CRYPT_OPTION_DEVICE_PKCS11_DVR01 ...
CRYPT_OPTION_DEVICE_PKCS11_DVR05, cryptlib will step through the list and
load each mod
ul
ei
nt
ur
n.Onc
ey
ou’
v
es
p
e
c
i
f
i
e
dt
hemo
du
l
ena
me
,
y
oune
e
dt
o
c
o
mmi
tt
hec
ha
ng
e
si
nor
de
rf
orc
r
y
pt
l
i
bt
ous
et
h
e
mt
hene
x
tt
i
mei
t
’
sl
o
a
de
d.For
example to use the Gemplus GemSAFE driver, you would use:
cryptSetAttributeString( CRYPT_UNUSED,
CRYPT_OPTION_DEVICE_PKCS11_DVR01, "w32pk2ig.dll", 12 );
cryptSetAttribute( CRYPT_UNUSED, CRYPT_OPTION_CONFIGCHANGED, FALSE );

The first line of code updates the configuration information to point to the PKCS #11
driver DLL, and the second line makes the changes permanent by flushing the
configuration information to disk.
Since the drivers are dynamically loaded on start-up by cryptlib, specifying a driver
a
sac
on
f
i
g
ur
a
t
i
ono
pt
i
o
nwon
’
ti
mme
di
a
t
e
l
yma
k
ei
ta
v
a
i
l
a
bl
ef
orus
e
.Toma
k
et
h
e
driver available, you have to restart cryptlib or the application using it so that cryptlib
can load the driver on start-up, whereupon cryptlib will load the specified modules
and make them available as CRYPT_DEVICE_PKCS11 devices. When the module

272

Encryption Devices and Modules

is loaded, cryptlib will query each module for the device name, this is the name that
you should use to access it using cryptDeviceOpen.
Somede
v
i
c
e
sdo
n’
ti
mpl
e
me
nta
l
lo
ft
h
e
i
rc
r
y
pt
of
u
nc
t
i
o
na
l
i
t
yi
nt
hed
e
v
i
c
eb
ut
instead emulate it in software on the host PC. If you have a PKCS #11 module that
doe
st
he
ni
t
’
sbe
t
t
e
rt
ous
ec
r
y
pt
l
i
b
’
sna
t
i
v
ec
r
y
pt
oc
a
p
a
bi
l
i
t
i
e
sbe
c
a
us
et
he
y
’
l
lbe
more efficient than those in the driver and possibly more secure as well, depending on
how carefully the driver has been written. In order to use only the real device
capabilities (rather than those emulated on the host PC), you can set the configuration
option CRYPT_OPTION_DEVICE_PKCS11_HARDWAREONLY to true (any
non
z
e
r
ov
a
l
ue
)a
se
x
pl
a
i
ne
di
n“
Working with Configuration Options”o
npage 274.
If this option is set, cryptlib will only use capabilities that are provided by the crypto
token any not any that are emulated in software.

Accessing PKCS #11 Devices
PKCS #11 devices are identified by the device name, for example the Litronix PKCS
#11dr
i
v
e
ri
de
nt
i
f
i
e
si
t
s
e
l
fa
s“
Li
t
r
oni
xCr
y
pt
Ok
iI
nt
e
r
f
a
c
e
”s
oy
ouwoul
dc
r
e
a
t
ea
device object of this type with:
CRYPT_DEVICE cryptDevice;
cryptDeviceOpen( &cryptDevice, cryptUser, CRYPT_DEVICE_PKCS11,
"Litronix CryptOki Interface" );

I
fy
oudo
n
’
tk
nowt
h
ede
v
i
c
ena
meort
he
r
e
’
sonl
yo
ned
e
v
i
c
epr
e
s
e
n
t
,
y
ouc
a
nus
et
he
special device name [Autodetect] to have cryptlib auto-detect the device for you.
I
ft
he
r
e
’
smor
et
ha
nonede
v
i
c
epr
e
s
e
n
t
,
c
r
y
pt
l
i
bwi
l
lus
et
h
ef
i
r
s
t one it finds:
CRYPT_DEVICE cryptDevice;
cryptDeviceOpen( &cryptDevice, cryptUser, CRYPT_DEVICE_PKCS11,
"[Autodetect]" );

Some PKCS #11 devices allow the use of multiple physical or logical crypto tokens
as part of a single device, for example a smart card reader device might have two
slots that can each contain a smart card, or the reader itself might function as a crypto
token alongside the smart card which is inserted into it. To identify a particular token
in a device, you can specify its name after the device name, separated with a double
colon. For example if the Litronix reader given in the example above contained two
s
ma
r
tc
a
r
ds
,
y
ouwoul
da
c
c
e
s
st
heo
nec
a
l
l
e
d“
Si
g
ni
ngs
ma
r
tc
a
r
d”wi
t
h
:
CRYPT_DEVICE cryptDevice;
cryptDeviceOpen( &cryptDevice, cryptUser, CRYPT_DEVICE_PKCS11,
"Litronix CryptOki Interface::Signing smart card " );

Some PKCS #11 devices and drivers have special-case requirements that need to be
taken into account when you use them. For example some removeable tokens may
require speci
a
lh
a
n
dl
i
ngf
ort
ok
e
nc
h
a
ng
e
si
ft
her
e
a
de
rd
o
e
s
n’
ts
up
por
ta
ut
o
ma
t
i
c
insertion detection, some drivers may have problems if the application forks (under
Unix), and so on. You should consult the vendor documentation for the crypto device
and drivers that y
o
u’
l
lb
eus
i
n
gt
oc
he
c
kf
ora
nys
pe
c
i
a
lr
e
q
ui
r
e
me
nt
st
h
a
ty
oune
e
dt
o
meet when you use the device.

CryptoAPI
The following section is intended for forwards-compatibility with future versions of
cryptlib. Although some portions of this interface may be implemented, they should
not be relied upon in applications.
The CryptoAPI interface provides access to the encryption, signature, and hashing
capabilities of the underlying CryptoAPI implementation. All of these facilities are
already provided by cryptlib,
s
oi
t
’
spr
i
ma
r
ypur
p
os
ei
st
op
r
ov
i
dea
c
c
e
s
st
oPKCS
#12
/
PFXpr
i
v
a
t
ek
e
y
sa
ndc
e
r
t
i
f
i
c
a
t
e
she
l
di
nWi
n
dows
’i
n
t
e
r
na
l(
pr
o
pr
i
e
t
a
r
y
)k
e
y
store, and by extension keys imported to it from other applications. Using the
CryptoAPI interface provides full access to all keys generated by and stored inside

CryptoAPI

273

Windows, while still allowing the use of all standard cryptlib functionality and
facilities.
Since CryptoAPI is a software implementation managed entirely by the host
operating system, there is no need to perform any initialisation, user authentication, or
other operations like zeroisation, when using a CryptoAPI device. Initialisation was
performed when the operating system was installed, and authentication is performed
when the user logs in or the dæmon or service that uses the keys is activated. This
means that using the CryptoAPI device consists of no more than creating the device
object and then utilising it in subsequent crypto operations. All keys and certificates
that are accessed through the device will be ones stored in CryptoAPI, giving cryptlib
f
u
l
la
c
c
e
s
st
ot
heh
os
to
pe
r
a
t
i
ngs
y
s
t
e
m’
sk
e
y
sa
ndc
r
y
pt
oc
a
pa
bi
l
i
t
i
e
s
.

274

Miscellaneous Topics

Miscellaneous Topics
This chapter covers various miscellaneous topics not covered in other chapters such
as how to obtain information about the encryption capabilities provided by cryptlib,
how to obtain information about a particular encryption context, and how to ensure
that your code takes advantage of new encryption capabilities provided with future
versions of cryptlib.

Querying crypt
l
i
b’
sCapabi
l
i
t
i
es
cryptlib provides two functions to query encryption capabilities, one of which returns
information about a given algorithm and mode and the other which returns
information on the algorithm and mode used in an encryption context. In both cases
the information returned is in the form of a CRYPT_QUERY_INFO structure, which
i
sde
s
c
r
i
be
di
n“
CRYPT_QUERY_INFO Structure”onpa
g
e314.
You can interrogate cryptlib about the details of a particular encryption algorithm and
mode using cryptQueryCapability:
CRYPT_QUERY_INFO cryptQueryInfo;
cryptQueryCapability( algorithm, &cryptQueryInfo );

If you just want to check whether a particular algorithm is available (without
obtaining further information on them), you can set the query information parameter
to null:
cryptQueryCapability( algorithm, NULL );

This will simply return a status value without trying to return algorithm information.

Working with Configuration Options
In order to allow extensive control over its security and operational parameters,
cryptlib provides a configuration database that can be used to tune its operation for
different environments using portable configuration files that function similarly to
Unix .rc files. This allows cryptlib to be customised on a per-user basis (for example
it can remember which key the user usually uses to sign messages and offer to use
this key by default), allows a system administrator or manager to set a consistent
security policy (for example mandating the use of 1024-or 2048 bit public keys on a
company-wide basis instead of unsafe 512-bit keys), and provides information on the
use of optional features such as smart card readers, encryption hardware, and
cryptographically strong random number generators. The configuration options that
affect encryption parameter settings are automatically applied by cryptlib to
operations such as key generation and data encryption and signing.
The configuration database can be used to tune the way cryptlib works, with options
ranging from algorithms and key sizes through to preferred public/private keys to use
for signing and encryption and what to do when certain unusual conditions are
encountered. The available options are listed below, with the data type associated
with each value being either a boolean (B), numeric (N), or string (S) value:
Value
CRYPT_OPTION_CERT_SIGNUNRECOGNISEDATTRIBUTES

Type Description
B

Whether to sign a certificate
containing unrecognised
attributes. If this option is set to
false, the attributes will be omitted
from the certificate when it is
signed. Default = false.

Working with Configuration Options

Value
CRYPT_OPTION_CERT_COMPLIANCELEVEL

Type Description
N The amount of checking for
standards-compliance to apply to
certificates, certificate requests,
and other certificate objects.
Default = CRYPT_COMPLIANCELEVEL_STANDARD,

CRYPT_OPTION_CERT_REQUIREPOLICY

Whether to require matching
certificate policies for certificates
in a cert chain once a CA sets a
policy. Default = true.

CRYPT_OPTION_CERT_UPDATEINTERVAL

The update interval in days for
CRLs. Default = 90.

CRYPT_OPTION_CERT_VALIDITY

The validity period in days for
certificates. Default = 365.

CRYPT_OPTION_CMS_DEFAULTATTRIBUTES
CRYPT_OPTION_SMIME_DEFAULTATTRIBUTES

Whether to add the default CMS /
S/MIME attributes to signatures
(these are alternative names for
the same option, since S/MIME
uses CMS as the underlying
format). Default = true.

CRYPT_OPTION_CONFIGCHANGED

Whether any configuration
options have been changed from
their original settings (see note
below).

CRYPT_OPTION_DEVICE_PKCS11_DVR01
...
CRYPT_OPTION_DEVICE_PKCS11_DVR05

The module names of any PKCS
#11 drivers that cryptlib should
load on start-up.

CRYPT_OPTION_DEVICE_PKCS11_HARDWAREONLY

Whether cryptlib should use only
the hardware capabilities of the
device and not capabilities
emulated in software on the host
PC by the PKCS #11 driver.
Default = false.

CRYPT_OPTION_ENCR_ALGO

Encryption algorithm given as a
conventional-encryption
CRYPT_ALGO_TYPE. Default
= CRYPT_ALGO_3DES.

CRYPT_OPTION_ENCR_HASH

Hash algorithm given as a hash
CRYPT_ALGO_TYPE. Default
= CRYPT_ALGO_SHA.

CRYPT_OPTION_ENCR_HASH

MAC algorithm given as a MAC
CRYPT_ALGO_TYPE. Default
= CRYPT_ALGO_HMAC_SHA.

CRYPT_OPTION_INFO_COPYRIGHT

cryptlib copyright notice.

275

276

Miscellaneous Topics

Value
CRYPT_OPTION_INFO_DESCRIPTION

Type Description
S cryptlib description.

CRYPT_OPTION_INFO_MAJORVERSION
CRYPT_OPTION_INFO_MINORVERSION
CRYPT_OPTION_INFO_STEPPING

cryptlib major and minor version
numbers and stepping number.

CRYPT_OPTION_KEYING_ALGO

Key processing algorithm given as
a hash CRYPT_ALGO_TYPE.
Default = CRYPT_ALGO_SHA.

CRYPT_OPTION_KEYING_ITERATIONS

Number of times to iterate the
key-processing algorithm. Note
that key processing when used for
private-key encryption uses a
much higher value than this
general-purpose value. Default =
500.

CRYPT_OPTION_KEYS_LDAP_CACERTNAME
CRYPT_OPTION_KEYS_LDAP_CERTNAME
CRYPT_OPTION_KEYS_LDAP_CRLNAME
CRYPT_OPTION_KEYS_LDAP_EMAILNAME
CRYPT_OPTION_KEYS_LDAP_FILTER
CRYPT_OPTION_KEYS_LDAP_OBJECTCLASS

The names of various LDAP
attributes and object classes used
for certificate storage/retrieval.

CRYPT_OPTION_MISC_ASYNCINIT

Whether to bind in various drivers
asynchronously when cryptlib is
initialised. This performs the
initialisation in a background
thread rather than blocking on
start-up until the initialisation has
completed. Default = true.

CRYPT_OPTION_MISC_SIDECHANNELPROTECTION

Whether to perform additional
operations that add protection
against some obscure (and rather
unlikely) side-channel attacks on
private keys. Enabling this option
will slow down all private-key
operations by up to 10%. Default
= false.

CRYPT_OPTION_NET_HTTP_PROXY

HTTP proxy used for accessing
web pages. Default = none.

CRYPT_OPTION_NET_SOCKS_SERVER
CRYPT_OPTION_NET_SOCKS_USERNAME

Socks server and user name used
for Internet access. Default =
none.

Working with Configuration Options

Value
CRYPT_OPTION_NET_CONNECTTIMEOUT
CRYPT_OPTION_NET_READTIMEOUT
CRYPT_OPTION_NET_WRITETIMEOUT

277

Type Description
N Timeout in seconds when
connecting to a remote server and
when transferring data after a
connection has been established.
Default = 30 seconds for the
connect timeout, 0 seconds for the
read timeout, 2 seconds for the
write timeout.

CRYPT_OPTION_PKC_ALGO

Public-key encryption algorithm
given as a public-key
CRYPT_ALGO_TYPE. Default
= CRYPT_ALGO_RSA.

CRYPT_OPTION_PKC_KEYSIZE

Public-key encryption key size in
bytes. Default = 128 (1024 bits).

CRYPT_OPTION_SELFTESTOK

The current algorithm self-test
status (see note below).

CRYPT_OPTION_SIG_ALGO

Signature algorithm given as a
public-key encryption
CRYPT_ALGO_TYPE. Default
= CRYPT_ALGO_RSA.

CRYPT_OPTION_SIG_KEYSIZE

Signature key size in bytes.
Default = 128 (1024 bits).

CRYPT_OPTION_CONFIGCHANGED has special significance in that it contains
the current state of the configuration options. If this value is FALSE, the current inmemory configuration options are still set to the same value that they had when
cryptlib was started. If set to TRUE, one or more options have been changed and
they no longer match the values saved in permanent storage such as a hard disk or
flash memory. Writing this value back to FALSE forces the current in-memory
values to be committed to permanent storage so that the two match up again.
CRYPT_OPTION_SELFTEST also has special significanc
e
,
c
ont
r
ol
l
i
ngc
r
y
pt
l
i
b
’
s
built-in self-test functionality. If you want to perform a self-test of any cryptlib
algorithm, you can set this attribute to the algorithm that you want to test. If the selftest succeeds, cryptlib will return an OK status, othe
r
wi
s
ei
t
’
l
lr
e
t
ur
naf
a
i
l
ur
ee
r
r
or
code. For example to perform the internal self-t
e
s
to
ft
heDSAi
mpl
e
me
nt
a
t
i
ony
ou
’
d
use:
cryptSetAttribute( cryptEnvelope, CRYPT_OPTION_SELFTESTOK,
CRYPT_ALGO_DSA );

To test all of the implementations, you can set the attribute to CRYPT_USE_DEFAULT. If one (or more) of the algorithm self-tests fails, you can use the peralgorithm test to determine which algorithm(s) failed the self-test.
In addition to these manually-triggered self-tests, cryptlib automatically tests its builtin SHA-1 and DES/3DES implementation and random number generator every time
i
ts
t
a
r
t
s
,
a
n
dwon
’
ts
t
a
r
ti
ft
he
r
e
’
sapr
o
bl
e
m wi
t
ha
nyo
ft
h
e
m.

Querying/Setting Configuration Options
You can manipulate the configuration options by getting or setting the appropriate
attribute values. Since these apply to all of cryptlib rather than to any specific object,
you should set the object handle to CRYPT_UNUSED. For example to query the
current default encryption algorithm you would use:
CRYPT_ALGO_TYPE cryptAlgo;
cryptGetAttribute( CRYPT_UNUSED, CRYPT_OPTION_ENCR_ALGO, &cryptAlgo );

278

Miscellaneous Topics

To set the default encryption algorithm to CAST-128, you would use:
cryptSetAttribute( CRYPT_UNUSED, CRYPT_OPTION_ENCR_ALGO,
CRYPT_ALGO_CAST );

Some configuration options which contain values that apply to individual objects can
also be set for that one object type rather than as a global setting. These options
include timeouts for session objects, key size and key setup parameters for encryption
contexts, and encryption and hash algorithms for envelopes. For example to set the
encryption algorithm to be used when enveloping data in one particular envelope to
IDEA, you would use:
cryptSetAttribute( cryptEnvelope, CRYPT_OPTION_ENCR_ALGO,
CRYPT_ALGO_IDEA );

A few of the options are used internally by cryptlib and are read-only (this is
i
nd
i
c
a
t
e
di
nt
heo
pt
i
o
ns
’d
e
s
c
r
i
pt
i
on)
.The
s
ewi
l
lr
e
t
ur
nCRYPT_ERROR_PERMI
SSI
ONi
fy
out
r
yt
omodi
f
yt
he
mt
oi
nd
i
c
a
t
et
h
a
ty
o
udo
n’
tha
v
ep
e
r
mi
s
s
i
o
nt
o
change this option.

Saving Configuration Options
The changes you make to the configuration options only last while your program is
running or while cryptlib is loaded. In order to make the changes permanent, you can
save them to a permanent storage medium such as a hard disk by setting the
CRYPT_OPTION_CONFIGCHANGED option to FALSE, indicating that the inmemory settings will be synced to disk so that the two match up. cryptlib will
automatically reload the saved options when it starts.
The location of the saved configuration options depend on the system type on which
cryptlib is running:
System

Location

BeOS
Unix

$(HOME)/.cryptlib/cryptlib.p15

DOS
OS/2

./cryptlib.p15

MVS
VM/CMS

CRYPTLIB P15

Tandem

$system.system.cryptlib

Windows 3.x

Windows/cryptlib/cryptlib.p15

Windows 95/98/ME
Windows NT/2000/XP
Windows CE

\Documents and Settings\user_name\Application
Data\cryptlib\cryptlib.p15 or \Windows\All
Users\Application Data\cryptlib\cryptlib.p15 or
\Windows\Profiles\user_name\Application
Data\cryptlib.p15 (this varies depending on the OS type
and version, and is determined by the Windows
application data CSIDL)

Where the operating system supports it, cryptlib will set the security options on the
configuration information so that only the person who created it (and, usually, the
system administrator) can access it. For example under Unix the file access bits are
set to allow only the file owner (and, by extension, the superuser) to access the file,
and under Windows NT/2000/XP with NTFS the file ACLs are set so that only the
user who owns it can access or change it.

Obtaining Information About Cryptlib
cryptlib provides a number of read-only configuration options that you can use to
obt
a
i
ni
n
f
or
ma
t
i
o
na
bo
utt
hev
e
r
s
i
ono
fc
r
y
pt
l
i
bt
ha
ty
o
u’
r
ewor
k
i
ngwi
t
h.
These options are:

Random Numbers

Value

279

Type Description

CRYPT_OPTION_INFO_MAJORVERSION
CRYPT_OPTION_INFO_MINORVERSION
CRYPT_OPTION_INFO_STEPPING

The cryptlib major and minor
version numbers and release
stepping. For cryptlib 3.1 the
major version number is 3 and the
minor version number is 1. For
beta release 2 the stepping is 2.

CRYPT_OPTION_INFO_DESCRIPTION

A text string containing a
description of cryptlib.

CRYPT_OPTION_INFO_COPYRIGHT

The cryptlib copyright notice.

Random Numbers
Several cryptlib functions require access to a source of cryptographically strong
random numbers. The random-data-gathering operation is controlled with the
cryptAddRandom function, which can be used to either inject your own random
information into the internal randomness pool or to tell cryptlib to poll the system for
random information. To add your own random data (such as keystroke timings when
the user enters a password) to the pool, use:
cryptAddRandom( buffer, bufferLength );

In addition to user-supplied and built-in randomness sources, cryptlib will check for a
/dev/random, EGD, or PRNGD-style style randomness driver (which continually
accumulates random data from the system) and will use this as a source of
randomness. If running on a system with a hardware random number source
(provided by some CPUs and chipsets), cryptlib will also make use of the hardware
random number source. cryptlib can also make use of additional entropy seeding
i
n
f
or
ma
t
i
o
none
mbe
dde
ds
y
s
t
e
mswi
t
h
outi
n
he
r
e
n
te
n
t
r
opys
our
c
e
s
,
s
e
e“
Porting to
Devices without Randomness/Entropy Sources”onp
a
g
e293 for more information.
cryptlib includes in its built-in generator an ANSI X9.17 / ANSI X9.31 generator for
FIPS 140 certification purposes. Full technical details of the generator are given in
t
her
e
f
e
r
e
n
c
ei
n“
Recommended Reading”onpa
g
e15.

Gathering Random Information
cryptlib can also gather its own random data by polling the system for random
information. There are two polling methods you can use, a fast poll that returns
immediately and retrieves a moderate amount of random information, and a slow poll
that may take some time but that retrieves much larger amounts of random
information. A fast poll is performed with:
cryptAddRandom( NULL, CRYPT_RANDOM_FASTPOLL );

In general you should sprinkle these throughout your code to build up the amount of
randomness in the pool.
A slow poll is performed with:
cryptAddRandom( NULL, CRYPT_RANDOM_SLOWPOLL );

The effect of this call varies depending on the operating system. Under DOS the call
returns immediately (see below). Under Windows 3.x the call will get all the
information it can in about a second, then return (there is usually more information
present in the system than can be obtained in a second). Under BeOS, OS/2, and on
the Macintosh, the call will get all the information it can and then return. Under
Unix, Windows 95/98/ME, Windows NT/2000/XP, and Windows CE the call will
spawn one or more separate processes or threads to perform the polling and will
return immediately while the poll continues in the background.
Before the first use of a high-level function such as envelopes, secure sessions, or
calling cryptGenerateKey or cryptExportKey you must perform at least one slow

280

Miscellaneous Topics
poll (or, in some cases, several fast polls — see below) in order to accumulate enough
random information for use by cryptlib. On most systems cryptlib will perform a
non-blocking randomness poll, so you can usually do this by calling the slow poll
routine when your program starts. This ensures that the random information will
have accumulated by the time you need it:
/* Program start-up */
cryptAddRandom( NULL, CRYPT_RANDOM_SLOWPOLL );
/* Other code, slow poll runs in the background */
cryptGenerateKey( cryptContext );

If you forget to perform a slow poll beforehand, the high-level function will block
until the slow poll completes. The fact that the call is blocking is usually fairly
obvious, because your program will stop for the duration of the randomness poll. If
no reliable random data is available then the high-level function that requires it will
return the error CRYPT_ERROR_RANDOM.

Obtaining Random Numbers
You can obtain random data from cryptlib by using an encryption context with an
algorithm that produces byte-oriented output (for example a stream cipher or a block
cipher employed in a stream mode like CFB or OFB). To obtain random data, create
a context, generate a key into it, and use the context to generate the required quantity
of output by encrypting the contents of a buffer. Since the encryption output is
r
a
ndo
m,
i
tdo
e
s
n
’
tma
t
t
e
rwha
tt
hebu
f
f
e
ri
ni
t
i
a
l
l
yc
o
nt
a
i
ns
.Fore
x
a
mpl
ey
ouc
a
nus
e
the RC4 algorithm (a stream cipher) to generate random data with:
CRYPT_CONTEXT cryptContext;
cryptCreateContext( &cryptContext, cryptUser, CRYPT_ALGO_RC4 );
cryptGenerateKey( cryptContext )
cryptEncrypt( cryptContext, randomDataBuffer, randomDataLength );
cryptDestroyContext( cryptContext );

This will fill the data buffer with the required number of random bytes.

Working with Newer Versions of cryptlib
Your software can automatically support new encryption algorithms as they are added
to cryptlib if you check for the range of supported algorithms instead of hard-coding
in the values that existed when you wrote the program. In order to support this,
cryptlib predefines the values CRYPT_ALGO_FIRST_CONVENTIONAL and
CRYPT_ALGO_LAST_CONVENTIONAL for the first and last possible
conventional encryption algorithms, CRYPT_ALGO_FIRST_PKC and
CRYPT_ALGO_LAST_PKC for the first and last possible public-key encryption
algorithms, CRYPT_ALGO_FIRST_HASH and CRYPT_ALGO_LAST_HASH for
the first and last possible hash algorithms, and CRYPT_ALGO_FIRST_MAC and
CRYPT_ALGO_LAST_MAC for the first and last possible MAC algorithms. By
checking each possible algorithm value within this range using
cryptQueryCapability, your software can automatically incorporate any new
algorithms as they are added. For example to scan for all available conventional
encryption algorithms you would use:
CRYPT_ALGO_TYPE cryptAlgo;
for( cryptAlgo = CRYPT_ALGO_FIRST_CONVENTIONAL;
cryptAlgo <= CRYPT_ALGO_LAST_CONVENTIONAL;
cryptAlgo++ )
if( cryptStatusOK( cryptQueryCapability( cryptAlgo, NULL ) )
/* Perform action using algorithm */;

The action you would perform would typically be building a list of available
algorithms and allowing the user to choose the one they preferred. The same can be
done for the public-key, hash, and MAC algorithms.

Working with Newer Versions of cryptlib

281

If your code follows these guidelines, it will automatically handle any new encryption
algorithms that are added in newer versions of cryptlib. If you are using the shared
l
i
br
a
r
yorDLLf
or
m ofc
r
y
pt
l
i
b,
y
ours
of
t
wa
r
e
’
se
nc
r
y
pt
i
o
nc
a
p
a
bi
l
i
t
i
e
swi
l
lbe
automatically upgraded every time cryptlib is upgraded.

282

Error Handling

Error Handling
Each function in cryptlib performs extensive parameter and error checking (although
monitoring of error codes has been omitted in the code samples for readability). In
addition each of the built-in encryption algorithms can perform a self-test procedure
that checks the implementation using standard test vectors and methods given with
the algorithm specification (typically FIPS publications, ANSI or IETF standards, or
standard reference implementations). This self-test is used to verify that each
encryption algorithm is performing as required.
The macros cryptStatusError() and cryptStatusOK() can be used to
determine whether a return value denotes an error condition, for example:
CRYPT_CONTEXT cryptContext;
int status;
status = cryptCreateContext( &cryptContext, cryptUser,
CRYPT_ALGO_IDEA );
if( cryptStatusError( status ) )
/* Perform error processing */;

The error codes that can be returned are grouped into a number of classes that cover
areas such as function parameter errors, resource errors, and data access errors.
Thef
i
r
s
tg
r
oupc
on
t
a
i
nsas
i
n
g
l
eme
mb
e
r
,
t
he“
noe
r
r
or
”v
a
l
ue
:
Error code

Description

CRYPT_OK

No error.

The next group contains parameter error codes that identify erroneous parameters
passed to cryptlib functions:
Error code

Description

CRYPT_ERROR_PARAM1…
CRYPT_ERROR_PARAM7

There is a problem with a parameter passed to a
cryptlib function. The exact code depends on the
parameter in error.

The next group contains resource-related errors such as a certain resource not being
available or initialised:
Error code

Description

CRYPT_ERROR_FAILED

The operation, for example a public-key encryption or
decryption, failed.

CRYPT_ERROR_INITED

The object or attribute that you have tried to initialise
has already been initialised previously.

CRYPT_ERROR_MEMORY

There is not enough memory available to perform this
operation.

CRYPT_NOSECURE cryptlib cannot perform an operation at the requested
s
e
c
ur
i
t
yl
e
v
e
l(
f
ore
x
a
mpl
ea
l
l
oc
a
t
e
dp
a
g
e
sc
a
n’
tbe
locked into memory to prevent them from being
s
wa
ppe
dt
od
i
s
k
,
ora
nLDAPc
on
ne
c
t
i
o
nc
a
n’
tbe
established using SSL).
CRYPT_ERROR_NOTINITED

Theo
bj
e
c
tora
t
t
r
i
b
ut
et
ha
ty
ouha
v
et
r
i
e
dt
ous
eha
s
n’
t
been initialised yet, or a resource which is required
i
s
n’
ta
v
a
i
l
a
b
l
e
.

CRYPT_ERROR_RANDOM

Not enough random data is available for cryptlib to
perform the requested operation.

Working with Newer Versions of cryptlib

283

The next group contains cryptlib security violations such as an attempt to use the
wr
ongobj
e
c
tf
ora
no
pe
r
a
t
i
o
nort
ous
ea
nob
j
e
c
tf
orwhi
c
hy
oudo
n’
tha
v
ea
c
c
e
s
s
permission:
Error code

Description

CRYPT_ERROR_COMPLETE

An operation that consists of multiple steps (such as a
message hash) is complete and cannot be continued.

CRYPT_ERROR_INCOMPLETE

An operation that consists of multiple steps (such as a
message hash) is still in progress and requires further
steps before it can be regarded as having completed.

CRYPT_ERROR_INVALID

The public/private key context or certificate object or
attribute is invalid for this type of operation.

CRYPT_ERROR_NOTAVAIL

The requested operation is not available for this object
(for example an attempt to load an encryption key into
a hash context, or to decrypt a Diffie-Hellman shared
integer with an RSA key).

CRYPT_ERROR_PERMISSION

Youdo
n
’
tha
v
ep
e
r
mi
s
s
i
o
nt
ope
r
f
or
mt
hi
st
y
peof
operation (for example an encrypt-only key being used
for a decrypt operation, or an attempt to modify a readonly attribute).

CRYPT_ERROR_SIGNALLED

An external event such as a signal from a hardware
device caused a change in the state of the object. For
example if a smart card is removed from a card reader,
all the objects that had been loaded or derived from the
data on the smart card would return CRYPT_ERROR_SIGNALLED if you tried to use them.
Once an object has entered this state, the only available
option is to destroy it, typically using
cryptDestroyObject.

CRYPT_ERROR_TIMEOUT

The operation timed out, either because of a general
timeout while accessing an object such as a network
connection or data file, or because the object was in use
for another operation such as asynchronous key
generation or a key database lookup operation.

CRYPT_ERROR_WRONGKEY

The key being used to decrypt or verify the signature
on a piece of data is incorrect.

The next group contains errors related to the higher-level encryption functions such
as enveloping, secure session, and key export/import and signature
generation/checking functions:
Error code

Description

CRYPT_ERROR_BADDATA

The data item (typically encrypted or signed data, or a
key certificate) was corrupt, or not all of the data was
pr
e
s
e
n
t
,a
ndi
tc
a
n
’
tbepr
o
c
e
s
s
e
d.

CRYPT_ERROR_OVERFLOW

There is too much data for this function to work with.
For an enveloping function, you need to call
cryptPopData before you can add any more data to the
envelope.
For a certificate function this means the amount of data
you have supplied is more than what is allowed for the
field you are trying to store it in.
For a public-key encryption or signature function this
means there is too much data for this public/private key
to encrypt/sign. You should either use a larger

284

Error Handling

Error code

Description
public/private key (in general a 1024-bit or larger key
should be sufficient for most purposes) or less data (for
example by reducing the key size in the encryption
context passed to cryptExportKey).

CRYPT_ERROR_SIGNATURE

Thes
i
g
na
t
ur
eori
nt
e
g
r
i
t
yc
he
c
kv
a
l
uedi
dn
’
tma
t
c
ht
he
data.

CRYPT_ERROR_UNDERFLOW

There is too little data in the envelope or session for
cryptlib to process (for example only a portion of a data
i
t
e
mma
ybepr
e
s
e
nt
,
whi
c
hi
s
n’
te
n
oug
hf
orcryptlib to
work with).

The next group contains data/information access errors, usually arising from keyset,
certificate, or device container object accesses:
Error code

Description

CRYPT_ERROR_DUPLICATE

The given item is already present in the container
object.

CRYPT_ERROR_NOTFOUND

The requested item (for example a key being read from
a key database or a certificate component being
e
x
t
r
a
c
t
e
df
r
o
m ac
e
r
t
i
f
i
c
a
t
e
)i
s
n’
tpr
e
s
e
n
ti
nt
he
container object.

CRYPT_ERROR_OPEN

The container object (for example a keyset or
c
on
f
i
g
ur
a
t
i
ond
a
t
a
ba
s
e
)c
o
ul
d
n’
tbeo
pe
ne
d,
e
i
t
h
e
r
be
c
a
us
ei
twa
s
n’
tf
ou
ndorb
e
c
a
us
et
heo
pe
nop
e
r
a
t
i
on
failed.

CRYPT_ERROR_READ

Ther
e
q
ue
s
t
e
di
t
e
mc
o
ul
dn
’
tb
er
e
a
df
r
o
mt
hec
on
t
a
i
ne
r
object.

CRYPT_ERROR_WRITE

Thei
t
e
mc
o
ul
d
n
’
tb
ewr
i
t
t
e
n to the container object or
t
hed
a
t
aobj
e
c
tc
ou
l
d
n
’
tbeup
da
t
e
d(
f
ore
x
a
mp
l
eak
e
y
c
ou
l
d
n’
tbewr
i
t
t
e
nt
oak
e
y
s
e
t
,
orc
oul
dn
’
tbed
e
l
e
t
e
d
from a keyset).

The next group contains errors related to data enveloping:
Error code
Description
CRYPT_ENVELOPE_ A resource such as an encryption key or password
RESOURCE
needs to be added to the envelope before cryptlib can
continue processing the data in it.

Extended Error Reporting
Some
t
i
me
st
hes
t
a
nd
a
r
dc
r
y
pt
l
i
be
r
r
orc
o
de
sa
r
e
n’
tc
a
p
a
b
l
eofr
e
t
ur
ni
ngf
ul
ld
e
t
a
i
ls on
the large variety of possible error conditions that can be encountered. This is
particularly true for complex objects such as certificates or ones that are tied to other
s
of
t
wa
r
eorha
r
dwa
r
ewhi
c
hi
sout
s
i
dec
r
y
pt
l
i
b’
sc
on
t
r
ol
.The
s
eo
bj
e
c
t
si
nc
l
ud
e
database or directory keyset objects, crypto devices, and secure sessions. For
example if there is a problem checking a certificate object, cryptlib will return a
generic CRYPT_ERROR_INVALID status. If there is a missing object attribute that
must be set before an object can be used, cryptlib will return a CRYPT_ERROR_NOTINITED status.
In order to obtain more information on the problem you can read the CRYPT_ATTRIBUTE_ERRORLOCUS attribute to obtain the locus of the error (the attribute
that caused the problem) and the CRYPT_ATTRIBUTE_ERRORTYPE attribute to
identify the type of problem that occurred. These error attributes are present in all
objects and can often provide more extensive information on why an operation with
the object failed, for example if a function returns CRYPT_ERROR_NOTINITED

Extended Error Reporting

285

then the CRYPT_ATTRIBUTE_ERRORLOCUS attribute will tell you which object
a
t
t
r
i
bu
t
eha
s
n’
tbe
e
ni
ni
t
i
a
l
i
s
e
d.
The error types are:
Error Type

Description

CRYPT_ERRTYPE_ATTR_ABSENT

The attribute is required but not present in the
object.

CRYPT_ERRTYPE_ATTR_PRESENT

The attribute is already present in the object, or
present but not permitted for this type of object.

CRYPT_ERRTYPE_ATTR_SIZE

The attribute is smaller than the minimum
allowable or larger than the maximum allowable
size.

CRYPT_ERRORTYPE_- The attribute is set to an invalid value.
ATTR_VALUE
CRYPT_ERRTYPE_CONSTRAINT

The attribute violates some constraint for the
object, or represents a constraint which is being
violated, for example a validity period or key
usage or certificate policy constraint.

CRYPT_ERRTYPE_The attribute violates a constraint set by an
ISSUER_CONSTRAINT issuer certificate, for example the issuer may set
a name constraint which is violated by the
c
e
r
t
i
f
i
c
a
t
eobj
e
c
t
’
ss
u
bj
e
c
t
Na
meor subject
altName.
For example to obtain more information on why an attempt to sign a certificate failed
you would use:
CRYPT_ATTRIBUTE_TYPE errorLocus;
CRYPT_ERRTYPE_TYPE errorType;
status = cryptSignCert( cryptCertificate, cryptCAKey );
if( cryptStatusError( status ) )
{
cryptGetAttribute( cryptCertificate, CRYPT_ATTRIBUTE_ERRORLOCUS,
&errorLocus );
cryptGetAttribute( cryptCertificate, CRYPT_ATTRIBUTE_ERRORTYPE,
&errorType );
}

The error type and locus information comes from cryptlib itself, and relates to errors
with object usage identified by cryptlib. In addition to the cryptlib error information,
keyset and session objects and objects tied to devices often provide internal error
information which is passed to them from the underlying software, hardware, or a
remote client or server application. The object-specific error code and message are
accessible as the CRYPT_ATTRIBUTE_INT_ERRORCODE and CRYPT_ATTRIBUTE_INT_ERRORMESSAGE attributes. For example to obtain more
information on why an attempt to read a key from an SQL Server database failed you
would use:
CRYPT_KEYSET cryptKeyset;
CRYPT_HANDLE publicKey
int status;
status = cryptGetPublicKey( &cryptKeyset, &publicKey,
CRYPT_KEYID_NAME, "John Doe" );
if( cryptStatusError( status ) )
{
int errorCode, errorStringLength;
char *errorString;
errorString = malloc( ... );
cryptGetAttribute( cryptKeyset, CRYPT_ATTRIBUTE_INT_ERRORCODE,
&errorCode );

286

Error Handling

cryptGetAttributeString( cryptKeyset,
CRYPT_ATTRIBUTE_INT_ERRORMESSAGE, errorString,
&errorStringLength );
}

Note that the error information being returned is passed through by cryptlib from the
underlying software or hardware, and will be specific to the implementation. For
example if the software that underlies a keyset database is SQL Server then the data
returned will be the SQL Server error code and message. Since the returned data is
low-level, internal error information coming from the underlying software and will
often be information provided by a third-party or remote client or server application,
the contents of the error code and message can vary somewhat but the error message
will typically contain some indication of what the problem is.
In some cases the access attempt will be blocked by the cryptlib security kernel, and
never gets to the object itself. This typically occurs when cryptlib returns a CRYPT_ERROR_PERMISSION error, in which the kernel has prevented a disallowed access
type. In this case neither the extended error information nor the internal error code
and string will be set, since the object never saw the access attempt.

Embedded OS Types

287

Embedded Systems
cryptlib has been designed to be usable in embedded designs that lack many facilities
that are normally found on standard systems, both in terms of resources (memory,
network I/O) and in system functionality (a filesystem, dynamic memory allocation).
I
fy
ou’
r
er
u
nn
i
ngi
nar
e
s
our
c
e
-constrained environment such as an embedded
system, you first need to decide what cryptlib services you require and disable any
unn
e
c
e
s
s
a
r
yop
t
i
ons
,
a
sde
s
c
r
i
be
di
n“
Customised and Cut-down cryptlib Versions”
on page 24. This will reduce the cryptlib code footprint to the minimum required for
your particular situation.
Asag
e
ne
r
a
lr
ul
eo
ft
h
u
mbi
fy
ou’
r
eo
nar
e
s
o
ur
c
e
-constrained system you should
turn off anything that uses networking, which includes secure sessions (USE_SESSIONS), and HTTP and LDAP keyset access (USE_HTTP, USE_LDAP). You
probably also want to turn off crypto devices, (USE_PKCS11 and USE_FORTEZZA), since the embedded system is unlikely to have PKCS #11 crypto
ha
r
dwa
r
ea
t
t
a
c
he
dt
oi
t
.Youpr
oba
bl
ywon
’
tbeus
i
ngda
t
a
ba
s
ek
e
y
s
e
t
s(
USE_DBMS)
,
a
ndun
l
e
s
sy
ou
’
r
eus
i
ngPGPk
e
y
r
i
ng
sy
ouc
a
nt
ur
nt
ha
to
f
fa
swe
l
l(
USE_PGPKEYS). PGP keyrings are particularly problematic because their structure
r
e
qui
r
e
st
ha
tt
he
ybepr
oc
e
s
s
e
dv
i
aal
o
ok
a
he
a
db
uf
f
e
rb
e
c
a
us
ei
t
’
sn
otp
os
s
i
b
l
et
o
de
t
e
r
mi
neh
owmuc
hmor
eda
t
aa
s
s
oc
i
a
t
e
dwi
t
ht
h
ek
e
yi
st
of
o
l
l
ow.I
fy
ou’
r
e
running in a memory-constrained environment and are thinking of using PGP keys,
you should consider using the PKCS #15 format (the cryptlib native keyset type)
i
ns
t
e
a
d,
s
i
nc
et
hi
sd
oe
s
n
’
tha
v
et
hi
spr
ob
l
e
m.
For envelopes, you probably want to turn off compressed enveloping (USE_COMPRESSION) since zlib needs to allocate a series of fairly sizeable buffers in
order to operate (256KB for compression, 32KB for decompression, compared to
onl
y8KBus
e
df
ort
h
ee
nv
e
l
o
peb
uf
f
e
ri
t
s
e
l
f
)
.I
fy
ou’
r
en
otus
i
ngPGP,
y
ouc
a
nt
ur
n
that off as well (USE_PGP). Finally, there are a considerable range of other options
that you can turn off to save memory and space, see cryptini.h for more details.
I
na
dd
i
t
i
ont
ot
hec
o
des
i
z
et
u
ni
nga
ndi
fy
ou
’
r
et
a
r
g
e
t
i
ngane
we
mbe
dde
ds
y
s
t
e
m
t
ha
ti
s
n
’
ta
l
r
e
a
dys
up
por
t
e
db
yc
r
y
pt
l
i
b,
y
oune
e
dto make any necessary systemspecific adaptations to cryptlib to match the characteristics of the embedded device
t
ha
ty
ou’
r
ewor
k
i
ngwi
t
h.The
s
ea
da
pt
a
t
i
onsa
r
ed
e
s
c
r
i
b
e
df
o
l
l
owi
ngt
hedi
s
c
us
s
i
o
n
of supported systems below.

Embedded OS Types
Many embedded OSes, and in particular real-time OSes (RTOSes) are highly
modular, and can be heavily customised to suit particular applications. Because of
t
hi
sh
i
g
hde
g
r
e
eofc
us
t
o
mi
s
a
bi
l
i
t
y
,
i
t
’
sno
tpos
s
i
bl
ef
orc
r
y
pt
l
i
bt
oa
u
t
o
ma
t
i
c
a
l
l
y
assume that a given OS capability will be available. As a result, the default cryptlib
build for a particular embedded OS/RTOS uses a fairly minimal set of OS capabilities
that should work in most configurations. If you have extended OS facilities available,
you can use the cryptlib configuration file cryptini.h to enable any additional
c
a
pa
bi
l
i
t
i
e
st
ha
ty
ouma
yne
e
d.I
t
’
sag
oodi
de
at
oc
ont
a
c
tt
hec
r
y
pt
l
i
bde
v
e
l
ope
r
s
before you build cryptlib on one of the more modular, configurable embedded OSes
like AMX, eCOS, µC/OS-II, µITRON, VxWorks, or XMK. Notes for individual
OSes are given below.

AMX
AMX is a highly configurable kernel with most functionality set to the minimum
level in the default build in order to conserve space. To run cryptlib you need to
enable the time/date manager (so that cryptlib can check datestamps on the data that
i
t
’
spr
oc
e
s
s
i
ng
)
,
a
ndt
i
me
-s
l
i
c
i
ngi
fy
ou’
r
er
u
nni
ngmul
t
i
p
l
et
a
s
k
swi
t
hi
nc
r
y
pt
l
i
b.For
t
a
s
ks
y
nc
hr
on
i
s
a
t
i
o
nc
r
y
pt
l
i
bus
e
sAMXs
e
ma
ph
or
e
s
,
butd
oe
s
n
’
tr
e
q
ui
r
ea
nyf
ur
t
he
r
AMX facilities like mailboxes, event groups, or buffer pools.

288

Embedded Systems

ChorusOS
ChorusOS provides a standard Posix file API and BSD sockets networking API that
ma
t
c
h
e
st
heoneus
e
dbyc
r
y
pt
l
i
b’
sg
e
ne
r
i
cUni
xc
o
nf
i
g
ur
a
t
i
on.Nos
pe
c
i
a
l
operational considerations are required for cryptlib in this environment.

eCOS
Unlike most other embedded OSes, eCOS requires that all data structures used by the
kernel be statically allocated by the user. This means that cryptlib has to allocate
storage for all semaphores, mutexes, tasks, and other eCOS objects either at compile
t
i
meor(
a
tt
hel
a
t
e
s
t
)whe
ni
t
’
sl
oa
d
e
d/
i
n
i
t
i
a
l
i
s
e
d.Thi
se
nt
a
i
l
sa
l
l
oc
a
t
i
ngt
hes
t
or
a
g
e
required by eCOS for each object when cryptlib allocates its kernel object table,
rather than allocating the storage on-demand when an object is created. If memory is
at a premium, you should shrink the object table (via CONFIG_CONSERVE_MEMORY and/or CONFIG_NUM_OBJECTS) to the smallest size that you can work
with, since each object entry has to include space for eCOS kernel data.
Typical eCOS configurations include a full TCP/IP stack and file I/O services.
cryptlib uses the Posix section 5/6 file I/O layer, the universal low-level I/O layer
t
ha
t
’
ss
u
pp
or
t
e
dbya
l
lf
i
l
e
s
y
s
t
e
m dr
i
v
e
r
s
.TheTCP/
I
Ps
t
a
c
ki
sas
t
a
nda
r
dBSDderived stack and it’
sus
ei
se
na
b
l
e
dbyde
f
a
u
l
ti
nt
hee
COSbui
l
d.

µC/OS-II
To run cryptlib under µC/OS-II you need to enable mutexes (OS_MUTEX_EN and
OS_MUTEX_DEL_EN) for task synchronisation and tasks (OS_TASK_CREATE_EN
and OS_TASK_DEL_EN)i
fy
ou
’
r
er
un
ni
ngmu
l
t
i
pl
et
a
s
k
swithin cryptlib. µC/OS-II
ma
k
e
sat
a
s
k
’
spr
i
or
i
t
ydod
o
ubl
edu
t
ya
st
het
a
s
kI
D,s
ot
h
e
r
e
’
sn
owa
yt
oun
i
q
ue
l
y
i
de
nt
i
f
yat
a
s
kov
e
rt
hel
ongt
e
r
m.I
fy
ouc
h
a
ng
eat
a
s
k
’
sp
r
i
or
i
t
yus
i
ng
OSTaskChangePrio(),
you
’
l
la
l
s
oc
ha
ng
ei
t
st
a
s
kI
D.Thi
sme
a
nst
ha
ti
fy
ou
’
v
e
bou
ndac
r
y
pt
l
i
bo
bj
e
c
tt
oat
a
s
kf
ora
c
c
e
s
sc
o
nt
r
o
lpur
pos
e
s(
s
e
e“
Object Security”o
n
page 41)
,
i
t
’
l
lnol
o
ng
e
rbea
c
c
e
s
s
i
b
l
eo
nc
et
het
a
s
kpr
i
or
i
t
yc
ha
ng
ec
ha
ng
e
si
t
st
a
s
k
ID. If your tasksc
ha
ng
et
he
i
rI
Dsi
nt
hi
sma
nn
e
r
,
y
ous
ho
u
l
dn
’
tbi
ndo
bj
e
c
t
st
o
particular task IDs.

Embedded Linux
Embedded Linux is a standard Unix environment. No special operational
considerations are required for cryptlib in this environment.

µITRON
µITRON has a file interface (ITRON/FILE) derived from the BTRON persistent
obj
e
c
ts
t
or
ei
n
t
e
r
f
a
c
e
,
b
utt
heonl
yd
oc
u
me
nt
a
t
i
onf
ort
hi
si
sf
orBTRONa
ndi
t
’
son
l
y
available in Japanese. Because of the inability to obtain either documentation or an
implementation to code against, cryptlib only contains stubs for file I/O functionality.
If your µITRON system provides this file interface, please contact the cryptlib
developers.
µI
TRONa
l
s
oha
saTCP/
I
Pi
nt
e
r
f
a
c
e
,
b
uti
td
oe
s
n
’
ts
e
e
mt
obewi
d
e
l
yus
e
da
ndt
he
only documentation available is in Japanese. Because of this the use of TCP/IP under
µITRON is disabled by default in cryptini.h, if you have a µITRON TCP/IP
implementation you can use it to replace the existing TCP/IP interface in io/tcp.c.

Palm OS
When you install the PalmOS SDK, the include path for the PalmOS compiler may
not cover the directory containing the standard ANSI/ISO C headers. These headers
are found in the posix subdirectory of the standard PalmOS include directory, you
can either configure the include path to include this directory or specify it in the
makefile with the –I compiler option.
I
fy
ou’
r
ebui
l
d
i
ngc
r
y
pt
l
i
bus
i
ngt
hePa
l
mOSSDKc
ompi
l
e
r
,
a
l
lc
o
mp
i
l
e
rwa
r
ni
ng
me
s
s
a
g
e
sa
r
ee
na
b
l
e
dbyde
f
a
ul
ta
ndc
a
n
’
tb
er
e
s
e
tt
oamor
enor
ma
ll
e
v
e
l
.Be
c
a
us
e

Embedded OS Types

289

of t
hi
sma
x
i
mu
m wa
r
ni
ngl
e
ve
l
,
y
ou’
l
lg
e
tas
t
r
e
a
mo
fc
o
mpi
l
e
rme
s
s
a
g
e
swhe
ny
ou
build cryptlib, in particular erroneous used-before-initialised messages. This is
normal, and can be ignored.
I
fy
ou’
r
ebui
l
d
i
ngc
r
y
pt
l
i
bus
i
ngt
hePRCt
oo
l
c
h
a
i
n,
t
hePa
l
mOShe
aders contain gccspecific directives that try to pull in gcc headers that lie outside the PalmOS SDK
pa
t
h.I
ft
hep
a
t
ht
ot
he
s
ea
dd
i
t
i
o
na
lhe
a
de
r
si
s
n
’
tc
on
f
i
g
ur
e
d,
y
ouc
a
ne
i
t
he
rc
o
nf
i
g
ur
e
the include path to include the directories needed by gcc or specify it in the makefile
with the -idirafter compiler option.

QNX Neutrino
QNX Neutrino is a standard Unix environment, and in general no special operational
considerations are required for cryptlib in this environment. The one exception is in
the choice of networking environments. QNX Neutrino provides three network stack
configurations, the standard TCP/IP stack, the enhanced TCP/IP stack, and a lowresource version of the standard stack. cryptlib works with all of these stacks, and
will try and use the mos
ts
o
ph
i
s
t
i
c
a
t
e
df
e
a
t
ur
e
spr
ov
i
d
e
dbyt
hes
y
s
t
e
m.I
fy
ou’
r
e
using one of the more restricted networking stacks (for example the tiny TCP/IP stack
with no IPv6 support) you may need to change the settings in io/tcp.h to reflect this.

RTEMS
RTEMS provides a standard Posix file API and BSD sockets networking API that
ma
t
c
h
e
st
heoneus
e
dbyc
r
y
pt
l
i
b’
sg
e
ne
r
i
cUni
xc
o
nf
i
g
ur
a
t
i
on.Nos
pe
c
i
a
l
operational considerations are required for cryptlib in this environment.

uClinux
uClinux is an embedded OS intended for use on hardware without memory
pr
ot
e
c
t
i
on,
a
l
l
owi
ngi
tt
ober
uno
ns
y
s
t
e
mst
ha
tc
o
ul
dn
’
to
t
he
r
wi
s
er
unas
t
a
nd
a
r
d
Linux build. To conserve memory, you may want to configure uClinux to use the
page_alloc2/kmalloc2 allocator instead of the somewhat wasteful standard
power-of-two Linux allocator, which is intended for use on systems with virtual
me
mor
ys
uppor
t
.c
r
y
pt
l
i
b
’
sme
mor
ya
l
l
oc
a
t
i
ons
t
r
a
t
e
g
yf
i
t
sne
a
t
l
ywi
t
ht
he
page_alloc2 allocator to minimise memory usage.
By default the uClinux toolchains tend to allocate extremely small stacks of only
4KB, which is inadequate for all but the most trivial applications. To provide an
adequate stack, you need to either set FLTFLAGS=-s stacksize and export
FLTFLAGS to the makefile before building your application, or run flthdrs –s
stacksize on your executable after building it.

Windows CE
Windows CE is a standard Windows environment. No special operational
considerations are required for cryptlib in this environment.

VxWorks
VxWorks includes a TCP/IP stack and file I/O services. cryptlib uses the ioLib file
I/O mechanisms, the universal low-l
e
v
e
lI
/
Ol
a
y
e
rt
ha
t
’
ss
u
ppor
t
e
dbya
l
lf
i
l
e
s
y
s
t
e
m
drivers. The VxWorks TCP/IP stack has changed somewhat over time and is
sometimes replaced by more functional third-party alternatives or may not be present
at all if VxWorks has been configured without it. Because of this, the use of TCP/IP
s
e
r
v
i
c
e
si
s
n’
te
n
a
b
l
e
dbyde
f
a
ul
t
.I
fy
oun
e
e
dne
t
wor
k
i
ngs
e
r
v
i
c
e
s
,
y
ouc
a
ne
na
b
l
e
them in cryptini.h, and may need to perform VxWorks-specific network initialisation
(for example calling selectInit)i
fy
oura
pp
l
i
c
a
t
i
o
ndo
e
s
n’
ta
l
r
e
a
dydos
o.

Xilinx XMK
XMK is highly configurable kernel with several functions disabled in the default
build. To run cryptlib you need to enable mutexes (config_pthread_mutex)
for thread synchronisation, the yield interface (config_yield) for thread
management, and timers (config_time)f
ort
i
meha
nd
l
i
ng
.I
na
ddi
t
i
o
ni
fy
o
u’
r
e

290

Embedded Systems

starting threads within cryptlib, you need to either increase the default thread stack
size (pthread_stack_size) or set a larger stack size when you start the internal
thread.
Xilinkx XMK provides an emulated Posix filesystem API, however in order to reduce
code size cryptlib uses the native XMK memory filesystem (MFS) interface to access
stored data in RAM, ROM, or flash memory. If you need to store data such as
configuration options or private keys, you need to enable MFS support in your XMK
build.
XMK includes a minimal network stack (LibXilNet), however this only provides
server funct
i
o
na
l
i
t
y(
s
oi
t
’
sn
otp
os
s
i
b
l
et
oi
mp
l
e
me
n
tane
t
wor
kc
l
i
e
nt
)a
n
dd
oe
s
n
’
t
support timers, so that each send or receive will block forever until data arrives or is
sent. Because of these limitations, you need to use a third-party network stack in
order to us
ec
r
y
pt
l
i
b
’
sne
t
wor
k
i
ngc
a
pa
bi
l
i
t
i
e
sun
de
rXMK.

Embedded cryptlib Configuration Options
You can use the standard cryptlib makefile to cross-compile the code for any of the
e
mbe
d
de
dt
a
r
g
e
t
s
.I
fy
ou’
r
ebui
l
d
i
ngf
orane
wt
a
r
g
e
tt
y
pe
,
y
ouf
i
r
s
tne
e
dt
oa
d
d the
ne
wt
a
r
g
e
tt
y
pea
tt
hee
ndoft
hema
k
e
f
i
l
ei
nt
h
e“
Embe
dd
e
dSy
s
t
e
ms
”s
e
c
t
i
on.The
cryptlib naming convention for preprocessor symbols used to identify targets is to use
__target_name__, which then enables system-specific behaviour in the code. For
example if you were adding a new target type to build the code for an Atmel TDMI
ARM c
or
e
,
y
ou
’
dus
e–D__ATMEL__ as the necessary compile option (some
compilers will define the necessary symbols automatically).
The cryptlib makefile and source code auto-detect various system parameters at
c
o
mp
i
l
et
i
me
,
i
fy
o
u’
r
ec
r
os
s
-c
o
mp
i
l
i
ngf
orane
wt
a
r
g
e
tt
ypet
h
a
ty
ou
’
v
ede
f
i
ne
d
y
our
s
e
l
fy
o
u’
l
ln
e
e
dt
oov
e
r
r
i
det
h
i
ss
ot
ha
ty
ou
’
r
eb
ui
l
di
ngwi
t
ht
h
epa
r
a
me
t
e
r
sf
or
your target rather than for the host system. In addition you can enable various build
options for systems with limited resources as described earlier. The values that you
may need to define to handle these system-specific options are:
Option

Description

__target_name__

Thet
a
r
g
e
tt
y
pet
ha
ty
ou
’
r
ebu
i
l
d
i
ngfor.

CONFIG_LITTLE_ENDIAN
CONFIG_BIG_ENDIAN

The CPU endianness of the target
system.

CONFIG_CONSERVE_MEMORY

Define if the target has limited memory
available to reduce the default sizes of
bu
f
f
e
r
sa
ndda
t
as
t
r
uc
t
ur
e
s
.“
Li
mi
t
e
d”
means less than about 256KB of RAM.

CONFIG_DEBUG_MALLOC

Define to dump memory usage
diagnostics to the console. You
g
e
ne
r
a
l
l
ywoul
d
n’
tus
et
hi
so
pt
i
onont
he
target system, but only on the host during
development.

CONFIG_NO_DYNALLOC

De
f
i
n
et
oc
ha
ng
ec
r
y
pt
l
i
b
’
sh
a
nd
l
i
ngof
on-demand memory allocation as
de
s
c
r
i
be
di
n“
Porting to Devices without
Dynamic Memory Allocation”onp
a
g
e
291.

CONFIG_NO_ERRORMSG

Don’
ti
n
c
l
u
del
ongde
s
c
r
i
p
t
i
v
ee
r
r
or
messages in the code, which reduces
code size.

CONFIG_NO_STDIO

Define if the target has no
filesystem/stdio support.

CONFIG_NUM_OBJECTS=n

The number of objects that cryptlib

Debugging with Embedded cryptlib

Option

Description
reserves room for, defaulting to 1024
without CONFIG_CONSERVE_MEMORY defined or 128 with.

CONFIG_RANDSEED
CONFIG_RANDSEED_QUALITY

Define to use external random seed data.
Define to set the value of the random
seed data, as a percentage figure from 10100 percent.

291

Finally, cryptlib includes a considerable amount of other configurability that you can
take advantage of if you need to use it in an environment that imposes particular
r
e
s
t
r
i
c
t
i
onsonr
e
s
o
ur
c
eus
a
g
e
.I
fy
ou’
r
ewor
k
i
ngwi
t
ha
ne
mb
e
d
de
ds
y
s
t
e
m,
y
ou
should contact the cryptlib developers with more details on any specific requirements
that you may have.
Once you
’
v
eg
ott
hene
c
e
s
s
a
r
yopt
i
onss
e
tup,
y
ouc
a
nb
ui
l
dt
hec
od
e
.I
fy
ou’
r
e
building for a completely new target, cryptlib will detect this and print messages at
the various locations in the code where you need to add system-specific adaptations
such as support for reading/writing to flash memory segments in io/file.c.
Alternatively, you can edit io/file.c before you try to build the code, look for all the
locations where CONFIG_NO_STDIO is referenced, and add the necessary support
there rather than having cryptlib warn you about it during the build process.

Debugging with Embedded cryptlib
Si
nc
ey
ou
’
l
lbeus
i
ngt
hes
a
mec
od
eony
o
urhos
ts
y
s
t
e
ma
sy
ouwi
l
li
nt
het
a
r
g
e
t
,
by
far the easiest way to develop and debug your application is to do it on the host using
your preferred development tools. By enabling the same build options as you would
on the target (except for the CPU endianness override) you can exactly duplicate the
conditions on the target embedded system and perform all of your application
development on the host rather than having to cross-compile, upload code, and work
wi
t
ht
het
a
r
g
e
t
’
sde
bug
g
i
ngf
a
c
i
l
i
t
i
e
s(
i
ft
he
r
ea
r
ea
ny
)
.

Porting to Devices without a Filesystem
I
ft
hede
v
i
c
ey
ou
’
r
ewor
k
i
ngwi
t
hl
a
c
k
saf
i
l
e
s
y
s
t
e
m,
y
ou
’
l
lne
e
dt
owor
kwi
t
h
io/file.c to add an adaptation layer to handle the underlying storage abstraction that
y
ou’
r
eus
i
ng
.I
ne
mbe
d
de
dd
e
v
i
c
e
st
h
i
sus
u
a
l
l
yc
o
ns
i
s
t
sofbl
oc
k
so
ff
l
a
s
hme
mor
yor
occasionally battery-backed RAM, identified either by name/label or an integer value
or tag. cryptlib supports the use of named/tagged memory segments if you build it
with the CONFIG_NO_STDIO option, and will assemble in-memory (RAM) pseudofiles on which it performs all I/O until the file is committed to backing store,
whe
r
e
up
oni
t
’
l
lpe
r
form an atomic transfer of the pseudo-file to flash to minimise
we
a
ront
h
ef
l
a
s
hme
mor
yc
e
l
l
s
.I
t
’
st
huspos
s
i
bl
et
oma
n
i
p
ul
a
t
et
h
e
s
e(
ps
e
ud
o-)files
arbitrarily without causing excessive wear on the underlying storage medium.

Porting to Devices without Dynamic Memory Allocation
I
fy
ours
y
s
t
e
ml
a
c
k
sdy
na
mi
cme
mor
ya
l
l
oc
a
t
i
on,
orh
a
ss
ol
i
t
t
l
eme
mor
yt
h
a
ti
t
’
s
necessary to conserve it as much as possible, you first need to build cryptlib with the
CONFIG_CONSERVE_MEMORY option. This reduces the default sizes of some
bu
f
f
e
r
s
,
a
nds
e
t
st
hei
ni
t
i
a
ls
i
z
eofc
r
y
pt
l
i
b’
si
nt
e
r
na
lobj
e
c
tt
a
b
l
et
o12
8ob
j
e
c
t
s
instead of the usual 1024. You can further tune the amount of memory used by the
system object table by setting the CONFIG_NUM_OBJECTS setting to the
maximum nu
mb
e
rofobj
e
c
t
st
ha
ty
ou’
l
lne
e
d.Thi
sv
a
l
uemus
tbeap
owe
ro
f2,
a
n
d
c
a
n
’
tb
el
e
s
st
ha
n8.Fors
i
ng
l
e
-purpose use in an embedded device (for example
when used specifically for enveloping messages rather than as a general-purpose tool
where anything is possible), you can usually get by with 32 or even 16 objects.
Depending on other options such as whether you use certificate trust settings or not
and whether your system has a 16- or 32-bit word size, the cryptlib kernel and built-in
system objects consume between 6 and 12 KB of memory.

292

Embedded Systems

As a rough rule of thumb, each non-public-key encryption context consumes around
200by
t
e
s(
a
l
o
ngwi
t
ha
nye
x
t
r
ame
mor
yne
e
de
dbyt
hea
l
g
or
i
t
h
m’
se
x
pa
nd
e
d
encryption key), each public-key encryption context consumes around 1500 bytes
(depending again on algorithm-specific parameters such as the algorithm type and
key size), file keysets (which are buffered in memory as mentioned earlier) consume
600 bytes plus the size of the keyset file (usually around 1.3 KB for a standard 1024bit RSA key and accompanying certificate and 3 KB for the key and a 3-certificate
chain), envelopes consume 1.2KB plus 16 KB for enveloping and 8KB for deenveloping (the extra size is due to the built-in envelope buffer), and certificates
consume a
na
mou
nto
fme
mo
r
yt
ha
ti
s
n
’
te
a
s
i
l
ypr
e
d
i
c
t
a
b
l
ei
na
dv
a
n
c
es
i
nc
et
he
y
consist of an arbitrary number of arbitrarily-sized objects. This makes it very
difficult to estimate their eventual memory usage, but a rule of thumb is about 2 KB
used for a typical certificate. Note that the certificate object consumption has very
little to do with the key size, but is mostly dependent on the number and size of all the
other X.509 components that are present in the certificate.

Memory Allocation Strategy
cryptlib allocates memory in strict FIFO manner, so that creating an object and then
destroying it again rolls back memory to the exact state it was in before the object
wa
sc
r
e
a
t
e
d.Thi
se
ns
ur
e
st
ha
ti
t
’
spos
s
i
bl
et
or
u
nc
r
y
pt
l
i
bonas
y
s
t
e
m wi
t
h
ou
t
dynamic memory allocation by using a simple high-water-mark pointer that tracks the
last memory position used, and falls back to its earlier position when the memory is
“
f
r
e
e
d”
.Be
c
a
us
eo
ft
hi
sme
mor
yus
a
g
es
t
r
a
t
e
g
y
,
c
r
y
pt
l
i
b,
a
l
t
h
oug
hi
td
oe
sa
c
qui
r
e
memory as required,
d
oe
s
n
’
tne
e
dr
e
a
ldy
na
mi
cme
mor
ya
l
l
oc
a
t
i
ona
ndc
a
nf
un
c
t
i
o
n
perfectly well if given a single fixed block of memory and told to use that.
cryptlib allocates either very little or no memory during its normal operation. That is,
memory is allocated once at object creation or activation, after which cryptlib stays
within the already-allocated bounds unless it encounters some object that it needs to
store for later use. For example if it finds a certificate while processing S/MIME data
i
t
’
l
ln
e
e
dt
oa
c
qu
i
r
e a block of memory to store the certificate for later access by the
caller.

cryptlib Memory Usage
Almost all of the information that cryptlib processes has the potential to include
arbitrary-length data, and occasionally arbitrary amounts of arbitrary-length data.
Ce
r
t
i
f
i
c
a
t
e
sa
r
eapa
r
t
i
c
ul
a
re
x
a
mp
l
eo
ft
h
i
s
,
a
sme
nt
i
o
ne
de
a
r
l
i
e
r
.c
r
y
pt
l
i
b
’
ss
t
r
a
t
e
g
y
for handling these situations is to use stack memory to handle the data if possible, but
if the item being processed exceeds a certain size, to temporarily grab a larger block
of memory from the heap to allow the item to be processed, freeing it again
immediately after use.
In normal use this overflow handling is never invoked, however since cryptlib can
always run into data items of unusual size (constructed either accidentally or
maliciously), you need to decide whether you want to allow this behaviour or not.
Allowing it means that you can process unusual data items, but may make you
vulnerable to deliberate resource-starvation attacks. Conversely, denying it makes
you immune to excessive memory usage when trying to process data maliciously
constructed to require extra memory to process, but will also make it impossible to
process data that just happens to have unusual characteristics. In general, cryptlib
will be able to process any normal data without requiring dynamically allocated
me
mor
y
,
s
oi
fy
ouk
nowi
na
d
v
a
nc
ewhi
c
ht
y
pe
so
fd
a
t
ay
o
u’
l
lbepr
oc
e
s
s
i
nga
nda
r
e
concerned about possible resource-starvation attacks, you can disable the
opportunistic allocation of larger working areas by using the
CONFIG_NO_DYNALLOC build option.
cryptlib includes a number of internal lookup tables used for certificate decoding,
algorithm information lookup, error parsing, and so on. These are all declared
static const to tell the compiler to place them in the read-only code segment
(held in ROM) rather than the initialised data segment (held in RAM). If your

Porting to Devices without Randomness/Entropy Sources

293

c
o
mp
i
l
e
rd
oe
s
n
’
ta
ut
o
ma
t
i
c
a
l
l
ydot
hi
sf
ory
ou(
a
l
mos
ta
l
ld
o)
,
y
ou’
l
lne
e
dt
opl
a
y
with compiler options to ensure that the tables are stored in ROM rather than RAM.
Many cryptlib functions store detailed error information as descriptive text strings
that can be retrieved through the CRYPT_ATTRIBUTE_INT_ERRORMESSAGE
attribute. Since storage for these detailed text messages consumes ROM space, you
may want to disable them to save space, or only enable them in the debug build but
not the release build. To disable descriptive error messages (only error codes will be
returned), define CONFIG_NO_ERRORMSG.

Tracking Memory Usage
I
nor
de
rt
ot
r
a
c
kme
mor
yus
a
g
ea
ndde
t
e
r
mi
n
ewha
t
’
l
lber
e
qu
i
r
e
do
ny
ourt
a
r
g
e
t
system, you can use the CONFIG_DEBUG_MALLOC option to dump diagnostics
about memory usage to the console. This will allow you to see approximately how
much memory a certain operation will require, and let you play with rearranging
operations to reduce memory consumption. For example having two objects active
simultaneously rather than using them one after the other will result in a total memory
consumption equal to the sum of their sizes rather than only the size of the larger of
the two objects.
The memory usage diagnostics will reveal the FIFO nature of the memory allocation
that cryptlib uses to try to minimise its overall footprint. You can use the sequence
numbers after each allocate and free to track the order in which things are used.

Porting to Devices without Randomness/Entropy Sources
cryptlib requires a source (or more generally multiple sources) of randomness/entropy
for the generation of encryption keys ands
i
mi
l
a
rda
t
a
,
a
sd
e
s
c
r
i
be
di
n“
Random
Numbers”onpa
g
e279. On some embedded systems there may not be enough
entropy available to safely generate these keys. You can provide this additional
entropy yourself through the use of the CONFIG_RANDSEED option, which enables
the use of stored random data that contains additional random seed material. This is
s
t
or
e
di
nt
hes
a
mel
oc
a
t
i
o
na
st
hec
r
y
pt
l
i
bc
on
f
i
g
ur
a
t
i
ond
a
t
a(
s
e
e“
Working with
Configuration Options”o
npa
g
e274 f
ormor
ede
t
a
i
l
s
)
,
a
ndi
s
n’
tne
c
e
s
s
a
r
i
l
yaf
i
l
ebu
t
can be a block of data in flash memory, data in battery-backed RAM, or whatever
other mechanism your system uses for persistent storage. If you define CONFIG_RANDSEED, cryptlib will try and read the random seed data and use it as additional
input to the internal randomness pool. This seed data should be at least 128 bits (16
bytes) long, something like 128 or 256 bytes is a better value. The source of the data
i
sde
t
e
r
mi
ne
dbyy
ours
y
s
t
e
mc
on
f
i
g
ur
a
t
i
on,
i
ft
h
e
r
e
’
saf
i
l
es
y
s
t
e
ma
v
a
i
l
a
b
l
ei
t
’
l
lbe
stored in a file called randseed.dat,
i
fnoti
t
’
l
lbea
c
c
e
s
s
e
dv
i
awha
t
e
v
e
rpe
r
s
i
s
t
e
n
t
storage mechanism is configured for your system in io/file.c. When you build your
embedded system, you should install the seed data from an external source, for
example a hardware random number generator or a copy of cryptlib running on a
secure system with a good source of randomness (the use of cryptlib to generate
r
a
ndo
mda
t
ai
sc
ov
e
r
e
di
n“
Random Numbers”o
npa
g
e279).
Since a significant portion of the input data for crypto key generation will be
determined by the seed data if there are no other randomness sources available
(cryptlib will always get at least some randomness from the environment, so the value
wi
l
lc
h
a
ng
ee
a
c
ht
i
mei
t
’
sus
e
d)
,
y
ous
hou
l
dt
a
k
ea
smuc
hc
a
r
ea
spos
s
i
bl
et
opr
o
t
e
c
t
the seed data. Obviously you should use different seed data on each system, to
prevent a compromise of one system from affecting any others. In addition if your
system provides any protection mechanisms you should apply them to the seed data
to try and safeguard it as much as possible. Finally, you should use the ability to add
user-s
up
pl
i
e
dr
a
n
do
mne
s
sde
s
c
r
i
be
di
n“
Random Numbers”onpa
g
e279 to
periodically add any situation-specific data that you may have available. For example
if your embedded device is being used for voice or video transmission you can add
segments of the compressed audio or video data, and if your device performs a
sensor/monitoring function you can add the sensor data. Since most embedded
devices have at least some interactionwi
t
ht
hes
ur
r
ou
nd
i
nge
nv
i
r
on
me
nt
,
t
he
r
e
’
s
usually a source of additional randomness available.

294

Embedded Systems

Once you have your seed data set up, you need to decide how much overall
randomness it contributes to the system. You can set this value as a percentage
between 10 and 100 percent via the CONFIG_RANDSEED_QUALITY
c
on
f
i
g
ur
a
t
i
ono
pt
i
o
n.I
fy
oudon
’
ts
e
tav
a
l
u
e
,
c
r
y
pt
l
i
bwi
l
la
s
s
umeaf
i
g
ur
eof80%,
meaning that it needs to obtain an additional 20% of randomness from the
e
nv
i
r
on
me
ntbe
f
or
ei
t
’
l
lg
e
ne
r
a
t
ek
e
y
s
.Note that this setting is merely a safety level,
i
td
oe
s
n
’
tme
a
nt
ha
tc
r
y
pt
l
i
bwi
l
lg
a
t
he
rr
a
ndo
mne
s
su
nt
i
li
tr
e
a
c
he
s10
0% a
n
dt
h
e
n
s
t
op(
i
tne
v
e
rs
t
o
psg
a
t
he
r
i
ngr
a
ndo
mne
s
s
)
,
me
r
e
l
yt
ha
ti
twon
’
tg
e
ne
r
a
t
ek
e
y
swhe
n
the randomness value is below 100%.

The Database Plugin Interface

295

Database and Networking Plugins
In order to communicate with databases that are used as certificate stores and with
different network types, cryptlib uses a plugin interface that allows it to talk to any
type of database back-end and network protocol. The database plugin provides five
functions that are used to interface to the back-end, two functions to open and close
the connection to the back-end, two to send data to and read data from it, and one to
fetch extended error information if a problem occurs. The plugin typically runs as a
Unix daemon which is accessed via an RPC mechanism, however for the ODBC and
generic database interfaces the code is compiled directly into cryptlib. If you prefer
to have your plugin as part of cryptlib you can compile it in as a generic database
interface. The advantage of using an RPC mechanism instead of compiling the
plugin code directly into cryptlib is that cryptlib itself (and the machine that cryptlib
is running on) don’
t need to contain any database interface code, since everything can
be done on the database server.
The network plugin interface also provides five functions, two to initialise and shut
down the connection, two to read and write data, and one to check that the
networking interface provided by the interface has been correctly initialised. The
network plugin allows cryptlib to use any kind of network interface, either a
customised form of the built-in BSD sockets interface or a completely different
network mechanism such as SNA or X.25.
The crypto plugin interface is slightly different, and provides direct access to
c
r
y
pt
l
i
b’
si
nt
e
r
na
le
nc
r
y
pt
i
o
nc
a
pa
bi
l
i
t
yi
n
t
e
r
f
a
c
e
.Re
pl
a
c
i
n
gabui
l
t
-in software
encryption capability with (say) a hardware crypto core involves unplugging the
built-in software implementation and replacing it with the corresponding hardware
core interface.

The Database Plugin Interface
The database plugin interface is used when cryptlib receives a user request to access a
database of type CRYPT_KEYSET_PLUGIN or CRYPT_KEYSET_PLUGIN_STORE (and by extension for the various CRYPT_KEYSET_ODBC and CRYPT_KEYSET_DATABASEt
y
pe
sa
swe
l
l
,
a
l
t
h
oug
ht
he
s
ea
r
epr
e
c
o
nf
i
g
ur
e
da
ndd
on
’
t
require any further setup). The first thing that cryptlib does is call the
initDbxSession() function in keyset/dbms.c, which connects the generic
database type to the actual database plugin (for example an Oracle, Sybase, or
PostgreSQL interface). There are three standard plugin types defined, one for ODBC,
one for generic built-in databases, and a skeleton generic database network plugin
that can communicate with a stub server that talks to the actual database. If you need
any other plugin type for a particular database, you can create it as required.
The structure of the plugin is as follows:
#include "keyset/keyset.h"
/* Plugin functions: openDatabase(), closeDatabase(), performUpdate(),
performQuery(),performErrorQuery() */
int initDispatchDatabase( DBMS_INFO *dbmsInfo )
{
dbmsInfo->openDatabaseBackend = openDatabase;
dbmsInfo->closeDatabaseBackend = closeDatabase;
dbmsInfo->performUpdateBackend = performUpdate;
dbmsInfo->performQueryBackend = performQuery;
dbmsInfo->performErrorQueryBackend = performErrorQuery;
return( CRYPT_OK );
}

keyset.h contains the keyset-related defines that are used in the code, and the
dispatcher initialisation function sets up function pointers to the database access
routines, which are explained in more detail below. State information about a session
with the database is contained in the DBMS_STATE_INFO structure which is
defined in keyset.h. This contains both shared information such as the last error

296

Database and Networking Plugins

code and the status of the session, and back-end -specific information such as
connection handles and temporary data areas. When you create a plugin for a new
database type, you should add any variables that you need to the database-specific
section of the DBMS_STATE_INFO structure. When cryptlib calls your plugin
functions, it will pass in the DBMS_STATE_INFO that you can use to store state
information.

Database Plugin Functions
The database plugin functions that you need to provide are as follows:
static int openDatabase( DBMS_STATE_INFO *dbmsInfo, const char *name,
const int options, int *featureFlags )

This function is called to open a session with the database. The parameters are the
name of the database to open the session to and a set of option flags that apply to the
session. The name parameter is a composite value that depends on the underlying
database being used, usually this is simply the database name, but it can also contain
a complete user name and password in the format user:pass@server. Other
combinations are user:pass (only a database user name and password) or
user@server (only a user name and server).
The option flags will be set to either CRYPT_KEYOPT_NONE or CRYPT_KEYOPT_READONLY, many servers can optimise accesses if they know that no
updates will be performed so your code should try and communicate this to the server
if possible. The function should return a set of database feature flags indicating its
capabilities in the featureFlags parameter. These will be either DBMS_HAS_BINARYBLOBS if the database can store binary data blobs rather than requiring that
data be base64-encoded, and DBMS_HAS_NONE if it has no special capabilities.
The plugin should provide binary blob access if the database supports this (almost all
do) since this increases data handling efficiency and reduces storage requirements.
static void closeDatabase( DBMS_STATE_INFO *dbmsInfo )

This function is called to shut down the session with the database.
static int performUpdate( DBMS_STATE_INFO *dbmsInfo, const char
*command, const void *boundData, const int boundDataLength, const
time_t boundDate, const DBMS_UPDATE_TYPE updateType )

This function is called to send data to the database. The parameters are an SQL
command, optional binary blob data and a date, and an update type indicator that
indicates which type of update is being performed. If the boundData value is nonnull then this parameter and the boundDataLength contain a binary blob which is
to be added as part of the SQL command. If the boundDate value is nonzero then
this parameter contains the date and time which is to be added as part of the SQL
command as an SQL DATETIME value. For example the function can be called
with:
performUpdate( …, "'INSERT INTO certificates VALUES ( '…', '…', …
'…' )", NULL, 0, 0 );
performUpdate( …, "INSERT INTO certificates VALUES ( '…', '…', … ? )",
data, length, 0 );
performUpdate( …, "INSERT INTO certificates VALUES ( ?, '…', … ? )",
data, length, date );

In the first case all data is contained in the SQL command. In the second case there is
a binary data blob associated with the SQL command whose position is indicated by
t
he‘
?
’pl
a
c
e
hol
de
r
.Af
t
e
rs
e
n
di
ngt
heSQLc
omma
n
dt
ot
h
eda
t
a
ba
s
e
,
y
oua
l
s
on
e
e
d
to send the ( data, length ) value. In the third case there is a binary data blob and a
date value associated with the SQL command, with the positions again indicated by
t
he‘
?
’pl
a
c
e
hol
de
r
s
.Theda
t
ev
a
l
uei
sa
l
wa
y
sf
i
r
s
ti
nt
hes
e
qu
e
nc
eo
fpl
a
c
e
h
ol
de
r
s
,
and the data blob is always second (even if the data blob parameter appears before the
date parameter in the list of function parameters). After sending the SQL command
to the database, you also need to send the date and then the ( data, length ) values.
The date value needs to be converted into whatever format the database expects for a

The Database Plugin Interface

297

DATETIME value. The exact format depends on the database back-end, which is
whyi
t
’
sno
tpr
e
s
e
nti
nt
h
eSQLc
omma
n
d.
The update types are as follows:
Update Type

Description

DBMS_UPDATE_- Abort a transaction. This state is communicated to the
ABORT
database through an SQL statement such as ABORT
TRANSACTION or ROLLBACK or ABORT, or via a
function call that indicates that the transaction begun
earlier should be aborted or rolled back.
DBMS_UPDATE_- Begin a transaction. This state is communicated to the
BEGIN
database through an SQL statement such as BEGIN
TRANSACTION or BEGIN WORK or BEGIN, or via
a function call that indicates that transaction semantics
are in effect for the following SQL statements.
DBMS_UPDATE_- Commit a transaction. This state is communicated to
COMMIT
the database through an SQL statement such as END
TRANSACTION or COMMIT WORK or COMMIT,
or via a function call that indicates that the transaction
should be committed and that transaction semantics are
no longer in effect after the statement has been
submitted.
DBMS_UPDATE_- Continue an ongoing transaction.
CONTINUE
DBMS_UPDATE_- Standard data update.
NORMAL
The DBMS_UPDATE_BEGIN/CONTINUE/COMMIT combination is used to
perform an atomic update on the database. The sequence of calls is as follows:
performUpdate( …, "INSERT INTO certificates VALUES ( … )",
certificate, certLength, certDate, DBMS_UPDATE_BEGIN );
performUpdate( …, "INSERT INTO certLog VALUES ( … )", certificate,
certLength, currentDate, DBMS_UPDATE_CONTINUE );
performUpdate( …, "DELETE FROM certRequests WHERE keyID = keyID",
NULL, 0, 0, DBMS_UPDATE_COMMIT );

The first call begins the transaction and submits the initial portion, the ongoing calls
submit successive portions of the transaction, and the final call submits the last
por
t
i
ona
ndc
o
mmi
t
st
het
r
a
ns
a
c
t
i
on.I
ft
he
r
e
’
sapr
ob
l
e
m,
t
hel
a
s
tc
a
l
li
nt
he
t
r
a
ns
a
c
t
i
onwi
l
lus
ea
nup
da
t
et
y
peofDBMS_UPDATE_ABORT.Not
et
ha
ti
t
’
s
important to ensure that performUpdate i
t
s
e
l
fi
sa
t
o
mi
c
,
f
o
re
x
a
mpl
ei
ft
he
r
e
’
sa
n
error inside the function then it needs to back out of the transaction (if one is in
progress) rather than simply returning immediately to the caller. This requires careful
tracking of the state of the transaction and handling of error conditions.
static int performQuery( DBMS_STATE_INFO *dbmsInfo, const char
*command, char *data, int *dataLength, const char *boundData, const
int boundDataLength, time_t boundDate, const DBMS_CACHEDQUERY_TYPE
queryEntry, const DBMS_QUERY_TYPE queryType )

This function is called to fetch data from the database. The parameters are an SQL
command, an optional buffer to store the result, optional bound query data and date
parameters, a query cacheing indicator (explained further on) and a query type
indicator that indicates which type of query is being performed. The query types are
as follows:
Query Type

Description

DBMS_QUERY_- Cancel an ongoing query. This terminates an ongoing
CANCEL
query begun by sending a DBMS_QUERY_START
query.

298

Database and Networking Plugins

Query Type

Description

DBMS_QUERY_- Cancel an ongoing query. This terminates an ongoing
CANCEL
query begun by sending a DBMS_QUERY_START
query.
DBMS_QUERY_- Perform a presence check that simply returns a
CHECK
present/not present indication without returning any
data. This allows the query to be optimised since
t
he
r
e
’
snone
e
dt
oa
c
t
ua
l
l
yf
e
t
c
ha
nyda
t
af
r
omt
he
back-e
n
d.Al
lt
ha
t
’
sn
e
c
e
s
s
a
r
yi
st
ha
tas
t
a
t
us
indication be returned that indicates whether the
requested data is available to be fetched or not.
DBMS_QUERY_- Continue a previous ongoing query. This returns the
CONTINUE
next entry in the result set generated by sending a
DBMS_QUERY_START query.
DBMS_QUERY_- Standard data fetch.
NORMAL
DBMS_QUERY_- Begin an ongoing query. This submits a query to the
START
back-end without returning any data. The result set is
read one entry at a time by sending
DBMS_QUERY_CONTINUE messages.
The DBMS_QUERY_START/CONTINUE/CANCEL combination is used to fetch a
collection of entries from the database. The sequence of calls is as follows:
performQuery( …, "SELECT certData FROM certificates WHERE key = ?",
NULL, NULL, boundData, boundDataLength, 0, DBMS_CACHEDQUERY_NONE,
DBMS_QUERY_START );
do
status = performQuery( …, NULL, buffer, &length, NULL, 0, 0,
DBMS_CACHEDQUERY_NONE, DBMS_QUERY_CONTINUE );
while( cryptStatusOK( status ) );

The first call submits the query and the ongoing calls fetch successive entries in the
result set until an error status is returned (usually this is CRYPT_ERROR_COMPLETE to indicate that there are no more entries in the result set).
In order to allow for more efficient execution of common queries, cryptlib allows
them to be cached by the database back-end for re-use in the future. This allows the
back-end to perform the task of SQL parsing and validation against the system
catalog, query optimisation, and access plan generation just once when the first query
is executed rather than having to re-do it for each query. cryptlib provides hints about
cached queries by specifying a cache entry number when it submits the query.
Uncached queries are given an entry number of DBMS_CACHEDQUERY_NONE
(these will be little-us
e
dq
ue
r
yt
y
pe
st
ha
ti
t
’
snotwor
t
hc
a
c
he
i
ng
)
,que
r
i
e
swhe
r
e
cacheing are worthwhile are given an entry number from 1 to 5. The submitted SQL
f
ort
he
s
eq
ue
r
i
e
swi
l
lne
v
e
rc
ha
ng
eov
e
rs
ubs
e
q
ue
n
tc
a
l
l
s
,
s
oi
t
’
son
l
yne
c
e
s
s
a
r
yt
o
perform the parsing and processing once when the query is submitted for the first
time. Any subsequent requests can be satisfied using the previously parsed query
held at the back-end. In the above example, if the query were submitted with a
cacheing indicator of DBMS_CACHEDQUERY_URI, you could prepare a query for
"SELECT certData FROM certificates WHERE uri = ?" the first
time that the query is submitted and then re-use the prepared query every time
another query with the cacheing indicator DBMS_CACHEDQUERY_URI is used.
Note that some databases may return a (potentially large) result set in response to a
query for a single result using DBMS_QUERY_NORMAL, for example by returning
further results after the first one is read or by disallowing further queries until all
results have been processed. In this case it will be necessary to limit the query
response size either by setting a size limit before submitting the query or by explicitly
cancelling a query if more than one result is returned. In addition since cryptlib
expects all data to be SQL text strings (or binary data for certificates if the database

The Network Plugin Interface

299

supports it) you may need to convert some data types such as integer values to text
equivalents when returning them in response to a query.
static void performErrorQuery( DBMS_STATE_INFO *dbmsInfo, int
*errorCode, char *errorMessage )

This function is called to return extended error information when an error occurs.
Whenever either performQuery() or performUpdate() return an error status, this
function will be called to obtain further information. The information returned is
specific to the database back-end and can include the back-end-specific error code
a
ndat
e
x
ts
t
r
i
ngde
s
c
r
i
bi
ngt
hee
r
r
or
.I
ft
hi
si
n
f
or
ma
t
i
o
ni
s
n’
ta
v
a
i
l
a
bl
e
,
y
ous
ho
ul
d
leave it empty.
An example of a plugin interface is keyset/odbc.c, which implements the full
functionality required by cryptlib, a somewhat simpler interface for a database that
doe
s
n’
ts
up
por
tbi
na
r
ybl
o
bsi
skeyset/mysql.c. In addition to the standard functions
included below, you may also need to include an SQL rewrite function that changes
the contents of SQL queries to match the SQL dialect used by your database. This is
a simple function that just substitutes one text string in the query for another. The
most common conversion changes the name of the binary blob type (if the database
supports it) from the built-in “BLOB”to whatever value is required by the database.
Again, see keyset/odbc.c or keyset/mysql.c for an example of the SQL rewrite
process.

The Network Plugin Interface
The network plugin interface is used to provide a transport-layer service to the
higher-level cryptlib protocols that require network access capabilities. Network
management is handled by the cryptlib I/O streams module stream.c. The stream
I/O system implements a multi-layer architecture with the transport-layer service in
the lowest layer, optional I/O buffering layered above that, optional application-layer
handling (for example HTTP) above that, and finally the cryptlib protocols such as
CMP, RTCS, SCEP, OCSP and TSP above that. Other protocols such as SSH and
SSL,
whi
c
hdo
n’
tr
e
qu
i
r
ea
nyoft
hei
n
t
e
r
me
d
i
a
t
el
a
y
e
r
s
,
t
a
l
kdi
r
e
c
t
l
yt
ot
het
r
a
ns
p
or
t
layer.
By replacing the transport-layer interface, you can run cryptlib communications over
any type of transport interface. Currently cryptlib provides two types of built-in
transport provider, a generic BSD sockets provider and a provider that uses a cryptlib
session as the transport layer, making it possible to run (for example) RTCS over SSL
or CMP over SSH. You can also use the plugin functionality to provide custom I/O
handling that goes beyond that provided by the standard sockets-based interface. For
example if you need to use event-based I/O or OS-specific mechanisms such as I/O
completion ports, you can provide this capability through the use of custom I/O
handlers in the network plugin interface.
The network plugin interface is handled through function pointers to the various
transport-layer functions. By setting these to point to functions in the appropriate
pl
ug
i
ns
,
i
t
’
spos
s
i
bl
et
ous
ea
nyt
y
peofne
t
wor
k
i
ngorc
ommu
ni
c
a
t
i
o
nsi
n
t
e
r
f
a
c
ef
or
the transport layer. To set these pointers, the cryptlib I/O stream system calls
setAccessMethodXXX(), which in the case of BSD sockets is
setAccessMethodTCP().
When calling a transport-layer interface function, cryptlib passes in a STREAM
structure which is defined in stream.h. This contains information which is required
by the transport layer such as socket handles and network communications timeout
information.

Network Plugin Functions
The network plugin functions that you need to provide are as follows:
static BOOLEAN transportOKFunction( void )

This function is called before using any transport-layer functions to query whether the
transport layer is OK. I
ts
houl
dr
e
t
ur
nTRUEi
fi
t
’
ss
a
f
et
oc
a
l
lt
heo
t
h
e
rt
r
a
ns
p
or
t
-

300

Database and Networking Plugins

layer functions or FALSE otherwise, for example because the requested network
i
nt
e
r
f
a
c
edr
i
v
e
r
sa
r
e
n
’
tl
oa
d
e
d
.
static int transportConnectFunction( STREAM *stream, const char
*server, const int port )

This functions is called to established a connection, either by connecting to a remote
system or by waiting for a connection from a remote system (the exact type depends
on whether the stream is acting as a client or server stream). The server parameter
is the name of the local interface or remote server, and the port parameter is the port
number to listen on or connect to.
static void transportDisconnectFunction( STREAM *stream )

This function is called to shut down a connection with a remote client or server.
static int transportReadFunction( STREAM *stream, BYTE *buffer, const
int length, const int flags )

This function is called to read data from a remote client or server. The behaviour of
this function differs slightly depending on read timeout handling. For blocking reads,
it should read as many bytes as are indicated in the length parameter, returning an
error if less bytes are read. For nonblocking reads it should read as many bytes as are
available (which may be zero) and return. In either case if the read succeeds it returns
a byte count.
Normally the read should wait for data to appear for the number of seconds indicated
byt
het
i
me
o
utv
a
l
u
es
t
or
e
di
nt
hes
t
r
e
a
mI
/
Os
t
r
uc
t
ur
e
.Howe
v
e
r
,
i
t
’
spos
s
i
bl
et
o
override this with the flags parameter, which can contain the following flags:
Flag

Description

TRANSPORT_FLAG_NONBLOCKING

Perform a nonblocking read, overriding the
timeout value in the stream I/O structure if
necessary.

TRANSPORT_FLAG_BLOCKING

Perform a blocking read, overriding the timeout
value in the stream I/O structure if necessary.

The
s
ef
l
a
g
sa
r
eus
e
di
nc
a
s
e
swhe
r
ei
t
’
sk
nownt
h
a
tac
e
r
t
a
i
nnu
mbe
ro
fby
t
e
smus
tbe
read in order to continue, or when the higher-level stream buffering functions want to
perform a speculative read-ahead.
static int transportWriteFunction( STREAM *stream, const BYTE *buffer,
const int length, const int flags )

This function is used to write data to a remote client or server. The flags parameter is
currently unused and should be set to TRANSPORT_FLAG_NONE.

The Crypto Plugin Interface
Thec
r
y
pt
opl
ug
i
ni
nt
e
r
f
a
c
ei
sus
e
dt
or
e
pl
a
c
eors
u
ppl
e
me
n
tc
r
y
pt
l
i
b’
sbu
i
l
t
-in
encryption capabilities with external implementations such as crypto hardware or
dedicated crypto cores. When cryptlib initialises itself, it calls a sequence of
encryption capability initialisation functions declared in device/system.c, which
return information on each encryption capability available to cryptlib. This capability
information is returned in a CAPABILITY_INFO structure, defined in
device/capabil.h, that contains details such as the algorithm name, block size, key
size details, and a set of function pointers to the interface for the algorithm. For
example one of these would point to the function to load a key (if the algorithm uses
k
e
y
s
)
,onet
ot
hef
u
nc
t
i
o
nt
oe
nc
r
y
ptda
t
a(
i
fi
t
’
sa
ne
nc
r
y
pt
i
ona
l
g
or
i
t
h
m)
,
a
n
ds
oo
n.
For a software implementation, the encryption function would simply constitute the
encryption algorithm. For a hardware implementation, the encryption function would
pass the data on to the encryption hardware for processing.
The get-capability function is the only externally visible interface to an encryption
capability. The easiest way to understand the interface is by looking at an example.
If you look in the context d
i
r
e
c
t
or
yy
ou’
l
lf
i
n
dt
hei
mp
l
e
me
nt
a
t
i
o
nsf
ora
l
lof
c
r
y
pt
l
i
b’
sb
ui
l
t
-in capabilities. Take as an example the DES capability

The Crypto Plugin Interface

301

implementation, implemented in context/ctx_des.c. The getDESCapability()
function simply returns a pointer to the initialised CAPABILITY_INFO structure
containing algorithm information and function pointers for each of the DES
capabilities. This is the simplest case, in more sophisticated implementations you
could (for example) check for the presence of encryption hardware and return an
appropriate CAPABILITY_INFO structure for the hardware instead of the software
implementation, or vary the algorithm parameters based on what your implementation
is capable of. You can even implement completely new (and/or proprietary)
algorithms in this manner.
Toa
d
ds
up
por
tf
ory
ourowni
mpl
e
me
nt
a
t
i
o
n,
i
t
’
se
a
s
i
e
s
tt
ous
eoneoft
he
context/ctx_xxx.c modules as a template for your implementation, and replace the
code in the module with your own code or the interface to the crypto hardware or
c
r
y
pt
oc
or
e
.I
fy
ou
’
r
er
e
pl
a
c
i
ngabui
l
t
-in algorithm (rather than adding a new one),
you can retain some of the existing functions such as the selfTest() function,
since these function independently of the underlying implementation.

302

Algorithms

Algorithms
This chapter describes the characteristics of each algorithm used in cryptlib and any
k
nownr
e
s
t
r
i
c
t
i
o
nsont
he
i
rus
e
.Si
nc
ec
r
y
pt
l
i
bor
i
g
i
na
t
e
si
nac
ou
nt
r
yt
ha
tdoe
s
n
’
t
allow software patents, there are no patent restrictions on the code in its country of
origin. Known restrictions in other countries are listed below and all possible care
has been taken to ensure that no other infringing technology is incorporated into the
code, however since the author is a cryptographer and not an IP lawyer users are
urged to consult IP lawyers in the country of intended use if they have any concerns
over potential restrictions.

AES
AES is a 128-bit block cipher with a 128-bit key and has the cryptlib algorithm
identifier CRYPT_ALGO_AES.

Blowfish
Blowfish is a 64-bit block cipher with a 448-bit key and has the cryptlib algorithm
identifier CRYPT_ALGO_BLOWFISH.

CAST-128
CAST-128 is a 64-bit block cipher with a 128-bit key and has the cryptlib algorithm
identifier CRYPT_ALGO_CAST.

DES
DES is a 64-bit block cipher with a 56-bit key and has the cryptlib algorithm
identifier CRYPT_ALGO_DES. Note that this algorithm is no longer considered
secure and should not be used. It is present in cryptlib only for compatibility with
legacy applications.
Although cryptlib uses 64-bit DES keys, only 56 bits of the key are actually used.
The least significant bit in each byte is used as a parity bit (cryptlib will set the
c
or
r
e
c
tp
a
r
i
t
yv
a
l
ue
sf
ory
ou,
s
oy
oudo
n
’
th
a
v
et
owor
r
ya
boutt
hi
s
)
.Youc
a
nt
r
e
a
t
the algorithm as having a 64-bit key, but bear in mind that only the high 7 bits of each
byte are actually used as keying material.
Loading a key will return a CRYPT_ERROR_PARAM3 error if the key is a weak
key. cryptExportKey will export the correct parity-adjusted version of the key.

Triple DES
Triple DES is a 64-bit block cipher with a 112/168-bit key and has the cryptlib
algorithm identifier CRYPT_ALGO_3DES.
Although cryptlib uses 128, or 192-bit DES keys (depending on whether two- or
three-key triple DES is being used), only 112 or 168 bits of the key are actually used.
The least significant bit in each byte is used as a parity bit (cryptlib will set the
c
or
r
e
c
tp
a
r
i
t
yv
a
l
ue
sf
ory
ou,
s
oy
oudo
n
’
th
a
v
et
owor
r
ya
boutt
hi
s
)
.Youc
a
nt
r
e
a
t
the algorithm as having a 128 or 192-bit key, but bear in mind that only the high 7
bits of each byte are actually used as keying material.
Loading a key will return a CRYPT_ERROR_PARAM3 error if the key is a weak
key. cryptExportKey will export the correct parity-adjusted version of the key.

Diffie-Hellman
Diffie-Hellman is a key exchange algorithm with a key size of up to 4096 bits and has
the cryptlib algorithm identifier CRYPT_ALGO_DH.
Diffie-Hellman was formerly covered by a patent in the US, this has now expired.

DSA

303

DSA
DSA is a digital signature algorithm with a key size of up to 1024 bits and has the
cryptlib algorithm identifier CRYPT_ALGO_DSA.
DSA is covered by US patent 5,231,668, with the patent held by the US government.
This patent has been made available royalty-free to all users world-wide. The US
Department of Commerce is not aware of any other patents that would be infringed
byt
heDSA.USpa
t
e
nt4,
99
5
,
082,
“
Me
t
ho
df
ori
de
nt
i
f
y
i
ngs
ubs
c
r
i
b
e
r
sa
ndf
or
g
e
ne
r
a
t
i
nga
ndv
e
r
i
f
y
i
nge
l
e
c
t
r
oni
cs
i
g
na
t
ur
e
si
nad
a
t
ae
x
c
ha
ng
es
y
s
t
e
m”(
“
t
he
Schnor
rpa
t
e
nt
”
)r
e
l
a
t
e
st
ot
heDSAa
l
g
or
i
t
hm b
uto
nl
ya
p
pl
i
e
st
oav
e
r
yr
e
s
t
r
i
c
t
e
ds
e
t
of smart-card based applications and does not affect the DSA implementation in
cryptlib.

Elgamal
Elgamal is a public-key encryption/digital signature algorithm with a key size of up to
4096 bits and has the cryptlib algorithm identifier CRYPT_ALGO_ELGAMAL.
Elgamal was formerly covered (indirectly) by a patent in the US, this has now
expired.

HMAC-MD5
HMAC-SHA1
HMAC-RIPEMD-160
HMAC-MD5, HMAC-SHA1, and HMAC-RIPEMD-160 are MAC algorithms with a
key size of up to 1024 bits and have the cryptlib algorithm identifiers
CRYPT_ALGO_HMAC_MD5, CRYPT_ALGO_HMAC_SHA, and
CRYPT_ALGO_HMAC_RIPEMD160.

IDEA
IDEA is a 64-bit block cipher with a 128-bit key and has the cryptlib algorithm
identifier CRYPT_ALGO_IDEA.
IDEA is covered by patents in Austria, France, Germany, Italy, Japan, the
Netherlands, Spain, Sweden, Switzerland, the UK, and the US. A statement from the
patent owners is included below.
IDEA Patent Notice
IDEA is protected by International copyright law and in addition has been patented
in the USA, several countries in Europe (Austria, France, Germany, Italy,
Netherlands, Spain, Sweden, Switzerland, United Kingdom), and filed in Japan.
Ascom Systec Ltd., 5506 Mägenwil, Switzerland, holds the patent rights.
MediaCrypt AG, 8005 Zurich, Switzerland holds all the relevant rights from Ascom
related to the worldwide licensing of the IDEA algorithm.
Any use of the algorithm for Commercial Purposes is subject to a license from
MediaCrypt AG and any misuse of the algorithm will be prosecuted.
Commercial Purposes shall mean any revenue generating purpose including but not
limited to
(i)

using the algorithm for company internal purposes

(ii)
incorporating an application software containing the algorithm into any
hardware and/ or software and distributing such hardware and/or software and/or
providing services related thereto to others
(iii) using a product containing an application software that uses the algorithm
not covered by an IDEA license
Free use for private purposes:

304

Algorithms

The free use of software and/or hardware containing the algorithm is strictly limited
to non revenue generating data transfer between private individuals, i.e., not serving
commercial purposes. Requests by freeware developers to obtain a royalty-free
license to spread an application program containing the algorithm not for
commercial purposes must be directed to MediaCrypt.
Special offer for shareware developers:
Selling any software and/or hardware containing the algorithm is subject to a
product license. However, there is a special waiver for shareware developers. Such
waiver eliminates the up front fees as well as royalties for the first USD 10,000
gross sales of the product containing the algorithm, if and only if:
1)
The product is being sold for a minimum of USD 10.00 and a maximum of
USD 50.00.
2)
The source code for the shareware product is available to the public. Beyond
USD 10,000 gross sales from the shareware product the standard terms and
conditions for product licenses shall apply.

MD2
MD2 is a message digest/hash algorithm with a digest/hash size of 128 bits and has
the cryptlib algorithm identifier CRYPT_ALGO_MD2. Although no weaknesses
have been found in this algorithm, it should not be used any more except for legacy
application support.

MD4
MD4 is a message digest/hash algorithm with a digest/hash size of 128 bits and has
the cryptlib algorithm identifier CRYPT_ALGO_MD4. Note that this algorithm is no
longer considered secure and should not be used. It is present in cryptlib only for
compatibility with legacy applications.

MD5
MD5 is a message digest/hash algorithm with a digest/hash size of 128 bits and has
the cryptlib algorithm identifier CRYPT_ALGO_MD5. Note that this algorithm is no
longer considered secure and should not be used. It is present in cryptlib only for
compatibility with legacy applications.

RC2
RC2 is a 64-bit block cipher with a 1024-bit key and has the cryptlib algorithm
identifier CRYPT_ALGO_RC2. Although no weaknesses have been found in this
algorithm, it should not be used any more except for legacy application support.
Thet
e
r
m“
RC2”i
st
r
a
de
ma
r
k
e
di
nt
heUS.I
tma
ybene
c
e
s
s
a
r
yt
or
e
f
e
rt
oi
ta
s“
a
n
a
l
g
or
i
t
h
mc
o
mp
a
t
i
bl
ewi
t
hRC2”i
npr
o
duc
t
st
h
a
tus
eRC2a
nda
r
edi
s
t
r
i
bu
t
e
di
nt
he
US.

RC4
RC4 is an 8-bit stream cipher with a key of up to 1024 bits and has the cryptlib
algorithm identifier CRYPT_ALGO_RC4.
Thet
e
r
m“
RC4”i
st
r
a
de
ma
r
k
e
di
nt
heUS.I
tma
ybene
c
e
s
s
a
r
yt
or
e
f
e
rt
oi
ta
s“
a
n
a
l
g
or
i
t
h
mc
o
mp
a
t
i
bl
ewi
t
hRC4”i
npr
o
duc
t
st
hat use RC4 and are distributed in the
US. Common practice is to refer to it as ArcFour.

RC5
RC5 is a 64-bit block cipher with an 832-bit key and has the cryptlib algorithm
identifier CRYPT_ALGO_RC5.
RC5i
sc
ov
e
r
e
dbyUSpa
t
e
n
t5,
72
4,
42
8,
“
Bl
oc
kEnc
r
y
pt
i
o
n Algorithm with DataDe
pe
n
de
n
tRo
t
a
t
i
o
n”
,
i
s
s
u
e
d3Ma
r
c
h19
98.Thepa
t
e
nti
she
l
dbyRSADa
t
aSe
c
ur
i
t
y

RIPEMD-160

305

Inc. 100 Marine Parkway, Redwood City, California 94065, ph.+1 415 595-8782, fax
+1 415 595-1873, and the algorithm cannot be used commercially in the US without a
license.

RIPEMD-160
RIPEMD-160 is a message digest/hash algorithm with a digest/hash size of 160 bits
and has the cryptlib algorithm identifier CRYPT_ALGO_RIPEMD160.

RSA
RSA is a public-key encryption/digital signature algorithm with a key size of up to
4096 bits and has the cryptlib algorithm identifier CRYPT_ALGO_RSA.
RSA was formerly covered by a patent in the US, this has now expired.

SHA
SHA is a message digest/hash algorithm with a digest/hash size of 160 bits and has
the cryptlib algorithm identifier CRYPT_ALGO_SHA.

Skipjack
Skipjack is a 64-bit block cipher with an 80-bit key and has the cryptlib algorithm
identifier CRYPT_ALGO_SKIPJACK. Although no weaknesses have been found in
this algorithm, it should not be used any more except for legacy application support.

306

Data Types and Constants

Data Types and Constants
This section describes the data types and constants used by cryptlib.

CRYPT_ALGO_TYPE
The CRYPT_ALGO_TYPE is used to identify a particular encryption algorithm.
More information on the individual algorit
h
mt
y
pe
sc
a
nbef
ou
ndi
n“
Algorithms”o
n
page 282.
Value

Description

CRYPT_ALGO_AES

AES

CRYPT_ALGO_BLOWFISH

Blowfish

CRYPT_ALGO_CAST

CAST-128

CRYPT_ALGO_DES

DES. This algorithm is no longer
considered secure and should not
be used except for legacy
application support.

CRYPT_ALGO_3DES

Triple DES

CRYPT_ALGO_IDEA

IDEA

CRYPT_ALGO_RC2

RC2. Although no weaknesses
have been found in this algorithm,
it should not be used any more
except for legacy application
support.

CRYPT_ALGO_RC4

RC4

CRYPT_ALGO_RC5

RC5

CRYPT_ALGO_SKIPJACK

Skipjack. Although no
weaknesses have been found in
this algorithm, it should not be
used any more except for legacy
application support.

CRYPT_ALGO_DH

Diffie-Hellman

CRYPT_ALGO_DSA

DSA

CRYPT_ALGO_ELGAMAL

Elgamal

CRYPT_ALGO_RSA

RSA

CRYPT_ALGO_MD2

MD2. Although no weaknesses
have been found in this algorithm,
it should not be used any more
except for legacy application
support.

CRYPT_ALGO_MD4

MD4. This algorithm is no longer
considered secure and should not
be used except for legacy
application support.

CRYPT_ALGO_MD5

MD5. This algorithm is no longer
considered secure and should not
be used except for legacy
application support.

CRYPT_ATTRIBUTE_TYPE

Value
CRYPT_ALGO_RIPEMD160

Description
RIPE-MD 160

CRYPT_ALGO_SHA

SHA/SHA-1

CRYPT_ALGO_SHA2

SHA2/SHA-256/SHA-384/SHA512

CRYPT_ALGO_HMAC_MD5

HMAC-MD5

CRYPT_ALGO_HMAC_RIPEMD160

HMAC-RIPEMD-160

CRYPT_ALGO_HMAC_SHA

HMAC-SHA

CRYPT_ALGO_VENDOR1
CRYPT_ALGO_VENDOR2
CRYPT_ALGO_VENDOR3

Optional vendor-defined
algorithms.

CRYPT_ALGO_FIRST_CONVENTIONAL
CRYPT_ALGO_LAST_CONVENTIONAL

First and last possible
conventional encryption algorithm
type.

CRYPT_ALGO_FIRST_PKC
CRYPT_ALGO_LAST_PKC

First and last possible public-key
algorithm type.

CRYPT_ALGO_FIRST_HASH
CRYPT_ALGO_LAST_HASH

First and last possible hash
algorithm type.

CRYPT_ALGO_FIRST_MAC
CRYPT_ALGO_LAST_MAC

First and last possible MAC
algorithm type.

307

CRYPT_ATTRIBUTE_TYPE
The CRYPT_ATTRIBUTE_TYPE is used to identify the attribute associated with a
cryptlib object. Obj
e
c
ta
t
t
r
i
b
ut
e
sa
r
ei
nt
r
o
du
c
e
di
n“
Working with Object Attributes”
on page 33 and are used extensively throughout this manual.

CRYPT_CERTFORMAT_TYPE
The CRYPT_CERTFORMAT_TYPE is used to specify the format for exported
certificate objects. More information on exporting certificate objects is given in
“
Importing/Exporting Certificates”o
npa
g
e221.
Value

Description

CRYPT_CERTFORMAT_CERTCHAIN

Certificate object encoded as a PKCS
#7 certificate chain. This encoding is
only possible for objects that are
certificates or certificate chains.

CRYPT_CERTFORMAT_CERTIFICATE

Certificate object encoded according
to the ASN.1 distinguished encoding
rules (DER).

CRYPT_CERTFORMAT_TEXT_CERTCHAIN
CRYPT_CERTFORMAT_TEXT_CERTIFICATE

Base64-encoded text format. The
certificate object is encoded as for the
basic CRYPT_CERTFORMAT_type
format, and an extra layer of base64
encoding with BEGIN/END
CERTIFICATE tags is added. This
format is required by some web
browsers and applications.

308

Data Types and Constants

CRYPT_CERTTYPE_TYPE
The CRYPT_CERTTYPE_TYPE is used to specify the type of a certificate object
when used with cryptCreateCert. More information on certificates and certificate
objectsi
sg
i
v
e
ni
n“
Certificates and Certificate Management”o
npa
g
e149.
Value

Description

CRYPT_CERTTYPE_ATTRIBUTE_CERT

Attribute certificate.

CRYPT_CERTTYPE_CERTCHAIN PKCS #7 certificate chain.
CRYPT_CERTTYPE_CERTIFICATE

Certificate.

CRYPT_CERTTYPE_CERTREQUEST

PKCS #10 certification request.

CRYPT_CERTTYPE_CMS_ATTRIBUTES

PKCS #7/CMS attributes.

CRYPT_CERTTYPE_CRL

CRL

CRYPT_CERTTYPE_OCSP_REQUEST
CRYPT_CERTTYPE_OCSP_RESPONSE

OCSP request and response.

CRYPT_CERTTYPE_RTCS_REQUEST
CRYPT_CERTTYPE_RTCS_RESPONSE

RTCS request and response.

CRYPT_CERTTYPE_PKIUSER

PKI user information.

CRYPT_CERTTYPE_REQUEST_- CRMF certificate request/revocation
CERT
request.
CRYPT_CERTTYPE_REQUEST_REVOCATION

CRYPT_DEVICE_TYPE
The CRYPT_DEVICE_TYPE is used to specify encryption hardware or an
encryption device such as a PCMCIA or smart card. More information on encryption
de
v
i
c
e
si
sg
i
v
e
ni
n“
Encryption Devices and Modules”onpage 265.
Value

Description

CRYPT_DEVICE_FORTEZZA

Fortezza card.

CRYPT_DEVICE_PKCS11

PKCS #11 crypto token.

CRYPT_FORMAT_TYPE
The CRYPT_FORMAT_TYPE is used to identify a data format type for exported
keys, signatures, and encryption envelopes. Of the formats supported by cryptlib, the
cryptlib native format is the most flexible and is the recommended format unless you
require compatibility with a specific security standard. More information on the
different formats is given in “
Data Enveloping”onpa
g
e60,
“
Exchanging Keys”on
page 193,
a
n
d“
Signing Data”onpa
g
e199.
Value

Description

CRYPT_FORMAT_CRYPTLIB

cryptlib native format.

CRYPT_FORMAT_PGP

PGP format.

CRYPT_KEYID_TYPE

Value
CRYPT_FORMAT_CMS
CRYPT_FORMAT_PKCS7

Description
PKCS #7/CMS format.

CRYPT_FORMAT_SMIME

As CMS but with S/MIMEspecific behaviour.

309

CRYPT_KEYID_TYPE
The CRYPT_KEYID_TYPE is used to identify the type of key identifier which is
being passed to cryptGetPublicKey or cryptGetPrivateKey. More information on
us
i
ngt
he
s
ef
un
c
t
i
onst
or
e
a
dk
e
y
sf
r
om k
e
y
s
e
t
si
sg
i
v
e
ni
n“
Reading a Key from a
Keyset”onp
a
g
e141
Value

Description

CRYPT_KEYID_NAME

The name of the key owner.

CRYPT_KEYID_EMAIL

The email address of the key
owner.

CRYPT_KEYOPT_TYPE
The CRYPT_KEYOPT_TYPE is used to contain keyset option flags passed to
cryptKeysetOpen. The keyset options may be used to optimise access to keysets by
enabling cryptlib to perform enhanced transaction management in cases where, for
example, read-only access to a database is desired. Because this can improve
performance when accessing the keyset, you should always specify whether you will
be using the keyset in a restricted access mode when you call cryptKeysetOpen.
More information on using these options when opening a connection to a keyset is
g
i
v
e
ni
n“
Creating/Destroying Keyset Objects”onpa
g
e134
Value

Description

CRYPT_KEYOPT_CREATE

Create a new keyset. This option is only
valid for writeable keyset types, which
includes keysets implemented as
databases and cryptlib key files.

CRYPT_KEYOPT_NONE

No special access options (this option
implies read/write access).

CRYPT_KEYOPT_READONLY Read-only keyset access. This option is
automatically enabled by cryptlib for
keyset types that have read-only
restrictions enforced by the nature of the
keyset, the operating system, or user
access rights.
Unless you specifically require write
access to the keyset, you should use this
option since it allows cryptlib to optimise
its buffering and access strategies for the
keyset.

CRYPT_KEYSET_TYPE
The CRYPT_KEYSET_TYPE is used to identify a keyset type (or, more specifically,
the format and access method used to access a keyset) when used with
cryptKeysetOpen. Some keyset types may be unavailable on some systems. More
inf
or
ma
t
i
o
nonk
e
y
s
e
tt
y
pe
si
sg
i
v
e
ni
n“
Keyset Types”onpa
g
e133.

310

Data Types and Constants

Value

Description

CRYPT_KEYSET_FILE

A flat-file keyset, either a cryptlib
key file or a PGP/OpenPGP key
ring.

CRYPT_KEYSET_HTTP

URL specifying the location of a
certificate or CRL.

CRYPT_KEYSET_LDAP

LDAP directory service.

CRYPT_KEYSET_PLUGIN
CRYPT_KEYSET_DATABASE
CRYPT_KEYSET_ODBC

Generic database network plugin.
Generic RDBMS interface.
Generic ODBC interface.

CRYPT_KEYSET_DATABASE_STORE
CRYPT_KEYSET_ODBC_STORE
CRYPT_KEYSET_PLUGIN_STORE

As for the basic keyset types, but
representing a certificate store for
use by a CA rather than a simple
keyset. The user who creates and
updates these keyset types must
be a CA user.

CRYPT_MODE_TYPE
The CRYPT_MODE_TYPE is used to identify a particular conventional encryption
mo
de
.Mor
ei
n
f
or
ma
t
i
o
nont
hei
n
di
v
i
dua
lmod
e
sc
a
nbef
o
undi
n“
Algorithms”o
n
page 282.
Value

Description

CRYPT_MODE_ECB

ECB

CRYPT_MODE_CBC

CBC

CRYPT_MODE_CFB

CFB

CRYPT_MODE_OFB

OFB

CRYPT_OBJECT_TYPE
The CRYPT_OBJECT_TYPE is used to identify the type of an exported key or
signature object that has been created with cryptExportKey or
cryptCreateSignature. More information on working with these objects is given in
“
Querying an Exported Key Object”onpa
g
e196,
a
n
d“
Querying a Signature Object”
on page 200.
Value

Description

CRYPT_OBJECT_ENCRYPTED_KEY Conventionally exported key
object.
CRYPT_OBJECT_KEYAGREEMENT Key agreement object.
CRYPT_OBJECT_PKCENCRYPTED_- Public-key exported key object.
KEY
CRYPT_OBJECT_SIGNATURE

Signature object.

CRYPT_SESSION_TYPE
The CRYPT_SESSION_TYPE is used to identify a secure session type when used
with cryptCreateSession.Mor
ei
n
f
or
ma
t
i
o
no
ns
e
s
s
i
o
nsi
sg
i
v
e
ni
n“
Secure
Sessions”onp
a
g
e105.
Value

Description

CRYPT_SESSION_CMP
CRYPT_SESSION_CMP_SERVER

CMP client/server session.

Data Size Constants

Value

Description

CRYPT_SESSION_CMP
CRYPT_SESSION_CMP_SERVER

CMP client/server session.

CRYPT_SESSION_OCSP
CRYPT_SESSION_OCSP_SERVER

OCSP client/server session.

CRYPT_SESSION_RTCS
CRYPT_SESSION_RTCS_SERVER

RTCS client/server session.

CRYPT_SESSION_SCEP
CRYPT_SESSION_SCEP_SERVER

SCEP client/server session.

CRYPT_SESSION_SSH
CRYPT_SESSION_SSH_SERVER

SSH client/server session.

CRYPT_SESSION_SSL
CRYPT_SESSION_SSL_SERVER

SSL client/server session.

CRYPT_SESSION_TSP
CRYPT_SESSION_TSP_SERVER

TSP client/server session.

311

Data Size Constants
The following values define various maximum lengths for data objects that are used
in cryptlib. These can be used for allocating memory to contain the objects, or as a
c
he
c
kt
oe
ns
ur
et
ha
ta
no
bj
e
c
ti
s
n’
tl
a
r
g
e
rt
ha
nt
h
ema
x
i
mu
ms
i
z
ea
l
l
owe
dbyc
r
y
pt
l
i
b.
Constant

Description

CRYPT_MAX_HASHSIZE

Maximum hash size in bytes.

CRYPT_MAX_IVSIZE

Maximum initialisation vector size in bytes.

CRYPT_MAX_KEYSIZE

Maximum conventional-encryption key size
in bytes.

CRYPT_MAX_PKCSIZE

Maximum public-key component size in
bytes. This value specifies the maximum
size of individual components, since
public/private keys are usually composed of
a number of components the overall size is
larger than this.

CRYPT_MAX_TEXTSIZE

Maximum size of a text string (e.g. a public
or private key owner name) in characters.
This defines the string size in characters
rather than bytes, so a Unicode string of size
CRYPT_MAX_TEXTSIZE could be twice
as long as an ASCII string of size
CRYPT_MAX_TEXTSIZE. This value
does not include the terminating null
character in C strings.

Miscellaneous Constants
The following values are used for various purposes by cryptlib, for example to
specify that default parameter values are to be used, that the given parameter is
unused and can be ignored, or that a special action should be taken in response to
seeing this parameter.
Constant

Description

CRYPT_KEYTYPE_PRIVATE
CRYPT_KEYTYPE_PUBLIC

Whether the key being passed to
cryptInitComponents()/
cryptSetComponent() is a

312

Data Types and Constants

Constant

Description
public or private key.

CRYPT_RANDOM_FASTPOLL
CRYPT_RANDOM_SLOWPOLL

The type of polling to perform to
update the internal random data pool.

CRYPT_UNUSED

A value indicating that this parameter
is unused and can be ignored.

CRYPT_USE_DEFAULT

A value indicating that the default
setting for this parameter should be
used.

CRYPT_OBJECT_INFO Structure

313

Data Structures
This section describes the data structures used by cryptlib.

CRYPT_OBJECT_INFO Structure
The CRYPT_OBJECT_INFO structure is used with cryptQueryObject to return
information about a data object created with cryptExportKey or
cryptCreateSignature. Some of the fields are only valid for certain algorithm and
mo
dec
o
mbi
na
t
i
o
ns
,
orf
ors
omet
y
p
e
sofda
t
aob
j
e
c
t
s
.I
ft
he
ydo
n’
ta
p
pl
yt
ot
he
given algorithm and mode or context, they will be set to CRYPT_ERROR, null, or
filled with zeroes as appropriate.
Field

Description

CRYPT_OBJECT_TYPE objectType Data object type.
CRYPT_ALGO_TYPE cryptAlgo
Encryption/signature algorithm.
CRYPT_MODE_TYPE cryptMode Encryption/signature mode.
CRYPT_ALGO_TYPE hashAlgo

The hash algorithm used to hash the
data if the data object is a signature
object.

unsigned char salt[ CRYPT_MAX_- The salt used to derive the
HASHSIZE ]
export/import key if the object is a
int saltLength
conventionally encrypted key object

CRYPT_PKCINFO_xxx Structures
The CRYPT_PKCINFO_xxx structures are used to load public and private keys
(which contain multiple key components) into encryption contexts by setting them as
the CRYPT_CTXINFO_KEY_COMPONENTS attribute. All fields are multiprecision integer values that are set using the cryptSetComponent() macro.
The CRYPT_PKCINFO_DLP structure is used to load keys for algorithms based on
the discrete logarithm problem, which includes keys for Diffie-Hellman, DSA, and
Elgamal. The structure contains the following fields:
Field

Description

Prime modulus.

Pr
i
med
i
v
i
s
or
.SomeDHa
ndEl
g
a
ma
lk
e
y
sdon’
tus
e
this parameter, in which case you should set it to an allzero value of the appropriate size. Note that omitting
t
heqpa
r
a
me
t
e
rme
a
nst
ha
tc
r
y
pt
l
i
bc
a
n
’
tpe
r
f
or
m
certain key validity checks that it otherwise performs
when q is present.

Element of order q mod p.

Private random integer.

Public random integer, gx mod p.

The CRYPT_PKCINFO_RSA structure is used to load RSA public-key encryption
keys and contains the following fields:
Field

Description

Modulus.

Public exponent.

Pr
i
v
a
t
ee
x
p
on
e
nt
.So
mek
e
y
sdon
’
ti
nc
l
u
det
hi
s
parameter, in which case you should set it to an all-zero
value of the appropriate size. Note that if the d

314

Data Structures

Field

Description
parameter is absent then the e1 and e2 values must be
present.

Prime factor 1.

Prime factor 2.

CRT coefficient q-1 mod p.

Private exponent 1 (PKCS #1), d mod (p-1).

Private exponent 2 (PKCS #1), d mod (q-1).

The e1 and e2 components of CRYPT_PKCINFO_RSA may not be present in some
keys. cryptlib will make use of them if they are present, but can also work without
t
he
m.Thel
oa
di
ngofpr
i
v
a
t
ek
e
y
si
ss
l
i
g
ht
l
ys
l
owe
ri
ft
he
s
ev
a
l
ue
sa
r
e
n
’
tpr
e
s
e
n
t
since cryptlib needs to generate them itself.

CRYPT_QUERY_INFO Structure
The CRYPT_QUERY_INFO structure is used with cryptQueryCapability to return
information about an encryption algorithm or an encryption context or key-related
certificate object (for example a public-key certificate or certification request). Some
of the fields are only valid for certain algorithm types, or for some types of
e
nc
r
y
pt
i
o
nc
o
nt
e
x
t
s
.I
ft
h
e
ydon
’
ta
ppl
yt
ot
h
eg
i
v
e
na
l
g
or
i
t
hmorc
on
t
e
x
t
,
t
h
e
ywi
l
l
be set to CRYPT_ERROR, null, or filled with zeroes as appropriate.
Field

Description

char algoName[ CRYPT_MAX_TEXTSIZE ]
int blockSize

Algorithm name.

int minKeySize
int keySize
int maxKeySize

The minimum, recommended, and
maximum key size in bytes (if the
algorithm uses a key).

Algorithm block size in bytes.

cryptAddCertExtension

315

Function Reference
cryptAddCertExtension
The cryptAddCertExtension function is used to add a generic blob-type certificate
extension to a certificate object.
int cryptAddCertExtension( const CRYPT_CERTIFICATE certificate, const char *oid, const int
criticalFlag, const void *extension, const int extensionLength );
Parameters

certificate
The certificate object to which to add the extension.
oid
The object identifier value for the extension being added, specified as a sequence of
integers.
criticalFlag
The critical flag for the extension being added.
extension
The address of the extension data.
extensionLength
The length in bytes of the extension data.

Remarks

cryptlib directly supports extensions from X.509, PKIX, SET, SigG, and various
v
e
ndor
si
t
s
e
l
f
,
s
oy
ous
h
oul
dn
’
tus
et
h
i
sf
u
nc
t
i
o
nf
ora
ny
t
hing other than unknown,
proprietary extensions.

See also

cryptGetCertExtension, cryptDeleteCertExtension.

cryptAddPrivateKey
The cryptAddPrivateKey f
u
nc
t
i
o
ni
sus
e
dt
oa
ddaus
e
r
’
spr
i
v
a
t
ek
e
yt
oak
e
y
s
e
t
.
int cryptAddPrivateKey( const CRYPT_KEYSET keyset, const CRYPT_HANDLE cryptKey,
const char *password );
Parameters

keyset
The keyset object to which to write the key.
cryptKey
The private key to write to the keyset.
password
The password used to encrypt the private key.

Remarks

The use of a password to encrypt the private key is required when storing a private
key to a keyset, but not to a crypto device such as a smart card or Fortezza card, since
these provide their own protection for the key data.

See also

cryptAddPublicKey, cryptDeleteKey, cryptGetPrivateKey, cryptGetPublicKey.

cryptAddPublicKey
The cryptAddPublicKey f
u
n
c
t
i
oni
sus
e
dt
oa
d
daus
e
r
’
sp
ubl
i
ck
e
yorc
e
r
t
i
f
i
c
a
t
et
o
a keyset.
int cryptAddPublicKey( const CRYPT_KEYSET keyset, const CRYPT_CERTIFICATE
certificate );
Parameters

keyset
The keyset object to which to write the key.

316

Function Reference

certificate
The certificate to add to the keyset.
Remarks

This function requires a key certificate object rather than an encryption context, since
the certificate contains additional identification information which is used when the
certificate is written to the keyset.

See also

cryptAddPrivateKey, cryptDeleteKey, cryptGetPrivateKey, cryptGetPublicKey.

cryptAddRandom
The cryptAddRandom function is used to add random data to the internal random
data pool maintained by cryptlib, or to tell cryptlib to poll the system for random
information. The random data pool is used to generate session keys and
public/private keys, and by several of the high-level cryptlib functions.
int cryptAddRandom( const void *randomData, const int randomDataLength );
Parameters

randomData
The address of the random data to be added, or null if cryptlib should poll the
system for random information.
randomDataLength
The length of the random data being added, or CRYPT_RANDOM_SLOWPOLL
to perform an in-depth, slow poll or CRYPT_RANDOM_FASTPOLL to perform a
less thorough but faster poll for random information.

cryptAsyncCancel
The cryptAsyncCancel function is used to cancel an asynchronous operation on an
object.
int cryptAsyncCancel( const CRYPT_HANDLE cryptObject );
Parameters

cryptObject
The object on which an asynchronous operation is to be cancelled.

Remarks

Because of the asynchronous nature of the operation being performed the cancel may
not take effect immediately. In the worst case it may take a second or two for the
cancel command to be processed by the object.

See also

cryptAsyncQuery, cryptGenerateKeyAsync.

cryptAsyncQuery
The cryptAsyncQuery function is used to obtain the status of an asynchronous
operation on an object.
int cryptAsyncQuery( const CRYPT_HANDLE cryptObject );
Parameters

cryptObject
The object to be queried.

Remarks

cryptAsyncQuery will return CRYPT_ERROR_TIMEOUT if an asynchronous
operation is in progress and the object is unavailable for use until the operation
completes.

See also

cryptAsyncCancel, cryptGenerateKeyAsync.

cryptCAAddItem
The cryptCAAddItem function is used to add a certificate object to a certificate
store. Usually this would be a standard certificate, however this function can be used
by CAs to add special items such as certificate requests and PKI user information.

cryptCACertManagement

317

int cryptCAAddItem( const CRYPT_KEYSET keyset, const CRYPT_CERTIFICATE certificate
);
Parameters

keyset
The certificate store to which the item will be added.
certificate
The item to add to the certificate store.

See also

cryptCACertManagement, cryptCAGetItem.

cryptCACertManagement
The cryptCACertManagement function is used to perform a CA certificate
management operation such as a certificate issue, revocation, CRL issue, certificate
expiry, or other operation with a certificate store.
int cryptCACertManagement( CRYPT_CERTIFICATE *cryptCert, const
CRYPT_CERTACTION_TYPE action, const CRYPT_KEYSET keyset, const
CRYPT_CONTEXT caKey, const CRYPT_CERTIFICATE certRequest );
Parameters

cryptCert
The address of the certificate object to be created.
action
The certificate management operation to perform.
keyset
The certificate store to use to perform the action.
caKey
The CA key to use when performing the action, or CRYPT_UNUSED if no key is
necessary for this action.
certRequest
The certificate request to use when performing the action, or CRYPT_UNUSED if
no request is necessary for this action.

See also

cryptCAAddItem, cryptCAGetItem.

cryptCAGetItem
The cryptCAGetItem function is used to read a certificate object from a certificate
store. Usually this would be a standard certificate, however this function can be used
by CAs to obtain special items such as certificate requests and PKI user information.
The item to be fetched is identified either through t
hek
e
yowne
r
’
sna
meort
he
i
r
email address.
int cryptCAGetItem( const CRYPT_KEYSET keyset, CRYPT_CERTIFICATE *certificate, const
CRYPT_CERTTYPE_TYPE certType, const CRYPT_KEYID_TYPE
keyIDtype, const void *keyID );
Parameters

keyset
The certificate store from which to obtain the item.
certificate
The address of the certificate object to be fetched.
certType
The item type.
keyIDtype
The type of the key ID, either CRYPT_KEYID_NAME for the name or key label,
or CRYPT_KEYID_EMAIL for the email address.
keyID
The key ID of the item to read.

318

Function Reference

See also

cryptCACertManagement, cryptCAAddItem.

cryptCheckCert
The cryptCheckCert function is used to check the signature on a certificate object,
or to verify a certificate object against a CRL or a keyset containing a CRL.
int cryptCheckCert( const CRYPT_CERTIFICATE certificate, const CRYPT_HANDLE
sigCheckKey );
Parameters

certificate
The certificate container object that contains the certificate item to check.
sigCheckKey
A public-key context or key certificate object containing the public key used to
verify the signature, or alternatively CRYPT_UNUSED if the certificate item is
self-signed. If the certificate is to be verified against a CRL, this should be a
certificate object or keyset containing the CRL. If the certificate is to be verified
online, this should be a session object for the server used to verify the certificate.

See also

cryptSignCert.

cryptCheckSignature
The cryptCheckSignature function is used to check the digital signature on a piece
of data.
int cryptCheckSignature( const void *signature, const int signatureLength, const
CRYPT_HANDLE sigCheckKey, const CRYPT_CONTEXT hashContext );
Parameters

signature
The address of a buffer that contains the signature.
signatureLength
The length in bytes of the signature data.
sigCheckKey
A public-key context or key certificate object containing the public key used to
verify the signature.
hashContext
A hash context containing the hash of the data.

See also

cryptCheckSignatureEx, cryptCreateSignature, cryptCreateSignatureEx,
cryptQueryObject.

cryptCheckSignatureEx
The cryptCheckSignatureEx function is used to check the digital signature on a
piece of data with extended control over the signature information.
int cryptCheckSignatureEx( const void *signature, const int signatureLength, const
CRYPT_HANDLE sigCheckKey, const CRYPT_CONTEXT hashContext,
CRYPT_HANDLE *extraData );
Parameters

cryptCreateCert

319

hashContext
A hash context containing the hash of the data.
extraData
The address of a certificate object containing extra information which is included
wi
t
ht
hes
i
g
na
t
ur
e
,
ornu
l
li
fy
oud
on
’
tr
e
qui
r
et
hi
si
n
f
or
ma
t
i
on.
See also

cryptCheckSignature, cryptCreateSignature, cryptCreateSignatureEx,
cryptQueryObject.

cryptCreateCert
The cryptCreateCert function is used to create a certificate object that contains a
certificate, certification request, certificate chain, CRL, or other certificate-like
object.
int cryptCreateCert( CRYPT_CERTIFICATE *cryptCert, const CRYPT_USER cryptUser, const
CRYPT_CERTTYPE_TYPE certType );
Parameters

cryptCert
The address of the certificate object to be created.
cryptUser
The user who is to own the certificate object or CRYPT_UNUSED for the default,
normal user.
certType
The type of certificate item that will be created in the certificate object.

See also

cryptDestroyCert.

cryptCreateContext
The cryptCreateContext function is used to create an encryption context for a given
encryption algorithm.
int cryptCreateContext( CRYPT_CONTEXT *cryptContext, const CRYPT_USER cryptUser,
const CRYPT_ALGO_TYPE cryptAlgo );
Parameters

cryptContext
The address of the encryption context to be created.
cryptUser
The user who is to own the encryption context or CRYPT_UNUSED for the
default, normal user.
cryptAlgo
The encryption algorithm to be used in the context.

See also

cryptDestroyContext, cryptDeviceCreateContext.

cryptCreateEnvelope
The cryptCreateEnvelope function is used to create an envelope object for
encrypting or decrypting, signing or signature checking, compressing or
decompressing, or otherwise processing data.
int cryptCreateEnvelope( CRYPT_ENVELOPE *cryptEnvelope, const CRYPT_USER cryptUser,
const CRYPT_FORMAT_TYPE formatType );
Parameters

cryptEnvelope
The address of the envelope to be created.
cryptUser
The user who is to own the envelope object or CRYPT_UNUSED for the default,
normal user.

320

Function Reference

formatType
The data format for the enveloped data.
See also

cryptDestroyEnvelope.

cryptCreateSession
The cryptCreateSession function is used to create a secure session object for use in
securing a communications link or otherwise communicating with a remote server or
client.
int cryptCreateSession( CRYPT_SESSION *cryptSession, const CRYPT_USER cryptUser, const
CRYPT_SESSION_TYPE sessionType );
Parameters

cryptSession
The address of the session to be created.
cryptUser
The user who is to own the session object or CRYPT_UNUSED for the default,
normal user.
sessionType
The type of the secure session.

See also

cryptDestroySession.

cryptCreateSignature
The cryptCreateSignature function digitally signs a piece of data. The signature is
placed in a buffer in a portable format that allows it to be checked using
cryptCheckSignature.
int cryptCreateSignature( void *signature, const int signatureMaxLength, int *signatureLength,
const CRYPT_CONTEXT signContext, const CRYPT_CONTEXT hashContext
);
Parameters

See also

cryptCheckSignature, cryptCheckSignatureEx, cryptCreateSignatureEx,
cryptQueryObject.

cryptCreateSignatureEx
The cryptCreateSignatureEx function digitally signs a piece of data with extended
control over the signature format. The signature is placed in a buffer in a portable
format that allows it to be checked using cryptCheckSignatureEx.
int cryptCreateSignatureEx( void *signature, const int signatureMaxLength, int *signatureLength,
const CRYPT_FORMAT_TYPE formatType, const CRYPT_CONTEXT

cryptDecrypt

321

signContext, const CRYPT_CONTEXT hashContext, const
CRYPT_CERTIFICATE extraData );
Parameters

signature
The address of a buffer to contain the signature. If you set this parameter to null,
cryptCreateSignature will return the length of the signature in signatureLength
without actually generating the signature.
signatureMaxLength
The maximum size in bytes of the buffer to contain the signature data.
signatureLength
The address of the signature length.
formatType
The format of the signature to create.
signContext
A public-key encryption or signature context containing the private key used to sign
the data.
hashContext
A hash context containing the hash of the data to sign.
extraData
Extra information to include with the signature or CRYPT_UNUSED if the format
i
st
hed
e
f
a
u
l
ts
i
g
na
t
ur
ef
or
ma
t(
whi
c
hdo
e
s
n
’
tus
et
h
ee
x
t
r
ada
t
a
)or
CRYPT_USE_DEFAULTi
ft
hes
i
g
na
t
ur
ei
s
n
’
tt
hede
f
a
ul
tf
or
ma
ta
ndy
o
uwa
ntt
o
use the default extra information.

See also

cryptCheckSignature, cryptCheckSignatureEx, cryptCreateSignature,
cryptQueryObject.

cryptDecrypt
The cryptDecrypt function is used to decrypt or hash data.
int cryptDecrypt( const CRYPT_CONTEXT cryptContext, void *buffer, const int length );
Parameters

cryptContext
The encryption context to use to decrypt or hash the data.
buffer
The address of the data to be decrypted or hashed.
length
The length in bytes of the data to be decrypted or hashed.

Remarks

Public-key encryption and signature algorithms have special data formatting
requirements that need to be taken into account when this function is called. You
s
hou
l
d
n’
tus
et
hi
sf
u
nc
t
i
o
nwi
t
ht
he
s
ea
l
g
or
i
t
h
mt
y
p
e
s
,
buti
ns
t
e
a
ds
h
oul
dus
et
he
higher-level functions cryptCreateSignature, cryptCheckSignature,
cryptExportKey, and cryptImportKey.

See also

cryptEncrypt.

cryptDeleteAttribute
The cryptDeleteAttribute function is used to delete an attribute from an object.
int cryptDeleteAttribute( const CRYPT_HANDLE cryptObject, const
CRYPT_ATTRIBUTE_TYPE attributeType );
Parameters

certificate
The object from which to delete the attribute.

322

Function Reference

attributeType
The attribute to delete.
Remarks

Mos
ta
t
t
r
i
but
e
sa
r
ea
l
wa
y
spr
e
s
e
nta
ndc
a
n
’
tb
ede
l
e
t
e
d,
i
ng
e
ne
r
a
lonl
yc
e
r
t
i
f
i
c
a
t
e
attributes are deletable.

See also

cryptGetAttribute, cryptGetAttributeString, cryptSetAttribute,
cryptSetAttributeString.

cryptDeleteCertExtension
The cryptDeleteCertExtension function is used to delete a generic blob-type
certificate extension from a certificate object.
int cryptDeleteCertExtension( const CRYPT_CERTIFICATE certificate, const char *oid );
Parameters

certificate
The certificate object from which to delete the extension.
oid
The object identifier value for the extension being deleted, specified as a sequence
of integers.

Remarks

See also

cryptAddCertExtension, cryptGetCertExtension.

cryptDeleteKey
The cryptDeleteKey function is used to delete a key or certificate from a keyset or
de
v
i
c
e
.
Th
ek
e
yt
ode
l
e
t
ei
si
d
e
nt
i
f
i
e
de
i
t
he
rt
hr
o
ug
ht
hek
e
yowne
r
’
sna
meort
he
i
r
email address.
int cryptDeleteKey( const CRYPT_HANDLE cryptObject, const CRYPT_KEYID_TYPE
keyIDtype, const void *keyID );
Parameters

cryptObject
The keyset or device object from which to delete the key.
keyIDtype
The type of the key ID, either CRYPT_KEYID_NAME for the name or key label,
or CRYPT_KEYID_EMAIL for the email address.
keyID
The key ID of the key to delete.

See also

cryptAddPrivateKey, cryptAddPublicKey, cryptGetPrivateKey,
cryptGetPublicKey.

cryptDestroyCert
The cryptDestroyCert function is used to destroy a certificate object after use. This
erases all keying and security information used by the object and frees up any
memory it uses.
int cryptDestroyCert( const CRYPT_CERTIFICATE cryptCert );
Parameters

cryptCert
The certificate object to be destroyed.

See also

cryptCreateCert.

cryptDestroyContext

323

cryptDestroyContext
The cryptDestroyContext function is used to destroy an encryption context after use.
This erases all keying and security information used by the context and frees up any
memory it uses.
int cryptDestroyContext( const CRYPT_CONTEXT cryptContext );
Parameters

cryptContext
The encryption context to be destroyed.

See also

cryptCreateContext, cryptDeviceCreateContext.

cryptDestroyEnvelope
The cryptDestroyEnvelope function is used to destroy an envelope after use. This
erases all keying and security information used by the envelope and frees up any
memory it uses.
int cryptDestroyEnvelope( const CRYPT_ENVELOPE cryptEnvelope );
Parameters

cryptEnvelope
The envelope to be destroyed.

See also

cryptCreateEnvelope.

cryptDestroyObject
The cryptDestroyObject function is used to destroy a cryptlib object after use. This
erases all security information used by the object, closes any open data sources, and
frees up any memory it uses.
int cryptDestroyObject( const CRYPT_HANDLE cryptObject );
Parameters

cryptObject
The object to be destroyed.

Remarks

This function is a generic form of the specialised functions that destroy/close specific
cryptlib object types such as encryption contexts and certificate and keyset objects.
In some cases it may not be possible to determine the exact type of an object (for
example the keyset access functions may return a key certificate object or only an
encryption context depending on the keyset type), cryptDestroyObject can be used
to destroy an object of an unknown type.

See also

cryptDestroyContext, cryptDestroyCert, cryptDestroyEnvelope,
cryptDestroySession, cryptKeysetClose.

cryptDestroySession
The cryptDestroySession function is used to destroy a session object after use. This
close the link to the client or server, erases all keying and security information used
by the session, and frees up any memory it uses.
int cryptDestroySession( const CRYPT_SESSION cryptSession );
Parameters

cryptSession
The session to be destroyed.

See also

cryptCreateSession.

cryptDeviceClose
The cryptDeviceClose function is used to destroy a device object after use. This
closes the connection to the device and frees up any memory it uses.

324

Function Reference

int cryptDeviceClose( const CRYPT_DEVICE device );
Parameters

device
The device object to be destroyed.

See also

cryptDeviceOpen.

cryptDeviceCreateContext
The cryptDeviceCreateContext function is used to create an encryption context for a
given encryption algorithm via an encryption device.
int cryptDeviceCreateContext( const CRYPT_DEVICE cryptDevice, CRYPT_CONTEXT
*cryptContext, const CRYPT_ALGO_TYPE cryptAlgo );
Parameters

cryptDevice
The device object used to create the encryption context.
cryptContext
The address of the encryption context to be created.
cryptAlgo
The encryption algorithm to be used in the context.

See also

cryptCreateContext, cryptDestroyContext.

cryptDeviceOpen
The cryptDeviceOpen function is used to establish a connection to a crypto device
such as a crypto hardware accelerator or a PCMCIA card or smart card.
int cryptDeviceOpen( CRYPT_DEVICE *device, const CRYPT_USER cryptUser, const
CRYPT_DEVICE_TYPE deviceType, const char *name );
Parameters

device
The address of the device object to be created.
cryptUser
The user who is to own the device object or CRYPT_UNUSED for the default,
normal user.
deviceType
The device type to be used.
name
The name of the device, or null i
fana
mei
s
n
’
tr
e
q
ui
r
e
d.

See also

cryptDeviceClose.

cryptDeviceQueryCapability
The cryptDeviceQueryCapability function is used to obtain information about the
characteristics of a particular encryption algorithm provided by an encryption device.
The infor
ma
t
i
onr
e
t
ur
ne
dc
ov
e
r
st
hea
l
g
or
i
t
h
m’
sk
e
ys
i
z
e
,
da
t
ab
l
oc
ks
i
z
e
,
a
ndo
t
h
e
r
algorithm-specific information.
int cryptDeviceQueryCapability( const CRYPT_DEVICE cryptDevice, const
CRYPT_ALGO_TYPE cryptAlgo, CRYPT_QUERY_INFO *cryptQueryInfo );
Parameters

cryptDevice
The encryption device to be queried.
cryptAlgo
The encryption algorithm to be queried.
cryptQueryInfo
The address of a CRYPT_QUERY_INFO structure which is filled with the

cryptEncrypt

325

information on the requested algorithm and mode, or null if this informationi
s
n’
t
required.
Remarks

Any fields in the CRYPT_QUERY_INFO structure that d
on
’
ta
ppl
yt
ot
h
ea
l
g
or
i
t
h
m
being queried are set to CRYPT_ERROR, null or zero as appropriate. To determine
whether an algorithm is available (without returning information on them), set the
query information pointer to null.

See also

cryptQueryCapability.

cryptEncrypt
The cryptEncrypt function is used to encrypt or hash data.
int cryptEncrypt( const CRYPT_CONTEXT cryptContext, void *buffer, const int length );
Parameters

cryptContext
The encryption context to use to encrypt or hash the data.
buffer
The address of the data to be encrypted or hashed.
length
The length in bytes of the data to be encrypted or hashed.

Remarks

See also

cryptDecrypt.

cryptEnd
The cryptEnd function is used to shut down cryptlib after use. This function should
be called after you have finished using cryptlib.
int cryptEnd( void );
Parameters

None

See also

cryptInit.

cryptExportCert
The cryptExportCert function is used to export an encoded signed public key
certificate, certification request, CRL, or other certificate-related item from a
certificate container object.
int cryptExportCert( void *certObject, const int certObjectMaxLength, int *certObjectLength, const
CRYPT_CERTFORMAT_TYPE certFormatType, const
CRYPT_CERTIFICATE certificate );
Parameters

certObject
The address of a buffer to contain the encoded certificate.
certObjectMaxLength
The maximum size in bytes of the buffer to contain the exported certificate.
certObjectLength
The address of the exported certificate length.
certFormatType
The encoding format for the exported certificate object.

326

Function Reference

certificate
The address of the certificate object to be exported.
Remarks

The certificate object needs to have all the required fields filled in and must then be
signed using cryptSignCert before it can be exported.

See also

cryptImportCert.

cryptExportKey
The cryptExportKey function is used to share a session key between two parties by
either exporting a session key from a context in a secure manner or by establishing a
new shared key. The exported/shared key is placed in a buffer in a portable format
that allows it to be imported back into a context using cryptImportKey.
If an existing session key is to be shared, it can be exported using either a public key
or key certificate or a conventional encryption key. If a new session key is to be
established, it can be done using a Diffie-Hellman encryption context.
int cryptExportKey( void *encryptedKey, const int encryptedKeyMaxLength, int
*encryptedKeyLength, const CRYPT_HANDLE exportKey, const
CRYPT_CONTEXT sessionKeyContext );
Parameters

encryptedKey
The address of a buffer to contain the exported key. If you set this parameter to
null, cryptExportKey will return the length of the exported key in
encryptedKeyLength without actually exporting the key.
encryptedKeyMaxLength
The maximum size in bytes of the buffer to contain the exported key.
encryptedKeyLength
The address of the exported key length.
exportKey
A public-key or conventional encryption context or key certificate object containing
the public or conventional key used to export the session key.
sessionKeyContext
An encryption context containing the session key to export (if the key is to be
shared) or an empty context with no key loaded (if the key is to be established).

Remarks

A session key can be shared in one of two ways, either by one party exporting an
existing key and the other party importing it, or by both parties agreeing on a key to
use. The export/import process requires an existing session key and a public/private
or conventional encryption context or key certificate object to export/import it with.
The key agreement process requires a Diffie-Hellman context and an empty session
key context (with no key loaded) that the new shared session key is generated into.

See also

cryptExportKeyEx, cryptImportKey, cryptQueryObject.

cryptExportKeyEx
The cryptExportKeyEx function is used to share a session key between two parties
by either exporting a session key from a context in a secure manner or by establishing
a new shared key, with extended control over the exported key format. The
exported/shared key is placed in a buffer in a portable format that allows it to be
imported back into a context using cryptImportKey.
If an existing session key is to be shared, it can be exported using either a public key
or key certificate or a conventional encryption key. If a new session key is to be
established, it can be done using a Diffie-Hellman encryption context.

cryptFlushData

327

int cryptExportKeyEx( void *encryptedKey, const int encryptedKeyMaxLength, int
*encryptedKeyLength, const CRYPT_FORMAT_TYPE formatType, const
CRYPT_HANDLE exportKey, const CRYPT_CONTEXT sessionKeyContext );
Parameters

encryptedKey
The address of a buffer to contain the exported key. If you set this parameter to
null, cryptExportKeyEx will return the length of the exported key in
encryptedKeyLength without actually exporting the key.
encryptedKeyMaxLength
The maximum size in bytes of the buffer to contain the exported key.
encryptedKeyLength
The address of the exported key length.
formatType
The format for the exported key.
exportKey
A public-key or conventional encryption context or key certificate object containing
the public or conventional key used to export the session key.
sessionKeyContext
An encryption context containing the session key to export (if the key is to be
shared) or an empty context with no key loaded (if the key is to be established).

Remarks

See also

cryptExportKey, cryptImportKey, cryptQueryObject.

cryptFlushData
The cryptFlushData function is used to flush data through an envelope or session
object, completing processing and (for session objects) sending the data to the remote
client or server.
int cryptFlushData( const CRYPT_HANDLE cryptHandle );
Parameters

cryptHandle
The envelope or session object to flush the data through.

See also

cryptPopData, cryptPushData.

cryptGenerateKey
The cryptGenerateKey function is used to generate a new key into an encryption
context.
int cryptGenerateKey( const CRYPT_CONTEXT cryptContext );
Parameters

cryptContext
The encryption context into which the key is to be generated.

Remarks

Ha
s
hc
on
t
e
x
t
sd
on
’
tr
e
q
ui
r
ek
e
y
s
,
s
oa
na
t
t
e
mptt
og
e
ne
r
a
t
eak
e
yi
nt
oaha
s
hcontext
will return CRYPT_ERROR_NOTAVAIL.
cryptGenerateKey will generate a key of a length appropriate for the algorithm
being used into an encryption context. If you want to specify the generation of a key
of a particular length, you should set the CRYPT_CTXINFO_KEYSIZE attribute
before calling this function.

328

Function Reference

The generation of large public-key encryption or digital signature keys can take quite
some time. If the environment you are working in supports background processing,
you should use cryptGenerateKeyAsync to generate the key instead.
See also

cryptGenerateKeyAsync.

cryptGenerateKeyAsync
The cryptGenerateKeyAsync function is used to asynchronously generate a new key
into an encryption context.
int cryptGenerateKeyAsync( const CRYPT_CONTEXT cryptContext );
Parameters

cryptContext
The encryption context into which the key is to be generated.

Remarks

Ha
s
hc
on
t
e
x
t
sd
on
’
tr
e
q
ui
r
ek
e
y
s
,
s
oa
na
t
t
e
mptt
og
e
ne
r
a
t
eak
e
yi
nt
oaha
s
hc
o
nt
e
x
t
will return CRYPT_ERROR_NOTAVAIL.
cryptGenerateKeyAsync will generate a key of a length appropriate for the
algorithm being used into an encryption context. If you want to specify the
generation of a key of a particular length, you should set the CRYPT_CTXINFO_KEYSIZE attribute before calling this function.

See also

cryptAsyncCancel, cryptAsyncQuery.

cryptGetAttribute
The cryptGetAttribute function is used to obtain a boolean or numeric value, status
information, or object from a cryptlib object.
int cryptGetAttribute( const CRYPT_HANDLE cryptObject, const CRYPT_ATTRIBUTE_TYPE
attributeType, int *value );
Parameters

cryptObject
The object from which to read the boolean or numeric value, status information, or
object.
attributeType
The attribute which is being read.
value
The boolean or numeric value, status information, or object.

See also

cryptDeleteAttribute, cryptGetAttributeString, cryptSetAttribute,
cryptSetAttributeString.

cryptGetAttributeString
The cryptGetAttributeString function is used to obtain text or binary strings or time
values from a cryptlib object.
int cryptGetAttributeString( const CRYPT_HANDLE cryptObject, const
CRYPT_ATTRIBUTE_TYPE attributeType, void *value, int *valueLength );
Parameters

cryptObject
The object from which to read the text or binary string or time value.
attributeType
The attribute which is being read.
value
The address of a buffer to contain the data. If you set this parameter to null,
cryptGetAttributeString will return the length of the data in attributeLength
without returning the data itself.

cryptGetCertExtension

329

valueLength
The length of the data in bytes.
See also

cryptDeleteAttribute, cryptGetAttribute, cryptSetAttribute,
cryptSetAttributeString.

cryptGetCertExtension
The cryptGetCertExtension function is used to obtain a generic blob-type certificate
extension from a certificate object or public or private key with an attached
certificate.
int cryptGetCertExtension( const CRYPT_CERTIFICATE certificate, const char *oid, int
*criticalFlag, void *extension, const int extensionMaxLength, int
*extensionLength );
Parameters

cryptObject
The certificate or public/private key object from which to read the extension.
oid
The object identifier value for the extension being queried, specified as a sequence
of integers.
criticalFlag
The critical flag for the extension being read.
extension
The address of a buffer to contain the data. If you set this parameter to null,
cryptGetCertExtension will return the length of the data in extensionLength
without returning the data itself.
extensionMaxLength
The maximum size in bytes of the buffer to contain the extension data.
extensionLength
The length in bytes of the extension data.

Remarks

See also

cryptAddCertExtension, cryptDeleteCertExtension.

cryptGetPrivateKey
The cryptGetPrivateKey function is used to create an encryption context from a
private key in a keyset or crypto device. The private key is identified either through
the ke
yowne
r
’
sn
a
meort
h
e
i
re
ma
i
la
d
dr
e
s
s
.
int cryptGetPrivateKey( const CRYPT_HANDLE cryptHandle, CRYPT_CONTEXT
*cryptContext, const CRYPT_KEYID_TYPE keyIDtype, const void *keyID,
const char *password );
Parameters

cryptHandle
The keyset or device from which to obtain the key.
cryptContext
The address of the context to be fetched.
keyIDtype
The type of the key ID, either CRYPT_KEYID_NAME for the name or key label,
or CRYPT_KEYID_EMAIL for the email address.
keyID
The key ID of the key to read.

330

Function Reference

password
The password required to decrypt the private key, or null if no password is required.
Remarks

cryptGetPrivateKey will return CRYPT_ERROR_WRONGKEY if an incorrect
password is supplied. This can be used to determine whether a password is necessary
by first calling the function with a null password and then retrying the read with a
user-supplied password if the first call returns with CRYPT_ERROR_WRONGKEY.

See also

cryptAddPrivateKey, cryptAddPublicKey, cryptDeleteKey, cryptGetPublicKey.

cryptGetPublicKey
The cryptGetPublicKey function is used to create an encryption context from a
public key in a keyset or crypto device. The public key is identified either through
t
hek
e
yowne
r
’
sn
a
meort
h
e
i
re
ma
i
la
d
dr
e
s
s
.
int cryptGetPublicKey( const CRYPT_HANDLE cryptObject, CRYPT_HANDLE *publicKey,
const CRYPT_KEYID_TYPE keyIDtype, const void *keyID );
Parameters

cryptObject
The keyset or device from which to obtain the key.
publicKey
The address of the context or certificate to be fetched.
keyIDtype
The type of the key ID, either CRYPT_KEYID_NAME for the name or key label,
or CRYPT_KEYID_EMAIL for the email address.
keyID
The key ID of the key to read.

Remarks

The type of object in which the key is returned depends on the keyset or device from
which it is being read. Most sources will provide a key certificate object, but some
will return only an encryption context containing the key. Both types of object can be
used with cryptlib functions.

See also

cryptAddPrivateKey, cryptAddPublicKey, cryptDeleteKey,
cryptGetPrivateKey.

cryptImportCert
The cryptImportCert function is used to import an encoded certificate, certification
request, CRL, or other certificate-related item into a certificate container object.
int cryptImportCert( const void *certObject, const int certObjectLength, const CRYPT_USER
cryptUser, CRYPT_CERTIFICATE *certificate );
Parameters

certObject
The address of a buffer that contains the encoded certificate.
certObjectLength
The encoded certificate length.
cryptUser
The user who is to own the imported object or CRYPT_UNUSED for the default,
normal user.
certificate
The certificate object to be created using the imported certificate data.

See also

cryptExportCert.

cryptImportKey

331

cryptImportKey
The cryptImportKey function is used to share a session key between two parties by
importing an encrypted session key that was previously exported with
cryptExportKey into an encryption context.
If an existing session key being shared, it can be imported using either a private key
or a conventional encryption key. If a new session key is being established, it can be
done using a Diffie-Hellman encryption context.
int cryptImportKey( const void *encryptedKey, const int encryptedKeyLength, const
CRYPT_CONTEXT importContext, const CRYPT_CONTEXT
sessionKeyContext );
Parameters

encryptedKey
The address of a buffer that contains the exported key created by cryptExportKey.
encryptedKeyLength
The length in bytes of the encrypted key data.
importContext
A public-key or conventional encryption context containing the private or
conventional key required to import the session key.
sessionKeyContext
The context used to contain the imported session key.

Remarks

See also

cryptExportKey, cryptExportKeyEx, cryptImportKey, cryptQueryObject.

cryptInit
The cryptInit function is used to initialise cryptlib before use. This function should
be called before any other cryptlib function is called.
int cryptInit( void );
Parameters

None

See also

cryptEnd.

cryptKeysetClose
The cryptKeysetClose function is used to destroy a keyset object after use. This
closes the connection to the key collection or keyset and frees up any memory it uses.
int cryptKeysetClose( const CRYPT_KEYSET keyset );
Parameters

keyset
The keyset object to be destroyed.

See also

cryptKeysetOpen.

cryptKeysetOpen
The cryptKeysetOpen function is used to establish a connection to a key collection
or keyset.

332

Function Reference

int cryptKeysetOpen( CRYPT_KEYSET *keyset, const CRYPT_USER cryptUser, const
CRYPT_KEYSET_TYPE keysetType, const char *name, const
CRYPT_KEYOPT_TYPE options );
Parameters

keyset
The address of the keyset object to be created.
cryptUser
The user who is to own the keyset object or CRYPT_UNUSED for the default,
normal user.
keysetType
The keyset type to be used.
name
The name of the keyset.
options
Option flags to apply when opening or accessing the keyset.

See also

cryptKeysetClose.

cryptPopData
The cryptPopData function is used to remove data from an envelope or session
object.
int cryptPopData( const CRYPT_HANDLE envelope, void *buffer, const int length, int
*bytesCopied );
Parameters

envelope
The envelope or session object from which to remove the data.
buffer
The address of the data to remove.
length
The length of the data to remove.
bytesCopied
The address of the number of bytes copied from the envelope.

See also

cryptPushData.

cryptPushData
The cryptPushData function is used to add data to an envelope or session object.
int cryptPushData( const CRYPT_HANDLE envelope, const void *buffer, const int length, int
*bytesCopied );
Parameters

envelope
The envelope or session object to which to add the data.
buffer
The address of the data to add.
length
The length of the data to add.
bytesCopied
The address of the number of bytes copied into the envelope.

See also

cryptPopData.

cryptQueryCapability

333

cryptQueryCapability
The cryptQueryCapability function is used to obtain information about the
characteristics of a particular encryption algorithm. The information returned covers
t
hea
l
g
or
i
t
hm’
sk
e
ys
i
z
e
,
da
t
abl
o
c
ks
i
z
e
,
a
n
dot
he
ra
l
g
or
i
t
h
m-specific information.
int cryptQueryCapability( const CRYPT_ALGO_TYPE cryptAlgo, CRYPT_QUERY_INFO
*cryptQueryInfo );
Parameters

cryptAlgo
The encryption algorithm to be queried.
cryptQueryInfo
The address of a CRYPT_QUERY_INFO structure which is filled with the
information on the requested algorithm and mode, or null if this informati
oni
s
n’
t
required.

Remarks

See also

cryptDeviceQueryCapability.

cryptQueryObject
The cryptQueryObject function is used to obtain information about an exported key
object created with cryptExportKey or a signature object created with
cryptCreateSignature. It returns information such as the type and algorithms used
by the object.
int cryptQueryObject( const void *objectData, const int objectDataLength,
CRYPT_OBJECT_INFO *cryptObjectInfo );
Parameters

objectData
The address of a buffer that contains the object created by cryptExportKey or
cryptCreateSignature.
objectDataLength
The length in bytes of the object data.
cryptObjectInfo
The address of a CRYPT_OBJECT_INFO structure that contains information on
the exported key or signature.

Remarks

Any fields in the CRYPT_OBJECT_INFO structure that d
on
’
ta
ppl
yt
ot
h
eob
j
e
c
t
being queried are set to CRYPT_ERROR, null or zero as appropriate.

See also

cryptCheckSignature, cryptCreateSignature, cryptExportKey, cryptImportKey.

cryptSetAttribute
The cryptSetAttribute function is used to add boolean or numeric information,
command codes, and objects to a cryptlib object.
int cryptSetAttribute( const CRYPT_HANDLE cryptObject, const CRYPT_ATTRIBUTE_TYPE
attributeType, const int value );
Parameters

cryptObject
The object to which to add the value.
attributeType
The attribute which is being added.
value
The boolean or numeric value, command code, or object which is being added.

334

Function Reference

See also

cryptDeleteAttribute, cryptGetAttribute, cryptGetAttributeString,
cryptSetAttributeString.

cryptSetAttributeString
The cryptSetAttributeString function is used to add text or binary strings or time
values to an object.
int cryptSetAttributeString( const CRYPT_HANDLE cryptObject, const
CRYPT_ATTRIBUTE_TYPE attributeType, const void *value, const int
valueLength );
Parameters

cryptObject
The object to which to add the text or binary string or time value.
attributeType
The attribute which is being added.
value
The address of the data being added.
valueLength
The length in bytes of the data being added.

See also

cryptDeleteAttribute, cryptGetAttribute, cryptGetAttributeString,
cryptSetAttribute.

cryptSignCert
The cryptSignCert function is used to digitally sign a public key certificate, CA
certificate, certification request, CRL, or other certificate-related item held in a
certificate container object.
int cryptSignCert( const CRYPT_CERTIFICATE certificate, const CRYPT_CONTEXT
signContext );
Parameters

certificate
The certificate container object that contains the certificate item to sign.
signContext
A public-key encryption or signature context containing the private key used to sign
the certificate.

Remarks

Once a certificate item has been signed, it can no longer be modified or updated using
the usual certificate manipulation functions. If you want to add further data to the
certificate item, you have to start again with a new certificate object.

See also

cryptCheckCert.

cryptUIDisplayCert
The cryptUIDisplayCert function displays a certificate object such as a certificate or
certificate chain to the user.
int cryptUIDisplayCert( const CRYPT_CERTIFICATE certificate, const HWND hWnd );
Parameters

certificate
The certificate object to display.
hWnd
The handle of the owner window, or NULL if the certificate viewer dialog has no
owner.

See also

cryptUIGenerateKey.

cryptUIGenerateKey

335

cryptUIGenerateKey
The cryptUIGenerateKey function is used to generate a new key into an encryption
context and obtain from the user the information required to create or obtain a
certificate from a CA. This function presents the user with a key generation wizard
that takes them through the key generation process and obtains the information
needed for certificate creation.
int cryptUIGenerateKey( const CRYPT_DEVICE device, CRYPT_CONTEXT *cryptContext,
const CRYPT_CERTIFICATE certificate, char *password, const HWND hWnd
);
Parameters

device
The crypto device in which the key is to be generated, or CRYPT_UNUSED if no
crypto device is being used.
cryptContext
The address of the encryption context into which the key is to be generated.
certificate
The certificate object that will be filled in with the user's details.
password
The password selected by the user.
hWnd
The handle of the owner window, or NULL if the certificate viewer dialog has no
owner.

See also

cryptUIDisplayCert.

336

Standards Conformance

Standards Conformance
All algorithms, security methods, and data encoding systems used in cryptlib either
comply with one or more national and international banking and security standards,
or are implemented and tested to conform to a reference implementation of a
particular algorithm or security system. Compliance with national and international
security standards is automatically provided when cryptlib is integrated into an
application. The algorithm standards that cryptlib follows are listed below. A further
list of non-algorithm-related standards that cryptlib complies with are given at the
start of this document.

AES
AES has been implemented as per:
FI
PSPUB19
7,
“
Adv
a
nc
e
dEnc
r
y
pt
i
onSt
a
nd
a
r
d”
,
2
00
1.
The AES code has been validated against the test vectors given in:
FI
PSPUB19
7,
“
Adv
a
nc
e
dEnc
r
y
pt
i
onSt
a
nd
a
r
d”
,
2
00
1.

Blowfish
Blowfish has been implemented as per:
“
De
s
c
r
i
pt
i
o
no
faNe
wVa
r
i
a
bl
e
-Length Key, 64-bi
tBl
oc
kCi
p
he
r(
Bl
owf
i
s
h)
”
,
Br
uc
eSc
h
ne
i
e
r
,
“
Fa
s
tSof
t
wa
r
eEnc
r
y
pt
i
on”
,
Lecture Notes in Computer Science
No. 809, Springer-Verlag 1994.
The Blowfish modes of operation are given in:
I
SO/
I
EC8372
:
1
98
7,
“
I
nf
or
ma
t
i
onTe
c
hn
ol
og
y— Modes of Operation for a 64bi
tBl
oc
kCi
ph
e
rAl
g
or
i
t
hm”
.
I
SO/
I
EC1011
6:
19
97,
“
I
n
f
or
ma
t
i
o
nt
e
c
h
nol
og
y— Security techniques — Modes
of operation for an n-bi
tbl
o
c
kc
i
phe
ra
l
g
or
i
t
h
m”
.
The Blowfish code has been validated against the Blowfish reference implementation
test vectors.

CAST-128
CAST-128 has been implemented as per:
RFC21
44,
“
Th
eCAST-128 Encryption Algorithm”
,
Ca
r
l
i
s
l
eAda
ms
,
Ma
y199
7.
The CAST-128 modes of operation are given in:
I
SO/
I
EC8372
:
1
98
7,
“
I
nf
or
ma
t
i
onTe
c
hn
ol
og
y— Modes of Operation for a 64bi
tBl
oc
kCi
ph
e
rAl
g
or
i
t
hm”
.
I
SO/
I
EC1011
6:
19
97,
“
I
n
f
or
ma
t
i
o
nt
e
c
h
nol
og
y— Security techniques — Modes
of operation for an n-bi
tbl
o
c
kc
i
phe
ra
l
g
or
i
t
h
m”
.
The CAST-128 code has been validated against the RFC 2144 reference
implementation test vectors.

DES
DES has been implemented as per:
ANSIX3.
92,
“
Ame
r
i
c
a
nNa
t
i
ona
lSt
a
n
da
r
d,
Da
t
aEnc
r
y
pt
i
onAl
g
or
i
t
h
m”
,
19
81.
FIPS PUB 46-2,
“
Da
t
aEnc
r
y
pt
i
onSt
a
nd
a
r
d”
,
1
99
4.
FI
PSPUB74,
“
Gui
de
l
i
n
e
sf
o
rI
mpl
e
me
nt
i
nga
ndUs
i
ngt
heNBSDa
t
aEnc
r
y
pt
i
o
n
St
a
nd
a
r
d”
,
1
98
1.
I
SO/
I
EC8731
:
1
98
7,
“
Ba
nk
i
n
g— Approved Algorithms for Message
Authentication — Part 1: Data Encryption Algorithm (DEA)
”
.

cryptUIGenerateKey

337

The DES modes of operation are given in:
ANSIX3.
106,
“
Ame
r
i
c
a
nNa
t
i
o
na
lSt
a
n
da
r
d,
I
nf
or
ma
t
i
o
nSy
s
t
e
ms— Data
Encryption Algorithm — Mo
de
so
fOpe
r
a
t
i
o
n”
,
19
83.
FI
PSPUB81,
“
DESMod
e
so
fOpe
r
a
t
i
o
n”
,
19
80.
I
SO/
I
EC8372
:
1
98
7,
“
I
nf
or
ma
t
i
onTe
c
hn
ol
og
y— Modes of Operation for a 64bi
tBl
oc
kCi
ph
e
rAl
g
or
i
t
hm”
.
I
SO/
I
EC1011
6:
19
97,
“
I
n
f
or
ma
t
i
o
nt
e
c
h
nol
og
y— Security techniques — Modes
of operation for an n-bi
tbl
o
c
kc
i
phe
ra
l
g
or
i
t
h
m”
.
The DES MAC mode is given in:
ANSIX9.
9,
“
Fi
na
nc
i
a
lI
ns
t
i
t
u
t
i
o
nMe
s
s
a
g
eAut
he
nt
i
c
a
t
i
o
n(
Whol
e
s
a
l
e
)
”
,
19
86.
FI
PSPUB11
3,
“
Co
mp
ut
e
rDa
t
aAut
he
n
t
i
c
a
t
i
o
n”
,
19
84.
I
SO/
I
EC9797
:
1
99
4,
“
I
nf
or
ma
t
i
ont
e
c
h
no
l
og
y— Security techniques — Data
integrity mechanism using a cryptographic check function employing a block
c
i
p
he
ra
l
g
or
i
t
h
m”
.
The DES code has been validated against the test vectors given in:
NIST Special Publication 500-20,
“
Va
l
i
da
t
i
ngt
heCor
r
e
c
t
n
e
s
sofHa
r
dwa
r
e
I
mpl
e
me
n
t
a
t
i
o
nso
ft
h
eNBSDa
t
aEnc
r
y
pt
i
o
nSt
a
n
da
r
d”
.

Triple DES
Triple DES has been implemented as per:
ANSIX9.
17,
“
American National Standard, Financial Institution Key
Ma
na
g
e
me
nt(
Who
l
e
s
a
l
e
)
”
,
1
985.
ANSIX9.
52,
“
Tr
i
pl
eDa
t
aEn
c
r
y
pt
i
o
nAl
g
or
i
t
hmMo
de
so
fOpe
r
a
t
i
o
n”
,
1
99
9.
FIPS 46-3,
“
Da
t
aEn
c
r
y
pt
i
onSt
a
nd
a
r
d(
DES)
”
,
1999.
I
SO/
I
EC8732
:
1
98
7,
“
Ba
nk
i
n
g— Key Management (Whol
e
s
a
l
e
)
”
.
The triple DES modes of operation are given in:
I
SO/
I
EC8372
:
1
98
7,
“
I
nf
or
ma
t
i
onTe
c
hn
ol
og
y— Modes of Operation for a 64bi
tBl
oc
kCi
ph
e
rAl
g
or
i
t
hm”
.
I
SO/
I
EC1011
6:
19
97,
“
I
n
f
or
ma
t
i
o
nt
e
c
h
nol
og
y— Security techniques — Modes
of operation for an n-bi
tbl
o
c
kc
i
phe
ra
l
g
or
i
t
h
m”
.
The DES code has been validated against the test vectors given in:
NIST Special Publication 800-20,
“
Mo
de
so
fOpe
r
a
t
i
o
nVa
l
i
da
t
i
o
nSy
s
t
e
mf
ort
he
Tr
i
pl
eDa
t
aEnc
r
y
pt
i
o
nAl
g
or
i
t
h
m”
.

Diffie-Hellman
DH has been implemented as per:
PKCS#3,
“
Di
f
f
i
e
-He
l
l
ma
nKe
yAg
r
e
e
me
ntSt
a
nda
r
d”
,
19
9
1.
ANSIX9.
42,
“
Pu
bl
i
cKe
yCr
y
pt
og
r
a
phyf
ort
heFi
na
nc
i
a
lSe
r
v
i
c
e
sI
ndus
t
r
y—
Agreement of Symmetric Keys Using Diffie-He
l
l
ma
na
n
dMQVAl
g
or
i
t
hms
”
,
2000.

DSA
DSA has been implemented as per:
ANSI X9.30-1,
“
Ame
r
i
c
a
nNa
t
i
ona
lSt
a
n
da
r
d,
Pu
bl
i
c
-Key Cryptography Using
I
r
r
e
v
e
r
s
i
bl
eAl
g
or
i
t
hmsf
ort
h
eFi
na
n
c
i
a
lSe
r
v
i
c
e
sI
ndus
t
r
y
”
,
199
3.
FI
PSPUB18
6,
“
Di
g
i
t
a
lSi
g
na
t
ur
eSt
a
nd
a
r
d”
,
19
94.

338

Standards Conformance

Elgamal
Elgamal has been implemented as per
“
Apub
l
i
c
-key cryptosystem based o
ndi
s
c
r
e
t
el
og
a
r
i
t
hms
”
,
Ta
he
rEl
g
a
ma
l
,
IEEE
Transactions on Information Theory, Vol.31, No.4 (1985), p.469.

HMAC-MD5
HMAC-MD5 has been implemented as per:
RFC21
04,
“
HMAC:Ke
y
e
d-Ha
s
hi
ngf
orMe
s
s
a
g
eAut
he
n
t
i
c
a
t
i
o
n”
,
Hug
o
Krawczyk, Mihir Bellare, and Ran Canetti, February 1997.
The HMAC-MD5 code has been validated against the test vectors given in:
“
Te
s
tCa
s
e
sf
orHMAC-MD5 and HMAC-SHA-1”
,
Pa
u-Chen Cheng and Robert
Glenn, March 1997.

HMAC-SHA1
HMAC-SHA1 has been implemented as per:
FI
PSPUB19
8,
“
TheKe
y
e
d-Ha
s
hMe
s
s
a
g
eAut
he
n
t
i
c
a
t
i
onCode(
HMAC)
”
,
2002.
RFC21
04,
“
HMAC:Ke
y
e
d-Ha
s
hi
ngf
orMe
s
s
a
g
eAut
he
n
t
i
c
a
t
i
o
n”
,
Hug
o
Krawczyk, Mihir Bellare, and Ran Canetti, February 1997.
The HMAC-SHA1 code has been validated against the test vectors given in:
“
Te
s
tCa
s
e
sf
or HMAC-MD5 and HMAC-SHA-1”
,
Pa
u-Chen Cheng and Robert
Glenn, March 1997.

IDEA
IDEA has been implemented as per:
“
De
v
i
c
ef
ort
heConv
e
r
s
i
o
no
faDi
g
i
t
a
lBl
o
c
ka
ndt
heUs
eThe
r
e
o
f
”
,
J
a
me
s
Massey and Xuejia Lai, International Patent PCT/CH91/00117, 1991.
“
De
v
i
c
ef
ort
heConv
e
r
s
i
o
no
faDi
g
i
t
a
lBl
o
c
ka
ndUs
eo
fSa
me
”
,
J
a
me
sMa
s
s
e
y
and Xuejia Lai, US Patent #5,214,703, 1993.
“
Ont
heDe
s
i
g
na
ndSe
c
ur
i
t
yofBl
oc
kCi
ph
e
r
s
”
,
Xue
j
i
aLa
i
,
ETHSe
r
i
e
si
n
Information Processing, Vol.1, Hartung-Gorre Verlag, 1992.
ISO/IEC9979,
“
Da
t
aCr
y
pt
o
g
r
a
phi
cTe
c
hn
i
q
ue
s— Procedures for the
Re
g
i
s
t
r
a
t
i
o
nofCr
y
pt
og
r
a
phi
cAl
g
or
i
t
h
ms
”
.
The IDEA modes of operation are given in:
I
SO/
I
EC8372
:
1
98
7,
“
I
nf
or
ma
t
i
onTe
c
hn
ol
og
y— Modes of Operation for a 64bi
tBl
oc
kCi
ph
e
rAl
g
or
i
t
hm”
.
ISO/IEC 1011
6:
19
97,
“
I
n
f
or
ma
t
i
o
nt
e
c
h
nol
og
y— Security techniques — Modes
of operation for an n-bi
tbl
o
c
kc
i
phe
ra
l
g
or
i
t
h
m”
.
The IDEA code has been validated against the ETH reference implementation test
vectors.

MD2
MD2 has been implemented as per:
RFC13
19,
“
Th
eMD2Me
s
s
a
g
eDi
g
e
s
tAl
g
or
i
t
hm”
,
Bur
tKa
l
i
s
k
i
,
19
92.
The MD2 code has been validated against the RFC 1319 reference implementation
test vectors.

MD4
MD4 has been implemented as per:

cryptUIGenerateKey

339

RFC13
20,
“
Th
eMD4Me
s
s
a
g
eDi
g
e
s
tAl
g
or
i
t
hm”
,
Ron
a
l
dRi
v
e
s
t
,
1
99
2.
The MD4 code has been validated against the RFC 1320 reference implementation
test vectors.

MD5
MD5 has been implemented as per:
RFC13
21,
“
Th
eMD5Me
s
s
a
g
eDi
g
e
s
tAl
g
or
i
t
hm”
,
Ron
a
l
dRi
v
e
s
t
,
1
99
2.
The MD5 code has been validated against the RFC 1321 reference implementation
test vectors.

RC2
The RC2 code is implemented as per:
“
TheRC2En
c
r
y
pt
i
onAl
g
or
i
t
hm”
,
Ron
a
l
dRi
v
e
s
t
,
RSADa
t
aSe
c
ur
i
t
yI
nc
,
199
2.
RFC22
68,
“
ADe
s
c
r
i
pt
i
o
no
ft
heRC2Enc
r
y
pt
i
o
nAl
g
or
i
t
h
m”
,
Ro
na
l
dRi
v
e
s
t
,
1998.
The RC2 modes of operation are given in:
I
SO/
I
EC8372
:
1
98
7,
“
I
nf
or
ma
t
i
onTe
c
hn
ol
og
y— Modes of Operation for a 64bi
tBl
oc
kCi
ph
e
rAl
g
or
i
t
hm”
.
I
SO/
I
EC1011
6:
19
97,
“
I
n
f
or
ma
t
i
o
nt
e
c
h
nol
og
y— Security techniques — Modes
of operation for an n-bi
tbl
o
c
kc
i
phe
ra
l
g
or
i
t
h
m”
.
The RC2 code has been validated against RSADSI BSAFE test vectors.

RC4
The RC4 code is implemented as per:
“
TheRC4En
c
r
y
pt
i
onAl
g
or
i
t
hm”
,
Ron
a
l
dRi
v
e
s
t
,
RSADa
t
aSe
c
ur
i
t
yI
nc
,
199
2.
The RC4 code has been validated against RSADSI BSAFE and US Department of
Commerce test vectors.

RC5
The RC5 code is implemented as per:
“
TheRC5En
c
r
y
pt
i
onAl
g
or
i
t
hm”
,
Ron
a
l
dRi
v
e
s
t
,
“
Fa
s
tSo
f
t
wa
r
eEn
c
r
y
pt
i
o
nI
I
”
,
Lecture Notes in Computer Science No.1008, Springer-Verlag 1995.
RFC20
40,
“
Th
eRC5,
RC5-CBC, RC5-CBC-Pad, and RC5-CTSAl
g
or
i
t
hms
”
,
Robert Baldwin and Ronald Rivest, October 1996.
The RC5 modes of operation are given in:
I
SO/
I
EC8372
:
1
98
7,
“
I
nf
or
ma
t
i
onTe
c
hn
ol
og
y— Modes of Operation for a 64bi
tBl
oc
kCi
ph
e
rAl
g
or
i
t
hm”
.
I
SO/
I
EC1011
6:
19
97,
“
I
n
f
or
ma
t
i
o
nt
e
c
h
nol
og
y— Security techniques — Modes
of operation for an n-bi
tbl
o
c
kc
i
phe
ra
l
g
or
i
t
h
m”
.
The RC5 code has been validated against the RC5 reference implementation test
vectors.

RIPEMD-160
The RIPEMD-160 code has been implemented as per:
“
RI
PEMD-1
60
:As
t
r
e
ng
t
he
n
e
dv
e
r
s
i
onofRI
PEMD”
,
Ha
n
sDobbertin, Antoon
Bos
s
e
l
a
e
r
s
,
a
ndBa
r
tPr
e
ne
e
l
,
“
Fa
s
tSof
t
wa
r
eEnc
r
y
pt
i
o
nI
I
I
”
,
Lecture Notes in
Computer Science No.1008, Springer-Verlag 1995.
ISO/IEC 10118-3:
19
97,
“
I
n
f
o
r
ma
t
i
o
nTe
c
h
no
l
og
y— Security Techniques —
Hash functions — Part 3: Dedicated hash funct
i
ons
”
.

340

Standards Conformance

The RIPEMD-160 code has been validated against the RIPEMD-160 reference
implementation test vectors.

RSA
The RSA code is implemented as per:
ANSI X9.31-1,
“
Ame
r
i
c
a
nNa
t
i
ona
lSt
a
n
da
r
d,
Pu
bl
i
c
-Key Cryptography Using
Reversible Algorithms for the Financ
i
a
lSe
r
v
i
c
e
sI
n
dus
t
r
y
”
,
199
3.
ISO IEC 9594-8/ITU-TX.
509,
“
I
nf
or
ma
t
i
onTe
c
h
no
l
og
y— Open Systems
Interconnection — TheDi
r
e
c
t
or
y
:Aut
he
nt
i
c
a
t
i
onFr
a
me
wor
k
”
.
PKCS#1,
“
RSAEnc
r
y
pt
i
o
nSt
a
nd
a
r
d”
,
1
99
1.

SHA/SHA1
The SHA code has been implemented as per:
ANSI X9.30-2,
“
Ame
r
i
c
a
nNa
t
i
ona
lSt
a
n
da
r
d,
Pu
bl
i
c
-Key Cryptography Using
I
r
r
e
v
e
r
s
i
bl
eAl
g
or
i
t
hmsf
ort
h
eFi
na
n
c
i
a
lSe
r
v
i
c
e
sI
ndus
t
r
y
”
,
199
3.
FI
PSPUB18
0,
“
Se
c
ur
eHa
s
hSt
a
nda
r
d”
,
19
93.
FIPS PUB 180-1,
“
Se
c
ur
eHa
s
hSt
a
n
da
r
d”
,
1
99
4.
ISO/IEC 10118-3:
19
97,
“
I
n
f
o
r
mation Technology — Security Techniques —
Hash functions — Pa
r
t3:De
di
c
a
t
e
dha
s
hf
u
nc
t
i
ons
”
.
RFC31
74,
“
USSe
c
ur
eHa
s
hAl
g
or
i
t
h
m 1(
SHA1)
”
,
2001
The SHA code has been validated against the test vectors given in:
FI
PSPUB18
0,
“
Se
c
ur
eHa
s
hSt
a
nda
r
d”
,
19
93.
The SHA1 code has been validated against the test vectors given in:
FIPS PUB 180-1,
“
Se
c
ur
eHa
s
hSt
a
n
da
r
d”
,
1
99
4.

SHA2/SHA-256/SHA-384/SHA-512
The SHA2 code has been implemented as per:
FIPS PUB 180-2,
“
Se
c
ur
eHa
s
hSt
a
n
da
r
d”
,
2
00
2.
The SHA2 code has been validated against the test vectors given in:
FIPS PUB 180-2,
“
Se
c
ur
eHa
s
hSt
a
n
da
r
d”
,
2
00
2.

Skipjack
The Skipjack code has been implemented as per:
“
Sk
i
pj
a
c
ka
n
dKEAAl
g
or
i
t
h
m Spe
c
i
f
i
c
a
t
i
ons
,
Ve
r
s
i
on2.
0
”
,
Na
t
i
on
a
lSe
c
ur
i
t
y
Agency, 28 May 1998.
“
Ca
ps
t
o
ne(
MYK-80)Spe
c
i
f
i
c
a
t
i
ons
”
,
R21I
n
f
or
ma
lTe
c
hn
i
c
a
lRe
p
or
t
,
R2
1TECH-30-95, National Security Agency, 14 August 1995.

cryptUIGenerateKey

341

Acknowledgements
Alexey Kirichenko provided information on NtQuerySystemInfo for randomnessgathering under WinNT/Win2K to avoid the need to access the buggy Windows
registry performance counters.
Brian Gladman wrote the AES code.
Chris Wedgwood and Paul Kendall helped write the Unix random data gathering
routines.
endergone Zwiebeltüte helped debug the SSL/TLS implementation.
Eric Young and the OpenSSL team wrote the conventional encryption and hashing
code and bignum library.
Jean-Loup Gailly and Mark Adler wrote the zlib compression code.
Joerg Plate did the Amiga port.
Markus F.X.J. Oberhumer did the 32-bit DOS port.
Matt Thomlinson and Blake Coverett helped fix up and debug the Win32 random
data gathering routines.
Matthijs van Duin, Sascha Kratky, and Jeff Lamarche did the Macintosh port.
Nathan Hammond did the MVS port.
Osma Ahvenlampi did the PPC BeOS port.
Sami Tolvanen implemented the cryptlib GUI interface.
Sriram Ramachandran did the Cygwin port.
Steve Landers provided the Tcl bindings, with financial support from Eolas
Technologies.
Stuart Woolford and Mario Korva did the OS/2 port.
Trevor Perrin did the C#, Java, and Python bindings.
Wolfgang Gothier did the Delphi and Visual Basic bindings and tracked down a
number of really obscure probl^H^H^H^H^Hundocumented features.