$Id$
'OpenSSL for Ruby' project
Copyright (C) 2001-2002 Michal Rokos <m.rokos@sh.cvut.cz>
All rights reserved.
This program is licenced under the same licence as Ruby.
(See the file 'LICENCE'.)
['OpenSSL for Ruby' team members]
GOTOU Yuuzou <gotoyuzo@notwork.org> - SSL Socket implementation
Michal Rokos <m.rokos@sh.cvut.cz> - The rest (too long to enumerate), maintainer
[Contributors]
UNKNOWN <oss-ruby@technorama.net> - BN implementation core
Hynek Rostinsky <hynek.rostinsky@foresta.cz> - Windows platform fixes (strptime mainly)
[Done] (but not fully tested)
= PKey:: RSA,DSA keys - new, load, export
= X509::Certificate - generating new certs, load, looking inside
= X509::CRL - load, new, looking inside
= X509::Name - new, export, to_a, to_h (hash)
= X509::Revoked - new, looking inside (on parameters)
= X509::Store - new, import trusted certs and CRL, verifiing certs
= Digest::... - various hashes
= X509::Request - Cert requests
= X509::Attribute - as X509Request extensions (not tested)
= X509::Extension - to Certs, CRLs...
= X509::ExtensionMaker - for easy creating new Extensions
= Netscape::SPKI - for requests from NetscapeCommunicators
= Cipher::... - various ciphers
= basic PRNG functions (random generator) for OpenSSL module and class Random
= SSLSocket (merged Gotou Yuuzou's SSLsocket-Ruby project)
= PKCS7 (signing&data_verify is working, rest needs some testing)
= HMAC
= OpenSSL config file parser (part)
= BN (safe bignums)
= Diffie-Hellman
[To-Do]
= check for memory leaking :-))
= cleaner code
= examples
= RubyUnit to be used!
= API documentation
= comments to sources!!!
= further functionality to existing
= Std. Extensions, Attributes to be made as Classes?
= AttributeFactory?
= add aliases to to_pem as s_dump s_load to support Marshal module
= CipherFactory?
= autogen random IVs for Ciphers
= PKCS12
= PKCS8
= ASN.1 ???
= BIO ???
= compat tests for RSA/DSA sign/encrypt
[Requirements]
Ruby >= 1.6.4
OpenSSL >= 0.9.6b
[Instalation]
= Unix like systems:
ruby extconf.rb
make
su root -c make install
= Windows like systems:
add to %PATH%: c:\openssl\bin (where the dlls lays)
ruby extconf.rb --with-openssl-include=c:\openssl\include --with-openssl-lib=c:\openssl\lib
(or ruby extconf.rb --with-openssl-dir=c:\openssl (NOT TESTED))
nmake
nmake install
[Documentation/API]
Sorry, not done. See 'test' folder's examples and grep C sources for rb_define_*method :-))
--------------------------------------------------
=> XXX - XXX is return value
A <=> B - A is an alias to B
[XXX] - argument XXX is optional
A|B - argument can be A or B
bXXX - XXX is true or false
cXXX - XXX is defined as constant
fXXX - XXX is Fixnum
hXXX - XXX is Hash
nXXX - XXX is Number (Fixnum or Bignum)
oXXX - argument.kind_of?(XXX) => true
sXXX - XXX is String
tXXX - XXX is instance of Time
--------------------------------------------------
Integer
.to_bn() => BN.new
OpenSSL::
BN - Doc TODO!
::new(...)
--- PRIVATE ----------------------
.initialize(arg, type="dec")
.from_integer(arg, type="dec")
.from_string(arg, type="dec")
.from_bn(arg, dummy=nil)
.from_s_bin(sBIN)
.from_s_mpi(sMPI)
.from_s_dec(sDEC)
.from_s_hex(sHEX)
--- PUBLIC -----------------------
.to_s(type="dec") => sDEC
.to_s_bin() => sBIN
.to_s_mpi() => sMPI
.to_s_dec() => sDEC
.to_s_hex() => sHEX
BNError
Cipher::
constants: UNSPEC
modes: ECB, CFB, OFB, CBC
types: EDE, EDE3, BIT40, BIT64
BlowFish (allowed: ECB, CFB, OFB, CBC)
Cast5 (ECB, CFB, OFB, CBC)
DES (ECB, EDE, EDE3, CFB, CFB:EDE, CFB:EDE3, OFB, OFB:EDE, OFB:EDE3, CBC, CBC:EDE, CBC:EDE3)
Idea (ECB, CFB, OFB, CBC)
RC2 (ECB, CBC, BIT40:CBC, BIT64:CBC, CFB, OFB)
RC4 (nil, UNSPEC, BIT40)
RC5 (ECB, CFB, OFB, CBC)
::new([cMode|cType] [,cType|cMode])
----------------------------------
.encrypt(sPassword [, sInitVector]) => self
.decrypt(sPassword [, sInitVector]) => self
.update(sData) => s(En|De)crypted
.<< <=> .update
.cipher() => s(En|De)cryptedFinal
CipherError
Config
::new(sFilename) - dispatches .load
::load(sFilename)
----------------------------------
.get_value(sSection|nil, sKey) => sValue
.get_section(sSection) => hSection
ConfigError
Digest::
MD2
MD4
MD5
MDC2
RIPEMD160
SHA
SHA1
DSS
DSS1
::new([sData])
----------------------------------
.update(sData) => self
.<< <=> .update
.digest() => sDigestFinal
.hexdigest() => sHEXDigestFinal
.inspect <=> .hexdigest
.to_s <=> .hexdigest
DigestError
HMAC
::new(sKey, oDigest::ANY) => self
----------------------------------
.update(sData) => self
.<< <=> .update
.hmac() => sHMACFinal
.hexhmac() => sHEXHMACFinal
.inspect <=> .hexhmac
.to_s <=> .hexhmac
HMACError
Netscape::
SPKI
::new([sPEM])
----------------------------------
.to_pem() => sPEM
.to_s <=> .to_pem
.to_text() => sHumanReadable
.public_key() => oPKey::ANY
.public_key=(oPKey::ANY) => oPKey::ANY
.sign(oPKey::ANY, oDigest::ANY) => self
.verify(oPKey::ANY) => bResult
.challenge() => sChallenge
.challenge=(sChallenge) => sChallenge
SPKIError
PKCS7::
constants:
type: SIGNED, ENVELOPED, SIGNED_ENVELOPED
PKCS7
::new(cType|sPEM)
----------------------------------
.cipher=(oCipher::ANY) => oCipher::ANY
.add_signer(oPKCS7::Signer, oPKey::ANY) => self
.signers() => Array of PKCS7::Signer
.add_recipient(oX509::Certificate) => self
.add_certificate(oX509::Certificate) => self
.add_crl(oX509::CRL) => self
.add_data(sData [, bDetached]) => self
.verify_data(oX509::Store [, sDetachedData]) => bResult, yields PKCS7::Signer
.decode_data(oPKey::ANY, oX509::Certificate) => sData
.to_pem() => sPEM
.to_s <=> .to_pem
Signer
::new(oX509::Certificate, oPKey::ANY, oDigest::ANY)
----------------------------------
.name() => X509::Name
.serial() => fSerial
.signed_time() => tTime
PKCS7Error
PKey::
PKeyError
DH
::new((fLen|sPEM) [, fGenerator=2]) - dispatches .new_from_pem or .generate
::new_from_pem(sPEM)
::generate(fLen, fGenerator) - yields |p,n|
::new_from_fixnum <=> ::generate
----------------------------------
.public?() => bResult
.private?() => bResult
.to_text() => sHumanReadable
.export() => sPEM
.to_pem <=> .export
.public_key() => oPKey::ANY
DSA
::new([fKeyLen|sPEM [, sPassword]]) - dispatches .new_from_pem or .generate
::new_from_pem(sPEM [, sPassword])
::generate(fKeyLen) - yields |p,n|
::new_from_fixnum <=> generate
----------------------------------
.public?() => bResult
.private?() => bResult
.to_text() => sHumanReadable
.export([oCipher::ANY [, sPassword]]) => sPEM
.to_pem <=> .export
.public_key() => oPKey::DSA
.to_der() => sDER
.sign(oDigest::ANY, sData) => sSig
.sign_digest(sDigest) => sSig
.verify(oDigest::ANY, sData, sSig) => bResult
.verify_digest(sDigest, sSig) => bResult
DSAError
RSA
::new([fKeyLen|sPEM [, sPassword]]) - dispatches .new_from_pem or .generate
::new_from_pem(sPEM [, sPassword])
::generate(fKeyLen) - yields |p,n|
::new_from_fixnum <=> generate
----------------------------------
.public?() => bResult
.private?() => bResult
.to_text() => sHumanReadable
.export([oCipher::ANY [, sPassword]]) => sPEM
.to_pem <=> .export
.public_key() => oPKey::ANY
.public_encrypt(sData) => sEnc
.public_decrypt(sEnrypted) => sData
.private_encrypt(sData) => sEnc
.private_decrypt(sEncrypted) => sData
.to_der() => sDER
.sign(oDigest::ANY, sData) => sSig
.verify(oDigest::ANY, sData, sSig) => bResult
RSAError
Random
.seed(sSeed) => sSeed
.load_random_file(sFilename) => bResult
.write_random_file(sFilename) => bResult
.random_bytes(fLen) => sRandom
.egd(sUNIXSocketPath) => bResult
.egd_bytes(sUNIXSocketPath, fLen) => bResult
RandomError
SSL:: - Doc TODO!
Error
X509::
Attribute
::new(arg) - dispatches "new_from_#{arg.type.name.downcase}"
::new_from_string("oid = value")
::new_from_array(["oid", "value"])
::new_from_hash({"oid"=>"oid", "value"=>"val"})
----------------------------------
AttributeError
Certificate - Doc TODO!
.to_s <=> .to_pem
CertificateError
CRL - Doc TODO!
.to_s <=> .to_pem
CRLError
Extension - Doc TODO!
::new is DISABLED!
----------------------------------
.to_s => string as "oid = critical, value"
.to_a => ary as ["oid", "value", critical], critical as bool
.to_h => hash as {"oid"=>"oid", "value"=>"val", "critical"=>bool}
ExtensionFactory - Doc TODO!
::new(...)
----------------------------------
.create_extension(*arg)
.create_ext_from_string(str)
.create_ext_from_ary(ary) => X509::Extension, ary as ["oid", "value", critical], critical as bool
.create_ext_from_hash(hash)
ExtensionError
Name - Doc TODO!
::new(arg) dispatches "new_from_#{arg.type.name.downcase}"
::new_from_string(str) => self, str as "/A=B/C=D/E=F"
::new_from_array(ary) => self, ary as [["A","B"],["C","D"],["E","F"]]
::new_from_hash(hash) => self, hash as {"A"=>"B","C"=>"D","E"=>"F"}
----------------------------------
.to_s => str as "/A=B/C=D/E=F"
.to_a => ary as [["A","B"],["C","D"],["E","F"]]
.to_h => hash as {"A"=>"B","C"=>"D","E"=>"F"}
NameError
Request - Doc TODO!
.to_s <=> .to_pem
RequestError
Revoked
::new()
----------------------------------
serial() => nSerial
serial=(nSerial) => nSerial
time() => tRevoked
time=(tRevoked) => tRevoked
extensions() => Ary(X509::Extension)
extensions=(ary) => Ary(X509::Extension)
add_extension(oExtension) => oExtension
RevokedError
Store - Doc TODO!
StoreError
--------------------------------------------------
[Examples]
There are some braindead in 'test' directory
[Note]
All code is under development - API/method names can change
All feedback, bug reports, requests are welcomed!
Enjoy!
Michal <m.rokos@sh.cvut.cz>
