Newer
Older
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
This last flag is mostly used when reading a password for encryption.
For all of these functions, a NULL callback will call the above mentioned
default callback. This default function does not work under Windows 3.1.
For other machines, it will use an application defined prompt string
(EVP_set_pw_prompt(), which defines a library wide prompt string)
if defined, otherwise it will use it's own PEM password prompt.
It will then call EVP_read_pw_string() to get a password from the console.
If your application wishes to use nice fancy windows to retrieve passwords,
replace this function. The callback should return the number of bytes read
into 'buf'. If the number of bytes <= 0, it is considered an error.
Functions that take this callback are listed below. For the 'read' type
functions, the callback will only be required if the PEM data is encrypted.
For the Write functions, normally a password can be passed in 'kstr', of
'klen' bytes which will be used if the 'enc' cipher is not NULL. If
'kstr' is NULL, the callback will be used to retrieve a password.
int PEM_do_header (EVP_CIPHER_INFO *cipher, unsigned char *data,long *len,
int (*callback)());
char *PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *bp,char **x,int (*cb)());
char *PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)());
int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *bp,char *x,
EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)());
int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,
EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)());
STACK *PEM_X509_INFO_read(FILE *fp, STACK *sk, int (*cb)());
STACK *PEM_X509_INFO_read_bio(BIO *fp, STACK *sk, int (*cb)());
#define PEM_write_RSAPrivateKey(fp,x,enc,kstr,klen,cb)
#define PEM_write_DSAPrivateKey(fp,x,enc,kstr,klen,cb)
#define PEM_write_bio_RSAPrivateKey(bp,x,enc,kstr,klen,cb)
#define PEM_write_bio_DSAPrivateKey(bp,x,enc,kstr,klen,cb)
#define PEM_read_SSL_SESSION(fp,x,cb)
#define PEM_read_X509(fp,x,cb)
#define PEM_read_X509_REQ(fp,x,cb)
#define PEM_read_X509_CRL(fp,x,cb)
#define PEM_read_RSAPrivateKey(fp,x,cb)
#define PEM_read_DSAPrivateKey(fp,x,cb)
#define PEM_read_PrivateKey(fp,x,cb)
#define PEM_read_PKCS7(fp,x,cb)
#define PEM_read_DHparams(fp,x,cb)
#define PEM_read_bio_SSL_SESSION(bp,x,cb)
#define PEM_read_bio_X509(bp,x,cb)
#define PEM_read_bio_X509_REQ(bp,x,cb)
#define PEM_read_bio_X509_CRL(bp,x,cb)
#define PEM_read_bio_RSAPrivateKey(bp,x,cb)
#define PEM_read_bio_DSAPrivateKey(bp,x,cb)
#define PEM_read_bio_PrivateKey(bp,x,cb)
#define PEM_read_bio_PKCS7(bp,x,cb)
#define PEM_read_bio_DHparams(bp,x,cb)
int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());
RSA *d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)());
Now you will notice that macros like
#define PEM_write_X509(fp,x) \
PEM_ASN1_write((int (*)())i2d_X509,PEM_STRING_X509,fp, \
(char *)x, NULL,NULL,0,NULL)
Don't do encryption normally. If you want to PEM encrypt your X509 structure,
either just call PEM_ASN1_write directly or just define your own
macro variant. As you can see, this macro just sets all encryption related
parameters to NULL.
--------------------------
The SSL library.
#define SSL_set_info_callback(ssl,cb)
#define SSL_CTX_set_info_callback(ctx,cb)
void callback(SSL *ssl,int location,int ret)
This callback is called each time around the SSL_connect()/SSL_accept()
state machine. So it will be called each time the SSL protocol progresses.
It is mostly present for use when debugging. When SSL_connect() or
SSL_accept() return, the location flag is SSL_CB_ACCEPT_EXIT or
SSL_CB_CONNECT_EXIT and 'ret' is the value about to be returned.
Have a look at the SSL_CB_* defines in ssl.h. If an info callback is defined
against the SSL_CTX, it is called unless there is one set against the SSL.
Have a look at
void client_info_callback() in apps/s_client() for an example.
Certificate verification.
void SSL_set_verify(SSL *s, int mode, int (*callback) ());
void SSL_CTX_set_verify(SSL_CTX *ctx,int mode,int (*callback)());
This callback is used to help verify client and server X509 certificates.
It is actually passed to X509_cert_verify(), along with the SSL structure
so you have to read about X509_cert_verify() :-). The SSL_CTX version is used
if the SSL version is not defined. X509_cert_verify() is the function used
by the SSL part of the library to verify certificates. This function is
nearly always defined by the application.
void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(),char *arg);
int callback(char *arg,SSL *s,X509 *xs,STACK *cert_chain);
This call is used to replace the SSLeay certificate verification code.
The 'arg' is kept in the SSL_CTX and is passed to the callback.
If the callback returns 0, the certificate is rejected, otherwise it
is accepted. The callback is replacing the X509_cert_verify() call.
This feature is not often used, but if you wished to implement
some totally different certificate authentication system, this 'hook' is
vital.
SSLeay keeps a cache of session-ids against each SSL_CTX. These callbacks can
be used to notify the application when a SSL_SESSION is added to the cache
or to retrieve a SSL_SESSION that is not in the cache from the application.
#define SSL_CTX_sess_set_get_cb(ctx,cb)
SSL_SESSION *callback(SSL *s,char *session_id,int session_id_len,int *copy);
If defined, this callback is called to return the SESSION_ID for the
session-id in 'session_id', of 'session_id_len' bytes. 'copy' is set to 1
if the server is to 'take a copy' of the SSL_SESSION structure. It is 0
if the SSL_SESSION is being 'passed in' so the SSLeay library is now
responsible for 'free()ing' the structure. Basically it is used to indicate
if the reference count on the SSL_SESSION structure needs to be incremented.
#define SSL_CTX_sess_set_new_cb(ctx,cb)
int callback(SSL *s, SSL_SESSION *sess);
When a new connection is established, if the SSL_SESSION is going to be added
to the cache, this callback is called. Return 1 if a 'copy' is required,
otherwise, return 0. This return value just causes the reference count
to be incremented (on return of a 1), this means the application does
not need to worry about incrementing the refernece count (and the
locking that implies in a multi-threaded application).
void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx,int (*cb)());
This sets the SSL password reading function.
It is mostly used for windowing applications
and used by PEM_read_bio_X509() and PEM_read_bio_RSAPrivateKey()
calls inside the SSL library. The only reason this is present is because the
calls to PEM_* functions is hidden in the SSLeay library so you have to
pass in the callback some how.
#define SSL_CTX_set_client_cert_cb(ctx,cb)
int callback(SSL *s,X509 **x509, EVP_PKEY **pkey);
Called when a client certificate is requested but there is not one set
against the SSL_CTX or the SSL. If the callback returns 1, x509 and
pkey need to point to valid data. The library will free these when
required so if the application wants to keep these around, increment
their reference counts. If 0 is returned, no client cert is
available. If -1 is returned, it is assumed that the callback needs
to be called again at a later point in time. SSL_connect will return
-1 and SSL_want_x509_lookup(ssl) returns true. Remember that
application data can be attached to an SSL structure via the
SSL_set_app_data(SSL *ssl,char *data) call.
--------------------------
The X509 library.
int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)(),
int *error,char *arg,STACK *cert_chain);
int verify_callback(int ok,X509 *xs,X509 *xi,int depth,int error,char *arg,
STACK *cert_chain);
X509_cert_verify() is used to authenticate X509 certificates. The 'ctx' holds
the details of the various caches and files used to locate certificates.
'xs' is the certificate to verify and 'cb' is the application callback (more
detail later). 'error' will be set to the error code and 'arg' is passed
to the 'cb' callback. Look at the VERIFY_* defines in crypto/x509/x509.h
When ever X509_cert_verify() makes a 'negative' decision about a
certitificate, the callback is called. If everything checks out, the
callback is called with 'VERIFY_OK' or 'VERIFY_ROOT_OK' (for a self
signed cert that is not the passed certificate).
The callback is passed the X509_cert_verify opinion of the certificate
in 'ok', the certificate in 'xs', the issuer certificate in 'xi',
the 'depth' of the certificate in the verification 'chain', the
VERIFY_* code in 'error' and the argument passed to X509_cert_verify()
in 'arg'. cert_chain is a list of extra certs to use if they are not
in the cache.
The callback can be used to look at the error reason, and then return 0
for an 'error' or '1' for ok. This will override the X509_cert_verify()
opinion of the certificates validity. Processing will continue depending on
the return value. If one just wishes to use the callback for informational
reason, just return the 'ok' parameter.
--------------------------
The BN and DH library.
BIGNUM *BN_generate_prime(int bits,int strong,BIGNUM *add,
BIGNUM *rem,void (*callback)(int,int));
int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int),
Read doc/bn.doc for the description of these 2.
DH *DH_generate_parameters(int prime_len,int generator,
void (*callback)(int,int));
Read doc/bn.doc for the description of the callback, since it is just passed
to BN_generate_prime(), except that it is also called as
callback(3,0) by this function.
--------------------------
The CRYPTO library.
void CRYPTO_set_locking_callback(void (*func)(int mode,int type,char *file,
int line));
void CRYPTO_set_add_lock_callback(int (*func)(int *num,int mount,
int type,char *file, int line));
void CRYPTO_set_id_callback(unsigned long (*func)(void));
Read threads.doc for info on these ones.
==== cipher.doc ========================================================
The Cipher subroutines.
These routines require "evp.h" to be included.
These functions are a higher level interface to the various cipher
routines found in this library. As such, they allow the same code to be
used to encrypt and decrypt via different ciphers with only a change
in an initial parameter. These routines also provide buffering for block
ciphers.
These routines all take a pointer to the following structure to specify
which cipher to use. If you wish to use a new cipher with these routines,
you would probably be best off looking an how an existing cipher is
implemented and copying it. At this point in time, I'm not going to go
into many details. This structure should be considered opaque
typedef struct pem_cipher_st
{
int type;
int block_size;
int key_len;
int iv_len;
void (*enc_init)(); /* init for encryption */
void (*dec_init)(); /* init for decryption */
void (*do_cipher)(); /* encrypt data */
} EVP_CIPHER;
The type field is the object NID of the cipher type
(read the section on Objects for an explanation of what a NID is).
The cipher block_size is how many bytes need to be passed
to the cipher at a time. Key_len is the
length of the key the cipher requires and iv_len is the length of the
initialisation vector required. enc_init is the function
called to initialise the ciphers context for encryption and dec_init is the
function to initialise for decryption (they need to be different, especially
for the IDEA cipher).
One reason for specifying the Cipher via a pointer to a structure
is that if you only use des-cbc, only the des-cbc routines will
be included when you link the program. If you passed an integer
that specified which cipher to use, the routine that mapped that
integer to a set of cipher functions would cause all the ciphers
to be link into the code. This setup also allows new ciphers
to be added by the application (with some restrictions).
The thirteen ciphers currently defined in this library are
EVP_CIPHER *EVP_des_ecb(); /* DES in ecb mode, iv=0, block=8, key= 8 */
EVP_CIPHER *EVP_des_ede(); /* DES in ecb ede mode, iv=0, block=8, key=16 */
EVP_CIPHER *EVP_des_ede3(); /* DES in ecb ede mode, iv=0, block=8, key=24 */
EVP_CIPHER *EVP_des_cfb(); /* DES in cfb mode, iv=8, block=1, key= 8 */
EVP_CIPHER *EVP_des_ede_cfb(); /* DES in ede cfb mode, iv=8, block=1, key=16 */
EVP_CIPHER *EVP_des_ede3_cfb();/* DES in ede cfb mode, iv=8, block=1, key=24 */
EVP_CIPHER *EVP_des_ofb(); /* DES in ofb mode, iv=8, block=1, key= 8 */
EVP_CIPHER *EVP_des_ede_ofb(); /* DES in ede ofb mode, iv=8, block=1, key=16 */
EVP_CIPHER *EVP_des_ede3_ofb();/* DES in ede ofb mode, iv=8, block=1, key=24 */
EVP_CIPHER *EVP_des_cbc(); /* DES in cbc mode, iv=8, block=8, key= 8 */
EVP_CIPHER *EVP_des_ede_cbc(); /* DES in cbc ede mode, iv=8, block=8, key=16 */
EVP_CIPHER *EVP_des_ede3_cbc();/* DES in cbc ede mode, iv=8, block=8, key=24 */
EVP_CIPHER *EVP_desx_cbc(); /* DES in desx cbc mode,iv=8, block=8, key=24 */
EVP_CIPHER *EVP_rc4(); /* RC4, iv=0, block=1, key=16 */
EVP_CIPHER *EVP_idea_ecb(); /* IDEA in ecb mode, iv=0, block=8, key=16 */
EVP_CIPHER *EVP_idea_cfb(); /* IDEA in cfb mode, iv=8, block=1, key=16 */
EVP_CIPHER *EVP_idea_ofb(); /* IDEA in ofb mode, iv=8, block=1, key=16 */
EVP_CIPHER *EVP_idea_cbc(); /* IDEA in cbc mode, iv=8, block=8, key=16 */
EVP_CIPHER *EVP_rc2_ecb(); /* RC2 in ecb mode, iv=0, block=8, key=16 */
EVP_CIPHER *EVP_rc2_cfb(); /* RC2 in cfb mode, iv=8, block=1, key=16 */
EVP_CIPHER *EVP_rc2_ofb(); /* RC2 in ofb mode, iv=8, block=1, key=16 */
EVP_CIPHER *EVP_rc2_cbc(); /* RC2 in cbc mode, iv=8, block=8, key=16 */
EVP_CIPHER *EVP_bf_ecb(); /* Blowfish in ecb mode,iv=0, block=8, key=16 */
EVP_CIPHER *EVP_bf_cfb(); /* Blowfish in cfb mode,iv=8, block=1, key=16 */
EVP_CIPHER *EVP_bf_ofb(); /* Blowfish in ofb mode,iv=8, block=1, key=16 */
EVP_CIPHER *EVP_bf_cbc(); /* Blowfish in cbc mode,iv=8, block=8, key=16 */
The meaning of the compound names is as follows.
des The base cipher is DES.
idea The base cipher is IDEA
rc4 The base cipher is RC4-128
rc2 The base cipher is RC2-128
ecb Electronic Code Book form of the cipher.
cbc Cipher Block Chaining form of the cipher.
cfb 64 bit Cipher Feedback form of the cipher.
ofb 64 bit Output Feedback form of the cipher.
ede The cipher is used in Encrypt, Decrypt, Encrypt mode. The first
and last keys are the same.
ede3 The cipher is used in Encrypt, Decrypt, Encrypt mode.
All the Cipher routines take a EVP_CIPHER_CTX pointer as an argument.
The state of the cipher is kept in this structure.
typedef struct EVP_CIPHER_Ctx_st
{
EVP_CIPHER *cipher;
int encrypt; /* encrypt or decrypt */
int buf_len; /* number we have left */
unsigned char buf[8];
union {
.... /* cipher specific stuff */
} c;
} EVP_CIPHER_CTX;
Cipher is a pointer the the EVP_CIPHER for the current context. The encrypt
flag indicates encryption or decryption. buf_len is the number of bytes
currently being held in buf.
The 'c' union holds the cipher specify context.
The following functions are to be used.
int EVP_read_pw_string(
char *buf,
int len,
char *prompt,
int verify,
This function is the same as des_read_pw_string() (des.doc).
void EVP_set_pw_prompt(char *prompt);
This function sets the 'default' prompt to use to use in
EVP_read_pw_string when the prompt parameter is NULL. If the
prompt parameter is NULL, this 'default prompt' feature is turned
off. Be warned, this is a global variable so weird things
will happen if it is used under Win16 and care must be taken
with a multi-threaded version of the library.
char *EVP_get_pw_prompt();
This returns a pointer to the default prompt string. NULL
if it is not set.
int EVP_BytesToKey(
EVP_CIPHER *type,
EVP_MD *md,
unsigned char *salt,
unsigned char *data,
int datal,
int count,
unsigned char *key,
unsigned char *iv);
This function is used to generate a key and an initialisation vector
for a specified cipher from a key string and a salt. Type
specifies the cipher the 'key' is being generated for. Md is the
message digest algorithm to use to generate the key and iv. The salt
is an optional 8 byte object that is used to help seed the key
generator.
If the salt value is NULL, it is just not used. Datal is the
number of bytes to use from 'data' in the key generation.
This function returns the key size for the specified cipher, if
data is NULL, this value is returns and no other
computation is performed. Count is
the number of times to loop around the key generator. I would
suggest leaving it's value as 1. Key and iv are the structures to
place the returning iv and key in. If they are NULL, no value is
generated for that particular value.
The algorithm used is as follows
/* M[] is an array of message digests
* MD() is the message digest function */
M[0]=MD(data . salt);
for (i=1; i<count; i++) M[0]=MD(M[0]);
i=1
while (data still needed for key and iv)
{
M[i]=MD(M[i-1] . data . salt);
for (i=1; i<count; i++) M[i]=MD(M[i]);
i++;
}
If the salt is NULL, it is not used.
The digests are concatenated together.
M = M[0] . M[1] . M[2] .......
For key= 8, iv=8 => key=M[0.. 8], iv=M[ 9 .. 16].
For key=16, iv=0 => key=M[0..16].
For key=16, iv=8 => key=M[0..16], iv=M[17 .. 24].
For key=24, iv=8 => key=M[0..24], iv=M[25 .. 32].
This routine will produce DES-CBC keys and iv that are compatible
with the PKCS-5 standard when md2 or md5 are used. If md5 is
used, the salt is NULL and count is 1, this routine will produce
the password to key mapping normally used with RC4.
I have attempted to logically extend the PKCS-5 standard to
generate keys and iv for ciphers that require more than 16 bytes,
if anyone knows what the correct standard is, please inform me.
When using sha or sha1, things are a bit different under this scheme,
since sha produces a 20 byte digest. So for ciphers requiring
24 bits of data, 20 will come from the first MD and 4 will
come from the second.
I have considered having a separate function so this 'routine'
can be used without the requirement of passing a EVP_CIPHER *,
but I have decided to not bother. If you wish to use the
function without official EVP_CIPHER structures, just declare
a local one and set the key_len and iv_len fields to the
length you desire.
The following routines perform encryption and decryption 'by parts'. By
this I mean that there are groups of 3 routines. An Init function that is
used to specify a cipher and initialise data structures. An Update routine
that does encryption/decryption, one 'chunk' at a time. And finally a
'Final' function that finishes the encryption/decryption process.
All these functions take a EVP_CIPHER pointer to specify which cipher to
encrypt/decrypt with. They also take a EVP_CIPHER_CTX object as an
argument. This structure is used to hold the state information associated
with the operation in progress.
void EVP_EncryptInit(
EVP_CIPHER_CTX *ctx,
EVP_CIPHER *type,
unsigned char *key,
unsigned char *iv);
This function initialise a EVP_CIPHER_CTX for encryption using the
cipher passed in the 'type' field. The cipher is initialised to use
'key' as the key and 'iv' for the initialisation vector (if one is
required). If the type, key or iv is NULL, the value currently in the
EVP_CIPHER_CTX is reused. So to perform several decrypt
using the same cipher, key and iv, initialise with the cipher,
key and iv the first time and then for subsequent calls,
reuse 'ctx' but pass NULL for type, key and iv. You must make sure
to pass a key that is large enough for a particular cipher. I
would suggest using the EVP_BytesToKey() function.
void EVP_EncryptUpdate(
EVP_CIPHER_CTX *ctx,
unsigned char *out,
int *outl,
unsigned char *in,
int inl);
This function takes 'inl' bytes from 'in' and outputs bytes
encrypted by the cipher 'ctx' was initialised with into 'out'. The
number of bytes written to 'out' is put into outl. If a particular
cipher encrypts in blocks, less or more bytes than input may be
output. Currently the largest block size used by supported ciphers
is 8 bytes, so 'out' should have room for 'inl+7' bytes. Normally
EVP_EncryptInit() is called once, followed by lots and lots of
calls to EVP_EncryptUpdate, followed by a single EVP_EncryptFinal
call.
void EVP_EncryptFinal(
EVP_CIPHER_CTX *ctx,
unsigned char *out,
int *outl);
Because quite a large number of ciphers are block ciphers, there is
often an incomplete block to write out at the end of the
encryption. EVP_EncryptFinal() performs processing on this last
block. The last block in encoded in such a way that it is possible
to determine how many bytes in the last block are valid. For 8 byte
block size ciphers, if only 5 bytes in the last block are valid, the
last three bytes will be filled with the value 3. If only 2 were
valid, the other 6 would be filled with sixes. If all 8 bytes are
valid, a extra 8 bytes are appended to the cipher stream containing
nothing but 8 eights. These last bytes are output into 'out' and
the number of bytes written is put into 'outl' These last bytes
are output into 'out' and the number of bytes written is put into
'outl'. This form of block cipher finalisation is compatible with
PKCS-5. Please remember that even if you are using ciphers like
RC4 that has no blocking and so the function will not write
anything into 'out', it would still be a good idea to pass a
variable for 'out' that can hold 8 bytes just in case the cipher is
changed some time in the future. It should also be remembered
that the EVP_CIPHER_CTX contains the password and so when one has
finished encryption with a particular EVP_CIPHER_CTX, it is good
practice to zero the structure
(ie. memset(ctx,0,sizeof(EVP_CIPHER_CTX)).
void EVP_DecryptInit(
EVP_CIPHER_CTX *ctx,
EVP_CIPHER *type,
unsigned char *key,
unsigned char *iv);
This function is basically the same as EVP_EncryptInit() accept that
is prepares the EVP_CIPHER_CTX for decryption.
void EVP_DecryptUpdate(
EVP_CIPHER_CTX *ctx,
unsigned char *out,
int *outl,
unsigned char *in,
int inl);
This function is basically the same as EVP_EncryptUpdate()
except that it performs decryption. There is one
fundamental difference though. 'out' can not be the same as
'in' for any ciphers with a block size greater than 1 if more
than one call to EVP_DecryptUpdate() will be made. This
is because this routine can hold a 'partial' block between
calls. When a partial block is decrypted (due to more bytes
being passed via this function, they will be written to 'out'
overwriting the input bytes in 'in' that have not been read
yet. From this it should also be noted that 'out' should
be at least one 'block size' larger than 'inl'. This problem
only occurs on the second and subsequent call to
EVP_DecryptUpdate() when using a block cipher.
int EVP_DecryptFinal(
EVP_CIPHER_CTX *ctx,
unsigned char *out,
int *outl);
This function is different to EVP_EncryptFinal in that it 'removes'
any padding bytes appended when the data was encrypted. Due to the
way in which 1 to 8 bytes may have been appended when encryption
using a block cipher, 'out' can end up with 0 to 7 bytes being put
into it. When decoding the padding bytes, it is possible to detect
an incorrect decryption. If the decryption appears to be wrong, 0
is returned. If everything seems ok, 1 is returned. For ciphers
with a block size of 1 (RC4), this function would normally not
return any bytes and would always return 1. Just because this
function returns 1 does not mean the decryption was correct. It
would normally be wrong due to either the wrong key/iv or
corruption of the cipher data fed to EVP_DecryptUpdate().
As for EVP_EncryptFinal, it is a good idea to zero the
EVP_CIPHER_CTX after use since the structure contains the key used
to decrypt the data.
The following Cipher routines are convenience routines that call either
EVP_EncryptXxx or EVP_DecryptXxx depending on weather the EVP_CIPHER_CTX
was setup to encrypt or decrypt.
void EVP_CipherInit(
EVP_CIPHER_CTX *ctx,
EVP_CIPHER *type,
unsigned char *key,
unsigned char *iv,
int enc);
This function take arguments that are the same as EVP_EncryptInit()
and EVP_DecryptInit() except for the extra 'enc' flag. If 1, the
EVP_CIPHER_CTX is setup for encryption, if 0, decryption.
void EVP_CipherUpdate(
EVP_CIPHER_CTX *ctx,
unsigned char *out,
int *outl,
unsigned char *in,
int inl);
Again this function calls either EVP_EncryptUpdate() or
EVP_DecryptUpdate() depending on state in the 'ctx' structure.
As noted for EVP_DecryptUpdate(), when this routine is used
for decryption with block ciphers, 'out' should not be the
same as 'in'.
int EVP_CipherFinal(
EVP_CIPHER_CTX *ctx,
unsigned char *outm,
int *outl);
This routine call EVP_EncryptFinal() or EVP_DecryptFinal()
depending on the state information in 'ctx'. 1 is always returned
if the mode is encryption, otherwise the return value is the return
value of EVP_DecryptFinal().
==== cipher.m ========================================================
Date: Tue, 15 Oct 1996 08:16:14 +1000 (EST)
From: Eric Young <eay@mincom.com>
X-Sender: eay@orb
To: Roland Haring <rharing@tandem.cl>
Cc: ssl-users@mincom.com
Subject: Re: Symmetric encryption with ssleay
In-Reply-To: <m0vBpyq-00001aC@tandemnet.tandem.cl>
Message-Id: <Pine.SOL.3.91.961015075623.11394A-100000@orb>
Mime-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Sender: ssl-lists-owner@mincom.com
Precedence: bulk
Status: RO
X-Status:
On Fri, 11 Oct 1996, Roland Haring wrote:
> THE_POINT:
> Would somebody be so kind to give me the minimum basic
> calls I need to do to libcrypto.a to get some text encrypted
> and decrypted again? ...hopefully with code included to do
> base64 encryption and decryption ... e.g. that sign-it.c code
> posted some while ago was a big help :-) (please, do not point
> me to apps/enc.c where I suspect my Heissenbug to be hidden :-)
Ok, the base64 encoding stuff in 'enc.c' does the wrong thing sometimes
when the data is less than a line long (this is for decoding). I'll dig
up the exact fix today and post it. I am taking longer on 0.6.5 than I
intended so I'll just post this patch.
The documentation to read is in
doc/cipher.doc,
doc/encode.doc (very sparse :-).
and perhaps
doc/digest.doc,
The basic calls to encrypt with say triple DES are
Given
char key[EVP_MAX_KEY_LENGTH];
char iv[EVP_MAX_IV_LENGTH];
EVP_CIPHER_CTX ctx;
unsigned char out[512+8];
int outl;
/* optional generation of key/iv data from text password using md5
* via an upward compatable verson of PKCS#5. */
EVP_BytesToKey(EVP_des_ede3_cbc,EVP_md5,NULL,passwd,strlen(passwd),
key,iv);
/* Initalise the EVP_CIPHER_CTX */
EVP_EncryptInit(ctx,EVP_des_ede3_cbc,key,iv);
while (....)
{
/* This is processing 512 bytes at a time, the bytes are being
* copied into 'out', outl bytes are output. 'out' should not be the
* same as 'in' for reasons mentioned in the documentation. */
EVP_EncryptUpdate(ctx,out,&outl,in,512);
}
/* Output the last 'block'. If the cipher is a block cipher, the last
* block is encoded in such a way so that a wrong decryption will normally be
* detected - again, one of the PKCS standards. */
EVP_EncryptFinal(ctx,out,&outl);
To decrypt, use the EVP_DecryptXXXXX functions except that EVP_DecryptFinal()
will return 0 if the decryption fails (only detectable on block ciphers).
You can also use
EVP_CipherInit()
EVP_CipherUpdate()
EVP_CipherFinal()
which does either encryption or decryption depending on an extra
parameter to EVP_CipherInit().
To do the base64 encoding,
EVP_EncodeInit()
EVP_EncodeUpdate()
EVP_EncodeFinal()
EVP_DecodeInit()
EVP_DecodeUpdate()
EVP_DecodeFinal()
where the encoding is quite simple, but the decoding can be a bit more
fun (due to dud input).
EVP_DecodeUpdate() returns -1 for an error on an input line, 0 if the
'last line' was just processed, and 1 if more lines should be submitted.
EVP_DecodeFinal() returns -1 for an error or 1 if things are ok.
So the loop becomes
EVP_DecodeInit(....)
for (;;)
{
i=EVP_DecodeUpdate(....);
if (i < 0) goto err;
/* process the data */
if (i == 0) break;
}
EVP_DecodeFinal(....);
/* process the data */
The problem in 'enc.c' is that I was stuff the processing up after the
EVP_DecodeFinal(...) when the for(..) loop was not being run (one line of
base64 data) and this was because 'enc.c' tries to scan over a file until
it hits the first valid base64 encoded line.
hope this helps a bit.
eric
--
Eric Young | BOOL is tri-state according to Bill Gates.
AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage().
==== conf.doc ========================================================
The CONF library.
The CONF library is a simple set of routines that can be used to configure
programs. It is a superset of the genenv() function with some extra
structure.
The library consists of 5 functions.
LHASH *CONF_load(LHASH *config,char *file);
This function is called to load in a configuration file. Multiple
configuration files can be loaded, with each subsequent 'load' overwriting
any already defined 'variables'. If there is an error, NULL is returned.
If config is NULL, a new LHASH structure is created and returned, otherwise
the new data in the 'file' is loaded into the 'config' structure.
void CONF_free(LHASH *config);
This function free()s the data in config.
char *CONF_get_string(LHASH *config,char *section,char *name);
This function returns the string found in 'config' that corresponds to the
'section' and 'name' specified. Classes and the naming system used will be
discussed later in this document. If the variable is not defined, an NULL
is returned.
long CONF_get_long(LHASH *config,char *section, char *name);
This function is the same as CONF_get_string() except that it converts the
string to an long and returns it. If variable is not a number or the
variable does not exist, 0 is returned. This is a little problematic but I
don't know of a simple way around it.
STACK *CONF_get_section(LHASH *config, char *section);
This function returns a 'stack' of CONF_VALUE items that are all the
items defined in a particular section. DO NOT free() any of the
variable returned. They will disappear when CONF_free() is called.
The 'lookup' model.
The configuration file is divided into 'sections'. Each section is started by
a line of the form '[ section ]'. All subsequent variable definitions are
of this section. A variable definition is a simple alpha-numeric name
followed by an '=' and then the data. A section or variable name can be
described by a regular expression of the following form '[A-Za-z0-9_]+'.
The value of the variable is the text after the '=' until the end of the
line, stripped of leading and trailing white space.
At this point I should mention that a '#' is a comment character, \ is the
escape character, and all three types of quote can be used to stop any
special interpretation of the data.
Now when the data is being loaded, variable expansion can occur. This is
done by expanding any $NAME sequences into the value represented by the
variable NAME. If the variable is not in the current section, the different
section can be specified by using the $SECTION::NAME form. The ${NAME} form
also works and is very useful for expanding variables inside strings.
When a variable is looked up, there are 2 special section. 'default', which
is the initial section, and 'ENV' which is the processes environment
variables (accessed via getenv()). When a variable is looked up, it is
first 'matched' with it's section (if one was specified), if this fails, the
'default' section is matched.
If the 'lhash' variable passed was NULL, the environment is searched.
Now why do we bother with sections? So we can have multiple programs using
the same configuration file, or multiple instances of the same program
using different variables. It also provides a nice mechanism to override
the processes environment variables (eg ENV::HOME=/tmp). If there is a
program specific variable missing, we can have default values.
Multiple configuration files can be loaded, with each new value clearing
any predefined values. A system config file can provide 'default' values,
and application/usr specific files can provide overriding values.
Examples
# This is a simple example
SSLEAY_HOME = /usr/local/ssl
ENV::PATH = $SSLEAY_HOME/bin:$PATH # override my path
[X509]
cert_dir = $SSLEAY_HOME/certs # /usr/local/ssl/certs
[SSL]
CIPHER = DES-EDE-MD5:RC4-MD5
USER_CERT = $HOME/${USER}di'r 5' # /home/eay/eaydir 5
USER_CERT = $HOME/\${USER}di\'r # /home/eay/${USER}di'r
USER_CERT = "$HOME/${US"ER}di\'r # $HOME/${USER}di'r
TEST = 1234\
5678\
9ab # TEST=123456789ab
TTT = 1234\n\n # TTT=1234<nl><nl>
==== des.doc ========================================================
The DES library.
Please note that this library was originally written to operate with
eBones, a version of Kerberos that had had encryption removed when it left
the USA and then put back in. As such there are some routines that I will
advise not using but they are still in the library for historical reasons.
For all calls that have an 'input' and 'output' variables, they can be the
same.
This library requires the inclusion of 'des.h'.
All of the encryption functions take what is called a des_key_schedule as an
argument. A des_key_schedule is an expanded form of the des key.
A des_key is 8 bytes of odd parity, the type used to hold the key is a
des_cblock. A des_cblock is an array of 8 bytes, often in this library
description I will refer to input bytes when the function specifies
des_cblock's as input or output, this just means that the variable should
be a multiple of 8 bytes.
The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to
specify decryption. The functions and global variable are as follows:
int des_check_key;
DES keys are supposed to be odd parity. If this variable is set to
a non-zero value, des_set_key() will check that the key has odd
parity and is not one of the known weak DES keys. By default this
variable is turned off;
void des_set_odd_parity(
des_cblock *key );
This function takes a DES key (8 bytes) and sets the parity to odd.
int des_is_weak_key(
des_cblock *key );
This function returns a non-zero value if the DES key passed is a
weak, DES key. If it is a weak key, don't use it, try a different
one. If you are using 'random' keys, the chances of hitting a weak
key are 1/2^52 so it is probably not worth checking for them.
int des_set_key(
des_cblock *key,
des_key_schedule schedule);
Des_set_key converts an 8 byte DES key into a des_key_schedule.
A des_key_schedule is an expanded form of the key which is used to
perform actual encryption. It can be regenerated from the DES key
so it only needs to be kept when encryption or decryption is about
to occur. Don't save or pass around des_key_schedule's since they
are CPU architecture dependent, DES keys are not. If des_check_key
is non zero, zero is returned if the key has the wrong parity or
the key is a weak key, else 1 is returned.
int des_key_sched(
des_cblock *key,
des_key_schedule schedule);
An alternative name for des_set_key().
int des_rw_mode; /* defaults to DES_PCBC_MODE */
This flag holds either DES_CBC_MODE or DES_PCBC_MODE (default).
This specifies the function to use in the enc_read() and enc_write()
functions.
void des_encrypt(
unsigned long *data,
des_key_schedule ks,
int enc);
This is the DES encryption function that gets called by just about
every other DES routine in the library. You should not use this
function except to implement 'modes' of DES. I say this because the
functions that call this routine do the conversion from 'char *' to
long, and this needs to be done to make sure 'non-aligned' memory
access do not occur. The characters are loaded 'little endian',
have a look at my source code for more details on how I use this
function.
Data is a pointer to 2 unsigned long's and ks is the
des_key_schedule to use. enc, is non zero specifies encryption,
zero if decryption.
void des_encrypt2(
unsigned long *data,
des_key_schedule ks,
int enc);
This functions is the same as des_encrypt() except that the DES
initial permutation (IP) and final permutation (FP) have been left
out. As for des_encrypt(), you should not use this function.
It is used by the routines in my library that implement triple DES.
IP() des_encrypt2() des_encrypt2() des_encrypt2() FP() is the same
as des_encrypt() des_encrypt() des_encrypt() except faster :-).
void des_ecb_encrypt(
des_cblock *input,
des_cblock *output,
des_key_schedule ks,
int enc);
This is the basic Electronic Code Book form of DES, the most basic
form. Input is encrypted into output using the key represented by
ks. If enc is non zero (DES_ENCRYPT), encryption occurs, otherwise
decryption occurs. Input is 8 bytes long and output is 8 bytes.
(the des_cblock structure is 8 chars).
void des_ecb3_encrypt(
des_cblock *input,
des_cblock *output,
des_key_schedule ks1,
des_key_schedule ks2,
des_key_schedule ks3,
int enc);
This is the 3 key EDE mode of ECB DES. What this means is that
the 8 bytes of input is encrypted with ks1, decrypted with ks2 and
then encrypted again with ks3, before being put into output;
C=E(ks3,D(ks2,E(ks1,M))). There is a macro, des_ecb2_encrypt()
that only takes 2 des_key_schedules that implements,
C=E(ks1,D(ks2,E(ks1,M))) in that the final encrypt is done with ks1.
void des_cbc_encrypt(
des_cblock *input,
des_cblock *output,
long length,
des_key_schedule ks,
des_cblock *ivec,
int enc);
This routine implements DES in Cipher Block Chaining mode.
Input, which should be a multiple of 8 bytes is encrypted
(or decrypted) to output which will also be a multiple of 8 bytes.
The number of bytes is in length (and from what I've said above,
should be a multiple of 8). If length is not a multiple of 8, I'm
not being held responsible :-). ivec is the initialisation vector.
This function does not modify this variable. To correctly implement
cbc mode, you need to do one of 2 things; copy the last 8 bytes of
cipher text for use as the next ivec in your application,
or use des_ncbc_encrypt().
Only this routine has this problem with updating the ivec, all
other routines that are implementing cbc mode update ivec.
void des_ncbc_encrypt(
des_cblock *input,
des_cblock *output,
long length,
des_key_schedule sk,
des_cblock *ivec,
int enc);
For historical reasons, des_cbc_encrypt() did not update the
ivec with the value requires so that subsequent calls to
des_cbc_encrypt() would 'chain'. This was needed so that the same
'length' values would not need to be used when decrypting.
des_ncbc_encrypt() does the right thing. It is the same as
des_cbc_encrypt accept that ivec is updates with the correct value
to pass in subsequent calls to des_ncbc_encrypt(). I advise using
des_ncbc_encrypt() instead of des_cbc_encrypt();
void des_xcbc_encrypt(
des_cblock *input,
des_cblock *output,
long length,
des_key_schedule sk,
des_cblock *ivec,
des_cblock *inw,
des_cblock *outw,
int enc);
This 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.
void des_3cbc_encrypt(
des_cblock *input,
des_cblock *output,
long length,
des_key_schedule sk1,
des_key_schedule sk2,
des_cblock *ivec1,
des_cblock *ivec2,
int enc);
This function is flawed, do not use it. I have left it in the
library because it is used in my des(1) program and will function
correctly when used by des(1). If I removed the function, people
could end up unable to decrypt files.
This routine implements outer triple cbc encryption using 2 ks and
2 ivec's. Use des_ede2_cbc_encrypt() instead.
void des_ede3_cbc_encrypt(
des_cblock *input,
des_cblock *output,
long length,
des_key_schedule ks1,
des_key_schedule ks2,
des_key_schedule ks3,
des_cblock *ivec,
int enc);
This function implements outer triple CBC DES encryption with 3
keys. What this means is that each 'DES' operation
inside the cbc mode is really an C=E(ks3,D(ks2,E(ks1,M))).
Again, this is cbc mode so an ivec is requires.
This mode is used by SSL.
There is also a des_ede2_cbc_encrypt() that only uses 2
des_key_schedule's, the first being reused for the final
encryption. C=E(ks1,D(ks2,E(ks1,M))). This form of triple DES
is used by the RSAref library.
void des_pcbc_encrypt(
des_cblock *input,
des_cblock *output,
long length,
des_key_schedule ks,
des_cblock *ivec,
int enc);
This is Propagating Cipher Block Chaining mode of DES. It is used
by Kerberos v4. It's parameters are the same as des_ncbc_encrypt().
void des_cfb_encrypt(
unsigned char *in,
unsigned char *out,
int numbits,
long length,
des_key_schedule ks,
des_cblock *ivec,
int enc);
Cipher Feedback Back mode of DES. This implementation 'feeds back'
in numbit blocks. The input (and output) is in multiples of numbits
bits. numbits should to be a multiple of 8 bits. Length is the
number of bytes input. If numbits is not a multiple of 8 bits,
the extra bits in the bytes will be considered padding. So if
numbits is 12, for each 2 input bytes, the 4 high bits of the
second byte will be ignored. So to encode 72 bits when using
a numbits of 12 take 12 bytes. To encode 72 bits when using
numbits of 9 will take 16 bytes. To encode 80 bits when using
numbits of 16 will take 10 bytes. etc, etc. This padding will
apply to both input and output.
void des_cfb64_encrypt(
unsigned char *in,
unsigned char *out,
long length,
des_key_schedule ks,
des_cblock *ivec,