Wolf SSL JNI Manual

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 6

wolfSSLJNIManual
December4,2015,version1.4.0
Introduction
ThewolfSSLJNIpackageprovidesaJavainterfacetothewolfSSLSSL/TLSlibrary,providing
JavaapplicationswithSSL/TLSsupportuptothecurrentTLS1.2andDTLS1.2standards.
TheinterfaceisprovidedthroughtheuseofJNIandstandardJavapractices.Inadditiontothe
interface,thepackageprovidesanexampleclientandserver,writteninJava,whichutilizethe
interfacetomakeanSSL/TLSconnection.
AsthisinterfacewrapsaroundthenativewolfSSLlibrary,thisdocumentshouldbeusedin
referencetogetherwiththewolfSSLManual:
https://wolfssl.com/wolfSSL/Docswolfsslmanualtoc.html
TableofContents
1. GettingwolfSSLJNISourceCode
2. Requirements
3. PackageDesign
4. Building
5. Cleanup
6. Examples
7. APIDocumentation
8. License
9. Support
10. References
Copyright2015wolfSSLInc.Allrightsreserved.
GettingwolfSSLJNISourceCode
ThemostrecentversionofwolfSSLJNIcanbedownloadedfromthewolfSSLwebsiteasaZIP
filefromtheDownloadpage:
https://wolfssl.com/wolfSSL/download/downloadForm.php
Requirements
Tocompileandusethisinterface,usersmusthaveJavainstalledonthedevelopmentmachine.
PriortocompilingtheJNIwrapper,thewolfSSLlibrarymustbecompiledandinstalledina
locationwhichcanbefoundbytheJNIwrapper.ThisreleaseoftheJavawrapperhasbeen
testedagainstwolfSSL3.7.0.
Thepackageutilizestheantbuildsystemtomakecompilation,testing,anddocumentation
easierandmorestreamlined.Assuch,ifuserswishtousetheexistingantbuildscript,antwill
needtobeinstalledandavailableonthedevelopmentmachine.
JUnitisusedforunittests.JUnitwillneedtobeinstalledonthedevelopmentmachineinorder
forunitteststowork.UserscandownloadJUnitfromhttp://www.junit.org.
Afterdownloadingjunitx.x.jarandhamcrestcorex.x.jarfromtheJUnitwebsite,youmayneed
toaddthemtoyourclasspath.Forexample,onLinuxthiswouldbesimilarto:
$export
CLASSPATH=$CLASSPATH:/usr/share/java/junit4.12.jar:/usr/share/java/hamcrestco
re1.3.jar
WhenrunningJUnittests,thispackagewilllookforjunit4.12.jarandantjunit4.jaratthe
followinglocations:
$JUNIT_HOME/junit4.12.jar
$JUNIT_HOME/hamcrestcore1.3.jar
$JUNIT_HOME/ant/antjunit4.jar
Pleasesetthe$JUNIT_HOMEenvironmentvariabletomatchyoursystemwheretheabove
filesarelocated,ie:
$exportJUNIT_HOME=/usr/share/java
Copyright2015wolfSSLInc.Allrightsreserved.
PackageDesign
TheJavainterfacepackagehasthefollowingdirectorystructure.
<package_root>
build.xml (antbuildscript)
/docs (javadocs)
/examples (examples)
/certs (testcerts/keys)
java.sh (JNIgccscript)
/lib (outputdirectoryforcompiledJNIlibandJARfile)
/native (nativeJNIcode)
/src
/java (Javasources)
/test (testcode)
Building
wolfSSLwillneedtobecompiledandinstalledonthedevelopmentmachineusingthefollowing
buildoptions:
$cdwolfssl3.7.0
$./configureenablejni
$make
$sudomakeinstall
TocompiletheJNIinterface,runthefollowingcommandsfromtherootpackagedirectory.
$./java.sh (compilesnativeJNIsourcesintosharedlibrary)
$ant (compilesJavasources,javadocs,JNIheaders,JAR,andrunsavailabletests)
Thejava.shscripttriestodetectwhereJavaisinstalledonyoursystem,usingthejavaHome
variableinjava.shtostorethispath.IfyoursystemhasissuesfindingtheJavainstallationpath,
manualeditofthisvariablemaybenecessaryinjava.sh.
Cleanup
Tocleanthepackage,runthefollowingcommandsfromtherootdirectory:
antclean (cleansallJavasourcesand.JAR)
antcleanjni (cleansnativeobjectfilesandsharedlibrary)
Copyright2015wolfSSLInc.Allrightsreserved.
Examples
ThisinterfaceincludesanexampleserverandclientwritteninJavatoprovidedeveloperswitha
simpleusageexample.Theexampleclientandserverarelocatedinthe
<package_root>/examplesdirectory.Eachisaccompaniedbyawrapperscript.Thewrapper
scriptshouldbeusedwhenrunningtheprogramstomoreeasilysettheclasspathandlibrary
pathoptions.
Theexamplescanberunfromtherootpackagedirectoryusing:
./examples/server.sh
./examples/client.sh
Eachexampleprovidesseveralcommandlineoptionswhichcanbeusedtocustomizehowthe
example(s)run.Usethe“?”optiontoshowavailablecommandlineoptions:
Javaexampleserverusage:
? Help,printthisusage
p<num> Porttoconnectto,default11111
v<num> SSLversion[03],SSLv3(0)TLS1.2(3)),default3
l<str> Cipherlist
c<file> Certificatefile, default../certs/clientcert.pem
k<file> Keyfile, default../certs/clientkey.pem
A<file> CertificateAuthorityfile, default../certs/clientcert.pem
d Disablepeerchecks
s Usepresharedkeys
u UseUDPDTLS,addv2forDTLSv1(default),v3forDTLSv1.2
iocb EnabletestI/Ocallbacks
logtest Enabletestloggingcallback
o PerformOCSPlookuponpeercertificate
O<url> PerformOCSPlookupusing<url>asresponder
U AtomicUserRecordLayerCallbacks
P PublicKeyCallbacks
m EnableCRLdirectorymonitor
Theexamplesdemonstrateusageofseveralthings,includingusingcustomI/Ocallbacks,a
customverifycallback,DTLScookiegenerationcallback,AtomicRecordcallbacks,publickey
(ECC,RSA)callbacks,andPSKsupport.
Sourcesfortheexampleclientcanbefoundin<package_root>/examples/Client.javaandthe
exampleserverin<package_root>/examples/Server.java.CustomI/Ocallbackscanbefound
inMyRecvCallback.javaandMySendCallback.java,withtheI/Ocontextfoundin
MyIOContext.java.ThecustomverifycallbackcanbefoundinVerifyCallback.java.Examples
Copyright2015wolfSSLInc.Allrightsreserved.
ofatomicuserrecordlayercallbacksandpublickeycallbacksarealsoincludedinthe
<package_root>/examplesdirectory.
Theverifycallbackcurrentlyreturns1(failure),butdoesnoprocessingofthepeercertificate
chain.Arealworldapplicationwouldwanttodoanydesiredcertificateverificationprocessing
beforereturningfailureorsuccess.
CurrentlyDTLSusagerequirescustomI/OcallbacksandDTLScookiegenerationcallbackto
beregistered.ExamplesofthesecanbefoundinServer.javaandClient.java.
APIDocumentation
TheantbuildsystemcompilesuptodateJavadocswhenrun.Toviewthemostcurrent
Javadocsforthepackage,openthelocaljavadocsindexfileinawebbrowser.
<package_root>/docs/index.html
orbrowsetotheonlineversionat:
http://www.wolfssl.com/documentation/wolfssljnijavadocs/index.html
License
LikewolfSSL(wolfSSL),thispackageisduallicensedunderboththeGPLv2aswellasa
standardcommerciallicense.FulllicensedetailscanbefoundonthewolfSSLLicensingpage.
TheGPLv2licenseheaderincludedinthewolfSSLJNIdownloadpackageiscopiedbelow:
*Copyright(C)20062015wolfSSLInc.
*
*ThisfileispartofwolfSSL.
*
*wolfSSLisfreesoftware;youcanredistributeitand/ormodify
*itunderthetermsoftheGNUGeneralPublic.start();Licenseaspublishedby
*theFreeSoftwareFoundation;eitherversion2oftheLicense,or
*(atyouroption)anylaterversion.
*
*wolfSSLisdistributedinthehopethatitwillbeuseful,
*butWITHOUTANYWARRANTY;withouteventheimpliedwarrantyof
*MERCHANTABILITYorFITNESSFORAPARTICULARPURPOSE.Seethe
*GNUGeneralPublicLicenseformoredetails.
*
Copyright2015wolfSSLInc.Allrightsreserved.
*YoushouldhavereceivedacopyoftheGNUGeneralPublicLicense
*alongwiththisprogram;ifnot,writetotheFreeSoftware
*Foundation,Inc.,51FranklinStreet,FifthFloor,Boston,MA021101301,USA
Support
PleasesendquestionsorcommentstowolfSSLatsupport@wolfssl.com.
References
wolfSSLProductPage:https://wolfssl.com/wolfSSL/Productswolfssl.html
wolfSSLDocumentation:https://wolfssl.com/wolfSSL/Docs.html
wolfSSLManual:https://wolfssl.com/wolfSSL/Docswolfsslmanualtoc.html
Copyright2015wolfSSLInc.Allrightsreserved.

Navigation menu