'OpenSSL for Ruby 2' project
Copyright (C) 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'.)
$Id$
[WARNING]
[BIG FAT NOTE]
This 'README' is not up-to-date. For news check: 'ChangeLog' and 'ToDo' file.
['OpenSSL for Ruby' team members]
GOTOU Yuuzou <gotoyuzo@notwork.org> - SSL Socket implementation
Michal Rokos <m.rokos@sh.cvut.cz> - Errors, Memory leaks ;-) (maintainer)
[Contributors]
Technorama team <oss-ruby@technorama.net> - BN implementation core
Hynek Rostinsky <hynek.rostinsky@foresta.cz> - Windows platform fixes (strptime mainly)
[Requirements]
Ruby >= 1.7.2 (partially works with 1.6.8)
OpenSSL >= 0.9.6
[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
* Developers can use 'ruby extconf.rb --with-debug' (or --enable-debug)
[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>
---8<--- FROM NOW ON IT IS AN OLD FILE (= FOR OSSL1) ---8<---
[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
= PKCS#7 <-> S/MIME
= OCSP
[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
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(sPEM)
::read_smime(sSMIME) => oPKCS7
::write_smime(oPKCS7 [, sText, fFlags]) => sSMIME
::sign(oX509::Certificate, oPKey, sData [, Ary(X509::Certificate), fFlags]) #=> oPKCS7
::encrypt(Ary(X509::Certificate), sData, oCipher [, fFlags]) #=> oPKCS7
----------------------------------
.decrypt(oPKey, oX509::Certificate [, iFlags]) => sData
.verify(Ary(X509::Certificate), oX509::Store [, sData, fFlags]) => sData
.type=(a Symbol as PKCS#7)
.detached=(bDetached)
.detached? => bResult
.cipher=(oCipher::ANY) => oCipher::ANY
.add_signer(oPKCS7::Signer, oPKey::ANY) => self
.signers() => Ary(PKCS7::Signer)
.add_recipient(oX509::Certificate) => self
.add_certificate(oX509::Certificate) => self
.add_crl(oX509::CRL) => self
.add_data(sData) => self
.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::
SSLContext
::new([a Symbols as SSL methods])
----------------------------------
.cert=(aX509::Certificate)
.key=(aPKey)
.client_ca=(aX509::Certificate|Ary(X509::Certificate))
.ca_file=(a path of PEM file)
.ca_path=(a path of directory)
.timeout=(fTimeout)
.verify_mode=(fMode)
.verify_depth=(fDepth)
.verify_callback=(aProc)
.cert_store=(aX509::Store)
.options=(fOptions)
SSLSocket
::new(aIO [, aSSLContext])
----------------------------------
.to_io => aIO
.accept => self
.connect => self
.sysread(fLength) => aString
.syswrite(sData) => fSize
.sysclose => nil
.peer_cert => aX509::Certificate
.cert => aX509::Certificate
.cipher => Ary(sSipherName)
.state => sStateString
SSLError
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!
StoreContext - Doc TODO!
StoreError
OCSP::
Request - Doc TODO!
::new(sDER)
----------------------------------
.add_nonce([sValue])
.check_nonce(oBasicResponse) => fResult
.certid => oCertificateId
.sign(oX509::Certificate, oPKey [, Ary(X509::Certificate), fFlags])
.verify(oX509::Certificate, oX509::Store [, fFlags]) => fResult
.to_der => sDER
Response - Doc TODO!
::new
----------------------------------
.status => fStatus
.status_string => sStatus
.basic => oBasicResponse
.to_der => sDER
BasicResponse
::new(sDER)
----------------------------------
.copy_nonce(oRequest)
.add_nonce([sValue])
.add_status(oCertificateId, fStatus, fRevokeReason, tRevokeTime, tThisUpdate, tNextUpdate, Ary(X509::Extension))
.status => Ary(oCertificateId, fStatus, fRevokeReason, tRevokeTime, tThisUpdate, tNextUpdate, Ary(X509::Extension))
.sign(oX509::Certificate, aPKey [, Ary(X509::Certificate), fFlags])
.verify(oX509::Certificate, oX509::Store [, fFlags]) => fResult
CertificateId
::new(oX509::Certificate, oX509::Certificate)
----------------------------------
.cmp(oCertificateId) => bResult
.cmp_issuer(aCertificateId) => bResult
.serial => fSerialNumber
OCSPError
--------------------------------------------------
[Examples]
There are some braindead in 'test' directory
