Newer
Older
6001
6002
6003
6004
6005
6006
6007
6008
6009
6010
6011
6012
6013
6014
6015
6016
6017
6018
6019
6020
6021
6022
6023
6024
6025
6026
6027
6028
6029
6030
6031
6032
6033
6034
6035
6036
6037
6038
6039
6040
6041
6042
6043
6044
6045
6046
6047
6048
6049
6050
6051
6052
6053
6054
6055
6056
6057
6058
6059
6060
6061
6062
6063
6064
6065
6066
6067
6068
6069
6070
6071
6072
6073
6074
6075
6076
6077
6078
6079
6080
6081
6082
6083
6084
6085
6086
6087
6088
6089
6090
6091
6092
6093
6094
6095
6096
6097
6098
6099
6100
6101
6102
6103
6104
6105
6106
6107
6108
6109
6110
6111
6112
6113
6114
6115
6116
6117
6118
6119
6120
6121
6122
6123
6124
6125
6126
6127
6128
6129
6130
6131
6132
6133
6134
6135
6136
6137
6138
6139
6140
6141
6142
6143
6144
6145
6146
6147
6148
6149
6150
6151
6152
6153
6154
6155
6156
6157
6158
6159
6160
6161
6162
6163
6164
6165
6166
6167
6168
6169
6170
6171
6172
6173
6174
6175
6176
6177
6178
6179
6180
6181
6182
6183
6184
6185
6186
6187
6188
6189
6190
6191
6192
6193
6194
6195
6196
6197
6198
6199
6200
6201
6202
6203
6204
6205
6206
6207
6208
6209
6210
6211
6212
6213
6214
6215
6216
6217
6218
6219
6220
6221
6222
6223
6224
6225
6226
6227
6228
6229
6230
6231
6232
6233
6234
6235
6236
6237
6238
6239
6240
6241
6242
6243
6244
6245
6246
6247
6248
6249
6250
6251
6252
6253
6254
6255
6256
6257
6258
6259
6260
6261
6262
6263
6264
6265
6266
6267
6268
6269
6270
6271
6272
6273
6274
6275
6276
6277
6278
6279
6280
6281
6282
6283
6284
6285
6286
6287
6288
6289
6290
6291
6292
6293
6294
6295
6296
6297
6298
6299
6300
6301
6302
6303
6304
6305
6306
6307
6308
6309
6310
6311
6312
6313
6314
6315
6316
6317
6318
6319
6320
6321
6322
6323
6324
6325
6326
6327
6328
6329
6330
6331
6332
6333
6334
6335
6336
6337
6338
6339
6340
6341
6342
6343
6344
6345
6346
6347
6348
6349
6350
6351
6352
6353
6354
6355
6356
6357
6358
6359
6360
6361
6362
6363
6364
6365
6366
6367
6368
6369
6370
6371
6372
6373
6374
6375
6376
6377
6378
6379
6380
6381
6382
6383
6384
6385
6386
6387
6388
6389
6390
6391
6392
6393
6394
6395
6396
6397
6398
6399
6400
6401
6402
6403
6404
6405
6406
6407
6408
6409
6410
6411
6412
6413
6414
6415
6416
6417
6418
6419
6420
6421
6422
6423
6424
6425
6426
6427
6428
6429
6430
6431
6432
6433
6434
6435
6436
6437
6438
6439
6440
6441
6442
6443
6444
6445
6446
6447
6448
6449
6450
6451
6452
6453
6454
6455
6456
6457
6458
6459
6460
6461
6462
6463
6464
6465
6466
6467
6468
6469
6470
6471
6472
6473
6474
6475
6476
6477
6478
6479
6480
6481
6482
6483
6484
6485
6486
6487
6488
6489
6490
6491
6492
6493
6494
6495
6496
6497
6498
6499
6500
6501
6502
6503
6504
6505
6506
6507
6508
6509
6510
6511
6512
6513
6514
6515
6516
6517
6518
6519
6520
6521
6522
6523
6524
6525
6526
6527
6528
6529
6530
6531
6532
6533
6534
6535
6536
6537
6538
6539
6540
6541
6542
6543
6544
6545
6546
6547
6548
6549
6550
6551
6552
6553
6554
6555
6556
6557
6558
6559
6560
6561
6562
6563
6564
6565
6566
6567
6568
6569
6570
6571
6572
6573
6574
6575
6576
6577
6578
6579
6580
6581
6582
6583
6584
6585
6586
6587
6588
6589
6590
6591
6592
6593
6594
6595
6596
6597
6598
6599
6600
6601
6602
6603
6604
6605
6606
6607
6608
6609
6610
6611
6612
6613
6614
6615
6616
6617
6618
6619
6620
6621
6622
6623
6624
6625
6626
6627
6628
6629
6630
6631
6632
6633
6634
6635
6636
6637
6638
6639
6640
6641
6642
6643
6644
6645
6646
6647
6648
6649
6650
6651
6652
6653
6654
6655
6656
6657
6658
6659
6660
6661
6662
6663
6664
6665
6666
6667
6668
6669
6670
6671
6672
6673
6674
6675
6676
6677
6678
6679
6680
6681
6682
6683
6684
6685
6686
6687
6688
6689
6690
6691
6692
6693
6694
6695
6696
6697
6698
6699
6700
6701
6702
6703
6704
6705
6706
6707
6708
6709
6710
6711
6712
6713
6714
6715
6716
6717
6718
6719
6720
6721
6722
6723
6724
6725
6726
6727
6728
6729
6730
6731
6732
6733
6734
6735
6736
6737
6738
6739
6740
6741
6742
6743
6744
6745
6746
6747
6748
6749
6750
6751
6752
6753
6754
6755
6756
6757
6758
6759
6760
6761
6762
6763
6764
6765
6766
6767
6768
6769
6770
6771
6772
6773
6774
6775
6776
6777
6778
6779
6780
6781
6782
6783
6784
6785
6786
6787
6788
6789
6790
6791
6792
6793
6794
6795
6796
6797
6798
6799
6800
6801
6802
6803
6804
6805
6806
6807
6808
6809
6810
6811
6812
6813
6814
6815
6816
6817
6818
6819
6820
6821
6822
6823
6824
6825
6826
6827
6828
6829
6830
6831
6832
6833
6834
6835
6836
6837
6838
6839
6840
6841
6842
6843
6844
6845
6846
6847
6848
6849
6850
6851
6852
6853
6854
6855
6856
6857
6858
6859
6860
6861
6862
6863
6864
6865
6866
6867
6868
6869
6870
6871
6872
6873
6874
6875
6876
6877
6878
6879
6880
6881
6882
6883
6884
6885
6886
6887
6888
6889
6890
6891
6892
6893
6894
6895
6896
6897
6898
6899
6900
6901
6902
6903
6904
6905
6906
6907
6908
6909
6910
6911
6912
6913
6914
6915
6916
6917
6918
6919
6920
6921
6922
6923
6924
6925
6926
6927
6928
6929
6930
6931
6932
6933
6934
6935
6936
6937
6938
6939
6940
6941
6942
6943
6944
6945
6946
6947
6948
6949
6950
6951
6952
6953
6954
6955
6956
6957
6958
6959
6960
6961
6962
6963
6964
6965
6966
6967
6968
6969
6970
6971
6972
6973
6974
6975
6976
6977
6978
6979
6980
6981
6982
6983
6984
6985
6986
6987
6988
6989
6990
6991
6992
6993
6994
6995
6996
6997
6998
6999
7000
==== ssl-ciph.doc ========================================================
This is a quick high level summery of how things work now.
Each SSLv2 and SSLv3 cipher is composed of 4 major attributes plus a few extra
minor ones.
They are 'The key exchange algorithm', which is RSA for SSLv2 but can also
be Diffle-Hellman for SSLv3.
An 'Authenticion algorithm', which can be RSA, Diffle-Helman, DSS or
none.
The cipher
The MAC digest.
A cipher can also be an export cipher and is either an SSLv2 or a
SSLv3 ciphers.
To specify which ciphers to use, one can either specify all the ciphers,
one at a time, or use 'aliases' to specify the preference and order for
the ciphers.
There are a large number of aliases, but the most importaint are
kRSA, kDHr, kDHd and kEDH for key exchange types.
aRSA, aDSS, aNULL and aDH for authentication
DES, 3DES, RC4, RC2, IDEA and eNULL for ciphers
MD5, SHA0 and SHA1 digests
Now where this becomes interesting is that these can be put together to
specify the order and ciphers you wish to use.
To speed this up there are also aliases for certian groups of ciphers.
The main ones are
SSLv2 - all SSLv2 ciphers
SSLv3 - all SSLv3 ciphers
EXP - all export ciphers
LOW - all low strngth ciphers (no export ciphers, normally single DES)
MEDIUM - 128 bit encryption
HIGH - Triple DES
These aliases can be joined in a : separated list which specifies to
add ciphers, move them to the current location and delete them.
A simpler way to look at all of this is to use the 'ssleay ciphers -v' command.
The default library cipher spec is
!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP
which means, first, remove from consideration any ciphers that do not
authenticate. Next up, use ciphers using RC4 and RSA. Next include the HIGH,
MEDIUM and the LOW security ciphers. Finish up by adding all the export
ciphers on the end, then 'pull' all the SSLv2 and export ciphers to
the end of the list.
The results are
$ ssleay ciphers -v '!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP'
RC4-SHA SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=SHA1
RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5
EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1
EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1
DES-CBC3-SHA SSLv3 Kx=RSA Au=RSA Enc=3DES(168) Mac=SHA1
IDEA-CBC-MD5 SSLv3 Kx=RSA Au=RSA Enc=IDEA(128) Mac=SHA1
EDH-RSA-DES-CBC-SHA SSLv3 Kx=DH Au=RSA Enc=DES(56) Mac=SHA1
EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH Au=DSS Enc=DES(56) Mac=SHA1
DES-CBC-SHA SSLv3 Kx=RSA Au=RSA Enc=DES(56) Mac=SHA1
DES-CBC3-MD5 SSLv2 Kx=RSA Au=RSA Enc=3DES(168) Mac=MD5
DES-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=DES(56) Mac=MD5
IDEA-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=IDEA(128) Mac=MD5
RC2-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC2(128) Mac=MD5
RC4-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5
EXP-EDH-RSA-DES-CBC SSLv3 Kx=DH(512) Au=RSA Enc=DES(40) Mac=SHA1 export
EXP-EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(512) Au=DSS Enc=DES(40) Mac=SHA1 export
EXP-DES-CBC-SHA SSLv3 Kx=RSA(512) Au=RSA Enc=DES(40) Mac=SHA1 export
EXP-RC2-CBC-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export
EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export
EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
I would recoment people use the 'ssleay ciphers -v "text"'
command to check what they are going to use.
Anyway, I'm falling asleep here so I'll do some more tomorrow.
eric
==== ssl.doc ========================================================
SSL_CTX_sessions(SSL_CTX *ctx) - the session-id hash table.
/* Session-id cache stats */
SSL_CTX_sess_number
SSL_CTX_sess_connect
SSL_CTX_sess_connect_good
SSL_CTX_sess_accept
SSL_CTX_sess_accept_good
SSL_CTX_sess_hits
SSL_CTX_sess_cb_hits
SSL_CTX_sess_misses
SSL_CTX_sess_timeouts
/* Session-id application notification callbacks */
SSL_CTX_sess_set_new_cb
SSL_CTX_sess_get_new_cb
SSL_CTX_sess_set_get_cb
SSL_CTX_sess_get_get_cb
/* Session-id cache operation mode */
SSL_CTX_set_session_cache_mode
SSL_CTX_get_session_cache_mode
/* Set default timeout values to use. */
SSL_CTX_set_timeout
SSL_CTX_get_timeout
/* Global SSL initalisation informational callback */
SSL_CTX_set_info_callback
SSL_CTX_get_info_callback
SSL_set_info_callback
SSL_get_info_callback
/* If the SSL_accept/SSL_connect returned with -1, these indicate when
* we should re-call *.
SSL_want
SSL_want_nothing
SSL_want_read
SSL_want_write
SSL_want_x509_lookup
/* Where we are in SSL initalisation, used in non-blocking, perhaps
* have a look at ssl/bio_ssl.c */
SSL_state
SSL_is_init_finished
SSL_in_init
SSL_in_connect_init
SSL_in_accept_init
/* Used to set the 'inital' state so SSL_in_connect_init and SSL_in_accept_init
* can be used to work out which function to call. */
SSL_set_connect_state
SSL_set_accept_state
/* Where to look for certificates for authentication */
SSL_set_default_verify_paths /* calles SSL_load_verify_locations */
SSL_load_verify_locations
/* get info from an established connection */
SSL_get_session
SSL_get_certificate
SSL_get_SSL_CTX
SSL_CTX_new
SSL_CTX_free
SSL_new
SSL_clear
SSL_free
SSL_CTX_set_cipher_list
SSL_get_cipher
SSL_set_cipher_list
SSL_get_cipher_list
SSL_get_shared_ciphers
SSL_accept
SSL_connect
SSL_read
SSL_write
SSL_debug
SSL_get_read_ahead
SSL_set_read_ahead
SSL_set_verify
SSL_pending
SSL_set_fd
SSL_set_rfd
SSL_set_wfd
SSL_set_bio
SSL_get_fd
SSL_get_rbio
SSL_get_wbio
SSL_use_RSAPrivateKey
SSL_use_RSAPrivateKey_ASN1
SSL_use_RSAPrivateKey_file
SSL_use_PrivateKey
SSL_use_PrivateKey_ASN1
SSL_use_PrivateKey_file
SSL_use_certificate
SSL_use_certificate_ASN1
SSL_use_certificate_file
ERR_load_SSL_strings
SSL_load_error_strings
/* human readable version of the 'state' of the SSL connection. */
SSL_state_string
SSL_state_string_long
/* These 2 report what kind of IO operation the library was trying to
* perform last. Probably not very usefull. */
SSL_rstate_string
SSL_rstate_string_long
SSL_get_peer_certificate
SSL_SESSION_new
SSL_SESSION_print_fp
SSL_SESSION_print
SSL_SESSION_free
i2d_SSL_SESSION
d2i_SSL_SESSION
SSL_get_time
SSL_set_time
SSL_get_timeout
SSL_set_timeout
SSL_copy_session_id
SSL_set_session
SSL_CTX_add_session
SSL_CTX_remove_session
SSL_CTX_flush_sessions
BIO_f_ssl
/* used to hold information as to why a certificate verification failed */
SSL_set_verify_result
SSL_get_verify_result
/* can be used by the application to associate data with an SSL structure.
* It needs to be 'free()ed' by the application */
SSL_set_app_data
SSL_get_app_data
/* The following all set values that are kept in the SSL_CTX but
* are used as the default values when an SSL session is created.
* They are over writen by the relevent SSL_xxxx functions */
/* SSL_set_verify */
void SSL_CTX_set_default_verify
/* This callback, if set, totaly overrides the normal SSLeay verification
* functions and should return 1 on success and 0 on failure */
void SSL_CTX_set_cert_verify_callback
/* The following are the same as the equivilent SSL_xxx functions.
* Only one copy of this information is kept and if a particular
* SSL structure has a local override, it is totally separate structure.
*/
int SSL_CTX_use_RSAPrivateKey
int SSL_CTX_use_RSAPrivateKey_ASN1
int SSL_CTX_use_RSAPrivateKey_file
int SSL_CTX_use_PrivateKey
int SSL_CTX_use_PrivateKey_ASN1
int SSL_CTX_use_PrivateKey_file
int SSL_CTX_use_certificate
int SSL_CTX_use_certificate_ASN1
int SSL_CTX_use_certificate_file
==== ssl_ctx.doc ========================================================
This is now a bit dated, quite a few of the SSL_ functions could be
SSL_CTX_ functions. I will update this in the future. 30 Aug 1996
From eay@orb.mincom.oz.au Mon Dec 11 21:37:08 1995
Received: by orb.mincom.oz.au id AA00696
(5.65c/IDA-1.4.4 for eay); Mon, 11 Dec 1995 11:37:08 +1000
Date: Mon, 11 Dec 1995 11:37:08 +1000 (EST)
From: Eric Young <eay@mincom.oz.au>
X-Sender: eay@orb
To: sameer <sameer@c2.org>
Cc: Eric Young <eay@mincom.oz.au>
Subject: Re: PEM_readX509 oesn't seem to be working
In-Reply-To: <199512110102.RAA12521@infinity.c2.org>
Message-Id: <Pine.SOL.3.91.951211112115.28608D-100000@orb>
Mime-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Status: RO
X-Status:
On Sun, 10 Dec 1995, sameer wrote:
> OK, that's solved. I've found out that it is saying "no
> certificate set" in SSL_accept because s->conn == NULL
> so there is some place I need to initialize s->conn that I am
> not initializing it.
The full order of things for a server should be.
ctx=SSL_CTX_new();
/* The next line should not really be using ctx->cert but I'll leave it
* this way right now... I don't want a X509_ routine to know about an SSL
* structure, there should be an SSL_load_verify_locations... hmm, I may
* add it tonight.
*/
X509_load_verify_locations(ctx->cert,CAfile,CApath);
/* Ok now for each new connection we do the following */
con=SSL_new(ctx);
SSL_set_fd(con,s);
SSL_set_verify(con,verify,verify_callback);
/* set the certificate and private key to use. */
SSL_use_certificate_ASN1(con,X509_certificate);
SSL_use_RSAPrivateKey_ASN1(con,RSA_private_key);
SSL_accept(con);
SSL_read(con)/SSL_write(con);
There is a bit more than that but that is basically the structure.
Create a context and specify where to lookup certificates.
foreach connection
{
create a SSL structure
set the certificate and private key
do a SSL_accept
we should now be ok
}
eric
--
Eric Young | Signature removed since it was generating
AARNet: eay@mincom.oz.au | more followups than the message contents :-)
==== ssleay.doc ========================================================
SSLeay: a cryptographic kitchen sink.
1st December 1995
Way back at the start of April 1995, I was looking for a mindless
programming project. A friend of mine (Tim Hudson) said "why don't you do SSL,
it has DES encryption in it and I would not mind using it in a SSL telnet".
While it was true I had written a DES library in previous years, litle
did I know what an expansive task SSL would turn into.
First of all, the SSL protocol contains DES encryption. Well and good. My
DES library was fast and portable. It also contained the RSA's RC4 stream
cipher. Again, not a problem, some-one had just posted to sci.crypt
something that was claimed to be RC4. It also contained IDEA, I had the
specifications, not a problem to implement. MD5, an RFC, trivial, at most
I could spend a week or so trying to see if I could speed up the
implementation. All in all a nice set of ciphers.
Then the first 'expantion of the scope', RSA public key
encryption. Since I did not knowing a thing about public key encryption
or number theory, this appeared quite a daunting task. Just writing a
big number library would be problomatic in itself, let alone making it fast.
At this point the scope of 'implementing SSL' expands eponentialy.
First of all, the RSA private keys were being kept in ASN.1 format.
Thankfully the RSA PKCS series of documents explains this format. So I now
needed to be able to encode and decode arbitary ASN.1 objects. The Public
keys were embeded in X509 certificates. Hmm... these are not only
ASN.1 objects but they make up a heirachy of authentication. To
authenticate a X509 certificate one needs to retrieve it's issuers
certificate etc etc. Hmm..., so I also need to implement some kind
of certificate management software. I would also have to implement
software to authenticate certificates. At this point the support code made
the SSL part of my library look quite small.
Around this time, the first version of SSLeay was released.
Ah, but here was the problem, I was not happy with the code so far. As may
have become obvious, I had been treating all of this as a learning
exersize, so I have completely written the library myself. As such, due
to the way it had grown like a fungus, much of the library was not
'elagent' or neat. There were global and static variables all over the
place, the SSL part did not even handle non-blocking IO.
The Great rewrite began.
As of this point in time, the 'Great rewrite' has almost finished. So what
follows is an approximate list of what is actually SSLeay 0.5.0
/********* This needs to be updated for 0.6.0+ *************/
---
The library contains the following routines. Please note that most of these
functions are not specfic for SSL or any other particular cipher
implementation. I have tried to make all the routines as general purpose
as possible. So you should not think of this library as an SSL
implemtation, but rather as a library of cryptographic functions
that also contains SSL. I refer to each of these function groupings as
libraries since they are often capable of functioning as independant
libraries
First up, the general ciphers and message digests supported by the library.
MD2 rfc???, a standard 'by parts' interface to this algorithm.
MD5 rfc???, the same type of interface as for the MD2 library except a
different algorithm.
SHA THe Secure Hash Algorithm. Again the same type of interface as
MD2/MD5 except the digest is 20 bytes.
SHA1 The 'revised' version of SHA. Just about identical to SHA except
for one tweak of an inner loop.
DES This is my libdes library that has been floating around for the last
few years. It has been enhanced for no other reason than completeness.
It now supports ecb, cbc, cfb, ofb, cfb64, ofb64 in normal mode and
triple DES modes of ecb, cbc, cfb64 and ofb64. cfb64 and ofb64 are
functional interfaces to the 64 bit modes of cfb and ofb used in
such a way thay they function as single character interfaces.
RC4 The RSA Inc. stream cipher.
RC2 The RSA Inc. block cipher.
IDEA An implmentation of the IDEA cipher, the library supports ecb, cbc,
cfb64 and ofb64 modes of operation.
Now all the above mentioned ciphers and digests libraries support high
speed, minimal 'crap in the way' type interfaces. For fastest and
lowest level access, these routines should be used directly.
Now there was also the matter of public key crypto systems. These are
based on large integer arithmatic.
BN This is my large integer library. It supports all the normal
arithmentic operations. It uses malloc extensivly and as such has
no limits of the size of the numbers being manipulated. If you
wish to use 4000 bit RSA moduli, these routines will handle it.
This library also contains routines to 'generate' prime numbers and
to test for primality. The RSA and DH libraries sit on top of this
library. As of this point in time, I don't support SHA, but
when I do add it, it will just sit on top of the routines contained
in this library.
RSA This implements the RSA public key algorithm. It also contains
routines that will generate a new private/public key pair.
All the RSA functions conform to the PKCS#1 standard.
DH This is an implementation of the
Diffie-Hellman protocol. There are all the require routines for
the protocol, plus extra routines that can be used to generate a
strong prime for use with a specified generator. While this last
routine is not generally required by applications implementing DH,
It is present for completeness and because I thing it is much
better to be able to 'generate' your own 'magic' numbers as oposed
to using numbers suplied by others. I conform to the PKCS#3
standard where required.
You may have noticed the preceeding section mentions the 'generation' of
prime numbers. Now this requries the use of 'random numbers'.
RAND This psuedo-random number library is based on MD5 at it's core
and a large internal state (2k bytes). Once you have entered enough
seed data into this random number algorithm I don't feel
you will ever need to worry about it generating predictable output.
Due to the way I am writing a portable library, I have left the
issue of how to get good initial random seed data upto the
application but I do have support routines for saving and loading a
persistant random number state for use between program runs.
Now to make all these ciphers easier to use, a higher level
interface was required. In this form, the same function would be used to
encrypt 'by parts', via any one of the above mentioned ciphers.
EVP The Digital EnVeloPe library is quite large. At it's core are
function to perform encryption and decryption by parts while using
an initial parameter to specify which of the 17 different ciphers
or 4 different message digests to use. On top of these are implmented
the digital signature functions, sign, verify, seal and open.
Base64 encoding of binary data is also done in this library.
PEM rfc???? describe the format for Privacy Enhanced eMail.
As part of this standard, methods of encoding digital enveloped
data is an ascii format are defined. As such, I use a form of these
to encode enveloped data. While at this point in time full support
for PEM has not been built into the library, a minimal subset of
the secret key and Base64 encoding is present. These reoutines are
mostly used to Ascii encode binary data with a 'type' associated
with it and perhaps details of private key encryption used to
encrypt the data.
PKCS7 This is another Digital Envelope encoding standard which uses ASN.1
to encode the data. At this point in time, while there are some
routines to encode and decode this binary format, full support is
not present.
As Mentioned, above, there are several different ways to encode
data structures.
ASN1 This library is more a set of primatives used to encode the packing
and unpacking of data structures. It is used by the X509
certificate standard and by the PKCS standards which are used by
this library. It also contains routines for duplicating and signing
the structures asocisated with X509.
X509 The X509 library contains routines for packing and unpacking,
verifying and just about every thing else you would want to do with
X509 certificates.
PKCS7 PKCS-7 is a standard for encoding digital envelope data
structures. At this point in time the routines will load and save
DER forms of these structees. They need to be re-worked to support
the BER form which is the normal way PKCS-7 is encoded. If the
previous 2 sentances don't make much sense, don't worry, this
library is not used by this version of SSLeay anyway.
OBJ ASN.1 uses 'object identifiers' to identify objects. A set of
functions were requred to translate from ASN.1 to an intenger, to a
character string. This library provieds these translations
Now I mentioned an X509 library. X509 specified a hieachy of certificates
which needs to be traversed to authenticate particular certificates.
METH This library is used to push 'methods' of retrieving certificates
into the library. There are some supplied 'methods' with SSLeay
but applications can add new methods if they so desire.
This library has not been finished and is not being used in this
version.
Now all the above are required for use in the initial point of this project.
SSL The SSL protocol. This is a full implmentation of SSL v 2. It
support both server and client authentication. SSL v 3 support
will be added when the SSL v 3 specification is released in it's
final form.
Now quite a few of the above mentioned libraries rely on a few 'complex'
data structures. For each of these I have a library.
Lhash This is a hash table library which is used extensivly.
STACK An implemetation of a Stack data structure.
BUF A simple character array structure that also support a function to
check that the array is greater that a certain size, if it is not,
it is realloced so that is it.
TXT_DB A simple memory based text file data base. The application can specify
unique indexes that will be enforced at update time.
CONF Most of the programs written for this library require a configuration
file. Instead of letting programs constantly re-implment this
subsystem, the CONF library provides a consistant and flexable
interface to not only configuration files but also environment
variables.
But what about when something goes wrong?
The one advantage (and perhaps disadvantage) of all of these
functions being in one library was the ability to implement a
single error reporting system.
ERR This library is used to report errors. The error system records
library number, function number (in the library) and reason
number. Multiple errors can be reported so that an 'error' trace
is created. The errors can be printed in numeric or textual form.
==== ssluse.doc ========================================================
We have an SSL_CTX which contains global information for lots of
SSL connections. The session-id cache and the certificate verificate cache.
It also contains default values for use when certificates are used.
SSL_CTX
default cipher list
session-id cache
certificate cache
default session-id timeout period
New session-id callback
Required session-id callback
session-id stats
Informational callback
Callback that is set, overrides the SSLeay X509 certificate
verification
The default Certificate/Private Key pair
Default read ahead mode.
Default verify mode and verify callback. These are not used
if the over ride callback mentioned above is used.
Each SSL can have the following defined for it before a connection is made.
Certificate
Private key
Ciphers to use
Certificate verify mode and callback
IO object to use in the comunication.
Some 'read-ahead' mode information.
A previous session-id to re-use.
A connection is made by using SSL_connect or SSL_accept.
When non-blocking IO is being used, there are functions that can be used
to determin where and why the SSL_connect or SSL_accept did not complete.
This information can be used to recall the functions when the 'error'
condition has dissapeared.
After the connection has been made, information can be retrived about the
SSL session and the session-id values that have been decided upon.
The 'peer' certificate can be retrieved.
The session-id values include
'start time'
'timeout length'
==== stack.doc ========================================================
The stack data structure is used to store an ordered list of objects.
It is basically misnamed to call it a stack but it can function that way
and that is what I originally used it for. Due to the way element
pointers are kept in a malloc()ed array, the most efficient way to use this
structure is to add and delete elements from the end via sk_pop() and
sk_push(). If you wish to do 'lookups' sk_find() is quite efficient since
it will sort the stack (if required) and then do a binary search to lookup
the requested item. This sorting occurs automatically so just sk_push()
elements on the stack and don't worry about the order. Do remember that if
you do a sk_find(), the order of the elements will change.
You should never need to 'touch' this structure directly.
typedef struct stack_st
{
unsigned int num;
char **data;
int sorted;
unsigned int num_alloc;
int (*comp)();
} STACK;
'num' holds the number of elements in the stack, 'data' is the array of
elements. 'sorted' is 1 is the list has been sorted, 0 if not.
num_alloc is the number of 'nodes' allocated in 'data'. When num becomes
larger than num_alloc, data is realloced to a larger size.
If 'comp' is set, it is a function that is used to compare 2 of the items
in the stack. The function should return -1, 0 or 1, depending on the
ordering.
#define sk_num(sk) ((sk)->num)
#define sk_value(sk,n) ((sk)->data[n])
These 2 macros should be used to access the number of elements in the
'stack' and to access a pointer to one of the values.
STACK *sk_new(int (*c)());
This creates a new stack. If 'c', the comparison function, is not
specified, the various functions that operate on a sorted 'stack' will not
work (sk_find()). NULL is returned on failure.
void sk_free(STACK *);
This function free()'s a stack structure. The elements in the
stack will not be freed so one should 'pop' and free all elements from the
stack before calling this function or call sk_pop_free() instead.
void sk_pop_free(STACK *st; void (*func)());
This function calls 'func' for each element on the stack, passing
the element as the argument. sk_free() is then called to free the 'stack'
structure.
int sk_insert(STACK *sk,char *data,int where);
This function inserts 'data' into stack 'sk' at location 'where'.
If 'where' is larger that the number of elements in the stack, the element
is put at the end. This function tends to be used by other 'stack'
functions. Returns 0 on failure, otherwise the number of elements in the
new stack.
char *sk_delete(STACK *st,int loc);
Remove the item a location 'loc' from the stack and returns it.
Returns NULL if the 'loc' is out of range.
char *sk_delete_ptr(STACK *st, char *p);
If the data item pointed to by 'p' is in the stack, it is deleted
from the stack and returned. NULL is returned if the element is not in the
stack.
int sk_find(STACK *st,char *data);
Returns the location that contains a value that is equal to
the 'data' item. If the comparison function was not set, this function
does a linear search. This function actually qsort()s the stack if it is not
in order and then uses bsearch() to do the initial search. If the
search fails,, -1 is returned. For mutliple items with the same
value, the index of the first in the array is returned.
int sk_push(STACK *st,char *data);
Append 'data' to the stack. 0 is returned if there is a failure
(due to a malloc failure), else 1. This is
sk_insert(st,data,sk_num(st));
int sk_unshift(STACK *st,char *data);
Prepend 'data' to the front (location 0) of the stack. This is
sk_insert(st,data,0);
char *sk_shift(STACK *st);
Return and delete from the stack the first element in the stack.
This is sk_delete(st,0);
char *sk_pop(STACK *st);
Return and delete the last element on the stack. This is
sk_delete(st,sk_num(sk)-1);
void sk_zero(STACK *st);
Removes all items from the stack. It does not 'free'
pointers but is a quick way to clear a 'stack of references'.
==== threads.doc ========================================================
How to compile SSLeay for multi-threading.
Well basically it is quite simple, set the compiler flags and build.
I have only really done much testing under Solaris and Windows NT.
If you library supports localtime_r() and gmtime_r() add,
-DTHREADS to the makefile parameters. You can probably survive with out
this define unless you are going to have multiple threads generating
certificates at once. It will not affect the SSL side of things.
The approach I have taken to doing locking is to make the application provide
callbacks to perform locking and so that the SSLeay library can distinguish
between threads (for the error state).
To have a look at an example program, 'cd mt; vi mttest.c'.
To build under solaris, sh solaris.sh, for Windows NT or Windows 95,
win32.bat
This will build mttest which will fire up 10 threads that talk SSL
to each other 10 times.
To enable everything to work, the application needs to call
CRYPTO_set_id_callback(id_function);
CRYPTO_set_locking_callback(locking_function);
before any multithreading is started.
id_function does not need to be defined under Windows NT or 95, the
correct function will be called if it is not. Under unix, getpid()
is call if the id_callback is not defined, for Solaris this is wrong
(since threads id's are not pid's) but under Linux it is correct
(threads are just processes sharing the data segement).
The locking_callback is used to perform locking by the SSLeay library.
eg.
void solaris_locking_callback(mode,type,file,line)
int mode;
int type;
char *file;
int line;
{
if (mode & CRYPTO_LOCK)
mutex_lock(&(lock_cs[type]));
else
mutex_unlock(&(lock_cs[type]));
}
Now in this case I have used mutexes instead of read/write locks, since they
are faster and there are not many read locks in SSLeay, you may as well
always use write locks. file and line are __FILE__ and __LINE__ from
the compile and can be usefull when debugging.
Now as you can see, 'type' can be one of a range of values, these values are
defined in crypto/crypto.h
CRYPTO_get_lock_name(type) will return a text version of what the lock is.
There are CRYPTO_NUM_LOCKS locks required, so under solaris, the setup
for multi-threading can be
static mutex_t lock_cs[CRYPTO_NUM_LOCKS];
void thread_setup()
{
int i;
for (i=0; i<CRYPTO_NUM_LOCKS; i++)
mutex_init(&(lock_cs[i]),USYNC_THREAD,NULL);
CRYPTO_set_id_callback((unsigned long (*)())solaris_thread_id);
CRYPTO_set_locking_callback((void (*)())solaris_locking_callback);
}
As a final note, under Windows NT or Windows 95, you have to be careful
not to mix the various threaded, unthreaded and debug libraries.
Normally if they are mixed incorrectly, mttest will crash just after printing
out some usage statistics at the end. This is because the
different system libraries use different malloc routines and if
data is malloc()ed inside crypt32.dll or ssl32.dll and then free()ed by a
different library malloc, things get very confused.
The default SSLeay DLL builds use /MD, so if you use this on your
application, things will work as expected. If you use /MDd,
you will probably have to rebuild SSLeay using this flag.
I should modify util/mk1mf.pl so it does all this correctly, but
this has not been done yet.
One last warning. Because locking overheads are actually quite large, the
statistics collected against the SSL_CTX for successfull connections etc
are not locked when updated. This does make it possible for these
values to be slightly lower than they should be, if you are
running multithreaded on a multi-processor box, but this does not really
matter much.
==== txt_db.doc ========================================================
TXT_DB, a simple text based in memory database.
It holds rows of ascii data, for which the only special character is '\0'.
The rows can be of an unlimited length.
==== why.doc ========================================================
This file is more of a note for other people who wish to understand why
the build environment is the way it is :-).
The include files 'depend' as follows.
Each of
crypto/*/*.c includes crypto/cryptlib.h
ssl/*.c include ssl/ssl_locl.h
apps/*.c include apps/apps.h
crypto/cryptlib.h, ssl/ssl_locl.h and apps/apps.h
all include e_os.h which contains OS/environment specific information.
If you need to add something todo with a particular environment,
add it to this file. It is worth remembering that quite a few libraries,
like lhash, des, md, sha etc etc do not include crypto/cryptlib.h. This
is because these libraries should be 'independantly compilable' and so I
try to keep them this way.
e_os.h is not so much a part of SSLeay, as the placing in one spot all the
evil OS dependant muck.
I wanted to automate as many things as possible. This includes
error number generation. A
make errors
will scan the source files for error codes, append them to the correct
header files, and generate the functions to print the text version
of the error numbers. So don't even think about adding error numbers by
hand, put them in the form
XXXerr(XXXX_F_XXXX,YYYY_R_YYYY);
on line and it will be automatically picked up my a make errors.
In a similar vein, programs to be added into ssleay in the apps directory
just need to have an entry added to E_EXE in makefile.ssl and
everthing will work as expected. Don't edit progs.h by hand.
make links re-generates the symbolic links that are used. The reason why
I keep everything in its own directory, and don't put all the
test programs and header files in 'test' and 'include' is because I want
to keep the 'sub-libraries' independant. I still 'pull' out
indervidual libraries for use in specific projects where the code is
required. I have used the 'lhash' library in just about every software
project I have worked on :-).
make depend generates dependancies and
make dclean removes them.
You will notice that I use perl quite a bit when I could be using 'sed'.
The reason I decided to do this was to just stick to one 'extra' program.
For Windows NT, I have perl and no sed.
The util/mk1mf.pl program can be used to generate a single makefile.
I use this because makefiles under Microsoft are horrific.
Each C compiler seems to have different linker formats, which have
to be used because the retarted C compilers explode when you do
cl -o file *.o.
Now some would argue that I should just use the single makefile. I don't
like it during develoment for 2 reasons. First, the actuall make
command takes a long time. For my current setup, if I'm in
crypto/bn and I type make, only the crypto/bn directory gets rebuilt,
which is nice when you are modifying prototypes in bn.h which
half the SSLeay depends on. The second is that to add a new souce file
I just plonk it in at the required spot in the local makefile. This
then alows me to keep things local, I don't need to modify a 'global'
tables (the make for unix, the make for NT, the make for w31...).
When I am ripping apart a library structure, it is nice to only
have to worry about one directory :-).
Having said all this, for the hell of it I put together 2 files that
#include all the souce code (generated by doing a ls */*.o after a build).
crypto.c takes only 30 seconds to build under NT and 2 minutes under linux
for my pentium100. Much faster that the normal build :-).
Again, the problem is that when using libraries, every program linked
to libcrypto.a would suddenly get 330k of library when it may only need
1k. This technique does look like a nice way to do shared libraries though.
Oh yes, as a final note, to 'build' a distribution, I just type
make dist.
This cleans and packages everything. The directory needs to be called
SSLeay since the make does a 'cd ..' and renames and tars things up.
==== req.1 ========================================================
The 'req' command is used to manipulate and deal with pkcs#10
certificate requests.
It's default mode of operation is to load a certificate and then
write it out again.
By default the 'req' is read from stdin in 'PEM' format.
The -inform option can be used to specify 'pem' format or 'der'
format. PEM format is the base64 encoding of the DER format.
By default 'req' then writes the request back out. -outform can be used
to indicate the desired output format, be it 'pem' or 'der'.
To specify an input file, use the '-in' option and the '-out' option
can be used to specify the output file.
If you wish to perform a command and not output the certificate
request afterwards, use the '-noout' option.
When a certificate is loaded, it can be printed in a human readable
ascii format via the '-text' option.
To check that the signature on a certificate request is correct, use
the '-verify' option to make sure that the private key contained in the
certificate request corresponds to the signature.
Besides the default mode, there is also the 'generate a certificate
request' mode. There are several flags that trigger this mode.
-new will generate a new RSA key (if required) and then prompts
the user for details for the certificate request.
-newkey has an argument that is the number of bits to make the new
key. This function also triggers '-new'.
The '-new' option can have a key to use specified instead of having to
load one, '-key' is used to specify the file containg the key.
-keyform can be used to specify the format of the key. Only
'pem' and 'der' formats are supported, later, 'netscape' format may be added.
Finally there is the '-x509' options which makes req output a self
signed x509 certificate instead of a certificate request.
Now as you may have noticed, there are lots of default options that
cannot be specified via the command line. They are held in a 'template'
or 'configuration file'. The -config option specifies which configuration
file to use. See conf.doc for details on the syntax of this file.
The req command uses the 'req' section of the config file.
---
# The following variables are defined. For this example I will populate
# the various values
[ req ]
default_bits = 512 # default number of bits to use.
default_keyfile = testkey.pem # Where to write the generated keyfile
# if not specified.
distinguished_name= req_dn # The section that contains the
# information about which 'object' we
# want to put in the DN.
attributes = req_attr # The objects we want for the
# attributes field.
encrypt_rsa_key = no # Should we encrypt newly generated
# keys. I strongly recommend 'yes'.
# The distinguished name section. For the following entries, the
# object names must exist in the SSLeay header file objects.h. If they
# do not, they will be silently ignored. The entries have the following
# format.
# <object_name> => string to prompt with
# <object_name>_default => default value for people
# <object_name>_value => Automatically use this value for this field.
# <object_name>_min => minimum number of characters for data (def. 0)
# <object_name>_max => maximum number of characters for data (def. inf.)
# All of these entries are optional except for the first one.
[ req_dn ]
countryName = Country Name (2 letter code)
countryName_default = AU
stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName_default = Queensland
localityName = Locality Name (eg, city)
organizationName = Organization Name (eg, company)
organizationName_default = Mincom Pty Ltd
organizationalUnitName = Organizational Unit Name (eg, section)
organizationalUnitName_default = MTR
commonName = Common Name (eg, YOUR name)
commonName_max = 64
emailAddress = Email Address
emailAddress_max = 40
# The next section is the attributes section. This is exactly the
# same as for the previous section except that the resulting objects are
# put in the attributes field.
[ req_attr ]
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20
unstructuredName = An optional company name
----
Also note that the order that attributes appear in this file is the
order they will be put into the distinguished name.
Once this request has been generated, it can be sent to a CA for
certifying.
----
A few quick examples....
To generate a new request and a new key
req -new
To generate a new request and a 1058 bit key