Newer
Older
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
3998
3999
4000
int *num,
int enc);
This is one of the more useful functions in this DES library, it
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 :-).
void des_ede3_cfb64_encrypt(
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);
Same as des_cfb64_encrypt() accept that the DES operation is
triple DES. As usual, there is a macro for
des_ede2_cfb64_encrypt() which reuses ks1.
void des_ofb_encrypt(
unsigned char *in,
unsigned char *out,
int numbits,
long length,
des_key_schedule ks,
des_cblock *ivec);
This is a implementation of Output Feed Back mode of DES. It is
the same as des_cfb_encrypt() in that numbits is the size of the
units dealt with during input and output (in bits).
void des_ofb64_encrypt(
unsigned char *in,
unsigned char *out,
long length,
des_key_schedule ks,
des_cblock *ivec,
int *num);
The same as des_cfb64_encrypt() except that it is Output Feed Back
mode.
void des_ede3_ofb64_encrypt(
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);
Same as des_ofb64_encrypt() accept that the DES operation is
triple DES. As usual, there is a macro for
des_ede2_ofb64_encrypt() which reuses ks1.
int des_read_pw_string(
char *buf,
int length,
char *prompt,
int verify);
This routine is used to get a password from the terminal with echo
turned off. Buf is where the string will end up and length is the
size of buf. Prompt is a string presented to the 'user' and if
verify is set, the key is asked for twice and unless the 2 copies
match, an error is returned. A return code of -1 indicates a
system error, 1 failure due to use interaction, and 0 is success.
unsigned long des_cbc_cksum(
des_cblock *input,
des_cblock *output,
long length,
des_key_schedule ks,
des_cblock *ivec);
This function produces an 8 byte checksum from input that it puts in
output and returns the last 4 bytes as a long. The checksum is
generated via cbc mode of DES in which only the last 8 byes are
kept. I would recommend not using this function but instead using
the EVP_Digest routines, or at least using MD5 or SHA. This
function is used by Kerberos v4 so that is why it stays in the
library.
char *des_fcrypt(
const char *buf,
const char *salt
char *ret);
This is my 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.
char *crypt(
const char *buf,
const char *salt);
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).
void des_string_to_key(
char *str,
des_cblock *key);
This function takes str and converts it into a DES key. I would
recommend using MD5 instead and use the first 8 bytes of output.
When I wrote the first version of these routines back in 1990, MD5
did not exist but I feel these routines are still sound. This
routines is compatible with the one in MIT's libdes.
void des_string_to_2keys(
char *str,
des_cblock *key1,
des_cblock *key2);
This function takes str and converts it into 2 DES keys.
I would recommend using MD5 and using the 16 bytes as the 2 keys.
I have nothing against these 2 'string_to_key' routines, it's just
that if you say that your encryption key is generated by using the
16 bytes of an MD5 hash, every-one knows how you generated your
keys.
int des_read_password(
des_cblock *key,
char *prompt,
int verify);
This routine combines des_read_pw_string() with des_string_to_key().
int des_read_2passwords(
des_cblock *key1,
des_cblock *key2,
char *prompt,
int verify);
This routine combines des_read_pw_string() with des_string_to_2key().
void des_random_seed(
des_cblock key);
This routine sets a starting point for des_random_key().
void des_random_key(
des_cblock ret);
This function return a random key. Make sure to 'seed' the random
number generator (with des_random_seed()) before using this function.
I personally now use a MD5 based random number system.
int des_enc_read(
int fd,
char *buf,
int len,
des_key_schedule ks,
des_cblock *iv);
This function will write to a file descriptor the encrypted data
from buf. This data will be preceded by a 4 byte 'byte count' and
will be padded out to 8 bytes. The encryption is either CBC of
PCBC depending on the value of des_rw_mode. If it is DES_PCBC_MODE,
pcbc is used, if DES_CBC_MODE, cbc is used. The default is to use
DES_PCBC_MODE.
int des_enc_write(
int fd,
char *buf,
int len,
des_key_schedule ks,
des_cblock *iv);
This routines read stuff written by des_enc_read() and decrypts it.
I have used these routines quite a lot but I don't believe they are
suitable for non-blocking io. If you are after a full
authentication/encryption over networks, have a look at SSL instead.
unsigned long des_quad_cksum(
des_cblock *input,
des_cblock *output,
long length,
int out_count,
des_cblock *seed);
This is a function from Kerberos v4 that is not anything to do with
DES but was needed. It is a cksum that is quicker to generate than
des_cbc_cksum(); I personally would use MD5 routines now.
=====
Modes of DES
Quite a bit of the following information has been taken from
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
There are several different modes in which DES can be used, they are
as follows.
Electronic Codebook Mode (ECB) (des_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) (des_cbc_encrypt())
- 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) (des_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) (des_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.
- 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-synchronising. If the two operation of
encipherment and decipherment get out of synchronism, the system needs
to be re-initialised.
- Each re-initialisation 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 (des_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 key space to 55 bit's but it
requires 2^56 blocks of memory.
- If all 3 keys are the same, this is effectively the same as normal
ecb mode.
Triple CBC Mode (des_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.
==== digest.doc ========================================================
The Message Digest subroutines.
These routines require "evp.h" to be included.
These functions are a higher level interface to the various message digest
routines found in this library. As such, they allow the same code to be
used to digest via different algorithms with only a change in an initial
parameter. They are basically just a front-end to the MD2, MD5, SHA
and SHA1
routines.
These routines all take a pointer to the following structure to specify
which message digest algorithm to use.
typedef struct evp_md_st
{
int type;
int pkey_type;
int md_size;
void (*init)();
void (*update)();
void (*final)();
int required_pkey_type; /*EVP_PKEY_xxx */
int (*sign)();
int (*verify)();
} EVP_MD;
If additional message digest algorithms are to be supported, a structure of
this type needs to be declared and populated and then the Digest routines
can be used with that algorithm. The type field is the object NID of the
digest type (read the section on Objects for an explanation). The pkey_type
is the Object type to use when the a message digest is generated by there
routines and then is to be signed with the pkey algorithm. Md_size is
the size of the message digest returned. Init, update
and final are the relevant functions to perform the message digest function
by parts. One reason for specifying the message digest to use via this
mechanism is that if you only use md5, only the md5 routines will
be included in you linked program. If you passed an integer
that specified which message digest to use, the routine that mapped that
integer to a set of message digest functions would cause all the message
digests functions to be link into the code. This setup also allows new
message digest functions to be added by the application.
The six message digests defined in this library are
EVP_MD *EVP_md2(void); /* RSA sign/verify */
EVP_MD *EVP_md5(void); /* RSA sign/verify */
EVP_MD *EVP_sha(void); /* RSA sign/verify */
EVP_MD *EVP_sha1(void); /* RSA sign/verify */
EVP_MD *EVP_dss(void); /* DSA sign/verify */
EVP_MD *EVP_dss1(void); /* DSA sign/verify */
All the message digest routines take a EVP_MD_CTX pointer as an argument.
The state of the message digest is kept in this structure.
typedef struct pem_md_ctx_st
{
EVP_MD *digest;
union {
unsigned char base[4]; /* this is used in my library as a
* 'pointer' to all union elements
* structures. */
MD2_CTX md2;
MD5_CTX md5;
SHA_CTX sha;
} md;
} EVP_MD_CTX;
The Digest functions are as follows.
void EVP_DigestInit(
EVP_MD_CTX *ctx,
EVP_MD *type);
This function is used to initialise the EVP_MD_CTX. The message
digest that will associated with 'ctx' is specified by 'type'.
void EVP_DigestUpdate(
EVP_MD_CTX *ctx,
unsigned char *data,
unsigned int cnt);
This function is used to pass more data to the message digest
function. 'cnt' bytes are digested from 'data'.
void EVP_DigestFinal(
EVP_MD_CTX *ctx,
unsigned char *md,
unsigned int *len);
This function finishes the digestion and puts the message digest
into 'md'. The length of the message digest is put into len;
EVP_MAX_MD_SIZE is the size of the largest message digest that
can be returned from this function. Len can be NULL if the
size of the digest is not required.
==== encode.doc ========================================================
void EVP_EncodeInit(EVP_ENCODE_CTX *ctx);
void EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,
int *outl,unsigned char *in,int inl);
void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl);
int EVP_EncodeBlock(unsigned char *t, unsigned char *f, int n);
void EVP_DecodeInit(EVP_ENCODE_CTX *ctx);
int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl,
unsigned char *in, int inl);
int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned
char *out, int *outl);
int EVP_DecodeBlock(unsigned char *t, unsigned
char *f, int n);
==== envelope.doc ========================================================
The following routines are use to create 'digital' envelopes.
By this I mean that they perform various 'higher' level cryptographic
functions. Have a read of 'cipher.doc' and 'digest.doc' since those
routines are used by these functions.
cipher.doc contains documentation about the cipher part of the
envelope library and digest.doc contatins the description of the
message digests supported.
To 'sign' a document involves generating a message digest and then encrypting
the digest with an private key.
#define EVP_SignInit(a,b) EVP_DigestInit(a,b)
#define EVP_SignUpdate(a,b,c) EVP_DigestUpdate(a,b,c)
Due to the fact this operation is basically just an extended message
digest, the first 2 functions are macro calls to Digest generating
functions.
int EVP_SignFinal(
EVP_MD_CTX *ctx,
unsigned char *md,
unsigned int *s,
EVP_PKEY *pkey);
This finalisation function finishes the generation of the message
digest and then encrypts the digest (with the correct message digest
object identifier) with the EVP_PKEY private key. 'ctx' is the message digest
context. 'md' will end up containing the encrypted message digest. This
array needs to be EVP_PKEY_size(pkey) bytes long. 's' will actually
contain the exact length. 'pkey' of course is the private key. It is
one of EVP_PKEY_RSA or EVP_PKEY_DSA type.
If there is an error, 0 is returned, otherwise 1.
Verify is used to check an signed message digest.
#define EVP_VerifyInit(a,b) EVP_DigestInit(a,b)
#define EVP_VerifyUpdate(a,b,c) EVP_DigestUpdate(a,b,c)
Since the first step is to generate a message digest, the first 2 functions
are macros.
int EVP_VerifyFinal(
EVP_MD_CTX *ctx,
unsigned char *md,
unsigned int s,
EVP_PKEY *pkey);
This function finishes the generation of the message digest and then
compares it with the supplied encrypted message digest. 'md' contains the
's' bytes of encrypted message digest. 'pkey' is used to public key decrypt
the digest. It is then compared with the message digest just generated.
If they match, 1 is returned else 0.
int EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek,
int *ekl, unsigned char *iv, EVP_PKEY **pubk, int npubk);
Must have at least one public key, error is 0. I should also mention that
the buffers pointed to by 'ek' need to be EVP_PKEY_size(pubk[n]) is size.
#define EVP_SealUpdate(a,b,c,d,e) EVP_EncryptUpdate(a,b,c,d,e)
void EVP_SealFinal(EVP_CIPHER_CTX *ctx,unsigned char *out,int *outl);
int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek,
int ekl,unsigned char *iv,EVP_PKEY *priv);
0 on failure
#define EVP_OpenUpdate(a,b,c,d,e) EVP_DecryptUpdate(a,b,c,d,e)
int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
Decrypt final return code
==== error.doc ========================================================
The error routines.
The 'error' system I've implemented is intended to server 2 purpose, to
record the reason why a command failed and to record where in the libraries
the failure occurred. It is more or less setup to record a 'trace' of which
library components were being traversed when the error occurred.
When an error is recorded, it is done so a as single unsigned long which is
composed of three parts. The top byte is the 'library' number, the middle
12 bytes is the function code, and the bottom 12 bits is the 'reason' code.
Each 'library', or should a say, 'section' of the SSLeay library has a
different unique 'library' error number. Each function in the library has
a number that is unique for that library. Each 'library' also has a number
for each 'error reason' that is only unique for that 'library'.
Due to the way these error routines record a 'error trace', there is an
array per thread that is used to store the error codes.
The various functions in this library are used to access
and manipulate this array.
void ERR_put_error(int lib, int func,int reason);
This routine records an error in library 'lib', function 'func'
and reason 'reason'. As errors get 'put' into the buffer, they wrap
around and overwrite old errors if too many are written. It is assumed
that the last errors are the most important.
unsigned long ERR_get_error(void );
This function returns the last error added to the error buffer.
In effect it is popping the value off the buffer so repeated calls will
continue to return values until there are no more errors to return in which
case 0 is returned.
unsigned long ERR_peek_error(void );
This function returns the value of the last error added to the
error buffer but does not 'pop' it from the buffer.
void ERR_clear_error(void );
This function clears the error buffer, discarding all unread
errors.
While the above described error system obviously produces lots of different
error number, a method for 'reporting' these errors in a human readable
form is required. To achieve this, each library has the option of
'registering' error strings.
typedef struct ERR_string_data_st
{
unsigned long error;
char *string;
} ERR_STRING_DATA;
The 'ERR_STRING_DATA' contains an error code and the corresponding text
string. To add new function error strings for a library, the
ERR_STRING_DATA needs to be 'registered' with the library.
void ERR_load_strings(unsigned long lib,ERR_STRING_DATA *err);
This function 'registers' the array of ERR_STRING_DATA pointed to by
'err' as error text strings for the error library 'lib'.
void ERR_free_strings(void);
This function free()s all the loaded error strings.
char *ERR_error_string(unsigned long error,char *buf);
This function returns a text string that is a human readable
version of the error represented by 'error'. Buff should be at least 120
bytes long and if it is NULL, the return value is a pointer to a static
variable that will contain the error string, otherwise 'buf' is returned.
If there is not a text string registered for a particular error, a text
string containing the error number is returned instead.
void ERR_print_errors(BIO *bp);
void ERR_print_errors_fp(FILE *fp);
This function is a convenience routine that prints the error string
for each error until all errors have been accounted for.
char *ERR_lib_error_string(unsigned long e);
char *ERR_func_error_string(unsigned long e);
char *ERR_reason_error_string(unsigned long e);
The above three functions return the 3 different components strings for the
error 'e'. ERR_error_string() uses these functions.
void ERR_load_ERR_strings(void );
This function 'registers' the error strings for the 'ERR' module.
void ERR_load_crypto_strings(void );
This function 'register' the error strings for just about every
library in the SSLeay package except for the SSL routines. There is no
need to ever register any error text strings and you will probably save in
program size. If on the other hand you do 'register' all errors, it is
quite easy to determine why a particular routine failed.
As a final footnote as to why the error system is designed as it is.
1) I did not want a single 'global' error code.
2) I wanted to know which subroutine a failure occurred in.
3) For Windows NT etc, it should be simple to replace the 'key' routines
with code to pass error codes back to the application.
4) I wanted the option of meaningful error text strings.
Late breaking news - the changes to support threads.
Each 'thread' has an 'ERR_STATE' state associated with it.
ERR_STATE *ERR_get_state(void ) will return the 'state' for the calling
thread/process.
ERR_remove_state(unsigned long pid); will 'free()' this state. If pid == 0
the current 'thread/process' will have it's error state removed.
If you do not remove the error state of a thread, this could be considered a
form of memory leak, so just after 'reaping' a thread that has died,
call ERR_remove_state(pid).
Have a read of thread.doc for more details for what is required for
multi-threading support. All the other error routines will
work correctly when using threads.
==== idea.doc ========================================================
The IDEA library.
IDEA is a block cipher that operates on 64bit (8 byte) quantities. It
uses a 128bit (16 byte) key. It can be used in all the modes that DES can
be used. This library implements the ecb, cbc, cfb64 and ofb64 modes.
For all calls that have an 'input' and 'output' variables, they can be the
same.
This library requires the inclusion of 'idea.h'.
All of the encryption functions take what is called an IDEA_KEY_SCHEDULE as an
argument. An IDEA_KEY_SCHEDULE is an expanded form of the idea key.
For all modes of the IDEA algorithm, the IDEA_KEY_SCHEDULE used for
decryption is different to the one used for encryption.
The define IDEA_ENCRYPT is passed to specify encryption for the functions
that require an encryption/decryption flag. IDEA_DECRYPT is passed to
specify decryption. For some mode there is no encryption/decryption
flag since this is determined by the IDEA_KEY_SCHEDULE.
So to encrypt you would do the following
idea_set_encrypt_key(key,encrypt_ks);
idea_ecb_encrypt(...,encrypt_ks);
idea_cbc_encrypt(....,encrypt_ks,...,IDEA_ENCRYPT);
To Decrypt
idea_set_encrypt_key(key,encrypt_ks);
idea_set_decrypt_key(encrypt_ks,decrypt_ks);
idea_ecb_encrypt(...,decrypt_ks);
idea_cbc_encrypt(....,decrypt_ks,...,IDEA_DECRYPT);
Please note that any of the encryption modes specified in my DES library
could be used with IDEA. I have only implemented ecb, cbc, cfb64 and
ofb64 for the following reasons.
- ecb is the basic IDEA encryption.
- cbc is the normal 'chaining' form for block ciphers.
- cfb64 can be used to encrypt single characters, therefore input and output
do not need to be a multiple of 8.
- ofb64 is similar to cfb64 but is more like a stream cipher, not as
secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
- If you want triple IDEA, thats 384 bits of key and you must be totally
obsessed with security. Still, if you want it, it is simple enough to
copy the function from the DES library and change the des_encrypt to
idea_encrypt; an exercise left for the paranoid reader :-).
The functions are as follows:
void idea_set_encrypt_key(
unsigned char *key;
IDEA_KEY_SCHEDULE *ks);
idea_set_encrypt_key converts a 16 byte IDEA key into an
IDEA_KEY_SCHEDULE. The IDEA_KEY_SCHEDULE is an expanded form of
the key which can be used to perform IDEA encryption.
An IDEA_KEY_SCHEDULE is an expanded form of the key which is used to
perform actual encryption. It can be regenerated from the IDEA key
so it only needs to be kept when encryption is about
to occur. Don't save or pass around IDEA_KEY_SCHEDULE's since they
are CPU architecture dependent, IDEA keys are not.
void idea_set_decrypt_key(
IDEA_KEY_SCHEDULE *encrypt_ks,
IDEA_KEY_SCHEDULE *decrypt_ks);
This functions converts an encryption IDEA_KEY_SCHEDULE into a
decryption IDEA_KEY_SCHEDULE. For all decryption, this conversion
of the key must be done. In some modes of IDEA, an
encryption/decryption flag is also required, this is because these
functions involve block chaining and the way this is done changes
depending on which of encryption of decryption is being done.
Please note that there is no quick way to generate the decryption
key schedule other than generating the encryption key schedule and
then converting it.
void idea_encrypt(
unsigned long *data,
IDEA_KEY_SCHEDULE *ks);
This is the IDEA encryption function that gets called by just about
every other IDEA routine in the library. You should not use this
function except to implement 'modes' of IDEA. 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.
Data is a pointer to 2 unsigned long's and ks is the
IDEA_KEY_SCHEDULE to use. Encryption or decryption depends on the
IDEA_KEY_SCHEDULE.
void idea_ecb_encrypt(
unsigned char *input,
unsigned char *output,
IDEA_KEY_SCHEDULE *ks);
This is the basic Electronic Code Book form of IDEA (in DES this
mode is called Electronic Code Book so I'm going to use the term
for idea as well :-).
Input is encrypted into output using the key represented by
ks. Depending on the IDEA_KEY_SCHEDULE, encryption or
decryption occurs. Input is 8 bytes long and output is 8 bytes.
void idea_cbc_encrypt(
unsigned char *input,
unsigned char *output,
long length,
IDEA_KEY_SCHEDULE *ks,
unsigned char *ivec,
int enc);
This routine implements IDEA 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, bad
things will probably happen. ivec is the initialisation vector.
This function updates iv after each call so that it can be passed to
the next call to idea_cbc_encrypt().
void idea_cfb64_encrypt(
unsigned char *in,
unsigned char *out,
long length,
des_key_schedule ks,
des_cblock *ivec,
int *num,
int enc);
This is one of the more useful functions in this IDEA library, it
implements CFB mode of IDEA with 64bit feedback.
This allows you to encrypt an arbitrary number of bytes,
you do not require 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.
Enc is used to indicate encryption or decryption.
One very important thing to remember is that when decrypting, use
the encryption form of the key.
CFB64 mode operates by using the cipher to
generate a stream of bytes which is used to encrypt the plain text.
The cipher text is then encrypted to generate the next 64 bits to
be xored (incrementally) with the next 64 bits of plain
text. As can be seen from this, to encrypt or decrypt,
the same 'cipher stream' needs to be generated but the way the next
block of data is gathered for encryption is different for
encryption and decryption. What this means is that to encrypt
idea_set_encrypt_key(key,ks);
idea_cfb64_encrypt(...,ks,..,IDEA_ENCRYPT)
do decrypt
idea_set_encrypt_key(key,ks)
idea_cfb64_encrypt(...,ks,...,IDEA_DECRYPT)
Note: The same IDEA_KEY_SCHEDULE but different encryption flags.
For idea_cbc or idea_ecb, idea_set_decrypt_key() would need to be
used to generate the IDEA_KEY_SCHEDULE for decryption.
The reason I'm stressing this point is that I just wasted 3 hours
today trying to decrypt using this mode and the decryption form of
the key :-(.
void idea_ofb64_encrypt(
unsigned char *in,
unsigned char *out,
long length,
des_key_schedule ks,
des_cblock *ivec,
int *num);
This functions implements OFB mode of IDEA with 64bit feedback.
This allows you to encrypt an arbitrary number of bytes,
you do not require 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.
This is in effect a stream cipher, there is no encryption or
decryption mode. The same key and iv should be used to
encrypt and decrypt.
For reading passwords, I suggest using des_read_pw_string() from my DES library.
To generate a password from a text string, I suggest using MD5 (or MD2) to
produce a 16 byte message digest that can then be passed directly to
idea_set_encrypt_key().
=====
For more information about the specific IDEA modes in this library
(ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
documentation on my DES library. What is said about DES is directly
applicable for IDEA.
==== legal.doc ========================================================
From eay@mincom.com Thu Jun 27 00:25:45 1996
Received: by orb.mincom.oz.au id AA15821
(5.65c/IDA-1.4.4 for eay); Wed, 26 Jun 1996 14:25:45 +1000
Date: Wed, 26 Jun 1996 14:25:45 +1000 (EST)
From: Eric Young <eay@mincom.oz.au>
X-Sender: eay@orb
To: Ken Toll <ktoll@ren.digitalage.com>
Cc: Eric Young <eay@mincom.oz.au>, ssl-talk@netscape.com
Subject: Re: Unidentified subject!
In-Reply-To: <9606261950.ZM28943@ren.digitalage.com>
Message-Id: <Pine.SOL.3.91.960626131156.28573K-100000@orb>
Mime-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Status: O
X-Status:
This is a little off topic but since SSLeay is a free implementation of
the SSLv2 protocol, I feel it is worth responding on the topic of if it
is actually legal for Americans to use free cryptographic software.
On Wed, 26 Jun 1996, Ken Toll wrote:
> Is the U.S the only country that SSLeay cannot be used commercially
> (because of RSAref) or is that going to be an issue with every country
> that a client/server application (non-web browser/server) is deployed
> and sold?
>From what I understand, the software patents that apply to algorithms
like RSA and DH only apply in the USA. The IDEA algorithm I believe is
patened in europe (USA?), but considing how little it is used by other SSL
implementations, it quite easily be left out of the SSLeay build
(this can be done with a compile flag).
Actually if the RSA patent did apply outside the USA, it could be rather
interesting since RSA is not alowed to let RSA toolkits outside of the USA
[1], and since these are the only forms that they will alow the algorithm
to be used in, it would mean that non-one outside of the USA could produce
public key software which would be a very strong statment for
international patent law to make :-). This logic is a little flawed but
it still points out some of the more interesting permutations of USA
patent law and ITAR restrictions.
Inside the USA there is also the unresolved issue of RC4/RC2 which were
made public on sci.crypt in Sep 1994 (RC4) and Feb 1996 (RC2). I have
copies of the origional postings if people are interested. RSA I believe
claim that they were 'trade-secrets' and that some-one broke an NDA in
revealing them. Other claim they reverse engineered the algorithms from
compiled binaries. If the algorithms were reverse engineered, I believe
RSA had no legal leg to stand on. If an NDA was broken, I don't know.
Regardless, RSA, I believe, is willing to go to court over the issue so
licencing is probably the best idea, or at least talk to them.
If there are people who actually know more about this, pease let me know, I
don't want to vilify or spread miss-information if I can help it.
If you are not producing a web browser, it is easy to build SSLeay with
RC2/RC4 removed. Since RC4 is the defacto standard cipher in
all web software (and it is damn fast) it is more or less required for
www use. For non www use of SSL, especially for an application where
interoperability with other vendors is not critical just leave it out.
Removing IDEA, RC2 and RC4 would only leave DES and Triple DES but
they should be ok. Considing that Triple DES can encrypt at rates of
410k/sec on a pentium 100, and 940k/sec on a P6/200, this is quite
reasonable performance. Single DES clocks in at 1160k/s and 2467k/s
respectivly is actually quite fast for those not so paranoid (56 bit key).[1]
> Is it possible to get a certificate for commercial use outside of the U.S.?
yes.
Thawte Consulting issues certificates (they are the people who sell the
Sioux httpd server and are based in South Africa)
Verisign will issue certificates for Sioux (sold from South Africa), so this
proves that they will issue certificate for OS use if they are
happy with the quality of the software.
(The above mentioned companies just the ones that I know for sure are issuing
certificates outside the USA).
There is always the point that if you are using SSL for an intra net,
SSLeay provides programs that can be used so you can issue your own
certificates. They need polishing but at least it is a good starting point.
I am not doing anything outside Australian law by implementing these
algorithms (to the best of my knowedge). It is another example of how
the world legal system does not cope with the internet very well.
I may start making shared libraries available (I have now got DLL's for
Windows). This will mean that distributions into the usa could be
shipped with a version with a reduced cipher set and the versions outside
could use the DLL/shared library with all the ciphers (and without RSAref).
This could be completly hidden from the application, so this would not
even require a re-linking.
This is the reverse of what people were talking about doing to get around
USA export regulations :-)
eric
[1]: The RSAref2.0 tookit is available on at least 3 ftp sites in Europe
and one in South Africa.
[2]: Since I always get questions when I post benchmark numbers :-),
DES performace figures are in 1000's of bytes per second in cbc
mode using an 8192 byte buffer. The pentium 100 was running Windows NT
3.51 DLLs and the 686/200 was running NextStep.
I quote pentium 100 benchmarks because it is basically the
'entry level' computer that most people buy for personal use.
Windows 95 is the OS shipping on those boxes, so I'll give
NT numbers (the same Win32 runtime environment). The 686
numbers are present as an indication of where we will be in a
few years.
--
Eric Young | BOOL is tri-state according to Bill Gates.
AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage().
==== lhash.doc ========================================================
The LHASH library.
I wrote this library in 1991 and have since forgotten why I called it lhash.
It implements a hash table from an article I read at the
time from 'Communications of the ACM'. What makes this hash
table different is that as the table fills, the hash table is
increased (or decreased) in size via 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'.
The state for a particular hash table is kept in the LHASH structure.
The LHASH structure also records statistics about most aspects of accessing
the hash table. This is mostly a legacy of my writing this library for
the reasons of implementing what looked like a nice algorithm rather than
for a particular software product.
Internal stuff you probably don't want to know about.
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 'bucked', it can be searched
with 10 'unsigned long' compares and 10 linked list traverses. This
will be much less expensive that 10 calls to you compare function.
LHASH *lh_new(
unsigned long (*hash)(),
int (*cmp)());
This function is used to create a new LHASH structure. It is passed
function pointers that are used to store and retrieve values passed
into the hash table. The 'hash'
function is a hashing function that will return a hashed value of
it's passed structure. 'cmp' is passed 2 parameters, it returns 0
is they are equal, otherwise, non zero.
If there are any problems (usually malloc failures), NULL is
returned, otherwise a new LHASH structure is returned. The
hash value is normally truncated to a power of 2, so make sure
that your hash function returns well mixed low order bits.
void lh_free(
LHASH *lh);
This function free()s a LHASH structure. If there is malloced
data in the hash table, it will not be freed. Consider using the
lh_doall function to deallocate any remaining entries in the hash
table.
char *lh_insert(
LHASH *lh,
char *data);
This function inserts the data pointed to by data into the lh hash
table. If there is already and entry in the hash table entry, the
value being replaced is returned. A NULL is returned if the new
entry does not clash with an entry already in the table (the normal
case) or on a malloc() failure (perhaps I should change this....).
The 'char *data' is exactly what is passed to the hash and
comparison functions specified in lh_new().
char *lh_delete(
LHASH *lh,
char *data);
This routine deletes an entry from the hash table. The value being
deleted is returned. NULL is returned if there is no such value in
the hash table.
char *lh_retrieve(
LHASH *lh,
char *data);
If 'data' is in the hash table it is returned, else NULL is
returned. The way these routines would normally be uses is that a
dummy structure would have key fields populated and then
ret=lh_retrieve(hash,&dummy);. Ret would now be a pointer to a fully
populated structure.
void lh_doall(
LHASH *lh,
void (*func)(char *a));
This function will, for every entry in the hash table, call function
'func' with the data item as parameters.
This function can be quite useful when used as follows.
void cleanup(STUFF *a)
{ STUFF_free(a); }
lh_doall(hash,cleanup);
lh_free(hash);
This can be used to free all the entries, lh_free() then
cleans up the 'buckets' that point to nothing. Be careful
when doing this. If you delete entries from the hash table,
in the call back function, the table may decrease in size,
moving item that you are
currently on down lower in the hash table. This could cause
some entries to be skipped. The best solution to this problem
is to set lh->down_load=0 before you start. This will stop
the hash table ever being decreased in size.
void lh_doall_arg(
LHASH *lh;
void(*func)(char *a,char *arg));
char *arg;
This function is the same as lh_doall except that the function
called will be passed 'arg' as the second argument.
unsigned long lh_strhash(
char *c);
This function is a demo string hashing function. 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().
The next three routines print out various statistics about the state of the