OpenSSL

0.9.7

Crypto Library
Title Page Crypto Library

05 July 2003 Fly leaf

 Table of Contents
Crypto Library

CRYPTO 1
ASN1_OBJECT allocation 2
ASN1_STRING utility 3
ASN1_STRING allocation 4
ASN1_STRING output 5
BIO - I/O abstraction 7
BIO control 8
BIO chain traversal 10
BIO base64 12
BIO buffering 14
BIO cipher 15
BIO message digest 16
BIO null 18
BIO SSL 19
BIO allocation 24
BIO chain 25
BIO I/O 26
BIO callback 27
BIO retry 29
BIO accept 31
BIO pair 34
BIO connect 37
BIO file decscriptor 40
BIO file 41
BIO memory 43
BIO null 45
BIO socket 46
Blowfish encryption 47
BN multiprecision integer 49
BIGNUM operations 52
BIGNUM functions 54
BIGNUM conversion 55
BIGNUM compare and test 57
BIGNUM copy 58
BN_CTX allocation 59
BIGNUM temp 60
BIGNUM primes 61
BIGNUM internals 62
BIGNUM inverse 65
BIGNUM Montgomery 66
BIGNUM modular multiplication 68
BIGNUM allocation 69
BIGNUM size 70
BIGNUM pseudo-random 71
BIGNUM bit-operations 72
BIGNUM exchange 73
BIGNUM assignment 74
BUF_MEM 75
CRYPTO internals 76
d2i/i2d ASN1_OBJECT 77
d2i/i2d PKCS#3 DH parameter 78
d2i/i2d DSA key encoding and parsing 79

05 July 2003 i
Crypto Library Table of Contents

d2i/i2d PKCS#8 private key 81

d2i/i2d RSA public and private key encoding 82
d2i/i2d X509 encode and decode 83
d2i/i2d AlgorithmIdentifier 86
d2i/i2d PKCS#10 certificate request 87
d2i/i2d X509_NAME encoding 88
d2i/i2d PKCS#10 certificate request 89
d2i/i2d DigestInfo 90
DES encryption 91
DES modes 96
DH - Diffie-Hellman key agreement 98
DH Diffie-Hellman key exchange 100
DH generate and check 101
DH add application data 102
DH allocation 103
DH select method 104
DH size 106
DSA - Digital Signature Algorithm 107
DSA raw signature 109
DSA dup DH 110
DSA generate key pair 111
DSA generate parameters 112
DSA add application data 113
DSA allocation 114
DSA select method 115
DSA signatures 117
DSA signature allocation 118
DSA size 119
ENGINE cryptographic module 120
ERR - error codes 129
ERR clear error queue 132
ERR human-readable messages 133
ERR error codes and data 134
ERR get library, function, reason code 135
ERR string allocation 136
ERR arbitrary error strings 137
ERR print errors 138
ERR recording 139
ERR free thread error queue 140
EVP - high-level cryptography 141
EVP password encryption 142
EVP digest 143
EVP cipher 147
EVP envelope decryption 154
EVP_PKEY allocation 155
EVP_PKEY assignment 156
EVP envelope encryption 157
EVP signing 158
EVP signature verification 159
HMAC message authentication code 160
LH dynamic hash table 162
LH statistics 166
MD2, MD4, MD5 hash 167
MDC2 hash 169
OBJ_nid... ASN1 object utility 170
OpenSSL add algorithms 172
OpenSSL version number 173
PEM routines 175
PKCS12_create 182

ii 05 July 2003
Table of Contents Crypto Library

PKCS12_parse 183
PKCS7_decrypt 184
PKCS7_encrypt 185
PKCS7_sign 186
PKCS7_verify 187
RAND pseudo-random number generator 189
RAND entropy 191
RAND random data 192
RAND cleanup 193
RAND_egd entropy daemon 194
RAND seed file 195
RAND select method 196
RC4 encryption 198
RIPEMD-160 hash 199
RSA public key cryptosystem 200
RSA protection from timing attacks 202
RSA validate private keys 203
RSA generate key pair 204
RSA add application data 205
RSA allocation 207
RSA asymmetric encryption padding 208
RSA print cryptographic parameters 210
RSA low level signature 211
RSA public key cryptography 212
RSA select method 213
RSA signatures 216
RSA ASN1 signatures 217
RSA size 218
SHA Secure Hash Algorithm 219
SMIME parse 220
SMIME_write_PKCS7 221
OpenSSL thread support 222
UI New User Interface 224
Compatibility user interface 227
X509_NAME modification 228
X509_NAME_ENTRY utility 230
X509_NAME lookup and enumeration 231
X509_NAME printing 233
X509 certificate ASN1 allocation 235

05 July 2003 iii

Crypto Library Table of Contents

iv 05 July 2003
Crypto Library CRYPTO

CRYPTO
CRYPTO - OpenSSL cryptographic library
SYNOPSIS
DESCRIPTION
The OpenSSL crypto library implements a wide range of cryptographic algorithms used in various
Internet standards. The services provided by this library are used by the OpenSSL implementations of
SSL, TLS and S/MIME, and they have also been used to implement SSH, OpenPGP, and other
cryptographic standards.
OVERVIEW
libcrypto consists of a number of sub-libraries that implement the individual algorithms.
The functionality includes symmetric encryption, public key cryptography and key agreement, certificate
handling, cryptographic hash functions and a cryptographic pseudo-random number generator.

SYMMETRIC CIPHERS
blowfish(3)|blowfish(3), cast(3)|cast(3), des(3)|des(3), idea(3)|idea(3), rc2(3)|rc2(3),
rc4(3)|rc4(3), rc5(3)|rc5(3)
PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT
dsa(3)|dsa(3), dh(3)|dh(3), rsa(3)|rsa(3)
CERTIFICATES
x509(3)|x509(3), x509v3(3)|x509v3(3)
AUTHENTICATION CODES, HASH FUNCTIONS
hmac(3)|hmac(3), md2(3)|md2(3), md4(3)|md4(3), md5(3)|md5(3), mdc2(3)|mdc2(3),
ripemd(3)|ripemd(3), sha(3)|sha(3)
AUXILIARY FUNCTIONS
err(3)|err(3), threads(3)|threads(3), rand(3)|rand(3),
OPENSSL_VERSION_NUMBER(3)|OPENSSL_VERSION_NUMBER(3)
INPUT/OUTPUT, DATA ENCODING
asn1(3)|asn1(3), bio(3)|bio(3), evp(3)|evp(3), pem(3)|pem(3), pkcs7(3)|pkcs7(3),
pkcs12(3)|pkcs12(3)
INTERNAL FUNCTIONS
bn(3)|bn(3), buffer(3)|buffer(3), lhash(3)|lhash(3), objects(3)|objects(3), stack(3)|stack(3),
txt_db(3)|txt_db(3)

NOTES
Some of the newer functions follow a naming convention using the numbers 0 and 1. For example the
functions:
int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
int X509_add1_trust_object(X509 *x, ASN1_OBJECT *obj);

The 0 version uses the supplied structure pointer directly in the parent and it will be freed up when the
parent is freed. In the above example crl would be freed but rev would not.
The 1 function uses a copy of the supplied structure pointer (or in some cases increases its link count) in
the parent and so both (x and obj above) should be freed up.
SEE ALSO
openssl(1)|openssl(1), ssl(3)|ssl(3)

05 July 2003 1
ASN1_OBJECT allocation Crypto Library

ASN1_OBJECT allocation
ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions
SYNOPSIS
ASN1_OBJECT *ASN1_OBJECT_new(void);
void ASN1_OBJECT_free(ASN1_OBJECT *a);
DESCRIPTION
The ASN1_OBJECT allocation routines, allocate and free an ASN1_OBJECT structure, which
represents an ASN1 OBJECT IDENTIFIER.
ASN1_OBJECT_new() allocates and initializes a ASN1_OBJECT structure.
ASN1_OBJECT_free() frees up the ASN1_OBJECT structure a.
NOTES
Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it is almost never used in
applications. The ASN1 object utility functions such as OBJ_nid2obj() are used instead.
RETURN VALUES
If the allocation fails, ASN1_OBJECT_new() returns NULL and sets an error code that can be obtained
by ERR_get_error(3)|ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.
ASN1_OBJECT_free() returns no value.
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), d2i_ASN1_OBJECT(3)|d2i_ASN1_OBJECT(3)
HISTORY
ASN1_OBJECT_new() and ASN1_OBJECT_free() are available in all versions of SSLeay and
OpenSSL.

2 05 July 2003
Crypto Library ASN1_STRING utility

ASN1_STRING utility
ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data - ASN1_STRING utility
functions
SYNOPSIS
int ASN1_STRING_length(ASN1_STRING *x);
unsigned char * ASN1_STRING_data(ASN1_STRING *x);

ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);

int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);

int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);

int ASN1_STRING_type(ASN1_STRING *x);

int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in);

DESCRIPTION
These functions allow an ASN1_STRING structure to be manipulated.
ASN1_STRING_length() returns the length of the content of x.
ASN1_STRING_data() returns an internal pointer to the data of x. Since this is an internal pointer it
should not be freed or modified in any way.
ASN1_STRING_dup() returns a copy of the structure a.
ASN1_STRING_cmp() compares a and b returning 0 if the two are identical. The string types and
content are compared.
ASN1_STRING_set() sets the data of string str to the buffer data or length len. The supplied data is
copied. If len is -1 then the length is determined by strlen(data).
ASN1_STRING_type() returns the type of x, using standard constants such as
V_ASN1_OCTET_STRING.
ASN1_STRING_to_UTF8() converts the string in to UTF8 format, the converted data is allocated in a
buffer in *out. The length of out is returned or a negative error code. The buffer *out should be free
using OPENSSL_free().
NOTES
Almost all ASN1 types in OpenSSL are represented as an ASN1_STRING structure. Other types such
as ASN1_OCTET_STRING are simply typedefed to ASN1_STRING and the functions call the
ASN1_STRING equivalents. ASN1_STRING is also used for some CHOICE types which consist
entirely of primitive string types such as DirectoryString and Time.
These functions should not be used to examine or modify ASN1_INTEGER or
ASN1_ENUMERATED types: the relevant INTEGER or ENUMERATED utility functions should be
used instead.
In general it cannot be assumed that the data returned by ASN1_STRING_data() is null terminated or
does not contain embedded nulls. The actual format of the data will depend on the actual string type
itself: for example for and IA5String the data will be ASCII, for a BMPString two bytes per character in
big endian format, UTF8String will be in UTF8 format.
Similar care should be take to ensure the data is in the correct format when calling
ASN1_STRING_set().
RETURN VALUES
SEE ALSO
ERR_get_error(3)|ERR_get_error(3)
HISTORY

05 July 2003 3
ASN1_STRING allocation Crypto Library

ASN1_STRING allocation
ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free - ASN1_STRING allocation
functions
SYNOPSIS
ASN1_STRING * ASN1_STRING_new(void);
ASN1_STRING * ASN1_STRING_type_new(int type);
void ASN1_STRING_free(ASN1_STRING *a);
DESCRIPTION
ASN1_STRING_new() returns an allocated ASN1_STRING structure. Its type is undefined.
ASN1_STRING_type_new() returns an allocated ASN1_STRING structure of type type.
ASN1_STRING_free() frees up a.
NOTES
Other string types call the ASN1_STRING functions. For example ASN1_OCTET_STRING_new()
calls ASN1_STRING_type(V_ASN1_OCTET_STRING).
RETURN VALUES
ASN1_STRING_new() and ASN1_STRING_type_new() return a valid ASN1_STRING structure or
NULL if an error occurred.
ASN1_STRING_free() does not return a value.
SEE ALSO
ERR_get_error(3)|ERR_get_error(3)
HISTORY
TBA

4 05 July 2003
Crypto Library ASN1_STRING output

ASN1_STRING output
ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp - ASN1_STRING output routines.
SYNOPSIS
#include <openssl/asn1.h>

int ASN1_STRING_print_ex(BIO *out, ASN1_STRING *str, unsigned long flags);

int ASN1_STRING_print_ex_fp(FILE *fp, ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print(BIO *out, ASN1_STRING *str);
DESCRIPTION
These functions output an ASN1_STRING structure. ASN1_STRING is used to represent all the ASN1
string types.
ASN1_STRING_print_ex() outputs str to out, the format is determined by the options flags.
ASN1_STRING_print_ex_fp() is identical except it outputs to fp instead.
ASN1_STRING_print() prints str to out but using a different format to ASN1_STRING_print_ex(). It
replaces unprintable characters (other than CR, LF) with ’.’.
NOTES
ASN1_STRING_print() is a legacy function which should be avoided in new applications.
Although there are a large number of options frequently ASN1_STRFLAGS_RFC2253 is suitable, or
on UTF8 terminals ASN1_STRFLAGS_RFC2253 & ~ASN1_STRFLAGS_ESC_MSB.
The complete set of supported options for flags is listed below.
Various characters can be escaped. If ASN1_STRFLGS_ESC_2253 is set the characters determined by
RFC2253 are escaped. If ASN1_STRFLGS_ESC_CTRL is set control characters are escaped. If
ASN1_STRFLGS_ESC_MSB is set characters with the MSB set are escaped: this option should not be
used if the terminal correctly interprets UTF8 sequences.
Escaping takes several forms.
If the character being escaped is a 16 bit character then the form "\WXXXX" is used using exactly four
characters for the hex representation. If it is 32 bits then "\UXXXXXXXX" is used using eight
characters of its hex representation. These forms will only be used if UTF8 conversion is not set (see
below).
Printable characters are normally escaped using the backslash ‘\’ character. If
ASN1_STRFLGS_ESC_QUOTE is set then the whole string is instead surrounded by double quote
characters: this is arguably more readable than the backslash notation. Other characters use the "\XX"
using exactly two characters of the hex representation.
If ASN1_STRFLGS_UTF8_CONVERT is set then characters are converted to UTF8 format first. If
the terminal supports the display of UTF8 sequences then this option will correctly display multi byte
characters.
If ASN1_STRFLGS_IGNORE_TYPE is set then the string type is not interpreted at all: everything is
assumed to be one byte per character. This is primarily for debugging purposes and can result in
confusing output in multi character strings.
If ASN1_STRFLGS_SHOW_TYPE is set then the string type itself is printed out before its value (for
example "BMPSTRING"), this actually uses ASN1_tag2str().
The content of a string instead of being interpreted can be "dumped": this just outputs the value of the
string using the form #XXXX using hex format for each octet.
If ASN1_STRFLGS_DUMP_ALL is set then any type is dumped.
Normally non character string types (such as OCTET STRING) are assumed to be one byte per
character, if ASN1_STRFLAGS_DUMP_UNKNOWN is set then they will be dumped instead.
When a type is dumped normally just the content octets are printed, if ASN1_STRFLGS_DUMP_DER
is set then the complete encoding is dumped instead (including tag and length octets).
ASN1_STRFLGS_RFC2253 includes all the flags required by RFC2253. It is equivalent to:
ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB |
ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER
SEE ALSO
X509_NAME_print_ex(3)|X509_NAME_print_ex(3), ASN1_tag2str(3)|ASN1_tag2str(3)

05 July 2003 5
ASN1_STRING output Crypto Library

HISTORY
TBA

6 05 July 2003
Crypto Library BIO - I/O abstraction

BIO - I/O abstraction

BIO - I/O abstraction
SYNOPSIS
#include <openssl/bio.h>

TBA

DESCRIPTION
A BIO is an I/O abstraction, it hides many of the underlying I/O details from an application. If an
application uses a BIO for its I/O it can transparently handle SSL connections, unencrypted network
connections and file I/O.
There are two type of BIO, a source/sink BIO and a filter BIO.
As its name implies a source/sink BIO is a source and/or sink of data, examples include a socket BIO
and a file BIO.
A filter BIO takes data from one BIO and passes it through to another, or the application. The data may
be left unmodified (for example a message digest BIO) or translated (for example an encryption BIO).
The effect of a filter BIO may change according to the I/O operation it is performing: for example an
encryption BIO will encrypt data if it is being written to and decrypt data if it is being read from.
BIOs can be joined together to form a chain (a single BIO is a chain with one component). A chain
normally consist of one source/sink BIO and one or more filter BIOs. Data read from or written to the
first BIO then traverses the chain to the end (normally a source/sink BIO).
SEE ALSO
BIO_ctrl(3)|BIO_ctrl(3), BIO_f_base64(3)|BIO_f_base64(3), BIO_f_buffer(3)|BIO_f_buffer(3),
BIO_f_cipher(3)|BIO_f_cipher(3), BIO_f_md(3)|BIO_f_md(3), BIO_f_null(3)|BIO_f_null(3),
BIO_f_ssl(3)|BIO_f_ssl(3), BIO_find_type(3)|BIO_find_type(3), BIO_new(3)|BIO_new(3),
BIO_new_bio_pair(3)|BIO_new_bio_pair(3), BIO_push(3)|BIO_push(3), BIO_read(3)|BIO_read(3),
BIO_s_accept(3)|BIO_s_accept(3), BIO_s_bio(3)|BIO_s_bio(3), BIO_s_connect(3)|BIO_s_connect(3),
BIO_s_fd(3)|BIO_s_fd(3), BIO_s_file(3)|BIO_s_file(3), BIO_s_mem(3)|BIO_s_mem(3),
BIO_s_null(3)|BIO_s_null(3), BIO_s_socket(3)|BIO_s_socket(3),
BIO_set_callback(3)|BIO_set_callback(3), BIO_should_retry(3)|BIO_should_retry(3)

05 July 2003 7
BIO control Crypto Library

BIO control
BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, BIO_seek, BIO_tell, BIO_flush,
BIO_eof, BIO_set_close, BIO_get_close, BIO_pending, BIO_wpending, BIO_ctrl_pending,
BIO_ctrl_wpending, BIO_get_info_callback, BIO_set_info_callback - BIO control operations
SYNOPSIS
#include <openssl/bio.h>

long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg);

long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *,
int, const char *, int, long, long));
char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg);
long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg);

int BIO_reset(BIO *b);

int BIO_seek(BIO *b, int ofs);
int BIO_tell(BIO *b);
int BIO_flush(BIO *b);
int BIO_eof(BIO *b);
int BIO_set_close(BIO *b,long flag);
int BIO_get_close(BIO *b);
int BIO_pending(BIO *b);
int BIO_wpending(BIO *b);
size_t BIO_ctrl_pending(BIO *b);
size_t BIO_ctrl_wpending(BIO *b);

int BIO_get_info_callback(BIO *b,bio_info_cb **cbp);

int BIO_set_info_callback(BIO *b,bio_info_cb *cb);

typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1,
long arg2, long arg3);
DESCRIPTION
BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl() are BIO "control" operations taking
arguments of various types. These functions are not normally called directly, various macros are used
instead. The standard macros are described below, macros specific to a particular type of BIO are
described in the specific BIOs manual page as well as any special features of the standard calls.
BIO_reset() typically resets a BIO to some initial state, in the case of file related BIOs for example it
rewinds the file pointer to the start of the file.
BIO_seek() resets a file related BIO‘s (that is file descriptor and FILE BIOs) file position pointer to ofs
bytes from start of file.
BIO_tell() returns the current file position of a file related BIO.
BIO_flush() normally writes out any internally buffered data, in some cases it is used to signal EOF and
that no more data will be written.
BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of "EOF" varies according to the BIO
type.
BIO_set_close() sets the BIO b close flag to flag. flag can take the value BIO_CLOSE or
BIO_NOCLOSE. Typically BIO_CLOSE is used in a source/sink BIO to indicate that the underlying
I/O stream should be closed when the BIO is freed.
BIO_get_close() returns the BIOs close flag.
BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() return the number of
pending characters in the BIOs read and write buffers. Not all BIOs support these calls.
BIO_ctrl_pending() and BIO_ctrl_wpending() return a size_t type and are functions, BIO_pending() and
BIO_wpending() are macros which call BIO_ctrl().
RETURN VALUES
BIO_reset() normally returns 1 for success and 0 or -1 for failure. File BIOs are an exception, they return
0 for success and -1 for failure.

8 05 July 2003
Crypto Library BIO control

BIO_seek() and BIO_tell() both return the current file position on success and -1 for failure, except file
BIOs which for BIO_seek() always return 0 for success and -1 for failure.
BIO_flush() returns 1 for success and 0 or -1 for failure.
BIO_eof() returns 1 if EOF has been reached 0 otherwise.
BIO_set_close() always returns 1.
BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE.
BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() return the amount of
pending data.
NOTES
BIO_flush(), because it can write data may return 0 or -1 indicating that the call should be retried later in
a similar manner to BIO_write(). The BIO_should_retry() call should be used and appropriate action
taken is the call fails.
The return values of BIO_pending() and BIO_wpending() may not reliably determine the amount of
pending data in all cases. For example in the case of a file BIO some data may be available in the FILE
structures internal buffers but it is not possible to determine this in a portably way. For other types of
BIO they may not be supported.
Filter BIOs if they do not internally handle a particular BIO_ctrl() operation usually pass the operation to
the next BIO in the chain. This often means there is no need to locate the required BIO for a particular
operation, it can be called on a chain and it will be automatically passed to the relevant BIO. However
this can cause unexpected results: for example no current filter BIOs implement BIO_seek(), but this
may still succeed if the chain ends in a FILE or file descriptor BIO.
Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl() operation.
BUGS
Some of the return values are ambiguous and care should be taken. In particular a return value of 0 can
be returned if an operation is not supported, if an error occurred, if EOF has not been reached and in the
case of BIO_seek() on a file BIO for a successful operation.
SEE ALSO
TBA

05 July 2003 9
BIO chain traversal Crypto Library

BIO chain traversal

BIO_find_type, BIO_next - BIO chain traversal
SYNOPSIS
#include <openssl/bio.h>

BIO * BIO_find_type(BIO *b,int bio_type);

BIO * BIO_next(BIO *b);

#define BIO_method_type(b) ((b)->method->type)

#define BIO_TYPE_NONE 0
#define BIO_TYPE_MEM (1|0x0400)
#define BIO_TYPE_FILE (2|0x0400)

#define BIO_TYPE_FD (4|0x0400|0x0100)

#define BIO_TYPE_SOCKET (5|0x0400|0x0100)
#define BIO_TYPE_NULL (6|0x0400)
#define BIO_TYPE_SSL (7|0x0200)
#define BIO_TYPE_MD (8|0x0200)
#define BIO_TYPE_BUFFER (9|0x0200)
#define BIO_TYPE_CIPHER (10|0x0200)
#define BIO_TYPE_BASE64 (11|0x0200)
#define BIO_TYPE_CONNECT (12|0x0400|0x0100)
#define BIO_TYPE_ACCEPT (13|0x0400|0x0100)
#define BIO_TYPE_PROXY_CLIENT (14|0x0200)
#define BIO_TYPE_PROXY_SERVER (15|0x0200)
#define BIO_TYPE_NBIO_TEST (16|0x0200)
#define BIO_TYPE_NULL_FILTER (17|0x0200)
#define BIO_TYPE_BER (18|0x0200)
#define BIO_TYPE_BIO (19|0x0400)

#define BIO_TYPE_DESCRIPTOR 0x0100

#define BIO_TYPE_FILTER 0x0200
#define BIO_TYPE_SOURCE_SINK 0x0400
DESCRIPTION
The BIO_find_type() searches for a BIO of a given type in a chain, starting at BIO b. If type is a specific
type (such as BIO_TYPE_MEM) then a search is made for a BIO of that type. If type is a general type
(such as BIO_TYPE_SOURCE_SINK) then the next matching BIO of the given general type is
searched for. BIO_find_type() returns the next matching BIO or NULL if none is found.
Note: not all the BIO_TYPE_* types above have corresponding BIO implementations.
BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs in a chain or used in
conjunction with BIO_find_type() to find all BIOs of a certain type.
BIO_method_type() returns the type of a BIO.
RETURN VALUES
BIO_find_type() returns a matching BIO or NULL for no match.
BIO_next() returns the next BIO in a chain.
BIO_method_type() returns the type of the BIO b.
NOTES
BIO_next() was added to OpenSSL 0.9.6 to provide a ‘clean’ way to traverse a BIO chain or find
multiple matches using BIO_find_type(). Previous versions had to use:
next = bio->next_bio;
BUGS
BIO_find_type() in OpenSSL 0.9.5a and earlier could not be safely passed a NULL pointer for the b
argument.

10 05 July 2003
Crypto Library BIO chain traversal

EXAMPLE
Traverse a chain looking for digest BIOs:
BIO *btmp;
btmp = in_bio; /* in_bio is chain to search through */

do {
btmp = BIO_find_type(btmp, BIO_TYPE_MD);
if(btmp == NULL) break; /* Not found */
/* btmp is a digest BIO, do something with it ...*/
...

btmp = BIO_next(btmp);
} while(btmp);
SEE ALSO
TBA

05 July 2003 11
BIO base64 Crypto Library

BIO base64
BIO_f_base64 - base64 BIO filter
SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>

BIO_METHOD * BIO_f_base64(void);
DESCRIPTION
BIO_f_base64() returns the base64 BIO method. This is a filter BIO that base64 encodes any data
written through it and decodes any data read through it.
Base64 BIOs do not support BIO_gets() or BIO_puts().
BIO_flush() on a base64 BIO that is being written through is used to signal that no more data is to be
encoded: this is used to flush the final block through the BIO.
The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags() to encode the data all on one
line or expect the data to be all on one line.
NOTES
Because of the format of base64 encoding the end of the encoded block cannot always be reliably
determined.
RETURN VALUES
BIO_f_base64() returns the base64 BIO method.
EXAMPLES
Base64 encode the string "Hello World\n" and write the result to standard output:
BIO *bio, *b64;
char message[] = "Hello World \n";

b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdout, BIO_NOCLOSE);
bio = BIO_push(b64, bio);
BIO_write(bio, message, strlen(message));
BIO_flush(bio);

BIO_free_all(bio);

Read Base64 encoded data from standard input and write the decoded data to standard output:
BIO *bio, *b64, bio_out;
char inbuf[512];
int inlen;
char message[] = "Hello World \n";

b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdin, BIO_NOCLOSE);
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
bio = BIO_push(b64, bio);
while((inlen = BIO_read(bio, inbuf, strlen(message))) > 0)
BIO_write(bio_out, inbuf, inlen);

BIO_free_all(bio);
BUGS
The ambiguity of EOF in base64 encoded data can cause additional data following the base64 encoded
block to be misinterpreted.
There should be some way of specifying a test that the BIO can perform to reliably determine EOF (for
example a MIME boundary).

12 05 July 2003
Crypto Library BIO base64

SEE ALSO
TBA

05 July 2003 13
BIO buffering Crypto Library

BIO buffering
BIO_f_buffer - buffering BIO
SYNOPSIS
#include <openssl/bio.h>

BIO_METHOD * BIO_f_buffer(void);

#define BIO_get_buffer_num_lines(b) BIO_ctrl(b,

BIO_C_GET_BUFF_NUM_LINES,0,NULL)
#define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,
BIO_C_SET_BUFF_SIZE,size,0)
#define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,
BIO_C_SET_BUFF_SIZE,size,1)
#define BIO_set_buffer_size(b,size) BIO_ctrl(b,
BIO_C_SET_BUFF_SIZE,size,NULL)
#define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,
BIO_C_SET_BUFF_READ_DATA,num,buf)
DESCRIPTION
BIO_f_buffer() returns the buffering BIO method.
Data written to a buffering BIO is buffered and periodically written to the next BIO in the chain. Data
read from a buffering BIO comes from an internal buffer which is filled from the next BIO in the chain.
Both BIO_gets() and BIO_puts() are supported.
Calling BIO_reset() on a buffering BIO clears any buffered data.
BIO_get_buffer_num_lines() returns the number of lines currently buffered.
BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() set the read, write
or both read and write buffer sizes to size. The initial buffer size is DEFAULT_BUFFER_SIZE,
currently 1024. Any attempt to reduce the buffer size below DEFAULT_BUFFER_SIZE is ignored. Any
buffered data is cleared when the buffer is resized.
BIO_set_buffer_read_data() clears the read buffer and fills it with num bytes of buf. If num is larger
than the current buffer size the buffer is expanded.
NOTES
Buffering BIOs implement BIO_gets() by using BIO_read() operations on the next BIO in the chain. By
prepending a buffering BIO to a chain it is therefore possible to provide BIO_gets() functionality if the
following BIOs do not support it (for example SSL BIOs).
Data is only written to the next BIO in the chain when the write buffer fills or when BIO_flush() is
called. It is therefore important to call BIO_flush() whenever any pending data should be written such as
when removing a buffering BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate
source/sink BIO is non blocking.
RETURN VALUES
BIO_f_buffer() returns the buffering BIO method.
BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0).
BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() return 1 if the
buffer was successfully resized or 0 for failure.
BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if there was an error.
SEE ALSO
TBA

14 05 July 2003
Crypto Library BIO cipher

BIO cipher
BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter
SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>

BIO_METHOD * BIO_f_cipher(void);
void BIO_set_cipher(BIO *b,const EVP_CIPHER *cipher,
unsigned char *key, unsigned char *iv, int enc);
int BIO_get_cipher_status(BIO *b)
int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx)
DESCRIPTION
BIO_f_cipher() returns the cipher BIO method. This is a filter BIO that encrypts any data written
through it, and decrypts any data read from it. It is a BIO wrapper for the cipher routines
EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal().
Cipher BIOs do not support BIO_gets() or BIO_puts().
BIO_flush() on an encryption BIO that is being written through is used to signal that no more data is to
be encrypted: this is used to flush and possibly pad the final block through the BIO.
BIO_set_cipher() sets the cipher of BIO <b> to cipher using key key and IV iv. enc should be set to 1
for encryption and zero for decryption.
When reading from an encryption BIO the final block is automatically decrypted and checked when
EOF is detected. BIO_get_cipher_status() is a BIO_ctrl() macro which can be called to determine
whether the decryption operation was successful.
BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal BIO cipher context. The
retrieved context can be used in conjunction with the standard cipher routines to set it up. This is useful
when BIO_set_cipher() is not flexible enough for the applications needs.
NOTES
When encrypting BIO_flush() must be called to flush the final block through the BIO. If it is not then
the final block will fail a subsequent decrypt.
When decrypting an error on the final block is signalled by a zero return value from the read operation.
A successful decrypt followed by EOF will also return zero for the final read. BIO_get_cipher_status()
should be called to determine if the decrypt was successful.
As always, if BIO_gets() or BIO_puts() support is needed then it can be achieved by preceding the
cipher BIO with a buffering BIO.
RETURN VALUES
BIO_f_cipher() returns the cipher BIO method.
BIO_set_cipher() does not return a value.
BIO_get_cipher_status() returns 1 for a successful decrypt and 0 for failure.
BIO_get_cipher_ctx() currently always returns 1.
EXAMPLES
TBA
SEE ALSO
TBA

05 July 2003 15
BIO message digest Crypto Library

BIO message digest

BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter
SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>

BIO_METHOD * BIO_f_md(void);
int BIO_set_md(BIO *b,EVP_MD *md);
int BIO_get_md(BIO *b,EVP_MD **mdp);
int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp);
DESCRIPTION
BIO_f_md() returns the message digest BIO method. This is a filter BIO that digests any data passed
through it, it is a BIO wrapper for the digest routines EVP_DigestInit(), EVP_DigestUpdate() and
EVP_DigestFinal().
Any data written or read through a digest BIO using BIO_read() and BIO_write() is digested.
BIO_gets(), if its size parameter is large enough finishes the digest calculation and returns the digest
value. BIO_puts() is not supported.
BIO_reset() reinitialises a digest BIO.
BIO_set_md() sets the message digest of BIO b to md: this must be called to initialize a digest BIO
before any data is passed through it. It is a BIO_ctrl() macro.
BIO_get_md() places the a pointer to the digest BIOs digest method in mdp, it is a BIO_ctrl() macro.
BIO_get_md_ctx() returns the digest BIOs context into mdcp.
NOTES
The context returned by BIO_get_md_ctx() can be used in calls to EVP_DigestFinal() and also the
signature routines EVP_SignFinal() and EVP_VerifyFinal().
The context returned by BIO_get_md_ctx() is an internal context structure. Changes made to this context
will affect the digest BIO itself and the context pointer will become invalid when the digest BIO is freed.

After the digest has been retrieved from a digest BIO it must be reinitialized by calling BIO_reset(), or
BIO_set_md() before any more data is passed through it.
If an application needs to call BIO_gets() or BIO_puts() through a chain containing digest BIOs then this
can be done by prepending a buffering BIO.
RETURN VALUES
BIO_f_md() returns the digest BIO method.
BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and 0 for failure.
EXAMPLES
The following example creates a BIO chain containing an SHA1 and MD5 digest BIO and passes the
string "Hello World" through it. Error checking has been omitted for clarity.
BIO *bio, *mdtmp;
char message[] = "Hello World";
bio = BIO_new(BIO_s_null());
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_sha1());
/* For BIO_push() we want to append the sink BIO and keep a note of
* the start of the chain.
*/
bio = BIO_push(mdtmp, bio);
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_md5());
bio = BIO_push(mdtmp, bio);
/* Note: mdtmp can now be discarded */
BIO_write(bio, message, strlen(message));

The next example digests data by reading through a chain instead:

16 05 July 2003
Crypto Library BIO message digest

BIO *bio, *mdtmp;

char buf[1024];
int rdlen;
bio = BIO_new_file(file, "rb");
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_sha1());
bio = BIO_push(mdtmp, bio);
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_md5());
bio = BIO_push(mdtmp, bio);
do {
rdlen = BIO_read(bio, buf, sizeof(buf));
/* Might want to do something with the data here */
} while(rdlen > 0);

This next example retrieves the message digests from a BIO chain and outputs them. This could be used
with the examples above.
BIO *mdtmp;
unsigned char mdbuf[EVP_MAX_MD_SIZE];
int mdlen;
int i;
mdtmp = bio; /* Assume bio has previously been set up */
do {
EVP_MD *md;
mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
if(!mdtmp) break;
BIO_get_md(mdtmp, &md);
printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));
mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
printf("\n");
mdtmp = BIO_next(mdtmp);
} while(mdtmp);

BIO_free_all(bio);
BUGS
The lack of support for BIO_puts() and the non standard behaviour of BIO_gets() could be regarded as
anomalous. It could be argued that BIO_gets() and BIO_puts() should be passed to the next BIO in the
chain and digest the data passed through and that digests should be retrieved using a separate BIO_ctrl()
call.
SEE ALSO
TBA

05 July 2003 17
BIO null Crypto Library

BIO null
BIO_f_null - null filter
SYNOPSIS
#include <openssl/bio.h>

BIO_METHOD * BIO_f_null(void);
DESCRIPTION
BIO_f_null() returns the null filter BIO method. This is a filter BIO that does nothing.
All requests to a null filter BIO are passed through to the next BIO in the chain: this means that a BIO
chain containing a null filter BIO behaves just as though the BIO was not there.
NOTES
As may be apparent a null filter BIO is not particularly useful.
RETURN VALUES
BIO_f_null() returns the null filter BIO method.
SEE ALSO
TBA

18 05 July 2003
Crypto Library BIO SSL

BIO SSL
BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes,
BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, BIO_new_ssl_connect,
BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, BIO_ssl_shutdown - SSL BIO
SYNOPSIS
#include <openssl/bio.h>
#include <openssl/ssl.h>

BIO_METHOD *BIO_f_ssl(void);

#define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl)

#define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp)
#define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL)
#define BIO_set_ssl_renegotiate_bytes(b,num) \
BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL);
#define BIO_set_ssl_renegotiate_timeout(b,seconds) \
BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL);
#define BIO_get_num_renegotiates(b) \
BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL);

BIO *BIO_new_ssl(SSL_CTX *ctx,int client);

BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
int BIO_ssl_copy_session_id(BIO *to,BIO *from);
void BIO_ssl_shutdown(BIO *bio);

#define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)

DESCRIPTION
BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which is a wrapper round the OpenSSL
SSL routines adding a BIO "flavour" to SSL I/O.
I/O performed on an SSL BIO communicates using the SSL protocol with the SSLs read and write BIOs.
If an SSL connection is not established then an attempt is made to establish one on the first I/O call.
If a BIO is appended to an SSL BIO using BIO_push() it is automatically used as the SSL BIOs read and
write BIOs.
Calling BIO_reset() on an SSL BIO closes down any current SSL connection by calling
SSL_shutdown(). BIO_reset() is then sent to the next BIO in the chain: this will typically disconnect the
underlying transport. The SSL BIO is then reset to the initial accept or connect state.
If the close flag is set when an SSL BIO is freed then the internal SSL structure is also freed using
SSL_free().
BIO_set_ssl() sets the internal SSL pointer of BIO b to ssl using the close flag c.
BIO_get_ssl() retrieves the SSL pointer of BIO b, it can then be manipulated using the standard SSL
library functions.
BIO_set_ssl_mode() sets the SSL BIO mode to client. If client is 1 client mode is set. If client is 0
server mode is set.
BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count to num. When set after every num bytes
of I/O (read and write) the SSL session is automatically renegotiated. num must be at least 512 bytes.
BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to seconds. When the renegotiate
timeout elapses the session is automatically renegotiated.
BIO_get_num_renegotiates() returns the total number of session renegotiations due to I/O or timeout.
BIO_new_ssl() allocates an SSL BIO using SSL_CTX ctx and using client mode if client is non zero.
BIO_new_ssl_connect() creates a new BIO chain consisting of an SSL BIO (using ctx) followed by a
connect BIO.
BIO_new_buffer_ssl_connect() creates a new BIO chain consisting of a buffering BIO, an SSL BIO
(using ctx) and a connect BIO.
BIO_ssl_copy_session_id() copies an SSL session id between BIO chains from and to. It does this by
locating the SSL BIOs in each chain and calling SSL_copy_session_id() on the internal SSL pointer.

05 July 2003 19
BIO SSL Crypto Library

BIO_ssl_shutdown() closes down an SSL connection on BIO chain bio. It does this by locating the SSL
BIO in the chain and calling SSL_shutdown() on its internal SSL pointer.
BIO_do_handshake() attempts to complete an SSL handshake on the supplied BIO and establish the SSL
connection. It returns 1 if the connection was established successfully. A zero or negative value is
returned if the connection could not be established, the call BIO_should_retry() should be used for non
blocking connect BIOs to determine if the call should be retried. If an SSL connection has already been
established this call has no effect.
NOTES
SSL BIOs are exceptional in that if the underlying transport is non blocking they can still request a retry
in exceptional circumstances. Specifically this will happen if a session renegotiation takes place during a
BIO_read() operation, one case where this happens is when SGC or step up occurs.
In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be set to disable this behaviour. That
is when this flag is set an SSL BIO using a blocking transport will never request a retry.
Since unknown BIO_ctrl() operations are sent through filter BIOs the servers name and port can be set
using BIO_set_host() on the BIO returned by BIO_new_ssl_connect() without having to locate the
connect BIO first.
Applications do not have to call BIO_do_handshake() but may wish to do so to separate the handshake
process from other I/O processing.
RETURN VALUES
TBA
EXAMPLE
This SSL/TLS client example, attempts to retrieve a page from an SSL/TLS web server. The I/O
routines are identical to those of the unencrypted example in BIO_s_connect(3)|BIO_s_connect(3).
BIO *sbio, *out;
int len;
char tmpbuf[1024];
SSL_CTX *ctx;
SSL *ssl;

ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();

/* We would seed the PRNG here if the platform didn’t

* do it automatically
*/

ctx = SSL_CTX_new(SSLv23_client_method());

/* We’d normally set some stuff like the verify paths and
* mode here because as things stand this will connect to
* any server whose certificate is signed by any CA.
*/

sbio = BIO_new_ssl_connect(ctx);

BIO_get_ssl(sbio, &ssl);

if(!ssl) {
fprintf(stderr, "Can’t locate SSL pointer\n");
/* whatever ... */
}

/* Don’t want any retries */

SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);

/* We might want to do other things with ssl here */

20 05 July 2003
Crypto Library BIO SSL

BIO_set_conn_hostname(sbio, "localhost:https");

out = BIO_new_fp(stdout, BIO_NOCLOSE);

if(BIO_do_connect(sbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
}

if(BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error establishing SSL connection\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
}

/* Could examine ssl here to get connection info */

BIO_puts(sbio, "GET / HTTP/1.0\n\n");

for(;;) {
len = BIO_read(sbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(out, tmpbuf, len);
}
BIO_free_all(sbio);
BIO_free(out);

Here is a simple server example. It makes use of a buffering BIO to allow lines to be read from the SSL
BIO using BIO_gets. It creates a pseudo web page containing the actual request from a client and also
echoes the request to standard output.
BIO *sbio, *bbio, *acpt, *out;
int len;
char tmpbuf[1024];
SSL_CTX *ctx;
SSL *ssl;

ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();

/* Might seed PRNG here */

ctx = SSL_CTX_new(SSLv23_server_method());

if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM)
|| !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM)
|| !SSL_CTX_check_private_key(ctx)) {

fprintf(stderr, "Error setting up SSL_CTX\n");

ERR_print_errors_fp(stderr);
return 0;
}

/* Might do other things here like setting verify locations and

* DH and/or RSA temporary key callbacks
*/

/* New SSL BIO setup as server */

sbio=BIO_new_ssl(ctx,0);

05 July 2003 21
BIO SSL Crypto Library

BIO_get_ssl(sbio, &ssl);

if(!ssl) {
fprintf(stderr, "Can’t locate SSL pointer\n");
/* whatever ... */
}

/* Don’t want any retries */

SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);

/* Create the buffering BIO */

bbio = BIO_new(BIO_f_buffer());

/* Add to chain */
sbio = BIO_push(bbio, sbio);

acpt=BIO_new_accept("4433");

/* By doing this when a new connection is established

* we automatically have sbio inserted into it. The
* BIO chain is now ’swallowed’ by the accept BIO and
* will be freed when the accept BIO is freed.
*/

BIO_set_accept_bios(acpt,sbio);

out = BIO_new_fp(stdout, BIO_NOCLOSE);

/* Setup accept BIO */

if(BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error setting up accept BIO\n");
ERR_print_errors_fp(stderr);
return 0;
}

/* Now wait for incoming connection */

if(BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error in connection\n");
ERR_print_errors_fp(stderr);
return 0;
}

/* We only want one connection so remove and free

* accept BIO
*/

sbio = BIO_pop(acpt);

BIO_free_all(acpt);

if(BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error in SSL handshake\n");
ERR_print_errors_fp(stderr);
return 0;
}

BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/html\r\n\r\n");

22 05 July 2003
Crypto Library BIO SSL

BIO_puts(sbio, "<pre>\r\nConnection Established\r\nRequest headers:\r\n");

BIO_puts(sbio, "--------------------------------------------------\r\n");

for(;;) {
len = BIO_gets(sbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(sbio, tmpbuf, len);
BIO_write(out, tmpbuf, len);
/* Look for blank line signifying end of headers*/
if((tmpbuf[0] == ’\r’) || (tmpbuf[0] == ’\n’)) break;
}

BIO_puts(sbio, "--------------------------------------------------\r\n");
BIO_puts(sbio, "</pre>\r\n");

/* Since there is a buffering BIO present we had better flush it */

BIO_flush(sbio);

BIO_free_all(sbio);
SEE ALSO
TBA

05 July 2003 23
BIO allocation Crypto Library

BIO allocation
BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions
SYNOPSIS
#include <openssl/bio.h>

BIO * BIO_new(BIO_METHOD *type);

int BIO_set(BIO *a,BIO_METHOD *type);
int BIO_free(BIO *a);
void BIO_vfree(BIO *a);
void BIO_free_all(BIO *a);
DESCRIPTION
The BIO_new() function returns a new BIO using method type.
BIO_set() sets the method of an already existing BIO.
BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO but it does not return a value.
Calling BIO_free() may also have some effect on the underlying I/O structure, for example it may close
the file being referred to under certain circumstances. For more details see the individual
BIO_METHOD descriptions.
BIO_free_all() frees up an entire BIO chain, it does not halt if an error occurs freeing up an individual
BIO in the chain.
RETURN VALUES
BIO_new() returns a newly created BIO or NULL if the call fails.
BIO_set(), BIO_free() return 1 for success and 0 for failure.
BIO_free_all() and BIO_vfree() do not return values.
NOTES
Some BIOs (such as memory BIOs) can be used immediately after calling BIO_new(). Others (such as
file BIOs) need some additional initialization, and frequently a utility function exists to create and
initialize such BIOs.
If BIO_free() is called on a BIO chain it will only free one BIO resulting in a memory leak.
Calling BIO_free_all() a single BIO has the same effect as calling BIO_free() on it other than the
discarded return value.
Normally the type argument is supplied by a function which returns a pointer to a BIO_METHOD.
There is a naming convention for such functions: a source/sink BIO is normally called BIO_s_*() and a
filter BIO BIO_f_*();
EXAMPLE
Create a memory BIO:
BIO *mem = BIO_new(BIO_s_mem());
SEE ALSO
TBA

24 05 July 2003
Crypto Library BIO chain

BIO chain
BIO_push, BIO_pop - add and remove BIOs from a chain.
SYNOPSIS
#include <openssl/bio.h>

BIO * BIO_push(BIO *b,BIO *append);

BIO * BIO_pop(BIO *b);
DESCRIPTION
The BIO_push() function appends the BIO append to b, it returns b.
BIO_pop() removes the BIO b from a chain and returns the next BIO in the chain, or NULL if there is
no next BIO. The removed BIO then becomes a single BIO with no association with the original chain, it
can thus be freed or attached to a different chain.
NOTES
The names of these functions are perhaps a little misleading. BIO_push() joins two BIO chains whereas
BIO_pop() deletes a single BIO from a chain, the deleted BIO does not need to be at the end of a chain.
The process of calling BIO_push() and BIO_pop() on a BIO may have additional consequences (a
control call is made to the affected BIOs) any effects will be noted in the descriptions of individual
BIOs.
EXAMPLES
For these examples suppose md1 and md2 are digest BIOs, b64 is a base64 BIO and f is a file BIO.
If the call:
BIO_push(b64, f);

is made then the new chain will be b64-chain. After making the calls
BIO_push(md2, b64);
BIO_push(md1, md2);

the new chain is md1-md2-b64-f. Data written to md1 will be digested by md1 and md2, base64
encoded and written to f.
It should be noted that reading causes data to pass in the reverse direction, that is data is read from f,
base64 decoded and digested by md1 and md2. If the call:
BIO_pop(md2);

The call will return b64 and the new chain will be md1-b64-f data can be written to md1 as before.
RETURN VALUES
BIO_push() returns the end of the chain, b.
BIO_pop() returns the next BIO in the chain, or NULL if there is no next BIO.
SEE ALSO
TBA

05 July 2003 25
BIO I/O Crypto Library

BIO I/O
BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
SYNOPSIS
#include <openssl/bio.h>

int BIO_read(BIO *b, void *buf, int len);

int BIO_gets(BIO *b,char *buf, int size);
int BIO_write(BIO *b, const void *buf, int len);
int BIO_puts(BIO *b,const char *buf);
DESCRIPTION
BIO_read() attempts to read len bytes from BIO b and places the data in buf.
BIO_gets() performs the BIOs "gets" operation and places the data in buf. Usually this operation will
attempt to read a line of data from the BIO of maximum length len. There are exceptions to this
however, for example BIO_gets() on a digest BIO will calculate and return the digest and other BIOs
may not support BIO_gets() at all.
BIO_write() attempts to write len bytes from buf to BIO b.
BIO_puts() attempts to write a null terminated string buf to BIO b
RETURN VALUES
All these functions return either the amount of data successfully read or written (if the return value is
positive) or that no data was successfully read or written if the result is 0 or -1. If the return value is -2
then the operation is not implemented in the specific BIO type.
NOTES
A 0 or -1 return is not necessarily an indication of an error. In particular when the source/sink is
non-blocking or of a certain type it may merely be an indication that no data is currently available and
that the application should retry the operation later.
One technique sometimes used with blocking sockets is to use a system call (such as select(), poll() or
equivalent) to determine when data is available and then call read() to read the data. The equivalent with
BIOs (that is call select() on the underlying I/O structure and then call BIO_read() to read the data)
should not be used because a single call to BIO_read() can cause several reads (and writes in the case of
SSL BIOs) on the underlying I/O structure and may block as a result. Instead select() (or equivalent)
should be combined with non blocking I/O so successive reads will request a retry instead of blocking.
See BIO_should_retry(3)|BIO_should_retry(3) for details of how to determine the cause of a retry and
other I/O issues.
If the BIO_gets() function is not supported by a BIO then it possible to work around this by adding a
buffering BIO BIO_f_buffer(3)|BIO_f_buffer(3) to the chain.
SEE ALSO
BIO_should_retry(3)|BIO_should_retry(3)
TBA

26 05 July 2003
Crypto Library BIO callback

BIO callback
BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
BIO_debug_callback - BIO callback functions
SYNOPSIS
#include <openssl/bio.h>

#define BIO_set_callback(b,cb) ((b)->callback=(cb))

#define BIO_get_callback(b) ((b)->callback)
#define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg))
#define BIO_get_callback_arg(b) ((b)->cb_arg)

long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,

long argl,long ret);

typedef long callback(BIO *b, int oper, const char *argp,

int argi, long argl, long retvalue);
DESCRIPTION
BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback, they are both macros. The
callback is called during most high level BIO operations. It can be used for debugging purposes to trace
operations on a BIO or to modify its operation.
BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be used to set and retrieve an
argument for use in the callback.
BIO_debug_callback() is a standard debugging callback which prints out information relating to each
BIO operation. If the callback argument is set if is interpreted as a BIO to send the information to,
otherwise stderr is used.
callback() is the callback function itself. The meaning of each argument is described below.
The BIO the callback is attached to is passed in b.
oper is set to the operation being performed. For some operations the callback is called twice, once
before and once after the actual operation, the latter case has oper or‘ed with BIO_CB_RETURN.
The meaning of the arguments argp, argi and argl depends on the value of oper, that is the operation
being performed.
retvalue is the return value that would be returned to the application if no callback were present. The
actual value returned is the return value of the callback itself. In the case of callbacks called before the
actual BIO operation 1 is placed in retvalue, if the return value is not positive it will be immediately
returned to the application and the BIO operation will not be performed.
The callback should normally simply return retvalue when it has finished processing, unless if
specifically wishes to modify the value returned to the application.
CALLBACK OPERATIONS
BIO_free(b)
callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the free operation.
BIO_read(b, out, outl)
callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before the read and callback(b,
BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue) after.
BIO_write(b, in, inl)
callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before the write and callback(b,
BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue) after.
BIO_gets(b, out, outl)
callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before the operation and callback(b,
BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue) after.
BIO_puts(b, in)
callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before the operation and callback(b,
BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue) after.
BIO_ctrl(BIO *b, int cmd, long larg, void *parg)
callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and
callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.

05 July 2003 27
BIO callback Crypto Library

EXAMPLE
The BIO_debug_callback() function is a good example, its source is in crypto/bio/bio_cb.c
SEE ALSO
TBA

28 05 July 2003
Crypto Library BIO retry

BIO retry
BIO_should_retry, BIO_should_read, BIO_should_write, BIO_should_io_special, BIO_retry_type,
BIO_should_retry, BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions
SYNOPSIS
#include <openssl/bio.h>

#define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ)

#define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE)
#define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL)
#define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS)
#define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY)

#define BIO_FLAGS_READ 0x01

#define BIO_FLAGS_WRITE 0x02
#define BIO_FLAGS_IO_SPECIAL 0x04
#define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)
#define BIO_FLAGS_SHOULD_RETRY 0x08

BIO * BIO_get_retry_BIO(BIO *bio, int *reason);

int BIO_get_retry_reason(BIO *bio);
DESCRIPTION
These functions determine why a BIO is not able to read or write data. They will typically be called after
a failed BIO_read() or BIO_write() call.
BIO_should_retry() is true if the call that produced this condition should then be retried at a later time.
If BIO_should_retry() is false then the cause is an error condition.
BIO_should_read() is true if the cause of the condition is that a BIO needs to read data.
BIO_should_write() is true if the cause of the condition is that a BIO needs to read data.
BIO_should_io_special() is true if some "special" condition, that is a reason other than reading or
writing is the cause of the condition.
BIO_get_retry_reason() returns a mask of the cause of a retry condition consisting of the values
BIO_FLAGS_READ, BIO_FLAGS_WRITE, BIO_FLAGS_IO_SPECIAL though current BIO
types will only set one of these.
BIO_get_retry_BIO() determines the precise reason for the special condition, it returns the BIO that
caused this condition and if reason is not NULL it contains the reason code. The meaning of the reason
code and the action that should be taken depends on the type of BIO that resulted in this condition.
BIO_get_retry_reason() returns the reason for a special condition if passed the relevant BIO, for
example as returned by BIO_get_retry_BIO().
NOTES
If BIO_should_retry() returns false then the precise "error condition" depends on the BIO type that
caused it and the return code of the BIO operation. For example if a call to BIO_read() on a socket BIO
returns 0 and BIO_should_retry() is false then the cause will be that the connection closed. A similar
condition on a file BIO will mean that it has reached EOF. Some BIO types may place additional
information on the error queue. For more details see the individual BIO type manual pages.
If the underlying I/O structure is in a blocking mode almost all current BIO types will not request a retry,
because the underlying I/O calls will not. If the application knows that the BIO type will never signal a
retry then it need not call BIO_should_retry() after a failed BIO I/O call. This is typically done with file
BIOs.
SSL BIOs are the only current exception to this rule: they can request a retry even if the underlying I/O
structure is blocking, if a handshake occurs during a call to BIO_read(). An application can retry the
failed call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY on the
underlying SSL structure.
While an application may retry a failed non blocking call immediately this is likely to be very inefficient
because the call will fail repeatedly until data can be processed or is available. An application will
normally wait until the necessary condition is satisfied. How this is done depends on the underlying I/O
structure.

05 July 2003 29
BIO retry Crypto Library

For example if the cause is ultimately a socket and BIO_should_read() is true then a call to select() may
be made to wait until data is available and then retry the BIO operation. By combining the retry
conditions of several non blocking BIOs in a single select() call it is possible to service several BIOs in a
single thread, though the performance may be poor if SSL BIOs are present because long delays can
occur during the initial handshake process.
It is possible for a BIO to block indefinitely if the underlying I/O structure cannot process or return any
data. This depends on the behaviour of the platforms I/O functions. This is often not desirable: one
solution is to use non blocking I/O and use a timeout on the select() (or equivalent) call.
BUGS
The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O: that is they cannot retry
after a partial read or write. This is usually worked around by only passing the relevant data to ASN1
functions when the entire structure can be read or written.
SEE ALSO
TBA

30 05 July 2003
Crypto Library BIO accept

BIO accept
BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, BIO_set_nbio_accept,
BIO_set_accept_bios, BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO
SYNOPSIS
#include <openssl/bio.h>

BIO_METHOD *BIO_s_accept(void);

long BIO_set_accept_port(BIO *b, char *name);

char *BIO_get_accept_port(BIO *b);

BIO *BIO_new_accept(char *host_port);

long BIO_set_nbio_accept(BIO *b, int n);

long BIO_set_accept_bios(BIO *b, char *bio);

long BIO_set_bind_mode(BIO *b, long mode);

long BIO_get_bind_mode(BIO *b, long dummy);

#define BIO_BIND_NORMAL 0
#define BIO_BIND_REUSEADDR_IF_UNUSED 1
#define BIO_BIND_REUSEADDR 2

int BIO_do_accept(BIO *b);

DESCRIPTION
BIO_s_accept() returns the accept BIO method. This is a wrapper round the platform‘s TCP/IP socket
accept routines.
Using accept BIOs, TCP/IP connections can be accepted and data transferred using only BIO routines. In
this way any platform specific operations are hidden by the BIO abstraction.
Read and write operations on an accept BIO will perform I/O on the underlying connection. If no
connection is established and the port (see below) is set up properly then the BIO waits for an incoming
connection.
Accept BIOs support BIO_puts() but not BIO_gets().
If the close flag is set on an accept BIO then any active connection on that chain is shutdown and the
socket closed when the BIO is freed.
Calling BIO_reset() on a accept BIO will close any active connection and reset the BIO into a state
where it awaits another incoming connection.
BIO_get_fd() and BIO_set_fd() can be called to retrieve or set the accept socket. See
BIO_s_fd(3)|BIO_s_fd(3)
BIO_set_accept_port() uses the string name to set the accept port. The port is represented as a string of
the form "host:port", where "host" is the interface to use and "port" is the port. Either or both values can
be "*" which is interpreted as meaning any interface or port respectively. "port" has the same syntax as
the port specified in BIO_set_conn_port() for connect BIOs, that is it can be a numerical port string or a
string to lookup using getservbyname() and a string table.
BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into a single call: that is it creates a
new accept BIO with port host_port.
BIO_set_nbio_accept() sets the accept socket to blocking mode (the default) if n is 0 or non blocking
mode if n is 1.
BIO_set_accept_bios() can be used to set a chain of BIOs which will be duplicated and prepended to the
chain when an incoming connection is received. This is useful if, for example, a buffering or SSL BIO
is required for each connection. The chain of BIOs must not be freed after this call, they will be
automatically freed when the accept BIO is freed.
BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve the current bind mode. If
BIO_BIND_NORMAL (the default) is set then another socket cannot be bound to the same port. If
BIO_BIND_REUSEADDR is set then other sockets can bind to the same port. If
BIO_BIND_REUSEADDR_IF_UNUSED is set then and attempt is first made to use
BIO_BIN_NORMAL, if this fails and the port is not in use then a second attempt is made using

05 July 2003 31
BIO accept Crypto Library

BIO_BIND_REUSEADDR.
BIO_do_accept() serves two functions. When it is first called, after the accept BIO has been setup, it will
attempt to create the accept socket and bind an address to it. Second and subsequent calls to
BIO_do_accept() will await an incoming connection, or request a retry in non blocking mode.
NOTES
When an accept BIO is at the end of a chain it will await an incoming connection before processing I/O
calls. When an accept BIO is not at then end of a chain it passes I/O calls to the next BIO in the chain.
When a connection is established a new socket BIO is created for the connection and appended to the
chain. That is the chain is now accept-socket. This effectively means that attempting I/O on an initial
accept socket will await an incoming connection then perform I/O on it.
If any additional BIOs have been set using BIO_set_accept_bios() then they are placed between the
socket and the accept BIO, that is the chain will be accept-otherbios-socket.
If a server wishes to process multiple connections (as is normally the case) then the accept BIO must be
made available for further incoming connections. This can be done by waiting for a connection and then
calling:
connection = BIO_pop(accept);

After this call connection will contain a BIO for the recently established connection and accept will
now be a single BIO again which can be used to await further incoming connections. If no further
connections will be accepted the accept can be freed using BIO_free().
If only a single connection will be processed it is possible to perform I/O using the accept BIO itself.
This is often undesirable however because the accept BIO will still accept additional incoming
connections. This can be resolved by using BIO_pop() (see above) and freeing up the accept BIO after
the initial connection.
If the underlying accept socket is non-blocking and BIO_do_accept() is called to await an incoming
connection it is possible for BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this
happens then it is an indication that an accept attempt would block: the application should take
appropriate action to wait until the underlying socket has accepted a connection and retry the call.
BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(),
BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros.
RETURN VALUES
TBA
EXAMPLE
This example accepts two connections on port 4444, sends messages down each and finally closes both
down.
BIO *abio, *cbio, *cbio2;
ERR_load_crypto_strings();
abio = BIO_new_accept("4444");

/* First call to BIO_accept() sets up accept BIO */

if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error setting up accept\n");
ERR_print_errors_fp(stderr);
exit(0);
}

/* Wait for incoming connection */

if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(0);
}
fprintf(stderr, "Connection 1 established\n");
/* Retrieve BIO for connection */
cbio = BIO_pop(abio);
BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n");
fprintf(stderr, "Sent out data on connection 1\n");

32 05 July 2003
Crypto Library BIO accept

/* Wait for another connection */

if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(0);
}
fprintf(stderr, "Connection 2 established\n");
/* Close accept BIO to refuse further connections */
cbio2 = BIO_pop(abio);
BIO_free(abio);
BIO_puts(cbio2, "Connection 2: Sending out Data on second\n");
fprintf(stderr, "Sent out data on connection 2\n");

BIO_puts(cbio, "Connection 1: Second connection established\n");

/* Close the two established connections */
BIO_free(cbio);
BIO_free(cbio2);
SEE ALSO
TBA

05 July 2003 33
BIO pair Crypto Library

BIO pair
BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, BIO_set_write_buf_size,
BIO_get_write_buf_size, BIO_new_bio_pair, BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee,
BIO_get_read_request, BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
SYNOPSIS
#include <openssl/bio.h>

BIO_METHOD *BIO_s_bio(void);

#define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2)

#define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,
0,NULL)
#define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL)

#define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,

BIO_C_SET_WRITE_BUF_SIZE,size,NULL)
#define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,
BIO_C_GET_WRITE_BUF_SIZE,size,NULL)

int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2,

size_t writebuf2);

#define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,

0,NULL)
size_t BIO_ctrl_get_write_guarantee(BIO *b);

#define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL)

size_t BIO_ctrl_get_read_request(BIO *b);

int BIO_ctrl_reset_read_request(BIO *b);

DESCRIPTION
BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink BIOs where data
written to either half of the pair is buffered and can be read from the other half. Both halves must usually
by handled by the same application thread since no locking is done on the internal data structures.
Since BIO chains typically end in a source/sink BIO it is possible to make this one half of a BIO pair and
have all the data processed by the chain under application control.
One typical use of BIO pairs is to place TLS/SSL I/O under application control, this can be used when
the application wishes to use a non standard transport for TLS/SSL or the normal socket routines are
inappropriate.
Calls to BIO_read() will read data from the buffer or request a retry if no data is available.
Calls to BIO_write() will place data in the buffer or request a retry if the buffer is full.
The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to determine the amount of
pending data in the read or write buffer.
BIO_reset() clears any data in the write buffer.
BIO_make_bio_pair() joins two separate BIOs into a connected pair.
BIO_destroy_pair() destroys the association between two connected BIOs. Freeing up any half of the
pair will automatically destroy the association.
BIO_shutdown_wr() is used to close down a BIO b. After this call no further writes on BIO b are
allowed (they will return an error). Reads on the other half of the pair will return any pending data or
EOF when all pending data has been read.
BIO_set_write_buf_size() sets the write buffer size of BIO b to size. If the size is not initialized a default
value is used. This is currently 17K, sufficient for a maximum size TLS record.
BIO_get_write_buf_size() returns the size of the write buffer.
BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and
BIO_set_write_buf_size() to create a connected pair of BIOs bio1, bio2 with write buffer sizes
writebuf1 and writebuf2. If either size is zero then the default size is used. BIO_new_bio_pair() does
not check whether bio1 or bio2 do point to some other BIO, the values are overwritten, BIO_free() is not

34 05 July 2003
Crypto Library BIO pair

called.
BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum length of data that
can be currently written to the BIO. Writes larger than this value will return a value from BIO_write()
less than the amount requested or if the buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a
function whereas BIO_get_write_guarantee() is a macro.
BIO_get_read_request() and BIO_ctrl_get_read_request() return the amount of data requested, or the
buffer size if it is less, if the last read attempt at the other half of the BIO pair failed due to an empty
buffer. This can be used to determine how much data should be written to the BIO so the next read will
succeed: this is most useful in TLS/SSL applications where the amount of data read is usually
meaningful rather than just a buffer size. After a successful read this call will return zero. It also will
return zero once new data has been written satisfying the read request or part of it. Note that
BIO_get_read_request() never returns an amount larger than that returned by
BIO_get_write_guarantee().
BIO_ctrl_reset_read_request() can also be used to reset the value returned by BIO_get_read_request() to
zero.
NOTES
Both halves of a BIO pair should be freed. That is even if one half is implicit freed due to a
BIO_free_all() or SSL_free() call the other half needs to be freed.
When used in bidirectional applications (such as TLS/SSL) care should be taken to flush any data in the
write buffer. This can be done by calling BIO_pending() on the other half of the pair and, if any data is
pending, reading it and sending it to the underlying transport. This must be done before any normal
processing (such as calling select() ) due to a request and BIO_should_read() being true.
To see why this is important consider a case where a request is sent using BIO_write() and a response
read with BIO_read(), this can occur during an TLS/SSL handshake for example. BIO_write() will
succeed and place data in the write buffer. BIO_read() will initially fail and BIO_should_read() will be
true. If the application then waits for data to be available on the underlying transport before flushing the
write buffer it will never succeed because the request was never sent!
RETURN VALUES
BIO_new_bio_pair() returns 1 on success, with the new BIOs available in bio1 and bio2, or 0 on failure,
with NULL pointers stored into the locations for bio1 and bio2. Check the error stack for more
information.
[XXXXX: More return values need to be added here]
EXAMPLE
The BIO pair can be used to have full control over the network access of an application. The application
can call select() on the socket as required without having to go through the SSL-interface.
BIO *internal_bio, *network_bio;
...
BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
SSL_set_bio(ssl, internal_bio, internal_bio);
SSL_operations();
...

application | TLS-engine
| |
+----------> SSL_operations()
| /\ ||
| || \/
| BIO-pair (internal_bio)
+----------< BIO-pair (network_bio)
| |
socket |

...
SSL_free(ssl); /* implicitly frees internal_bio */
BIO_free(network_bio);
...

05 July 2003 35
BIO pair Crypto Library

As the BIO pair will only buffer the data and never directly access the connection, it behaves
non-blocking and will return as soon as the write buffer is full or the read buffer is drained. Then the
application has to flush the write buffer and/or fill the read buffer.
Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO and must be transfered to
the network. Use BIO_ctrl_get_read_request() to find out, how many bytes must be written into the
buffer before the SSL_operation() can successfully be continued.
WARNING
As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ condition, but
there is still data in the write buffer. An application must not rely on the error value of SSL_operation()
but must assure that the write buffer is always flushed first. Otherwise a deadlock may occur as the peer
might be waiting for the data before being able to continue.
SEE ALSO
SSL_set_bio(3)|SSL_set_bio(3), ssl(3)|ssl(3), bio(3)|bio(3), BIO_should_retry(3)|BIO_should_retry(3),
BIO_read(3)|BIO_read(3)

36 05 July 2003
Crypto Library BIO connect

BIO connect
BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port, BIO_set_conn_ip,
BIO_set_conn_int_port, BIO_get_conn_hostname, BIO_get_conn_port, BIO_get_conn_ip,
BIO_get_conn_int_port, BIO_set_nbio, BIO_do_connect - connect BIO
SYNOPSIS
#include <openssl/bio.h>

BIO_METHOD * BIO_s_connect(void);

BIO *BIO_new_connect(char *name);

long BIO_set_conn_hostname(BIO *b, char *name);

long BIO_set_conn_port(BIO *b, char *port);
long BIO_set_conn_ip(BIO *b, char *ip);
long BIO_set_conn_int_port(BIO *b, char *port);
char *BIO_get_conn_hostname(BIO *b);
char *BIO_get_conn_port(BIO *b);
char *BIO_get_conn_ip(BIO *b, dummy);
long BIO_get_conn_int_port(BIO *b, int port);

long BIO_set_nbio(BIO *b, long n);

int BIO_do_connect(BIO *b);

DESCRIPTION
BIO_s_connect() returns the connect BIO method. This is a wrapper round the platform‘s TCP/IP socket
connection routines.
Using connect BIOs, TCP/IP connections can be made and data transferred using only BIO routines. In
this way any platform specific operations are hidden by the BIO abstraction.
Read and write operations on a connect BIO will perform I/O on the underlying connection. If no
connection is established and the port and hostname (see below) is set up properly then a connection is
established first.
Connect BIOs support BIO_puts() but not BIO_gets().
If the close flag is set on a connect BIO then any active connection is shutdown and the socket closed
when the BIO is freed.
Calling BIO_reset() on a connect BIO will close any active connection and reset the BIO into a state
where it can connect to the same host again.
BIO_get_fd() places the underlying socket in c if it is not NULL, it also returns the socket . If c is not
NULL it should be of type (int *).
BIO_set_conn_hostname() uses the string name to set the hostname. The hostname can be an IP address.
The hostname can also include the port in the form hostname:port . It is also acceptable to use the form
"hostname/any/other/path" or "hostname:port/any/other/path".
BIO_set_conn_port() sets the port to port. port can be the numerical form or a string such as "http". A
string will be looked up first using getservbyname() on the host platform but if that fails a standard table
of port names will be used. Currently the list is http, telnet, socks, https, ssl, ftp, gopher and wais.
BIO_set_conn_ip() sets the IP address to ip using binary form, that is four bytes specifying the IP
address in big-endian form.
BIO_set_conn_int_port() sets the port using port. port should be of type (int *).
BIO_get_conn_hostname() returns the hostname of the connect BIO or NULL if the BIO is initialized
but no hostname is set. This return value is an internal pointer which should not be modified.
BIO_get_conn_port() returns the port as a string.
BIO_get_conn_ip() returns the IP address in binary form.
BIO_get_conn_int_port() returns the port as an int.
BIO_set_nbio() sets the non blocking I/O flag to n. If n is zero then blocking I/O is set. If n is 1 then non
blocking I/O is set. Blocking I/O is the default. The call to BIO_set_nbio() should be made before the
connection is established because non blocking I/O is set during the connect process.
BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into a single call: that is it
creates a new connect BIO with name.

05 July 2003 37
BIO connect Crypto Library

BIO_do_connect() attempts to connect the supplied BIO. It returns 1 if the connection was established
successfully. A zero or negative value is returned if the connection could not be established, the call
BIO_should_retry() should be used for non blocking connect BIOs to determine if the call should be
retried.
NOTES
If blocking I/O is set then a non positive return value from any I/O call is caused by an error condition,
although a zero return will normally mean that the connection was closed.
If the port name is supplied as part of the host name then this will override any value set with
BIO_set_conn_port(). This may be undesirable if the application does not wish to allow connection to
arbitrary ports. This can be avoided by checking for the presence of the ‘:’ character in the passed
hostname and either indicating an error or truncating the string at that point.
The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(), BIO_get_conn_ip() and
BIO_get_conn_int_port() are updated when a connection attempt is made. Before any connection
attempt the values returned are those set by the application itself.
Applications do not have to call BIO_do_connect() but may wish to do so to separate the connection
process from other I/O processing.
If non blocking I/O is set then retries will be requested as appropriate.
It addition to BIO_should_read() and BIO_should_write() it is also possible for
BIO_should_io_special() to be true during the initial connection process with the reason
BIO_RR_CONNECT. If this is returned then this is an indication that a connection attempt would block,
the application should then take appropriate action to wait until the underlying socket has connected and
retry the call.
BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(), BIO_set_conn_int_port(),
BIO_get_conn_hostname(), BIO_get_conn_port(), BIO_get_conn_ip(), BIO_get_conn_int_port(),
BIO_set_nbio() and BIO_do_connect() are macros.
RETURN VALUES
BIO_s_connect() returns the connect BIO method.
BIO_get_fd() returns the socket or -1 if the BIO has not been initialized.
BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and BIO_set_conn_int_port()
always return 1.
BIO_get_conn_hostname() returns the connected hostname or NULL is none was set.
BIO_get_conn_port() returns a string representing the connected port or NULL if not set.
BIO_get_conn_ip() returns a pointer to the connected IP address in binary form or all zeros if not set.
BIO_get_conn_int_port() returns the connected port or 0 if none was set.
BIO_set_nbio() always returns 1.
BIO_do_connect() returns 1 if the connection was successfully established and 0 or -1 if the connection
failed.
EXAMPLE
This is example connects to a webserver on the local host and attempts to retrieve a page and copy the
result to standard output.

BIO *cbio, *out;

int len;
char tmpbuf[1024];
ERR_load_crypto_strings();
cbio = BIO_new_connect("localhost:http");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if(BIO_do_connect(cbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
}
BIO_puts(cbio, "GET / HTTP/1.0\n\n");
for(;;) {
len = BIO_read(cbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(out, tmpbuf, len);

38 05 July 2003
Crypto Library BIO connect

}
BIO_free(cbio);
BIO_free(out);
SEE ALSO
TBA

05 July 2003 39
BIO file decscriptor Crypto Library

BIO file decscriptor

BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
SYNOPSIS
#include <openssl/bio.h>

BIO_METHOD * BIO_s_fd(void);

#define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd)

#define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c)

BIO *BIO_new_fd(int fd, int close_flag);

DESCRIPTION
BIO_s_fd() returns the file descriptor BIO method. This is a wrapper round the platforms file descriptor
routines such as read() and write().
BIO_read() and BIO_write() read or write the underlying descriptor. BIO_puts() is supported but
BIO_gets() is not.
If the close flag is set then then close() is called on the underlying file descriptor when the BIO is freed.
BIO_reset() attempts to change the file pointer to the start of file using lseek(fd, 0, 0).
BIO_seek() sets the file pointer to position ofs from start of file using lseek(fd, ofs, 0).
BIO_tell() returns the current file position by calling lseek(fd, 0, 1).
BIO_set_fd() sets the file descriptor of BIO b to fd and the close flag to c.
BIO_get_fd() places the file descriptor in c if it is not NULL, it also returns the file descriptor. If c is not
NULL it should be of type (int *).
BIO_new_fd() returns a file descriptor BIO using fd and close_flag.
NOTES
The behaviour of BIO_read() and BIO_write() depends on the behavior of the platforms read() and
write() calls on the descriptor. If the underlying file descriptor is in a non blocking mode then the BIO
will behave in the manner described in the BIO_read(3)|BIO_read(3) and
BIO_should_retry(3)|BIO_should_retry(3) manual pages.
File descriptor BIOs should not be used for socket I/O. Use socket BIOs instead.
RETURN VALUES
BIO_s_fd() returns the file descriptor BIO method.
BIO_reset() returns zero for success and -1 if an error occurred. BIO_seek() and BIO_tell() return the
current file position or -1 is an error occurred. These values reflect the underlying lseek() behaviour.
BIO_set_fd() always returns 1.
BIO_get_fd() returns the file descriptor or -1 if the BIO has not been initialized.
BIO_new_fd() returns the newly allocated BIO or NULL is an error occurred.
EXAMPLE
This is a file descriptor BIO version of "Hello World":
BIO *out;
out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
BIO_printf(out, "Hello World\n");
BIO_free(out);
SEE ALSO
BIO_seek(3)|BIO_seek(3), BIO_tell(3)|BIO_tell(3), BIO_reset(3)|BIO_reset(3),
BIO_read(3)|BIO_read(3), BIO_write(3)|BIO_write(3), BIO_puts(3)|BIO_puts(3),
BIO_gets(3)|BIO_gets(3), BIO_printf(3)|BIO_printf(3), BIO_set_close(3)|BIO_set_close(3),
BIO_get_close(3)|BIO_get_close(3)

40 05 July 2003
Crypto Library BIO file

BIO file
BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp, BIO_read_filename,
BIO_write_filename, BIO_append_filename, BIO_rw_filename - BIO file
SYNOPSIS
#include <openssl/bio.h>

BIO_METHOD * BIO_s_file(void);
BIO *BIO_new_file(const char *filename, const char *mode);
BIO *BIO_new_fp(FILE *stream, int flags);

BIO_set_fp(BIO *b,FILE *fp, int flags);

BIO_get_fp(BIO *b,FILE **fpp);

int BIO_read_filename(BIO *b, char *name)

int BIO_write_filename(BIO *b, char *name)
int BIO_append_filename(BIO *b, char *name)
int BIO_rw_filename(BIO *b, char *name)
DESCRIPTION
BIO_s_file() returns the BIO file method. As its name implies it is a wrapper round the stdio FILE
structure and it is a source/sink BIO.
Calls to BIO_read() and BIO_write() read and write data to the underlying stream. BIO_gets() and
BIO_puts() are supported on file BIOs.
BIO_flush() on a file BIO calls the fflush() function on the wrapped stream.
BIO_reset() attempts to change the file pointer to the start of file using fseek(stream, 0, 0).
BIO_seek() sets the file pointer to position ofs from start of file using fseek(stream, ofs, 0).
BIO_eof() calls feof().
Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO is freed.
BIO_new_file() creates a new file BIO with mode mode the meaning of mode is the same as the stdio
function fopen(). The BIO_CLOSE flag is set on the returned BIO.
BIO_new_fp() creates a file BIO wrapping stream. Flags can be: BIO_CLOSE, BIO_NOCLOSE (the
close flag) BIO_FP_TEXT (sets the underlying stream to text mode, default is binary: this only has any
effect under Win32).
BIO_set_fp() set the fp of a file BIO to fp. flags has the same meaning as in BIO_new_fp(), it is a
macro.
BIO_get_fp() retrieves the fp of a file BIO, it is a macro.
BIO_seek() is a macro that sets the position pointer to offset bytes from the start of file.
BIO_tell() returns the value of the position pointer.
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and BIO_rw_filename() set the
file BIO b to use file name for reading, writing, append or read write respectively.
NOTES
When wrapping stdout, stdin or stderr the underlying stream should not normally be closed so the
BIO_NOCLOSE flag should be set.
Because the file BIO calls the underlying stdio functions any quirks in stdio behaviour will be mirrored
by the corresponding BIO.
EXAMPLES
File BIO "hello world":
BIO *bio_out;
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
BIO_printf(bio_out, "Hello World\n");

Alternative technique:
BIO *bio_out;
bio_out = BIO_new(BIO_s_file());
if(bio_out == NULL) /* Error ... */
if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
BIO_printf(bio_out, "Hello World\n");

05 July 2003 41
BIO file Crypto Library

Write to a file:
BIO *out;
out = BIO_new_file("filename.txt", "w");
if(!out) /* Error occurred */
BIO_printf(out, "Hello World\n");
BIO_free(out);

Alternative technique:
BIO *out;
out = BIO_new(BIO_s_file());
if(out == NULL) /* Error ... */
if(!BIO_write_filename(out, "filename.txt")) /* Error ... */
BIO_printf(out, "Hello World\n");
BIO_free(out);
RETURN VALUES
BIO_s_file() returns the file BIO method.
BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error occurred.
BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure (although the current implementation
never return 0).
BIO_seek() returns the same value as the underlying fseek() function: 0 for success or -1 for failure.
BIO_tell() returns the current file position.
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and BIO_rw_filename() return 1
for success or 0 for failure.
BUGS
BIO_reset() and BIO_seek() are implemented using fseek() on the underlying stream. The return value
for fseek() is 0 for success or -1 if an error occurred this differs from other types of BIO which will
typically return 1 for success and a non positive value if an error occurred.
SEE ALSO
BIO_seek(3)|BIO_seek(3), BIO_tell(3)|BIO_tell(3), BIO_reset(3)|BIO_reset(3),
BIO_flush(3)|BIO_flush(3), BIO_read(3)|BIO_read(3), BIO_write(3)|BIO_write(3),
BIO_puts(3)|BIO_puts(3), BIO_gets(3)|BIO_gets(3), BIO_printf(3)|BIO_printf(3),
BIO_set_close(3)|BIO_set_close(3), BIO_get_close(3)|BIO_get_close(3)

42 05 July 2003
Crypto Library BIO memory

BIO memory
BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, BIO_get_mem_ptr,
BIO_new_mem_buf - memory BIO
SYNOPSIS
#include <openssl/bio.h>

BIO_METHOD * BIO_s_mem(void);

BIO_set_mem_eof_return(BIO *b,int v)
long BIO_get_mem_data(BIO *b, char **pp)
BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c)
BIO_get_mem_ptr(BIO *b,BUF_MEM **pp)

BIO *BIO_new_mem_buf(void *buf, int len);

DESCRIPTION
BIO_s_mem() return the memory BIO method function.
A memory BIO is a source/sink BIO which uses memory for its I/O. Data written to a memory BIO is
stored in a BUF_MEM structure which is extended as appropriate to accommodate the stored data.
Any data written to a memory BIO can be recalled by reading from it. Unless the memory BIO is read
only any data read from it is deleted from the BIO.
Memory BIOs support BIO_gets() and BIO_puts().
If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying BUF_MEM structure is
also freed.
Calling BIO_reset() on a read write memory BIO clears any data in it. On a read only BIO it restores the
BIO to its original state and the read only data can be read again.
BIO_eof() is true if no data is in the BIO.
BIO_ctrl_pending() returns the number of bytes currently stored.
BIO_set_mem_eof_return() sets the behaviour of memory BIO b when it is empty. If the v is zero then
an empty memory BIO will return EOF (that is it will return zero and BIO_should_retry(b) will be false.
If v is non zero then it will return v when it is empty and it will set the read retry flag (that is
BIO_read_retry(b) is true). To avoid ambiguity with a normal positive return value v should be set to a
negative value, typically -1.
BIO_get_mem_data() sets pp to a pointer to the start of the memory BIOs data and returns the total
amount of data available. It is implemented as a macro.
BIO_set_mem_buf() sets the internal BUF_MEM structure to bm and sets the close flag to c, that is c
should be either BIO_CLOSE or BIO_NOCLOSE. It is a macro.
BIO_get_mem_ptr() places the underlying BUF_MEM structure in pp. It is a macro.
BIO_new_mem_buf() creates a memory BIO using len bytes of data at buf, if len is -1 then the buf is
assumed to be null terminated and its length is determined by strlen. The BIO is set to a read only state
and as a result cannot be written to. This is useful when some data needs to be made available from a
static area of memory in the form of a BIO. The supplied data is read directly from the supplied buffer: it
is not copied first, so the supplied area of memory must be unchanged until the BIO is freed.
NOTES
Writes to memory BIOs will always succeed if memory is available: that is their size can grow
indefinitely.
Every read from a read write memory BIO will remove the data just read with an internal copy
operation, if a BIO contains a lots of data and it is read in small chunks the operation can be very slow.
The use of a read only memory BIO avoids this problem. If the BIO must be read write then adding a
buffering BIO to the chain will speed up the process.
BUGS
There should be an option to set the maximum size of a memory BIO.
There should be a way to "rewind" a read write BIO without destroying its contents.
The copying operation should not occur after every small read of a large BIO to improve efficiency.

05 July 2003 43
BIO memory Crypto Library

EXAMPLE
Create a memory BIO and write some data to it:
BIO *mem = BIO_new(BIO_s_mem());
BIO_puts(mem, "Hello World\n");

Create a read only memory BIO:

char data[] = "Hello World";
BIO *mem;
mem = BIO_new_mem_buf(data, -1);

Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
BUF_MEM *bptr;
BIO_get_mem_ptr(mem, &bptr);
BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
BIO_free(mem);
SEE ALSO
TBA

44 05 July 2003
Crypto Library BIO null

BIO null
BIO_s_null - null data sink
SYNOPSIS
#include <openssl/bio.h>

BIO_METHOD * BIO_s_null(void);
DESCRIPTION
BIO_s_null() returns the null sink BIO method. Data written to the null sink is discarded, reads return
EOF.
NOTES
A null sink BIO behaves in a similar manner to the Unix /dev/null device.
A null bio can be placed on the end of a chain to discard any data passed through it.
A null sink is useful if, for example, an application wishes to digest some data by writing through a
digest bio but not send the digested data anywhere. Since a BIO chain must normally include a
source/sink BIO this can be achieved by adding a null sink BIO to the end of the chain
RETURN VALUES
BIO_s_null() returns the null sink BIO method.
SEE ALSO
TBA

05 July 2003 45
BIO socket Crypto Library

BIO socket
BIO_s_socket, BIO_new_socket - socket BIO
SYNOPSIS
#include <openssl/bio.h>

BIO_METHOD *BIO_s_socket(void);

long BIO_set_fd(BIO *b, int fd, long close_flag);

long BIO_get_fd(BIO *b, int *c);

BIO *BIO_new_socket(int sock, int close_flag);

DESCRIPTION
BIO_s_socket() returns the socket BIO method. This is a wrapper round the platform‘s socket routines.
BIO_read() and BIO_write() read or write the underlying socket. BIO_puts() is supported but
BIO_gets() is not.
If the close flag is set then the socket is shut down and closed when the BIO is freed.
BIO_set_fd() sets the socket of BIO b to fd and the close flag to close_flag.
BIO_get_fd() places the socket in c if it is not NULL, it also returns the socket. If c is not NULL it
should be of type (int *).
BIO_new_socket() returns a socket BIO using sock and close_flag.
NOTES
Socket BIOs also support any relevant functionality of file descriptor BIOs.
The reason for having separate file descriptor and socket BIOs is that on some platforms sockets are not
file descriptors and use distinct I/O routines, Windows is one such platform. Any code mixing the two
will not work on all platforms.
BIO_set_fd() and BIO_get_fd() are macros.
RETURN VALUES
BIO_s_socket() returns the socket BIO method.
BIO_set_fd() always returns 1.
BIO_get_fd() returns the socket or -1 if the BIO has not been initialized.
BIO_new_socket() returns the newly allocated BIO or NULL is an error occurred.
SEE ALSO
TBA

46 05 July 2003
Crypto Library Blowfish encryption

Blowfish encryption
blowfish, BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, BF_cfb64_encrypt,
BF_ofb64_encrypt, BF_options - Blowfish encryption
SYNOPSIS
#include <openssl/blowfish.h>

void BF_set_key(BF_KEY *key, int len, const unsigned char *data);

void BF_ecb_encrypt(const unsigned char *in, unsigned char *out,

BF_KEY *key, int enc);
void BF_cbc_encrypt(const unsigned char *in, unsigned char *out,
long length, BF_KEY *schedule, unsigned char *ivec, int enc);
void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out,
long length, BF_KEY *schedule, unsigned char *ivec, int *num,
int enc);
void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out,
long length, BF_KEY *schedule, unsigned char *ivec, int *num);
const char *BF_options(void);

void BF_encrypt(BF_LONG *data,const BF_KEY *key);

void BF_decrypt(BF_LONG *data,const BF_KEY *key);
DESCRIPTION
This library implements the Blowfish cipher, which was invented and described by Counterpane (see
http://www.counterpane.com/blowfish.html ).
Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data. It uses a variable size key, but
typically, 128 bit (16 byte) keys are a considered good for strong encryption. Blowfish can be used in
the same modes as DES (see des_modes(7)|des_modes(7)). Blowfish is currently one of the faster block
ciphers. It is quite a bit faster than DES, and much faster than IDEA or RC2.
Blowfish consists of a key setup phase and the actual encryption or decryption phase.
BF_set_key() sets up the BF_KEY key using the len bytes long key at data.
BF_ecb_encrypt() is the basic Blowfish encryption and decryption function. It encrypts or decrypts the
first 64 bits of in using the key key, putting the result in out. enc decides if encryption
(BF_ENCRYPT) or decryption (BF_DECRYPT) shall be performed. The vector pointed at by in and
out must be 64 bits in length, no less. If they are larger, everything after the first 64 bits is ignored.
The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt() all operate on
variable length data. They all take an initialization vector ivec which needs to be passed along into the
next call of the same function for the same message. ivec may be initialized with anything, but the
recipient needs to know what it was initialized with, or it won‘t be able to decrypt. Some programs and
protocols simplify this, like SSH, where ivec is simply initialized to zero. BF_cbc_encrypt() operates on
data that is a multiple of 8 bytes long, while BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to
encrypt an variable number of bytes (the amount does not have to be an exact multiple of 8). The
purpose of the latter two is to simulate stream ciphers, and therefore, they need the parameter num,
which is a pointer to an integer where the current offset in ivec is stored between calls. This integer
must be initialized to zero when ivec is initialized.
BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It encrypts or decrypts the 64
bits chunks of in using the key schedule, putting the result in out. enc decides if encryption
(BF_ENCRYPT) or decryption (BF_DECRYPT) shall be performed. ivec must point at an 8 byte long
initialization vector.
BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback. It encrypts or decrypts the
bytes in in using the key schedule, putting the result in out. enc decides if encryption (BF_ENCRYPT)
or decryption (BF_DECRYPT) shall be performed. ivec must point at an 8 byte long initialization
vector. num must point at an integer which must be initially zero.
BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback. It uses the same parameters as
BF_cfb64_encrypt(), which must be initialized the same way.
BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish encryption. They
encrypt/decrypt the first 64 bits of the vector pointed by data, using the key key. These functions
should not be used unless you implement ‘modes’ of Blowfish. The alternative is to use

05 July 2003 47
Blowfish encryption Crypto Library

BF_ecb_encrypt(). If you still want to use these functions, you should be aware that they take each
32-bit chunk in host-byte order, which is little-endian on little-endian platforms and big-endian on
big-endian ones.
RETURN VALUES
None of the functions presented here return any value.
NOTE
Applications should use the higher level functions EVP_EncryptInit(3)|EVP_EncryptInit(3) etc. instead
of calling the blowfish functions directly.
SEE ALSO
des_modes(7)|des_modes(7)
HISTORY
The Blowfish functions are available in all versions of SSLeay and OpenSSL.

48 05 July 2003
Crypto Library BN multiprecision integer

BN multiprecision integer
BN - multiprecision integer arithmetics
SYNOPSIS
#include <openssl/bn.h>

BIGNUM *BN_new(void);
void BN_free(BIGNUM *a);
void BN_init(BIGNUM *);
void BN_clear(BIGNUM *a);
void BN_clear_free(BIGNUM *a);

BN_CTX *BN_CTX_new(void);
void BN_CTX_init(BN_CTX *c);
void BN_CTX_free(BN_CTX *c);

BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b);

BIGNUM *BN_dup(const BIGNUM *a);

BIGNUM *BN_swap(BIGNUM *a, BIGNUM *b);

int BN_num_bytes(const BIGNUM *a);

int BN_num_bits(const BIGNUM *a);
int BN_num_bits_word(BN_ULONG w);

int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);

int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
BN_CTX *ctx);
int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
int BN_nnmod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
int BN_mod_add(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
BN_CTX *ctx);
int BN_mod_sub(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
BN_CTX *ctx);
int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
BN_CTX *ctx);
int BN_mod_sqr(BIGNUM *ret, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx);
int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
const BIGNUM *m, BN_CTX *ctx);
int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);

int BN_add_word(BIGNUM *a, BN_ULONG w);

int BN_sub_word(BIGNUM *a, BN_ULONG w);
int BN_mul_word(BIGNUM *a, BN_ULONG w);
BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);
BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w);

int BN_cmp(BIGNUM *a, BIGNUM *b);

int BN_ucmp(BIGNUM *a, BIGNUM *b);
int BN_is_zero(BIGNUM *a);
int BN_is_one(BIGNUM *a);
int BN_is_word(BIGNUM *a, BN_ULONG w);
int BN_is_odd(BIGNUM *a);

int BN_zero(BIGNUM *a);

05 July 2003 49
BN multiprecision integer Crypto Library

int BN_one(BIGNUM *a);

const BIGNUM *BN_value_one(void);
int BN_set_word(BIGNUM *a, unsigned long w);
unsigned long BN_get_word(BIGNUM *a);

int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);

int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range);

BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add,

BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg);
int BN_is_prime(const BIGNUM *p, int nchecks,
void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);

int BN_set_bit(BIGNUM *a, int n);

int BN_clear_bit(BIGNUM *a, int n);
int BN_is_bit_set(const BIGNUM *a, int n);
int BN_mask_bits(BIGNUM *a, int n);
int BN_lshift(BIGNUM *r, const BIGNUM *a, int n);
int BN_lshift1(BIGNUM *r, BIGNUM *a);
int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
int BN_rshift1(BIGNUM *r, BIGNUM *a);

int BN_bn2bin(const BIGNUM *a, unsigned char *to);

BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
char *BN_bn2hex(const BIGNUM *a);
char *BN_bn2dec(const BIGNUM *a);
int BN_hex2bn(BIGNUM **a, const char *str);
int BN_dec2bn(BIGNUM **a, const char *str);
int BN_print(BIO *fp, const BIGNUM *a);
int BN_print_fp(FILE *fp, const BIGNUM *a);
int BN_bn2mpi(const BIGNUM *a, unsigned char *to);
BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);

BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,

BN_CTX *ctx);

BN_RECP_CTX *BN_RECP_CTX_new(void);
void BN_RECP_CTX_init(BN_RECP_CTX *recp);
void BN_RECP_CTX_free(BN_RECP_CTX *recp);
int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);
int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b,
BN_RECP_CTX *recp, BN_CTX *ctx);

BN_MONT_CTX *BN_MONT_CTX_new(void);
void BN_MONT_CTX_init(BN_MONT_CTX *ctx);
void BN_MONT_CTX_free(BN_MONT_CTX *mont);
int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);
BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);
int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,
BN_MONT_CTX *mont, BN_CTX *ctx);
int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
BN_CTX *ctx);
int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
BN_CTX *ctx);

50 05 July 2003
Crypto Library BN multiprecision integer

DESCRIPTION
This library performs arithmetic operations on integers of arbitrary size. It was written for use in public
key cryptography, such as RSA and Diffie-Hellman.
It uses dynamic memory allocation for storing its data structures. That means that there is no limit on the
size of the numbers manipulated by these functions, but return values must always be checked in case a
memory allocation error has occurred.
The basic object in this library is a BIGNUM. It is used to hold a single large integer. This type should
be considered opaque and fields should not be modified or accessed directly.
The creation of BIGNUM objects is described in BN_new(3)|BN_new(3); BN_add(3)|BN_add(3)
describes most of the arithmetic operations. Comparison is described in BN_cmp(3)|BN_cmp(3);
BN_zero(3)|BN_zero(3) describes certain assignments, BN_rand(3)|BN_rand(3) the generation of
random numbers, BN_generate_prime(3)|BN_generate_prime(3) deals with prime numbers and
BN_set_bit(3)|BN_set_bit(3) with bit operations. The conversion of BIGNUMs to external formats is
described in BN_bn2bin(3)|BN_bn2bin(3).
SEE ALSO
bn_internal(3)|bn_internal(3), dh(3)|dh(3), err(3)|err(3), rand(3)|rand(3), rsa(3)|rsa(3),
BN_new(3)|BN_new(3), BN_CTX_new(3)|BN_CTX_new(3), BN_copy(3)|BN_copy(3),
BN_swap(3)|BN_swap(3), BN_num_bytes(3)|BN_num_bytes(3), BN_add(3)|BN_add(3),
BN_add_word(3)|BN_add_word(3), BN_cmp(3)|BN_cmp(3), BN_zero(3)|BN_zero(3),
BN_rand(3)|BN_rand(3), BN_generate_prime(3)|BN_generate_prime(3), BN_set_bit(3)|BN_set_bit(3),
BN_bn2bin(3)|BN_bn2bin(3), BN_mod_inverse(3)|BN_mod_inverse(3),
BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3),
BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)

05 July 2003 51
BIGNUM operations Crypto Library

BIGNUM operations
BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add, BN_mod_sub,
BN_mod_mul, BN_mod_sqr, BN_exp, BN_mod_exp, BN_gcd - arithmetic operations on BIGNUMs
SYNOPSIS
#include <openssl/bn.h>

int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);

int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);

int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);

int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);

int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
BN_CTX *ctx);

int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);

int BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);

int BN_mod_add(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
BN_CTX *ctx);

int BN_mod_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
BN_CTX *ctx);

int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
BN_CTX *ctx);

int BN_mod_sqr(BIGNUM *r, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);

int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx);

int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p,

const BIGNUM *m, BN_CTX *ctx);

int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);

DESCRIPTION
BN_add() adds a and b and places the result in r (r=a+b). r may be the same BIGNUM as a or b.
BN_sub() subtracts b from a and places the result in r (r=a-b).
BN_mul() multiplies a and b and places the result in r (r=a*b). r may be the same BIGNUM as a or b.
For multiplication by powers of 2, use BN_lshift(3)|BN_lshift(3).
BN_sqr() takes the square of a and places the result in r (r=a^2). r and a may be the same BIGNUM.
This function is faster than BN_mul(r,a,a).
BN_div() divides a by d and places the result in dv and the remainder in rem (dv=a/d, rem=a%d).
Either of dv and rem may be NULL, in which case the respective value is not returned. The result is
rounded towards zero; thus if a is negative, the remainder will be zero or negative. For division by
powers of 2, use BN_rshift(3).
BN_mod() corresponds to BN_div() with dv set to NULL.
BN_nnmod() reduces a modulo m and places the non-negative remainder in r.
BN_mod_add() adds a to b modulo m and places the non-negative result in r.
BN_mod_sub() subtracts b from a modulo m and places the non-negative result in r.
BN_mod_mul() multiplies a by b and finds the non-negative remainder respective to modulus m
(r=(a*b) mod m). r may be the same BIGNUM as a or b. For more efficient algorithms for repeated
computations using the same modulus, see BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)
and BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3).

52 05 July 2003
Crypto Library BIGNUM operations

BN_mod_sqr() takes the square of a modulo m and places the result in r.

BN_exp() raises a to the p-th power and places the result in r (r=a^p). This function is faster than
repeated applications of BN_mul().
BN_mod_exp() computes a to the p-th power modulo m (r=a^p % m). This function uses less time
and space than BN_exp().
BN_gcd() computes the greatest common divisor of a and b and places the result in r. r may be the same
BIGNUM as a or b.
For all functions, ctx is a previously allocated BN_CTX used for temporary variables; see
BN_CTX_new(3)|BN_CTX_new(3).
Unless noted otherwise, the result BIGNUM must be different from the arguments.
RETURN VALUES
For all functions, 1 is returned for success, 0 on error. The return value should always be checked (e.g.,
if (!BN_add(r,a,b)) goto err;). The error codes can be obtained by
ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
bn(3)|bn(3), ERR_get_error(3)|ERR_get_error(3), BN_CTX_new(3)|BN_CTX_new(3),
BN_add_word(3)|BN_add_word(3), BN_set_bit(3)|BN_set_bit(3)
HISTORY
BN_add(), BN_sub(), BN_sqr(), BN_div(), BN_mod(), BN_mod_mul(), BN_mod_exp() and BN_gcd()
are available in all versions of SSLeay and OpenSSL. The ctx argument to BN_mul() was added in
SSLeay 0.9.1b. BN_exp() appeared in SSLeay 0.9.0. BN_nnmod(), BN_mod_add(), BN_mod_sub(),
and BN_mod_sqr() were added in OpenSSL 0.9.7.

05 July 2003 53
BIGNUM functions Crypto Library

BIGNUM functions
BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word - arithmetic functions on
BIGNUMs with integers
SYNOPSIS
#include <openssl/bn.h>

int BN_add_word(BIGNUM *a, BN_ULONG w);

int BN_sub_word(BIGNUM *a, BN_ULONG w);

int BN_mul_word(BIGNUM *a, BN_ULONG w);

BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);

BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w);

DESCRIPTION
These functions perform arithmetic operations on BIGNUMs with unsigned integers. They are much
more efficient than the normal BIGNUM arithmetic operations.
BN_add_word() adds w to a (a+=w).
BN_sub_word() subtracts w from a (a-=w).
BN_mul_word() multiplies a and w (a*=b).
BN_div_word() divides a by w (a/=w) and returns the remainder.
BN_mod_word() returns the remainder of a divided by w (a%m).
For BN_div_word() and BN_mod_word(), w must not be 0.
RETURN VALUES
BN_add_word(), BN_sub_word() and BN_mul_word() return 1 for success, 0 on error. The error codes
can be obtained by ERR_get_error(3)|ERR_get_error(3).
BN_mod_word() and BN_div_word() return a%w.
SEE ALSO
bn(3)|bn(3), ERR_get_error(3)|ERR_get_error(3), BN_add(3)|BN_add(3)
HISTORY
BN_add_word() and BN_mod_word() are available in all versions of SSLeay and OpenSSL.
BN_div_word() was added in SSLeay 0.8, and BN_sub_word() and BN_mul_word() in SSLeay 0.9.0.

54 05 July 2003
Crypto Library BIGNUM conversion

BIGNUM conversion
BN_bn2bin, BN_bin2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp,
BN_bn2mpi, BN_mpi2bn - format conversions
SYNOPSIS
#include <openssl/bn.h>

int BN_bn2bin(const BIGNUM *a, unsigned char *to);

BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);

char *BN_bn2hex(const BIGNUM *a);

char *BN_bn2dec(const BIGNUM *a);
int BN_hex2bn(BIGNUM **a, const char *str);
int BN_dec2bn(BIGNUM **a, const char *str);

int BN_print(BIO *fp, const BIGNUM *a);

int BN_print_fp(FILE *fp, const BIGNUM *a);

int BN_bn2mpi(const BIGNUM *a, unsigned char *to);

BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);
DESCRIPTION
BN_bn2bin() converts the absolute value of a into big-endian form and stores it at to. to must point to
BN_num_bytes(a) bytes of memory.
BN_bin2bn() converts the positive integer in big-endian form of length len at s into a BIGNUM and
places it in ret. If ret is NULL, a new BIGNUM is created.
BN_bn2hex() and BN_bn2dec() return printable strings containing the hexadecimal and decimal
encoding of a respectively. For negative numbers, the string is prefaced with a leading ‘-’. The string
must be freed later using OPENSSL_free().
BN_hex2bn() converts the string str containing a hexadecimal number to a BIGNUM and stores it in
**bn. If *bn is NULL, a new BIGNUM is created. If bn is NULL, it only computes the number‘s
length in hexadecimal digits. If the string starts with ‘-‘, the number is negative. BN_dec2bn() is the
same using the decimal system.
BN_print() and BN_print_fp() write the hexadecimal encoding of a, with a leading ‘-’ for negative
numbers, to the BIO or FILE fp.
BN_bn2mpi() and BN_mpi2bn() convert BIGNUMs from and to a format that consists of the number‘s
length in bytes represented as a 4-byte big-endian number, and the number itself in big-endian format,
where the most significant bit signals a negative number (the representation of numbers with the MSB
set is prefixed with null byte).
BN_bn2mpi() stores the representation of a at to, where to must be large enough to hold the result. The
size can be determined by calling BN_bn2mpi(a, NULL).
BN_mpi2bn() converts the len bytes long representation at s to a BIGNUM and stores it at ret, or in a
newly allocated BIGNUM if ret is NULL.
RETURN VALUES
BN_bn2bin() returns the length of the big-endian number placed at to. BN_bin2bn() returns the
BIGNUM, NULL on error.
BN_bn2hex() and BN_bn2dec() return a null-terminated string, or NULL on error. BN_hex2bn() and
BN_dec2bn() return the number‘s length in hexadecimal or decimal digits, and 0 on error.
BN_print_fp() and BN_print() return 1 on success, 0 on write errors.
BN_bn2mpi() returns the length of the representation. BN_mpi2bn() returns the BIGNUM, and NULL
on error.
The error codes can be obtained by ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
bn(3)|bn(3), ERR_get_error(3)|ERR_get_error(3), BN_zero(3)|BN_zero(3),
ASN1_INTEGER_to_BN(3)|ASN1_INTEGER_to_BN(3), BN_num_bytes(3)|BN_num_bytes(3)

05 July 2003 55
BIGNUM conversion Crypto Library

HISTORY
BN_bn2bin(), BN_bin2bn(), BN_print_fp() and BN_print() are available in all versions of SSLeay and
OpenSSL.
BN_bn2hex(), BN_bn2dec(), BN_hex2bn(), BN_dec2bn(), BN_bn2mpi() and BN_mpi2bn() were added
in SSLeay 0.9.0.

56 05 July 2003
Crypto Library BIGNUM compare and test

BIGNUM compare and test

BN_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_is_odd - BIGNUM comparison and
test functions
SYNOPSIS
#include <openssl/bn.h>

int BN_cmp(BIGNUM *a, BIGNUM *b);

int BN_ucmp(BIGNUM *a, BIGNUM *b);

int BN_is_zero(BIGNUM *a);

int BN_is_one(BIGNUM *a);
int BN_is_word(BIGNUM *a, BN_ULONG w);
int BN_is_odd(BIGNUM *a);
DESCRIPTION
BN_cmp() compares the numbers a and b. BN_ucmp() compares their absolute values.
BN_is_zero(), BN_is_one() and BN_is_word() test if a equals 0, 1, or w respectively. BN_is_odd() tests
if a is odd.
BN_is_zero(), BN_is_one(), BN_is_word() and BN_is_odd() are macros.
RETURN VALUES
BN_cmp() returns -1 if a < b>, 0 if a == b and 1 if a b. BN_ucmp() is the same using the absolute
values of a and b.
BN_is_zero(), BN_is_one() BN_is_word() and BN_is_odd() return 1 if the condition is true, 0
otherwise.
SEE ALSO
bn(3)|bn(3)
HISTORY
BN_cmp(), BN_ucmp(), BN_is_zero(), BN_is_one() and BN_is_word() are available in all versions of
SSLeay and OpenSSL. BN_is_odd() was added in SSLeay 0.8.

05 July 2003 57
BIGNUM copy Crypto Library

BIGNUM copy
BN_copy, BN_dup - copy BIGNUMs
SYNOPSIS
#include <openssl/bn.h>

BIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from);

BIGNUM *BN_dup(const BIGNUM *from);

DESCRIPTION
BN_copy() copies from to to. BN_dup() creates a new BIGNUM containing the value from.
RETURN VALUES
BN_copy() returns to on success, NULL on error. BN_dup() returns the new BIGNUM, and NULL on
error. The error codes can be obtained by ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
bn(3)|bn(3), ERR_get_error(3)|ERR_get_error(3)
HISTORY
BN_copy() and BN_dup() are available in all versions of SSLeay and OpenSSL.

58 05 July 2003
Crypto Library BN_CTX allocation

BN_CTX allocation
BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
SYNOPSIS
#include <openssl/bn.h>

BN_CTX *BN_CTX_new(void);

void BN_CTX_init(BN_CTX *c);

void BN_CTX_free(BN_CTX *c);

DESCRIPTION
A BN_CTX is a structure that holds BIGNUM temporary variables used by library functions. Since
dynamic memory allocation to create BIGNUMs is rather expensive when used in conjunction with
repeated subroutine calls, the BN_CTX structure is used.
BN_CTX_new() allocates and initializes a BN_CTX structure. BN_CTX_init() initializes an existing
uninitialized BN_CTX.
BN_CTX_free() frees the components of the BN_CTX, and if it was created by BN_CTX_new(), also
the structure itself. If BN_CTX_start(3)|BN_CTX_start(3) has been used on the BN_CTX,
BN_CTX_end(3)|BN_CTX_end(3) must be called before the BN_CTX may be freed by
BN_CTX_free().

RETURN VALUES
BN_CTX_new() returns a pointer to the BN_CTX. If the allocation fails, it returns NULL and sets an
error code that can be obtained by ERR_get_error(3)|ERR_get_error(3).
BN_CTX_init() and BN_CTX_free() have no return values.
SEE ALSO
bn(3)|bn(3), ERR_get_error(3)|ERR_get_error(3), BN_add(3)|BN_add(3),
BN_CTX_start(3)|BN_CTX_start(3)
HISTORY
BN_CTX_new() and BN_CTX_free() are available in all versions on SSLeay and OpenSSL.
BN_CTX_init() was added in SSLeay 0.9.1b.

05 July 2003 59
BIGNUM temp Crypto Library

BIGNUM temp
BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables
SYNOPSIS
#include <openssl/bn.h>

void BN_CTX_start(BN_CTX *ctx);

BIGNUM *BN_CTX_get(BN_CTX *ctx);

void BN_CTX_end(BN_CTX *ctx);

DESCRIPTION
These functions are used to obtain temporary BIGNUM variables from a BN_CTX (which can been
created by using BN_CTX_new(3)|BN_CTX_new(3)) in order to save the overhead of repeatedly creating
and freeing BIGNUMs in functions that are called from inside a loop.
A function must call BN_CTX_start() first. Then, BN_CTX_get() may be called repeatedly to obtain
temporary BIGNUMs. All BN_CTX_get() calls must be made before calling any other functions that
use the ctx as an argument.
Finally, BN_CTX_end() must be called before returning from the function. When BN_CTX_end() is
called, the BIGNUM pointers obtained from BN_CTX_get() become invalid.
RETURN VALUES
BN_CTX_start() and BN_CTX_end() return no values.
BN_CTX_get() returns a pointer to the BIGNUM, or NULL on error. Once BN_CTX_get() has failed,
the subsequent calls will return NULL as well, so it is sufficient to check the return value of the last
BN_CTX_get() call. In case of an error, an error code is set, which can be obtained by
ERR_get_error(3)|ERR_get_error(3).

SEE ALSO
BN_CTX_new(3)|BN_CTX_new(3)
HISTORY
BN_CTX_start(), BN_CTX_get() and BN_CTX_end() were added in OpenSSL 0.9.5.

60 05 July 2003
Crypto Library BIGNUM primes

BIGNUM primes
BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test for primality
SYNOPSIS
#include <openssl/bn.h>

BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,

BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg);

int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int,

void *), BN_CTX *ctx, void *cb_arg);

int BN_is_prime_fasttest(const BIGNUM *a, int checks,

void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg,
int do_trial_division);
DESCRIPTION
BN_generate_prime() generates a pseudo-random prime number of num bits. If ret is not NULL, it will
be used to store the number.
If callback is not NULL, it is called as follows:

callback(0, i, cb_arg) is called after generating the i-th potential prime number.
While the number is being tested for primality, callback(1, j, cb_arg) is called as described below.

When a prime has been found, callback(2, i, cb_arg) is called.

The prime may have to fulfill additional requirements for use in Diffie-Hellman key exchange:
If add is not NULL, the prime will fulfill the condition p % add == rem (p % add == 1 if rem ==
NULL) in order to suit a given generator.
If safe is true, it will be a safe prime (i.e. a prime p so that (p-1)/2 is also prime).
The PRNG must be seeded prior to calling BN_generate_prime(). The prime number generation has a
negligible error probability.
BN_is_prime() and BN_is_prime_fasttest() test if the number a is prime. The following tests are
performed until one of them shows that a is composite; if a passes all these tests, it is considered prime.
BN_is_prime_fasttest(), when called with do_trial_division == 1, first attempts trial division by a
number of small primes; if no divisors are found by this test and callback is not NULL, callback(1, -1,
cb_arg) is called. If do_trial_division == 0, this test is skipped.
Both BN_is_prime() and BN_is_prime_fasttest() perform a Miller-Rabin probabilistic primality test with
checks iterations. If checks == BN_prime_checks, a number of iterations is used that yields a false
positive rate of at most 2^-80 for random input.
If callback is not NULL, callback(1, j, cb_arg) is called after the j-th iteration (j = 0, 1, ...). ctx is a
pre-allocated BN_CTX (to save the overhead of allocating and freeing the structure in a loop), or
NULL.
RETURN VALUES
BN_generate_prime() returns the prime number on success, NULL otherwise.
BN_is_prime() returns 0 if the number is composite, 1 if it is prime with an error probability of less than
0.25^checks, and -1 on error.
The error codes can be obtained by ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
bn(3)|bn(3), ERR_get_error(3)|ERR_get_error(3), rand(3)|rand(3)
HISTORY
The cb_arg arguments to BN_generate_prime() and to BN_is_prime() were added in SSLeay 0.9.0. The
ret argument to BN_generate_prime() was added in SSLeay 0.9.1. BN_is_prime_fasttest() was added in
OpenSSL 0.9.5.

05 July 2003 61
BIGNUM internals Crypto Library

BIGNUM internals
bn_mul_words, bn_mul_add_words, bn_sqr_words, bn_div_words, bn_add_words, bn_sub_words,
bn_mul_comba4, bn_mul_comba8, bn_sqr_comba4, bn_sqr_comba8, bn_cmp_words, bn_mul_normal,
bn_mul_low_normal, bn_mul_recursive, bn_mul_part_recursive, bn_mul_low_recursive, bn_mul_high,
bn_sqr_normal, bn_sqr_recursive, bn_expand, bn_wexpand, bn_expand2, bn_fix_top, bn_check_top,
bn_print, bn_dump, bn_set_max, bn_set_high, bn_set_low - BIGNUM library internal functions
SYNOPSIS
BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w);
BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num,
BN_ULONG w);
void bn_sqr_words(BN_ULONG *rp, BN_ULONG *ap, int num);
BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d);
BN_ULONG bn_add_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp,
int num);
BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp,
int num);

void bn_mul_comba4(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b);

void bn_mul_comba8(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b);
void bn_sqr_comba4(BN_ULONG *r, BN_ULONG *a);
void bn_sqr_comba8(BN_ULONG *r, BN_ULONG *a);

int bn_cmp_words(BN_ULONG *a, BN_ULONG *b, int n);

void bn_mul_normal(BN_ULONG *r, BN_ULONG *a, int na, BN_ULONG *b,

int nb);
void bn_mul_low_normal(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n);
void bn_mul_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2,
int dna,int dnb,BN_ULONG *tmp);
void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b,
int n, int tna,int tnb, BN_ULONG *tmp);
void bn_mul_low_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b,
int n2, BN_ULONG *tmp);
void bn_mul_high(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, BN_ULONG *l,
int n2, BN_ULONG *tmp);

void bn_sqr_normal(BN_ULONG *r, BN_ULONG *a, int n, BN_ULONG *tmp);

void bn_sqr_recursive(BN_ULONG *r, BN_ULONG *a, int n2, BN_ULONG *tmp);

void mul(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c);

void mul_add(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c);
void sqr(BN_ULONG r0, BN_ULONG r1, BN_ULONG a);

BIGNUM *bn_expand(BIGNUM *a, int bits);

BIGNUM *bn_wexpand(BIGNUM *a, int n);
BIGNUM *bn_expand2(BIGNUM *a, int n);
void bn_fix_top(BIGNUM *a);

void bn_check_top(BIGNUM *a);

void bn_print(BIGNUM *a);
void bn_dump(BN_ULONG *d, int n);
void bn_set_max(BIGNUM *a);
void bn_set_high(BIGNUM *r, BIGNUM *a, int n);
void bn_set_low(BIGNUM *r, BIGNUM *a, int n);
DESCRIPTION
This page documents the internal functions used by the OpenSSL BIGNUM implementation. They are
described here to facilitate debugging and extending the library. They are not to be used by applications.

62 05 July 2003
Crypto Library BIGNUM internals

The BIGNUM structure

typedef struct bignum_st
{
int top; /* index of last used d (most significant word) */
BN_ULONG *d; /* pointer to an array of ’BITS2’ bit chunks */
int max; /* size of the d array */
int neg; /* sign */
} BIGNUM;

The big number is stored in d, a malloc()ed array of BN_ULONGs, least significant first. A
BN_ULONG can be either 16, 32 or 64 bits in size (BITS2), depending on the ‘number of bits’
specified in openssl/bn.h.
max is the size of the d array that has been allocated. top is the ‘last’ entry being used, so for a value of
4, bn.d[0]=4 and bn.top=1. neg is 1 if the number is negative. When a BIGNUM is 0, the d field can be
NULL and top == 0.
Various routines in this library require the use of temporary BIGNUM variables during their execution.
Since dynamic memory allocation to create BIGNUMs is rather expensive when used in conjunction
with repeated subroutine calls, the BN_CTX structure is used. This structure contains BN_CTX_NUM
BIGNUMs, see BN_CTX_start(3)|BN_CTX_start(3).
Low-level arithmetic operations
These functions are implemented in C and for several platforms in assembly language:
bn_mul_words(rp, ap, num, w) operates on the num word arrays rp and ap. It computes ap * w,
places the result in rp, and returns the high word (carry).
bn_mul_add_words(rp, ap, num, w) operates on the num word arrays rp and ap. It computes ap * w +
rp, places the result in rp, and returns the high word (carry).
bn_sqr_words(rp, ap, n) operates on the num word array ap and the 2*num word array ap. It computes
ap * ap word-wise, and places the low and high bytes of the result in rp.
bn_div_words(h, l, d) divides the two word number (h,l) by d and returns the result.
bn_add_words(rp, ap, bp, num) operates on the num word arrays ap, bp and rp. It computes ap + bp,
places the result in rp, and returns the high word (carry).
bn_sub_words(rp, ap, bp, num) operates on the num word arrays ap, bp and rp. It computes ap - bp,
places the result in rp, and returns the carry (1 if bp ap, 0 otherwise).
bn_mul_comba4(r, a, b) operates on the 4 word arrays a and b and the 8 word array r. It computes a*b
and places the result in r.
bn_mul_comba8(r, a, b) operates on the 8 word arrays a and b and the 16 word array r. It computes
a*b and places the result in r.
bn_sqr_comba4(r, a, b) operates on the 4 word arrays a and b and the 8 word array r.
bn_sqr_comba8(r, a, b) operates on the 8 word arrays a and b and the 16 word array r.
The following functions are implemented in C:
bn_cmp_words(a, b, n) operates on the n word arrays a and b. It returns 1, 0 and -1 if a is greater than,
equal and less than b.
bn_mul_normal(r, a, na, b, nb) operates on the na word array a, the nb word array b and the na+nb
word array r. It computes a*b and places the result in r.
bn_mul_low_normal(r, a, b, n) operates on the n word arrays r, a and b. It computes the n low words
of a*b and places the result in r.
bn_mul_recursive(r, a, b, n2, dna, dnb, t) operates on the word arrays a and b of length n2+dna and
n2+dnb (dna and dnb are currently allowed to be 0 or negative) and the 2*n2 word arrays r and t. n2
must be a power of 2. It computes a*b and places the result in r.
bn_mul_part_recursive(r, a, b, n, tna, tnb, tmp) operates on the word arrays a and b of length n+tna
and n+tnb and the 4*n word arrays r and tmp.
bn_mul_low_recursive(r, a, b, n2, tmp) operates on the n2 word arrays r and tmp and the n2/2 word
arrays a and b.
bn_mul_high(r, a, b, l, n2, tmp) operates on the n2 word arrays r, a, b and l (?) and the 3*n2 word array
tmp.
BN_mul() calls bn_mul_normal(), or an optimized implementation if the factors have the same size:
bn_mul_comba8() is used if they are 8 words long, bn_mul_recursive() if they are larger than
BN_MULL_SIZE_NORMAL and the size is an exact multiple of the word size, and
bn_mul_part_recursive() for others that are larger than BN_MULL_SIZE_NORMAL.

05 July 2003 63
BIGNUM internals Crypto Library

bn_sqr_normal(r, a, n, tmp) operates on the n word array a and the 2*n word arrays tmp and r.
The implementations use the following macros which, depending on the architecture, may use "long
long" C operations or inline assembler. They are defined in bn_lcl.h.
mul(r, a, w, c) computes w*a+c and places the low word of the result in r and the high word in c.
mul_add(r, a, w, c) computes w*a+r+c and places the low word of the result in r and the high word in c.

sqr(r0, r1, a) computes a*a and places the low word of the result in r0 and the high word in r1.
Size changes
bn_expand() ensures that b has enough space for a bits bit number. bn_wexpand() ensures that b has
enough space for an n word number. If the number has to be expanded, both macros call bn_expand2(),
which allocates a new d array and copies the data. They return NULL on error, b otherwise.
The bn_fix_top() macro reduces a-top to point to the most significant non-zero word when a has shrunk.

Debugging
bn_check_top() verifies that ((a)-top = 0 && (a)-top <= (a)->max). A violation will cause the
program to abort.
bn_print() prints a to stderr. bn_dump() prints n words at d (in reverse order, i.e. most significant word
first) to stderr.
bn_set_max() makes a a static number with a max of its current size. This is used by bn_set_low() and
bn_set_high() to make r a read-only BIGNUM that contains the n low or high words of a.
If BN_DEBUG is not defined, bn_check_top(), bn_print(), bn_dump() and bn_set_max() are defined as
empty macros.
SEE ALSO
bn(3)|bn(3)

64 05 July 2003
Crypto Library BIGNUM inverse

BIGNUM inverse
BN_mod_inverse - compute inverse modulo n
SYNOPSIS
#include <openssl/bn.h>

BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,

BN_CTX *ctx);
DESCRIPTION
BN_mod_inverse() computes the inverse of a modulo n places the result in r ((a*r)%n==1). If r is
NULL, a new BIGNUM is created.
ctx is a previously allocated BN_CTX used for temporary variables. r may be the same BIGNUM as a
or n.
RETURN VALUES
BN_mod_inverse() returns the BIGNUM containing the inverse, and NULL on error. The error codes
can be obtained by ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
bn(3)|bn(3), ERR_get_error(3)|ERR_get_error(3), BN_add(3)|BN_add(3)
HISTORY
BN_mod_inverse() is available in all versions of SSLeay and OpenSSL.

05 July 2003 65
BIGNUM Montgomery Crypto Library

BIGNUM Montgomery
BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init, BN_MONT_CTX_free,
BN_MONT_CTX_set, BN_MONT_CTX_copy, BN_from_montgomery, BN_to_montgomery -
Montgomery multiplication
SYNOPSIS
#include <openssl/bn.h>

BN_MONT_CTX *BN_MONT_CTX_new(void);
void BN_MONT_CTX_init(BN_MONT_CTX *ctx);
void BN_MONT_CTX_free(BN_MONT_CTX *mont);

int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);

BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);

int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,

BN_MONT_CTX *mont, BN_CTX *ctx);

int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,

BN_CTX *ctx);

int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,

BN_CTX *ctx);
DESCRIPTION
These functions implement Montgomery multiplication. They are used automatically when
BN_mod_exp(3)|BN_mod_exp(3) is called with suitable input, but they may be useful when several
operations are to be performed using the same modulus.
BN_MONT_CTX_new() allocates and initializes a BN_MONT_CTX structure.
BN_MONT_CTX_init() initializes an existing uninitialized BN_MONT_CTX.
BN_MONT_CTX_set() sets up the mont structure from the modulus m by precomputing its inverse and
a value R.
BN_MONT_CTX_copy() copies the BN_MONT_CTX from to to.
BN_MONT_CTX_free() frees the components of the BN_MONT_CTX, and, if it was created by
BN_MONT_CTX_new(), also the structure itself.
BN_mod_mul_montgomery() computes Mont(a,b):=a*b*R^-1 and places the result in r.
BN_from_montgomery() performs the Montgomery reduction r = a*R^-1.
BN_to_montgomery() computes Mont(a,R^2), i.e. a*R. Note that a must be non-negative and smaller
than the modulus.
For all functions, ctx is a previously allocated BN_CTX used for temporary variables.
The BN_MONT_CTX structure is defined as follows:
typedef struct bn_mont_ctx_st
{
int ri; /* number of bits in R */
BIGNUM RR; /* R^2 (used to convert to Montgomery form) */
BIGNUM N; /* The modulus */
BIGNUM Ni; /* R*(1/R mod N) - N*Ni = 1
* (Ni is only stored for bignum algorithm) */
BN_ULONG n0; /* least significant word of Ni */
int flags;
} BN_MONT_CTX;

BN_to_montgomery() is a macro.
RETURN VALUES
BN_MONT_CTX_new() returns the newly allocated BN_MONT_CTX, and NULL on error.
BN_MONT_CTX_init() and BN_MONT_CTX_free() have no return values.
For the other functions, 1 is returned for success, 0 on error. The error codes can be obtained by
ERR_get_error(3)|ERR_get_error(3).

66 05 July 2003
Crypto Library BIGNUM Montgomery

WARNING
The inputs must be reduced modulo m, otherwise the result will be outside the expected range.
SEE ALSO
bn(3)|bn(3), ERR_get_error(3)|ERR_get_error(3), BN_add(3)|BN_add(3),
BN_CTX_new(3)|BN_CTX_new(3)
HISTORY
BN_MONT_CTX_new(), BN_MONT_CTX_free(), BN_MONT_CTX_set(),
BN_mod_mul_montgomery(), BN_from_montgomery() and BN_to_montgomery() are available in all
versions of SSLeay and OpenSSL.
BN_MONT_CTX_init() and BN_MONT_CTX_copy() were added in SSLeay 0.9.1b.

05 July 2003 67
BIGNUM modular multiplication Crypto Library

BIGNUM modular multiplication

BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_init,
BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using reciprocal
SYNOPSIS
#include <openssl/bn.h>

BN_RECP_CTX *BN_RECP_CTX_new(void);
void BN_RECP_CTX_init(BN_RECP_CTX *recp);
void BN_RECP_CTX_free(BN_RECP_CTX *recp);

int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);

int BN_div_recp(BIGNUM *dv, BIGNUM *rem, BIGNUM *a, BN_RECP_CTX *recp,

BN_CTX *ctx);

int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b,

BN_RECP_CTX *recp, BN_CTX *ctx);
DESCRIPTION
BN_mod_mul_reciprocal() can be used to perform an efficient BN_mod_mul(3)|BN_mod_mul(3)
operation when the operation will be performed repeatedly with the same modulus. It computes
r=(a*b)%m using recp=1/m, which is set as described below. ctx is a previously allocated BN_CTX
used for temporary variables.
BN_RECP_CTX_new() allocates and initializes a BN_RECP structure. BN_RECP_CTX_init()
initializes an existing uninitialized BN_RECP.
BN_RECP_CTX_free() frees the components of the BN_RECP, and, if it was created by
BN_RECP_CTX_new(), also the structure itself.
BN_RECP_CTX_set() stores m in recp and sets it up for computing 1/m and shifting it left by
BN_num_bits(m)+1 to make it an integer. The result and the number of bits it was shifted left will later
be stored in recp.
BN_div_recp() divides a by m using recp. It places the quotient in dv and the remainder in rem.
The BN_RECP_CTX structure is defined as follows:
typedef struct bn_recp_ctx_st
{
BIGNUM N; /* the divisor */
BIGNUM Nr; /* the reciprocal */
int num_bits;
int shift;
int flags;
} BN_RECP_CTX;

It cannot be shared between threads.

RETURN VALUES
BN_RECP_CTX_new() returns the newly allocated BN_RECP_CTX, and NULL on error.
BN_RECP_CTX_init() and BN_RECP_CTX_free() have no return values.
For the other functions, 1 is returned for success, 0 on error. The error codes can be obtained by
ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
bn(3)|bn(3), ERR_get_error(3)|ERR_get_error(3), BN_add(3)|BN_add(3),
BN_CTX_new(3)|BN_CTX_new(3)
HISTORY
BN_RECP_CTX was added in SSLeay 0.9.0. Before that, the function BN_reciprocal() was used
instead, and the BN_mod_mul_reciprocal() arguments were different.

68 05 July 2003
Crypto Library BIGNUM allocation

BIGNUM allocation
BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
SYNOPSIS
#include <openssl/bn.h>

BIGNUM *BN_new(void);

void BN_init(BIGNUM *);

void BN_clear(BIGNUM *a);

void BN_free(BIGNUM *a);

void BN_clear_free(BIGNUM *a);

DESCRIPTION
BN_new() allocated and initializes a BIGNUM structure. BN_init() initializes an existing uninitialized
BIGNUM.
BN_clear() is used to destroy sensitive data such as keys when they are no longer needed. It erases the
memory used by a and sets it to the value 0.
BN_free() frees the components of the BIGNUM, and if it was created by BN_new(), also the structure
itself. BN_clear_free() additionally overwrites the data before the memory is returned to the system.
RETURN VALUES
BN_new() returns a pointer to the BIGNUM. If the allocation fails, it returns NULL and sets an error
code that can be obtained by ERR_get_error(3)|ERR_get_error(3).
BN_init(), BN_clear(), BN_free() and BN_clear_free() have no return values.
SEE ALSO
bn(3)|bn(3), ERR_get_error(3)|ERR_get_error(3)
HISTORY
BN_new(), BN_clear(), BN_free() and BN_clear_free() are available in all versions on SSLeay and
OpenSSL. BN_init() was added in SSLeay 0.9.1b.

05 July 2003 69
BIGNUM size Crypto Library

BIGNUM size
BN_num_bits, BN_num_bytes, BN_num_bits_word - get BIGNUM size
SYNOPSIS
#include <openssl/bn.h>

int BN_num_bytes(const BIGNUM *a);

int BN_num_bits(const BIGNUM *a);

int BN_num_bits_word(BN_ULONG w);

DESCRIPTION
These functions return the size of a BIGNUM in bytes or bits, and the size of an unsigned integer in bits.

BN_num_bytes() is a macro.
RETURN VALUES
The size.
SEE ALSO
bn(3)|bn(3)
HISTORY
BN_num_bytes(), BN_num_bits() and BN_num_bits_word() are available in all versions of SSLeay and
OpenSSL.

70 05 July 2003
Crypto Library BIGNUM pseudo-random

BIGNUM pseudo-random
BN_rand, BN_pseudo_rand - generate pseudo-random number
SYNOPSIS
#include <openssl/bn.h>

int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);

int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);

int BN_rand_range(BIGNUM *rnd, BIGNUM *range);

int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range);

DESCRIPTION
BN_rand() generates a cryptographically strong pseudo-random number of bits bits in length and stores
it in rnd. If top is -1, the most significant bit of the random number can be zero. If top is 0, it is set to 1,
and if top is 1, the two most significant bits of the number will be set to 1, so that the product of two
such random numbers will always have 2*bits length. If bottom is true, the number will be odd.
BN_pseudo_rand() does the same, but pseudo-random numbers generated by this function are not
necessarily unpredictable. They can be used for non-cryptographic purposes and for certain purposes in
cryptographic protocols, but usually not for key generation etc.
BN_rand_range() generates a cryptographically strong pseudo-random number rnd in the range 0 <lt>=
rnd < range>. BN_pseudo_rand_range() does the same, but is based on BN_pseudo_rand(), and
hence numbers generated by it are not necessarily unpredictable.
The PRNG must be seeded prior to calling BN_rand() or BN_rand_range().
RETURN VALUES
The functions return 1 on success, 0 on error. The error codes can be obtained by
ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
bn(3)|bn(3), ERR_get_error(3)|ERR_get_error(3), rand(3)|rand(3), RAND_add(3)|RAND_add(3),
RAND_bytes(3)|RAND_bytes(3)
HISTORY
BN_rand() is available in all versions of SSLeay and OpenSSL. BN_pseudo_rand() was added in
OpenSSL 0.9.5. The top == -1 case and the function BN_rand_range() were added in OpenSSL 0.9.6a.
BN_pseudo_rand_range() was added in OpenSSL 0.9.6c.

05 July 2003 71
BIGNUM bit-operations Crypto Library

BIGNUM bit-operations
BN_set_bit, BN_clear_bit, BN_is_bit_set, BN_mask_bits, BN_lshift, BN_lshift1, BN_rshift, BN_rshift1
- bit operations on BIGNUMs
SYNOPSIS
#include <openssl/bn.h>

int BN_set_bit(BIGNUM *a, int n);

int BN_clear_bit(BIGNUM *a, int n);

int BN_is_bit_set(const BIGNUM *a, int n);

int BN_mask_bits(BIGNUM *a, int n);

int BN_lshift(BIGNUM *r, const BIGNUM *a, int n);

int BN_lshift1(BIGNUM *r, BIGNUM *a);

int BN_rshift(BIGNUM *r, BIGNUM *a, int n);

int BN_rshift1(BIGNUM *r, BIGNUM *a);
DESCRIPTION
BN_set_bit() sets bit n in a to 1 (a|=(1<<n)>). The number is expanded if
necessary.
BN_clear_bit() sets bit n in a to 0 (a&=~(1<<n)>). An error occurs if a is shorter
than n bits.
BN_is_bit_set() tests if bit n in a is set.
BN_mask_bits() truncates a to an n bit number (a&=~((~0)n)). An error occurs if a already is shorter
than n bits.
BN_lshift() shifts a left by n bits and places the result in r (r=a*2^n). BN_lshift1() shifts a left by one
and places the result in r (r=2*a).
BN_rshift() shifts a right by n bits and places the result in r (r=a/2^n). BN_rshift1() shifts a right by
one and places the result in r (r=a/2).
For the shift functions, r and a may be the same variable.
RETURN VALUES
BN_is_bit_set() returns 1 if the bit is set, 0 otherwise.
All other functions return 1 for success, 0 on error. The error codes can be obtained by
ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
bn(3)|bn(3), BN_num_bytes(3)|BN_num_bytes(3), BN_add(3)|BN_add(3)
HISTORY
BN_set_bit(), BN_clear_bit(), BN_is_bit_set(), BN_mask_bits(), BN_lshift(), BN_lshift1(), BN_rshift(),
and BN_rshift1() are available in all versions of SSLeay and OpenSSL.

72 05 July 2003
Crypto Library BIGNUM exchange

BIGNUM exchange
BN_swap - exchange BIGNUMs
SYNOPSIS
#include <openssl/bn.h>

void BN_swap(BIGNUM *a, BIGNUM *b);

DESCRIPTION
BN_swap() exchanges the values of a and b.
bn(3)|bn(3)
HISTORY
BN_swap was added in OpenSSL 0.9.7.

05 July 2003 73
BIGNUM assignment Crypto Library

BIGNUM assignment
BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word - BIGNUM assignment operations
SYNOPSIS
#include <openssl/bn.h>

int BN_zero(BIGNUM *a);

int BN_one(BIGNUM *a);

const BIGNUM *BN_value_one(void);

int BN_set_word(BIGNUM *a, unsigned long w);

unsigned long BN_get_word(BIGNUM *a);
DESCRIPTION
BN_zero(), BN_one() and BN_set_word() set a to the values 0, 1 and w respectively. BN_zero() and
BN_one() are macros.
BN_value_one() returns a BIGNUM constant of value 1. This constant is useful for use in comparisons
and assignment.
BN_get_word() returns a, if it can be represented as an unsigned long.
RETURN VALUES
BN_get_word() returns the value a, and 0xffffffffL if a cannot be represented as an unsigned long.
BN_zero(), BN_one() and BN_set_word() return 1 on success, 0 otherwise. BN_value_one() returns the
constant.
BUGS
Someone might change the constant.
If a BIGNUM is equal to 0xffffffffL it can be represented as an unsigned long but this value is also
returned on error.
SEE ALSO
bn(3)|bn(3), BN_bn2bin(3)|BN_bn2bin(3)
HISTORY
BN_zero(), BN_one() and BN_set_word() are available in all versions of SSLeay and OpenSSL.
BN_value_one() and BN_get_word() were added in SSLeay 0.8.
BN_value_one() was changed to return a true const BIGNUM * in OpenSSL 0.9.7.

74 05 July 2003
Crypto Library BUF_MEM

BUF_MEM
BUF_MEM_new, BUF_MEM_free, BUF_MEM_grow, BUF_strdup - simple character arrays structure
SYNOPSIS
#include <openssl/buffer.h>

BUF_MEM *BUF_MEM_new(void);

void BUF_MEM_free(BUF_MEM *a);

int BUF_MEM_grow(BUF_MEM *str, int len);

char * BUF_strdup(const char *str);

DESCRIPTION
The buffer library handles simple character arrays. Buffers are used for various purposes in the library,
most notably memory BIOs.
The library uses the BUF_MEM structure defined in buffer.h:
typedef struct buf_mem_st
{
int length; /* current number of bytes */
char *data;
int max; /* size of buffer */
} BUF_MEM;

length is the current size of the buffer in bytes, max is the amount of memory allocated to the buffer.
There are three functions which handle these and one "miscellaneous" function.
BUF_MEM_new() allocates a new buffer of zero size.
BUF_MEM_free() frees up an already existing buffer. The data is zeroed before freeing up in case the
buffer contains sensitive data.
BUF_MEM_grow() changes the size of an already existing buffer to len. Any data already in the buffer
is preserved if it increases in size.
BUF_strdup() copies a null terminated string into a block of allocated memory and returns a pointer to
the allocated block. Unlike the standard C library strdup() this function uses OPENSSL_malloc() and so
should be used in preference to the standard library strdup() because it can be used for memory leak
checking or replacing the malloc() function.
The memory allocated from BUF_strdup() should be freed up using the OPENSSL_free() function.
RETURN VALUES
BUF_MEM_new() returns the buffer or NULL on error.
BUF_MEM_free() has no return value.
BUF_MEM_grow() returns zero on error or the new size (i.e. len).
SEE ALSO
bio(3)|bio(3)
HISTORY
BUF_MEM_new(), BUF_MEM_free() and BUF_MEM_grow() are available in all versions of SSLeay
and OpenSSL. BUF_strdup() was added in SSLeay 0.8.

05 July 2003 75
CRYPTO internals Crypto Library

CRYPTO internals
CRYPTO_set_ex_data, CRYPTO_get_ex_data - internal application specific data functions
SYNOPSIS
int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);

void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);

DESCRIPTION
Several OpenSSL structures can have application specific data attached to them. These functions are
used internally by OpenSSL to manipulate application specific data attached to a specific structure.
These functions should only be used by applications to manipulate CRYPTO_EX_DATA structures
passed to the new_func(), free_func() and dup_func() callbacks: as passed to
RSA_get_ex_new_index() for example.
CRYPTO_set_ex_data() is used to set application specific data, the data is supplied in the arg
parameter and its precise meaning is up to the application.
CRYPTO_get_ex_data() is used to retrieve application specific data. The data is returned to the
application, this will be the same value as supplied to a previous CRYPTO_set_ex_data() call.
RETURN VALUES
CRYPTO_set_ex_data() returns 1 on success or 0 on failure.
CRYPTO_get_ex_data() returns the application data or 0 on failure. 0 may also be valid application
data but currently it can only fail if given an invalid idx parameter.
On failure an error code can be obtained from ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3),
DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3),
DH_get_ex_new_index(3)|DH_get_ex_new_index(3)
HISTORY
CRYPTO_set_ex_data() and CRYPTO_get_ex_data() have been available since SSLeay 0.9.0.

76 05 July 2003
Crypto Library d2i/i2d ASN1_OBJECT

d2i/i2d ASN1_OBJECT
d2i_ASN1_OBJECT, i2d_ASN1_OBJECT - ASN1 OBJECT IDENTIFIER functions
SYNOPSIS
#include <openssl/objects.h>

ASN1_OBJECT *d2i_ASN1_OBJECT(ASN1_OBJECT **a, unsigned char **pp, long length);

int i2d_ASN1_OBJECT(ASN1_OBJECT *a, unsigned char **pp);
DESCRIPTION
These functions decode and encode an ASN1 OBJECT IDENTIFIER.
Othewise these behave in a similar way to d2i_X509() and i2d_X509() described in the
d2i_X509(3)|d2i_X509(3) manual page.
SEE ALSO
d2i_X509(3)|d2i_X509(3)
HISTORY
TBA

05 July 2003 77
d2i/i2d PKCS#3 DH parameter Crypto Library

d2i/i2d PKCS#3 DH parameter

d2i_DHparams, i2d_DHparams - PKCS#3 DH parameter functions.
SYNOPSIS
#include <openssl/dh.h>

DH *d2i_DHparams(DH **a, unsigned char **pp, long length);

int i2d_DHparams(DH *a, unsigned char **pp);
DESCRIPTION
These functions decode and encode PKCS#3 DH parameters using the DHparameter structure described
in PKCS#3.
Othewise these behave in a similar way to d2i_X509() and i2d_X509() described in the
d2i_X509(3)|d2i_X509(3) manual page.
SEE ALSO
d2i_X509(3)|d2i_X509(3)
HISTORY
TBA

78 05 July 2003
Crypto Library d2i/i2d DSA key encoding and parsing

d2i/i2d DSA key encoding and parsing

d2i_DSAPublicKey, i2d_DSAPublicKey, d2i_DSAPrivateKey, i2d_DSAPrivateKey,
d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSA_SIG, i2d_DSA_SIG - DSA key encoding and
parsing functions.
SYNOPSIS
#include <openssl/dsa.h>

DSA * d2i_DSAPublicKey(DSA **a, const unsigned char **pp, long length);

int i2d_DSAPublicKey(const DSA *a, unsigned char **pp);

DSA * d2i_DSA_PUBKEY(DSA **a, const unsigned char **pp, long length);

int i2d_DSA_PUBKEY(const DSA *a, unsigned char **pp);

DSA * d2i_DSAPrivateKey(DSA **a, const unsigned char **pp, long length);

int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp);

DSA * d2i_DSAparams(DSA **a, const unsigned char **pp, long length);

int i2d_DSAparams(const DSA *a, unsigned char **pp);

DSA * d2i_DSA_SIG(DSA_SIG **a, const unsigned char **pp, long length);

int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp);

DESCRIPTION
d2i_DSAPublicKey() and i2d_DSAPublicKey() decode and encode the DSA public key components
structure.
d2i_DSA_PUKEY() and i2d_DSA_PUKEY() decode and encode an DSA public key using a
SubjectPublicKeyInfo (certificate public key) structure.
d2i_DSAPrivateKey(), i2d_DSAPrivateKey() decode and encode the DSA private key components.
d2i_DSAparams(), i2d_DSAparams() decode and encode the DSA parameters using a Dss-Parms
structure as defined in RFC2459.
d2i_DSA_SIG(), i2d_DSA_SIG() decode and encode a DSA signature using a Dss-Sig-Value structure
as defined in RFC2459.
The usage of all of these functions is similar to the d2i_X509() and i2d_X509() described in the
d2i_X509(3)|d2i_X509(3) manual page.
NOTES
The DSA structure passed to the private key encoding functions should have all the private key
components present.
The data encoded by the private key functions is unencrypted and therefore offers no private key
security.
The DSA_PUBKEY functions should be used in preference to the DSAPublicKey functions when
encoding public keys because they use a standard format.
The DSAPublicKey functions use an non standard format the actual data encoded depends on the value
of the write_params field of the a key parameter. If write_params is zero then only the pub_key field
is encoded as an INTEGER. If write_params is 1 then a SEQUENCE consisting of the p, q, g and
pub_key respectively fields are encoded.
The DSAPrivateKey functions also use a non standard structure consiting consisting of a SEQUENCE
containing the p, q, g and pub_key and priv_key fields respectively.
SEE ALSO
d2i_X509(3)|d2i_X509(3)

05 July 2003 79
d2i/i2d DSA key encoding and parsing Crypto Library

HISTORY
TBA

80 05 July 2003
Crypto Library d2i/i2d PKCS#8 private key

d2i/i2d PKCS#8 private key

d2i_PKCS8PrivateKey_bio, d2i_PKCS8PrivateKey_fp, i2d_PKCS8PrivateKey_bio,
i2d_PKCS8PrivateKey_fp, i2d_PKCS8PrivateKey_nid_bio, i2d_PKCS8PrivateKey_nid_fp - PKCS#8
format private key functions
SYNOPSIS
#include <openssl/evp.h>

EVP_PKEY *d2i_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY **x,

pem_password_cb *cb, void *u);
EVP_PKEY *d2i_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY **x,
pem_password_cb *cb, void *u);

int i2d_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,

char *kstr, int klen,
pem_password_cb *cb, void *u);

int i2d_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,

char *kstr, int klen,
pem_password_cb *cb, void *u);

int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, EVP_PKEY *x, int nid,

char *kstr, int klen,
pem_password_cb *cb, void *u);

int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, EVP_PKEY *x, int nid,

char *kstr, int klen,
pem_password_cb *cb, void *u);
DESCRIPTION
The PKCS#8 functions encode and decode private keys in PKCS#8 format using both PKCS#5 v1.5 and
PKCS#5 v2.0 password based encryption algorithms.
Other than the use of DER as opposed to PEM these functions are identical to the corresponding PEM
function as described in the pem(3)|pem(3) manual page.
NOTES
Before using these functions OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3) should
be called to initialize the internal algorithm lookup tables otherwise errors about unknown algorithms
will occur if an attempt is made to decrypt a private key.
These functions are currently the only way to store encrypted private keys using DER format.
Currently all the functions use BIOs or FILE pointers, there are no functions which work directly on
memory: this can be readily worked around by converting the buffers to memory BIOs, see
BIO_s_mem(3)|BIO_s_mem(3) for details.
SEE ALSO
pem(3)|pem(3)

05 July 2003 81
d2i/i2d RSA public and private key encoding Crypto Library

d2i/i2d RSA public and private key encoding

d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey,
d2i_RSA_PUBKEY, i2d_RSA_PUBKEY, i2d_Netscape_RSA, d2i_Netscape_RSA - RSA public and
private key encoding functions.
SYNOPSIS
#include <openssl/rsa.h>

RSA * d2i_RSAPublicKey(RSA **a, unsigned char **pp, long length);

int i2d_RSAPublicKey(RSA *a, unsigned char **pp);

RSA * d2i_RSA_PUBKEY(RSA **a, unsigned char **pp, long length);

int i2d_RSA_PUBKEY(RSA *a, unsigned char **pp);

RSA * d2i_RSAPrivateKey(RSA **a, unsigned char **pp, long length);

int i2d_RSAPrivateKey(RSA *a, unsigned char **pp);

int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());

RSA * d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)());
DESCRIPTION
d2i_RSAPublicKey() and i2d_RSAPublicKey() decode and encode a PKCS#1 RSAPublicKey structure.

d2i_RSA_PUKEY() and i2d_RSA_PUKEY() decode and encode an RSA public key using a
SubjectPublicKeyInfo (certificate public key) structure.
d2i_RSAPrivateKey(), i2d_RSAPrivateKey() decode and encode a PKCS#1 RSAPrivateKey structure.
d2i_Netscape_RSA(), i2d_Netscape_RSA() decode and encode an RSA private key in NET format.
The usage of all of these functions is similar to the d2i_X509() and i2d_X509() described in the
d2i_X509(3)|d2i_X509(3) manual page.
NOTES
The RSA structure passed to the private key encoding functions should have all the PKCS#1 private key
components present.
The data encoded by the private key functions is unencrypted and therefore offers no private key
security.
The NET format functions are present to provide compatibility with certain very old software. This
format has some severe security weaknesses and should be avoided if possible.
SEE ALSO
d2i_X509(3)|d2i_X509(3)
HISTORY
TBA

82 05 July 2003
Crypto Library d2i/i2d X509 encode and decode

d2i/i2d X509 encode and decode

d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio, i2d_X509_fp - X509 encode and
decode functions
SYNOPSIS
#include <openssl/x509.h>

X509 *d2i_X509(X509 **px, unsigned char **in, int len);

int i2d_X509(X509 *x, unsigned char **out);

X509 *d2i_X509_bio(BIO *bp, X509 **x);

X509 *d2i_X509_fp(FILE *fp, X509 **x);

int i2d_X509_bio(X509 *x, BIO *bp);

int i2d_X509_fp(X509 *x, FILE *fp);
DESCRIPTION
The X509 encode and decode routines encode and parse an X509 structure, which represents an X509
certificate.
d2i_X509() attempts to decode len bytes at *out. If successful a pointer to the X509 structure is
returned. If an error occurred then NULL is returned. If px is not NULL then the returned structure is
written to *px. If *px is not NULL then it is assumed that *px contains a valid X509 structure and an
attempt is made to reuse it. If the call is successful *out is incremented to the byte following the parsed
data.
i2d_X509() encodes the structure pointed to by x into DER format. If out is not NULL is writes the
DER encoded data to the buffer at *out, and increments it to point after the data just written. If the return
value is negative an error occurred, otherwise it returns the length of the encoded data.
For OpenSSL 0.9.7 and later if *out is NULL memory will be allocated for a buffer and the encoded
data written to it. In this case *out is not incremented and it points to the start of the data just written.
d2i_X509_bio() is similar to d2i_X509() except it attempts to parse data from BIO bp.
d2i_X509_fp() is similar to d2i_X509() except it attempts to parse data from FILE pointer fp.
i2d_X509_bio() is similar to i2d_X509() except it writes the encoding of the structure x to BIO bp and it
returns 1 for success and 0 for failure.
i2d_X509_fp() is similar to i2d_X509() except it writes the encoding of the structure x to BIO bp and it
returns 1 for success and 0 for failure.
NOTES
The letters i and d in for example i2d_X509 stand for "internal" (that is an internal C structure) and
"DER". So that i2d_X509 converts from internal to DER.
The functions can also understand BER forms.
The actual X509 structure passed to i2d_X509() must be a valid populated X509 structure it can not
simply be fed with an empty structure such as that returned by X509_new().
The encoded data is in binary form and may contain embedded zeroes. Therefore any FILE pointers or
BIOs should be opened in binary mode. Functions such as strlen() will not return the correct length of
the encoded structure.
The ways that *in and *out are incremented after the operation can trap the unwary. See the
WARNINGS section for some common errors.
The reason for the auto increment behaviour is to reflect a typical usage of ASN1 functions: after one
structure is encoded or decoded another will processed after it.
EXAMPLES
Allocate and encode the DER encoding of an X509 structure:
int len;
unsigned char *buf, *p;

len = i2d_X509(x, NULL);

buf = OPENSSL_malloc(len);

if (buf == NULL)

05 July 2003 83
d2i/i2d X509 encode and decode Crypto Library

/* error */

p = buf;

i2d_X509(x, &p);

If you are using OpenSSL 0.9.7 or later then this can be simplified to:

int len;
unsigned char *buf;

buf = NULL;

len = i2d_X509(x, &buf);

if (len < 0)
/* error */

Attempt to decode a buffer:

X509 *x;

unsigned char *buf, *p;

int len;

/* Something to setup buf and len */

p = buf;

x = d2i_X509(NULL, &p, len);

if (x == NULL)
/* Some error */

Alternative technique:
X509 *x;

unsigned char *buf, *p;

int len;

/* Something to setup buf and len */

p = buf;

x = NULL;

if(!d2i_X509(&x, &p, len))

/* Some error */
WARNINGS
The use of temporary variable is mandatory. A common mistake is to attempt to use a buffer directly as
follows:
int len;
unsigned char *buf;

len = i2d_X509(x, NULL);

84 05 July 2003
Crypto Library d2i/i2d X509 encode and decode

buf = OPENSSL_malloc(len);

if (buf == NULL)
/* error */

i2d_X509(x, &buf);

/* Other stuff ... */

OPENSSL_free(buf);

This code will result in buf apparently containing garbage because it was incremented after the call to
point after the data just written. Also buf will no longer contain the pointer allocated by
OPENSSL_malloc() and the subsequent call to OPENSSL_free() may well crash.
The auto allocation feature (setting buf to NULL) only works on OpenSSL 0.9.7 and later. Attempts to
use it on earlier versions will typically cause a segmentation violation.
Another trap to avoid is misuse of the xp argument to d2i_X509():
X509 *x;

if (!d2i_X509(&x, &p, len))

/* Some error */

This will probably crash somewhere in d2i_X509(). The reason for this is that the variable x is
uninitialized and an attempt will be made to interpret its (invalid) value as an X509 structure, typically
causing a segmentation violation. If x is set to NULL first then this will not happen.
BUGS
In some versions of OpenSSL the "reuse" behaviour of d2i_X509() when *px is valid is broken and
some parts of the reused structure may persist if they are not present in the new one. As a result the use
of this "reuse" behaviour is strongly discouraged.
i2d_X509() will not return an error in many versions of OpenSSL, if mandatory fields are not initialized
due to a programming error then the encoded structure may contain invalid data or omit the fields
entirely and will not be parsed by d2i_X509(). This may be fixed in future so code should not assume
that i2d_X509() will always succeed.
RETURN VALUES
d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid X509 structure or NULL if an error
occurs. The error code that can be obtained by ERR_get_error(3)|ERR_get_error(3).
i2d_X509(), i2d_X509_bio() and i2d_X509_fp() return a the number of bytes successfully encoded or a
negative value if an error occurs. The error code can be obtained by
ERR_get_error(3)|ERR_get_error(3).
i2d_X509_bio() and i2d_X509_fp() returns 1 for success and 0 if an error occurs The error code can be
obtained by ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
ERR_get_error(3)|ERR_get_error(3)
HISTORY
d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio and i2d_X509_fp are available in all
versions of SSLeay and OpenSSL.

05 July 2003 85
d2i/i2d AlgorithmIdentifier Crypto Library

d2i/i2d AlgorithmIdentifier
d2i_X509_ALGOR, i2d_X509_ALGOR - AlgorithmIdentifier functions.
SYNOPSIS
#include <openssl/x509.h>

X509_ALGOR *d2i_X509_ALGOR(X509_ALGOR **a, unsigned char **pp, long length);

int i2d_X509_ALGOR(X509_ALGOR *a, unsigned char **pp);
DESCRIPTION
These functions decode and encode an X509_ALGOR structure which is equivalent to the
AlgorithmIdentifier structure.
Othewise these behave in a similar way to d2i_X509() and i2d_X509() described in the
d2i_X509(3)|d2i_X509(3) manual page.
SEE ALSO
d2i_X509(3)|d2i_X509(3)
HISTORY
TBA

86 05 July 2003
Crypto Library d2i/i2d PKCS#10 certificate request

d2i/i2d PKCS#10 certificate request

d2i_X509_CRL, i2d_X509_CRL, d2i_X509_CRL_bio, d2i_509_CRL_fp, i2d_X509_CRL_bio,
i2d_X509_CRL_fp - PKCS#10 certificate request functions.
SYNOPSIS
#include <openssl/x509.h>

X509_CRL *d2i_X509_CRL(X509_CRL **a, unsigned char **pp, long length);

int i2d_X509_CRL(X509_CRL *a, unsigned char **pp);

X509_CRL *d2i_X509_CRL_bio(BIO *bp, X509_CRL **x);

X509_CRL *d2i_X509_CRL_fp(FILE *fp, X509_CRL **x);

int i2d_X509_CRL_bio(X509_CRL *x, BIO *bp);

int i2d_X509_CRL_fp(X509_CRL *x, FILE *fp);
DESCRIPTION
These functions decode and encode an X509 CRL (certificate revocation list).
Othewise the functions behave in a similar way to d2i_X509() and i2d_X509() described in the
d2i_X509(3)|d2i_X509(3) manual page.
SEE ALSO
d2i_X509(3)|d2i_X509(3)
HISTORY
TBA

05 July 2003 87
d2i/i2d X509_NAME encoding Crypto Library

d2i/i2d X509_NAME encoding

d2i_X509_NAME, i2d_X509_NAME - X509_NAME encoding functions
SYNOPSIS
#include <openssl/x509.h>

X509_NAME *d2i_X509_NAME(X509_NAME **a, unsigned char **pp, long length);

int i2d_X509_NAME(X509_NAME *a, unsigned char **pp);
DESCRIPTION
These functions decode and encode an X509_NAME structure which is the the same as the Name type
defined in RFC2459 (and elsewhere) and used for example in certificate subject and issuer names.
Othewise the functions behave in a similar way to d2i_X509() and i2d_X509() described in the
d2i_X509(3)|d2i_X509(3) manual page.
SEE ALSO
d2i_X509(3)|d2i_X509(3)
HISTORY
TBA

88 05 July 2003
Crypto Library d2i/i2d PKCS#10 certificate request

d2i/i2d PKCS#10 certificate request

d2i_X509_REQ, i2d_X509_REQ, d2i_X509_REQ_bio, d2i_X509_REQ_fp, i2d_X509_REQ_bio,
i2d_X509_REQ_fp - PKCS#10 certificate request functions.
SYNOPSIS
#include <openssl/x509.h>

X509_REQ *d2i_X509_REQ(X509_REQ **a, unsigned char **pp, long length);

int i2d_X509_REQ(X509_REQ *a, unsigned char **pp);

X509_REQ *d2i_X509_REQ_bio(BIO *bp, X509_REQ **x);

X509_REQ *d2i_X509_REQ_fp(FILE *fp, X509_REQ **x);

int i2d_X509_REQ_bio(X509_REQ *x, BIO *bp);

int i2d_X509_REQ_fp(X509_REQ *x, FILE *fp);
DESCRIPTION
These functions decode and encode a PKCS#10 certificate request.
Othewise these behave in a similar way to d2i_X509() and i2d_X509() described in the
d2i_X509(3)|d2i_X509(3) manual page.
SEE ALSO
d2i_X509(3)|d2i_X509(3)
HISTORY
TBA

05 July 2003 89
d2i/i2d DigestInfo Crypto Library

d2i/i2d DigestInfo
d2i_X509_SIG, i2d_X509_SIG - DigestInfo functions.
SYNOPSIS
#include <openssl/x509.h>

X509_SIG *d2i_X509_SIG(X509_SIG **a, unsigned char **pp, long length);

int i2d_X509_SIG(X509_SIG *a, unsigned char **pp);
DESCRIPTION
These functions decode and encode an X509_SIG structure which is equivalent to the DigestInfo
structure defined in PKCS#1 and PKCS#7.
Othewise these behave in a similar way to d2i_X509() and i2d_X509() described in the
d2i_X509(3)|d2i_X509(3) manual page.
SEE ALSO
d2i_X509(3)|d2i_X509(3)
HISTORY
TBA

90 05 July 2003
Crypto Library DES encryption

DES encryption
DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked, DES_set_key_unchecked,
DES_set_odd_parity, DES_is_weak_key, DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt,
DES_ncbc_encrypt, DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt,
DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt, DES_ede2_cfb64_encrypt,
DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt, DES_ede3_cbcm_encrypt,
DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt, DES_cbc_cksum, DES_quad_cksum,
DES_string_to_key, DES_string_to_2keys, DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write -
DES encryption
SYNOPSIS
#include <openssl/des.h>

void DES_random_key(DES_cblock *ret);

int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule);

int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule);
int DES_set_key_checked(const_DES_cblock *key,
DES_key_schedule *schedule);
void DES_set_key_unchecked(const_DES_cblock *key,
DES_key_schedule *schedule);

void DES_set_odd_parity(DES_cblock *key);

int DES_is_weak_key(const_DES_cblock *key);

void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output,

DES_key_schedule *ks, int enc);
void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output,
DES_key_schedule *ks1, DES_key_schedule *ks2, int enc);
void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output,
DES_key_schedule *ks1, DES_key_schedule *ks2,
DES_key_schedule *ks3, int enc);

void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output,

long length, DES_key_schedule *schedule, DES_cblock *ivec,
int enc);
void DES_cfb_encrypt(const unsigned char *in, unsigned char *out,
int numbits, long length, DES_key_schedule *schedule,
DES_cblock *ivec, int enc);
void DES_ofb_encrypt(const unsigned char *in, unsigned char *out,
int numbits, long length, DES_key_schedule *schedule,
DES_cblock *ivec);
void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
int enc);
void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
int *num, int enc);
void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
int *num);

void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output,

long length, DES_key_schedule *schedule, DES_cblock *ivec,
const_DES_cblock *inw, const_DES_cblock *outw, int enc);

void DES_ede2_cbc_encrypt(const unsigned char *input,

unsigned char *output, long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_cblock *ivec, int enc);

05 July 2003 91
DES encryption Crypto Library

void DES_ede2_cfb64_encrypt(const unsigned char *in,

unsigned char *out, long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_cblock *ivec, int *num, int enc);
void DES_ede2_ofb64_encrypt(const unsigned char *in,
unsigned char *out, long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_cblock *ivec, int *num);

void DES_ede3_cbc_encrypt(const unsigned char *input,

unsigned char *output, long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec,
int enc);
void DES_ede3_cbcm_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *ks1, DES_key_schedule *ks2,
DES_key_schedule *ks3, DES_cblock *ivec1, DES_cblock *ivec2,
int enc);
void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *ks1, DES_key_schedule *ks2,
DES_key_schedule *ks3, DES_cblock *ivec, int *num, int enc);
void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_key_schedule *ks3,
DES_cblock *ivec, int *num);

DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output,

long length, DES_key_schedule *schedule,
const_DES_cblock *ivec);
DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[],
long length, int out_count, DES_cblock *seed);
void DES_string_to_key(const char *str, DES_cblock *key);
void DES_string_to_2keys(const char *str, DES_cblock *key1,
DES_cblock *key2);

char *DES_fcrypt(const char *buf, const char *salt, char *ret);

char *DES_crypt(const char *buf, const char *salt);

int DES_enc_read(int fd, void *buf, int len, DES_key_schedule *sched,

DES_cblock *iv);
int DES_enc_write(int fd, const void *buf, int len,
DES_key_schedule *sched, DES_cblock *iv);
DESCRIPTION
This library contains a fast implementation of the DES encryption algorithm.
There are two phases to the use of DES encryption. The first is the generation of a DES_key_schedule
from a key, the second is the actual encryption. A DES key is of type DES_cblock. This type is consists
of 8 bytes with odd parity. The least significant bit in each byte is the parity bit. The key schedule is an
expanded form of the key; it is used to speed the encryption process.
DES_random_key() generates a random key. The PRNG must be seeded prior to using this function
(see rand(3)|rand(3)). If the PRNG could not generate a secure key, 0 is returned.
Before a DES key can be used, it must be converted into the architecture dependent DES_key_schedule
via the DES_set_key_checked() or DES_set_key_unchecked() function.
DES_set_key_checked() will check that the key passed is of odd parity and is not a week or semi-weak
key. If the parity is wrong, then -1 is returned. If the key is a weak key, then -2 is returned. If an error
is returned, the key schedule is not generated.
DES_set_key() works like DES_set_key_checked() if the DES_check_key flag is non-zero, otherwise
like DES_set_key_unchecked(). These functions are available for compatibility; it is recommended to
use a function that does not depend on a global variable.
DES_set_odd_parity() sets the parity of the passed key to odd.
DES_is_weak_key() returns 1 is the passed key is a weak key, 0 if it is ok. The probability that a
randomly generated key is weak is 1/2^52, so it is not really worth checking for them.

92 05 July 2003
Crypto Library DES encryption

The following routines mostly operate on an input and output stream of DES_cblocks.
DES_ecb_encrypt() is the basic DES encryption routine that encrypts or decrypts a single 8-byte
DES_cblock in electronic code book (ECB) mode. It always transforms the input data, pointed to by
input, into the output data, pointed to by the output argument. If the encrypt argument is non-zero
(DES_ENCRYPT), the input (cleartext) is encrypted in to the output (ciphertext) using the key_schedule
specified by the schedule argument, previously set via DES_set_key. If encrypt is zero
(DES_DECRYPT), the input (now ciphertext) is decrypted into the output (now cleartext). Input and
output may overlap. DES_ecb_encrypt() does not return a value.
DES_ecb3_encrypt() encrypts/decrypts the input block by using three-key Triple-DES encryption in
ECB mode. This involves encrypting the input with ks1, decrypting with the key schedule ks2, and then
encrypting with ks3. This routine greatly reduces the chances of brute force breaking of DES and has
the advantage of if ks1, ks2 and ks3 are the same, it is equivalent to just encryption using ECB mode and
ks1 as the key.
The macro DES_ecb2_encrypt() is provided to perform two-key Triple-DES encryption by using ks1 for
the final encryption.
DES_ncbc_encrypt() encrypts/decrypts using the cipher-block-chaining (CBC) mode of DES. If the
encrypt argument is non-zero, the routine cipher-block-chain encrypts the cleartext data pointed to by the
input argument into the ciphertext pointed to by the output argument, using the key schedule provided by
the schedule argument, and initialization vector provided by the ivec argument. If the length argument is
not an integral multiple of eight bytes, the last block is copied to a temporary area and zero filled. The
output is always an integral multiple of eight bytes.
DES_xcbc_encrypt() is RSA‘s DESX mode of DES. It uses inw and outw to ‘whiten’ the encryption.
inw and outw are secret (unlike the iv) and are as such, part of the key. So the key is sort of 24 bytes.
This is much better than CBC DES.
DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with three keys. This means that
each DES operation inside the CBC mode is really an C=E(ks3,D(ks2,E(ks1,M))). This mode is
used by SSL.
The DES_ede2_cbc_encrypt() macro implements two-key Triple-DES by reusing ks1 for the final
encryption. C=E(ks1,D(ks2,E(ks1,M))). This form of Triple-DES is used by the RSAREF
library.
DES_pcbc_encrypt() encrypt/decrypts using the propagating cipher block chaining mode used by
Kerberos v4. Its parameters are the same as DES_ncbc_encrypt().
DES_cfb_encrypt() encrypt/decrypts using cipher feedback mode. This method takes an array of
characters as input and outputs and array of characters. It does not require any padding to 8 character
groups. Note: the ivec variable is changed and the new changed value needs to be passed to the next call
to this function. Since this function runs a complete DES ECB encryption per numbits, this function is
only suggested for use when sending small numbers of characters.
DES_cfb64_encrypt() implements CFB mode of DES with 64bit feedback. Why is this useful you ask?
Because this routine will allow you to encrypt an arbitrary number of bytes, no 8 byte padding. Each
call to this routine will encrypt the input bytes to output and then update ivec and num. num contains
‘how far’ we are though ivec. If this does not make much sense, read more about cfb mode of DES :-).
DES_ede3_cfb64_encrypt() and DES_ede2_cfb64_encrypt() is the same as DES_cfb64_encrypt() except
that Triple-DES is used.
DES_ofb_encrypt() encrypts using output feedback mode. This method takes an array of characters as
input and outputs and array of characters. It does not require any padding to 8 character groups. Note:
the ivec variable is changed and the new changed value needs to be passed to the next call to this
function. Since this function runs a complete DES ECB encryption per numbits, this function is only
suggested for use when sending small numbers of characters.
DES_ofb64_encrypt() is the same as DES_cfb64_encrypt() using Output Feed Back mode.
DES_ede3_ofb64_encrypt() and DES_ede2_ofb64_encrypt() is the same as DES_ofb64_encrypt(), using
Triple-DES.
The following functions are included in the DES library for compatibility with the MIT Kerberos library.

DES_cbc_cksum() produces an 8 byte checksum based on the input stream (via CBC encryption). The
last 4 bytes of the checksum are returned and the complete 8 bytes are placed in output. This function is
used by Kerberos v4. Other applications should use EVP_DigestInit(3)|EVP_DigestInit(3) etc. instead.
DES_quad_cksum() is a Kerberos v4 function. It returns a 4 byte checksum from the input bytes. The
algorithm can be iterated over the input, depending on out_count, 1, 2, 3 or 4 times. If output is
non-NULL, the 8 bytes generated by each pass are written into output.

05 July 2003 93
DES encryption Crypto Library

The following are DES-based transformations:

DES_fcrypt() is a fast version of the Unix crypt(3) function. This version takes only a small amount of
space relative to other fast crypt() implementations. This is different to the normal crypt in that the third
parameter is the buffer that the return value is written into. It needs to be at least 14 bytes long. This
function is thread safe, unlike the normal crypt.
DES_crypt() is a faster replacement for the normal system crypt(). This function calls DES_fcrypt() with
a static array passed as the third parameter. This emulates the normal non-thread safe semantics of
crypt(3).
DES_enc_write() writes len bytes to file descriptor fd from buffer buf. The data is encrypted via
pcbc_encrypt (default) using sched for the key and iv as a starting vector. The actual data send down fd
consists of 4 bytes (in network byte order) containing the length of the following encrypted data. The
encrypted data then follows, padded with random data out to a multiple of 8 bytes.
DES_enc_read() is used to read len bytes from file descriptor fd into buffer buf. The data being read
from fd is assumed to have come from DES_enc_write() and is decrypted using sched for the key
schedule and iv for the initial vector.
Warning: The data format used by DES_enc_write() and DES_enc_read() has a cryptographic
weakness: When asked to write more than MAXWRITE bytes, DES_enc_write() will split the data into
several chunks that are all encrypted using the same IV. So don‘t use these functions unless you are sure
you know what you do (in which case you might not want to use them anyway). They cannot handle
non-blocking sockets. DES_enc_read() uses an internal state and thus cannot be used on multiple files.
DES_rw_mode is used to specify the encryption mode to use with DES_enc_read() and
DES_end_write(). If set to DES_PCBC_MODE (the default), DES_pcbc_encrypt is used. If set to
DES_CBC_MODE DES_cbc_encrypt is used.
NOTES
Single-key DES is insecure due to its short key size. ECB mode is not suitable for most applications;
see DES_modes(7)|DES_modes(7).
The evp(3)|evp(3) library provides higher-level encryption functions.
BUGS
DES_3cbc_encrypt() is flawed and must not be used in applications.
DES_cbc_encrypt() does not modify ivec; use DES_ncbc_encrypt() instead.
DES_cfb_encrypt() and DES_ofb_encrypt() operates on input of 8 bits. What this means is that if you
set numbits to 12, and length to 2, the first 12 bits will come from the 1st input byte and the low half of
the second input byte. The second 12 bits will have the low 8 bits taken from the 3rd input byte and the
top 4 bits taken from the 4th input byte. The same holds for output. This function has been
implemented this way because most people will be using a multiple of 8 and because once you get into
pulling bytes input bytes apart things get ugly!
DES_string_to_key() is available for backward compatibility with the MIT library. New applications
should use a cryptographic hash function. The same applies for DES_string_to_2key().
CONFORMING TO
ANSI X3.106
The des library was written to be source code compatible with the MIT Kerberos library.
SEE ALSO
crypt(3), des_modes(7)|des_modes(7), evp(3)|evp(3), rand(3)|rand(3)
HISTORY
In OpenSSL 0.9.7, all des_ functions were renamed to DES_ to avoid clashes with older versions of
libdes. Compatibility des_ functions are provided for a short while, as well as crypt(). Declarations for
these are in <openssl/des_old.h>. There is no DES_ variant for des_random_seed(). This will happen to
other functions as well if they are deemed redundant (des_random_seed() just calls RAND_seed() and is
present for backward compatibility only), buggy or already scheduled for removal.
des_cbc_cksum(), des_cbc_encrypt(), des_ecb_encrypt(), des_is_weak_key(), des_key_sched(),
des_pcbc_encrypt(), des_quad_cksum(), des_random_key() and des_string_to_key() are available in the
MIT Kerberos library; des_check_key_parity(), des_fixup_key_parity() and des_is_weak_key() are
available in newer versions of that library.
des_set_key_checked() and des_set_key_unchecked() were added in OpenSSL 0.9.5.
des_generate_random_block(), des_init_random_number_generator(), des_new_random_key(),
des_set_random_generator_seed() and des_set_sequence_number() and des_rand_data() are used in

94 05 July 2003
Crypto Library DES encryption

newer versions of Kerberos but are not implemented here.

des_random_key() generated cryptographically weak random data in SSLeay and in OpenSSL prior
version 0.9.5, as well as in the original MIT library.
AUTHOR
Eric Young ([email protected]). Modified for the OpenSSL project (http://www.openssl.org).

05 July 2003 95
DES modes Crypto Library

DES modes
Modes of DES - the variants of DES and other crypto algorithms of OpenSSL
DESCRIPTION
Several crypto algorithms for OpenSSL can be used in a number of modes. Those are used for using
block ciphers in a way similar to stream ciphers, among other things.
OVERVIEW
Electronic Codebook Mode (ECB)
Normally, this is found as the function algorithm_ecb_encrypt().

64 bits are enciphered at a time.

The order of the blocks can be rearranged without detection.
The same plaintext block always produces the same ciphertext block (for the same key) making it
vulnerable to a ‘dictionary attack’.
An error will only affect one ciphertext block.

Cipher Block Chaining Mode (CBC)

Normally, this is found as the function algorithm_cbc_encrypt(). Be aware that des_cbc_encrypt() is not
really DES CBC (it does not update the IV); use des_ncbc_encrypt() instead.

a multiple of 64 bits are enciphered at a time.

The CBC mode produces the same ciphertext whenever the same plaintext is encrypted using the
same key and starting variable.
The chaining operation makes the ciphertext blocks dependent on the current and all preceding
plaintext blocks and therefore blocks can not be rearranged.
The use of different starting variables prevents the same plaintext enciphering to the same ciphertext.
An error will affect the current and the following ciphertext blocks.

Cipher Feedback Mode (CFB)

Normally, this is found as the function algorithm_cfb_encrypt().

a number of bits (j) <= 64 are enciphered at a time.

The CFB mode produces the same ciphertext whenever the same plaintext is encrypted using the
same key and starting variable.
The chaining operation makes the ciphertext variables dependent on the current and all preceding
variables and therefore j-bit variables are chained together and can not be rearranged.
The use of different starting variables prevents the same plaintext enciphering to the same ciphertext.
The strength of the CFB mode depends on the size of k (maximal if j == k). In my implementation
this is always the case.
Selection of a small value for j will require more cycles through the encipherment algorithm per unit
of plaintext and thus cause greater processing overheads.
Only multiples of j bits can be enciphered.
An error will affect the current and the following ciphertext variables.

Output Feedback Mode (OFB)

Normally, this is found as the function algorithm_ofb_encrypt().

a number of bits (j) <= 64 are enciphered at a time.

The OFB mode produces the same ciphertext whenever the same plaintext enciphered using the same
key and starting variable. More over, in the OFB mode the same key stream is produced when the
same key and start variable are used. Consequently, for security reasons a specific start variable
should be used only once for a given key.

96 05 July 2003
Crypto Library DES modes

The absence of chaining makes the OFB more vulnerable to specific attacks.
The use of different start variables values prevents the same plaintext enciphering to the same
ciphertext, by producing different key streams.
Selection of a small value for j will require more cycles through the encipherment algorithm per unit
of plaintext and thus cause greater processing overheads.
Only multiples of j bits can be enciphered.
OFB mode of operation does not extend ciphertext errors in the resultant plaintext output. Every bit
error in the ciphertext causes only one bit to be in error in the deciphered plaintext.
OFB mode is not self-synchronizing. If the two operation of encipherment and decipherment get out
of synchronism, the system needs to be re-initialized.
Each re-initialization should use a value of the start variable different from the start variable values
used before with the same key. The reason for this is that an identical bit stream would be produced
each time from the same parameters. This would be susceptible to a ‘known plaintext’ attack.

Triple ECB Mode

Normally, this is found as the function algorithm_ecb3_encrypt().

Encrypt with key1, decrypt with key2 and encrypt with key3 again.
As for ECB encryption but increases the key length to 168 bits. There are theoretic attacks that can be
used that make the effective key length 112 bits, but this attack also requires 2^56 blocks of memory,
not very likely, even for the NSA.
If both keys are the same it is equivalent to encrypting once with just one key.
If the first and last key are the same, the key length is 112 bits. There are attacks that could reduce the
effective key strength to only slightly more than 56 bits, but these require a lot of memory.
If all 3 keys are the same, this is effectively the same as normal ecb mode.

Triple CBC Mode

Normally, this is found as the function algorithm_ede3_cbc_encrypt().

Encrypt with key1, decrypt with key2 and then encrypt with key3.
As for CBC encryption but increases the key length to 168 bits with the same restrictions as for triple
ecb mode.

NOTES
This text was been written in large parts by Eric Young in his original documentation for SSLeay, the
predecessor of OpenSSL. In turn, he attributed it to:
AS 2805.5.2
Australian Standard
Electronic funds transfer - Requirements for interfaces,
Part 5.2: Modes of operation for an n-bit block cipher algorithm
Appendix A
SEE ALSO
blowfish(3)|blowfish(3), des(3)|des(3), idea(3)|idea(3), rc2(3)|rc2(3)

05 July 2003 97
DH - Diffie-Hellman key agreement Crypto Library

DH - Diffie-Hellman key agreement

DH - Diffie-Hellman key agreement
SYNOPSIS
#include <openssl/dh.h>
#include <openssl/engine.h>

DH * DH_new(void);
void DH_free(DH *dh);

int DH_size(const DH *dh);

DH * DH_generate_parameters(int prime_len, int generator,

void (*callback)(int, int, void *), void *cb_arg);
int DH_check(const DH *dh, int *codes);

int DH_generate_key(DH *dh);

int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);

void DH_set_default_method(const DH_METHOD *meth);

const DH_METHOD *DH_get_default_method(void);
int DH_set_method(DH *dh, const DH_METHOD *meth);
DH *DH_new_method(ENGINE *engine);
const DH_METHOD *DH_OpenSSL(void);

int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(),

int (*dup_func)(), void (*free_func)());
int DH_set_ex_data(DH *d, int idx, char *arg);
char *DH_get_ex_data(DH *d, int idx);

DH * d2i_DHparams(DH **a, unsigned char **pp, long length);

int i2d_DHparams(const DH *a, unsigned char **pp);

int DHparams_print_fp(FILE *fp, const DH *x);

int DHparams_print(BIO *bp, const DH *x);
DESCRIPTION
These functions implement the Diffie-Hellman key agreement protocol. The generation of shared DH
parameters is described in DH_generate_parameters(3)|DH_generate_parameters(3);
DH_generate_key(3)|DH_generate_key(3) describes how to perform a key agreement.
The DH structure consists of several BIGNUM components.
struct
{
BIGNUM *p; // prime number (shared)
BIGNUM *g; // generator of Z_p (shared)
BIGNUM *priv_key; // private DH value x
BIGNUM *pub_key; // public DH value g^x
// ...
};
DH

Note that DH keys may use non-standard DH_METHOD implementations, either directly or by the use
of ENGINE modules. In some cases (eg. an ENGINE providing support for hardware-embedded keys),
these BIGNUM values will not be used by the implementation or may be used for alternative data
storage. For this reason, applications should generally avoid using DH structure elements directly and
instead use API functions to query or modify keys.

98 05 July 2003
Crypto Library DH - Diffie-Hellman key agreement

SEE ALSO
dhparam(1)|dhparam(1), bn(3)|bn(3), dsa(3)|dsa(3), err(3)|err(3), rand(3)|rand(3), rsa(3)|rsa(3),
engine(3)|engine(3), DH_set_method(3)|DH_set_method(3), DH_new(3)|DH_new(3),
DH_get_ex_new_index(3)|DH_get_ex_new_index(3),
DH_generate_parameters(3)|DH_generate_parameters(3), DH_compute_key(3)|DH_compute_key(3),
d2i_DHparams(3)|d2i_DHparams(3), RSA_print(3)|RSA_print(3)

05 July 2003 99
DH Diffie-Hellman key exchange Crypto Library

DH Diffie-Hellman key exchange

DH_generate_key, DH_compute_key - perform Diffie-Hellman key exchange
SYNOPSIS
#include <openssl/dh.h>

int DH_generate_key(DH *dh);

int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);

DESCRIPTION
DH_generate_key() performs the first step of a Diffie-Hellman key exchange by generating private and
public DH values. By calling DH_compute_key(), these are combined with the other party‘s public
value to compute the shared key.
DH_generate_key() expects dh to contain the shared parameters dh-p and dh-g. It generates a random
private DH value unless dh-priv_key is already set, and computes the corresponding public value
dh-pub_key, which can then be published.
DH_compute_key() computes the shared secret from the private DH value in dh and the other party‘s
public value in pub_key and stores it in key. key must point to DH_size(dh) bytes of memory.
RETURN VALUES
DH_generate_key() returns 1 on success, 0 otherwise.
DH_compute_key() returns the size of the shared secret on success, -1 on error.
The error codes can be obtained by ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
dh(3)|dh(3), ERR_get_error(3)|ERR_get_error(3), rand(3)|rand(3), DH_size(3)|DH_size(3)
HISTORY
DH_generate_key() and DH_compute_key() are available in all versions of SSLeay and OpenSSL.

100 05 July 2003

Crypto Library DH generate and check

DH generate and check

DH_generate_parameters, DH_check - generate and check Diffie-Hellman parameters
SYNOPSIS
#include <openssl/dh.h>

DH *DH_generate_parameters(int prime_len, int generator,

void (*callback)(int, int, void *), void *cb_arg);

int DH_check(DH *dh, int *codes);

DESCRIPTION
DH_generate_parameters() generates Diffie-Hellman parameters that can be shared among a group of
users, and returns them in a newly allocated DH structure. The pseudo-random number generator must
be seeded prior to calling DH_generate_parameters().
prime_len is the length in bits of the safe prime to be generated. generator is a small number 1,
typically 2 or 5.
A callback function may be used to provide feedback about the progress of the key generation. If
callback is not NULL, it will be called as described in BN_generate_prime(3)|BN_generate_prime(3)
while a random prime number is generated, and when a prime has been found, callback(3, 0, cb_arg) is
called.
DH_check() validates Diffie-Hellman parameters. It checks that p is a safe prime, and that g is a suitable
generator. In the case of an error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or
DH_NOT_SUITABLE_GENERATOR are set in *codes. DH_UNABLE_TO_CHECK_GENERATOR
is set if the generator cannot be checked, i.e. it does not equal 2 or 5.
RETURN VALUES
DH_generate_parameters() returns a pointer to the DH structure, or NULL if the parameter generation
fails. The error codes can be obtained by ERR_get_error(3)|ERR_get_error(3).
DH_check() returns 1 if the check could be performed, 0 otherwise.
NOTES
DH_generate_parameters() may run for several hours before finding a suitable prime.
The parameters generated by DH_generate_parameters() are not to be used in signature schemes.
BUGS
If generator is not 2 or 5, dh-g=generator is not a usable generator.
SEE ALSO
dh(3)|dh(3), ERR_get_error(3)|ERR_get_error(3), rand(3)|rand(3), DH_free(3)|DH_free(3)
HISTORY
DH_check() is available in all versions of SSLeay and OpenSSL. The cb_arg argument to
DH_generate_parameters() was added in SSLeay 0.9.0.
In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used instead of
DH_CHECK_P_NOT_SAFE_PRIME.

05 July 2003 101

DH add application data Crypto Library

DH add application data

DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data - add application specific data to DH
structures
SYNOPSIS
#include <openssl/dh.h>

int DH_get_ex_new_index(long argl, void *argp,

CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);

int DH_set_ex_data(DH *d, int idx, void *arg);

char *DH_get_ex_data(DH *d, int idx);

DESCRIPTION
These functions handle application specific data in DH structures. Their usage is identical to that of
RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() as described in
RSA_get_ex_new_index(3).
SEE ALSO
RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3), dh(3)|dh(3)
HISTORY
DH_get_ex_new_index(), DH_set_ex_data() and DH_get_ex_data() are available since OpenSSL 0.9.5.

102 05 July 2003

Crypto Library DH allocation

DH allocation
DH_new, DH_free - allocate and free DH objects
SYNOPSIS
#include <openssl/dh.h>

DH* DH_new(void);

void DH_free(DH *dh);

DESCRIPTION
DH_new() allocates and initializes a DH structure.
DH_free() frees the DH structure and its components. The values are erased before the memory is
returned to the system.
RETURN VALUES
If the allocation fails, DH_new() returns NULL and sets an error code that can be obtained by
ERR_get_error(3)|ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.
DH_free() returns no value.
SEE ALSO
dh(3)|dh(3), ERR_get_error(3)|ERR_get_error(3),
DH_generate_parameters(3)|DH_generate_parameters(3), DH_generate_key(3)|DH_generate_key(3)
HISTORY
DH_new() and DH_free() are available in all versions of SSLeay and OpenSSL.

05 July 2003 103

DH select method Crypto Library

DH select method
DH_set_default_method, DH_get_default_method, DH_set_method, DH_new_method, DH_OpenSSL -
select DH method
SYNOPSIS
#include <openssl/dh.h>
#include <openssl/engine.h>

void DH_set_default_method(const DH_METHOD *meth);

const DH_METHOD *DH_get_default_method(void);

int DH_set_method(DH *dh, const DH_METHOD *meth);

DH *DH_new_method(ENGINE *engine);

const DH_METHOD *DH_OpenSSL(void);

DESCRIPTION
A DH_METHOD specifies the functions that OpenSSL uses for Diffie-Hellman operations. By
modifying the method, alternative implementations such as hardware accelerators may be used.
IMPORTANT: See the NOTES section for important information about how these DH API functions
are affected by the use of ENGINE API calls.
Initially, the default DH_METHOD is the OpenSSL internal implementation, as returned by
DH_OpenSSL().
DH_set_default_method() makes meth the default method for all DH structures created later. NB: This
is true only whilst no ENGINE has been set as a default for DH, so this function is no longer
recommended.
DH_get_default_method() returns a pointer to the current default DH_METHOD. However, the
meaningfulness of this result is dependant on whether the ENGINE API is being used, so this function is
no longer recommended.
DH_set_method() selects meth to perform all operations using the key dh. This will replace the
DH_METHOD used by the DH key and if the previous method was supplied by an ENGINE, the handle
to that ENGINE will be released during the change. It is possible to have DH keys that only work with
certain DH_METHOD implementations (eg. from an ENGINE module that supports embedded
hardware-protected keys), and in such cases attempting to change the DH_METHOD for the key can
have unexpected results.
DH_new_method() allocates and initializes a DH structure so that engine will be used for the DH
operations. If engine is NULL, the default ENGINE for DH operations is used, and if no default
ENGINE is set, the DH_METHOD controlled by DH_set_default_method() is used.
THE DH_METHOD STRUCTURE
typedef struct dh_meth_st
{
/* name of the implementation */
const char *name;

/* generate private and public DH values for key agreement */

int (*generate_key)(DH *dh);

/* compute shared secret */

int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh);

/* compute r = a ^ p mod m (May be NULL for some implementations) */

int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p,
const BIGNUM *m, BN_CTX *ctx,
BN_MONT_CTX *m_ctx);

/* called at DH_new */

104 05 July 2003

Crypto Library DH select method

int (*init)(DH *dh);

/* called at DH_free */
int (*finish)(DH *dh);

int flags;

char *app_data; /* ?? */

} DH_METHOD;
RETURN VALUES
DH_OpenSSL() and DH_get_default_method() return pointers to the respective DH_METHODs.
DH_set_default_method() returns no value.
DH_set_method() returns non-zero if the provided meth was successfully set as the method for dh
(including unloading the ENGINE handle if the previous method was supplied by an ENGINE).
DH_new_method() returns NULL and sets an error code that can be obtained by
ERR_get_error(3)|ERR_get_error(3) if the allocation fails. Otherwise it returns a pointer to the newly
allocated structure.
NOTES
As of version 0.9.7, DH_METHOD implementations are grouped together with other algorithmic APIs
(eg. RSA_METHOD, EVP_CIPHER, etc) in ENGINE modules. If a default ENGINE is specified for
DH functionality using an ENGINE API function, that will override any DH defaults set using the DH
API (ie. DH_set_default_method()). For this reason, the ENGINE API is the recommended way to
control default implementations for use in DH and other cryptographic algorithms.
SEE ALSO
dh(3)|dh(3), DH_new(3)|DH_new(3)
HISTORY
DH_set_default_method(), DH_get_default_method(), DH_set_method(), DH_new_method() and
DH_OpenSSL() were added in OpenSSL 0.9.4.
DH_set_default_openssl_method() and DH_get_default_openssl_method() replaced
DH_set_default_method() and DH_get_default_method() respectively, and DH_set_method() and
DH_new_method() were altered to use ENGINEs rather than DH_METHODs during development of
the engine version of OpenSSL 0.9.6. For 0.9.7, the handling of defaults in the ENGINE API was
restructured so that this change was reversed, and behaviour of the other functions resembled more
closely the previous behaviour. The behaviour of defaults in the ENGINE API now transparently
overrides the behaviour of defaults in the DH API without requiring changing these function prototypes.

05 July 2003 105

DH size Crypto Library

DH size
DH_size - get Diffie-Hellman prime size
SYNOPSIS
#include <openssl/dh.h>

int DH_size(DH *dh);

DESCRIPTION
This function returns the Diffie-Hellman size in bytes. It can be used to determine how much memory
must be allocated for the shared secret computed by DH_compute_key().
dh-p must not be NULL.
RETURN VALUE
The size in bytes.
SEE ALSO
dh(3)|dh(3), DH_generate_key(3)|DH_generate_key(3)
HISTORY
DH_size() is available in all versions of SSLeay and OpenSSL.

106 05 July 2003

Crypto Library DSA - Digital Signature Algorithm

DSA - Digital Signature Algorithm

DSA - Digital Signature Algorithm
SYNOPSIS
#include <openssl/dsa.h>
#include <openssl/engine.h>

DSA * DSA_new(void);
void DSA_free(DSA *dsa);

int DSA_size(const DSA *dsa);

DSA * DSA_generate_parameters(int bits, unsigned char *seed,

int seed_len, int *counter_ret, unsigned long *h_ret,
void (*callback)(int, int, void *), void *cb_arg);

DH * DSA_dup_DH(const DSA *r);

int DSA_generate_key(DSA *dsa);

int DSA_sign(int dummy, const unsigned char *dgst, int len,

unsigned char *sigret, unsigned int *siglen, DSA *dsa);
int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp,
BIGNUM **rp);
int DSA_verify(int dummy, const unsigned char *dgst, int len,
const unsigned char *sigbuf, int siglen, DSA *dsa);

void DSA_set_default_method(const DSA_METHOD *meth);

const DSA_METHOD *DSA_get_default_method(void);
int DSA_set_method(DSA *dsa, const DSA_METHOD *meth);
DSA *DSA_new_method(ENGINE *engine);
const DSA_METHOD *DSA_OpenSSL(void);

int DSA_get_ex_new_index(long argl, char *argp, int (*new_func)(),

int (*dup_func)(), void (*free_func)());
int DSA_set_ex_data(DSA *d, int idx, char *arg);
char *DSA_get_ex_data(DSA *d, int idx);

DSA_SIG *DSA_SIG_new(void);
void DSA_SIG_free(DSA_SIG *a);
int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp);
DSA_SIG *d2i_DSA_SIG(DSA_SIG **v, unsigned char **pp, long length);

DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa);

int DSA_do_verify(const unsigned char *dgst, int dgst_len,
DSA_SIG *sig, DSA *dsa);

DSA * d2i_DSAPublicKey(DSA **a, unsigned char **pp, long length);

DSA * d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length);
DSA * d2i_DSAparams(DSA **a, unsigned char **pp, long length);
int i2d_DSAPublicKey(const DSA *a, unsigned char **pp);
int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp);
int i2d_DSAparams(const DSA *a,unsigned char **pp);

int DSAparams_print(BIO *bp, const DSA *x);

int DSAparams_print_fp(FILE *fp, const DSA *x);
int DSA_print(BIO *bp, const DSA *x, int off);
int DSA_print_fp(FILE *bp, const DSA *x, int off);

05 July 2003 107

DSA - Digital Signature Algorithm Crypto Library

DESCRIPTION
These functions implement the Digital Signature Algorithm (DSA). The generation of shared DSA
parameters is described in DSA_generate_parameters(3)|DSA_generate_parameters(3);
DSA_generate_key(3)|DSA_generate_key(3) describes how to generate a signature key. Signature
generation and verification are described in DSA_sign(3)|DSA_sign(3).
The DSA structure consists of several BIGNUM components.
struct
{
BIGNUM *p; // prime number (public)
BIGNUM *q; // 160-bit subprime, q | p-1 (public)
BIGNUM *g; // generator of subgroup (public)
BIGNUM *priv_key; // private key x
BIGNUM *pub_key; // public key y = g^x
// ...
}
DSA;

In public keys, priv_key is NULL.

Note that DSA keys may use non-standard DSA_METHOD implementations, either directly or by the
use of ENGINE modules. In some cases (eg. an ENGINE providing support for hardware-embedded
keys), these BIGNUM values will not be used by the implementation or may be used for alternative data
storage. For this reason, applications should generally avoid using DSA structure elements directly and
instead use API functions to query or modify keys.
CONFORMING TO
US Federal Information Processing Standard FIPS 186 (Digital Signature Standard, DSS), ANSI X9.30
SEE ALSO
bn(3)|bn(3), dh(3)|dh(3), err(3)|err(3), rand(3)|rand(3), rsa(3)|rsa(3), sha(3)|sha(3),
engine(3)|engine(3), DSA_new(3)|DSA_new(3), DSA_size(3)|DSA_size(3),
DSA_generate_parameters(3)|DSA_generate_parameters(3), DSA_dup_DH(3)|DSA_dup_DH(3),
DSA_generate_key(3)|DSA_generate_key(3), DSA_sign(3)|DSA_sign(3),
DSA_set_method(3)|DSA_set_method(3), DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3),
RSA_print(3)|RSA_print(3)

108 05 July 2003

Crypto Library DSA raw signature

DSA raw signature

DSA_do_sign, DSA_do_verify - raw DSA signature operations
SYNOPSIS
#include <openssl/dsa.h>

DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa);

int DSA_do_verify(const unsigned char *dgst, int dgst_len,

DSA_SIG *sig, DSA *dsa);
DESCRIPTION
DSA_do_sign() computes a digital signature on the len byte message digest dgst using the private key
dsa and returns it in a newly allocated DSA_SIG structure.
DSA_sign_setup(3)|DSA_sign_setup(3) may be used to precompute part of the signing operation in case
signature generation is time-critical.
DSA_do_verify() verifies that the signature sig matches a given message digest dgst of size len. dsa is
the signer‘s public key.
RETURN VALUES
DSA_do_sign() returns the signature, NULL on error. DSA_do_verify() returns 1 for a valid signature,
0 for an incorrect signature and -1 on error. The error codes can be obtained by
ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
dsa(3)|dsa(3), ERR_get_error(3)|ERR_get_error(3), rand(3)|rand(3),
DSA_SIG_new(3)|DSA_SIG_new(3), DSA_sign(3)|DSA_sign(3)
HISTORY
DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3.

05 July 2003 109

DSA dup DH Crypto Library

DSA dup DH
DSA_dup_DH - create a DH structure out of DSA structure
SYNOPSIS
#include <openssl/dsa.h>

DH * DSA_dup_DH(const DSA *r);

DESCRIPTION
DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q is lost during that
conversion, but the resulting DH parameters contain its length.
RETURN VALUE
DSA_dup_DH() returns the new DH structure, and NULL on error. The error codes can be obtained by
ERR_get_error(3)|ERR_get_error(3).
NOTE
Be careful to avoid small subgroup attacks when using this.
SEE ALSO
dh(3)|dh(3), dsa(3)|dsa(3), ERR_get_error(3)|ERR_get_error(3)
HISTORY
DSA_dup_DH() was added in OpenSSL 0.9.4.

110 05 July 2003

Crypto Library DSA generate key pair

DSA generate key pair

DSA_generate_key - generate DSA key pair
SYNOPSIS
#include <openssl/dsa.h>

int DSA_generate_key(DSA *a);

DESCRIPTION
DSA_generate_key() expects a to contain DSA parameters. It generates a new key pair and stores it in
a-pub_key and a-priv_key.
The PRNG must be seeded prior to calling DSA_generate_key().
RETURN VALUE
DSA_generate_key() returns 1 on success, 0 otherwise. The error codes can be obtained by
ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
dsa(3)|dsa(3), ERR_get_error(3)|ERR_get_error(3), rand(3)|rand(3),
DSA_generate_parameters(3)|DSA_generate_parameters(3)
HISTORY
DSA_generate_key() is available since SSLeay 0.8.

05 July 2003 111

DSA generate parameters Crypto Library

DSA generate parameters

DSA_generate_parameters - generate DSA parameters
SYNOPSIS
#include <openssl/dsa.h>

DSA *DSA_generate_parameters(int bits, unsigned char *seed,

int seed_len, int *counter_ret, unsigned long *h_ret,
void (*callback)(int, int, void *), void *cb_arg);
DESCRIPTION
DSA_generate_parameters() generates primes p and q and a generator g for use in the DSA.
bits is the length of the prime to be generated; the DSS allows a maximum of 1024 bits.
If seed is NULL or seed_len < 20, the primes will be generated at random. Otherwise, the seed is used
to generate them. If the given seed does not yield a prime q, a new random seed is chosen and placed at
seed.
DSA_generate_parameters() places the iteration count in *counter_ret and a counter used for finding a
generator in *h_ret, unless these are NULL.
A callback function may be used to provide feedback about the progress of the key generation. If
callback is not NULL, it will be called as follows:

When a candidate for q is generated, callback(0, m++, cb_arg) is called (m is 0 for the first
candidate).
When a candidate for q has passed a test by trial division, callback(1, -1, cb_arg) is called. While
a candidate for q is tested by Miller-Rabin primality tests, callback(1, i, cb_arg) is called in the
outer loop (once for each witness that confirms that the candidate may be prime); i is the loop
counter (starting at 0).
When a prime q has been found, callback(2, 0, cb_arg) and callback(3, 0, cb_arg) are called.
Before a candidate for p (other than the first) is generated and tested, callback(0, counter,
cb_arg) is called.
When a candidate for p has passed the test by trial division, callback(1, -1, cb_arg) is called.
While it is tested by the Miller-Rabin primality test, callback(1, i, cb_arg) is called in the outer
loop (once for each witness that confirms that the candidate may be prime). i is the loop counter
(starting at 0).
When p has been found, callback(2, 1, cb_arg) is called.
When the generator has been found, callback(3, 1, cb_arg) is called.

RETURN VALUE
DSA_generate_parameters() returns a pointer to the DSA structure, or NULL if the parameter
generation fails. The error codes can be obtained by ERR_get_error(3)|ERR_get_error(3).
BUGS
Seed lengths 20 are not supported.
SEE ALSO
dsa(3)|dsa(3), ERR_get_error(3)|ERR_get_error(3), rand(3)|rand(3), DSA_free(3)|DSA_free(3)
HISTORY
DSA_generate_parameters() appeared in SSLeay 0.8. The cb_arg argument was added in SSLeay 0.9.0.
In versions up to OpenSSL 0.9.4, callback(1, ...) was called in the inner loop of the Miller-Rabin test
whenever it reached the squaring step (the parameters to callback did not reveal how many witnesses
had been tested); since OpenSSL 0.9.5, callback(1, ...) is called as in BN_is_prime(3), i.e. once for each
witness.

112 05 July 2003

Crypto Library DSA add application data

DSA add application data

DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application specific data to DSA
structures
SYNOPSIS
#include <openssl/DSA.h>

int DSA_get_ex_new_index(long argl, void *argp,

CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);

int DSA_set_ex_data(DSA *d, int idx, void *arg);

char *DSA_get_ex_data(DSA *d, int idx);

DESCRIPTION
These functions handle application specific data in DSA structures. Their usage is identical to that of
RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() as described in
RSA_get_ex_new_index(3).
SEE ALSO
RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3), dsa(3)|dsa(3)
HISTORY
DSA_get_ex_new_index(), DSA_set_ex_data() and DSA_get_ex_data() are available since OpenSSL
0.9.5.

05 July 2003 113

DSA allocation Crypto Library

DSA allocation
DSA_new, DSA_free - allocate and free DSA objects
SYNOPSIS
#include <openssl/dsa.h>

DSA* DSA_new(void);

void DSA_free(DSA *dsa);

DESCRIPTION
DSA_new() allocates and initializes a DSA structure. It is equivalent to calling
DSA_new_method(NULL).
DSA_free() frees the DSA structure and its components. The values are erased before the memory is
returned to the system.
RETURN VALUES
If the allocation fails, DSA_new() returns NULL and sets an error code that can be obtained by
ERR_get_error(3)|ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.
DSA_free() returns no value.
SEE ALSO
dsa(3)|dsa(3), ERR_get_error(3)|ERR_get_error(3),
DSA_generate_parameters(3)|DSA_generate_parameters(3),
DSA_generate_key(3)|DSA_generate_key(3)
HISTORY
DSA_new() and DSA_free() are available in all versions of SSLeay and OpenSSL.

114 05 July 2003

Crypto Library DSA select method

DSA select method

DSA_set_default_method, DSA_get_default_method, DSA_set_method, DSA_new_method,
DSA_OpenSSL - select DSA method
SYNOPSIS
#include <openssl/dsa.h>
#include <openssl/engine.h>

void DSA_set_default_method(const DSA_METHOD *meth);

const DSA_METHOD *DSA_get_default_method(void);

int DSA_set_method(DSA *dsa, const DSA_METHOD *meth);

DSA *DSA_new_method(ENGINE *engine);

DSA_METHOD *DSA_OpenSSL(void);
DESCRIPTION
A DSA_METHOD specifies the functions that OpenSSL uses for DSA operations. By modifying the
method, alternative implementations such as hardware accelerators may be used. IMPORTANT: See the
NOTES section for important information about how these DSA API functions are affected by the use of
ENGINE API calls.
Initially, the default DSA_METHOD is the OpenSSL internal implementation, as returned by
DSA_OpenSSL().
DSA_set_default_method() makes meth the default method for all DSA structures created later. NB:
This is true only whilst no ENGINE has been set as a default for DSA, so this function is no longer
recommended.
DSA_get_default_method() returns a pointer to the current default DSA_METHOD. However, the
meaningfulness of this result is dependant on whether the ENGINE API is being used, so this function is
no longer recommended.
DSA_set_method() selects meth to perform all operations using the key rsa. This will replace the
DSA_METHOD used by the DSA key and if the previous method was supplied by an ENGINE, the
handle to that ENGINE will be released during the change. It is possible to have DSA keys that only
work with certain DSA_METHOD implementations (eg. from an ENGINE module that supports
embedded hardware-protected keys), and in such cases attempting to change the DSA_METHOD for the
key can have unexpected results.
DSA_new_method() allocates and initializes a DSA structure so that engine will be used for the DSA
operations. If engine is NULL, the default engine for DSA operations is used, and if no default ENGINE
is set, the DSA_METHOD controlled by DSA_set_default_method() is used.
THE DSA_METHOD STRUCTURE
struct
{
/* name of the implementation */
const char *name;
/* sign */
DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen,
DSA *dsa);

/* pre-compute k^-1 and r */

int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp,
BIGNUM **rp);

/* verify */
int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len,
DSA_SIG *sig, DSA *dsa);

/* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some

05 July 2003 115

DSA select method Crypto Library

implementations) */
int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1,
BIGNUM *a2, BIGNUM *p2, BIGNUM *m,
BN_CTX *ctx, BN_MONT_CTX *in_mont);

/* compute r = a ^ p mod m (May be NULL for some implementations) */

int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a,
const BIGNUM *p, const BIGNUM *m,
BN_CTX *ctx, BN_MONT_CTX *m_ctx);

/* called at DSA_new */
int (*init)(DSA *DSA);

/* called at DSA_free */
int (*finish)(DSA *DSA);

int flags;

char *app_data; /* ?? */

} DSA_METHOD;
RETURN VALUES
DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective DSA_METHODs.
DSA_set_default_method() returns no value.
DSA_set_method() returns non-zero if the provided meth was successfully set as the method for dsa
(including unloading the ENGINE handle if the previous method was supplied by an ENGINE).
DSA_new_method() returns NULL and sets an error code that can be obtained by
ERR_get_error(3)|ERR_get_error(3) if the allocation fails. Otherwise it returns a pointer to the newly
allocated structure.
NOTES
As of version 0.9.7, DSA_METHOD implementations are grouped together with other algorithmic APIs
(eg. RSA_METHOD, EVP_CIPHER, etc) in ENGINE modules. If a default ENGINE is specified for
DSA functionality using an ENGINE API function, that will override any DSA defaults set using the
DSA API (ie. DSA_set_default_method()). For this reason, the ENGINE API is the recommended way
to control default implementations for use in DSA and other cryptographic algorithms.
SEE ALSO
dsa(3)|dsa(3), DSA_new(3)|DSA_new(3)
HISTORY
DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(), DSA_new_method() and
DSA_OpenSSL() were added in OpenSSL 0.9.4.
DSA_set_default_openssl_method() and DSA_get_default_openssl_method() replaced
DSA_set_default_method() and DSA_get_default_method() respectively, and DSA_set_method() and
DSA_new_method() were altered to use ENGINEs rather than DSA_METHODs during development
of the engine version of OpenSSL 0.9.6. For 0.9.7, the handling of defaults in the ENGINE API was
restructured so that this change was reversed, and behaviour of the other functions resembled more
closely the previous behaviour. The behaviour of defaults in the ENGINE API now transparently
overrides the behaviour of defaults in the DSA API without requiring changing these function
prototypes.

116 05 July 2003

Crypto Library DSA signatures

DSA signatures
DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures
SYNOPSIS
#include <openssl/dsa.h>

int DSA_sign(int type, const unsigned char *dgst, int len,

unsigned char *sigret, unsigned int *siglen, DSA *dsa);

int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp,

BIGNUM **rp);

int DSA_verify(int type, const unsigned char *dgst, int len,

unsigned char *sigbuf, int siglen, DSA *dsa);
DESCRIPTION
DSA_sign() computes a digital signature on the len byte message digest dgst using the private key dsa
and places its ASN.1 DER encoding at sigret. The length of the signature is places in *siglen. sigret
must point to DSA_size(dsa) bytes of memory.
DSA_sign_setup() may be used to precompute part of the signing operation in case signature generation
is time-critical. It expects dsa to contain DSA parameters. It places the precomputed values in newly
allocated BIGNUMs at *kinvp and *rp, after freeing the old ones unless *kinvp and *rp are NULL.
These values may be passed to DSA_sign() in dsa-kinv and dsa-r. ctx is a pre-allocated BN_CTX or
NULL.
DSA_verify() verifies that the signature sigbuf of size siglen matches a given message digest dgst of
size len. dsa is the signer‘s public key.
The type parameter is ignored.
The PRNG must be seeded before DSA_sign() (or DSA_sign_setup()) is called.
RETURN VALUES
DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error. DSA_verify() returns 1 for a valid
signature, 0 for an incorrect signature and -1 on error. The error codes can be obtained by
ERR_get_error(3)|ERR_get_error(3).
CONFORMING TO
US Federal Information Processing Standard FIPS 186 (Digital Signature Standard, DSS), ANSI X9.30
SEE ALSO
dsa(3)|dsa(3), ERR_get_error(3)|ERR_get_error(3), rand(3)|rand(3), DSA_do_sign(3)|DSA_do_sign(3)
HISTORY
DSA_sign() and DSA_verify() are available in all versions of SSLeay. DSA_sign_setup() was added in
SSLeay 0.8.

05 July 2003 117

DSA signature allocation Crypto Library

DSA signature allocation

DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects
SYNOPSIS
#include <openssl/dsa.h>

DSA_SIG *DSA_SIG_new(void);

void DSA_SIG_free(DSA_SIG *a);

DESCRIPTION
DSA_SIG_new() allocates and initializes a DSA_SIG structure.
DSA_SIG_free() frees the DSA_SIG structure and its components. The values are erased before the
memory is returned to the system.
RETURN VALUES
If the allocation fails, DSA_SIG_new() returns NULL and sets an error code that can be obtained by
ERR_get_error(3)|ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.
DSA_SIG_free() returns no value.
SEE ALSO
dsa(3)|dsa(3), ERR_get_error(3)|ERR_get_error(3), DSA_do_sign(3)|DSA_do_sign(3)
HISTORY
DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3.

118 05 July 2003

Crypto Library DSA size

DSA size
DSA_size - get DSA signature size
SYNOPSIS
#include <openssl/dsa.h>

int DSA_size(const DSA *dsa);

DESCRIPTION
This function returns the size of an ASN.1 encoded DSA signature in bytes. It can be used to determine
how much memory must be allocated for a DSA signature.
dsa-q must not be NULL.
RETURN VALUE
The size in bytes.
SEE ALSO
dsa(3)|dsa(3), DSA_sign(3)|DSA_sign(3)
HISTORY
DSA_size() is available in all versions of SSLeay and OpenSSL.

05 July 2003 119

ENGINE cryptographic module Crypto Library

ENGINE cryptographic module

engine - ENGINE cryptographic module support
SYNOPSIS
#include <openssl/engine.h>

ENGINE *ENGINE_get_first(void);
ENGINE *ENGINE_get_last(void);
ENGINE *ENGINE_get_next(ENGINE *e);
ENGINE *ENGINE_get_prev(ENGINE *e);

int ENGINE_add(ENGINE *e);

int ENGINE_remove(ENGINE *e);

ENGINE *ENGINE_by_id(const char *id);

int ENGINE_init(ENGINE *e);

int ENGINE_finish(ENGINE *e);

void ENGINE_load_openssl(void);
void ENGINE_load_dynamic(void);
void ENGINE_load_cswift(void);
void ENGINE_load_chil(void);
void ENGINE_load_atalla(void);
void ENGINE_load_nuron(void);
void ENGINE_load_ubsec(void);
void ENGINE_load_aep(void);
void ENGINE_load_sureware(void);
void ENGINE_load_4758cca(void);
void ENGINE_load_openbsd_dev_crypto(void);
void ENGINE_load_builtin_engines(void);

void ENGINE_cleanup(void);

ENGINE *ENGINE_get_default_RSA(void);
ENGINE *ENGINE_get_default_DSA(void);
ENGINE *ENGINE_get_default_DH(void);
ENGINE *ENGINE_get_default_RAND(void);
ENGINE *ENGINE_get_cipher_engine(int nid);
ENGINE *ENGINE_get_digest_engine(int nid);

int ENGINE_set_default_RSA(ENGINE *e);

int ENGINE_set_default_DSA(ENGINE *e);
int ENGINE_set_default_DH(ENGINE *e);
int ENGINE_set_default_RAND(ENGINE *e);
int ENGINE_set_default_ciphers(ENGINE *e);
int ENGINE_set_default_digests(ENGINE *e);
int ENGINE_set_default_string(ENGINE *e, const char *list);

int ENGINE_set_default(ENGINE *e, unsigned int flags);

unsigned int ENGINE_get_table_flags(void);

void ENGINE_set_table_flags(unsigned int flags);

int ENGINE_register_RSA(ENGINE *e);

void ENGINE_unregister_RSA(ENGINE *e);
void ENGINE_register_all_RSA(void);
int ENGINE_register_DSA(ENGINE *e);
void ENGINE_unregister_DSA(ENGINE *e);

120 05 July 2003

Crypto Library ENGINE cryptographic module

void ENGINE_register_all_DSA(void);
int ENGINE_register_DH(ENGINE *e);
void ENGINE_unregister_DH(ENGINE *e);
void ENGINE_register_all_DH(void);
int ENGINE_register_RAND(ENGINE *e);
void ENGINE_unregister_RAND(ENGINE *e);
void ENGINE_register_all_RAND(void);
int ENGINE_register_ciphers(ENGINE *e);
void ENGINE_unregister_ciphers(ENGINE *e);
void ENGINE_register_all_ciphers(void);
int ENGINE_register_digests(ENGINE *e);
void ENGINE_unregister_digests(ENGINE *e);
void ENGINE_register_all_digests(void);
int ENGINE_register_complete(ENGINE *e);
int ENGINE_register_all_complete(void);

int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)());
int ENGINE_cmd_is_executable(ENGINE *e, int cmd);
int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,
long i, void *p, void (*f)(), int cmd_optional);
int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
int cmd_optional);

int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg);

void *ENGINE_get_ex_data(const ENGINE *e, int idx);

int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,

CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);

ENGINE *ENGINE_new(void);
int ENGINE_free(ENGINE *e);

int ENGINE_set_id(ENGINE *e, const char *id);

int ENGINE_set_name(ENGINE *e, const char *name);
int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);
int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);
int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);
int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);
int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f);
int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);
int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);
int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);
int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f);
int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f);
int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);
int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);
int ENGINE_set_flags(ENGINE *e, int flags);
int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);

const char *ENGINE_get_id(const ENGINE *e);

const char *ENGINE_get_name(const ENGINE *e);
const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e);
const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e);
const DH_METHOD *ENGINE_get_DH(const ENGINE *e);
const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e);
ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e);
ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e);
ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e);

05 July 2003 121

ENGINE cryptographic module Crypto Library

ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e);

ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e);
ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e);
ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e);
ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e);
const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid);
const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid);
int ENGINE_get_flags(const ENGINE *e);
const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e);

EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,

UI_METHOD *ui_method, void *callback_data);
EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
UI_METHOD *ui_method, void *callback_data);

void ENGINE_add_conf_module(void);
DESCRIPTION
These functions create, manipulate, and use cryptographic modules in the form of ENGINE objects.
These objects act as containers for implementations of cryptographic algorithms, and support a
reference-counted mechanism to allow them to be dynamically loaded in and out of the running
application.
The cryptographic functionality that can be provided by an ENGINE implementation includes the
following abstractions;
RSA_METHOD - for providing alternative RSA implementations
DSA_METHOD, DH_METHOD, RAND_METHOD - alternative DSA, DH, and RAND
EVP_CIPHER - potentially multiple cipher algorithms (indexed by ’nid’)
EVP_DIGEST - potentially multiple hash algorithms (indexed by ’nid’)
key-loading - loading public and/or private EVP_PKEY keys
Reference counting and handles
Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be treated as handles - ie.
not only as pointers, but also as references to the underlying ENGINE object. Ie. you should obtain a
new reference when making copies of an ENGINE pointer if the copies will be used (and released)
independantly.
ENGINE objects have two levels of reference-counting to match the way in which the objects are used.
At the most basic level, each ENGINE pointer is inherently a structural reference - you need a
structural reference simply to refer to the pointer value at all, as this kind of reference is your guarantee
that the structure can not be deallocated until you release your reference.
However, a structural reference provides no guarantee that the ENGINE has been initiliased to be usable
to perform any of its cryptographic implementations - and indeed it‘s quite possible that most ENGINEs
will not initialised at all on standard setups, as ENGINEs are typically used to support specialised
hardware. To use an ENGINE‘s functionality, you need a functional reference. This kind of reference
can be considered a specialised form of structural reference, because each functional reference implicitly
contains a structural reference as well - however to avoid difficult-to-find programming bugs, it is
recommended to treat the two kinds of reference independantly. If you have a functional reference to an
ENGINE, you have a guarantee that the ENGINE has been initialised ready to perform cryptographic
operations and will not be uninitialised or cleaned up until after you have released your reference.
We will discuss the two kinds of reference separately, including how to tell which one you are dealing
with at any given point in time (after all they are both simply (ENGINE *) pointers, the difference is in
the way they are used).
Structural references
This basic type of reference is typically used for creating new ENGINEs dynamically, iterating across
OpenSSL‘s internal linked-list of loaded ENGINEs, reading information about an ENGINE, etc.
Essentially a structural reference is sufficient if you only need to query or manipulate the data of an
ENGINE implementation rather than use its functionality.
The ENGINE_new() function returns a structural reference to a new (empty) ENGINE object. Other
than that, structural references come from return values to various ENGINE API functions such as;
ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), ENGINE_get_next(),

122 05 July 2003

Crypto Library ENGINE cryptographic module

ENGINE_get_prev(). All structural references should be released by a corresponding to call to the

ENGINE_free() function - the ENGINE object itself will only actually be cleaned up and deallocated
when the last structural reference is released.
It should also be noted that many ENGINE API function calls that accept a structural reference will
internally obtain another reference - typically this happens whenever the supplied ENGINE will be
needed by OpenSSL after the function has returned. Eg. the function to add a new ENGINE to
OpenSSL‘s internal list is ENGINE_add() - if this function returns success, then OpenSSL will have
stored a new structural reference internally so the caller is still responsible for freeing their own
reference with ENGINE_free() when they are finished with it. In a similar way, some functions will
automatically release the structural reference passed to it if part of the function‘s job is to do so. Eg. the
ENGINE_get_next() and ENGINE_get_prev() functions are used for iterating across the internal
ENGINE list - they will return a new structural reference to the next (or previous) ENGINE in the list or
NULL if at the end (or beginning) of the list, but in either case the structural reference passed to the
function is released on behalf of the caller.
To clarify a particular function‘s handling of references, one should always consult that function‘s
documentation "man" page, or failing that the openssl/engine.h header file includes some hints.
Functional references
As mentioned, functional references exist when the cryptographic functionality of an ENGINE is
required to be available. A functional reference can be obtained in one of two ways; from an existing
structural reference to the required ENGINE, or by asking OpenSSL for the default operational ENGINE
for a given cryptographic purpose.
To obtain a functional reference from an existing structural reference, call the ENGINE_init() function.
This returns zero if the ENGINE was not already operational and couldn‘t be successfully initialised (eg.
lack of system drivers, no special hardware attached, etc), otherwise it will return non-zero to indicate
that the ENGINE is now operational and will have allocated a new functional reference to the ENGINE.
In this case, the supplied ENGINE pointer is, from the point of the view of the caller, both a structural
reference and a functional reference - so if the caller intends to use it as a functional reference it should
free the structural reference with ENGINE_free() first. If the caller wishes to use it only as a structural
reference (eg. if the ENGINE_init() call was simply to test if the ENGINE seems available/online), then
it should free the functional reference; all functional references are released by the ENGINE_finish()
function.
The second way to get a functional reference is by asking OpenSSL for a default implementation for a
given task, eg. by ENGINE_get_default_RSA(), ENGINE_get_default_cipher_engine(), etc. These are
discussed in the next section, though they are not usually required by application programmers as they
are used automatically when creating and using the relevant algorithm-specific types in OpenSSL, such
as RSA, DSA, EVP_CIPHER_CTX, etc.
Default implementations
For each supported abstraction, the ENGINE code maintains an internal table of state to control which
implementations are available for a given abstraction and which should be used by default. These
implementations are registered in the tables separated-out by an ‘nid’ index, because abstractions like
EVP_CIPHER and EVP_DIGEST support many distinct algorithms and modes - ENGINEs will support
different numbers and combinations of these. In the case of other abstractions like RSA, DSA, etc, there
is only one "algorithm" so all implementations implicitly register using the same ‘nid’ index. ENGINEs
can be registered into these tables to make themselves available for use automatically by the various
abstractions, eg. RSA. For illustrative purposes, we continue with the RSA example, though all
comments apply similarly to the other abstractions (they each get their own table and linkage to the
corresponding section of openssl code).
When a new RSA key is being created, ie. in RSA_new_method(), a "get_default" call will be made to
the ENGINE subsystem to process the RSA state table and return a functional reference to an initialised
ENGINE whose RSA_METHOD should be used. If no ENGINE should (or can) be used, it will return
NULL and the RSA key will operate with a NULL ENGINE handle by using the conventional RSA
implementation in OpenSSL (and will from then on behave the way it used to before the ENGINE API
existed - for details see RSA_new_method(3)|RSA_new_method(3)).
Each state table has a flag to note whether it has processed this "get_default" query since the table was
last modified, because to process this question it must iterate across all the registered ENGINEs in the
table trying to initialise each of them in turn, in case one of them is operational. If it returns a functional
reference to an ENGINE, it will also cache another reference to speed up processing future queries
(without needing to iterate across the table). Likewise, it will cache a NULL response if no ENGINE
was available so that future queries won‘t repeat the same iteration unless the state table changes. This

05 July 2003 123

ENGINE cryptographic module Crypto Library

behaviour can also be changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using

ENGINE_set_table_flags()), no attempted initialisations will take place, instead the only way for the
state table to return a non-NULL ENGINE to the "get_default" query will be if one is expressly set in the
table. Eg. ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except that it
also sets the state table‘s cached response for the "get_default" query.
In the case of abstractions like EVP_CIPHER, where implementations are indexed by ‘nid‘, these flags
and cached-responses are distinct for each ‘nid’ value.
It is worth illustrating the difference between "registration" of ENGINEs into these per-algorithm state
tables and using the alternative "set_default" functions. The latter handles both "registration" and also
setting the cached "default" ENGINE in each relevant state table - so registered ENGINEs will only have
a chance to be initialised for use as a default if a default ENGINE wasn‘t already set for the same state
table. Eg. if ENGINE X supports cipher nids {A,B} and RSA, ENGINE Y supports ciphers {A} and
DSA, and the following code is executed;
ENGINE_register_complete(X);
ENGINE_set_default(Y, ENGINE_METHOD_ALL);
e1 = ENGINE_get_default_RSA();
e2 = ENGINE_get_cipher_engine(A);
e3 = ENGINE_get_cipher_engine(B);
e4 = ENGINE_get_default_DSA();
e5 = ENGINE_get_cipher_engine(C);

The results would be as follows;

assert(e1 == X);
assert(e2 == Y);
assert(e3 == X);
assert(e4 == Y);
assert(e5 == NULL);
Application requirements
This section will explain the basic things an application programmer should support to make the most
useful elements of the ENGINE functionality available to the user. The first thing to consider is whether
the programmer wishes to make alternative ENGINE modules available to the application and user.
OpenSSL maintains an internal linked list of "visible" ENGINEs from which it has to operate - at
start-up, this list is empty and in fact if an application does not call any ENGINE API calls and it uses
static linking against openssl, then the resulting application binary will not contain any alternative
ENGINE code at all. So the first consideration is whether any/all available ENGINE implementations
should be made visible to OpenSSL - this is controlled by calling the various "load" functions, eg.
/* Make the "dynamic" ENGINE available */
void ENGINE_load_dynamic(void);
/* Make the CryptoSwift hardware acceleration support available */
void ENGINE_load_cswift(void);
/* Make support for nCipher’s "CHIL" hardware available */
void ENGINE_load_chil(void);
...
/* Make ALL ENGINE implementations bundled with OpenSSL available */
void ENGINE_load_builtin_engines(void);

Having called any of these functions, ENGINE objects would have been dynamically allocated and
populated with these implementations and linked into OpenSSL‘s internal linked list. At this point it is
important to mention an important API function;
void ENGINE_cleanup(void);

If no ENGINE API functions are called at all in an application, then there are no inherent memory leaks
to worry about from the ENGINE functionality, however if any ENGINEs are "load"ed, even if they are
never registered or used, it is necessary to use the ENGINE_cleanup() function to correspondingly
cleanup before program exit, if the caller wishes to avoid memory leaks. This mechanism uses an
internal callback registration table so that any ENGINE API functionality that knows it requires cleanup
can register its cleanup details to be called during ENGINE_cleanup(). This approach allows
ENGINE_cleanup() to clean up after any ENGINE functionality at all that your program uses, yet
doesn‘t automatically create linker dependencies to all possible ENGINE functionality - only the cleanup

124 05 July 2003

Crypto Library ENGINE cryptographic module

callbacks required by the functionality you do use will be required by the linker.
The fact that ENGINEs are made visible to OpenSSL (and thus are linked into the program and loaded
into memory at run-time) does not mean they are "registered" or called into use by OpenSSL
automatically - that behaviour is something for the application to have control over. Some applications
will want to allow the user to specify exactly which ENGINE they want used if any is to be used at all.
Others may prefer to load all support and have OpenSSL automatically use at run-time any ENGINE
that is able to successfully initialise - ie. to assume that this corresponds to acceleration hardware
attached to the machine or some such thing. There are probably numerous other ways in which
applications may prefer to handle things, so we will simply illustrate the consequences as they apply to a
couple of simple cases and leave developers to consider these and the source code to openssl‘s builtin
utilities as guides.
Using a specific ENGINE implementation
Here we‘ll assume an application has been configured by its user or admin to want to use the "ACME"
ENGINE if it is available in the version of OpenSSL the application was compiled with. If it is available,
it should be used by default for all RSA, DSA, and symmetric cipher operation, otherwise OpenSSL
should use its builtin software as per usual. The following code illustrates how to approach this;
ENGINE *e;
const char *engine_id = "ACME";
ENGINE_load_builtin_engines();
e = ENGINE_by_id(engine_id);
if(!e)
/* the engine isn’t available */
return;
if(!ENGINE_init(e)) {
/* the engine couldn’t initialise, release ’e’ */
ENGINE_free(e);
return;
}
if(!ENGINE_set_default_RSA(e))
/* This should only happen when ’e’ can’t initialise, but the previous
* statement suggests it did. */
abort();
ENGINE_set_default_DSA(e);
ENGINE_set_default_ciphers(e);
/* Release the functional reference from ENGINE_init() */
ENGINE_finish(e);
/* Release the structural reference from ENGINE_by_id() */
ENGINE_free(e);

Automatically using builtin ENGINE implementations

Here we‘ll assume we want to load and register all ENGINE implementations bundled with OpenSSL,
such that for any cryptographic algorithm required by OpenSSL - if there is an ENGINE that implements
it and can be initialise, it should be used. The following code illustrates how this can work;
/* Load all bundled ENGINEs into memory and make them visible */
ENGINE_load_builtin_engines();
/* Register all of them for every algorithm they collectively implement */
ENGINE_register_all_complete();

That‘s all that‘s required. Eg. the next time OpenSSL tries to set up an RSA key, any bundled ENGINEs
that implement RSA_METHOD will be passed to ENGINE_init() and if any of those succeed, that
ENGINE will be set as the default for use with RSA from then on.
Advanced configuration support
There is a mechanism supported by the ENGINE framework that allows each ENGINE implementation
to define an arbitrary set of configuration "commands" and expose them to OpenSSL and any
applications based on OpenSSL. This mechanism is entirely based on the use of name-value pairs and
and assumes ASCII input (no unicode or UTF for now!), so it is ideal if applications want to provide a
transparent way for users to provide arbitrary configuration "directives" directly to such ENGINEs. It is
also possible for the application to dynamically interrogate the loaded ENGINE implementations for the
names, descriptions, and input flags of their available "control commands", providing a more flexible

05 July 2003 125

ENGINE cryptographic module Crypto Library

configuration scheme. However, if the user is expected to know which ENGINE device he/she is using
(in the case of specialised hardware, this goes without saying) then applications may not need to concern
themselves with discovering the supported control commands and simply prefer to allow settings to
passed into ENGINEs exactly as they are provided by the user.
Before illustrating how control commands work, it is worth mentioning what they are typically used for.
Broadly speaking there are two uses for control commands; the first is to provide the necessary details to
the implementation (which may know nothing at all specific to the host system) so that it can be
initialised for use. This could include the path to any driver or config files it needs to load, required
network addresses, smart-card identifiers, passwords to initialise password-protected devices, logging
information, etc etc. This class of commands typically needs to be passed to an ENGINE before
attempting to initialise it, ie. before calling ENGINE_init(). The other class of commands consist of
settings or operations that tweak certain behaviour or cause certain operations to take place, and these
commands may work either before or after ENGINE_init(), or in same cases both. ENGINE
implementations should provide indications of this in the descriptions attached to builtin control
commands and/or in external product documentation.
Issuing control commands to an ENGINE
Let‘s illustrate by example; a function for which the caller supplies the name of the ENGINE it wishes to
use, a table of string-pairs for use before initialisation, and another table for use after initialisation. Note
that the string-pairs used for control commands consist of a command "name" followed by the command
"parameter" - the parameter could be NULL in some cases but the name can not. This function should
initialise the ENGINE (issuing the "pre" commands beforehand and the "post" commands afterwards)
and set it as the default for everything except RAND and then return a boolean success or failure.
int generic_load_engine_fn(const char *engine_id,
const char **pre_cmds, int pre_num,
const char **post_cmds, int post_num)
{
ENGINE *e = ENGINE_by_id(engine_id);
if(!e) return 0;
while(pre_num--) {
if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) {
fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)");
ENGINE_free(e);
return 0;
}
pre_cmds += 2;
}
if(!ENGINE_init(e)) {
fprintf(stderr, "Failed initialisation\n");
ENGINE_free(e);
return 0;
}
/* ENGINE_init() returned a functional reference, so free the structural
* reference from ENGINE_by_id(). */
ENGINE_free(e);
while(post_num--) {
if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) {
fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)");
ENGINE_finish(e);
return 0;
}
post_cmds += 2;
}
ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND);
/* Success */
return 1;
}

126 05 July 2003

Crypto Library ENGINE cryptographic module

Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can relax the semantics of the
function - if set non-zero it will only return failure if the ENGINE supported the given command name
but failed while executing it, if the ENGINE doesn‘t support the command name it will simply return
success without doing anything. In this case we assume the user is only supplying commands specific to
the given ENGINE so we set this to FALSE.
Discovering supported control commands
It is possible to discover at run-time the names, numerical-ids, descriptions and input parameters of the
control commands supported from a structural reference to any ENGINE. It is first important to note that
some control commands are defined by OpenSSL itself and it will intercept and handle these control
commands on behalf of the ENGINE, ie. the ENGINE‘s ctrl() handler is not used for the control
command. openssl/engine.h defines a symbol, ENGINE_CMD_BASE, that all control commands
implemented by ENGINEs from. Any command value lower than this symbol is considered a "generic"
command is handled directly by the OpenSSL core routines.
It is using these "core" control commands that one can discover the the control commands implemented
by a given ENGINE, specifically the commands;
#define ENGINE_HAS_CTRL_FUNCTION 10
#define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11
#define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12
#define ENGINE_CTRL_GET_CMD_FROM_NAME 13
#define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14
#define ENGINE_CTRL_GET_NAME_FROM_CMD 15
#define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16
#define ENGINE_CTRL_GET_DESC_FROM_CMD 17
#define ENGINE_CTRL_GET_CMD_FLAGS 18

Whilst these commands are automatically processed by the OpenSSL framework code, they use various
properties exposed by each ENGINE by which to process these queries. An ENGINE has 3 properties it
exposes that can affect this behaviour; it can supply a ctrl() handler, it can specify
ENGINE_FLAGS_MANUAL_CMD_CTRL in the ENGINE‘s flags, and it can expose an array of
control command descriptions. If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL
flag, then it will simply pass all these "core" control commands directly to the ENGINE‘s ctrl() handler
(and thus, it must have supplied one), so it is up to the ENGINE to reply to these "discovery" commands
itself. If that flag is not set, then the OpenSSL framework code will work with the following rules;
if no ctrl() handler supplied;
ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero),
all other commands fail.
if a ctrl() handler was supplied but no array of control commands;
ENGINE_HAS_CTRL_FUNCTION returns TRUE,
all other commands fail.
if a ctrl() handler and array of control commands was supplied;
ENGINE_HAS_CTRL_FUNCTION returns TRUE,
all other commands proceed processing ...

If the ENGINE‘s array of control commands is empty then all other commands will fail, otherwise;
ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of the first command supported by
the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the identifier of a command supported by the
ENGINE and returns the next command identifier or fails if there are no more,
ENGINE_CMD_FROM_NAME takes a string name for a command and returns the corresponding
identifier or fails if no such command name exists, and the remaining commands take a command
identifier and return properties of the corresponding commands. All except
ENGINE_CTRL_GET_FLAGS return the string length of a command name or description, or populate
a supplied character buffer with a copy of the command name or description.
ENGINE_CTRL_GET_FLAGS returns a bitwise-OR‘d mask of the following possible values;
#define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001
#define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002
#define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004
#define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008

05 July 2003 127

ENGINE cryptographic module Crypto Library

If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely informational to
the caller - this flag will prevent the command being usable for any higher-level ENGINE functions such
as ENGINE_ctrl_cmd_string(). "INTERNAL" commands are not intended to be exposed to text-based
configuration by applications, administrations, users, etc. These can support arbitrary operations via
ENGINE_ctrl(), including passing to and/or from the control commands data of any arbitrary type.
These commands are supported in the discovery mechanisms simply to allow applications determinie if
an ENGINE supports certain specific commands it might want to use (eg. application "foo" might query
various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - and ENGINE could
therefore decide whether or not to support this "foo"-specific extension).
Future developments
The ENGINE API and internal architecture is currently being reviewed. Slated for possible release in
0.9.8 is support for transparent loading of "dynamic" ENGINEs (built as self-contained shared-libraries).
This would allow ENGINE implementations to be provided independantly of OpenSSL libraries and/or
OpenSSL-based applications, and would also remove any requirement for applications to explicitly use
the "dynamic" ENGINE to bind to shared-library implementations.
SEE ALSO
rsa(3)|rsa(3), dsa(3)|dsa(3), dh(3)|dh(3), rand(3)|rand(3), RSA_new_method(3)|RSA_new_method(3)

128 05 July 2003

Crypto Library ERR - error codes

ERR - error codes

ERR - error codes
SYNOPSIS
#include <openssl/err.h>

unsigned long ERR_get_error(void);

unsigned long ERR_peek_error(void);
unsigned long ERR_get_error_line(const char **file, int *line);
unsigned long ERR_peek_error_line(const char **file, int *line);
unsigned long ERR_get_error_line_data(const char **file, int *line,
const char **data, int *flags);
unsigned long ERR_peek_error_line_data(const char **file, int *line,
const char **data, int *flags);

int ERR_GET_LIB(unsigned long e);

int ERR_GET_FUNC(unsigned long e);
int ERR_GET_REASON(unsigned long e);

void ERR_clear_error(void);

char *ERR_error_string(unsigned long e, char *buf);

const char *ERR_lib_error_string(unsigned long e);
const char *ERR_func_error_string(unsigned long e);
const char *ERR_reason_error_string(unsigned long e);

void ERR_print_errors(BIO *bp);

void ERR_print_errors_fp(FILE *fp);

void ERR_load_crypto_strings(void);
void ERR_free_strings(void);

void ERR_remove_state(unsigned long pid);

void ERR_put_error(int lib, int func, int reason, const char *file,
int line);
void ERR_add_error_data(int num, ...);

void ERR_load_strings(int lib,ERR_STRING_DATA str[]);

unsigned long ERR_PACK(int lib, int func, int reason);
int ERR_get_next_error_library(void);
DESCRIPTION
When a call to the OpenSSL library fails, this is usually signalled by the return value, and an error code
is stored in an error queue associated with the current thread. The err library provides functions to
obtain these error codes and textual error messages.
The ERR_get_error(3)|ERR_get_error(3) manpage describes how to access error codes.
Error codes contain information about where the error occurred, and what went wrong.
ERR_GET_LIB(3)|ERR_GET_LIB(3) describes how to extract this information. A method to obtain
human-readable error messages is described in ERR_error_string(3)|ERR_error_string(3).
ERR_clear_error(3)|ERR_clear_error(3) can be used to clear the error queue.
Note that ERR_remove_state(3)|ERR_remove_state(3) should be used to avoid memory leaks when
threads are terminated.
ADDING NEW ERROR CODES TO OPENSSL
See ERR_put_error(3) if you want to record error codes in the OpenSSL error system from within your
application.
The remainder of this section is of interest only if you want to add new error codes to OpenSSL or add
error codes from external libraries.

05 July 2003 129

ERR - error codes Crypto Library

Reporting errors
Each sub-library has a specific macro XXXerr() that is used to report errors. Its first argument is a
function code XXX_F_..., the second argument is a reason code XXX_R_.... Function codes are derived
from the function names; reason codes consist of textual error descriptions. For example, the function
ssl23_read() reports a "handshake failure" as follows:
SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE);

Function and reason codes should consist of upper case characters, numbers and underscores only. The
error file generation script translates function codes into function names by looking in the header files
for an appropriate function name, if none is found it just uses the capitalized form such as
"SSL23_READ" in the above example.
The trailing section of a reason code (after the "_R_") is translated into lower case and underscores
changed to spaces.
When you are using new function or reason codes, run make errors. The necessary #defines will then
automatically be added to the sub-library‘s header file.
Although a library will normally report errors using its own specific XXXerr macro, another library‘s
macro can be used. This is normally only done when a library wants to include ASN1 code which must
use the ASN1err() macro.
Adding new libraries
When adding a new sub-library to OpenSSL, assign it a library number ERR_LIB_XXX, define a
macro XXXerr() (both in err.h), add its name to ERR_str_libraries[] (in crypto/err/err.c), and add
ERR_load_XXX_strings() to the ERR_load_crypto_strings() function (in crypto/err/err_all.c).
Finally, add an entry
L XXX xxx.h xxx_err.c

to crypto/err/openssl.ec, and add xxx_err.c to the Makefile. Running make errors will then generate a
file xxx_err.c, and add all error codes used in the library to xxx.h.
Additionally the library include file must have a certain form. Typically it will initially look like this:
#ifndef HEADER_XXX_H
#define HEADER_XXX_H

#ifdef __cplusplus
extern "C" {
#endif

/* Include files */

#include <openssl/bio.h>
#include <openssl/x509.h>

/* Macros, structures and function prototypes */

/* BEGIN ERROR CODES */

The BEGIN ERROR CODES sequence is used by the error code generation script as the point to place
new error codes, any text after this point will be overwritten when make errors is run. The closing
#endif etc will be automatically added by the script.
The generated C error code file xxx_err.c will load the header files stdio.h, openssl/err.h and
openssl/xxx.h so the header file must load any additional header files containing any definitions it uses.
USING ERROR CODES IN EXTERNAL LIBRARIES
It is also possible to use OpenSSL‘s error code scheme in external libraries. The library needs to load its
own codes and call the OpenSSL error code insertion script mkerr.pl explicitly to add codes to the
header file and generate the C error code file. This will normally be done if the external library needs to
generate new ASN1 structures but it can also be used to add more general purpose error code handling.
TBA more details
INTERNALS

130 05 July 2003

Crypto Library ERR - error codes

The error queues are stored in a hash table with one ERR_STATE entry for each pid. ERR_get_state()
returns the current thread‘s ERR_STATE. An ERR_STATE can hold up to ERR_NUM_ERRORS
error codes. When more error codes are added, the old ones are overwritten, on the assumption that the
most recent errors are most important.
Error strings are also stored in hash table. The hash tables can be obtained by calling
ERR_get_err_state_table(void) and ERR_get_string_table(void) respectively.
SEE ALSO
CRYPTO_set_id_callback(3)|CRYPTO_set_id_callback(3),
CRYPTO_set_locking_callback(3)|CRYPTO_set_locking_callback(3),
ERR_get_error(3)|ERR_get_error(3), ERR_GET_LIB(3)|ERR_GET_LIB(3),
ERR_clear_error(3)|ERR_clear_error(3), ERR_error_string(3)|ERR_error_string(3),
ERR_print_errors(3)|ERR_print_errors(3), ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3),
ERR_remove_state(3)|ERR_remove_state(3), ERR_put_error(3)|ERR_put_error(3),
ERR_load_strings(3)|ERR_load_strings(3), SSL_get_error(3)|SSL_get_error(3)

05 July 2003 131

ERR clear error queue Crypto Library

ERR clear error queue

ERR_clear_error - clear the error queue
SYNOPSIS
#include <openssl/err.h>

void ERR_clear_error(void);
DESCRIPTION
ERR_clear_error() empties the current thread‘s error queue.
RETURN VALUES
ERR_clear_error() has no return value.
SEE ALSO
err(3)|err(3), ERR_get_error(3)|ERR_get_error(3)
HISTORY
ERR_clear_error() is available in all versions of SSLeay and OpenSSL.

132 05 July 2003

Crypto Library ERR human-readable messages

ERR human-readable messages

ERR_error_string, ERR_error_string_n, ERR_lib_error_string, ERR_func_error_string,
ERR_reason_error_string - obtain human-readable error message
SYNOPSIS
#include <openssl/err.h>

char *ERR_error_string(unsigned long e, char *buf);

char *ERR_error_string_n(unsigned long e, char *buf, size_t len);

const char *ERR_lib_error_string(unsigned long e);

const char *ERR_func_error_string(unsigned long e);
const char *ERR_reason_error_string(unsigned long e);
DESCRIPTION
ERR_error_string() generates a human-readable string representing the error code e, and places it at buf.
buf must be at least 120 bytes long. If buf is NULL, the error string is placed in a static buffer.
ERR_error_string_n() is a variant of ERR_error_string() that writes at most len characters (including the
terminating 0) and truncates the string if necessary. For ERR_error_string_n(), buf may not be NULL.
The string will have the following format:
error:[error code]:[library name]:[function name]:[reason string]

error code is an 8 digit hexadecimal number, library name, function name and reason string are ASCII
text.
ERR_lib_error_string(), ERR_func_error_string() and ERR_reason_error_string() return the library
name, function name and reason string respectively.
The OpenSSL error strings should be loaded by calling
ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3) or, for SSL applications,
SSL_load_error_strings(3)|SSL_load_error_strings(3) first. If there is no text string registered for the
given error code, the error string will contain the numeric code.
ERR_print_errors(3)|ERR_print_errors(3) can be used to print all error codes currently in the queue.
RETURN VALUES
ERR_error_string() returns a pointer to a static buffer containing the string if buf == NULL, buf
otherwise.
ERR_lib_error_string(), ERR_func_error_string() and ERR_reason_error_string() return the strings, and
NULL if none is registered for the error code.
SEE ALSO
err(3)|err(3), ERR_get_error(3)|ERR_get_error(3),
ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3),
SSL_load_error_strings(3)|SSL_load_error_strings(3) ERR_print_errors(3)|ERR_print_errors(3)
HISTORY
ERR_error_string() is available in all versions of SSLeay and OpenSSL. ERR_error_string_n() was
added in OpenSSL 0.9.6.

05 July 2003 133

ERR error codes and data Crypto Library

ERR error codes and data

ERR_get_error, ERR_peek_error, ERR_peek_last_error, ERR_get_error_line, ERR_peek_error_line,
ERR_peek_last_error_line, ERR_get_error_line_data, ERR_peek_error_line_data,
ERR_peek_last_error_line_data - obtain error code and data
SYNOPSIS
#include <openssl/err.h>

unsigned long ERR_get_error(void);

unsigned long ERR_peek_error(void);
unsigned long ERR_peek_last_error(void);

unsigned long ERR_get_error_line(const char **file, int *line);

unsigned long ERR_peek_error_line(const char **file, int *line);
unsigned long ERR_peek_last_error_line(const char **file, int *line);

unsigned long ERR_get_error_line_data(const char **file, int *line,

const char **data, int *flags);
unsigned long ERR_peek_error_line_data(const char **file, int *line,
const char **data, int *flags);
unsigned long ERR_peek_last_error_line_data(const char **file, int *line,
const char **data, int *flags);
DESCRIPTION
ERR_get_error() returns the earliest error code from the thread‘s error queue and removes the entry. This
function can be called repeatedly until there are no more error codes to return.
ERR_peek_error() returns the earliest error code from the thread‘s error queue without modifying it.
ERR_peek_last_error() returns the latest error code from the thread‘s error queue without modifying it.
See ERR_GET_LIB(3)|ERR_GET_LIB(3) for obtaining information about location and reason of the
error, and ERR_error_string(3)|ERR_error_string(3) for human-readable error messages.
ERR_get_error_line(), ERR_peek_error_line() and ERR_peek_last_error_line() are the same as the
above, but they additionally store the file name and line number where the error occurred in *file and
*line, unless these are NULL.
ERR_get_error_line_data(), ERR_peek_error_line_data() and ERR_get_last_error_line_data() store
additional data and flags associated with the error code in *data and *flags, unless these are NULL.
*data contains a string if *flags&ERR_TXT_STRING. If it has been allocated by
OPENSSL_malloc(), *flags&ERR_TXT_MALLOCED is true.
RETURN VALUES
The error code, or 0 if there is no error in the queue.
SEE ALSO
err(3)|err(3), ERR_error_string(3)|ERR_error_string(3), ERR_GET_LIB(3)|ERR_GET_LIB(3)
HISTORY
ERR_get_error(), ERR_peek_error(), ERR_get_error_line() and ERR_peek_error_line() are available in
all versions of SSLeay and OpenSSL. ERR_get_error_line_data() and ERR_peek_error_line_data() were
added in SSLeay 0.9.0. ERR_peek_last_error(), ERR_peek_last_error_line() and
ERR_peek_last_error_line_data() were added in OpenSSL 0.9.7.

134 05 July 2003

Crypto Library ERR get library, function, reason code

ERR get library, function, reason code

ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and reason code
SYNOPSIS
#include <openssl/err.h>

int ERR_GET_LIB(unsigned long e);

int ERR_GET_FUNC(unsigned long e);

int ERR_GET_REASON(unsigned long e);

DESCRIPTION
The error code returned by ERR_get_error() consists of a library number, function code and reason code.
ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() can be used to extract these.
The library number and function code describe where the error occurred, the reason code is the
information about what went wrong.
Each sub-library of OpenSSL has a unique library number; function and reason codes are unique within
each sub-library. Note that different libraries may use the same value to signal different functions and
reasons.
ERR_R_... reason codes such as ERR_R_MALLOC_FAILURE are globally unique. However, when
checking for sub-library specific reason codes, be sure to also compare the library number.
ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are macros.
RETURN VALUES
The library number, function code and reason code respectively.
SEE ALSO
err(3)|err(3), ERR_get_error(3)|ERR_get_error(3)
HISTORY
ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in all versions of
SSLeay and OpenSSL.

05 July 2003 135

ERR string allocation Crypto Library

ERR string allocation

ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings - load and free error strings
SYNOPSIS
#include <openssl/err.h>

void ERR_load_crypto_strings(void);
void ERR_free_strings(void);

#include <openssl/ssl.h>

void SSL_load_error_strings(void);
DESCRIPTION
ERR_load_crypto_strings() registers the error strings for all libcrypto functions.
SSL_load_error_strings() does the same, but also registers the libssl error strings.
One of these functions should be called before generating textual error messages. However, this is not
required when memory usage is an issue.
ERR_free_strings() frees all previously loaded error strings.
RETURN VALUES
ERR_load_crypto_strings(), SSL_load_error_strings() and ERR_free_strings() return no values.
SEE ALSO
err(3)|err(3), ERR_error_string(3)|ERR_error_string(3)
HISTORY
ERR_load_error_strings(), SSL_load_error_strings() and ERR_free_strings() are available in all
versions of SSLeay and OpenSSL.

136 05 July 2003

Crypto Library ERR arbitrary error strings

ERR arbitrary error strings

ERR_load_strings, ERR_PACK, ERR_get_next_error_library - load arbitrary error strings
SYNOPSIS
#include <openssl/err.h>

void ERR_load_strings(int lib, ERR_STRING_DATA str[]);

int ERR_get_next_error_library(void);

unsigned long ERR_PACK(int lib, int func, int reason);

DESCRIPTION
ERR_load_strings() registers error strings for library number lib.
str is an array of error string data:
typedef struct ERR_string_data_st
{
unsigned long error;
char *string;
} ERR_STRING_DATA;

The error code is generated from the library number and a function and reason code: error =
ERR_PACK(lib, func, reason). ERR_PACK() is a macro.
The last entry in the array is {0,0}.
ERR_get_next_error_library() can be used to assign library numbers to user libraries at runtime.
RETURN VALUE
ERR_load_strings() returns no value. ERR_PACK() return the error code. ERR_get_next_error_library()
returns a new library number.
SEE ALSO
err(3)|err(3), ERR_load_strings(3)|ERR_load_strings(3)
HISTORY
ERR_load_error_strings() and ERR_PACK() are available in all versions of SSLeay and OpenSSL.
ERR_get_next_error_library() was added in SSLeay 0.9.0.

05 July 2003 137

ERR print errors Crypto Library

ERR print errors

ERR_print_errors, ERR_print_errors_fp - print error messages
SYNOPSIS
#include <openssl/err.h>

void ERR_print_errors(BIO *bp);

void ERR_print_errors_fp(FILE *fp);
DESCRIPTION
ERR_print_errors() is a convenience function that prints the error strings for all errors that OpenSSL has
recorded to bp, thus emptying the error queue.
ERR_print_errors_fp() is the same, except that the output goes to a FILE.

The error strings will have the following format:

[pid]:error:[error code]:[library name]:[function name]:
[reason string]:[file name]:[line]:[optional text message]

error code is an 8 digit hexadecimal number. library name, function name and reason string are ASCII
text, as is optional text message if one was set for the respective error code.
If there is no text string registered for the given error code, the error string will contain the numeric code.

RETURN VALUES
ERR_print_errors() and ERR_print_errors_fp() return no values.
SEE ALSO
err(3)|err(3), ERR_error_string(3)|ERR_error_string(3), ERR_get_error(3)|ERR_get_error(3),
ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3),
SSL_load_error_strings(3)|SSL_load_error_strings(3)
HISTORY
ERR_print_errors() and ERR_print_errors_fp() are available in all versions of SSLeay and OpenSSL.

138 05 July 2003

Crypto Library ERR recording

ERR recording
ERR_put_error, ERR_add_error_data - record an error
SYNOPSIS
#include <openssl/err.h>

void ERR_put_error(int lib, int func, int reason, const char *file,
int line);

void ERR_add_error_data(int num, ...);

DESCRIPTION
ERR_put_error() adds an error code to the thread‘s error queue. It signals that the error of reason code
reason occurred in function func of library lib, in line number line of file. This function is usually called
by a macro.
ERR_add_error_data() associates the concatenation of its num string arguments with the error code
added last.
ERR_load_strings(3)|ERR_load_strings(3) can be used to register error strings so that the application
can a generate human-readable error messages for the error code.
RETURN VALUES
ERR_put_error() and ERR_add_error_data() return no values.
SEE ALSO
err(3)|err(3), ERR_load_strings(3)|ERR_load_strings(3)
HISTORY
ERR_put_error() is available in all versions of SSLeay and OpenSSL. ERR_add_error_data() was added
in SSLeay 0.9.0.

05 July 2003 139

ERR free thread error queue Crypto Library

ERR free thread error queue

ERR_remove_state - free a thread‘s error queue
SYNOPSIS
#include <openssl/err.h>

void ERR_remove_state(unsigned long pid);

DESCRIPTION
ERR_remove_state() frees the error queue associated with thread pid. If pid == 0, the current thread will
have its error queue removed.
Since error queue data structures are allocated automatically for new threads, they must be freed when
threads are terminated in order to avoid memory leaks.
RETURN VALUE
ERR_remove_state() returns no value.
SEE ALSO
err(3)|err(3)
HISTORY
ERR_remove_state() is available in all versions of SSLeay and OpenSSL.

140 05 July 2003

Crypto Library EVP - high-level cryptography

EVP - high-level cryptography

EVP - high-level cryptographic functions
SYNOPSIS
#include <openssl/evp.h>
DESCRIPTION
The EVP library provides a high-level interface to cryptographic functions.
EVP_Seal... and EVP_Open... provide public key encryption and decryption to implement digital
"envelopes".
The EVP_Sign... and EVP_Verify... functions implement digital signatures.
Symmetric encryption is available with the EVP_Encrypt... functions. The EVP_Digest... functions
provide message digests.
Algorithms are loaded with OpenSSL_add_all_algorithms(3).
All the symmetric algorithms (ciphers) and digests can be replaced by ENGINE modules providing
alternative implementations. If ENGINE implementations of ciphers or digests are registered as defaults,
then the various EVP functions will automatically use those implementations automatically in preference
to built in software implementations. For more information, consult the engine(3) man page.
SEE ALSO
EVP_DigestInit(3)|EVP_DigestInit(3), EVP_EncryptInit(3)|EVP_EncryptInit(3),
EVP_OpenInit(3)|EVP_OpenInit(3), EVP_SealInit(3)|EVP_SealInit(3),
EVP_SignInit(3)|EVP_SignInit(3), EVP_VerifyInit(3)|EVP_VerifyInit(3),
OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3), engine(3)|engine(3)

05 July 2003 141

EVP password encryption Crypto Library

EVP password encryption

EVP_BytesToKey - password based encryption routine
SYNOPSIS
#include <openssl/evp.h>

int EVP_BytesToKey(const EVP_CIPHER *type,const EVP_MD *md,

const unsigned char *salt,
const unsigned char *data, int datal, int count,
unsigned char *key,unsigned char *iv);
DESCRIPTION
EVP_BytesToKey() derives a key and IV from various parameters. type is the cipher to derive the key
and IV for. md is the message digest to use. The salt paramter is used as a salt in the derivation: it
should point to an 8 byte buffer or NULL if no salt is used. data is a buffer containing datal bytes which
is used to derive the keying data. count is the iteration count to use. The derived key and IV will be
written to key and iv respectively.
NOTES
A typical application of this function is to derive keying material for an encryption algorithm from a
password in the data parameter.
Increasing the count parameter slows down the algorithm which makes it harder for an attacker to
peform a brute force attack using a large number of candidate passwords.
If the total key and IV length is less than the digest length and MD5 is used then the derivation
algorithm is compatible with PKCS#5 v1.5 otherwise a non standard extension is used to derive the extra
data.
Newer applications should use more standard algorithms such as PKCS#5 v2.0 for key derivation.
KEY DERIVATION ALGORITHM
The key and IV is derived by concatenating D_1, D_2, etc until enough data is available for the key and
IV. D_i is defined as:
D_i = HASH^count(D_(i-1) || data || salt)

where || denotes concatentaion, D_0 is empty, HASH is the digest algorithm in use, HASH^1(data) is
simply HASH(data), HASH^2(data) is HASH(HASH(data)) and so on.
The initial bytes are used for the key and the subsequent bytes for the IV.
RETURN VALUES
EVP_BytesToKey() returns the size of the derived key in bytes.
SEE ALSO
evp(3)|evp(3), rand(3)|rand(3), EVP_EncryptInit(3)|EVP_EncryptInit(3),
HISTORY

142 05 July 2003

Crypto Library EVP digest

EVP digest
EVP_MD_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate,
EVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, EVP_MAX_MD_SIZE,
EVP_MD_CTX_copy_ex EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type,
EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size,
EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, EVP_sha,
EVP_sha1, EVP_dss, EVP_dss1, EVP_mdc2, EVP_ripemd160, EVP_get_digestbyname,
EVP_get_digestbynid, EVP_get_digestbyobj - EVP digest routines
SYNOPSIS
#include <openssl/evp.h>

void EVP_MD_CTX_init(EVP_MD_CTX *ctx);

EVP_MD_CTX *EVP_MD_CTX_create(void);

int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);

int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md,
unsigned int *s);

int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx);

void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx);

int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in);

int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);

int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md,
unsigned int *s);

int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in);

#define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */

#define EVP_MD_type(e) ((e)->type)

#define EVP_MD_pkey_type(e) ((e)->pkey_type)
#define EVP_MD_size(e) ((e)->md_size)
#define EVP_MD_block_size(e) ((e)->block_size)

#define EVP_MD_CTX_md(e) (e)->digest)

#define EVP_MD_CTX_size(e) EVP_MD_size((e)->digest)
#define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest)
#define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest)

const EVP_MD *EVP_md_null(void);

const EVP_MD *EVP_md2(void);
const EVP_MD *EVP_md5(void);
const EVP_MD *EVP_sha(void);
const EVP_MD *EVP_sha1(void);
const EVP_MD *EVP_dss(void);
const EVP_MD *EVP_dss1(void);
const EVP_MD *EVP_mdc2(void);
const EVP_MD *EVP_ripemd160(void);

const EVP_MD *EVP_get_digestbyname(const char *name);

#define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a))
#define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a))

05 July 2003 143

EVP digest Crypto Library

DESCRIPTION
The EVP digest routines are a high level interface to message digests.
EVP_MD_CTX_init() initializes digest contet ctx.
EVP_MD_CTX_create() allocates, initializes and returns a digest contet.
EVP_DigestInit_ex() sets up digest context ctx to use a digest type from ENGINE impl. ctx must be
initialized before calling this function. type will typically be supplied by a functionsuch as EVP_sha1().
If impl is NULL then the default implementation of digest type is used.
EVP_DigestUpdate() hashes cnt bytes of data at d into the digest context ctx. This function can be
called several times on the same ctx to hash additional data.
EVP_DigestFinal_ex() retrieves the digest value from ctx and places it in md. If the s parameter is not
NULL then the number of bytes of data written (i.e. the length of the digest) will be written to the
integer at s, at most EVP_MAX_MD_SIZE bytes will be written. After calling EVP_DigestFinal_ex()
no additional calls to EVP_DigestUpdate() can be made, but EVP_DigestInit_ex() can be called to
initialize a new digest operation.
EVP_MD_CTX_cleanup() cleans up digest context ctx, it should be called after a digest context is no
longer needed.
EVP_MD_CTX_destroy() cleans up digest context ctx and frees up the space allocated to it, it should be
called only on a context created using EVP_MD_CTX_create().
EVP_MD_CTX_copy_ex() can be used to copy the message digest state from in to out. This is useful if
large amounts of data are to be hashed which only differ in the last few bytes. out must be initialized
before calling this function.
EVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except the passed context ctx does
not have to be initialized, and it always uses the default digest implementation.
EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest contet ctx is automatically
cleaned up.
EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination out does not
have to be initialized.
EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest when passed an
EVP_MD or an EVP_MD_CTX structure, i.e. the size of the hash.
EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the message digest
when passed an EVP_MD or an EVP_MD_CTX structure.
EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER representing
the given message digest when passed an EVP_MD structure. For example
EVP_MD_type(EVP_sha1()) returns NID_sha1. This function is normally used when setting ASN1
OIDs.
EVP_MD_CTX_md() returns the EVP_MD structure corresponding to the passed EVP_MD_CTX.
EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated with this digest.
For example EVP_sha1() is associated with RSA so this will return NID_sha1WithRSAEncryption.
This "link" between digests and signature algorithms may not be retained in future versions of OpenSSL.

EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_mdc2() and EVP_ripemd160() return

EVP_MD structures for the MD2, MD5, SHA, SHA1, MDC2 and RIPEMD160 digest algorithms
respectively. The associated signature algorithm is RSA in each case.
EVP_dss() and EVP_dss1() return EVP_MD structures for SHA and SHA1 digest algorithms but using
DSS (DSA) for the signature algorithm.
EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it returns is of zero length.
EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() return an EVP_MD
structure when passed a digest name, a digest NID or an ASN1_OBJECT structure respectively. The
digest table must be initialized using, for example, OpenSSL_add_all_digests() for these functions to
work.
RETURN VALUES
EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for success and 0 for
failure.
EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure.
EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the corresponding
OBJECT IDENTIFIER or NID_undef if none exists.
EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size(e), EVP_MD_size(),
EVP_MD_CTX_block_size() and EVP_MD_block_size() return the digest or block size in bytes.

144 05 July 2003

Crypto Library EVP digest

EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), EVP_dss1(),

EVP_mdc2() and EVP_ripemd160() return pointers to the corresponding EVP_MD structures.
EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() return either an
EVP_MD structure or NULL if an error occurs.
NOTES
The EVP interface to message digests should almost always be used in preference to the low level
interfaces. This is because the code then becomes transparent to the digest used and much more flexible.
SHA1 is the digest of choice for new applications. The other digest algorithms are still in common use.
For most applications the impl parameter to EVP_DigestInit_ex() will be set to NULL to use the default
digest implementation.
The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are obsolete but are
retained to maintain compatibility with existing code. New applications should use
EVP_DigestInit_ex(), EVP_DigestFinal_ex() and EVP_MD_CTX_copy_ex() because they can
efficiently reuse a digest context instead of initializing and cleaning it up on each call and allow non
default implementations of digests to be specified.
In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use memory leaks will occur.
EXAMPLE
This example digests the data "Test Message\n" and "Hello World\n", using the digest name passed on
the command line.
#include <stdio.h>
#include <openssl/evp.h>

main(int argc, char *argv[])

{
EVP_MD_CTX mdctx;
const EVP_MD *md;
char mess1[] = "Test Message\n";
char mess2[] = "Hello World\n";
unsigned char md_value[EVP_MAX_MD_SIZE];
int md_len, i;

OpenSSL_add_all_digests();

if(!argv[1]) {
printf("Usage: mdtest digestname\n");
exit(1);
}

md = EVP_get_digestbyname(argv[1]);

if(!md) {
printf("Unknown message digest %s\n", argv[1]);
exit(1);
}

EVP_MD_CTX_init(&mdctx);
EVP_DigestInit_ex(&mdctx, md, NULL);
EVP_DigestUpdate(&mdctx, mess1, strlen(mess1));
EVP_DigestUpdate(&mdctx, mess2, strlen(mess2));
EVP_DigestFinal_ex(&mdctx, md_value, &md_len);
EVP_MD_CTX_cleanup(&mdctx);

printf("Digest is: ");

for(i = 0; i < md_len; i++) printf("%02x", md_value[i]);
printf("\n");
}

05 July 2003 145

EVP digest Crypto Library

BUGS
The link between digests and signing algorithms results in a situation where EVP_sha1() must be used
with RSA and EVP_dss1() must be used with DSS even though they are identical digests.
SEE ALSO
evp(3)|evp(3), hmac(3)|hmac(3), md2(3)|md2(3), md5(3)|md5(3), mdc2(3)|mdc2(3),
ripemd(3)|ripemd(3), sha(3)|sha(3), dgst(1)|dgst(1)
HISTORY
EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are available in all versions of SSLeay
and OpenSSL.
EVP_MD_CTX_init(), EVP_MD_CTX_create(), EVP_MD_CTX_copy_ex(),
EVP_MD_CTX_cleanup(), EVP_MD_CTX_destroy(), EVP_DigestInit_ex() and EVP_DigestFinal_ex()
were added in OpenSSL 0.9.7.
EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), EVP_dss1(),
EVP_mdc2() and EVP_ripemd160() were changed to return truely const EVP_MD * in OpenSSL 0.9.7.

146 05 July 2003

Crypto Library EVP cipher

EVP cipher
EVP_CIPHER_CTX_init, EVP_EncryptInit_ex, EVP_EncryptUpdate, EVP_EncryptFinal_ex,
EVP_DecryptInit_ex, EVP_DecryptUpdate, EVP_DecryptFinal_ex, EVP_CipherInit_ex,
EVP_CipherUpdate, EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length,
EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_cleanup, EVP_EncryptInit, EVP_EncryptFinal,
EVP_DecryptInit, EVP_DecryptFinal, EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname,
EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid, EVP_CIPHER_block_size,
EVP_CIPHER_key_length, EVP_CIPHER_iv_length, EVP_CIPHER_flags, EVP_CIPHER_mode,
EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, EVP_CIPHER_CTX_nid,
EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, EVP_CIPHER_CTX_iv_length,
EVP_CIPHER_CTX_get_app_data, EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type,
EVP_CIPHER_CTX_flags, EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1,
EVP_CIPHER_asn1_to_param, EVP_CIPHER_CTX_set_padding - EVP cipher routines
SYNOPSIS
#include <openssl/evp.h>

int EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a);

int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,

ENGINE *impl, unsigned char *key, unsigned char *iv);
int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, unsigned char *in, int inl);
int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl);

int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,

ENGINE *impl, unsigned char *key, unsigned char *iv);
int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, unsigned char *in, int inl);
int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
int *outl);

int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,

ENGINE *impl, unsigned char *key, unsigned char *iv, int enc);
int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, unsigned char *in, int inl);
int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
int *outl);

int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,

unsigned char *key, unsigned char *iv);
int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl);

int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,

unsigned char *key, unsigned char *iv);
int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
int *outl);

int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,

unsigned char *key, unsigned char *iv, int enc);
int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
int *outl);

int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);

int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a);

05 July 2003 147

EVP cipher Crypto Library

const EVP_CIPHER *EVP_get_cipherbyname(const char *name);

#define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a))
#define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a))

#define EVP_CIPHER_nid(e) ((e)->nid)

#define EVP_CIPHER_block_size(e) ((e)->block_size)
#define EVP_CIPHER_key_length(e) ((e)->key_len)
#define EVP_CIPHER_iv_length(e) ((e)->iv_len)
#define EVP_CIPHER_flags(e) ((e)->flags)
#define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE)
int EVP_CIPHER_type(const EVP_CIPHER *ctx);

#define EVP_CIPHER_CTX_cipher(e) ((e)->cipher)

#define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid)
#define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size)
#define EVP_CIPHER_CTX_key_length(e) ((e)->key_len)
#define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len)
#define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data)
#define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d))
#define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c))
#define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags)
#define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE)

int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);

int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
DESCRIPTION
The EVP cipher routines are a high level interface to certain symmetric ciphers.
EVP_CIPHER_CTX_init() initializes cipher contex ctx.
EVP_EncryptInit_ex() sets up cipher context ctx for encryption with cipher type from ENGINE impl.
ctx must be initialized before calling this function. type is normally supplied by a function such as
EVP_des_cbc(). If impl is NULL then the default implementation is used. key is the symmetric key to
use and iv is the IV to use (if necessary), the actual number of bytes used for the key and IV depends on
the cipher. It is possible to set all parameters to NULL except type in an initial call and supply the
remaining parameters in subsequent calls, all of which have type set to NULL. This is done when the
default cipher parameters are not appropriate.
EVP_EncryptUpdate() encrypts inl bytes from the buffer in and writes the encrypted version to out.
This function can be called multiple times to encrypt successive blocks of data. The amount of data
written depends on the block alignment of the encrypted data: as a result the amount of data written may
be anything from zero bytes to (inl + cipher_block_size - 1) so outl should contain sufficient room. The
actual number of bytes written is placed in outl.
If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts the "final" data, that is any data
that remains in a partial block. It uses standard block padding|/NOTES (aka PKCS padding). The
encrypted final data is written to out which should have sufficient space for one cipher block. The
number of bytes written is placed in outl. After this function is called the encryption operation is
finished and no further calls to EVP_EncryptUpdate() should be made.
If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more data and it will return an
error if any data remains in a partial block: that is if the total data length is not a multiple of the block
size.
EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the corresponding
decryption operations. EVP_DecryptFinal() will return an error code if padding is enabled and the final
block is not correctly formatted. The parameters and restrictions are identical to the encryption
operations except that if padding is enabled the decrypted data buffer out passed to
EVP_DecryptUpdate() should have sufficient room for (inl + cipher_block_size) bytes unless the cipher
block size is 1 in which case inl bytes is sufficient.
EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are functions that can be used
for decryption or encryption. The operation performed depends on the value of the enc parameter. It
should be set to 1 for encryption, 0 for decryption and -1 to leave the value unchanged (the actual value
of ‘enc’ being supplied in a previous call).

148 05 July 2003

Crypto Library EVP cipher

EVP_CIPHER_CTX_cleanup() clears all information from a cipher context and free up any allocated
memory associate with it. It should be called after all operations using a cipher are complete so sensitive
information does not remain in memory.
EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a similar way to
EVP_EncryptInit_ex(), EVP_DecryptInit_ex and EVP_CipherInit_ex() except the ctx paramter does not
need to be initialized and they always use the default cipher implementation.
EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() behave in a similar way to
EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and EVP_CipherFinal_ex() except ctx is
automatically cleaned up after the call.
EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() return an EVP_CIPHER
structure when passed a cipher name, a NID or an ASN1_OBJECT structure.
EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when passed an
EVP_CIPHER or EVP_CIPHER_CTX structure. The actual NID value is an internal value which
may not have a corresponding OBJECT IDENTIFIER.
EVP_CIPHER_CTX_set_padding() enables or disables padding. By default encryption operations are
padded using standard block padding and the padding is checked and removed when decrypting. If the
pad parameter is zero then no padding is performed, the total amount of data encrypted or decrypted
must then be a multiple of the block size or an error will occur.
EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key length of a cipher
when passed an EVP_CIPHER or EVP_CIPHER_CTX structure. The constant
EVP_MAX_KEY_LENGTH is the maximum key length for all ciphers. Note: although
EVP_CIPHER_key_length() is fixed for a given cipher, the value of EVP_CIPHER_CTX_key_length()
may be different for variable key length ciphers.
EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx. If the cipher is a fixed
length cipher then attempting to set the key length to any value other than the fixed value is an error.
EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV length of a cipher when
passed an EVP_CIPHER or EVP_CIPHER_CTX. It will return zero if the cipher does not use an IV.
The constant EVP_MAX_IV_LENGTH is the maximum IV length for all ciphers.
EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block size of a cipher
when passed an EVP_CIPHER or EVP_CIPHER_CTX structure. The constant
EVP_MAX_IV_LENGTH is also the maximum block length for all ciphers.
EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed cipher or context.
This "type" is the actual NID of the cipher OBJECT IDENTIFIER as such it ignores the cipher
parameters and 40 bit RC2 and 128 bit RC2 have the same NID. If the cipher does not have an object
identifier or does not have ASN1 support this function will return NID_undef.
EVP_CIPHER_CTX_cipher() returns the EVP_CIPHER structure when passed an
EVP_CIPHER_CTX structure.
EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode:
EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or
EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then EVP_CIPH_STREAM_CIPHER is
returned.
EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based on the passed cipher.
This will typically include any parameters and an IV. The cipher IV (if any) must be set when this call is
made. This call should be made before the cipher is actually "used" (before any EVP_EncryptUpdate(),
EVP_DecryptUpdate() calls for example). This function may fail if the cipher does not have any ASN1
support.
EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1 AlgorithmIdentifier
"parameter". The precise effect depends on the cipher In the case of RC2, for example, it will set the IV
and effective key length. This function should be called after the base cipher type is set but before the
key is set. For example EVP_CipherInit() will be called with the IV and key set to NULL,
EVP_CIPHER_asn1_to_param() will be called and finally EVP_CipherInit() again with all parameters
except the key set to NULL. It is possible for this function to fail if the cipher does not have any ASN1
support or the parameters cannot be set (for example the RC2 effective key length is not supported.
EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined and set.
Currently only the RC2 effective key length and the number of rounds of RC5 can be set.
RETURN VALUES
EVP_CIPHER_CTX_init, EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
return 1 for success and 0 for failure.

05 July 2003 149

EVP cipher Crypto Library

EVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0 for failure.

EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success.
EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for failure.
EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success.
EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure.
EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() return an
EVP_CIPHER structure or NULL on error.
EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID.
EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block size.
EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key length.
EVP_CIPHER_CTX_set_padding() always returns 1.
EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV length or zero if the
cipher does not use an IV.
EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher‘s OBJECT
IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER.
EVP_CIPHER_CTX_cipher() returns an EVP_CIPHER structure.
EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for success or zero for
failure.
CIPHER LISTING
All algorithms have a fixed key length unless otherwise stated.

EVP_enc_null()
Null cipher: does nothing.
EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void)
DES in CBC, ECB, CFB and OFB modes respectively.
EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), EVP_des_ede_cfb(void)
Two key triple DES in CBC, ECB, CFB and OFB modes respectively.
EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void),
EVP_des_ede3_cfb(void)
Three key triple DES in CBC, ECB, CFB and OFB modes respectively.
EVP_desx_cbc(void)
DESX algorithm in CBC mode.
EVP_rc4(void)
RC4 stream cipher. This is a variable key length cipher with default key length 128 bits.
EVP_rc4_40(void)
RC4 stream cipher with 40 bit key length. This is obsolete and new code should use EVP_rc4()
and the EVP_CIPHER_CTX_set_key_length() function.
EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void),
EVP_idea_cbc(void)
IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void)
RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
length cipher with an additional parameter called "effective key bits" or "effective key length". By
default both are set to 128 bits.
EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void)
RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits.
These are obsolete and new code should use EVP_rc2_cbc(),
EVP_CIPHER_CTX_set_key_length() and EVP_CIPHER_CTX_ctrl() to set the key length and
effective key length.
EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void);
Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable
key length cipher.
EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void)
CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable
key length cipher.
EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void),

150 05 July 2003

Crypto Library EVP cipher

EVP_rc5_32_12_16_ofb(void)
RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
length cipher with an additional "number of rounds" parameter. By default the key length is set to
128 bits and 12 rounds.

NOTES
Where possible the EVP interface to symmetric ciphers should be used in preference to the low level
interfaces. This is because the code then becomes transparent to the cipher used and much more flexible.

PKCS padding works by adding n padding bytes of value n to make the total length of the encrypted
data a multiple of the block size. Padding is always added so if the data is already a multiple of the block
size n will equal the block size. For example if the block size is 8 and 11 bytes are to be encrypted then 5
padding bytes of value 5 will be added.
When decrypting the final block is checked to see if it has the correct form.
Although the decryption operation can produce an error if padding is enabled, it is not a strong test that
the input data or key is correct. A random block has better than 1 in 256 chance of being of the correct
format and problems with the input data earlier on will not produce a final decrypt error.
If padding is disabled then the decryption operation will always succeed if the total amount of data
decrypted is a multiple of the block size.
The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(), EVP_CipherInit() and
EVP_CipherFinal() are obsolete but are retained for compatibility with existing code. New code should
use EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(),
EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an existing context without
allocating and freeing it up on each call.
BUGS
For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is a limitation of the current
RC5 code rather than the EVP interface.
EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with
default key lengths. If custom ciphers exceed these values the results are unpredictable. This is because
it has become standard practice to define a generic key as a fixed unsigned char array containing
EVP_MAX_KEY_LENGTH bytes.
The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested for certain common
S/MIME ciphers (RC2, DES, triple DES) in CBC mode.
EXAMPLES
Get the number of rounds used in RC5:
int nrounds;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds);

Get the RC2 effective key length:

int key_bits;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits);

Set the number of rounds used in RC5:

int nrounds;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL);

Set the effective key length used in RC2:

int key_bits;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL);

Encrypt a string using blowfish:

int do_crypt(char *outfile)
{
unsigned char outbuf[1024];
int outlen, tmplen;
/* Bogus key and IV: we’d normally set these from

05 July 2003 151

EVP cipher Crypto Library

* another source.
*/
unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
unsigned char iv[] = {1,2,3,4,5,6,7,8};
char intext[] = "Some Crypto Text";
EVP_CIPHER_CTX ctx;
FILE *out;
EVP_CIPHER_CTX_init(&ctx);
EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv);

if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext)))

{
/* Error */
return 0;
}
/* Buffer passed to EVP_EncryptFinal() must be after data just
* encrypted to avoid overwriting it.
*/
if(!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen))
{
/* Error */
return 0;
}
outlen += tmplen;
EVP_CIPHER_CTX_cleanup(&ctx);
/* Need binary mode for fopen because encrypted data is
* binary data. Also cannot use strlen() on it because
* it wont be null terminated and may contain embedded
* nulls.
*/
out = fopen(outfile, "wb");
fwrite(outbuf, 1, outlen, out);
fclose(out);
return 1;
}

The ciphertext from the above example can be decrypted using the openssl utility with the command
line:
S<openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F

-iv 0102030405060708 -d> General encryption, decryption function example using FILE I/O
and RC2 with an 80 bit key:
int do_crypt(FILE *in, FILE *out, int do_encrypt)
{
/* Allow enough space in output buffer for additional block */
inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
int inlen, outlen;
/* Bogus key and IV: we’d normally set these from
* another source.
*/
unsigned char key[] = "0123456789";
unsigned char iv[] = "12345678";
/* Don’t set key or IV because we will modify the parameters */
EVP_CIPHER_CTX_init(&ctx);
EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt);
EVP_CIPHER_CTX_set_key_length(&ctx, 10);
/* We finished modifying parameters so now we can set key and IV */
EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);

152 05 July 2003

Crypto Library EVP cipher

for(;;)
{
inlen = fread(inbuf, 1, 1024, in);
if(inlen <= 0) break;
if(!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, inlen))
{
/* Error */
return 0;
}
fwrite(outbuf, 1, outlen, out);
}
if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen))
{
/* Error */
return 0;
}
fwrite(outbuf, 1, outlen, out);

EVP_CIPHER_CTX_cleanup(&ctx);
return 1;
}
SEE ALSO
evp(3)|evp(3)
HISTORY
EVP_CIPHER_CTX_init(), EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(),
EVP_DecryptFinal_ex(), EVP_CipherInit_ex(), EVP_CipherFinal_ex() and
EVP_CIPHER_CTX_set_padding() appeared in OpenSSL 0.9.7.

05 July 2003 153

EVP envelope decryption Crypto Library

EVP envelope decryption

EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption
SYNOPSIS
#include <openssl/evp.h>

int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek,

int ekl,unsigned char *iv,EVP_PKEY *priv);
int EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, unsigned char *in, int inl);
int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl);
DESCRIPTION
The EVP envelope routines are a high level interface to envelope decryption. They decrypt a public key
encrypted symmetric key and then decrypt data using it.
EVP_OpenInit() initializes a cipher context ctx for decryption with cipher type. It decrypts the
encrypted symmetric key of length ekl bytes passed in the ek parameter using the private key priv. The
IV is supplied in the iv parameter.
EVP_OpenUpdate() and EVP_OpenFinal() have exactly the same properties as the
EVP_DecryptUpdate() and EVP_DecryptFinal() routines, as documented on the
EVP_EncryptInit(3)|EVP_EncryptInit(3) manual page.
NOTES
It is possible to call EVP_OpenInit() twice in the same way as EVP_DecryptInit(). The first call should
have priv set to NULL and (after setting any cipher parameters) it should be called again with type set
to NULL.
If the cipher passed in the type parameter is a variable length cipher then the key length will be set to the
value of the recovered key length. If the cipher is a fixed length cipher then the recovered key length
must match the fixed cipher length.
RETURN VALUES
EVP_OpenInit() returns 0 on error or a non zero integer (actually the recovered secret key size) if
successful.
EVP_OpenUpdate() returns 1 for success or 0 for failure.
EVP_OpenFinal() returns 0 if the decrypt failed or 1 for success.
SEE ALSO
evp(3)|evp(3), rand(3)|rand(3), EVP_EncryptInit(3)|EVP_EncryptInit(3),
EVP_SealInit(3)|EVP_SealInit(3)
HISTORY

154 05 July 2003

Crypto Library EVP_PKEY allocation

EVP_PKEY allocation
EVP_PKEY_new, EVP_PKEY_free - private key allocation functions.
SYNOPSIS
#include <openssl/evp.h>

EVP_PKEY *EVP_PKEY_new(void);
void EVP_PKEY_free(EVP_PKEY *key);
DESCRIPTION
The EVP_PKEY_new() function allocates an empty EVP_PKEY structure which is used by OpenSSL
to store private keys.
EVP_PKEY_free() frees up the private key key.
NOTES
The EVP_PKEY structure is used by various OpenSSL functions which require a general private key
without reference to any particular algorithm.
The structure returned by EVP_PKEY_new() is empty. To add a private key to this empty structure the
functions described in EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3) should be used.
RETURN VALUES
EVP_PKEY_new() returns either the newly allocated EVP_PKEY structure of NULL if an error
occurred.
EVP_PKEY_free() does not return a value.
SEE ALSO
EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)
HISTORY
TBA

05 July 2003 155

EVP_PKEY assignment Crypto Library

EVP_PKEY assignment
EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,
EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY,
EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH,
EVP_PKEY_assign_EC_KEY, EVP_PKEY_type - EVP_PKEY assignment functions.
SYNOPSIS
#include <openssl/evp.h>

int EVP_PKEY_set1_RSA(EVP_PKEY *pkey,RSA *key);

int EVP_PKEY_set1_DSA(EVP_PKEY *pkey,DSA *key);
int EVP_PKEY_set1_DH(EVP_PKEY *pkey,DH *key);
int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey,EC_KEY *key);

RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);

DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);
DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);
EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);

int EVP_PKEY_assign_RSA(EVP_PKEY *pkey,RSA *key);

int EVP_PKEY_assign_DSA(EVP_PKEY *pkey,DSA *key);
int EVP_PKEY_assign_DH(EVP_PKEY *pkey,DH *key);
int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey,EC_KEY *key);

int EVP_PKEY_type(int type);

DESCRIPTION
EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
EVP_PKEY_set1_EC_KEY() set the key referenced by pkey to key.
EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
EVP_PKEY_get1_EC_KEY() return the referenced key in pkey or NULL if the key is not of the correct
type.
EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() and
EVP_PKEY_assign_EC_KEY() also set the referenced key to key however these use the supplied key
internally and so key will be freed when the parent pkey is freed.
EVP_PKEY_type() returns the type of key corresponding to the value type. The type of a key can be
obtained with EVP_PKEY_type(pkey-type). The return value will be EVP_PKEY_RSA,
EVP_PKEY_DSA, EVP_PKEY_DH or EVP_PKEY_EC for the corresponding key types or NID_undef
if the key type is unassigned.
NOTES
In accordance with the OpenSSL naming convention the key obtained from or assigned to the pkey
using the 1 functions must be freed as well as pkey.
EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
EVP_PKEY_assign_EC_KEY() are implemented as macros.
RETURN VALUES
EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure.
EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
EVP_PKEY_get1_EC_KEY() return the referenced key or NULL if an error occurred.
EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() and
EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure.
SEE ALSO
EVP_PKEY_new(3)|EVP_PKEY_new(3)
HISTORY
TBA

156 05 July 2003

Crypto Library EVP envelope encryption

EVP envelope encryption

EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption
SYNOPSIS
#include <openssl/evp.h>

int EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek,

int *ekl, unsigned char *iv,EVP_PKEY **pubk, int npubk);
int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, unsigned char *in, int inl);
int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl);
DESCRIPTION
The EVP envelope routines are a high level interface to envelope encryption. They generate a random
key and IV (if required) then "envelope" it by using public key encryption. Data can then be encrypted
using this key.
EVP_SealInit() initializes a cipher context ctx for encryption with cipher type using a random secret key
and IV. type is normally supplied by a function such as EVP_des_cbc(). The secret key is encrypted
using one or more public keys, this allows the same encrypted data to be decrypted using any of the
corresponding private keys. ek is an array of buffers where the public key encrypted secret key will be
written, each buffer must contain enough room for the corresponding encrypted key: that is ek[i] must
have room for EVP_PKEY_size(pubk[i]) bytes. The actual size of each encrypted secret key is written
to the array ekl. pubk is an array of npubk public keys.
The iv parameter is a buffer where the generated IV is written to. It must contain enough room for the
corresponding cipher‘s IV, as determined by (for example) EVP_CIPHER_iv_length(type).
If the cipher does not require an IV then the iv parameter is ignored and can be NULL.
EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties as the EVP_EncryptUpdate()
and EVP_EncryptFinal() routines, as documented on the EVP_EncryptInit(3)|EVP_EncryptInit(3)
manual page.
RETURN VALUES
EVP_SealInit() returns 0 on error or npubk if successful.
EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for failure.
NOTES
Because a random secret key is generated the random number generator must be seeded before calling
EVP_SealInit().
The public key must be RSA because it is the only OpenSSL public key algorithm that supports key
transport.
Envelope encryption is the usual method of using public key encryption on large amounts of data, this is
because public key encryption is slow but symmetric encryption is fast. So symmetric encryption is used
for bulk encryption and the small random symmetric key used is transferred using public key encryption.

It is possible to call EVP_SealInit() twice in the same way as EVP_EncryptInit(). The first call should
have npubk set to 0 and (after setting any cipher parameters) it should be called again with type set to
NULL.
SEE ALSO
evp(3)|evp(3), rand(3)|rand(3), EVP_EncryptInit(3)|EVP_EncryptInit(3),
EVP_OpenInit(3)|EVP_OpenInit(3)
HISTORY
EVP_SealFinal() did not return a value before OpenSSL 0.9.7.

05 July 2003 157

EVP signing Crypto Library

EVP signing
EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions
SYNOPSIS
#include <openssl/evp.h>

int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);

int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s,
EVP_PKEY *pkey);
void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);

int EVP_PKEY_size(EVP_PKEY *pkey);

DESCRIPTION
The EVP signature routines are a high level interface to digital signatures.
EVP_SignInit_ex() sets up signing context ctx to use digest type from ENGINE impl. ctx must be
initialized with EVP_MD_CTX_init() before calling this function.
EVP_SignUpdate() hashes cnt bytes of data at d into the signature context ctx. This function can be
called several times on the same ctx to include additional data.
EVP_SignFinal() signs the data in ctx using the private key pkey and places the signature in sig. If the s
parameter is not NULL then the number of bytes of data written (i.e. the length of the signature) will be
written to the integer at s, at most EVP_PKEY_size(pkey) bytes will be written.
EVP_SignInit() initializes a signing context ctx to use the default implementation of digest type.
EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual signature returned by
EVP_SignFinal() may be smaller.
RETURN VALUES
EVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1 for success and 0 for failure.
EVP_PKEY_size() returns the maximum size of a signature in bytes.
The error codes can be obtained by ERR_get_error(3)|ERR_get_error(3).
NOTES
The EVP interface to digital signatures should almost always be used in preference to the low level
interfaces. This is because the code then becomes transparent to the algorithm used and much more
flexible.
Due to the link between message digests and public key algorithms the correct digest algorithm must be
used with the correct public key type. A list of algorithms and associated public key algorithms appears
in EVP_DigestInit(3)|EVP_DigestInit(3).
When signing with DSA private keys the random number generator must be seeded or the operation will
fail. The random number generator does not need to be seeded for RSA signatures.
The call to EVP_SignFinal() internally finalizes a copy of the digest context. This means that calls to
EVP_SignUpdate() and EVP_SignFinal() can be called later to digest and sign additional data.
Since only a copy of the digest context is ever finalized the context must be cleaned up after use by
calling EVP_MD_CTX_cleanup() or a memory leak will occur.
BUGS
Older versions of this documentation wrongly stated that calls to EVP_SignUpdate() could not be made
after calling EVP_SignFinal().
SEE ALSO
EVP_VerifyInit(3)|EVP_VerifyInit(3), EVP_DigestInit(3)|EVP_DigestInit(3), err(3)|err(3),
evp(3)|evp(3), hmac(3)|hmac(3), md2(3)|md2(3), md5(3)|md5(3), mdc2(3)|mdc2(3),
ripemd(3)|ripemd(3), sha(3)|sha(3), dgst(1)|dgst(1)
HISTORY
EVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are available in all versions of SSLeay and
OpenSSL.
EVP_SignInit_ex() was added in OpenSSL 0.9.7.

158 05 July 2003

Crypto Library EVP signature verification

EVP signature verification

EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification functions
SYNOPSIS
#include <openssl/evp.h>

int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);

int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
int EVP_VerifyFinal(EVP_MD_CTX *ctx,unsigned char *sigbuf,
unsigned int siglen,EVP_PKEY *pkey);
int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type);
DESCRIPTION
The EVP signature verification routines are a high level interface to digital signatures.
EVP_VerifyInit_ex() sets up verification context ctx to use digest type from ENGINE impl. ctx must be
initialized by calling EVP_MD_CTX_init() before calling this function.
EVP_VerifyUpdate() hashes cnt bytes of data at d into the verification context ctx. This function can be
called several times on the same ctx to include additional data.
EVP_VerifyFinal() verifies the data in ctx using the public key pkey and against the siglen bytes at
sigbuf.
EVP_VerifyInit() initializes verification context ctx to use the default implementation of digest type.
RETURN VALUES
EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for failure.
EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if some other error occurred.
The error codes can be obtained by ERR_get_error(3)|ERR_get_error(3).
NOTES
The EVP interface to digital signatures should almost always be used in preference to the low level
interfaces. This is because the code then becomes transparent to the algorithm used and much more
flexible.
Due to the link between message digests and public key algorithms the correct digest algorithm must be
used with the correct public key type. A list of algorithms and associated public key algorithms appears
in EVP_DigestInit(3)|EVP_DigestInit(3).
The call to EVP_VerifyFinal() internally finalizes a copy of the digest context. This means that calls to
EVP_VerifyUpdate() and EVP_VerifyFinal() can be called later to digest and verify additional data.
Since only a copy of the digest context is ever finalized the context must be cleaned up after use by
calling EVP_MD_CTX_cleanup() or a memory leak will occur.
BUGS
Older versions of this documentation wrongly stated that calls to EVP_VerifyUpdate() could not be
made after calling EVP_VerifyFinal().
SEE ALSO
evp(3)|evp(3), EVP_SignInit(3)|EVP_SignInit(3), EVP_DigestInit(3)|EVP_DigestInit(3), err(3)|err(3),
evp(3)|evp(3), hmac(3)|hmac(3), md2(3)|md2(3), md5(3)|md5(3), mdc2(3)|mdc2(3),
ripemd(3)|ripemd(3), sha(3)|sha(3), dgst(1)|dgst(1)
HISTORY
EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are available in all versions of SSLeay
and OpenSSL.
EVP_VerifyInit_ex() was added in OpenSSL 0.9.7

05 July 2003 159

HMAC message authentication code Crypto Library

HMAC message authentication code

HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - HMAC message authentication
code
SYNOPSIS
#include <openssl/hmac.h>

unsigned char *HMAC(const EVP_MD *evp_md, const void *key,

int key_len, const unsigned char *d, int n,
unsigned char *md, unsigned int *md_len);

void HMAC_CTX_init(HMAC_CTX *ctx);

void HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,

const EVP_MD *md);
void HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len,
const EVP_MD *md);
void HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len);
void HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len);

void HMAC_CTX_cleanup(HMAC_CTX *ctx);

void HMAC_cleanup(HMAC_CTX *ctx);
DESCRIPTION
HMAC is a MAC (message authentication code), i.e. a keyed hash function used for message
authentication, which is based on a hash function.
HMAC() computes the message authentication code of the n bytes at d using the hash function evp_md
and the key key which is key_len bytes long.
It places the result in md (which must have space for the output of the hash function, which is no more
than EVP_MAX_MD_SIZE bytes). If md is NULL, the digest is placed in a static array. The size of
the output is placed in md_len, unless it is NULL.
evp_md can be EVP_sha1(), EVP_ripemd160() etc. key and evp_md may be NULL if a key and hash
function have been set in a previous call to HMAC_Init() for that HMAC_CTX.
HMAC_CTX_init() initialises a HMAC_CTX before first use. It must be called.
HMAC_CTX_cleanup() erases the key and other data from the HMAC_CTX and releases any
associated resources. It must be called when an HMAC_CTX is no longer required.
HMAC_cleanup() is an alias for HMAC_CTX_cleanup() included for back compatibility with 0.9.6b, it
is deprecated.
The following functions may be used if the message is not completely stored in memory:
HMAC_Init() initializes a HMAC_CTX structure to use the hash function evp_md and the key key
which is key_len bytes long. It is deprecated and only included for backward compatibility with
OpenSSL 0.9.6b.
HMAC_Init_ex() initializes or reuses a HMAC_CTX structure to use the function evp_md and key
key. Either can be NULL, in which case the existing one will be reused. HMAC_CTX_init() must have
been called before the first use of an HMAC_CTX in this function. N.B. HMAC_Init() had this
undocumented behaviour in previous versions of OpenSSL - failure to switch to HMAC_Init_ex()
in programs that expect it will cause them to stop working.
HMAC_Update() can be called repeatedly with chunks of the message to be authenticated (len bytes at
data).
HMAC_Final() places the message authentication code in md, which must have space for the hash
function output.
RETURN VALUES
HMAC() returns a pointer to the message authentication code.
HMAC_CTX_init(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final() and HMAC_CTX_cleanup()
do not return values.
CONFORMING TO

160 05 July 2003

Crypto Library HMAC message authentication code

RFC 2104
SEE ALSO
sha(3)|sha(3), evp(3)|evp(3)
HISTORY
HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup() are available since
SSLeay 0.9.0.
HMAC_CTX_init(), HMAC_Init_ex() and HMAC_CTX_cleanup() are available since OpenSSL 0.9.7.

05 July 2003 161

LH dynamic hash table Crypto Library

LH dynamic hash table

lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, lh_error - dynamic hash table
SYNOPSIS
#include <openssl/lhash.h>

LHASH *lh_new(LHASH_HASH_FN_TYPE hash, LHASH_COMP_FN_TYPE compare);

void lh_free(LHASH *table);

void *lh_insert(LHASH *table, void *data);

void *lh_delete(LHASH *table, void *data);
void *lh_retrieve(LHASH *table, void *data);

void lh_doall(LHASH *table, LHASH_DOALL_FN_TYPE func);

void lh_doall_arg(LHASH *table, LHASH_DOALL_ARG_FN_TYPE func,
void *arg);

int lh_error(LHASH *table);

typedef int (*LHASH_COMP_FN_TYPE)(const void *, const void *);

typedef unsigned long (*LHASH_HASH_FN_TYPE)(const void *);
typedef void (*LHASH_DOALL_FN_TYPE)(const void *);
typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *);
DESCRIPTION
This library implements dynamic hash tables. The hash table entries can be arbitrary structures. Usually
they consist of key and value fields.
lh_new() creates a new LHASH structure to store arbitrary data entries, and provides the ‘hash’ and
‘compare’ callbacks to be used in organising the table‘s entries. The hash callback takes a pointer to a
table entry as its argument and returns an unsigned long hash value for its key field. The hash value is
normally truncated to a power of 2, so make sure that your hash function returns well mixed low order
bits. The compare callback takes two arguments (pointers to two hash table entries), and returns 0 if
their keys are equal, non-zero otherwise. If your hash table will contain items of some particular type
and the hash and compare callbacks hash/compare these types, then the
DECLARE_LHASH_HASH_FN and IMPLEMENT_LHASH_COMP_FN macros can be used to
create callback wrappers of the prototypes required by lh_new(). These provide per-variable casts
before calling the type-specific callbacks written by the application author. These macros, as well as
those used for the "doall" callbacks, are defined as;
#define DECLARE_LHASH_HASH_FN(f_name,o_type) \
unsigned long f_name##_LHASH_HASH(const void *);
#define IMPLEMENT_LHASH_HASH_FN(f_name,o_type) \
unsigned long f_name##_LHASH_HASH(const void *arg) { \
o_type a = (o_type)arg; \
return f_name(a); }
#define LHASH_HASH_FN(f_name) f_name##_LHASH_HASH

#define DECLARE_LHASH_COMP_FN(f_name,o_type) \
int f_name##_LHASH_COMP(const void *, const void *);
#define IMPLEMENT_LHASH_COMP_FN(f_name,o_type) \
int f_name##_LHASH_COMP(const void *arg1, const void *arg2) { \
o_type a = (o_type)arg1; \
o_type b = (o_type)arg2; \
return f_name(a,b); }
#define LHASH_COMP_FN(f_name) f_name##_LHASH_COMP

#define DECLARE_LHASH_DOALL_FN(f_name,o_type) \
void f_name##_LHASH_DOALL(const void *);
#define IMPLEMENT_LHASH_DOALL_FN(f_name,o_type) \
void f_name##_LHASH_DOALL(const void *arg) { \

162 05 July 2003

Crypto Library LH dynamic hash table

o_type a = (o_type)arg; \
f_name(a); }
#define LHASH_DOALL_FN(f_name) f_name##_LHASH_DOALL

#define DECLARE_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \
void f_name##_LHASH_DOALL_ARG(const void *, const void *);
#define IMPLEMENT_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \
void f_name##_LHASH_DOALL_ARG(const void *arg1, const void *arg2) { \
o_type a = (o_type)arg1; \
a_type b = (a_type)arg2; \
f_name(a,b); }
#define LHASH_DOALL_ARG_FN(f_name) f_name##_LHASH_DOALL_ARG

An example of a hash table storing (pointers to) structures of type ‘STUFF’ could be defined as follows;
/* Calculates the hash value of ’tohash’ (implemented elsewhere) */
unsigned long STUFF_hash(const STUFF *tohash);
/* Orders ’arg1’ and ’arg2’ (implemented elsewhere) */
int STUFF_cmp(const STUFF *arg1, const STUFF *arg2);
/* Create the type-safe wrapper functions for use in the LHASH internals */
static IMPLEMENT_LHASH_HASH_FN(STUFF_hash, const STUFF *)
static IMPLEMENT_LHASH_COMP_FN(STUFF_cmp, const STUFF *);
/* ... */
int main(int argc, char *argv[]) {
/* Create the new hash table using the hash/compare wrappers */
LHASH *hashtable = lh_new(LHASH_HASH_FN(STUFF_hash),
LHASH_COMP_FN(STUFF_cmp));
/* ... */
}

lh_free() frees the LHASH structure table. Allocated hash table entries will not be freed; consider using
lh_doall() to deallocate any remaining entries in the hash table (see below).
lh_insert() inserts the structure pointed to by data into table. If there already is an entry with the same
key, the old value is replaced. Note that lh_insert() stores pointers, the data are not copied.
lh_delete() deletes an entry from table.
lh_retrieve() looks up an entry in table. Normally, data is a structure with the key field(s) set; the
function will return a pointer to a fully populated structure.
lh_doall() will, for every entry in the hash table, call func with the data item as its parameter. For
lh_doall() and lh_doall_arg(), function pointer casting should be avoided in the callbacks (see NOTE) -
instead, either declare the callbacks to match the prototype required in lh_new() or use the
declare/implement macros to create type-safe wrappers that cast variables prior to calling your
type-specific callbacks. An example of this is illustrated here where the callback is used to cleanup
resources for items in the hash table prior to the hashtable itself being deallocated:
/* Cleans up resources belonging to ’a’ (this is implemented elsewhere) */
void STUFF_cleanup(STUFF *a);
/* Implement a prototype-compatible wrapper for "STUFF_cleanup" */
IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF *)
/* ... then later in the code ... */
/* So to run "STUFF_cleanup" against all items in a hash table ... */
lh_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup));
/* Then the hash table itself can be deallocated */
lh_free(hashtable);

When doing this, be careful if you delete entries from the hash table in your callbacks: the table may
decrease in size, moving the item that you are currently on down lower in the hash table - this could
cause some entries to be skipped during the iteration. The second best solution to this problem is to set
hash-down_load=0 before you start (which will stop the hash table ever decreasing in size). The best
solution is probably to avoid deleting items from the hash table inside a "doall" callback!

05 July 2003 163

LH dynamic hash table Crypto Library

lh_doall_arg() is the same as lh_doall() except that func will be called with arg as the second argument
and func should be of type LHASH_DOALL_ARG_FN_TYPE (a callback prototype that is passed
both the table entry and an extra argument). As with lh_doall(), you can instead choose to declare your
callback with a prototype matching the types you are dealing with and use the declare/implement macros
to create compatible wrappers that cast variables before calling your type-specific callbacks. An
example of this is demonstrated here (printing all hash table entries to a BIO that is provided by the
caller):
/* Prints item ’a’ to ’output_bio’ (this is implemented elsewhere) */
void STUFF_print(const STUFF *a, BIO *output_bio);
/* Implement a prototype-compatible wrapper for "STUFF_print" */
static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF_print, const STUFF *, BIO *)
/* ... then later in the code ... */
/* Print out the entire hashtable to a particular BIO */
lh_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), logging_bio);

lh_error() can be used to determine if an error occurred in the last operation. lh_error() is a macro.
RETURN VALUES
lh_new() returns NULL on error, otherwise a pointer to the new LHASH structure.
When a hash table entry is replaced, lh_insert() returns the value being replaced. NULL is returned on
normal operation and on error.
lh_delete() returns the entry being deleted. NULL is returned if there is no such value in the hash table.
lh_retrieve() returns the hash table entry if it has been found, NULL otherwise.
lh_error() returns 1 if an error occurred in the last operation, 0 otherwise.
lh_free(), lh_doall() and lh_doall_arg() return no values.
NOTE
The various LHASH macros and callback types exist to make it possible to write type-safe code without
resorting to function-prototype casting - an evil that makes application code much harder to audit/verify
and also opens the window of opportunity for stack corruption and other hard-to-find bugs. It also,
apparently, violates ANSI-C.
The LHASH code regards table entries as constant data. As such, it internally represents lh_insert()‘d
items with a "const void *" pointer type. This is why callbacks such as those used by lh_doall() and
lh_doall_arg() declare their prototypes with "const", even for the parameters that pass back the table
items’ data pointers - for consistency, user-provided data is "const" at all times as far as the LHASH
code is concerned. However, as callers are themselves providing these pointers, they can choose
whether they too should be treating all such parameters as constant.
As an example, a hash table may be maintained by code that, for reasons of encapsulation, has only
"const" access to the data being indexed in the hash table (ie. it is returned as "const" from elsewhere in
their code) - in this case the LHASH prototypes are appropriate as-is. Conversely, if the caller is
responsible for the life-time of the data in question, then they may well wish to make modifications to
table item passed back in the lh_doall() or lh_doall_arg() callbacks (see the "STUFF_cleanup" example
above). If so, the caller can either cast the "const" away (if they‘re providing the raw callbacks
themselves) or use the macros to declare/implement the wrapper functions without "const" types.
Callers that only have "const" access to data they‘re indexing in a table, yet declare callbacks without
constant types (or cast the "const" away themselves), are therefore creating their own risks/bugs without
being encouraged to do so by the API. On a related note, those auditing code should pay special
attention to any instances of DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros that
provide types without any "const" qualifiers.
BUGS
lh_insert() returns NULL both for success and error.
INTERNALS
The following description is based on the SSLeay documentation:
The lhash library implements a hash table described in the Communications of the ACM in 1991. What
makes this hash table different is that as the table fills, the hash table is increased (or decreased) in size
via OPENSSL_realloc(). When a ‘resize’ is done, instead of all hashes being redistributed over twice as
many ‘buckets‘, one bucket is split. So when an ‘expand’ is done, there is only a minimal cost to
redistribute some values. Subsequent inserts will cause more single ‘bucket’ redistributions but there
will never be a sudden large cost due to redistributing all the ‘buckets’.

164 05 July 2003

Crypto Library LH dynamic hash table

The state for a particular hash table is kept in the LHASH structure. The decision to increase or decrease
the hash table size is made depending on the ‘load’ of the hash table. The load is the number of items in
the hash table divided by the size of the hash table. The default values are as follows. If (hash-up_load
< load) => expand. if (hash-down_load load) = contract. The up_load has a default value of 1 and
down_load has a default value of 2. These numbers can be modified by the application by just playing
with the up_load and down_load variables. The ‘load’ is kept in a form which is multiplied by 256. So
hash-up_load=8*256; will cause a load of 8 to be set.
If you are interested in performance the field to watch is num_comp_calls. The hash library keeps track
of the ‘hash’ value for each item so when a lookup is done, the ‘hashes’ are compared, if there is a
match, then a full compare is done, and hash-num_comp_calls is incremented. If num_comp_calls is not
equal to num_delete plus num_retrieve it means that your hash function is generating hashes that are the
same for different values. It is probably worth changing your hash function if this is the case because
even if your hash table has 10 items in a ‘bucket‘, it can be searched with 10 unsigned long compares
and 10 linked list traverses. This will be much less expensive that 10 calls to your compare function.
lh_strhash() is a demo string hashing function:
unsigned long lh_strhash(const char *c);

Since the LHASH routines would normally be passed structures, this routine would not normally be
passed to lh_new(), rather it would be used in the function passed to lh_new().
SEE ALSO
lh_stats(3)|lh_stats(3)
HISTORY
The lhash library is available in all versions of SSLeay and OpenSSL. lh_error() was added in SSLeay
0.9.1b.
This manpage is derived from the SSLeay documentation.
In OpenSSL 0.9.7, all lhash functions that were passed function pointers were changed for better type
safety, and the function types LHASH_COMP_FN_TYPE, LHASH_HASH_FN_TYPE,
LHASH_DOALL_FN_TYPE and LHASH_DOALL_ARG_FN_TYPE became available.

05 July 2003 165

LH statistics Crypto Library

LH statistics
lh_stats, lh_node_stats, lh_node_usage_stats, lh_stats_bio, lh_node_stats_bio, lh_node_usage_stats_bio -
LHASH statistics
SYNOPSIS
#include <openssl/lhash.h>

void lh_stats(LHASH *table, FILE *out);

void lh_node_stats(LHASH *table, FILE *out);
void lh_node_usage_stats(LHASH *table, FILE *out);

void lh_stats_bio(LHASH *table, BIO *out);

void lh_node_stats_bio(LHASH *table, BIO *out);
void lh_node_usage_stats_bio(LHASH *table, BIO *out);
DESCRIPTION
The LHASH structure records statistics about most aspects of accessing the hash table. This is mostly a
legacy of Eric Young writing this library for the reasons of implementing what looked like a nice
algorithm rather than for a particular software product.
lh_stats() prints out statistics on the size of the hash table, how many entries are in it, and the number
and result of calls to the routines in this library.
lh_node_stats() prints the number of entries for each ‘bucket’ in the hash table.
lh_node_usage_stats() prints out a short summary of the state of the hash table. It prints the ‘load’ and
the ‘actual load’. The load is the average number of data items per ‘bucket’ in the hash table. The
‘actual load’ is the average number of items per ‘bucket‘, but only for buckets which contain entries. So
the ‘actual load’ is the average number of searches that will need to find an item in the hash table, while
the ‘load’ is the average number that will be done to record a miss.
lh_stats_bio(), lh_node_stats_bio() and lh_node_usage_stats_bio() are the same as the above, except that
the output goes to a BIO.
RETURN VALUES
These functions do not return values.
SEE ALSO
bio(3)|bio(3), lhash(3)|lhash(3)
HISTORY
These functions are available in all versions of SSLeay and OpenSSL.
This manpage is derived from the SSLeay documentation.

166 05 July 2003

Crypto Library MD2, MD4, MD5 hash

MD2, MD4, MD5 hash

MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update, MD4_Final,
MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions
SYNOPSIS
#include <openssl/md2.h>

unsigned char *MD2(const unsigned char *d, unsigned long n,

unsigned char *md);

void MD2_Init(MD2_CTX *c);

void MD2_Update(MD2_CTX *c, const unsigned char *data,
unsigned long len);
void MD2_Final(unsigned char *md, MD2_CTX *c);

#include <openssl/md4.h>

unsigned char *MD4(const unsigned char *d, unsigned long n,

unsigned char *md);

void MD4_Init(MD4_CTX *c);

void MD4_Update(MD4_CTX *c, const void *data,
unsigned long len);
void MD4_Final(unsigned char *md, MD4_CTX *c);

#include <openssl/md5.h>

unsigned char *MD5(const unsigned char *d, unsigned long n,

unsigned char *md);

void MD5_Init(MD5_CTX *c);

void MD5_Update(MD5_CTX *c, const void *data,
unsigned long len);
void MD5_Final(unsigned char *md, MD5_CTX *c);
DESCRIPTION
MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output.
MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest of the n bytes at d and
place it in md (which must have space for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH ==
MD5_DIGEST_LENGTH == 16 bytes of output). If md is NULL, the digest is placed in a static array.
The following functions may be used if the message is not completely stored in memory:
MD2_Init() initializes a MD2_CTX structure.
MD2_Update() can be called repeatedly with chunks of the message to be hashed (len bytes at data).
MD2_Final() places the message digest in md, which must have space for MD2_DIGEST_LENGTH ==
16 bytes of output, and erases the MD2_CTX.
MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() are
analogous using an MD4_CTX and MD5_CTX structure.
Applications should use the higher level functions EVP_DigestInit(3)|EVP_DigestInit(3) etc. instead of
calling the hash functions directly.
NOTE
MD2, MD4, and MD5 are recommended only for compatibility with existing applications. In new
applications, SHA-1 or RIPEMD-160 should be preferred.
RETURN VALUES
MD2(), MD4(), and MD5() return pointers to the hash value.
MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(),
MD5_Update(), and MD5_Final() do not return values.

05 July 2003 167

MD2, MD4, MD5 hash Crypto Library

CONFORMING TO
RFC 1319, RFC 1320, RFC 1321
SEE ALSO
sha(3)|sha(3), ripemd(3)|ripemd(3), EVP_DigestInit(3)|EVP_DigestInit(3)
HISTORY
MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(), MD5_Update() and
MD5_Final() are available in all versions of SSLeay and OpenSSL.
MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and above.

168 05 July 2003

Crypto Library MDC2 hash

MDC2 hash
MDC2, MDC2_Init, MDC2_Update, MDC2_Final - MDC2 hash function
SYNOPSIS
#include <openssl/mdc2.h>

unsigned char *MDC2(const unsigned char *d, unsigned long n,

unsigned char *md);

void MDC2_Init(MDC2_CTX *c);

void MDC2_Update(MDC2_CTX *c, const unsigned char *data,
unsigned long len);
void MDC2_Final(unsigned char *md, MDC2_CTX *c);
DESCRIPTION
MDC2 is a method to construct hash functions with 128 bit output from block ciphers. These functions
are an implementation of MDC2 with DES.
MDC2() computes the MDC2 message digest of the n bytes at d and places it in md (which must have
space for MDC2_DIGEST_LENGTH == 16 bytes of output). If md is NULL, the digest is placed in a
static array.
The following functions may be used if the message is not completely stored in memory:
MDC2_Init() initializes a MDC2_CTX structure.
MDC2_Update() can be called repeatedly with chunks of the message to be hashed (len bytes at data).
MDC2_Final() places the message digest in md, which must have space for MDC2_DIGEST_LENGTH
== 16 bytes of output, and erases the MDC2_CTX.
Applications should use the higher level functions EVP_DigestInit(3)|EVP_DigestInit(3) etc. instead of
calling the hash functions directly.
RETURN VALUES
MDC2() returns a pointer to the hash value.
MDC2_Init(), MDC2_Update() and MDC2_Final() do not return values.
CONFORMING TO
ISO/IEC 10118-2, with DES
SEE ALSO
sha(3)|sha(3), EVP_DigestInit(3)|EVP_DigestInit(3)
HISTORY
MDC2(), MDC2_Init(), MDC2_Update() and MDC2_Final() are available since SSLeay 0.8.

05 July 2003 169

OBJ_nid... ASN1 object utility Crypto Library

OBJ_nid... ASN1 object utility

OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid,
OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup - ASN1 object utility
functions
SYNOPSIS
ASN1_OBJECT * OBJ_nid2obj(int n);
const char * OBJ_nid2ln(int n);
const char * OBJ_nid2sn(int n);

int OBJ_obj2nid(const ASN1_OBJECT *o);

int OBJ_ln2nid(const char *ln);
int OBJ_sn2nid(const char *sn);

int OBJ_txt2nid(const char *s);

ASN1_OBJECT * OBJ_txt2obj(const char *s, int no_name);

int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name);

int OBJ_cmp(const ASN1_OBJECT *a,const ASN1_OBJECT *b);

ASN1_OBJECT * OBJ_dup(const ASN1_OBJECT *o);

int OBJ_create(const char *oid,const char *sn,const char *ln);

void OBJ_cleanup(void);
DESCRIPTION
The ASN1 object utility functions process ASN1_OBJECT structures which are a representation of the
ASN1 OBJECT IDENTIFIER (OID) type.
OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID n to an ASN1_OBJECT structure, its
long name and its short name respectively, or NULL is an error occurred.
OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID for the object o, the long
name <ln> or the short name <sn> respectively or NID_undef if an error occurred.
OBJ_txt2nid() returns NID corresponding to text string <s>. s can be a long name, a short name or the
numerical respresentation of an object.
OBJ_txt2obj() converts the text string s into an ASN1_OBJECT structure. If no_name is 0 then long
names and short names will be interpreted as well as numerical forms. If no_name is 1 only the
numerical form is acceptable.
OBJ_obj2txt() converts the ASN1_OBJECT a into a textual representation. The representation is
written as a null terminated string to buf at most buf_len bytes are written, truncating the result if
necessary. The total amount of space required is returned. If no_name is 0 then if the object has a long
or short name then that will be used, otherwise the numerical form will be used. If no_name is 1 then
the numerical form will always be used.
OBJ_cmp() compares a to b. If the two are identical 0 is returned.
OBJ_dup() returns a copy of o.
OBJ_create() adds a new object to the internal table. oid is the numerical form of the object, sn the short
name and ln the long name. A new NID is returned for the created object.
OBJ_cleanup() cleans up OpenSSLs internal object table: this should be called before an application
exits if any new objects were added using OBJ_create().
NOTES
Objects in OpenSSL can have a short name, a long name and a numerical identifier (NID) associated
with them. A standard set of objects is represented in an internal table. The appropriate values are
defined in the header file objects.h.
For example the OID for commonName has the following definitions:
#define SN_commonName "CN"
#define LN_commonName "commonName"
#define NID_commonName 13

170 05 July 2003

Crypto Library OBJ_nid... ASN1 object utility

New objects can be added by calling OBJ_create().

Table objects have certain advantages over other objects: for example their NIDs can be used in a C
language switch statement. They are also static constant structures which are shared: that is there is only
a single constant structure for each table object.
Objects which are not in the table have the NID value NID_undef.
Objects do not need to be in the internal tables to be processed, the functions OBJ_txt2obj() and
OBJ_obj2txt() can process the numerical form of an OID.
EXAMPLES
Create an object for commonName:
ASN1_OBJECT *o;
o = OBJ_nid2obj(NID_commonName);

Check if an object is commonName

if (OBJ_obj2nid(obj) == NID_commonName)
/* Do something */

Create a new NID and initialize an object from it:

int new_nid;
ASN1_OBJECT *obj;
new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");

obj = OBJ_nid2obj(new_nid);

Create a new object directly:

obj = OBJ_txt2obj("1.2.3.4", 1);
BUGS
OBJ_obj2txt() is awkward and messy to use: it doesn‘t follow the convention of other OpenSSL
functions where the buffer can be set to NULL to determine the amount of data that should be written.
Instead buf must point to a valid buffer and buf_len should be set to a positive value. A buffer length of
80 should be more than enough to handle any OID encountered in practice.
RETURN VALUES
OBJ_nid2obj() returns an ASN1_OBJECT structure or NULL is an error occurred.
OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or NULL on error.
OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return a NID or NID_undef on error.
SEE ALSO
ERR_get_error(3)|ERR_get_error(3)
HISTORY
TBA

05 July 2003 171

OpenSSL add algorithms Crypto Library

OpenSSL add algorithms

OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests - add algorithms
to internal table
SYNOPSIS
#include <openssl/evp.h>

void OpenSSL_add_all_algorithms(void);
void OpenSSL_add_all_ciphers(void);
void OpenSSL_add_all_digests(void);

void EVP_cleanup(void);
DESCRIPTION
OpenSSL keeps an internal table of digest algorithms and ciphers. It uses this table to lookup ciphers via
functions such as EVP_get_cipher_byname().
OpenSSL_add_all_digests() adds all digest algorithms to the table.
OpenSSL_add_all_algorithms() adds all algorithms to the table (digests and ciphers).
OpenSSL_add_all_ciphers() adds all encryption algorithms to the table including password based
encryption algorithms.
EVP_cleanup() removes all ciphers and digests from the table.
RETURN VALUES
None of the functions return a value.
NOTES
A typical application will will call OpenSSL_add_all_algorithms() initially and EVP_cleanup() before
exiting.
An application does not need to add algorithms to use them explicitly, for example by EVP_sha1(). It
just needs to add them if it (or any of the functions it calls) needs to lookup algorithms.
The cipher and digest lookup functions are used in many parts of the library. If the table is not initialized
several functions will misbehave and complain they cannot find algorithms. This includes the PEM,
PKCS#12, SSL and S/MIME libraries. This is a common query in the OpenSSL mailing lists.
Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a statically linked executable
can be quite large. If this is important it is possible to just add the required ciphers and digests.
BUGS
Although the functions do not return error codes it is possible for them to fail. This will only happen as a
result of a memory allocation failure so this is not too much of a problem in practice.
SEE ALSO
evp(3)|evp(3), EVP_DigestInit(3)|EVP_DigestInit(3), EVP_EncryptInit(3)|EVP_EncryptInit(3)

172 05 July 2003

Crypto Library OpenSSL version number

OpenSSL version number

OPENSSL_VERSION_NUMBER, SSLeay, SSLeay_version - get OpenSSL version number
SYNOPSIS
#include <openssl/opensslv.h>
#define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL

#include <openssl/crypto.h>
long SSLeay(void);
const char *SSLeay_version(int t);
DESCRIPTION
OPENSSL_VERSION_NUMBER is a numeric release version identifier:
MMNNFFPPS: major minor fix patch status

The status nibble has one of the values 0 for development, 1 to e for betas 1 to 14, and f for release.
for example
0x000906000 == 0.9.6 dev
0x000906023 == 0.9.6b beta 3
0x00090605f == 0.9.6e release

Versions prior to 0.9.3 have identifiers < 0x0930. Versions between 0.9.3 and 0.9.5 had a version
identifier with this interpretation:
MMNNFFRBB major minor fix final beta/patch

for example
0x000904100 == 0.9.4 release
0x000905000 == 0.9.5 dev

Version 0.9.5a had an interim interpretation that is like the current one, except the patch level got the
highest bit set, to keep continuity. The number was therefore 0x0090581f.

For backward compatibility, SSLEAY_VERSION_NUMBER is also defined.

SSLeay() returns this number. The return value can be compared to the macro to make sure that the
correct version of the library has been loaded, especially when using DLLs on Windows systems.
SSLeay_version() returns different strings depending on t:

SSLEAY_VERSION
The text variant of the version number and the release date. For example, "OpenSSL 0.9.5a 1 Apr
2000".
SSLEAY_CFLAGS
The compiler flags set for the compilation process in the form "compiler: ..." if available or
"compiler: information not available" otherwise.
SSLEAY_BUILT_ON
The date of the build process in the form "built on: ..." if available or "built on: date not available"
otherwise.
SSLEAY_PLATFORM
The "Configure" target of the library build in the form "platform: ..." if available or "platform:
information not available" otherwise.
SSLEAY_DIR
The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "..."" if available or
"OPENSSLDIR: N/A" otherwise.

For an unknown t, the text "not available" is returned.

RETURN VALUE
The version number.

05 July 2003 173

OpenSSL version number Crypto Library

SEE ALSO
crypto(3)|crypto(3)
HISTORY
SSLeay() and SSLEAY_VERSION_NUMBER are available in all versions of SSLeay and OpenSSL.
OPENSSL_VERSION_NUMBER is available in all versions of OpenSSL. SSLEAY_DIR was added in
OpenSSL 0.9.7.

174 05 July 2003

Crypto Library PEM routines

PEM routines
PEM - PEM routines
SYNOPSIS
#include <openssl/pem.h>

EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,

pem_password_cb *cb, void *u);

EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,

pem_password_cb *cb, void *u);

int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,

unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);

int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,

unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);

int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,

char *kstr, int klen,
pem_password_cb *cb, void *u);

int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,

char *kstr, int klen,
pem_password_cb *cb, void *u);

int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,

char *kstr, int klen,
pem_password_cb *cb, void *u);

int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,

char *kstr, int klen,
pem_password_cb *cb, void *u);

EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,

pem_password_cb *cb, void *u);

EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,

pem_password_cb *cb, void *u);

int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);

int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);

RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,

pem_password_cb *cb, void *u);

RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,

pem_password_cb *cb, void *u);

int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc,

unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);

int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc,

unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);

05 July 2003 175

PEM routines Crypto Library

RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,

pem_password_cb *cb, void *u);

RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,

pem_password_cb *cb, void *u);

int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);

int PEM_write_RSAPublicKey(FILE *fp, RSA *x);

RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,

pem_password_cb *cb, void *u);

RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,

pem_password_cb *cb, void *u);

int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);

int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);

DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,

pem_password_cb *cb, void *u);

DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,

pem_password_cb *cb, void *u);

int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc,

unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);

int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc,

unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);

DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,

pem_password_cb *cb, void *u);

DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,

pem_password_cb *cb, void *u);

int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);

int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);

DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);

DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);

int PEM_write_bio_DSAparams(BIO *bp, DSA *x);

int PEM_write_DSAparams(FILE *fp, DSA *x);

DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);

DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);

int PEM_write_bio_DHparams(BIO *bp, DH *x);

176 05 July 2003

Crypto Library PEM routines

int PEM_write_DHparams(FILE *fp, DH *x);

X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);

X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);

int PEM_write_bio_X509(BIO *bp, X509 *x);

int PEM_write_X509(FILE *fp, X509 *x);

X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);

X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);

int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);

int PEM_write_X509_AUX(FILE *fp, X509 *x);

X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,

pem_password_cb *cb, void *u);

X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,

pem_password_cb *cb, void *u);

int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);

int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);

int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);

int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);

X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x,

pem_password_cb *cb, void *u);
X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x);
int PEM_write_X509_CRL(FILE *fp, X509_CRL *x);

PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);

PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);

int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);

int PEM_write_PKCS7(FILE *fp, PKCS7 *x);

NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp,

NETSCAPE_CERT_SEQUENCE **x,
pem_password_cb *cb, void *u);

NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp,

NETSCAPE_CERT_SEQUENCE **x,
pem_password_cb *cb, void *u);

int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x);

int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x);

05 July 2003 177

PEM routines Crypto Library

DESCRIPTION
The PEM functions read or write structures in PEM format. In this sense PEM format is simply base64
encoded data surrounded by header lines.
For more details about the meaning of arguments see the PEM FUNCTION ARGUMENTS section.
Each operation has four functions associated with it. For clarity the term "foobar functions" will be used
to collectively refer to the PEM_read_bio_foobar(), PEM_read_foobar(), PEM_write_bio_foobar() and
PEM_write_foobar() functions.
The PrivateKey functions read or write a private key in PEM format using an EVP_PKEY structure.
The write routines use "traditional" private key format and can handle both RSA and DSA private keys.
The read functions can additionally transparently handle PKCS#8 format encrypted and unencrypted
keys too.
PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private key in an
EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based
encryption algorithms. The cipher argument specifies the encryption algoritm to use: unlike all other
PEM routines the encryption is applied at the PKCS#8 level and not in the PEM headers. If cipher is
NULL then no encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead.
PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid() also write out a
private key as a PKCS#8 EncryptedPrivateKeyInfo however it uses PKCS#5 v1.5 or PKCS#12
encryption algorithms instead. The algorithm to use is specified in the nid parameter and should be the
NID of the corresponding OBJECT IDENTIFIER (see NOTES section).
The PUBKEY functions process a public key using an EVP_PKEY structure. The public key is encoded
as a SubjectPublicKeyInfo structure.
The RSAPrivateKey functions process an RSA private key using an RSA structure. It handles the same
formats as the PrivateKey functions but an error occurs if the private key is not RSA.
The RSAPublicKey functions process an RSA public key using an RSA structure. The public key is
encoded using a PKCS#1 RSAPublicKey structure.
The RSA_PUBKEY functions also process an RSA public key using an RSA structure. However the
public key is encoded using a SubjectPublicKeyInfo structure and an error occurs if the public key is not
RSA.
The DSAPrivateKey functions process a DSA private key using a DSA structure. It handles the same
formats as the PrivateKey functions but an error occurs if the private key is not DSA.
The DSA_PUBKEY functions process a DSA public key using a DSA structure. The public key is
encoded using a SubjectPublicKeyInfo structure and an error occurs if the public key is not DSA.
The DSAparams functions process DSA parameters using a DSA structure. The parameters are encoded
using a foobar structure.
The DHparams functions process DH parameters using a DH structure. The parameters are encoded
using a PKCS#3 DHparameter structure.
The X509 functions process an X509 certificate using an X509 structure. They will also process a
trusted X509 certificate but any trust settings are discarded.
The X509_AUX functions process a trusted X509 certificate using an X509 structure.
The X509_REQ and X509_REQ_NEW functions process a PKCS#10 certificate request using an
X509_REQ structure. The X509_REQ write functions use CERTIFICATE REQUEST in the header
whereas the X509_REQ_NEW functions use NEW CERTIFICATE REQUEST (as required by some
CAs). The X509_REQ read functions will handle either form so there are no X509_REQ_NEW read
functions.
The X509_CRL functions process an X509 CRL using an X509_CRL structure.
The PKCS7 functions process a PKCS#7 ContentInfo using a PKCS7 structure.
The NETSCAPE_CERT_SEQUENCE functions process a Netscape Certificate Sequence using a
NETSCAPE_CERT_SEQUENCE structure.
PEM FUNCTION ARGUMENTS
The PEM functions have many common arguments.
The bp BIO parameter (if present) specifies the BIO to read from or write to.
The fp FILE parameter (if present) specifies the FILE pointer to read from or write to.
The PEM read functions all take an argument TYPE **x and return a TYPE * pointer. Where TYPE is
whatever structure the function uses. If x is NULL then the parameter is ignored. If x is not NULL but
*x is NULL then the structure returned will be written to *x. If neither x nor *x is NULL then an attempt
is made to reuse the structure at *x (but see BUGS and EXAMPLES sections). Irrespective of the value
of x a pointer to the structure is always returned (or NULL if an error occurred).

178 05 July 2003

Crypto Library PEM routines

The PEM functions which write private keys take an enc parameter which specifies the encryption
algorithm to use, encryption is done at the PEM level. If this parameter is set to NULL then the private
key is written in unencrypted form.
The cb argument is the callback to use when querying for the pass phrase used for encrypted PEM
structures (normally only private keys).
For the PEM write routines if the kstr parameter is not NULL then klen bytes at kstr are used as the
passphrase and cb is ignored.
If the cb parameters is set to NULL and the u parameter is not NULL then the u parameter is interpreted
as a null terminated string to use as the passphrase. If both cb and u are NULL then the default callback
routine is used which will typically prompt for the passphrase on the current terminal with echoing
turned off.
The default passphrase callback is sometimes inappropriate (for example in a GUI application) so an
alternative can be supplied. The callback routine has the following form:
int cb(char *buf, int size, int rwflag, void *u);

buf is the buffer to write the passphrase to. size is the maximum length of the passphrase (i.e. the size of
buf). rwflag is a flag which is set to 0 when reading and 1 when writing. A typical routine will ask the
user to verify the passphrase (for example by prompting for it twice) if rwflag is 1. The u parameter has
the same value as the u parameter passed to the PEM routine. It allows arbitrary data to be passed to the
callback by the application (for example a window handle in a GUI application). The callback must
return the number of characters in the passphrase or 0 if an error occurred.
EXAMPLES
Although the PEM routines take several arguments in almost all applications most of them are set to 0 or
NULL.
Read a certificate in PEM format from a BIO:
X509 *x;
x = PEM_read_bio(bp, NULL, 0, NULL);
if (x == NULL)
{
/* Error */
}

Alternative method:
X509 *x = NULL;
if (!PEM_read_bio_X509(bp, &x, 0, NULL))
{
/* Error */
}

Write a certificate to a BIO:

if (!PEM_write_bio_X509(bp, x))
{
/* Error */
}

Write an unencrypted private key to a FILE pointer:

if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL))
{
/* Error */
}

Write a private key (using traditional format) to a BIO using triple DES encryption, the pass phrase is
prompted for:
if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
{
/* Error */
}

05 July 2003 179

PEM routines Crypto Library

Write a private key (using PKCS#8 format) to a BIO using triple DES encryption, using the pass phrase
"hello":
if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
NULL, 0, 0, "hello"))
{
/* Error */
}

Read a private key from a BIO using the pass phrase "hello":
key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
if (key == NULL)
{
/* Error */
}

Read a private key from a BIO using a pass phrase callback:

key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
if (key == NULL)
{
/* Error */
}

Skeleton pass phrase callback:

int pass_cb(char *buf, int size, int rwflag, void *u);
{
int len;
char *tmp;
/* We’d probably do something else if ’rwflag’ is 1 */
printf("Enter pass phrase for \"%s\"\n", u);

/* get pass phrase, length ’len’ into ’tmp’ */

tmp = "hello";
len = strlen(tmp);

if (len <= 0) return 0;

/* if too long, truncate */
if (len > size) len = size;
memcpy(buf, tmp, len);
return len;
}
NOTES
The old PrivateKey write routines are retained for compatibility. New applications should write private
keys using the PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines
because they are more secure (they use an iteration count of 2048 whereas the traditional routines use a
count of 1) unless compatibility with older versions of OpenSSL is important.
The PrivateKey read routines can be used in all applications because they handle all formats
transparently.
A frequent cause of problems is attempting to use the PEM routines like this:
X509 *x;
PEM_read_bio_X509(bp, &x, 0, NULL);

this is a bug because an attempt will be made to reuse the data at x which is an uninitialised pointer.
PEM ENCRYPTION FORMAT
This old PrivateKey routines use a non standard technique for encryption.
The private key (or other data) takes the following form:
-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89

180 05 July 2003

Crypto Library PEM routines

...base64 encoded data...

-----END RSA PRIVATE KEY-----

The line beginning DEK-Info contains two comma separated pieces of information: the encryption
algorithm name as used by EVP_get_cipherbyname() and an 8 byte salt encoded as a set of hexadecimal
digits.
After this is the base64 encoded encrypted data.
The encryption key is determined using EVP_bytestokey(), using salt and an iteration count of 1. The IV
used is the value of salt and *not* the IV returned by EVP_bytestokey().
BUGS
The PEM read routines in some versions of OpenSSL will not correctly reuse an existing structure.
Therefore the following:
PEM_read_bio(bp, &x, 0, NULL);

where x already contains a valid certificate, may not work, whereas:

X509_free(x);
x = PEM_read_bio(bp, NULL, 0, NULL);

is guaranteed to work.
RETURN CODES
The read routines return either a pointer to the structure read or NULL is an error occurred.
The write routines return 1 for success or 0 for failure.

05 July 2003 181

PKCS12_create Crypto Library

PKCS12_create
PKCS12_create - create a PKCS#12 structure
SYNOPSIS
#include <openssl/pkcs12.h>

PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert,

STACK_OF(X509) *ca, int nid_key, int nid_cert,
int iter, int mac_iter, int keytype);
DESCRIPTION
PKCS12_create() creates a PKCS#12 structure.
pass is the passphrase to use. name is the friendlyName to use for the supplied certifictate and key.
pkey is the private key to include in the structure and cert its corresponding certificates. ca, if not
NULL is an optional set of certificates to also include in the structure.
nid_key and nid_cert are the encryption algorithms that should be used for the key and certificate
respectively. iter is the encryption algorithm iteration count to use and mac_iter is the MAC iteration
count to use. keytype is the type of key.
NOTES
The parameters nid_key, nid_cert, iter, mac_iter and keytype can all be set to zero and sensible
defaults will be used.
These defaults are: 40 bit RC2 encryption for certificates, triple DES encryption for private keys, a key
iteration count of PKCS12_DEFAULT_ITER (currently 2048) and a MAC iteration count of 1.
The default MAC iteration count is 1 in order to retain compatibility with old software which did not
interpret MAC iteration counts. If such compatibility is not required then mac_iter should be set to
PKCS12_DEFAULT_ITER.
keytype adds a flag to the store private key. This is a non standard extension that is only currently
interpreted by MSIE. If set to zero the flag is omitted, if set to KEY_SIG the key can be used for signing
only, if set to KEY_EX it can be used for signing and encryption. This option was useful for old export
grade software which could use signing only keys of arbitrary size but had restrictions on the permissible
sizes of keys which could be used for encryption.
SEE ALSO
d2i_PKCS12(3)|d2i_PKCS12(3)
HISTORY
PKCS12_create was added in OpenSSL 0.9.3

182 05 July 2003

Crypto Library PKCS12_parse

PKCS12_parse
PKCS12_parse - parse a PKCS#12 structure
SYNOPSIS
#include <openssl/pkcs12.h>

int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert,
STACK_OF(X509) **ca);
DESCRIPTION
PKCS12_parse() parses a PKCS12 structure.
p12 is the PKCS12 structure to parse. pass is the passphrase to use. If successful the private key will be
written to *pkey, the corresponding certificate to *cert and any additional certificates to *ca.
NOTES
The parameters pkey and cert cannot be NULL. ca can be <NULL> in which case additional
certificates will be discarded. *ca can also be a valid STACK in which case additional certificates are
appended to *ca. If *ca is NULL a new STACK will be allocated.
The friendlyName and localKeyID attributes (if present) on each certificate will be stored in the alias
and keyid attributes of the X509 structure.
BUGS
Only a single private key and corresponding certificate is returned by this function. More complex
PKCS#12 files with multiple private keys will only return the first match.
Only friendlyName and localKeyID attributes are currently stored in certificates. Other attributes are
discarded.
Attributes currently cannot be store in the private key EVP_PKEY structure.
SEE ALSO
d2i_PKCS12(3)|d2i_PKCS12(3)
HISTORY
PKCS12_parse was added in OpenSSL 0.9.3

05 July 2003 183

PKCS7_decrypt Crypto Library

PKCS7_decrypt
PKCS7_decrypt - decrypt content from a PKCS#7 envelopedData structure
SYNOPSIS
int PKCS7_decrypt(PKCS7 *p7, EVP_PKEY *pkey, X509 *cert, BIO *data, int flags);
DESCRIPTION
PKCS7_decrypt() extracts and decrypts the content from a PKCS#7 envelopedData structure. pkey is
the private key of the recipient, cert is the recipients certificate, data is a BIO to write the content to and
flags is an optional set of flags.
NOTES
OpenSSL_add_all_algorithms() (or equivalent) should be called before using this function or errors
about unknown algorithms will occur.
Although the recipients certificate is not needed to decrypt the data it is needed to locate the appropriate
(of possible several) recipients in the PKCS#7 structure.
The following flags can be passed in the flags parameter.
If the PKCS7_TEXT flag is set MIME headers for type text/plain are deleted from the content. If the
content is not of type text/plain then an error is returned.
RETURN VALUES
PKCS7_decrypt() returns either 1 for success or 0 for failure. The error can be obtained from
ERR_get_error(3)
BUGS
PKCS7_decrypt() must be passed the correct recipient key and certificate. It would be better if it could
look up the correct key and certificate from a database.
The lack of single pass processing and need to hold all data in memory as mentioned in PKCS7_sign()
also applies to PKCS7_verify().
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), PKCS7_encrypt(3)|PKCS7_encrypt(3)
HISTORY
PKCS7_decrypt() was added to OpenSSL 0.9.5

184 05 July 2003

Crypto Library PKCS7_encrypt

PKCS7_encrypt
PKCS7_encrypt - create a PKCS#7 envelopedData structure
SYNOPSIS
PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags);
DESCRIPTION
PKCS7_encrypt() creates and returns a PKCS#7 envelopedData structure. certs is a list of recipient
certificates. in is the content to be encrypted. cipher is the symmetric cipher to use. flags is an optional
set of flags.
NOTES
Only RSA keys are supported in PKCS#7 and envelopedData so the recipient certificates supplied to this
function must all contain RSA public keys, though they do not have to be signed using the RSA
algorithm.
EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use because most clients will
support it.
Some old "export grade" clients may only support weak encryption using 40 or 64 bit RC2. These can be
used by passing EVP_rc2_40_cbc() and EVP_rc2_64_cbc() respectively.
The algorithm passed in the cipher parameter must support ASN1 encoding of its parameters.
Many browsers implement a "sign and encrypt" option which is simply an S/MIME envelopedData
containing an S/MIME signed message. This can be readily produced by storing the S/MIME signed
message in a memory BIO and passing it to PKCS7_encrypt().
The following flags can be passed in the flags parameter.
If the PKCS7_TEXT flag is set MIME headers for type text/plain are prepended to the data.
Normally the supplied content is translated into MIME canonical format (as required by the S/MIME
specifications) if PKCS7_BINARY is set no translation occurs. This option should be used if the
supplied data is in binary format otherwise the translation will corrupt it. If PKCS7_BINARY is set then
PKCS7_TEXT is ignored.
RETURN VALUES
PKCS7_encrypt() returns either a valid PKCS7 structure or NULL if an error occurred. The error can be
obtained from ERR_get_error(3).
BUGS
The lack of single pass processing and need to hold all data in memory as mentioned in PKCS7_sign()
also applies to PKCS7_verify().
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), PKCS7_decrypt(3)|PKCS7_decrypt(3)
HISTORY
PKCS7_decrypt() was added to OpenSSL 0.9.5

05 July 2003 185

PKCS7_sign Crypto Library

PKCS7_sign
PKCS7_sign - create a PKCS#7 signedData structure
SYNOPSIS
PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs,
BIO *data, int flags);
DESCRIPTION
PKCS7_sign() creates and returns a PKCS#7 signedData structure. signcert is the certificate to sign
with, pkey is the corresponsding private key. certs is an optional additional set of certificates to include
in the PKCS#7 structure (for example any intermediate CAs in the chain).
The data to be signed is read from BIO data.
flags is an optional set of flags.
NOTES
Any of the following flags (ored together) can be passed in the flags parameter.
Many S/MIME clients expect the signed content to include valid MIME headers. If the PKCS7_TEXT
flag is set MIME headers for type text/plain are prepended to the data.
If PKCS7_NOCERTS is set the signer‘s certificate will not be included in the PKCS7 structure, the
signer‘s certificate must still be supplied in the signcert parameter though. This can reduce the size of
the signature if the signers certificate can be obtained by other means: for example a previously signed
message.
The data being signed is included in the PKCS7 structure, unless PKCS7_DETACHED is set in which
case it is omitted. This is used for PKCS7 detached signatures which are used in S/MIME plaintext
signed messages for example.
Normally the supplied content is translated into MIME canonical format (as required by the S/MIME
specifications) if PKCS7_BINARY is set no translation occurs. This option should be used if the
supplied data is in binary format otherwise the translation will corrupt it.
The signedData structure includes several PKCS#7 autenticatedAttributes including the signing time, the
PKCS#7 content type and the supported list of ciphers in an SMIMECapabilities attribute. If
PKCS7_NOATTR is set then no authenticatedAttributes will be used. If PKCS7_NOSMIMECAP is
set then just the SMIMECapabilities are omitted.
If present the SMIMECapabilities attribute indicates support for the following algorithms: triple DES,
128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of these algorithms is disabled then it will not be
included.
BUGS
PKCS7_sign() is somewhat limited. It does not support multiple signers, some advanced attributes such
as counter signatures are not supported.
The SHA1 digest algorithm is currently always used.
When the signed data is not detached it will be stored in memory within the PKCS7 structure. This
effectively limits the size of messages which can be signed due to memory restraints. There should be a
way to sign data without having to hold it all in memory, this would however require fairly major
revisions of the OpenSSL ASN1 code.
Clear text signing does not store the content in memory but the way PKCS7_sign() operates means that
two passes of the data must typically be made: one to compute the signatures and a second to output the
data along with the signature. There should be a way to process the data with only a single pass.
RETURN VALUES
PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error occurred. The error can be
obtained from ERR_get_error(3).
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), PKCS7_verify(3)|PKCS7_verify(3)
HISTORY
PKCS7_sign() was added to OpenSSL 0.9.5

186 05 July 2003

Crypto Library PKCS7_verify

PKCS7_verify
PKCS7_verify - verify a PKCS#7 signedData structure
SYNOPSIS
int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store,
BIO *indata, BIO *out, int flags);
int PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags);
DESCRIPTION
PKCS7_verify() verifies a PKCS#7 signedData structure. p7 is the PKCS7 structure to verify. certs is a
set of certificates in which to search for the signer‘s certificate. store is a trusted certficate store (used
for chain verification). indata is the signed data if the content is not present in p7 (that is it is detached).
The content is written to out if it is not NULL.
flags is an optional set of flags, which can be used to modify the verify operation.
PKCS7_get0_signers() retrieves the signer‘s certificates from p7, it does not check their validity or
whether any signatures are valid. The certs and flags parameters have the same meanings as in
PKCS7_verify().
VERIFY PROCESS
Normally the verify process proceeds as follows.
Initially some sanity checks are performed on p7. The type of p7 must be signedData. There must be at
least one signature on the data and if the content is detached indata cannot be NULL.
An attempt is made to locate all the signer‘s certificates, first looking in the certs parameter (if it is not
NULL) and then looking in any certificates contained in the p7 structure itself. If any signer‘s
certificates cannot be located the operation fails.
Each signer‘s certificate is chain verified using the smimesign purpose and the supplied trusted
certificate store. Any internal certificates in the message are used as untrusted CAs. If any chain verify
fails an error code is returned.
Finally the signed content is read (and written to out is it is not NULL) and the signature‘s checked.
If all signature‘s verify correctly then the function is successful.
Any of the following flags (ored together) can be passed in the flags parameter to change the default
verify behaviour. Only the flag PKCS7_NOINTERN is meaningful to PKCS7_get0_signers().
If PKCS7_NOINTERN is set the certificates in the message itself are not searched when locating the
signer‘s certificate. This means that all the signers certificates must be in the certs parameter.
If the PKCS7_TEXT flag is set MIME headers for type text/plain are deleted from the content. If the
content is not of type text/plain then an error is returned.
If PKCS7_NOVERIFY is set the signer‘s certificates are not chain verified.
If PKCS7_NOCHAIN is set then the certificates contained in the message are not used as untrusted
CAs. This means that the whole verify chain (apart from the signer‘s certificate) must be contained in
the trusted store.
If PKCS7_NOSIGS is set then the signatures on the data are not checked.
NOTES
One application of PKCS7_NOINTERN is to only accept messages signed by a small number of
certificates. The acceptable certificates would be passed in the certs parameter. In this case if the signer
is not one of the certificates supplied in certs then the verify will fail because the signer cannot be found.

Care should be taken when modifying the default verify behaviour, for example setting
PKCS7_NOVERIFY|PKCS7_NOSIGS will totally disable all verification and any signed message
will be considered valid. This combination is however useful if one merely wishes to write the content to
out and its validity is not considered important.
Chain verification should arguably be performed using the signing time rather than the current time.
However since the signing time is supplied by the signer it cannot be trusted without additional evidence
(such as a trusted timestamp).
RETURN VALUES
PKCS7_verify() returns 1 for a successful verification and zero or a negative value if an error occurs.
PKCS7_get0_signers() returns all signers or NULL if an error occurred.
The error can be obtained from ERR_get_error(3)|ERR_get_error(3)

05 July 2003 187

PKCS7_verify Crypto Library

BUGS
The trusted certificate store is not searched for the signers certificate, this is primarily due to the
inadequacies of the current X509_STORE functionality.
The lack of single pass processing and need to hold all data in memory as mentioned in PKCS7_sign()
also applies to PKCS7_verify().
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), PKCS7_sign(3)|PKCS7_sign(3)
HISTORY
PKCS7_verify() was added to OpenSSL 0.9.5

188 05 July 2003

Crypto Library RAND pseudo-random number generator

RAND pseudo-random number generator

RAND - pseudo-random number generator
SYNOPSIS
#include <openssl/rand.h>

int RAND_set_rand_engine(ENGINE *engine);

int RAND_bytes(unsigned char *buf, int num);

int RAND_pseudo_bytes(unsigned char *buf, int num);

void RAND_seed(const void *buf, int num);

void RAND_add(const void *buf, int num, int entropy);
int RAND_status(void);

int RAND_load_file(const char *file, long max_bytes);

int RAND_write_file(const char *file);
const char *RAND_file_name(char *file, size_t num);

int RAND_egd(const char *path);

void RAND_set_rand_method(const RAND_METHOD *meth);

const RAND_METHOD *RAND_get_rand_method(void);
RAND_METHOD *RAND_SSLeay(void);

void RAND_cleanup(void);

/* For Win32 only */

void RAND_screen(void);
int RAND_event(UINT, WPARAM, LPARAM);
DESCRIPTION
Since the introduction of the ENGINE API, the recommended way of controlling default
implementations is by using the ENGINE API functions. The default RAND_METHOD, as set by
RAND_set_rand_method() and returned by RAND_get_rand_method(), is only used if no ENGINE has
been set as the default "rand" implementation. Hence, these two functions are no longer the recommened
way to control defaults.
If an alternative RAND_METHOD implementation is being used (either set directly or as provided by
an ENGINE module), then it is entirely responsible for the generation and management of a
cryptographically secure PRNG stream. The mechanisms described below relate solely to the software
PRNG implementation built in to OpenSSL and used by default.
These functions implement a cryptographically secure pseudo-random number generator (PRNG). It is
used by other library functions for example to generate random keys, and applications can use it when
they need randomness.
A cryptographic PRNG must be seeded with unpredictable data such as mouse movements or keys
pressed at random by the user. This is described in RAND_add(3)|RAND_add(3). Its state can be saved
in a seed file (see RAND_load_file(3)|RAND_load_file(3)) to avoid having to go through the seeding
process whenever the application is started.
RAND_bytes(3)|RAND_bytes(3) describes how to obtain random data from the PRNG.
INTERNALS
The RAND_SSLeay() method implements a PRNG based on a cryptographic hash function.
The following description of its design is based on the SSLeay documentation:
First up I will state the things I believe I need for a good RNG.

1 A good hashing algorithm to mix things up and to convert the RNG ‘state’ to random numbers.
2 An initial source of random ‘state’.
3 The state should be very large. If the RNG is being used to generate 4096 bit RSA keys, 2 2048
bit random strings are required (at a minimum). If your RNG state only has 128 bits, you are

05 July 2003 189

RAND pseudo-random number generator Crypto Library

obviously limiting the search space to 128 bits, not 2048. I‘m probably getting a little carried
away on this last point but it does indicate that it may not be a bad idea to keep quite a lot of RNG
state. It should be easier to break a cipher than guess the RNG seed data.
4 Any RNG seed data should influence all subsequent random numbers generated. This implies that
any random seed data entered will have an influence on all subsequent random numbers generated.

5 When using data to seed the RNG state, the data used should not be extractable from the RNG
state. I believe this should be a requirement because one possible source of ‘secret’ semi random
data would be a private key or a password. This data must not be disclosed by either subsequent
random numbers or a ‘core’ dump left by a program crash.
6 Given the same initial ‘state‘, 2 systems should deviate in their RNG state (and hence the random
numbers generated) over time if at all possible.
7 Given the random number output stream, it should not be possible to determine the RNG state or
the next random number.

The algorithm is as follows.

There is global state made up of a 1023 byte buffer (the ‘state’), a working hash value (‘md’), and a
counter (‘count’).
Whenever seed data is added, it is inserted into the ‘state’ as follows.
The input is chopped up into units of 20 bytes (or less for the last block). Each of these blocks is run
through the hash function as follows: The data passed to the hash function is the current ‘md‘, the same
number of bytes from the ‘state’ (the location determined by in incremented looping index) as the
current ‘block‘, the new key data ‘block‘, and ‘count’ (which is incremented after each use). The result
of this is kept in ‘md’ and also xored into the ‘state’ at the same locations that were used as input into the
hash function. I believe this system addresses points 1 (hash function; currently SHA-1), 3 (the ‘state’), 4
(via the ‘md’), 5 (by the use of a hash function and xor).
When bytes are extracted from the RNG, the following process is used. For each group of 10 bytes (or
less), we do the following:
Input into the hash function the local ‘md’ (which is initialized from the global ‘md’ before any bytes are
generated), the bytes that are to be overwritten by the random bytes, and bytes from the ‘state’
(incrementing looping index). From this digest output (which is kept in ‘md’), the top (up to) 10 bytes
are returned to the caller and the bottom 10 bytes are xored into the ‘state’.
Finally, after we have finished ‘num’ random bytes for the caller, ‘count’ (which is incremented) and the
local and global ‘md’ are fed into the hash function and the results are kept in the global ‘md’.
I believe the above addressed points 1 (use of SHA-1), 6 (by hashing into the ‘state’ the ‘old’ data from
the caller that is about to be overwritten) and 7 (by not using the 10 bytes given to the caller to update
the ‘state‘, but they are used to update ‘md’).
So of the points raised, only 2 is not addressed (but see RAND_add(3)|RAND_add(3)).
SEE ALSO
BN_rand(3)|BN_rand(3), RAND_add(3)|RAND_add(3), RAND_load_file(3)|RAND_load_file(3),
RAND_egd(3)|RAND_egd(3), RAND_bytes(3)|RAND_bytes(3),
RAND_set_rand_method(3)|RAND_set_rand_method(3), RAND_cleanup(3)|RAND_cleanup(3)

190 05 July 2003

Crypto Library RAND entropy

RAND entropy
RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen - add entropy to the PRNG
SYNOPSIS
#include <openssl/rand.h>

void RAND_seed(const void *buf, int num);

void RAND_add(const void *buf, int num, double entropy);

int RAND_status(void);

int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam);

void RAND_screen(void);
DESCRIPTION
RAND_add() mixes the num bytes at buf into the PRNG state. Thus, if the data at buf are unpredictable
to an adversary, this increases the uncertainty about the state and makes the PRNG output less
predictable. Suitable input comes from user interaction (random key presses, mouse movements) and
certain hardware events. The entropy argument is (the lower bound of) an estimate of how much
randomness is contained in buf, measured in bytes. Details about sources of randomness and how to
estimate their entropy can be found in the literature, e.g. RFC 1750.
RAND_add() may be called with sensitive data such as user entered passwords. The seed values cannot
be recovered from the PRNG output.
OpenSSL makes sure that the PRNG state is unique for each thread. On systems that provide
/dev/urandom, the randomness device is used to seed the PRNG transparently. However, on all other
systems, the application is responsible for seeding the PRNG by calling RAND_add(),
RAND_egd(3)|RAND_egd(3) or RAND_load_file(3)|RAND_load_file(3).
RAND_seed() is equivalent to RAND_add() when num == entropy.
RAND_event() collects the entropy from Windows events such as mouse movements and other user
interaction. It should be called with the iMsg, wParam and lParam arguments of all messages sent to
the window procedure. It will estimate the entropy contained in the event message (if any), and add it to
the PRNG. The program can then process the messages as usual.
The RAND_screen() function is available for the convenience of Windows programmers. It adds the
current contents of the screen to the PRNG. For applications that can catch Windows events, seeding the
PRNG by calling RAND_event() is a significantly better source of randomness. It should be noted that
both methods cannot be used on servers that run without user interaction.
RETURN VALUES
RAND_status() and RAND_event() return 1 if the PRNG has been seeded with enough data, 0
otherwise.
The other functions do not return values.
SEE ALSO
rand(3)|rand(3), RAND_egd(3)|RAND_egd(3), RAND_load_file(3)|RAND_load_file(3),
RAND_cleanup(3)|RAND_cleanup(3)
HISTORY
RAND_seed() and RAND_screen() are available in all versions of SSLeay and OpenSSL. RAND_add()
and RAND_status() have been added in OpenSSL 0.9.5, RAND_event() in OpenSSL 0.9.5a.

05 July 2003 191

RAND random data Crypto Library

RAND random data

RAND_bytes, RAND_pseudo_bytes - generate random data
SYNOPSIS
#include <openssl/rand.h>

int RAND_bytes(unsigned char *buf, int num);

int RAND_pseudo_bytes(unsigned char *buf, int num);

DESCRIPTION
RAND_bytes() puts num cryptographically strong pseudo-random bytes into buf. An error occurs if the
PRNG has not been seeded with enough randomness to ensure an unpredictable byte sequence.
RAND_pseudo_bytes() puts num pseudo-random bytes into buf. Pseudo-random byte sequences
generated by RAND_pseudo_bytes() will be unique if they are of sufficient length, but are not
necessarily unpredictable. They can be used for non-cryptographic purposes and for certain purposes in
cryptographic protocols, but usually not for key generation etc.
RETURN VALUES
RAND_bytes() returns 1 on success, 0 otherwise. The error code can be obtained by
ERR_get_error(3)|ERR_get_error(3). RAND_pseudo_bytes() returns 1 if the bytes generated are
cryptographically strong, 0 otherwise. Both functions return -1 if they are not supported by the current
RAND method.
SEE ALSO
rand(3)|rand(3), ERR_get_error(3)|ERR_get_error(3), RAND_add(3)|RAND_add(3)
HISTORY
RAND_bytes() is available in all versions of SSLeay and OpenSSL. It has a return value since
OpenSSL 0.9.5. RAND_pseudo_bytes() was added in OpenSSL 0.9.5.

192 05 July 2003

Crypto Library RAND cleanup

RAND cleanup
RAND_cleanup - erase the PRNG state
SYNOPSIS
#include <openssl/rand.h>

void RAND_cleanup(void);
DESCRIPTION
RAND_cleanup() erases the memory used by the PRNG.
RETURN VALUE
RAND_cleanup() returns no value.
SEE ALSO
rand(3)|rand(3)
HISTORY
RAND_cleanup() is available in all versions of SSLeay and OpenSSL.

05 July 2003 193

RAND_egd entropy daemon Crypto Library

RAND_egd entropy daemon

RAND_egd - query entropy gathering daemon
SYNOPSIS
#include <openssl/rand.h>

int RAND_egd(const char *path);

int RAND_egd_bytes(const char *path, int bytes);

int RAND_query_egd_bytes(const char *path, unsigned char *buf, int bytes);

DESCRIPTION
RAND_egd() queries the entropy gathering daemon EGD on socket path. It queries 255 bytes and uses
RAND_add(3)|RAND_add(3) to seed the OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for
RAND_egd_bytes(path, 255);
RAND_egd_bytes() queries the entropy gathering daemon EGD on socket path. It queries bytes bytes
and uses RAND_add(3)|RAND_add(3) to seed the OpenSSL built-in PRNG. This function is more
flexible than RAND_egd(). When only one secret key must be generated, it is not necessary to request
the full amount 255 bytes from the EGD socket. This can be advantageous, since the amount of entropy
that can be retrieved from EGD over time is limited.
RAND_query_egd_bytes() performs the actual query of the EGD daemon on socket path. If buf is
given, bytes bytes are queried and written into buf. If buf is NULL, bytes bytes are queried and used to
seed the OpenSSL built-in PRNG using RAND_add(3)|RAND_add(3).
NOTES
On systems without /dev/*random devices providing entropy from the kernel, the EGD entropy
gathering daemon can be used to collect entropy. It provides a socket interface through which entropy
can be gathered in chunks up to 255 bytes. Several chunks can be queried during one connection.
EGD is available from http://www.lothar.com/tech/crypto/ (perl Makefile.PL; make; make
install to install). It is run as egd path, where path is an absolute path designating a socket. When
RAND_egd() is called with that path as an argument, it tries to read random bytes that EGD has
collected. The read is performed in non-blocking mode.
Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is available from
http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html . PRNGD does employ an internal
PRNG itself and can therefore never run out of entropy.
OpenSSL automatically queries EGD when entropy is requested via RAND_bytes() or the status is
checked via RAND_status() for the first time, if the socket is located at /var/run/egd-pool, /dev/egd-pool
or /etc/egd-pool.
RETURN VALUE
RAND_egd() and RAND_egd_bytes() return the number of bytes read from the daemon on success, and
-1 if the connection failed or the daemon did not return enough data to fully seed the PRNG.
RAND_query_egd_bytes() returns the number of bytes read from the daemon on success, and -1 if the
connection failed. The PRNG state is not considered.
SEE ALSO
rand(3)|rand(3), RAND_add(3)|RAND_add(3), RAND_cleanup(3)|RAND_cleanup(3)
HISTORY
RAND_egd() is available since OpenSSL 0.9.5.
RAND_egd_bytes() is available since OpenSSL 0.9.6.
RAND_query_egd_bytes() is available since OpenSSL 0.9.7.
The automatic query of /var/run/egd-pool et al was added in OpenSSL 0.9.7.

194 05 July 2003

Crypto Library RAND seed file

RAND seed file

RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file
SYNOPSIS
#include <openssl/rand.h>

const char *RAND_file_name(char *buf, size_t num);

int RAND_load_file(const char *filename, long max_bytes);

int RAND_write_file(const char *filename);

DESCRIPTION
RAND_file_name() generates a default path for the random seed file. buf points to a buffer of size num
in which to store the filename. The seed file is $RANDFILE if that environment variable is set,
$HOME/.rnd otherwise. If $HOME is not set either, or num is too small for the path name, an error
occurs.
RAND_load_file() reads a number of bytes from file filename and adds them to the PRNG. If
max_bytes is non-negative, up to to max_bytes are read; starting with OpenSSL 0.9.5, if max_bytes is
-1, the complete file is read.
RAND_write_file() writes a number of random bytes (currently 1024) to file filename which can be
used to initialize the PRNG by calling RAND_load_file() in a later session.
RETURN VALUES
RAND_load_file() returns the number of bytes read.
RAND_write_file() returns the number of bytes written, and -1 if the bytes written were generated
without appropriate seed.
RAND_file_name() returns a pointer to buf on success, and NULL on error.
SEE ALSO
rand(3)|rand(3), RAND_add(3)|RAND_add(3), RAND_cleanup(3)|RAND_cleanup(3)
HISTORY
RAND_load_file(), RAND_write_file() and RAND_file_name() are available in all versions of SSLeay
and OpenSSL.

05 July 2003 195

RAND select method Crypto Library

RAND select method

RAND_set_rand_method, RAND_get_rand_method, RAND_SSLeay - select RAND method
SYNOPSIS
#include <openssl/rand.h>

void RAND_set_rand_method(const RAND_METHOD *meth);

const RAND_METHOD *RAND_get_rand_method(void);

RAND_METHOD *RAND_SSLeay(void);
DESCRIPTION
A RAND_METHOD specifies the functions that OpenSSL uses for random number generation. By
modifying the method, alternative implementations such as hardware RNGs may be used.
IMPORTANT: See the NOTES section for important information about how these RAND API functions
are affected by the use of ENGINE API calls.
Initially, the default RAND_METHOD is the OpenSSL internal implementation, as returned by
RAND_SSLeay().
RAND_set_default_method() makes meth the method for PRNG use. NB: This is true only whilst no
ENGINE has been set as a default for RAND, so this function is no longer recommended.
RAND_get_default_method() returns a pointer to the current RAND_METHOD. However, the
meaningfulness of this result is dependant on whether the ENGINE API is being used, so this function is
no longer recommended.
THE RAND_METHOD STRUCTURE
typedef struct rand_meth_st
{
void (*seed)(const void *buf, int num);
int (*bytes)(unsigned char *buf, int num);
void (*cleanup)(void);
void (*add)(const void *buf, int num, int entropy);
int (*pseudorand)(unsigned char *buf, int num);
int (*status)(void);
} RAND_METHOD;

The components point to the implementation of RAND_seed(), RAND_bytes(), RAND_cleanup(),

RAND_add(), RAND_pseudo_rand() and RAND_status(). Each component may be NULL if the
function is not implemented.
RETURN VALUES
RAND_set_rand_method() returns no value. RAND_get_rand_method() and RAND_SSLeay() return
pointers to the respective methods.
NOTES
As of version 0.9.7, RAND_METHOD implementations are grouped together with other algorithmic
APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in ENGINE modules. If a default ENGINE is specified
for RAND functionality using an ENGINE API function, that will override any RAND defaults set using
the RAND API (ie. RAND_set_rand_method()). For this reason, the ENGINE API is the recommended
way to control default implementations for use in RAND and other cryptographic algorithms.
SEE ALSO
rand(3)|rand(3), engine(3)|engine(3)
HISTORY
RAND_set_rand_method(), RAND_get_rand_method() and RAND_SSLeay() are available in all
versions of OpenSSL.
In the engine version of version 0.9.6, RAND_set_rand_method() was altered to take an ENGINE
pointer as its argument. As of version 0.9.7, that has been reverted as the ENGINE API transparently
overrides RAND defaults if used, otherwise RAND API functions work as before.

196 05 July 2003

Crypto Library RAND select method

RAND_set_rand_engine() was also introduced in version 0.9.7.

05 July 2003 197

RC4 encryption Crypto Library

RC4 encryption
RC4_set_key, RC4 - RC4 encryption
SYNOPSIS
#include <openssl/rc4.h>

void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data);

void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata,
unsigned char *outdata);
DESCRIPTION
This library implements the Alleged RC4 cipher, which is described for example in Applied
Cryptography. It is believed to be compatible with RC4[TM], a proprietary cipher of RSA Security Inc.
RC4 is a stream cipher with variable key length. Typically, 128 bit (16 byte) keys are used for strong
encryption, but shorter insecure key sizes have been widely used due to export restrictions.
RC4 consists of a key setup phase and the actual encryption or decryption phase.
RC4_set_key() sets up the RC4_KEY key using the len bytes long key at data.
RC4() encrypts or decrypts the len bytes of data at indata using key and places the result at outdata.
Repeated RC4() calls with the same key yield a continuous key stream.
Since RC4 is a stream cipher (the input is XORed with a pseudo-random key stream to produce the
output), decryption uses the same function calls as encryption.
Applications should use the higher level functions EVP_EncryptInit(3)|EVP_EncryptInit(3) etc. instead
of calling the RC4 functions directly.
RETURN VALUES
RC4_set_key() and RC4() do not return values.
NOTE
Certain conditions have to be observed to securely use stream ciphers. It is not permissible to perform
multiple encryptions using the same key stream.
SEE ALSO
blowfish(3)|blowfish(3), des(3)|des(3), rc2(3)|rc2(3)
HISTORY
RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL.

198 05 July 2003

Crypto Library RIPEMD-160 hash

RIPEMD-160 hash
RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final - RIPEMD-160 hash
function
SYNOPSIS
#include <openssl/ripemd.h>

unsigned char *RIPEMD160(const unsigned char *d, unsigned long n,

unsigned char *md);

void RIPEMD160_Init(RIPEMD160_CTX *c);

void RIPEMD160_Update(RIPEMD_CTX *c, const void *data,
unsigned long len);
void RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c);
DESCRIPTION
RIPEMD-160 is a cryptographic hash function with a 160 bit output.
RIPEMD160() computes the RIPEMD-160 message digest of the n bytes at d and places it in md (which
must have space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If md is NULL, the
digest is placed in a static array.
The following functions may be used if the message is not completely stored in memory:
RIPEMD160_Init() initializes a RIPEMD160_CTX structure.
RIPEMD160_Update() can be called repeatedly with chunks of the message to be hashed (len bytes at
data).
RIPEMD160_Final() places the message digest in md, which must have space for
RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases the RIPEMD160_CTX.
Applications should use the higher level functions EVP_DigestInit(3)|EVP_DigestInit(3) etc. instead of
calling the hash functions directly.
RETURN VALUES
RIPEMD160() returns a pointer to the hash value.
RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() do not return values.
CONFORMING TO
ISO/IEC 10118-3 (draft) (??)
SEE ALSO
sha(3)|sha(3), hmac(3)|hmac(3), EVP_DigestInit(3)|EVP_DigestInit(3)
HISTORY
RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() are available
since SSLeay 0.9.0.

05 July 2003 199

RSA public key cryptosystem Crypto Library

RSA public key cryptosystem

rsa - RSA public key cryptosystem
SYNOPSIS
#include <openssl/rsa.h>
#include <openssl/engine.h>

RSA * RSA_new(void);
void RSA_free(RSA *rsa);

int RSA_public_encrypt(int flen, unsigned char *from,

unsigned char *to, RSA *rsa, int padding);
int RSA_private_decrypt(int flen, unsigned char *from,
unsigned char *to, RSA *rsa, int padding);
int RSA_private_encrypt(int flen, unsigned char *from,
unsigned char *to, RSA *rsa,int padding);
int RSA_public_decrypt(int flen, unsigned char *from,
unsigned char *to, RSA *rsa,int padding);

int RSA_sign(int type, unsigned char *m, unsigned int m_len,

unsigned char *sigret, unsigned int *siglen, RSA *rsa);
int RSA_verify(int type, unsigned char *m, unsigned int m_len,
unsigned char *sigbuf, unsigned int siglen, RSA *rsa);

int RSA_size(const RSA *rsa);

RSA *RSA_generate_key(int num, unsigned long e,

void (*callback)(int,int,void *), void *cb_arg);

int RSA_check_key(RSA *rsa);

int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);

void RSA_blinding_off(RSA *rsa);

void RSA_set_default_method(const RSA_METHOD *meth);

const RSA_METHOD *RSA_get_default_method(void);
int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);
const RSA_METHOD *RSA_get_method(const RSA *rsa);
RSA_METHOD *RSA_PKCS1_SSLeay(void);
RSA_METHOD *RSA_null_method(void);
int RSA_flags(const RSA *rsa);
RSA *RSA_new_method(ENGINE *engine);

int RSA_print(BIO *bp, RSA *x, int offset);

int RSA_print_fp(FILE *fp, RSA *x, int offset);

int RSA_get_ex_new_index(long argl, char *argp, int (*new_func)(),

int (*dup_func)(), void (*free_func)());
int RSA_set_ex_data(RSA *r,int idx,char *arg);
char *RSA_get_ex_data(RSA *r, int idx);

int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m,

unsigned int m_len, unsigned char *sigret, unsigned int *siglen,
RSA *rsa);
int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m,
unsigned int m_len, unsigned char *sigbuf, unsigned int siglen,
RSA *rsa);

200 05 July 2003

Crypto Library RSA public key cryptosystem

DESCRIPTION
These functions implement RSA public key encryption and signatures as defined in PKCS #1 v2.0 [RFC
2437].
The RSA structure consists of several BIGNUM components. It can contain public as well as private
RSA keys:
struct
{
BIGNUM *n; // public modulus
BIGNUM *e; // public exponent
BIGNUM *d; // private exponent
BIGNUM *p; // secret prime factor
BIGNUM *q; // secret prime factor
BIGNUM *dmp1; // d mod (p-1)
BIGNUM *dmq1; // d mod (q-1)
BIGNUM *iqmp; // q^-1 mod p
// ...
};
RSA

In public keys, the private exponent and the related secret values are NULL.
p, q, dmp1, dmq1 and iqmp may be NULL in private keys, but the RSA operations are much faster
when these values are available.
Note that RSA keys may use non-standard RSA_METHOD implementations, either directly or by the
use of ENGINE modules. In some cases (eg. an ENGINE providing support for hardware-embedded
keys), these BIGNUM values will not be used by the implementation or may be used for alternative data
storage. For this reason, applications should generally avoid using RSA structure elements directly and
instead use API functions to query or modify keys.
CONFORMING TO
SSL, PKCS #1 v2.0
PATENTS
RSA was covered by a US patent which expired in September 2000.
SEE ALSO
rsa(1)|rsa(1), bn(3)|bn(3), dsa(3)|dsa(3), dh(3)|dh(3), rand(3)|rand(3), engine(3)|engine(3),
RSA_new(3)|RSA_new(3), RSA_public_encrypt(3)|RSA_public_encrypt(3), RSA_sign(3)|RSA_sign(3),
RSA_size(3)|RSA_size(3), RSA_generate_key(3)|RSA_generate_key(3),
RSA_check_key(3)|RSA_check_key(3), RSA_blinding_on(3)|RSA_blinding_on(3),
RSA_set_method(3)|RSA_set_method(3), RSA_print(3)|RSA_print(3),
RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3),
RSA_private_encrypt(3)|RSA_private_encrypt(3),
RSA_sign_ASN1_OCTET_STRING(3)|RSA_sign_ASN1_OCTET_STRING(3),
RSA_padding_add_PKCS1_type_1(3)|RSA_padding_add_PKCS1_type_1(3)

05 July 2003 201

RSA protection from timing attacks Crypto Library

RSA protection from timing attacks

RSA_blinding_on, RSA_blinding_off - protect the RSA operation from timing attacks
SYNOPSIS
#include <openssl/rsa.h>

int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);

void RSA_blinding_off(RSA *rsa);

DESCRIPTION
RSA is vulnerable to timing attacks. In a setup where attackers can measure the time of RSA decryption
or signature operations, blinding must be used to protect the RSA operation from that attack.
RSA_blinding_on() turns blinding on for key rsa and generates a random blinding factor. ctx is NULL
or a pre-allocated and initialized BN_CTX. The random number generator must be seeded prior to
calling RSA_blinding_on().
RSA_blinding_off() turns blinding off and frees the memory used for the blinding factor.
RETURN VALUES
RSA_blinding_on() returns 1 on success, and 0 if an error occurred.
RSA_blinding_off() returns no value.
SEE ALSO
rsa(3)|rsa(3), rand(3)|rand(3)
HISTORY
RSA_blinding_on() and RSA_blinding_off() appeared in SSLeay 0.9.0.

202 05 July 2003

Crypto Library RSA validate private keys

RSA validate private keys

RSA_check_key - validate private RSA keys
SYNOPSIS
#include <openssl/rsa.h>

int RSA_check_key(RSA *rsa);

DESCRIPTION
This function validates RSA keys. It checks that p and q are in fact prime, and that n = p*q.
It also checks that d*e = 1 mod (p-1*q-1), and that dmp1, dmq1 and iqmp are set correctly or are
NULL.
As such, this function can not be used with any arbitrary RSA key object, even if it is otherwise fit for
regular RSA operation. See NOTES for more information.
RETURN VALUE
RSA_check_key() returns 1 if rsa is a valid RSA key, and 0 otherwise. -1 is returned if an error occurs
while checking the key.
If the key is invalid or an error occurred, the reason code can be obtained using
ERR_get_error(3)|ERR_get_error(3).
NOTES
This function does not work on RSA public keys that have only the modulus and public exponent
elements populated. It performs integrity checks on all the RSA key material, so the RSA key structure
must contain all the private key data too.
Unlike most other RSA functions, this function does not work transparently with any underlying
ENGINE implementation because it uses the key data in the RSA structure directly. An ENGINE
implementation can override the way key data is stored and handled, and can even provide support for
HSM keys - in which case the RSA structure may contain no key data at all! If the ENGINE in question
is only being used for acceleration or analysis purposes, then in all likelihood the RSA key data is
complete and untouched, but this can‘t be assumed in the general case.
BUGS
A method of verifying the RSA key using opaque RSA API functions might need to be considered.
Right now RSA_check_key() simply uses the RSA structure elements directly, bypassing the
RSA_METHOD table altogether (and completely violating encapsulation and object-orientation in the
process). The best fix will probably be to introduce a "check_key()" handler to the RSA_METHOD
function table so that alternative implementations can also provide their own verifiers.
SEE ALSO
rsa(3)|rsa(3), ERR_get_error(3)|ERR_get_error(3)
HISTORY
RSA_check_key() appeared in OpenSSL 0.9.4.

05 July 2003 203

RSA generate key pair Crypto Library

RSA generate key pair

RSA_generate_key - generate RSA key pair
SYNOPSIS
#include <openssl/rsa.h>

RSA *RSA_generate_key(int num, unsigned long e,

void (*callback)(int,int,void *), void *cb_arg);
DESCRIPTION
RSA_generate_key() generates a key pair and returns it in a newly allocated RSA structure. The
pseudo-random number generator must be seeded prior to calling RSA_generate_key().
The modulus size will be num bits, and the public exponent will be e. Key sizes with num < 1024
should be considered insecure. The exponent is an odd number, typically 3, 17 or 65537.
A callback function may be used to provide feedback about the progress of the key generation. If
callback is not NULL, it will be called as follows:

While a random prime number is generated, it is called as described in

BN_generate_prime(3)|BN_generate_prime(3).
When the n-th randomly generated prime is rejected as not suitable for the key, callback(2, n,
cb_arg) is called.
When a random p has been found with p-1 relatively prime to e, it is called as callback(3, 0,
cb_arg).

The process is then repeated for prime q with callback(3, 1, cb_arg).

RETURN VALUE
If key generation fails, RSA_generate_key() returns NULL; the error codes can be obtained by
ERR_get_error(3)|ERR_get_error(3).
BUGS
callback(2, x, cb_arg) is used with two different meanings.
RSA_generate_key() goes into an infinite loop for illegal input values.
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), rand(3)|rand(3), rsa(3)|rsa(3), RSA_free(3)|RSA_free(3)
HISTORY
The cb_arg argument was added in SSLeay 0.9.0.

204 05 July 2003

Crypto Library RSA add application data

RSA add application data

RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specific data to RSA
structures
SYNOPSIS
#include <openssl/rsa.h>

int RSA_get_ex_new_index(long argl, void *argp,

CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);

int RSA_set_ex_data(RSA *r, int idx, void *arg);

void *RSA_get_ex_data(RSA *r, int idx);

typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,

int idx, long argl, void *argp);
typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
int idx, long argl, void *argp);
DESCRIPTION
Several OpenSSL structures can have application specific data attached to them. This has several
potential uses, it can be used to cache data associated with a structure (for example the hash of some part
of the structure) or some additional data (for example a handle to the data in an external library).
Since the application data can be anything at all it is passed and retrieved as a void * type.
The RSA_get_ex_new_index() function is initially called to "register" some new application specific
data. It takes three optional function pointers which are called when the parent structure (in this case an
RSA structure) is initially created, when it is copied and when it is freed up. If any or all of these
function pointer arguments are not used they should be set to NULL. The precise manner in which these
function pointers are called is described in more detail below. RSA_get_ex_new_index() also takes
additional long and pointer parameters which will be passed to the supplied functions but which
otherwise have no special meaning. It returns an index which should be stored (typically in a static
variable) and passed used in the idx parameter in the remaining functions. Each successful call to
RSA_get_ex_new_index() will return an index greater than any previously returned, this is important
because the optional functions are called in order of increasing index value.
RSA_set_ex_data() is used to set application specific data, the data is supplied in the arg parameter and
its precise meaning is up to the application.
RSA_get_ex_data() is used to retrieve application specific data. The data is returned to the application,
this will be the same value as supplied to a previous RSA_set_ex_data() call.
new_func() is called when a structure is initially allocated (for example with RSA_new(). The parent
structure members will not have any meaningful values at this point. This function will typically be used
to allocate any application specific structure.
free_func() is called when a structure is being freed up. The dynamic parent structure members should
not be accessed because they will be freed up when this function is called.
new_func() and free_func() take the same parameters. parent is a pointer to the parent RSA structure.
ptr is a the application specific data (this wont be of much use in new_func(). ad is a pointer to the
CRYPTO_EX_DATA structure from the parent RSA structure: the functions CRYPTO_get_ex_data()
and CRYPTO_set_ex_data() can be called to manipulate it. The idx parameter is the index: this will be
the same value returned by RSA_get_ex_new_index() when the functions were initially registered.
Finally the argl and argp parameters are the values originally passed to the same corresponding
parameters when RSA_get_ex_new_index() was called.
dup_func() is called when a structure is being copied. Pointers to the destination and source
CRYPTO_EX_DATA structures are passed in the to and from parameters respectively. The from_d
parameter is passed a pointer to the source application data when the function is called, when the
function returns the value is copied to the destination: the application can thus modify the data pointed to
by from_d and have different values in the source and destination. The idx, argl and argp parameters

05 July 2003 205

RSA add application data Crypto Library

are the same as those in new_func() and free_func().

RETURN VALUES
RSA_get_ex_new_index() returns a new index or -1 on failure (note 0 is a valid index value).
RSA_set_ex_data() returns 1 on success or 0 on failure.
RSA_get_ex_data() returns the application data or 0 on failure. 0 may also be valid application data but
currently it can only fail if given an invalid idx parameter.
new_func() and dup_func() should return 0 for failure and 1 for success.
On failure an error code can be obtained from ERR_get_error(3)|ERR_get_error(3).
BUGS
dup_func() is currently never called.
The return value of new_func() is ignored.
The new_func() function isn‘t very useful because no meaningful values are present in the parent RSA
structure when it is called.
SEE ALSO
rsa(3)|rsa(3), CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)
HISTORY
RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are available since SSLeay
0.9.0.

206 05 July 2003

Crypto Library RSA allocation

RSA allocation
RSA_new, RSA_free - allocate and free RSA objects
SYNOPSIS
#include <openssl/rsa.h>

RSA * RSA_new(void);

void RSA_free(RSA *rsa);

DESCRIPTION
RSA_new() allocates and initializes an RSA structure. It is equivalent to calling
RSA_new_method(NULL).
RSA_free() frees the RSA structure and its components. The key is erased before the memory is
returned to the system.
RETURN VALUES
If the allocation fails, RSA_new() returns NULL and sets an error code that can be obtained by
ERR_get_error(3)|ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.
RSA_free() returns no value.
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), rsa(3)|rsa(3), RSA_generate_key(3)|RSA_generate_key(3),
RSA_new_method(3)|RSA_new_method(3)
HISTORY
RSA_new() and RSA_free() are available in all versions of SSLeay and OpenSSL.

05 July 2003 207

RSA asymmetric encryption padding Crypto Library

RSA asymmetric encryption padding

RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1,
RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2,
RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP, RSA_padding_add_SSLv23,
RSA_padding_check_SSLv23, RSA_padding_add_none, RSA_padding_check_none - asymmetric
encryption padding
SYNOPSIS
#include <openssl/rsa.h>

int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen,

unsigned char *f, int fl);

int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen,

unsigned char *f, int fl, int rsa_len);

int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen,

unsigned char *f, int fl);

int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen,

unsigned char *f, int fl, int rsa_len);

int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen,

unsigned char *f, int fl, unsigned char *p, int pl);

int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen,

unsigned char *f, int fl, int rsa_len, unsigned char *p, int pl);

int RSA_padding_add_SSLv23(unsigned char *to, int tlen,

unsigned char *f, int fl);

int RSA_padding_check_SSLv23(unsigned char *to, int tlen,

unsigned char *f, int fl, int rsa_len);

int RSA_padding_add_none(unsigned char *to, int tlen,

unsigned char *f, int fl);

int RSA_padding_check_none(unsigned char *to, int tlen,

unsigned char *f, int fl, int rsa_len);
DESCRIPTION
The RSA_padding_xxx_xxx() functions are called from the RSA encrypt, decrypt, sign and verify
functions. Normally they should not be called from application programs.
However, they can also be called directly to implement padding for other asymmetric ciphers.
RSA_padding_add_PKCS1_OAEP() and RSA_padding_check_PKCS1_OAEP() may be used in an
application combined with RSA_NO_PADDING in order to implement OAEP with an encoding
parameter.
RSA_padding_add_xxx() encodes fl bytes from f so as to fit into tlen bytes and stores the result at to.
An error occurs if fl does not meet the size requirements of the encoding method.
The following encoding methods are implemented:

PKCS1_type_1
PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures
PKCS1_type_2
PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2)
PKCS1_OAEP
PKCS #1 v2.0 EME-OAEP
SSLv23

208 05 July 2003

Crypto Library RSA asymmetric encryption padding

PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification

none
simply copy the data

The random number generator must be seeded prior to calling RSA_padding_add_xxx().

RSA_padding_check_xxx() verifies that the fl bytes at f contain a valid encoding for a rsa_len byte
RSA key in the respective encoding method and stores the recovered data of at most tlen bytes (for
RSA_NO_PADDING: of size tlen) at to.
For RSA_padding_xxx_OAEP(), p points to the encoding parameter of length pl. p may be NULL if pl
is 0.
RETURN VALUES
The RSA_padding_add_xxx() functions return 1 on success, 0 on error. The RSA_padding_check_xxx()
functions return the length of the recovered data, -1 on error. Error codes can be obtained by calling
ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
RSA_public_encrypt(3)|RSA_public_encrypt(3), RSA_private_decrypt(3)|RSA_private_decrypt(3),
RSA_sign(3)|RSA_sign(3), RSA_verify(3)|RSA_verify(3)
HISTORY
RSA_padding_add_PKCS1_type_1(), RSA_padding_check_PKCS1_type_1(),
RSA_padding_add_PKCS1_type_2(), RSA_padding_check_PKCS1_type_2(),
RSA_padding_add_SSLv23(), RSA_padding_check_SSLv23(), RSA_padding_add_none() and
RSA_padding_check_none() appeared in SSLeay 0.9.0.
RSA_padding_add_PKCS1_OAEP() and RSA_padding_check_PKCS1_OAEP() were added in
OpenSSL 0.9.2b.

05 July 2003 209

RSA print cryptographic parameters Crypto Library

RSA print cryptographic parameters

RSA_print, RSA_print_fp, DSAparams_print, DSAparams_print_fp, DSA_print, DSA_print_fp,
DHparams_print, DHparams_print_fp - print cryptographic parameters
SYNOPSIS
#include <openssl/rsa.h>

int RSA_print(BIO *bp, RSA *x, int offset);

int RSA_print_fp(FILE *fp, RSA *x, int offset);

#include <openssl/dsa.h>

int DSAparams_print(BIO *bp, DSA *x);

int DSAparams_print_fp(FILE *fp, DSA *x);
int DSA_print(BIO *bp, DSA *x, int offset);
int DSA_print_fp(FILE *fp, DSA *x, int offset);

#include <openssl/dh.h>

int DHparams_print(BIO *bp, DH *x);

int DHparams_print_fp(FILE *fp, DH *x);
DESCRIPTION
A human-readable hexadecimal output of the components of the RSA key, DSA parameters or key or
DH parameters is printed to bp or fp.
The output lines are indented by offset spaces.
RETURN VALUES
These functions return 1 on success, 0 on error.
SEE ALSO
dh(3)|dh(3), dsa(3)|dsa(3), rsa(3)|rsa(3), BN_bn2bin(3)|BN_bn2bin(3)
HISTORY
RSA_print(), RSA_print_fp(), DSA_print(), DSA_print_fp(), DH_print(), DH_print_fp() are available in
all versions of SSLeay and OpenSSL. DSAparams_print() and DSAparams_print_pf() were added in
SSLeay 0.8.

210 05 July 2003

Crypto Library RSA low level signature

RSA low level signature

RSA_private_encrypt, RSA_public_decrypt - low level signature operations
SYNOPSIS
#include <openssl/rsa.h>

int RSA_private_encrypt(int flen, unsigned char *from,

unsigned char *to, RSA *rsa, int padding);

int RSA_public_decrypt(int flen, unsigned char *from,

unsigned char *to, RSA *rsa, int padding);
DESCRIPTION
These functions handle RSA signatures at a low level.
RSA_private_encrypt() signs the flen bytes at from (usually a message digest with an algorithm
identifier) using the private key rsa and stores the signature in to. to must point to RSA_size(rsa) bytes
of memory.
padding denotes one of the following modes:

RSA_PKCS1_PADDING
PKCS #1 v1.5 padding. This function does not handle the algorithmIdentifier specified in PKCS
#1. When generating or verifying PKCS #1 signatures, RSA_sign(3)|RSA_sign(3) and
RSA_verify(3)|RSA_verify(3) should be used.
RSA_NO_PADDING
Raw RSA signature. This mode should only be used to implement cryptographically sound
padding modes in the application code. Signing user data directly with RSA is insecure.

RSA_public_decrypt() recovers the message digest from the flen bytes long signature at from using the
signer‘s public key rsa. to must point to a memory section large enough to hold the message digest
(which is smaller than RSA_size(rsa) - 11). padding is the padding mode that was used to sign the data.

RETURN VALUES
RSA_private_encrypt() returns the size of the signature (i.e., RSA_size(rsa)). RSA_public_decrypt()
returns the size of the recovered message digest.
On error, -1 is returned; the error codes can be obtained by ERR_get_error(3)|ERR_get_error(3).
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), rsa(3)|rsa(3), RSA_sign(3)|RSA_sign(3),
RSA_verify(3)|RSA_verify(3)
HISTORY
The padding argument was added in SSLeay 0.8. RSA_NO_PADDING is available since SSLeay 0.9.0.

05 July 2003 211

RSA public key cryptography Crypto Library

RSA public key cryptography

RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography
SYNOPSIS
#include <openssl/rsa.h>

int RSA_public_encrypt(int flen, unsigned char *from,

unsigned char *to, RSA *rsa, int padding);

int RSA_private_decrypt(int flen, unsigned char *from,

unsigned char *to, RSA *rsa, int padding);
DESCRIPTION
RSA_public_encrypt() encrypts the flen bytes at from (usually a session key) using the public key rsa
and stores the ciphertext in to. to must point to RSA_size(rsa) bytes of memory.
padding denotes one of the following modes:

RSA_PKCS1_PADDING
PKCS #1 v1.5 padding. This currently is the most widely used mode.
RSA_PKCS1_OAEP_PADDING
EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty encoding parameter.
This mode is recommended for all new applications.
RSA_SSLV23_PADDING
PKCS #1 v1.5 padding with an SSL-specific modification that denotes that the server is SSL3
capable.
RSA_NO_PADDING
Raw RSA encryption. This mode should only be used to implement cryptographically sound
padding modes in the application code. Encrypting user data directly with RSA is insecure.

flen must be less than RSA_size(rsa) - 11 for the PKCS #1 v1.5 based padding modes, and less than
RSA_size(rsa) - 41 for RSA_PKCS1_OAEP_PADDING. The random number generator must be
seeded prior to calling RSA_public_encrypt().
RSA_private_decrypt() decrypts the flen bytes at from using the private key rsa and stores the plaintext
in to. to must point to a memory section large enough to hold the decrypted data (which is smaller than
RSA_size(rsa)). padding is the padding mode that was used to encrypt the data.
RETURN VALUES
RSA_public_encrypt() returns the size of the encrypted data (i.e., RSA_size(rsa)).
RSA_private_decrypt() returns the size of the recovered plaintext.
On error, -1 is returned; the error codes can be obtained by ERR_get_error(3)|ERR_get_error(3).
CONFORMING TO
SSL, PKCS #1 v2.0
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), rand(3)|rand(3), rsa(3)|rsa(3), RSA_size(3)|RSA_size(3)
HISTORY
The padding argument was added in SSLeay 0.8. RSA_NO_PADDING is available since SSLeay 0.9.0,
OAEP was added in OpenSSL 0.9.2b.

212 05 July 2003

Crypto Library RSA select method

RSA select method

RSA_set_default_method, RSA_get_default_method, RSA_set_method, RSA_get_method,
RSA_PKCS1_SSLeay, RSA_null_method, RSA_flags, RSA_new_method - select RSA method
SYNOPSIS
#include <openssl/rsa.h>

void RSA_set_default_method(const RSA_METHOD *meth);

RSA_METHOD *RSA_get_default_method(void);

int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);

RSA_METHOD *RSA_get_method(const RSA *rsa);

RSA_METHOD *RSA_PKCS1_SSLeay(void);

RSA_METHOD *RSA_null_method(void);

int RSA_flags(const RSA *rsa);

RSA *RSA_new_method(RSA_METHOD *method);

DESCRIPTION
An RSA_METHOD specifies the functions that OpenSSL uses for RSA operations. By modifying the
method, alternative implementations such as hardware accelerators may be used. IMPORTANT: See the
NOTES section for important information about how these RSA API functions are affected by the use of
ENGINE API calls.
Initially, the default RSA_METHOD is the OpenSSL internal implementation, as returned by
RSA_PKCS1_SSLeay().
RSA_set_default_method() makes meth the default method for all RSA structures created later. NB:
This is true only whilst no ENGINE has been set as a default for RSA, so this function is no longer
recommended.
RSA_get_default_method() returns a pointer to the current default RSA_METHOD. However, the
meaningfulness of this result is dependant on whether the ENGINE API is being used, so this function is
no longer recommended.
RSA_set_method() selects meth to perform all operations using the key rsa. This will replace the
RSA_METHOD used by the RSA key and if the previous method was supplied by an ENGINE, the
handle to that ENGINE will be released during the change. It is possible to have RSA keys that only
work with certain RSA_METHOD implementations (eg. from an ENGINE module that supports
embedded hardware-protected keys), and in such cases attempting to change the RSA_METHOD for the
key can have unexpected results.
RSA_get_method() returns a pointer to the RSA_METHOD being used by rsa. This method may or may
not be supplied by an ENGINE implementation, but if it is, the return value can only be guaranteed to be
valid as long as the RSA key itself is valid and does not have its implementation changed by
RSA_set_method().
RSA_flags() returns the flags that are set for rsa‘s current RSA_METHOD. See the BUGS section.
RSA_new_method() allocates and initializes an RSA structure so that engine will be used for the RSA
operations. If engine is NULL, the default ENGINE for RSA operations is used, and if no default
ENGINE is set, the RSA_METHOD controlled by RSA_set_default_method() is used.
RSA_flags() returns the flags that are set for rsa‘s current method.
RSA_new_method() allocates and initializes an RSA structure so that method will be used for the RSA
operations. If method is NULL, the default method is used.
THE RSA_METHOD STRUCTURE
typedef struct rsa_meth_st
{
/* name of the implementation */
const char *name;

05 July 2003 213

RSA select method Crypto Library

/* encrypt */
int (*rsa_pub_enc)(int flen, unsigned char *from,
unsigned char *to, RSA *rsa, int padding);

/* verify arbitrary data */

int (*rsa_pub_dec)(int flen, unsigned char *from,
unsigned char *to, RSA *rsa, int padding);

/* sign arbitrary data */

int (*rsa_priv_enc)(int flen, unsigned char *from,
unsigned char *to, RSA *rsa, int padding);

/* decrypt */
int (*rsa_priv_dec)(int flen, unsigned char *from,
unsigned char *to, RSA *rsa, int padding);

/* compute r0 = r0 ^ I mod rsa->n (May be NULL for some

implementations) */
int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);

/* compute r = a ^ p mod m (May be NULL for some implementations) */

int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);

/* called at RSA_new */
int (*init)(RSA *rsa);

/* called at RSA_free */
int (*finish)(RSA *rsa);

/* RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key

* operations, even if p,q,dmp1,dmq1,iqmp
* are NULL
* RSA_FLAG_SIGN_VER - enable rsa_sign and rsa_verify
* RSA_METHOD_FLAG_NO_CHECK - don’t check pub/private match
*/
int flags;

char *app_data; /* ?? */

/* sign. For backward compatibility, this is used only

* if (flags & RSA_FLAG_SIGN_VER)
*/
int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len,
unsigned char *sigret, unsigned int *siglen, RSA *rsa);

/* verify. For backward compatibility, this is used only

* if (flags & RSA_FLAG_SIGN_VER)
*/
int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len,
unsigned char *sigbuf, unsigned int siglen, RSA *rsa);

} RSA_METHOD;
RETURN VALUES
RSA_PKCS1_SSLeay(), RSA_PKCS1_null_method(), RSA_get_default_method() and
RSA_get_method() return pointers to the respective RSA_METHODs.
RSA_set_default_method() returns no value.

214 05 July 2003

Crypto Library RSA select method

RSA_set_method() returns a pointer to the old RSA_METHOD implementation that was replaced.
However, this return value should probably be ignored because if it was supplied by an ENGINE, the
pointer could be invalidated at any time if the ENGINE is unloaded (in fact it could be unloaded as a
result of the RSA_set_method() function releasing its handle to the ENGINE). For this reason, the return
type may be replaced with a void declaration in a future release.
RSA_new_method() returns NULL and sets an error code that can be obtained by
ERR_get_error(3)|ERR_get_error(3) if the allocation fails. Otherwise it returns a pointer to the newly
allocated structure.
NOTES
As of version 0.9.7, RSA_METHOD implementations are grouped together with other algorithmic APIs
(eg. DSA_METHOD, EVP_CIPHER, etc) into ENGINE modules. If a default ENGINE is specified for
RSA functionality using an ENGINE API function, that will override any RSA defaults set using the
RSA API (ie. RSA_set_default_method()). For this reason, the ENGINE API is the recommended way
to control default implementations for use in RSA and other cryptographic algorithms.
BUGS
The behaviour of RSA_flags() is a mis-feature that is left as-is for now to avoid creating compatibility
problems. RSA functionality, such as the encryption functions, are controlled by the flags value in the
RSA key itself, not by the flags value in the RSA_METHOD attached to the RSA key (which is what
this function returns). If the flags element of an RSA key is changed, the changes will be honoured by
RSA functionality but will not be reflected in the return value of the RSA_flags() function - in effect
RSA_flags() behaves more like an RSA_default_flags() function (which does not currently exist).
SEE ALSO
rsa(3)|rsa(3), RSA_new(3)|RSA_new(3)
HISTORY
RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8.
RSA_get_default_method(), RSA_set_method() and RSA_get_method() as well as the rsa_sign and
rsa_verify components of RSA_METHOD were added in OpenSSL 0.9.4.
RSA_set_default_openssl_method() and RSA_get_default_openssl_method() replaced
RSA_set_default_method() and RSA_get_default_method() respectively, and RSA_set_method() and
RSA_new_method() were altered to use ENGINEs rather than RSA_METHODs during development
of the engine version of OpenSSL 0.9.6. For 0.9.7, the handling of defaults in the ENGINE API was
restructured so that this change was reversed, and behaviour of the other functions resembled more
closely the previous behaviour. The behaviour of defaults in the ENGINE API now transparently
overrides the behaviour of defaults in the RSA API without requiring changing these function
prototypes.

05 July 2003 215

RSA signatures Crypto Library

RSA signatures
RSA_sign, RSA_verify - RSA signatures
SYNOPSIS
#include <openssl/rsa.h>

int RSA_sign(int type, unsigned char *m, unsigned int m_len,

unsigned char *sigret, unsigned int *siglen, RSA *rsa);

int RSA_verify(int type, unsigned char *m, unsigned int m_len,

unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
DESCRIPTION
RSA_sign() signs the message digest m of size m_len using the private key rsa as specified in PKCS #1
v2.0. It stores the signature in sigret and the signature size in siglen. sigret must point to RSA_size(rsa)
bytes of memory.
type denotes the message digest algorithm that was used to generate m. It usually is one of NID_sha1,
NID_ripemd160 and NID_md5; see objects(3)|objects(3) for details. If type is NID_md5_sha1, an
SSL signature (MD5 and SHA1 message digests with PKCS #1 padding and no algorithm identifier) is
created.
RSA_verify() verifies that the signature sigbuf of size siglen matches a given message digest m of size
m_len. type denotes the message digest algorithm that was used to generate the signature. rsa is the
signer‘s public key.
RETURN VALUES
RSA_sign() returns 1 on success, 0 otherwise. RSA_verify() returns 1 on successful verification, 0
otherwise.
The error codes can be obtained by ERR_get_error(3)|ERR_get_error(3).
BUGS
Certain signatures with an improper algorithm identifier are accepted for compatibility with SSLeay
0.4.5 :-)
CONFORMING TO
SSL, PKCS #1 v2.0
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), objects(3)|objects(3), rsa(3)|rsa(3),
RSA_private_encrypt(3)|RSA_private_encrypt(3), RSA_public_decrypt(3)|RSA_public_decrypt(3)
HISTORY
RSA_sign() and RSA_verify() are available in all versions of SSLeay and OpenSSL.

216 05 July 2003

Crypto Library RSA ASN1 signatures

RSA ASN1 signatures

RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA ASN1 signatures
SYNOPSIS
#include <openssl/rsa.h>

int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m,

unsigned int m_len, unsigned char *sigret, unsigned int *siglen,
RSA *rsa);

int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m,

unsigned int m_len, unsigned char *sigbuf, unsigned int siglen,
RSA *rsa);
DESCRIPTION
RSA_sign_ASN1_OCTET_STRING() signs the octet string m of size m_len using the private key rsa
represented in DER using PKCS #1 padding. It stores the signature in sigret and the signature size in
siglen. sigret must point to RSA_size(rsa) bytes of memory.
dummy is ignored.
The random number generator must be seeded prior to calling RSA_sign_ASN1_OCTET_STRING().
RSA_verify_ASN1_OCTET_STRING() verifies that the signature sigbuf of size siglen is the DER
representation of a given octet string m of size m_len. dummy is ignored. rsa is the signer‘s public key.
RETURN VALUES
RSA_sign_ASN1_OCTET_STRING() returns 1 on success, 0 otherwise.
RSA_verify_ASN1_OCTET_STRING() returns 1 on successful verification, 0 otherwise.
The error codes can be obtained by ERR_get_error(3)|ERR_get_error(3).
BUGS
These functions serve no recognizable purpose.
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), objects(3)|objects(3), rand(3)|rand(3), rsa(3)|rsa(3),
RSA_sign(3)|RSA_sign(3), RSA_verify(3)|RSA_verify(3)
HISTORY
RSA_sign_ASN1_OCTET_STRING() and RSA_verify_ASN1_OCTET_STRING() were added in
SSLeay 0.8.

05 July 2003 217

RSA size Crypto Library

RSA size
RSA_size - get RSA modulus size
SYNOPSIS
#include <openssl/rsa.h>

int RSA_size(const RSA *rsa);

DESCRIPTION
This function returns the RSA modulus size in bytes. It can be used to determine how much memory
must be allocated for an RSA encrypted value.
rsa-n must not be NULL.
RETURN VALUE
The size in bytes.
SEE ALSO
rsa(3)|rsa(3)
HISTORY
RSA_size() is available in all versions of SSLeay and OpenSSL.

218 05 July 2003

Crypto Library SHA Secure Hash Algorithm

SHA Secure Hash Algorithm

SHA1, SHA1_Init, SHA1_Update, SHA1_Final - Secure Hash Algorithm
SYNOPSIS
#include <openssl/sha.h>

unsigned char *SHA1(const unsigned char *d, unsigned long n,

unsigned char *md);

void SHA1_Init(SHA_CTX *c);

void SHA1_Update(SHA_CTX *c, const void *data,
unsigned long len);
void SHA1_Final(unsigned char *md, SHA_CTX *c);
DESCRIPTION
SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a 160 bit output.
SHA1() computes the SHA-1 message digest of the n bytes at d and places it in md (which must have
space for SHA_DIGEST_LENGTH == 20 bytes of output). If md is NULL, the digest is placed in a
static array.
The following functions may be used if the message is not completely stored in memory:
SHA1_Init() initializes a SHA_CTX structure.
SHA1_Update() can be called repeatedly with chunks of the message to be hashed (len bytes at data).
SHA1_Final() places the message digest in md, which must have space for SHA_DIGEST_LENGTH
== 20 bytes of output, and erases the SHA_CTX.
Applications should use the higher level functions EVP_DigestInit(3)|EVP_DigestInit(3) etc. instead of
calling the hash functions directly.
The predecessor of SHA-1, SHA, is also implemented, but it should be used only when backward
compatibility is required.
RETURN VALUES
SHA1() returns a pointer to the hash value.
SHA1_Init(), SHA1_Update() and SHA1_Final() do not return values.
CONFORMING TO
SHA: US Federal Information Processing Standard FIPS PUB 180 (Secure Hash Standard), SHA-1: US
Federal Information Processing Standard FIPS PUB 180-1 (Secure Hash Standard), ANSI X9.30
SEE ALSO
ripemd(3)|ripemd(3), hmac(3)|hmac(3), EVP_DigestInit(3)|EVP_DigestInit(3)
HISTORY
SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all versions of SSLeay and
OpenSSL.

05 July 2003 219

SMIME parse Crypto Library

SMIME parse
SMIME_read_PKCS7 - parse S/MIME message.
SYNOPSIS
PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont);
DESCRIPTION
SMIME_read_PKCS7() parses a message in S/MIME format.
in is a BIO to read the message from.
If cleartext signing is used then the content is saved in a memory bio which is written to *bcont,
otherwise *bcont is set to NULL.
The parsed PKCS#7 structure is returned or NULL if an error occurred.
NOTES
If *bcont is not NULL then the message is clear text signed. *bcont can then be passed to
PKCS7_verify() with the PKCS7_DETACHED flag set.
Otherwise the type of the returned structure can be determined using PKCS7_type().
To support future functionality if bcont is not NULL *bcont should be initialized to NULL. For
example:
BIO *cont = NULL;
PKCS7 *p7;

p7 = SMIME_read_PKCS7(in, &cont);
BUGS
The MIME parser used by SMIME_read_PKCS7() is somewhat primitive. While it will handle most
S/MIME messages more complex compound formats may not work.
The parser assumes that the PKCS7 structure is always base64 encoded and will not handle the case
where it is in binary format or uses quoted printable format.
The use of a memory BIO to hold the signed content limits the size of message which can be processed
due to memory restraints: a streaming single pass option should be available.
RETURN VALUES
SMIME_read_PKCS7() returns a valid PKCS7 structure or NULL is an error occurred. The error can be
obtained from ERR_get_error(3).
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), PKCS7_type(3)|PKCS7_type(3)
SMIME_read_PKCS7(3)|SMIME_read_PKCS7(3), PKCS7_sign(3)|PKCS7_sign(3),
PKCS7_verify(3)|PKCS7_verify(3), PKCS7_encrypt(3)|PKCS7_encrypt(3)
PKCS7_decrypt(3)|PKCS7_decrypt(3)
HISTORY
SMIME_read_PKCS7() was added to OpenSSL 0.9.5

220 05 July 2003

Crypto Library SMIME_write_PKCS7

SMIME_write_PKCS7
SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format.
SYNOPSIS
int SMIME_write_PKCS7(BIO *out, PKCS7 *p7, BIO *data, int flags);
DESCRIPTION
SMIME_write_PKCS7() adds the appropriate MIME headers to a PKCS#7 structure to produce an
S/MIME message.
out is the BIO to write the data to. p7 is the appropriate PKCS7 structure. If cleartext signing
(multipart/signed) is being used then the signed data must be supplied in the data argument. flags is an
optional set of flags.
NOTES
The following flags can be passed in the flags parameter.
If PKCS7_DETACHED is set then cleartext signing will be used, this option only makes sense for
signedData where PKCS7_DETACHED is also set when PKCS7_sign() is also called.
If the PKCS7_TEXT flag is set MIME headers for type text/plain are added to the content, this only
makes sense if PKCS7_DETACHED is also set.
If cleartext signing is being used then the data must be read twice: once to compute the signature in
PKCS7_sign() and once to output the S/MIME message.
BUGS
SMIME_write_PKCS7() always base64 encodes PKCS#7 structures, there should be an option to
disable this.
There should really be a way to produce cleartext signing using only a single pass of the data.
RETURN VALUES
SMIME_write_PKCS7() returns 1 for success or 0 for failure.
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), PKCS7_sign(3)|PKCS7_sign(3),
PKCS7_verify(3)|PKCS7_verify(3), PKCS7_encrypt(3)|PKCS7_encrypt(3)
PKCS7_decrypt(3)|PKCS7_decrypt(3)
HISTORY
SMIME_write_PKCS7() was added to OpenSSL 0.9.5

05 July 2003 221

OpenSSL thread support Crypto Library

OpenSSL thread support

CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks,
CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback,
CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, CRYPTO_destroy_dynlockid,
CRYPTO_lock - OpenSSL thread support
SYNOPSIS
#include <openssl/crypto.h>

void CRYPTO_set_locking_callback(void (*locking_function)(int mode,

int n, const char *file, int line));

void CRYPTO_set_id_callback(unsigned long (*id_function)(void));

int CRYPTO_num_locks(void);

/* struct CRYPTO_dynlock_value needs to be defined by the user */

struct CRYPTO_dynlock_value;

void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value *

(*dyn_create_function)(char *file, int line));
void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function)
(int mode, struct CRYPTO_dynlock_value *l,
const char *file, int line));
void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function)
(struct CRYPTO_dynlock_value *l, const char *file, int line));

int CRYPTO_get_new_dynlockid(void);

void CRYPTO_destroy_dynlockid(int i);

void CRYPTO_lock(int mode, int n, const char *file, int line);

#define CRYPTO_w_lock(type) \
CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
#define CRYPTO_w_unlock(type) \
CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
#define CRYPTO_r_lock(type) \
CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__)
#define CRYPTO_r_unlock(type) \
CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__)
#define CRYPTO_add(addr,amount,type) \
CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__)
DESCRIPTION
OpenSSL can safely be used in multi-threaded applications provided that at least two callback functions
are set.
locking_function(int mode, int n, const char *file, int line) is needed to perform locking on shared data
structures. (Note that OpenSSL uses a number of global data structures that will be implicitly shared
whenever multiple threads use OpenSSL.) Multi-threaded applications will crash at random if it is not
set.
locking_function() must be able to handle up to CRYPTO_num_locks() different mutex locks. It sets the
n-th lock if mode & CRYPTO_LOCK, and releases it otherwise.
file and line are the file number of the function setting the lock. They can be useful for debugging.
id_function(void) is a function that returns a thread ID. It is not needed on Windows nor on platforms
where getpid() returns a different ID for each thread (most notably Linux).
Additionally, OpenSSL supports dynamic locks, and sometimes, some parts of OpenSSL need it for
better performance. To enable this, the following is required:

222 05 July 2003

Crypto Library OpenSSL thread support

Three additional callback function, dyn_create_function, dyn_lock_function and

dyn_destroy_function.
A structure
struct defined with the has
CRYPTO_dynlock_value datatothat
be each lock
defined to needs
containtowhatever
handle. structure is needed to handle
locks.
dyn_create_function(const char *file, int line) is needed to create a lock. Multi-threaded applications
might crash at random if it is not set.
dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line) is needed to perform
locking off dynamic lock numbered n. Multi-threaded applications might crash at random if it is not set.
dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is needed to destroy the lock l.
Multi-threaded applications might crash at random if it is not set.
CRYPTO_get_new_dynlockid() is used to create locks. It will call dyn_create_function for the actual
creation.
CRYPTO_destroy_dynlockid() is used to destroy locks. It will call dyn_destroy_function for the actual
destruction.
CRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield describing what should be done
with the lock. n is the number of the lock as returned from CRYPTO_get_new_dynlockid(). mode can
be combined from the following values. These values are pairwise exclusive, with undefined behaviour
if misused (for example, CRYPTO_READ and CRYPTO_WRITE should not be used together):
CRYPTO_LOCK 0x01
CRYPTO_UNLOCK 0x02
CRYPTO_READ 0x04
CRYPTO_WRITE 0x08
RETURN VALUES
CRYPTO_num_locks() returns the required number of locks.
CRYPTO_get_new_dynlockid() returns the index to the newly created lock.
The other functions return no values.
NOTE
You can find out if OpenSSL was configured with thread support:
#define OPENSSL_THREAD_DEFINES
#include <openssl/opensslconf.h>
#if defined(THREADS)
// thread support enabled
#else
// no thread support
#endif

Also, dynamic locks are currently not used internally by OpenSSL, but may do so in the future.
EXAMPLES
crypto/threads/mttest.c shows examples of the callback functions on Solaris, Irix and Win32.
HISTORY
CRYPTO_set_locking_callback() and CRYPTO_set_id_callback() are available in all versions of
SSLeay and OpenSSL. CRYPTO_num_locks() was added in OpenSSL 0.9.4. All functions dealing with
dynamic locks were added in OpenSSL 0.9.5b-dev.
SEE ALSO
crypto(3)|crypto(3)

05 July 2003 223

UI New User Interface Crypto Library

UI New User Interface

UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string, UI_add_verify_string,
UI_dup_verify_string, UI_add_input_boolean, UI_dup_input_boolean, UI_add_info_string,
UI_dup_info_string, UI_add_error_string, UI_dup_error_string, UI_construct_prompt
UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process, UI_ctrl, UI_set_default_method,
UI_get_default_method, UI_get_method, UI_set_method, UI_OpenSSL, ERR_load_UI_strings - New
User Interface
SYNOPSIS
#include <openssl/ui.h>

typedef struct ui_st UI;

typedef struct ui_method_st UI_METHOD;

UI *UI_new(void);
UI *UI_new_method(const UI_METHOD *method);
void UI_free(UI *ui);

int UI_add_input_string(UI *ui, const char *prompt, int flags,

char *result_buf, int minsize, int maxsize);
int UI_dup_input_string(UI *ui, const char *prompt, int flags,
char *result_buf, int minsize, int maxsize);
int UI_add_verify_string(UI *ui, const char *prompt, int flags,
char *result_buf, int minsize, int maxsize, const char *test_buf);
int UI_dup_verify_string(UI *ui, const char *prompt, int flags,
char *result_buf, int minsize, int maxsize, const char *test_buf);
int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc,
const char *ok_chars, const char *cancel_chars,
int flags, char *result_buf);
int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc,
const char *ok_chars, const char *cancel_chars,
int flags, char *result_buf);
int UI_add_info_string(UI *ui, const char *text);
int UI_dup_info_string(UI *ui, const char *text);
int UI_add_error_string(UI *ui, const char *text);
int UI_dup_error_string(UI *ui, const char *text);

/* These are the possible flags. They can be or’ed together. */

#define UI_INPUT_FLAG_ECHO 0x01
#define UI_INPUT_FLAG_DEFAULT_PWD 0x02

char *UI_construct_prompt(UI *ui_method,

const char *object_desc, const char *object_name);

void *UI_add_user_data(UI *ui, void *user_data);

void *UI_get0_user_data(UI *ui);

const char *UI_get0_result(UI *ui, int i);

int UI_process(UI *ui);

int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)());
#define UI_CTRL_PRINT_ERRORS 1
#define UI_CTRL_IS_REDOABLE 2

void UI_set_default_method(const UI_METHOD *meth);

const UI_METHOD *UI_get_default_method(void);
const UI_METHOD *UI_get_method(UI *ui);
const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth);

224 05 July 2003

Crypto Library UI New User Interface

UI_METHOD *UI_OpenSSL(void);
DESCRIPTION
UI stands for User Interface, and is general purpose set of routines to prompt the user for text-based
information. Through user-written methods (see ui_create(3)|ui_create(3)), prompting can be done in
any way imaginable, be it plain text prompting, through dialog boxes or from a cell phone.
All the functions work through a context of the type UI. This context contains all the information
needed to prompt correctly as well as a reference to a UI_METHOD, which is an ordered vector of
functions that carry out the actual prompting.
The first thing to do is to create a UI with UI_new() or UI_new_method(), then add information to it
with the UI_add or UI_dup functions. Also, user-defined random data can be passed down to the
underlying method through calls to UI_add_user_data. The default UI method doesn‘t care about these
data, but other methods might. Finally, use UI_process() to actually perform the prompting and
UI_get0_result() to find the result to the prompt.
A UI can contain more than one prompt, which are performed in the given sequence. Each prompt gets
an index number which is returned by the UI_add and UI_dup functions, and has to be used to get the
corresponding result with UI_get0_result().
The functions are as follows:
UI_new() creates a new UI using the default UI method. When done with this UI, it should be freed
using UI_free().
UI_new_method() creates a new UI using the given UI method. When done with this UI, it should be
freed using UI_free().
UI_OpenSSL() returns the built-in UI method (note: not the default one, since the default can be
changed. See further on). This method is the most machine/OS dependent part of OpenSSL and
normally generates the most problems when porting.
UI_free() removes a UI from memory, along with all other pieces of memory that‘s connected to it, like
duplicated input strings, results and others.
UI_add_input_string() and UI_add_verify_string() add a prompt to the UI, as well as flags and a result
buffer and the desired minimum and maximum sizes of the result. The given information is used to
prompt for information, for example a password, and to verify a password (i.e. having the user enter it
twice and check that the same string was entered twice). UI_add_verify_string() takes and extra
argument that should be a pointer to the result buffer of the input string that it‘s supposed to verify, or
verification will fail.
UI_add_input_boolean() adds a prompt to the UI that‘s supposed to be answered in a boolean way, with
a single character for yes and a different character for no. A set of characters that can be used to cancel
the prompt is given as well. The prompt itself is really divided in two, one part being the descriptive text
(given through the prompt argument) and one describing the possible answers (given through the
action_desc argument).
UI_add_info_string() and UI_add_error_string() add strings that are shown at the same time as the
prompt for extra information or to show an error string. The difference between the two is only
conceptual. With the builtin method, there‘s no technical difference between them. Other methods may
make a difference between them, however.
The flags currently supported are UI_INPUT_FLAG_ECHO, which is relevant for
UI_add_input_string() and will have the users response be echoed (when prompting for a password, this
flag should obviously not be used, and UI_INPUT_FLAG_DEFAULT_PWD, which means that a
default password of some sort will be used (completely depending on the application and the UI
method).
UI_dup_input_string(), UI_dup_verify_string(), UI_dup_input_boolean(), UI_dup_info_string() and
UI_dup_error_string() are basically the same as their UI_add counterparts, except that they make their
own copies of all strings.
UI_construct_prompt() is a helper function that can be used to create a prompt from two pieces of
information: an description and a name. The default constructor (if there is none provided by the method
used) creates a string "Enter description for name:". With the description "pass phrase" and the file
name "foo.key", that becomes "Enter pass phrase for foo.key:". Other methods may create whatever
string and may include encodings that will be processed by the other method functions.
UI_add_user_data() adds a piece of memory for the method to use at any time. The builtin UI method
doesn‘t care about this info. Note that several calls to this function doesn‘t add data, it replaces the
previous blob with the one given as argument.

05 July 2003 225

UI New User Interface Crypto Library

UI_get0_user_data() retrieves the data that has last been given to the UI with UI_add_user_data().
UI_get0_result() returns a pointer to the result buffer associated with the information indexed by i.
UI_process() goes through the information given so far, does all the printing and prompting and returns.
UI_ctrl() adds extra control for the application author. For now, it understands two commands:
UI_CTRL_PRINT_ERRORS, which makes UI_process() print the OpenSSL error stack as part of
processing the UI, and UI_CTRL_IS_REDOABLE, which returns a flag saying if the used UI can be
used again or not.
UI_set_default_method() changes the default UI method to the one given.
UI_get_default_method() returns a pointer to the current default UI method.
UI_get_method() returns the UI method associated with a given UI.
UI_set_method() changes the UI method associated with a given UI.
SEE ALSO
ui_create(3)|ui_create(3), ui_compat(3)|ui_compat(3)
HISTORY
The UI section was first introduced in OpenSSL 0.9.7.
AUTHOR
Richard Levitte ([email protected]) for the OpenSSL project (http://www.openssl.org).

226 05 July 2003

Crypto Library Compatibility user interface

Compatibility user interface

des_read_password, des_read_2passwords, des_read_pw_string, des_read_pw - Compatibility user
interface functions
SYNOPSIS
int des_read_password(DES_cblock *key,const char *prompt,int verify);
int des_read_2passwords(DES_cblock *key1,DES_cblock *key2,
const char *prompt,int verify);

int des_read_pw_string(char *buf,int length,const char *prompt,int verify);

int des_read_pw(char *buf,char *buff,int size,const char *prompt,int verify);
DESCRIPTION
The DES library contained a few routines to prompt for passwords. These aren‘t necessarely dependent
on DES, and have therefore become part of the UI compatibility library.
des_read_pw() writes the string specified by prompt to standard output turns echo off and reads an input
string from the terminal. The string is returned in buf, which must have spac for at least size bytes. If
verify is set, the user is asked for the password twice and unless the two copies match, an error is
returned. The second password is stored in buff, which must therefore also be at least size bytes. A
return code of -1 indicates a system error, 1 failure due to use interaction, and 0 is success. All other
functions described here use des_read_pw() to do the work.
des_read_pw_string() is a variant of des_read_pw() that provides a buffer for you if verify is set.
des_read_password() calls des_read_pw() and converts the password to a DES key by calling
DES_string_to_key(); des_read_2password() operates in the same way as des_read_password() except
that it generates two keys by using the DES_string_to_2key() function.
NOTES
des_read_pw_string() is available in the MIT Kerberos library as well, and is also available under the
name EVP_read_pw_string().
SEE ALSO
ui(3)|ui(3), ui_create(3)|ui_create(3)
AUTHOR
Richard Levitte ([email protected]) for the OpenSSL project (http://www.openssl.org).

05 July 2003 227

X509_NAME modification Crypto Library

X509_NAME modification
X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ,
X509_NAME_add_entry_by_NID, X509_NAME_add_entry, X509_NAME_delete_entry -
X509_NAME modification functions
SYNOPSIS
int X509_NAME_add_entry_by_txt(X509_NAME *name, char *field, int type,
int X509_NAME_add_entry_by_OBJ(X509_NAME
unsigned
*name,
charASN1_OBJECT
*bytes, int len, int
*obj,
loc,int
inttype,
set);
int X509_NAME_add_entry_by_NID(X509_NAME
unsigned
*name,
charint
*bytes,
nid, int
inttype,
len, int loc, int set);
int X509_NAME_add_entry(X509_NAME *name,X509_NAME_ENTRY
unsigned char *bytes, int len,
*ne,
int int
loc,loc,
int int
set);
set);
X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc);
DESCRIPTION
X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ() and
X509_NAME_add_entry_by_NID() add a field whose name is defined by a string field, an object obj or
a NID nid respectively. The field value to be added is in bytes of length len. If len is -1 then the field
length is calculated internally using strlen(bytes).
The type of field is determined by type which can either be a definition of the type of bytes (such as
MBSTRING_ASC) or a standard ASN1 type (such as V_ASN1_IA5STRING). The new entry is added
to a position determined by loc and set.
X509_NAME_add_entry() adds a copy of X509_NAME_ENTRY structure ne to name. The new entry
is added to a position determined by loc and set. Since a copy of ne is added ne must be freed up after
the call.
X509_NAME_delete_entry() deletes an entry from name at position loc. The deleted entry is returned
and must be freed up.
NOTES
The use of string types such as MBSTRING_ASC or MBSTRING_UTF8 is strongly recommened for
the type parameter. This allows the internal code to correctly determine the type of the field and to apply
length checks according to the relevant standards. This is done using ASN1_STRING_set_by_NID().
If instead an ASN1 type is used no checks are performed and the supplied data in bytes is used directly.
In X509_NAME_add_entry_by_txt() the field string represents the field name using OBJ_txt2obj(field,
0).
The loc and set parameters determine where a new entry should be added. For almost all applications loc
can be set to -1 and set to 0. This adds a new entry to the end of name as a single valued
RelativeDistinguishedName (RDN).
loc actually determines the index where the new entry is inserted: if it is -1 it is appended.
set determines how the new type is added. If it is zero a new RDN is created.
If set is -1 or 1 it is added to the previous or next RDN structure respectively. This will then be a
multivalued RDN: since multivalues RDNs are very seldom used set is almost always set to zero.
EXAMPLES
Create an X509_NAME structure:
"C=UK, O=Disorganized Organization, CN=Joe Bloggs"
X509_NAME *nm;
nm = X509_NAME_new();
if (nm == NULL)
/* Some error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"C", "UK", -1, -1, 0))
/* Error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"O", "Disorganized Organization", -1, -1, 0))
/* Error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"CN", "Joe Bloggs", -1, -1, 0))
/* Error */

228 05 July 2003

Crypto Library X509_NAME modification

RETURN VALUES
X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(),
X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for success of 0 if an error
occurred.
X509_NAME_delete_entry() returns either the deleted X509_NAME_ENTRY structure of NULL if an
error occurred.
BUGS
type can still be set to V_ASN1_APP_CHOOSE to use a different algorithm to determine field types.
Since this form does not understand multicharacter types, performs no length checks and can result in
invalid field types its use is strongly discouraged.
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), d2i_X509_NAME(3)|d2i_X509_NAME(3)
HISTORY

05 July 2003 229

X509_NAME_ENTRY utility Crypto Library

X509_NAME_ENTRY utility
X509_NAME_ENTRY_get_object, X509_NAME_ENTRY_get_data,
X509_NAME_ENTRY_set_object, X509_NAME_ENTRY_set_data,
X509_NAME_ENTRY_create_by_txt, X509_NAME_ENTRY_create_by_NID,
X509_NAME_ENTRY_create_by_OBJ - X509_NAME_ENTRY utility functions
SYNOPSIS
ASN1_OBJECT * X509_NAME_ENTRY_get_object(X509_NAME_ENTRY *ne); ASN1_STRING *
X509_NAME_ENTRY_get_data(X509_NAME_ENTRY *ne);
int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *ne, ASN1_OBJECT *obj); int
X509_NAME_ENTRY_set_data(X509_NAME_ENTRY *ne, int type,
X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt(X509_NAME_ENTRY
unsigned char *bytes, int len); **ne,
char *field, int type,
X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_NID(X509_NAME_ENTRY
unsigned char *bytes, int len); **ne,
int nid, int type,unsigned char *bytes,
X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ(X509_NAME_ENTRY
int len); **ne,
ASN1_OBJECT *obj, int type,
unsigned char *bytes, int len);
DESCRIPTION
X509_NAME_ENTRY_get_object() retrieves the field name of ne in and ASN1_OBJECT structure.
X509_NAME_ENTRY_get_data() retrieves the field value of ne in and ASN1_STRING structure.
X509_NAME_ENTRY_set_object() sets the field name of ne to obj.
X509_NAME_ENTRY_set_data() sets the field value of ne to string type type and value determined by
bytes and len.
X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID() and
X509_NAME_ENTRY_create_by_OBJ() create and return an X509_NAME_ENTRY structure.
NOTES
X509_NAME_ENTRY_get_object() and X509_NAME_ENTRY_get_data() can be used to examine an
X509_NAME_ENTRY function as returned by X509_NAME_get_entry() for example.
X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID(), and
X509_NAME_ENTRY_create_by_OBJ() create and return an
X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_OBJ(),
X509_NAME_ENTRY_create_by_NID() and X509_NAME_ENTRY_set_data() are seldom used in
practice because X509_NAME_ENTRY structures are almost always part of X509_NAME structures
and the corresponding X509_NAME functions are typically used to create and add new entries in a
single operation.
The arguments of these functions support similar options to the similarly named ones of the
corresponding X509_NAME functions such as X509_NAME_add_entry_by_txt(). So for example type
can be set to MBSTRING_ASC but in the case of X509_set_data() the field name must be set first so
the relevant field information can be looked up internally.
RETURN VALUES
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), d2i_X509_NAME(3)|d2i_X509_NAME(3),
OBJ_nid2obj(3),OBJ_nid2obj(3)
HISTORY
TBA

230 05 July 2003

Crypto Library X509_NAME lookup and enumeration

X509_NAME lookup and enumeration

X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry,
X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ -
X509_NAME lookup and enumeration functions
SYNOPSIS
int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos); int
X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos);
int X509_NAME_entry_count(X509_NAME *name); X509_NAME_ENTRY
*X509_NAME_get_entry(X509_NAME *name, int loc);
int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len); int
X509_NAME_get_text_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj,
char *buf,int len);
DESCRIPTION
These functions allow an X509_NAME structure to be examined. The X509_NAME structure is the
same as the Name type defined in RFC2459 (and elsewhere) and used for example in certificate subject
and issuer names.
X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve the next index
matching nid or obj after lastpos. lastpos should initially be set to -1. If there are no more entries -1 is
returned.
X509_NAME_entry_count() returns the total number of entries in name.
X509_NAME_get_entry() retrieves the X509_NAME_ENTRY from name corresponding to index loc.
Acceptable values for loc run from 0 to (X509_NAME_entry_count(name) - 1). The value returned is an
internal pointer which must not be freed.
X509_NAME_get_text_by_NID(), X509_NAME_get_text_by_OBJ() retrieve the "text" from the first
entry in name which matches nid or obj, if no such entry exists -1 is returned. At most len bytes will be
written and the text written to buf will be null terminated. The length of the output string written is
returned excluding the terminating null. If buf is <NULL> then the amount of space needed in buf
(excluding the final null) is returned.
NOTES
X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are legacy functions which
have various limitations which make them of minimal use in practice. They can only find the first
matching entry and will copy the contents of the field verbatim: this can be highly confusing if the target
is a muticharacter string type like a BMPString or a UTF8String.
For a more general solution X509_NAME_get_index_by_NID() or X509_NAME_get_index_by_OBJ()
should be used followed by X509_NAME_get_entry() on any matching indices and then the various
X509_NAME_ENTRY utility functions on the result.
EXAMPLES
Process all entries:
int i;
X509_NAME_ENTRY *e;

for (i = 0; i < X509_NAME_entry_count(nm); i++)

{
e = X509_NAME_get_entry(nm, i);
/* Do something with e */
}

Process all commonName entries:

int loc;
X509_NAME_ENTRY *e;

loc = -1;
for (;;)
{
lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos);
if (lastpos == -1)

05 July 2003 231

X509_NAME lookup and enumeration Crypto Library

break;
e = X509_NAME_get_entry(nm, lastpos);
/* Do something with e */
}
RETURN VALUES
X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() return the index of the
next matching entry or -1 if not found.
X509_NAME_entry_count() returns the total number of entries.
X509_NAME_get_entry() returns an X509_NAME pointer to the requested entry or NULL if the index
is invalid.
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), d2i_X509_NAME(3)|d2i_X509_NAME(3)
HISTORY
TBA

232 05 July 2003

Crypto Library X509_NAME printing

X509_NAME printing
X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print, X509_NAME_oneline -
X509_NAME printing routines.
SYNOPSIS
#include <openssl/x509.h>

int X509_NAME_print_ex(BIO *out, X509_NAME *nm, int indent,

unsigned long flags);
int X509_NAME_print_ex_fp(FILE *fp, X509_NAME *nm, int indent,
unsigned long flags);
char * X509_NAME_oneline(X509_NAME *a,char *buf,int size);
int X509_NAME_print(BIO *bp, X509_NAME *name, int obase);
DESCRIPTION
X509_NAME_print_ex() prints a human readable version of nm to BIO out. Each line (for multiline
formats) is indented by indent spaces. The output format can be extensively customised by use of the
flags parameter.
X509_NAME_print_ex_fp() is identical to X509_NAME_print_ex() except the output is written to FILE
pointer fp.
X509_NAME_oneline() prints an ASCII version of a to buf. At most size bytes will be written. If buf is
NULL then a buffer is dynamically allocated and returned, otherwise buf is returned.
X509_NAME_print() prints out name to bp indenting each line by obase characters. Multiple lines are
used if the output (including indent) exceeds 80 characters.
NOTES
The functions X509_NAME_oneline() and X509_NAME_print() are legacy functions which produce a
non standard output form, they don‘t handle multi character fields and have various quirks and
inconsistencies. Their use is strongly discouraged in new applications.
Although there are a large number of possible flags for most purposes XN_FLAG_ONELINE,
XN_FLAG_MULTILINE or XN_FLAG_RFC2253 will suffice. As noted on the
ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3) manual page for UTF8 terminals the
ASN1_STRFLAGS_ESC_MSB should be unset: so for example XN_FLAG_ONELINE &
~ASN1_STRFLAGS_ESC_MSB would be used.
The complete set of the flags supported by X509_NAME_print_ex() is listed below.
Several options can be ored together.
The options XN_FLAG_SEP_COMMA_PLUS, XN_FLAG_SEP_CPLUS_SPC,
XN_FLAG_SEP_SPLUS_SPC and XN_FLAG_SEP_MULTILINE determine the field separators to
use. Two distinct separators are used between distinct RelativeDistinguishedName components and
separate values in the same RDN for a multi-valued RDN. Multi-valued RDNs are currently very rare so
the second separator will hardly ever be used.
XN_FLAG_SEP_COMMA_PLUS uses comma and plus as separators.
XN_FLAG_SEP_CPLUS_SPC uses comma and plus with spaces: this is more readable that plain
comma and plus. XN_FLAG_SEP_SPLUS_SPC uses spaced semicolon and plus.
XN_FLAG_SEP_MULTILINE uses spaced newline and plus respectively.
If XN_FLAG_DN_REV is set the whole DN is printed in reversed order.
The fields XN_FLAG_FN_SN, XN_FLAG_FN_LN, XN_FLAG_FN_OID, XN_FLAG_FN_NONE
determine how a field name is displayed. It will use the short name (e.g. CN) the long name (e.g.
commonName) always use OID numerical form (normally OIDs are only used if the field name is not
recognised) and no field name respectively.
If XN_FLAG_SPC_EQ is set then spaces will be placed around the ‘=’ character separating field names
and values.
If XN_FLAG_DUMP_UNKNOWN_FIELDS is set then the encoding of unknown fields is printed
instead of the values.
If XN_FLAG_FN_ALIGN is set then field names are padded to 20 characters: this is only of use for
multiline format.
Additionally all the options supported by ASN1_STRING_print_ex() can be used to control how each
field value is displayed.

05 July 2003 233

X509_NAME printing Crypto Library

In addition a number options can be set for commonly used formats.

XN_FLAG_RFC2253 sets options which produce an output compatible with RFC2253 it is equivalent
to:
ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV
| XN_FLAG_FN_SN| XN_FLAG_DUMP_UNKNOWN_FIELDS

XN_FLAG_ONELINE is a more readable one line format it is the same as:

ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC
| XN_FLAG_SPC_EQ | XN_FLAG_FN_SN
XN_FLAG_MULTILINE is a multiline format is is the same as:
ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE
| XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN
XN_FLAG_COMPAT uses a format identical to X509_NAME_print(): in fact it calls
X509_NAME_print() internally.
SEE ALSO
ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3)
HISTORY
TBA

234 05 July 2003

Crypto Library X509 certificate ASN1 allocation

X509 certificate ASN1 allocation

X509_new, X509_free - X509 certificate ASN1 allocation functions
SYNOPSIS
X509 *X509_new(void);
void X509_free(X509 *a);
DESCRIPTION
The X509 ASN1 allocation routines, allocate and free an X509 structure, which represents an X509
certificate.
X509_new() allocates and initializes a X509 structure.
X509_free() frees up the X509 structure a.
RETURN VALUES
If the allocation fails, X509_new() returns NULL and sets an error code that can be obtained by
ERR_get_error(3)|ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.
X509_free() returns no value.
SEE ALSO
ERR_get_error(3)|ERR_get_error(3), d2i_X509(3)|d2i_X509(3)
HISTORY
X509_new() and X509_free() are available in all versions of SSLeay and OpenSSL.

05 July 2003 235

X509 certificate ASN1 allocation Crypto Library

236 05 July 2003