ssl.h 468 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146514751485149515051515152515351545155515651575158515951605161516251635164516551665167516851695170517151725173517451755176517751785179518051815182518351845185518651875188518951905191519251935194519551965197519851995200520152025203520452055206520752085209521052115212521352145215521652175218521952205221522252235224522552265227522852295230523152325233523452355236523752385239524052415242524352445245524652475248524952505251525252535254525552565257525852595260526152625263526452655266526752685269527052715272527352745275527652775278527952805281528252835284528552865287528852895290529152925293529452955296529752985299530053015302530353045305530653075308530953105311531253135314531553165317531853195320532153225323532453255326532753285329533053315332533353345335533653375338533953405341534253435344534553465347534853495350535153525353535453555356535753585359536053615362536353645365536653675368536953705371537253735374537553765377537853795380538153825383538453855386538753885389539053915392539353945395539653975398539954005401540254035404540554065407540854095410541154125413541454155416541754185419542054215422542354245425542654275428542954305431543254335434543554365437543854395440544154425443544454455446544754485449545054515452545354545455545654575458545954605461546254635464546554665467546854695470547154725473547454755476547754785479548054815482548354845485548654875488548954905491549254935494549554965497549854995500550155025503550455055506550755085509551055115512551355145515551655175518551955205521552255235524552555265527552855295530553155325533553455355536553755385539554055415542554355445545554655475548554955505551555255535554555555565557555855595560556155625563556455655566556755685569557055715572557355745575557655775578557955805581558255835584558555865587558855895590559155925593559455955596559755985599560056015602560356045605560656075608560956105611561256135614561556165617561856195620562156225623562456255626562756285629563056315632563356345635563656375638563956405641564256435644564556465647564856495650565156525653565456555656565756585659566056615662566356645665566656675668566956705671567256735674567556765677567856795680568156825683568456855686568756885689569056915692569356945695569656975698569957005701570257035704570557065707570857095710571157125713571457155716571757185719572057215722572357245725572657275728572957305731573257335734573557365737573857395740574157425743574457455746574757485749575057515752575357545755575657575758575957605761576257635764576557665767576857695770577157725773577457755776577757785779578057815782578357845785578657875788578957905791579257935794579557965797579857995800580158025803580458055806580758085809581058115812581358145815581658175818581958205821582258235824582558265827582858295830583158325833583458355836583758385839584058415842584358445845584658475848584958505851585258535854585558565857585858595860586158625863586458655866586758685869587058715872587358745875587658775878587958805881588258835884588558865887588858895890589158925893589458955896589758985899590059015902590359045905590659075908590959105911591259135914591559165917591859195920592159225923592459255926592759285929593059315932593359345935593659375938593959405941594259435944594559465947594859495950595159525953595459555956595759585959596059615962596359645965596659675968596959705971597259735974597559765977597859795980598159825983598459855986598759885989599059915992599359945995599659975998599960006001600260036004600560066007600860096010601160126013601460156016601760186019602060216022602360246025602660276028602960306031603260336034603560366037603860396040604160426043604460456046604760486049605060516052605360546055605660576058605960606061606260636064606560666067606860696070607160726073607460756076607760786079608060816082608360846085608660876088608960906091609260936094609560966097609860996100610161026103610461056106610761086109611061116112611361146115611661176118611961206121612261236124612561266127612861296130613161326133613461356136613761386139614061416142614361446145614661476148614961506151615261536154615561566157615861596160616161626163616461656166616761686169617061716172617361746175617661776178617961806181618261836184618561866187618861896190619161926193619461956196619761986199620062016202620362046205620662076208620962106211621262136214621562166217621862196220622162226223622462256226622762286229623062316232623362346235623662376238623962406241624262436244624562466247624862496250625162526253625462556256625762586259626062616262626362646265626662676268626962706271627262736274627562766277627862796280628162826283628462856286628762886289629062916292629362946295629662976298629963006301630263036304630563066307630863096310631163126313631463156316631763186319632063216322632363246325632663276328632963306331633263336334633563366337633863396340634163426343634463456346634763486349635063516352635363546355635663576358635963606361636263636364636563666367636863696370637163726373637463756376637763786379638063816382638363846385638663876388638963906391639263936394639563966397639863996400640164026403640464056406640764086409641064116412641364146415641664176418641964206421642264236424642564266427642864296430643164326433643464356436643764386439644064416442644364446445644664476448644964506451645264536454645564566457645864596460646164626463646464656466646764686469647064716472647364746475647664776478647964806481648264836484648564866487648864896490649164926493649464956496649764986499650065016502650365046505650665076508650965106511651265136514651565166517651865196520652165226523652465256526652765286529653065316532653365346535653665376538653965406541654265436544654565466547654865496550655165526553655465556556655765586559656065616562656365646565656665676568656965706571657265736574657565766577657865796580658165826583658465856586658765886589659065916592659365946595659665976598659966006601660266036604660566066607660866096610661166126613661466156616661766186619662066216622662366246625662666276628662966306631663266336634663566366637663866396640664166426643664466456646664766486649665066516652665366546655665666576658665966606661666266636664666566666667666866696670667166726673667466756676667766786679668066816682668366846685668666876688668966906691669266936694669566966697669866996700670167026703670467056706670767086709671067116712671367146715671667176718671967206721672267236724672567266727672867296730673167326733673467356736673767386739674067416742674367446745674667476748674967506751675267536754675567566757675867596760676167626763676467656766676767686769677067716772677367746775677667776778677967806781678267836784678567866787678867896790679167926793679467956796679767986799680068016802680368046805680668076808680968106811681268136814681568166817681868196820682168226823682468256826682768286829683068316832683368346835683668376838683968406841684268436844684568466847684868496850685168526853685468556856685768586859686068616862686368646865686668676868686968706871687268736874687568766877687868796880688168826883688468856886688768886889689068916892689368946895689668976898689969006901690269036904690569066907690869096910691169126913691469156916691769186919692069216922692369246925692669276928692969306931693269336934693569366937693869396940694169426943694469456946694769486949695069516952695369546955695669576958695969606961696269636964696569666967696869696970697169726973697469756976697769786979698069816982698369846985698669876988698969906991699269936994699569966997699869997000700170027003700470057006700770087009701070117012701370147015701670177018701970207021702270237024702570267027702870297030703170327033703470357036703770387039704070417042704370447045704670477048704970507051705270537054705570567057705870597060706170627063706470657066706770687069707070717072707370747075707670777078707970807081708270837084708570867087708870897090709170927093709470957096709770987099710071017102710371047105710671077108710971107111711271137114711571167117711871197120712171227123712471257126712771287129713071317132713371347135713671377138713971407141714271437144714571467147714871497150715171527153715471557156715771587159716071617162716371647165716671677168716971707171717271737174717571767177717871797180718171827183718471857186718771887189719071917192719371947195719671977198719972007201720272037204720572067207720872097210721172127213721472157216721772187219722072217222722372247225722672277228722972307231723272337234723572367237723872397240724172427243724472457246724772487249725072517252725372547255725672577258725972607261726272637264726572667267726872697270727172727273727472757276727772787279728072817282728372847285728672877288728972907291729272937294729572967297729872997300730173027303730473057306730773087309731073117312731373147315731673177318731973207321732273237324732573267327732873297330733173327333733473357336733773387339734073417342734373447345734673477348734973507351735273537354735573567357735873597360736173627363736473657366736773687369737073717372737373747375737673777378737973807381738273837384738573867387738873897390739173927393739473957396739773987399740074017402740374047405740674077408740974107411741274137414741574167417741874197420742174227423742474257426742774287429743074317432743374347435743674377438743974407441744274437444744574467447744874497450745174527453745474557456745774587459746074617462746374647465746674677468746974707471747274737474747574767477747874797480748174827483748474857486748774887489749074917492749374947495749674977498749975007501750275037504750575067507750875097510751175127513751475157516751775187519752075217522752375247525752675277528752975307531753275337534753575367537753875397540754175427543754475457546754775487549755075517552755375547555755675577558755975607561756275637564756575667567756875697570757175727573757475757576757775787579758075817582758375847585758675877588758975907591759275937594759575967597759875997600760176027603760476057606760776087609761076117612761376147615761676177618761976207621762276237624762576267627762876297630763176327633763476357636763776387639764076417642764376447645764676477648764976507651765276537654765576567657765876597660766176627663766476657666766776687669767076717672767376747675767676777678767976807681768276837684768576867687768876897690769176927693769476957696769776987699770077017702770377047705770677077708770977107711771277137714771577167717771877197720772177227723772477257726772777287729773077317732773377347735773677377738773977407741774277437744774577467747774877497750775177527753775477557756775777587759776077617762776377647765776677677768776977707771777277737774777577767777777877797780778177827783778477857786778777887789779077917792779377947795779677977798779978007801780278037804780578067807780878097810781178127813781478157816781778187819782078217822782378247825782678277828782978307831783278337834783578367837783878397840784178427843784478457846784778487849785078517852785378547855785678577858785978607861786278637864786578667867786878697870787178727873787478757876787778787879788078817882788378847885788678877888788978907891789278937894789578967897789878997900790179027903790479057906790779087909791079117912791379147915791679177918791979207921792279237924792579267927792879297930793179327933793479357936793779387939794079417942794379447945794679477948794979507951795279537954795579567957795879597960796179627963796479657966796779687969797079717972797379747975797679777978797979807981798279837984798579867987798879897990799179927993799479957996799779987999800080018002800380048005800680078008800980108011801280138014801580168017801880198020802180228023802480258026802780288029803080318032803380348035803680378038803980408041804280438044804580468047804880498050805180528053805480558056805780588059806080618062806380648065806680678068806980708071807280738074807580768077807880798080808180828083808480858086808780888089809080918092809380948095809680978098809981008101810281038104810581068107810881098110811181128113811481158116811781188119812081218122812381248125812681278128812981308131813281338134813581368137813881398140814181428143814481458146814781488149815081518152815381548155815681578158815981608161816281638164816581668167816881698170817181728173817481758176817781788179818081818182818381848185818681878188818981908191819281938194819581968197819881998200820182028203820482058206820782088209821082118212821382148215821682178218821982208221822282238224822582268227822882298230823182328233823482358236823782388239824082418242824382448245824682478248824982508251825282538254825582568257825882598260826182628263826482658266826782688269827082718272827382748275827682778278827982808281828282838284828582868287828882898290829182928293829482958296829782988299830083018302830383048305830683078308830983108311831283138314831583168317831883198320832183228323832483258326832783288329833083318332833383348335833683378338833983408341834283438344834583468347834883498350835183528353835483558356835783588359836083618362836383648365836683678368836983708371837283738374837583768377837883798380838183828383838483858386838783888389839083918392839383948395839683978398839984008401840284038404840584068407840884098410841184128413841484158416841784188419842084218422842384248425842684278428842984308431843284338434843584368437843884398440844184428443844484458446844784488449845084518452845384548455845684578458845984608461846284638464846584668467846884698470847184728473847484758476847784788479848084818482848384848485848684878488848984908491849284938494849584968497849884998500850185028503850485058506850785088509851085118512851385148515851685178518851985208521852285238524852585268527852885298530853185328533853485358536853785388539854085418542854385448545854685478548854985508551855285538554855585568557855885598560856185628563856485658566856785688569857085718572857385748575857685778578857985808581858285838584858585868587858885898590859185928593859485958596859785988599860086018602860386048605860686078608860986108611861286138614861586168617861886198620862186228623862486258626862786288629863086318632863386348635863686378638863986408641864286438644864586468647864886498650865186528653865486558656865786588659866086618662866386648665866686678668866986708671867286738674867586768677867886798680868186828683868486858686868786888689869086918692869386948695869686978698869987008701870287038704870587068707870887098710871187128713871487158716871787188719872087218722872387248725872687278728872987308731873287338734873587368737873887398740874187428743874487458746874787488749875087518752875387548755875687578758875987608761876287638764876587668767876887698770877187728773877487758776877787788779878087818782878387848785878687878788878987908791879287938794879587968797879887998800880188028803880488058806880788088809881088118812881388148815881688178818881988208821882288238824882588268827882888298830883188328833883488358836883788388839884088418842884388448845884688478848884988508851885288538854885588568857885888598860886188628863886488658866886788688869887088718872887388748875887688778878887988808881888288838884888588868887888888898890889188928893889488958896889788988899890089018902890389048905890689078908890989108911891289138914891589168917891889198920892189228923892489258926892789288929893089318932893389348935893689378938893989408941894289438944894589468947894889498950895189528953895489558956895789588959896089618962896389648965896689678968896989708971897289738974897589768977897889798980898189828983898489858986898789888989899089918992899389948995899689978998899990009001900290039004900590069007900890099010901190129013901490159016901790189019902090219022902390249025902690279028902990309031903290339034903590369037903890399040904190429043904490459046904790489049905090519052905390549055905690579058905990609061906290639064906590669067906890699070907190729073907490759076907790789079908090819082908390849085908690879088908990909091909290939094909590969097909890999100910191029103910491059106910791089109911091119112911391149115911691179118911991209121912291239124912591269127912891299130913191329133913491359136913791389139914091419142914391449145914691479148914991509151915291539154915591569157915891599160916191629163916491659166916791689169917091719172917391749175917691779178917991809181918291839184918591869187918891899190919191929193919491959196919791989199920092019202920392049205920692079208920992109211921292139214921592169217921892199220922192229223922492259226922792289229923092319232923392349235923692379238923992409241924292439244924592469247924892499250925192529253925492559256925792589259926092619262926392649265926692679268926992709271927292739274927592769277927892799280928192829283928492859286928792889289929092919292929392949295929692979298929993009301930293039304930593069307930893099310931193129313931493159316931793189319932093219322932393249325932693279328932993309331933293339334933593369337933893399340934193429343934493459346934793489349935093519352935393549355935693579358935993609361936293639364936593669367936893699370937193729373937493759376937793789379938093819382938393849385938693879388938993909391939293939394939593969397939893999400940194029403940494059406940794089409941094119412941394149415941694179418941994209421942294239424942594269427942894299430943194329433943494359436943794389439944094419442944394449445944694479448944994509451945294539454945594569457945894599460946194629463946494659466946794689469947094719472947394749475947694779478947994809481948294839484948594869487948894899490949194929493949494959496949794989499950095019502950395049505950695079508950995109511951295139514951595169517951895199520952195229523952495259526952795289529953095319532953395349535953695379538953995409541954295439544954595469547954895499550955195529553955495559556955795589559956095619562956395649565956695679568956995709571957295739574957595769577957895799580958195829583958495859586958795889589959095919592959395949595959695979598959996009601960296039604960596069607960896099610961196129613961496159616961796189619962096219622962396249625962696279628962996309631963296339634963596369637963896399640964196429643964496459646964796489649965096519652965396549655965696579658965996609661966296639664966596669667966896699670967196729673967496759676967796789679968096819682968396849685968696879688968996909691969296939694969596969697969896999700970197029703970497059706970797089709971097119712971397149715971697179718971997209721972297239724972597269727972897299730973197329733973497359736973797389739974097419742974397449745974697479748974997509751975297539754975597569757975897599760976197629763976497659766976797689769977097719772977397749775977697779778977997809781978297839784978597869787978897899790979197929793979497959796979797989799980098019802980398049805980698079808980998109811981298139814981598169817981898199820982198229823982498259826982798289829983098319832983398349835983698379838983998409841984298439844984598469847984898499850985198529853985498559856985798589859986098619862986398649865986698679868986998709871987298739874987598769877987898799880988198829883988498859886988798889889989098919892989398949895989698979898989999009901990299039904990599069907990899099910991199129913991499159916991799189919992099219922992399249925992699279928992999309931993299339934993599369937993899399940994199429943994499459946994799489949995099519952995399549955995699579958995999609961996299639964996599669967996899699970997199729973997499759976997799789979998099819982998399849985998699879988998999909991999299939994999599969997999899991000010001100021000310004100051000610007100081000910010100111001210013100141001510016100171001810019100201002110022100231002410025100261002710028100291003010031100321003310034100351003610037100381003910040100411004210043100441004510046100471004810049100501005110052100531005410055100561005710058100591006010061100621006310064100651006610067100681006910070100711007210073100741007510076100771007810079100801008110082100831008410085100861008710088100891009010091100921009310094100951009610097100981009910100101011010210103101041010510106101071010810109101101011110112101131011410115101161011710118101191012010121101221012310124101251012610127101281012910130101311013210133101341013510136101371013810139101401014110142101431014410145101461014710148101491015010151101521015310154101551015610157101581015910160101611016210163101641016510166101671016810169101701017110172101731017410175101761017710178101791018010181101821018310184101851018610187101881018910190101911019210193101941019510196101971019810199102001020110202102031020410205102061020710208102091021010211102121021310214102151021610217102181021910220102211022210223102241022510226102271022810229102301023110232102331023410235102361023710238102391024010241102421024310244102451024610247102481024910250102511025210253102541025510256102571025810259102601026110262102631026410265102661026710268102691027010271102721027310274102751027610277102781027910280102811028210283102841028510286102871028810289102901029110292102931029410295102961029710298102991030010301103021030310304103051030610307103081030910310103111031210313103141031510316103171031810319103201032110322103231032410325103261032710328103291033010331103321033310334103351033610337103381033910340103411034210343103441034510346103471034810349103501035110352103531035410355103561035710358103591036010361103621036310364103651036610367103681036910370103711037210373103741037510376103771037810379103801038110382103831038410385103861038710388103891039010391103921039310394103951039610397103981039910400104011040210403104041040510406104071040810409104101041110412104131041410415104161041710418104191042010421104221042310424104251042610427104281042910430104311043210433104341043510436104371043810439104401044110442104431044410445104461044710448104491045010451104521045310454104551045610457104581045910460104611046210463104641046510466104671046810469104701047110472104731047410475104761047710478104791048010481104821048310484104851048610487104881048910490104911049210493104941049510496104971049810499105001050110502105031050410505105061050710508105091051010511105121051310514105151051610517105181051910520105211052210523105241052510526105271052810529105301053110532105331053410535105361053710538105391054010541105421054310544105451054610547105481054910550105511055210553105541055510556105571055810559105601056110562105631056410565105661056710568105691057010571105721057310574105751057610577105781057910580105811058210583105841058510586105871058810589105901059110592105931059410595105961059710598105991060010601106021060310604106051060610607106081060910610106111061210613106141061510616106171061810619106201062110622106231062410625106261062710628106291063010631106321063310634106351063610637106381063910640106411064210643106441064510646106471064810649106501065110652106531065410655106561065710658106591066010661106621066310664106651066610667106681066910670106711067210673106741067510676106771067810679106801068110682106831068410685106861068710688106891069010691106921069310694106951069610697106981069910700107011070210703107041070510706107071070810709107101071110712107131071410715107161071710718107191072010721107221072310724107251072610727107281072910730107311073210733107341073510736107371073810739107401074110742107431074410745107461074710748107491075010751107521075310754107551075610757107581075910760107611076210763107641076510766107671076810769107701077110772107731077410775107761077710778107791078010781107821078310784107851078610787107881078910790107911079210793107941079510796107971079810799108001080110802108031080410805108061080710808108091081010811108121081310814108151081610817108181081910820108211082210823108241082510826108271082810829108301083110832108331083410835108361083710838108391084010841108421084310844108451084610847108481084910850108511085210853108541085510856108571085810859108601086110862108631086410865108661086710868108691087010871108721087310874108751087610877108781087910880108811088210883108841088510886108871088810889108901089110892108931089410895108961089710898108991090010901109021090310904109051090610907109081090910910109111091210913109141091510916109171091810919109201092110922109231092410925109261092710928109291093010931109321093310934109351093610937109381093910940109411094210943109441094510946109471094810949109501095110952109531095410955109561095710958109591096010961109621096310964109651096610967109681096910970109711097210973109741097510976109771097810979109801098110982109831098410985109861098710988109891099010991109921099310994109951099610997109981099911000110011100211003110041100511006110071100811009110101101111012110131101411015110161101711018110191102011021110221102311024110251102611027110281102911030110311103211033110341103511036110371103811039110401104111042110431104411045110461104711048110491105011051110521105311054110551105611057110581105911060110611106211063110641106511066110671106811069110701107111072110731107411075110761107711078110791108011081110821108311084110851108611087110881108911090110911109211093110941109511096110971109811099111001110111102111031110411105111061110711108111091111011111111121111311114111151111611117111181111911120111211112211123111241112511126111271112811129111301113111132111331113411135111361113711138111391114011141111421114311144111451114611147111481114911150111511115211153111541115511156111571115811159111601116111162111631116411165111661116711168111691117011171111721117311174111751117611177111781117911180111811118211183111841118511186111871118811189111901119111192111931119411195111961119711198111991120011201112021120311204112051120611207112081120911210112111121211213112141121511216112171121811219112201122111222112231122411225112261122711228112291123011231112321123311234112351123611237112381123911240112411124211243112441124511246112471124811249112501125111252112531125411255112561125711258112591126011261112621126311264112651126611267112681126911270112711127211273112741127511276112771127811279112801128111282112831128411285112861128711288112891129011291112921129311294112951129611297112981129911300113011130211303113041130511306113071130811309113101131111312113131131411315113161131711318113191132011321113221132311324113251132611327113281132911330113311133211333113341133511336113371133811339113401134111342113431134411345113461134711348113491135011351113521135311354113551135611357113581135911360113611136211363113641136511366113671136811369113701137111372113731137411375113761137711378113791138011381113821138311384113851138611387113881138911390113911139211393113941139511396113971139811399114001140111402114031140411405114061140711408114091141011411114121141311414114151141611417114181141911420114211142211423114241142511426114271142811429114301143111432114331143411435114361143711438114391144011441114421144311444114451144611447114481144911450114511145211453114541145511456114571145811459114601146111462114631146411465114661146711468114691147011471114721147311474114751147611477114781147911480114811148211483114841148511486114871148811489114901149111492114931149411495114961149711498114991150011501115021150311504115051150611507115081150911510115111151211513115141151511516115171151811519115201152111522115231152411525115261152711528115291153011531115321153311534115351153611537115381153911540115411154211543115441154511546115471154811549115501155111552115531155411555115561155711558115591156011561115621156311564115651156611567115681156911570115711157211573115741157511576115771157811579115801158111582115831158411585115861158711588115891159011591115921159311594115951159611597115981159911600116011160211603116041160511606116071160811609116101161111612116131161411615116161161711618116191162011621116221162311624116251162611627116281162911630116311163211633116341163511636116371163811639116401164111642116431164411645116461164711648116491165011651116521165311654116551165611657116581165911660116611166211663116641166511666116671166811669116701167111672116731167411675116761167711678116791168011681116821168311684116851168611687116881168911690116911169211693116941169511696116971169811699117001170111702117031170411705117061170711708117091171011711117121171311714117151171611717117181171911720117211172211723117241172511726117271172811729117301173111732117331173411735117361173711738117391174011741117421174311744117451174611747117481174911750117511175211753117541175511756117571175811759117601176111762117631176411765117661176711768117691177011771117721177311774117751177611777117781177911780117811178211783117841178511786117871178811789117901179111792117931179411795117961179711798117991180011801118021180311804118051180611807118081180911810118111181211813118141181511816118171181811819118201182111822118231182411825118261182711828118291183011831118321183311834118351183611837118381183911840118411184211843118441184511846118471184811849118501185111852118531185411855118561185711858118591186011861118621186311864118651186611867118681186911870118711187211873118741187511876118771187811879118801188111882118831188411885118861188711888118891189011891118921189311894118951189611897118981189911900119011190211903119041190511906119071190811909119101191111912119131191411915119161191711918119191192011921119221192311924119251192611927119281192911930119311193211933119341193511936119371193811939119401194111942119431194411945119461194711948119491195011951119521195311954119551195611957119581195911960119611196211963119641196511966119671196811969119701197111972119731197411975119761197711978119791198011981119821198311984119851198611987119881198911990119911199211993119941199511996119971199811999120001200112002120031200412005120061200712008120091201012011120121201312014120151201612017120181201912020120211202212023120241202512026120271202812029120301203112032120331203412035120361203712038120391204012041120421204312044120451204612047120481204912050120511205212053120541205512056120571205812059120601206112062120631206412065120661206712068120691207012071120721207312074120751207612077120781207912080120811208212083120841208512086120871208812089120901209112092120931209412095120961209712098120991210012101121021210312104121051210612107121081210912110121111211212113121141211512116121171211812119121201212112122121231212412125121261212712128121291213012131121321213312134121351213612137121381213912140121411214212143121441214512146121471214812149121501215112152121531215412155121561215712158121591216012161121621216312164121651216612167121681216912170121711217212173121741217512176121771217812179121801218112182121831218412185121861218712188121891219012191121921219312194121951219612197121981219912200122011220212203122041220512206122071220812209122101221112212122131221412215122161221712218122191222012221122221222312224122251222612227122281222912230122311223212233122341223512236122371223812239122401224112242122431224412245122461224712248122491225012251122521225312254122551225612257122581225912260122611226212263122641226512266122671226812269122701227112272122731227412275122761227712278122791228012281122821228312284122851228612287122881228912290122911229212293122941229512296122971229812299123001230112302123031230412305123061230712308123091231012311123121231312314123151231612317123181231912320123211232212323123241232512326123271232812329123301233112332123331233412335123361233712338123391234012341123421234312344123451234612347123481234912350123511235212353123541235512356123571235812359123601236112362123631236412365123661236712368123691237012371123721237312374123751237612377123781237912380123811238212383123841238512386123871238812389123901239112392123931239412395123961239712398123991240012401124021240312404124051240612407124081240912410124111241212413124141241512416124171241812419124201242112422124231242412425124261242712428124291243012431124321243312434124351243612437124381243912440124411244212443124441244512446124471244812449124501245112452124531245412455124561245712458124591246012461124621246312464124651246612467124681246912470124711247212473124741247512476124771247812479124801248112482124831248412485124861248712488124891249012491124921249312494124951249612497124981249912500125011250212503125041250512506125071250812509125101251112512125131251412515125161251712518125191252012521125221252312524125251252612527125281252912530125311253212533125341253512536125371253812539125401254112542125431254412545125461254712548125491255012551125521255312554125551255612557125581255912560125611256212563125641256512566125671256812569125701257112572125731257412575125761257712578125791258012581125821258312584125851258612587125881258912590125911259212593125941259512596125971259812599126001260112602126031260412605126061260712608126091261012611126121261312614126151261612617126181261912620126211262212623126241262512626126271262812629126301263112632126331263412635126361263712638126391264012641126421264312644126451264612647126481264912650126511265212653126541265512656126571265812659126601266112662126631266412665126661266712668126691267012671126721267312674126751267612677126781267912680126811268212683126841268512686126871268812689126901269112692126931269412695126961269712698126991270012701127021270312704127051270612707127081270912710127111271212713127141271512716127171271812719127201272112722127231272412725127261272712728127291273012731127321273312734127351273612737127381273912740127411274212743127441274512746127471274812749127501275112752127531275412755127561275712758127591276012761127621276312764127651276612767127681276912770127711277212773127741277512776127771277812779127801278112782127831278412785127861278712788127891279012791127921279312794127951279612797127981279912800128011280212803128041280512806128071280812809128101281112812128131281412815128161281712818128191282012821128221282312824128251282612827128281282912830128311283212833128341283512836128371283812839128401284112842128431284412845128461284712848128491285012851128521285312854128551285612857128581285912860128611286212863128641286512866128671286812869128701287112872128731287412875128761287712878128791288012881128821288312884128851288612887128881288912890128911289212893128941289512896128971289812899129001290112902129031290412905129061290712908129091291012911129121291312914129151291612917129181291912920129211292212923129241292512926129271292812929129301293112932129331293412935129361293712938129391294012941129421294312944129451294612947129481294912950129511295212953129541295512956129571295812959129601296112962129631296412965129661296712968129691297012971129721297312974129751297612977129781297912980129811298212983129841298512986129871298812989129901299112992129931299412995129961299712998129991300013001130021300313004130051300613007130081300913010130111301213013130141301513016130171301813019130201302113022130231302413025130261302713028130291303013031130321303313034130351303613037130381303913040130411304213043130441304513046130471304813049130501305113052130531305413055130561305713058130591306013061130621306313064130651306613067130681306913070130711307213073130741307513076130771307813079130801308113082130831308413085130861308713088130891309013091130921309313094130951309613097130981309913100131011310213103131041310513106131071310813109131101311113112131131311413115131161311713118131191312013121131221312313124131251312613127131281312913130131311313213133131341313513136131371313813139131401314113142131431314413145131461314713148131491315013151131521315313154131551315613157131581315913160131611316213163131641316513166131671316813169131701317113172131731317413175131761317713178131791318013181131821318313184131851318613187131881318913190131911319213193131941319513196131971319813199132001320113202132031320413205132061320713208132091321013211132121321313214132151321613217132181321913220132211322213223132241322513226132271322813229132301323113232132331323413235132361323713238132391324013241132421324313244132451324613247132481324913250132511325213253132541325513256132571325813259132601326113262132631326413265132661326713268132691327013271132721327313274132751327613277132781327913280132811328213283132841328513286132871328813289132901329113292132931329413295132961329713298132991330013301133021330313304133051330613307133081330913310133111331213313133141331513316133171331813319133201332113322133231332413325133261332713328133291333013331133321333313334133351333613337133381333913340133411334213343133441334513346133471334813349133501335113352133531335413355133561335713358133591336013361133621336313364133651336613367133681336913370133711337213373133741337513376133771337813379133801338113382133831338413385133861338713388133891339013391133921339313394133951339613397133981339913400134011340213403134041340513406134071340813409134101341113412134131341413415134161341713418134191342013421134221342313424134251342613427134281342913430134311343213433134341343513436134371343813439134401344113442134431344413445134461344713448134491345013451134521345313454134551345613457134581345913460134611346213463134641346513466134671346813469134701347113472134731347413475134761347713478134791348013481134821348313484134851348613487134881348913490134911349213493134941349513496134971349813499135001350113502135031350413505135061350713508135091351013511135121351313514135151351613517135181351913520135211352213523135241352513526135271352813529135301353113532135331353413535135361353713538135391354013541135421354313544135451354613547135481354913550135511355213553135541355513556135571355813559135601356113562135631356413565135661356713568135691357013571135721357313574135751357613577135781357913580135811358213583135841358513586135871358813589135901359113592135931359413595135961359713598135991360013601136021360313604136051360613607136081360913610136111361213613136141361513616136171361813619136201362113622136231362413625136261362713628136291363013631136321363313634136351363613637136381363913640136411364213643136441364513646136471364813649136501365113652136531365413655136561365713658136591366013661136621366313664136651366613667136681366913670136711367213673136741367513676136771367813679136801368113682136831368413685136861368713688136891369013691136921369313694136951369613697136981369913700137011370213703137041370513706137071370813709137101371113712137131371413715137161371713718137191372013721137221372313724137251372613727137281372913730137311373213733137341373513736137371373813739137401374113742137431374413745137461374713748137491375013751137521375313754137551375613757137581375913760137611376213763137641376513766137671376813769137701377113772137731377413775137761377713778137791378013781137821378313784137851378613787137881378913790137911379213793137941379513796137971379813799138001380113802138031380413805138061380713808138091381013811138121381313814138151381613817138181381913820138211382213823138241382513826138271382813829138301383113832138331383413835138361383713838138391384013841138421384313844138451384613847138481384913850138511385213853138541385513856138571385813859138601386113862138631386413865138661386713868138691387013871138721387313874138751387613877138781387913880138811388213883138841388513886138871388813889138901389113892138931389413895138961389713898138991390013901139021390313904139051390613907139081390913910139111391213913139141391513916139171391813919139201392113922139231392413925139261392713928139291393013931139321393313934139351393613937139381393913940139411394213943139441394513946139471394813949139501395113952139531395413955139561395713958139591396013961139621396313964139651396613967139681396913970139711397213973139741397513976139771397813979139801398113982139831398413985139861398713988139891399013991139921399313994139951399613997139981399914000140011400214003140041400514006140071400814009140101401114012140131401414015140161401714018140191402014021140221402314024140251402614027140281402914030140311403214033140341403514036140371403814039140401404114042140431404414045140461404714048140491405014051140521405314054140551405614057140581405914060140611406214063140641406514066140671406814069140701407114072140731407414075140761407714078140791408014081140821408314084140851408614087140881408914090140911409214093140941409514096140971409814099141001410114102141031410414105141061410714108141091411014111141121411314114141151411614117141181411914120141211412214123141241412514126141271412814129141301413114132141331413414135141361413714138141391414014141141421414314144141451414614147141481414914150141511415214153141541415514156141571415814159141601416114162141631416414165141661416714168141691417014171141721417314174141751417614177141781417914180141811418214183141841418514186141871418814189141901419114192141931419414195141961419714198141991420014201142021420314204142051420614207142081420914210142111421214213142141421514216142171421814219142201422114222142231422414225142261422714228142291423014231142321423314234142351423614237142381423914240142411424214243142441424514246142471424814249142501425114252142531425414255142561425714258142591426014261142621426314264142651426614267142681426914270142711427214273142741427514276142771427814279142801428114282142831428414285142861428714288142891429014291142921429314294142951429614297142981429914300143011430214303143041430514306143071430814309143101431114312143131431414315143161431714318143191432014321143221432314324143251432614327143281432914330143311433214333143341433514336143371433814339143401434114342143431434414345143461434714348143491435014351143521435314354143551435614357143581435914360143611436214363143641436514366143671436814369143701437114372143731437414375143761437714378143791438014381143821438314384143851438614387143881438914390143911439214393143941439514396143971439814399144001440114402144031440414405144061440714408144091441014411144121441314414144151441614417144181441914420144211442214423144241442514426144271442814429144301443114432144331443414435144361443714438144391444014441144421444314444144451444614447144481444914450144511445214453144541445514456144571445814459144601446114462144631446414465144661446714468144691447014471144721447314474144751447614477144781447914480144811448214483144841448514486144871448814489144901449114492144931449414495144961449714498144991450014501145021450314504145051450614507145081450914510145111451214513145141451514516145171451814519145201452114522145231452414525145261452714528145291453014531145321453314534145351453614537145381453914540145411454214543145441454514546145471454814549145501455114552145531455414555145561455714558145591456014561145621456314564145651456614567145681456914570145711457214573145741457514576145771457814579145801458114582145831458414585145861458714588145891459014591145921459314594145951459614597145981459914600146011460214603146041460514606146071460814609146101461114612146131461414615146161461714618146191462014621146221462314624146251462614627146281462914630146311463214633146341463514636146371463814639146401464114642146431464414645146461464714648146491465014651146521465314654146551465614657146581465914660146611466214663146641466514666146671466814669146701467114672146731467414675146761467714678146791468014681146821468314684146851468614687146881468914690146911469214693146941469514696146971469814699147001470114702147031470414705147061470714708147091471014711147121471314714147151471614717147181471914720147211472214723147241472514726147271472814729147301473114732147331473414735147361473714738147391474014741147421474314744147451474614747147481474914750147511475214753147541475514756147571475814759147601476114762147631476414765147661476714768147691477014771147721477314774147751477614777147781477914780147811478214783147841478514786147871478814789147901479114792147931479414795147961479714798147991480014801148021480314804148051480614807148081480914810148111481214813148141481514816148171481814819148201482114822148231482414825148261482714828148291483014831148321483314834148351483614837148381483914840148411484214843148441484514846148471484814849148501485114852148531485414855148561485714858148591486014861148621486314864148651486614867148681486914870148711487214873148741487514876148771487814879148801488114882148831488414885148861488714888148891489014891148921489314894148951489614897148981489914900149011490214903149041490514906149071490814909149101491114912149131491414915149161491714918149191492014921149221492314924149251492614927149281492914930149311493214933149341493514936149371493814939149401494114942149431494414945149461494714948149491495014951149521495314954149551495614957149581495914960149611496214963149641496514966149671496814969149701497114972149731497414975149761497714978149791498014981149821498314984149851498614987149881498914990149911499214993149941499514996149971499814999150001500115002150031500415005150061500715008150091501015011150121501315014150151501615017150181501915020150211502215023150241502515026150271502815029150301503115032150331503415035150361503715038
  1. /*!
  2. \brief This function initializes the DTLS v1.2 client method.
  3. \return pointer This function returns a pointer to a new
  4. WOLFSSL_METHOD structure.
  5. \param none No parameters.
  6. _Example_
  7. \code
  8. wolfSSL_Init();
  9. WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfDTLSv1_2_client_method());
  10. WOLFSSL* ssl = wolfSSL_new(ctx);
  11. \endcode
  12. \sa wolfSSL_Init
  13. \sa wolfSSL_CTX_new
  14. */
  15. WOLFSSL_METHOD *wolfDTLSv1_2_client_method_ex(void* heap);
  16. /*!
  17. \ingroup Setup
  18. \brief This function returns a WOLFSSL_METHOD similar to
  19. wolfSSLv23_client_method except that it is not determined
  20. which side yet (server/client).
  21. \return WOLFSSL_METHOD* On successful creations returns a WOLFSSL_METHOD
  22. pointer
  23. \return NULL Null if memory allocation error or failure to create method
  24. \param none No parameters.
  25. _Example_
  26. \code
  27. WOLFSSL* ctx;
  28. ctx = wolfSSL_CTX_new(wolfSSLv23_method());
  29. // check ret value
  30. \endcode
  31. \sa wolfSSL_new
  32. \sa wolfSSL_free
  33. */
  34. WOLFSSL_METHOD *wolfSSLv23_method(void);
  35. /*!
  36. \ingroup Setup
  37. \brief The wolfSSLv3_server_method() function is used to indicate
  38. that the application is a server and will only support the SSL 3.0
  39. protocol. This function allocates memory for and initializes a new
  40. wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  41. with wolfSSL_CTX_new().
  42. \return * If successful, the call will return a pointer to the newly
  43. created WOLFSSL_METHOD structure.
  44. \return FAIL If memory allocation fails when calling XMALLOC, the
  45. failure value of the underlying malloc() implementation will be returned
  46. (typically NULL with errno will be set to ENOMEM).
  47. \param none No parameters.
  48. _Example_
  49. \code
  50. #include <wolfssl/ssl.h>
  51. WOLFSSL_METHOD* method;
  52. WOLFSSL_CTX* ctx;
  53. method = wolfSSLv3_server_method();
  54. if (method == NULL) {
  55. unable to get method
  56. }
  57. ctx = wolfSSL_CTX_new(method);
  58. ...
  59. \endcode
  60. \sa wolfTLSv1_server_method
  61. \sa wolfTLSv1_1_server_method
  62. \sa wolfTLSv1_2_server_method
  63. \sa wolfTLSv1_3_server_method
  64. \sa wolfDTLSv1_server_method
  65. \sa wolfSSLv23_server_method
  66. \sa wolfSSL_CTX_new
  67. */
  68. WOLFSSL_METHOD *wolfSSLv3_server_method(void);
  69. /*!
  70. \ingroup Setup
  71. \brief The wolfSSLv3_client_method() function is used to indicate
  72. that the application is a client and will only support the SSL 3.0
  73. protocol. This function allocates memory for and initializes a
  74. new wolfSSL_METHOD structure to be used when creating the SSL/TLS
  75. context with wolfSSL_CTX_new().
  76. \return * If successful, the call will return a pointer to the newly
  77. created WOLFSSL_METHOD structure.
  78. \return FAIL If memory allocation fails when calling XMALLOC, the
  79. failure value of the underlying malloc() implementation will be
  80. returned (typically NULL with errno will be set to ENOMEM).
  81. \param none No parameters.
  82. _Example_
  83. \code
  84. #include <wolfssl/ssl.h>
  85. WOLFSSL_METHOD* method;
  86. WOLFSSL_CTX* ctx;
  87. method = wolfSSLv3_client_method();
  88. if (method == NULL) {
  89. unable to get method
  90. }
  91. ctx = wolfSSL_CTX_new(method);
  92. ...
  93. \endcode
  94. \sa wolfTLSv1_client_method
  95. \sa wolfTLSv1_1_client_method
  96. \sa wolfTLSv1_2_client_method
  97. \sa wolfTLSv1_3_client_method
  98. \sa wolfDTLSv1_client_method
  99. \sa wolfSSLv23_client_method
  100. \sa wolfSSL_CTX_new
  101. */
  102. WOLFSSL_METHOD *wolfSSLv3_client_method(void);
  103. /*!
  104. \ingroup Setup
  105. \brief The wolfTLSv1_server_method() function is used to indicate that the
  106. application is a server and will only support the TLS 1.0 protocol. This
  107. function allocates memory for and initializes a new wolfSSL_METHOD
  108. structure to be used when creating the SSL/TLS context with
  109. wolfSSL_CTX_new().
  110. \return * If successful, the call will return a pointer to the newly
  111. created WOLFSSL_METHOD structure.
  112. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  113. value of the underlying malloc() implementation will be returned
  114. (typically NULL with errno will be set to ENOMEM).
  115. \param none No parameters.
  116. _Example_
  117. \code
  118. #include <wolfssl/ssl.h>
  119. WOLFSSL_METHOD* method;
  120. WOLFSSL_CTX* ctx;
  121. method = wolfTLSv1_server_method();
  122. if (method == NULL) {
  123. unable to get method
  124. }
  125. ctx = wolfSSL_CTX_new(method);
  126. ...
  127. \endcode
  128. \sa wolfSSLv3_server_method
  129. \sa wolfTLSv1_1_server_method
  130. \sa wolfTLSv1_2_server_method
  131. \sa wolfTLSv1_3_server_method
  132. \sa wolfDTLSv1_server_method
  133. \sa wolfSSLv23_server_method
  134. \sa wolfSSL_CTX_new
  135. */
  136. WOLFSSL_METHOD *wolfTLSv1_server_method(void);
  137. /*!
  138. \ingroup Setup
  139. \brief The wolfTLSv1_client_method() function is used to indicate
  140. that the application is a client and will only support the TLS 1.0
  141. protocol. This function allocates memory for and initializes a new
  142. wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  143. with wolfSSL_CTX_new().
  144. \return * If successful, the call will return a pointer to the newly
  145. created WOLFSSL_METHOD structure.
  146. \return FAIL If memory allocation fails when calling XMALLOC,
  147. the failure value of the underlying malloc() implementation
  148. will be returned (typically NULL with errno will be set to ENOMEM).
  149. \param none No parameters.
  150. _Example_
  151. \code
  152. #include <wolfssl/ssl.h>
  153. WOLFSSL_METHOD* method;
  154. WOLFSSL_CTX* ctx;
  155. method = wolfTLSv1_client_method();
  156. if (method == NULL) {
  157. unable to get method
  158. }
  159. ctx = wolfSSL_CTX_new(method);
  160. ...
  161. \endcode
  162. \sa wolfSSLv3_client_method
  163. \sa wolfTLSv1_1_client_method
  164. \sa wolfTLSv1_2_client_method
  165. \sa wolfTLSv1_3_client_method
  166. \sa wolfDTLSv1_client_method
  167. \sa wolfSSLv23_client_method
  168. \sa wolfSSL_CTX_new
  169. */
  170. WOLFSSL_METHOD *wolfTLSv1_client_method(void);
  171. /*!
  172. \ingroup Setup
  173. \brief The wolfTLSv1_1_server_method() function is used to indicate
  174. that the application is a server and will only support the TLS 1.1
  175. protocol. This function allocates memory for and initializes a new
  176. wolfSSL_METHOD structure to be used when creating the SSL/TLS
  177. context with wolfSSL_CTX_new().
  178. \return * If successful, the call will return a pointer to the newly
  179. created WOLFSSL_METHOD structure.
  180. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  181. value of the underlying malloc() implementation will be returned
  182. (typically NULL with errno will be set to ENOMEM).
  183. \param none No parameters.
  184. _Example_
  185. \code
  186. #include <wolfssl/ssl.h>
  187. WOLFSSL_METHOD* method;
  188. WOLFSSL_CTX* ctx;
  189. method = wolfTLSv1_1_server_method();
  190. if (method == NULL) {
  191. // unable to get method
  192. }
  193. ctx = wolfSSL_CTX_new(method);
  194. ...
  195. \endcode
  196. \sa wolfSSLv3_server_method
  197. \sa wolfTLSv1_server_method
  198. \sa wolfTLSv1_2_server_method
  199. \sa wolfTLSv1_3_server_method
  200. \sa wolfDTLSv1_server_method
  201. \sa wolfSSLv23_server_method
  202. \sa wolfSSL_CTX_new
  203. */
  204. WOLFSSL_METHOD *wolfTLSv1_1_server_method(void);
  205. /*!
  206. \ingroup Setup
  207. \brief The wolfTLSv1_1_client_method() function is used to indicate
  208. that the application is a client and will only support the TLS 1.0
  209. protocol. This function allocates memory for and initializes a
  210. new wolfSSL_METHOD structure to be used when creating the SSL/TLS
  211. context with wolfSSL_CTX_new().
  212. \return * If successful, the call will return a pointer to the
  213. newly created WOLFSSL_METHOD structure.
  214. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  215. value of the underlying malloc() implementation will be returned
  216. (typically NULL with errno will be set to ENOMEM).
  217. \param none No parameters.
  218. _Example_
  219. \code
  220. #include <wolfssl/ssl.h>
  221. WOLFSSL_METHOD* method;
  222. WOLFSSL_CTX* ctx;
  223. method = wolfTLSv1_1_client_method();
  224. if (method == NULL) {
  225. // unable to get method
  226. }
  227. ctx = wolfSSL_CTX_new(method);
  228. ...
  229. \endcode
  230. \sa wolfSSLv3_client_method
  231. \sa wolfTLSv1_client_method
  232. \sa wolfTLSv1_2_client_method
  233. \sa wolfTLSv1_3_client_method
  234. \sa wolfDTLSv1_client_method
  235. \sa wolfSSLv23_client_method
  236. \sa wolfSSL_CTX_new
  237. */
  238. WOLFSSL_METHOD *wolfTLSv1_1_client_method(void);
  239. /*!
  240. \ingroup Setup
  241. \brief The wolfTLSv1_2_server_method() function is used to indicate
  242. that the application is a server and will only support the TLS 1.2
  243. protocol. This function allocates memory for and initializes a new
  244. wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  245. with wolfSSL_CTX_new().
  246. \return * If successful, the call will return a pointer to the newly
  247. created WOLFSSL_METHOD structure.
  248. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  249. value of the underlying malloc() implementation will be returned
  250. (typically NULL with errno will be set to ENOMEM).
  251. \param none No parameters.
  252. _Example_
  253. \code
  254. #include <wolfssl/ssl.h>
  255. WOLFSSL_METHOD* method;
  256. WOLFSSL_CTX* ctx;
  257. method = wolfTLSv1_2_server_method();
  258. if (method == NULL) {
  259. // unable to get method
  260. }
  261. ctx = wolfSSL_CTX_new(method);
  262. ...
  263. \endcode
  264. \sa wolfSSLv3_server_method
  265. \sa wolfTLSv1_server_method
  266. \sa wolfTLSv1_1_server_method
  267. \sa wolfTLSv1_3_server_method
  268. \sa wolfDTLSv1_server_method
  269. \sa wolfSSLv23_server_method
  270. \sa wolfSSL_CTX_new
  271. */
  272. WOLFSSL_METHOD *wolfTLSv1_2_server_method(void);
  273. /*!
  274. \ingroup Setup
  275. \brief The wolfTLSv1_2_client_method() function is used to indicate
  276. that the application is a client and will only support the TLS 1.2
  277. protocol. This function allocates memory for and initializes a new
  278. wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  279. with wolfSSL_CTX_new().
  280. \return * If successful, the call will return a pointer to the newly
  281. created WOLFSSL_METHOD structure.
  282. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  283. value of the underlying malloc() implementation will be returned
  284. (typically NULL with errno will be set to ENOMEM).
  285. \param none No parameters.
  286. _Example_
  287. \code
  288. #include <wolfssl/ssl.h>
  289. WOLFSSL_METHOD* method;
  290. WOLFSSL_CTX* ctx;
  291. method = wolfTLSv1_2_client_method();
  292. if (method == NULL) {
  293. // unable to get method
  294. }
  295. ctx = wolfSSL_CTX_new(method);
  296. ...
  297. \endcode
  298. \sa wolfSSLv3_client_method
  299. \sa wolfTLSv1_client_method
  300. \sa wolfTLSv1_1_client_method
  301. \sa wolfTLSv1_3_client_method
  302. \sa wolfDTLSv1_client_method
  303. \sa wolfSSLv23_client_method
  304. \sa wolfSSL_CTX_new
  305. */
  306. WOLFSSL_METHOD *wolfTLSv1_2_client_method(void);
  307. /*!
  308. \ingroup Setup
  309. \brief The wolfDTLSv1_client_method() function is used to indicate that
  310. the application is a client and will only support the DTLS 1.0 protocol.
  311. This function allocates memory for and initializes a new
  312. wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  313. with wolfSSL_CTX_new(). This function is only available when wolfSSL has
  314. been compiled with DTLS support (--enable-dtls,
  315. or by defining wolfSSL_DTLS).
  316. \return * If successful, the call will return a pointer to the newly
  317. created WOLFSSL_METHOD structure.
  318. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  319. value of the underlying malloc() implementation will be returned
  320. (typically NULL with errno will be set to ENOMEM).
  321. \param none No parameters.
  322. _Example_
  323. \code
  324. WOLFSSL_METHOD* method;
  325. WOLFSSL_CTX* ctx;
  326. method = wolfDTLSv1_client_method();
  327. if (method == NULL) {
  328. // unable to get method
  329. }
  330. ctx = wolfSSL_CTX_new(method);
  331. ...
  332. \endcode
  333. \sa wolfSSLv3_client_method
  334. \sa wolfTLSv1_client_method
  335. \sa wolfTLSv1_1_client_method
  336. \sa wolfTLSv1_2_client_method
  337. \sa wolfTLSv1_3_client_method
  338. \sa wolfSSLv23_client_method
  339. \sa wolfSSL_CTX_new
  340. */
  341. WOLFSSL_METHOD *wolfDTLSv1_client_method(void);
  342. /*!
  343. \ingroup Setup
  344. \brief The wolfDTLSv1_server_method() function is used to indicate
  345. that the application is a server and will only support the DTLS 1.0
  346. protocol. This function allocates memory for and initializes a
  347. new wolfSSL_METHOD structure to be used when creating the SSL/TLS
  348. context with wolfSSL_CTX_new(). This function is only available
  349. when wolfSSL has been compiled with DTLS support (--enable-dtls,
  350. or by defining wolfSSL_DTLS).
  351. \return * If successful, the call will return a pointer to the newly
  352. created WOLFSSL_METHOD structure.
  353. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  354. value of the underlying malloc() implementation will be returned
  355. (typically NULL with errno will be set to ENOMEM).
  356. \param none No parameters.
  357. _Example_
  358. \code
  359. WOLFSSL_METHOD* method;
  360. WOLFSSL_CTX* ctx;
  361. method = wolfDTLSv1_server_method();
  362. if (method == NULL) {
  363. // unable to get method
  364. }
  365. ctx = wolfSSL_CTX_new(method);
  366. ...
  367. \endcode
  368. \sa wolfSSLv3_server_method
  369. \sa wolfTLSv1_server_method
  370. \sa wolfTLSv1_1_server_method
  371. \sa wolfTLSv1_2_server_method
  372. \sa wolfTLSv1_3_server_method
  373. \sa wolfSSLv23_server_method
  374. \sa wolfSSL_CTX_new
  375. */
  376. WOLFSSL_METHOD *wolfDTLSv1_server_method(void);
  377. /*!
  378. \ingroup Setup
  379. \brief The wolfDTLSv1_3_server_method() function is used to indicate that
  380. the application is a server and will only support the DTLS 1.3
  381. protocol. This function allocates memory for and initializes a new
  382. wolfSSL_METHOD structure to be used when creating the SSL/TLS context with
  383. wolfSSL_CTX_new(). This function is only available when wolfSSL has been
  384. compiled with DTLSv1.3 support (--enable-dtls13, or by defining
  385. wolfSSL_DTLS13).
  386. \return * If successful, the call will return a pointer to the newly
  387. created WOLFSSL_METHOD structure.
  388. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  389. value of the underlying malloc() implementation will be returned
  390. (typically NULL with errno will be set to ENOMEM).
  391. \param none No parameters.
  392. _Example_
  393. \code
  394. WOLFSSL_METHOD* method;
  395. WOLFSSL_CTX* ctx;
  396. method = wolfDTLSv1_3_server_method();
  397. if (method == NULL) {
  398. // unable to get method
  399. }
  400. ctx = wolfSSL_CTX_new(method);
  401. ...
  402. \endcode
  403. \sa wolfDTLSv1_3_client_method
  404. */
  405. WOLFSSL_METHOD *wolfDTLSv1_3_server_method(void);
  406. /*!
  407. \ingroup Setup
  408. \brief The wolfDTLSv1_3_client_method() function is used to indicate that
  409. the application is a client and will only support the DTLS 1.3
  410. protocol. This function allocates memory for and initializes a new
  411. wolfSSL_METHOD structure to be used when creating the SSL/TLS context with
  412. wolfSSL_CTX_new(). This function is only available when wolfSSL has been
  413. compiled with DTLSv1.3 support (--enable-dtls13, or by defining
  414. wolfSSL_DTLS13).
  415. \return * If successful, the call will return a pointer to the newly
  416. created WOLFSSL_METHOD structure.
  417. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  418. value of the underlying malloc() implementation will be returned
  419. (typically NULL with errno will be set to ENOMEM).
  420. \param none No parameters.
  421. _Example_
  422. \code
  423. WOLFSSL_METHOD* method;
  424. WOLFSSL_CTX* ctx;
  425. method = wolfDTLSv1_3_client_method();
  426. if (method == NULL) {
  427. // unable to get method
  428. }
  429. ctx = wolfSSL_CTX_new(method);
  430. ...
  431. \endcode
  432. \sa wolfDTLSv1_3_server_method
  433. */
  434. WOLFSSL_METHOD* wolfDTLSv1_3_client_method(void);
  435. /*!
  436. \ingroup Setup
  437. \brief The wolfDTLS_server_method() function is used to indicate that the
  438. application is a server and will support the highest version of DTLS
  439. available and all the version up to the minimum version allowed. The
  440. default minimum version allowed is based on the define
  441. WOLFSSL_MIN_DTLS_DOWNGRADE and can be changed at runtime using
  442. wolfSSL_SetMinVersion(). This function allocates memory for and initializes
  443. a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  444. with wolfSSL_CTX_new(). This function is only available when wolfSSL has
  445. been compiled with DTLS support (--enable-dtls, or by defining
  446. wolfSSL_DTLS).
  447. \return * If successful, the call will return a pointer to the newly
  448. created WOLFSSL_METHOD structure.
  449. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  450. value of the underlying malloc() implementation will be returned
  451. (typically NULL with errno will be set to ENOMEM).
  452. \param none No parameters.
  453. _Example_
  454. \code
  455. WOLFSSL_METHOD* method;
  456. WOLFSSL_CTX* ctx;
  457. method = wolfDTLS_server_method();
  458. if (method == NULL) {
  459. // unable to get method
  460. }
  461. ctx = wolfSSL_CTX_new(method);
  462. ...
  463. \endcode
  464. \sa wolfDTLS_client_method
  465. \sa wolfSSL_SetMinVersion
  466. */
  467. WOLFSSL_METHOD *wolfDTLS_server_method(void);
  468. /*!
  469. \ingroup Setup
  470. \brief The wolfDTLS_client_method() function is used to indicate that the
  471. application is a client and will support the highest version of DTLS
  472. available and all the version up to the minimum version allowed. The
  473. default minimum version allowed is based on the define
  474. WOLFSSL_MIN_DTLS_DOWNGRADE and can be changed at runtime using
  475. wolfSSL_SetMinVersion(). This function allocates memory for and initializes
  476. a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  477. with wolfSSL_CTX_new(). This function is only available when wolfSSL has
  478. been compiled with DTLS support (--enable-dtls, or by defining
  479. wolfSSL_DTLS).
  480. \return * If successful, the call will return a pointer to the newly
  481. created WOLFSSL_METHOD structure.
  482. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  483. value of the underlying malloc() implementation will be returned
  484. (typically NULL with errno will be set to ENOMEM).
  485. \param none No parameters.
  486. _Example_
  487. \code
  488. WOLFSSL_METHOD* method;
  489. WOLFSSL_CTX* ctx;
  490. method = wolfDTLS_client_method();
  491. if (method == NULL) {
  492. // unable to get method
  493. }
  494. ctx = wolfSSL_CTX_new(method);
  495. ...
  496. \endcode
  497. \sa wolfDTLS_server_method
  498. \sa wolfSSL_SetMinVersion
  499. */
  500. WOLFSSL_METHOD *wolfDTLS_client_method(void);
  501. /*!
  502. \brief This function creates and initializes a WOLFSSL_METHOD for the
  503. server side.
  504. \return This function returns a WOLFSSL_METHOD pointer.
  505. \param none No parameters.
  506. _Example_
  507. \code
  508. WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfDTLSv1_2_server_method());
  509. WOLFSSL* ssl = WOLFSSL_new(ctx);
  510. \endcode
  511. \sa wolfSSL_CTX_new
  512. */
  513. WOLFSSL_METHOD *wolfDTLSv1_2_server_method(void);
  514. /*!
  515. \ingroup Setup
  516. \brief Since there is some differences between the first release and
  517. newer versions of chacha-poly AEAD construction we have added an option
  518. to communicate with servers/clients using the older version. By default
  519. wolfSSL uses the new version.
  520. \return 0 upon success
  521. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  522. \param value whether or not to use the older version of setting up the
  523. information for poly1305. Passing a flag value of 1 indicates yes use the
  524. old poly AEAD, to switch back to using the new version pass a flag value
  525. of 0.
  526. _Example_
  527. \code
  528. int ret = 0;
  529. WOLFSSL* ssl;
  530. ...
  531. ret = wolfSSL_use_old_poly(ssl, 1);
  532. if (ret != 0) {
  533. // failed to set poly1305 AEAD version
  534. }
  535. \endcode
  536. \sa none
  537. */
  538. int wolfSSL_use_old_poly(WOLFSSL* ssl, int value);
  539. /*!
  540. \brief The wolfSSL_dtls_import() function is used to parse in a serialized
  541. session state. This allows for picking up the connection after the
  542. handshake has been completed.
  543. \return Success If successful, the amount of the buffer read will be
  544. returned.
  545. \return Failure All unsuccessful return values will be less than 0.
  546. \return VERSION_ERROR If a version mismatch is found ie DTLS v1 and ctx
  547. was set up for DTLS v1.2 then VERSION_ERROR is returned.
  548. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  549. \param buf serialized session to import.
  550. \param sz size of serialized session buffer.
  551. _Example_
  552. \code
  553. WOLFSSL* ssl;
  554. int ret;
  555. unsigned char buf[MAX];
  556. bufSz = MAX;
  557. ...
  558. //get information sent from wc_dtls_export function and place it in buf
  559. fread(buf, 1, bufSz, input);
  560. ret = wolfSSL_dtls_import(ssl, buf, bufSz);
  561. if (ret < 0) {
  562. // handle error case
  563. }
  564. // no wolfSSL_accept needed since handshake was already done
  565. ...
  566. ret = wolfSSL_write(ssl) and wolfSSL_read(ssl);
  567. ...
  568. \endcode
  569. \sa wolfSSL_new
  570. \sa wolfSSL_CTX_new
  571. \sa wolfSSL_CTX_dtls_set_export
  572. */
  573. int wolfSSL_dtls_import(WOLFSSL* ssl, unsigned char* buf,
  574. unsigned int sz);
  575. /*!
  576. \brief Used to import a serialized TLS session. This function is for
  577. importing the state of the connection.
  578. WARNING: buf contains sensitive information about the state and is best to
  579. be encrypted before storing if stored.
  580. Additional debug info can be displayed with the macro
  581. WOLFSSL_SESSION_EXPORT_DEBUG defined.
  582. \return the number of bytes read from buffer 'buf'
  583. \param ssl WOLFSSL structure to import the session into
  584. \param buf serialized session
  585. \param sz size of buffer 'buf'
  586. \sa wolfSSL_dtls_import
  587. \sa wolfSSL_tls_export
  588. */
  589. int wolfSSL_tls_import(WOLFSSL* ssl, const unsigned char* buf,
  590. unsigned int sz);
  591. /*!
  592. \brief The wolfSSL_CTX_dtls_set_export() function is used to set
  593. the callback function for exporting a session. It is allowed to
  594. pass in NULL as the parameter func to clear the export function
  595. previously stored. Used on the server side and is called immediately
  596. after handshake is completed.
  597. \return SSL_SUCCESS upon success.
  598. \return BAD_FUNC_ARG If null or not expected arguments are passed in
  599. \param ctx a pointer to a WOLFSSL_CTX structure, created
  600. with wolfSSL_CTX_new().
  601. \param func wc_dtls_export function to use when exporting a session.
  602. _Example_
  603. \code
  604. int send_session(WOLFSSL* ssl, byte* buf, word32 sz, void* userCtx);
  605. // body of send session (wc_dtls_export) that passes
  606. // buf (serialized session) to destination
  607. WOLFSSL_CTX* ctx;
  608. int ret;
  609. ...
  610. ret = wolfSSL_CTX_dtls_set_export(ctx, send_session);
  611. if (ret != SSL_SUCCESS) {
  612. // handle error case
  613. }
  614. ...
  615. ret = wolfSSL_accept(ssl);
  616. ...
  617. \endcode
  618. \sa wolfSSL_new
  619. \sa wolfSSL_CTX_new
  620. \sa wolfSSL_dtls_set_export
  621. \sa Static buffer use
  622. */
  623. int wolfSSL_CTX_dtls_set_export(WOLFSSL_CTX* ctx,
  624. wc_dtls_export func);
  625. /*!
  626. \brief The wolfSSL_dtls_set_export() function is used to set the callback
  627. function for exporting a session. It is allowed to pass in NULL as the
  628. parameter func to clear the export function previously stored. Used on
  629. the server side and is called immediately after handshake is completed.
  630. \return SSL_SUCCESS upon success.
  631. \return BAD_FUNC_ARG If null or not expected arguments are passed in
  632. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  633. \param func wc_dtls_export function to use when exporting a session.
  634. _Example_
  635. \code
  636. int send_session(WOLFSSL* ssl, byte* buf, word32 sz, void* userCtx);
  637. // body of send session (wc_dtls_export) that passes
  638. // buf (serialized session) to destination
  639. WOLFSSL* ssl;
  640. int ret;
  641. ...
  642. ret = wolfSSL_dtls_set_export(ssl, send_session);
  643. if (ret != SSL_SUCCESS) {
  644. // handle error case
  645. }
  646. ...
  647. ret = wolfSSL_accept(ssl);
  648. ...
  649. \endcode
  650. \sa wolfSSL_new
  651. \sa wolfSSL_CTX_new
  652. \sa wolfSSL_CTX_dtls_set_export
  653. */
  654. int wolfSSL_dtls_set_export(WOLFSSL* ssl, wc_dtls_export func);
  655. /*!
  656. \brief The wolfSSL_dtls_export() function is used to serialize a
  657. WOLFSSL session into the provided buffer. Allows for less memory
  658. overhead than using a function callback for sending a session and
  659. choice over when the session is serialized. If buffer is NULL when
  660. passed to function then sz will be set to the size of buffer needed
  661. for serializing the WOLFSSL session.
  662. \return Success If successful, the amount of the buffer used will
  663. be returned.
  664. \return Failure All unsuccessful return values will be less than 0.
  665. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  666. \param buf buffer to hold serialized session.
  667. \param sz size of buffer.
  668. _Example_
  669. \code
  670. WOLFSSL* ssl;
  671. int ret;
  672. unsigned char buf[MAX];
  673. bufSz = MAX;
  674. ...
  675. ret = wolfSSL_dtls_export(ssl, buf, bufSz);
  676. if (ret < 0) {
  677. // handle error case
  678. }
  679. ...
  680. \endcode
  681. \sa wolfSSL_new
  682. \sa wolfSSL_CTX_new
  683. \sa wolfSSL_CTX_dtls_set_export
  684. \sa wolfSSL_dtls_import
  685. */
  686. int wolfSSL_dtls_export(WOLFSSL* ssl, unsigned char* buf,
  687. unsigned int* sz);
  688. /*!
  689. \brief Used to export a serialized TLS session. This function is for
  690. exporting a serialized state of the connection.
  691. In most cases wolfSSL_get1_session should be used instead of
  692. wolfSSL_tls_export.
  693. Additional debug info can be displayed with the macro
  694. WOLFSSL_SESSION_EXPORT_DEBUG defined.
  695. WARNING: buf contains sensitive information about the state and is best to
  696. be encrypted before storing if stored.
  697. \return the number of bytes written into buffer 'buf'
  698. \param ssl WOLFSSL structure to export the session from
  699. \param buf output of serialized session
  700. \param sz size in bytes set in 'buf'
  701. \sa wolfSSL_dtls_import
  702. \sa wolfSSL_tls_import
  703. */
  704. int wolfSSL_tls_export(WOLFSSL* ssl, unsigned char* buf,
  705. unsigned int* sz);
  706. /*!
  707. \brief This function is used to set aside static memory for a CTX. Memory
  708. set aside is then used for the CTX’s lifetime and for any SSL objects
  709. created from the CTX. By passing in a NULL ctx pointer and a
  710. wolfSSL_method_func function the creation of the CTX itself will also
  711. use static memory. wolfSSL_method_func has the function signature of
  712. WOLFSSL_METHOD* (*wolfSSL_method_func)(void* heap);. Passing in 0 for max
  713. makes it behave as if not set and no max concurrent use restrictions is
  714. in place. The flag value passed in determines how the memory is used and
  715. behavior while operating. Available flags are the following: 0 - default
  716. general memory, WOLFMEM_IO_POOL - used for input/output buffer when
  717. sending receiving messages and overrides general memory, so all memory
  718. in buffer passed in is used for IO, WOLFMEM_IO_FIXED - same as
  719. WOLFMEM_IO_POOL but each SSL now keeps two buffers to themselves for
  720. their lifetime, WOLFMEM_TRACK_STATS - each SSL keeps track of memory
  721. stats while running.
  722. \return SSL_SUCCESS upon success.
  723. \return SSL_FAILURE upon failure.
  724. \param ctx address of pointer to a WOLFSSL_CTX structure.
  725. \param method function to create protocol. (should be NULL if ctx is not
  726. also NULL)
  727. \param buf memory to use for all operations.
  728. \param sz size of memory buffer being passed in.
  729. \param flag type of memory.
  730. \param max max concurrent operations.
  731. _Example_
  732. \code
  733. WOLFSSL_CTX* ctx;
  734. WOLFSSL* ssl;
  735. int ret;
  736. unsigned char memory[MAX];
  737. int memorySz = MAX;
  738. unsigned char IO[MAX];
  739. int IOSz = MAX;
  740. int flag = WOLFMEM_IO_FIXED | WOLFMEM_TRACK_STATS;
  741. ...
  742. // create ctx also using static memory, start with general memory to use
  743. ctx = NULL:
  744. ret = wolfSSL_CTX_load_static_memory(&ctx, wolfSSLv23_server_method_ex,
  745. memory, memorySz, 0, MAX_CONCURRENT_HANDSHAKES);
  746. if (ret != SSL_SUCCESS) {
  747. // handle error case
  748. }
  749. // load in memory for use with IO
  750. ret = wolfSSL_CTX_load_static_memory(&ctx, NULL, IO, IOSz, flag,
  751. MAX_CONCURRENT_IO);
  752. if (ret != SSL_SUCCESS) {
  753. // handle error case
  754. }
  755. ...
  756. \endcode
  757. \sa wolfSSL_CTX_new
  758. \sa wolfSSL_CTX_is_static_memory
  759. \sa wolfSSL_is_static_memory
  760. */
  761. int wolfSSL_CTX_load_static_memory(WOLFSSL_CTX** ctx,
  762. wolfSSL_method_func method,
  763. unsigned char* buf, unsigned int sz,
  764. int flag, int max);
  765. /*!
  766. \brief This function does not change any of the connections behavior
  767. and is used only for gathering information about the static memory usage.
  768. \return 1 is returned if using static memory for the CTX is true.
  769. \return 0 is returned if not using static memory.
  770. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  771. wolfSSL_CTX_new().
  772. \param mem_stats structure to hold information about static memory usage.
  773. _Example_
  774. \code
  775. WOLFSSL_CTX* ctx;
  776. int ret;
  777. WOLFSSL_MEM_STATS mem_stats;
  778. ...
  779. //get information about static memory with CTX
  780. ret = wolfSSL_CTX_is_static_memory(ctx, &mem_stats);
  781. if (ret == 1) {
  782. // handle case of is using static memory
  783. // print out or inspect elements of mem_stats
  784. }
  785. if (ret == 0) {
  786. //handle case of ctx not using static memory
  787. }
  788. \endcode
  789. \sa wolfSSL_CTX_new
  790. \sa wolfSSL_CTX_load_static_memory
  791. \sa wolfSSL_is_static_memory
  792. */
  793. int wolfSSL_CTX_is_static_memory(WOLFSSL_CTX* ctx,
  794. WOLFSSL_MEM_STATS* mem_stats);
  795. /*!
  796. \brief wolfSSL_is_static_memory is used to gather information about
  797. a SSL’s static memory usage. The return value indicates if static
  798. memory is being used and WOLFSSL_MEM_CONN_STATS will be filled out
  799. if and only if the flag WOLFMEM_TRACK_STATS was passed to the parent
  800. CTX when loading in static memory.
  801. \return 1 is returned if using static memory for the CTX is true.
  802. \return 0 is returned if not using static memory.
  803. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  804. \param mem_stats structure to contain static memory usage.
  805. _Example_
  806. \code
  807. WOLFSSL* ssl;
  808. int ret;
  809. WOLFSSL_MEM_CONN_STATS mem_stats;
  810. ...
  811. ret = wolfSSL_is_static_memory(ssl, mem_stats);
  812. if (ret == 1) {
  813. // handle case when is static memory
  814. // investigate elements in mem_stats if WOLFMEM_TRACK_STATS flag
  815. }
  816. ...
  817. \endcode
  818. \sa wolfSSL_new
  819. \sa wolfSSL_CTX_is_static_memory
  820. */
  821. int wolfSSL_is_static_memory(WOLFSSL* ssl,
  822. WOLFSSL_MEM_CONN_STATS* mem_stats);
  823. /*!
  824. \ingroup CertsKeys
  825. \brief This function loads a certificate file into the SSL context
  826. (WOLFSSL_CTX). The file is provided by the file argument. The
  827. format argument specifies the format type of the file, either
  828. SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples
  829. for proper usage.
  830. \return SSL_SUCCESS upon success.
  831. \return SSL_FAILURE If the function call fails, possible causes might
  832. include the file is in the wrong format, or the wrong format has been
  833. given using the “format” argument, file doesn’t exist, can’t be read,
  834. or is corrupted, an out of memory condition occurs, Base16 decoding
  835. fails on the file.
  836. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  837. wolfSSL_CTX_new()
  838. \param file a pointer to the name of the file containing the certificate
  839. to be loaded into the wolfSSL SSL context.
  840. \param format - format of the certificates pointed to by file. Possible
  841. options are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
  842. _Example_
  843. \code
  844. int ret = 0;
  845. WOLFSSL_CTX* ctx;
  846. ...
  847. ret = wolfSSL_CTX_use_certificate_file(ctx, “./client-cert.pem”,
  848. SSL_FILETYPE_PEM);
  849. if (ret != SSL_SUCCESS) {
  850. // error loading cert file
  851. }
  852. ...
  853. \endcode
  854. \sa wolfSSL_CTX_use_certificate_buffer
  855. \sa wolfSSL_use_certificate_file
  856. \sa wolfSSL_use_certificate_buffer
  857. */
  858. int wolfSSL_CTX_use_certificate_file(WOLFSSL_CTX* ctx, const char* file,
  859. int format);
  860. /*!
  861. \ingroup CertsKeys
  862. \brief This function loads a private key file into the SSL context
  863. (WOLFSSL_CTX). The file is provided by the file argument. The format
  864. argument specifies the format type of the file - SSL_FILETYPE_ASN1or
  865. SSL_FILETYPE_PEM. Please see the examples for proper usage.
  866. If using an external key store and do not have the private key you can
  867. instead provide the public key and register the crypro callback to handle
  868. the signing. For this you can build with either build with crypto callbacks
  869. or PK callbacks. To enable crypto callbacks use --enable-cryptocb
  870. or WOLF_CRYPTO_CB and register a crypto callback using
  871. wc_CryptoCb_RegisterDevice and set the associated devId using
  872. wolfSSL_CTX_SetDevId.
  873. \return SSL_SUCCESS upon success.
  874. \return SSL_FAILURE The file is in the wrong format, or the wrong format
  875. has been given using the “format” argument. The file doesn’t exist, can’t
  876. be read, or is corrupted. An out of memory condition occurs. Base16
  877. decoding fails on the file. The key file is encrypted but no password
  878. is provided.
  879. \param none No parameters.
  880. _Example_
  881. \code
  882. int ret = 0;
  883. WOLFSSL_CTX* ctx;
  884. ...
  885. ret = wolfSSL_CTX_use_PrivateKey_file(ctx, “./server-key.pem”,
  886. SSL_FILETYPE_PEM);
  887. if (ret != SSL_SUCCESS) {
  888. // error loading key file
  889. }
  890. ...
  891. \endcode
  892. \sa wolfSSL_CTX_use_PrivateKey_buffer
  893. \sa wolfSSL_use_PrivateKey_file
  894. \sa wolfSSL_use_PrivateKey_buffer
  895. \sa wc_CryptoCb_RegisterDevice
  896. \sa wolfSSL_CTX_SetDevId
  897. */
  898. int wolfSSL_CTX_use_PrivateKey_file(WOLFSSL_CTX* ctx, const char* file, int format);
  899. /*!
  900. \ingroup CertsKeys
  901. \brief This function loads PEM-formatted CA certificate files into the SSL
  902. context (WOLFSSL_CTX). These certificates will be treated as trusted root
  903. certificates and used to verify certs received from peers during the SSL
  904. handshake. The root certificate file, provided by the file argument, may
  905. be a single certificate or a file containing multiple certificates.
  906. If multiple CA certs are included in the same file, wolfSSL will load them
  907. in the same order they are presented in the file. The path argument is
  908. a pointer to the name of a directory that contains certificates of
  909. trusted root CAs. If the value of file is not NULL, path may be specified
  910. as NULL if not needed. If path is specified and NO_WOLFSSL_DIR was not
  911. defined when building the library, wolfSSL will load all CA certificates
  912. located in the given directory. This function will attempt to load all
  913. files in the directory. This function expects PEM formatted CERT_TYPE
  914. file with header “-----BEGIN CERTIFICATE-----”.
  915. \return SSL_SUCCESS up success.
  916. \return SSL_FAILURE will be returned if ctx is NULL, or if both file and
  917. path are NULL.
  918. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  919. \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
  920. read, or is corrupted.
  921. \return MEMORY_E will be returned if an out of memory condition occurs.
  922. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  923. \return ASN_BEFORE_DATE_E will be returned if the current date is before the
  924. before date.
  925. \return ASN_AFTER_DATE_E will be returned if the current date is after the
  926. after date.
  927. \return BUFFER_E will be returned if a chain buffer is bigger than the
  928. receiving buffer.
  929. \return BAD_PATH_ERROR will be returned if opendir() fails when trying
  930. to open path.
  931. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  932. \param file pointer to name of the file containing PEM-formatted CA
  933. certificates.
  934. \param path pointer to the name of a directory to load PEM-formatted
  935. certificates from.
  936. _Example_
  937. \code
  938. int ret = 0;
  939. WOLFSSL_CTX* ctx;
  940. ...
  941. ret = wolfSSL_CTX_load_verify_locations(ctx, “./ca-cert.pem”, NULL);
  942. if (ret != WOLFSSL_SUCCESS) {
  943. // error loading CA certs
  944. }
  945. ...
  946. \endcode
  947. \sa wolfSSL_CTX_load_verify_locations_ex
  948. \sa wolfSSL_CTX_load_verify_buffer
  949. \sa wolfSSL_CTX_use_certificate_file
  950. \sa wolfSSL_CTX_use_PrivateKey_file
  951. \sa wolfSSL_CTX_use_certificate_chain_file
  952. \sa wolfSSL_use_certificate_file
  953. \sa wolfSSL_use_PrivateKey_file
  954. \sa wolfSSL_use_certificate_chain_file
  955. */
  956. int wolfSSL_CTX_load_verify_locations(WOLFSSL_CTX* ctx, const char* file,
  957. const char* path);
  958. /*!
  959. \ingroup CertsKeys
  960. \brief This function loads PEM-formatted CA certificate files into the SSL
  961. context (WOLFSSL_CTX). These certificates will be treated as trusted root
  962. certificates and used to verify certs received from peers during the SSL
  963. handshake. The root certificate file, provided by the file argument, may
  964. be a single certificate or a file containing multiple certificates.
  965. If multiple CA certs are included in the same file, wolfSSL will load them
  966. in the same order they are presented in the file. The path argument is
  967. a pointer to the name of a directory that contains certificates of
  968. trusted root CAs. If the value of file is not NULL, path may be specified
  969. as NULL if not needed. If path is specified and NO_WOLFSSL_DIR was not
  970. defined when building the library, wolfSSL will load all CA certificates
  971. located in the given directory. This function will attempt to load all
  972. files in the directory based on flags specified. This function expects PEM
  973. formatted CERT_TYPE files with header “-----BEGIN CERTIFICATE-----”.
  974. \return SSL_SUCCESS up success.
  975. \return SSL_FAILURE will be returned if ctx is NULL, or if both file and
  976. path are NULL. This will also be returned if at least one cert is loaded
  977. successfully but there is one or more that failed. Check error stack for reason.
  978. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  979. \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
  980. read, or is corrupted.
  981. \return MEMORY_E will be returned if an out of memory condition occurs.
  982. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  983. \return BUFFER_E will be returned if a chain buffer is bigger than the
  984. receiving buffer.
  985. \return BAD_PATH_ERROR will be returned if opendir() fails when trying
  986. to open path.
  987. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  988. \param file pointer to name of the file containing PEM-formatted CA
  989. certificates.
  990. \param path pointer to the name of a directory to load PEM-formatted
  991. certificates from.
  992. \param flags possible mask values are: WOLFSSL_LOAD_FLAG_IGNORE_ERR,
  993. WOLFSSL_LOAD_FLAG_DATE_ERR_OKAY and WOLFSSL_LOAD_FLAG_PEM_CA_ONLY
  994. _Example_
  995. \code
  996. int ret = 0;
  997. WOLFSSL_CTX* ctx;
  998. ...
  999. ret = wolfSSL_CTX_load_verify_locations_ex(ctx, NULL, “./certs/external",
  1000. WOLFSSL_LOAD_FLAG_PEM_CA_ONLY);
  1001. if (ret != WOLFSSL_SUCCESS) {
  1002. // error loading CA certs
  1003. }
  1004. ...
  1005. \endcode
  1006. \sa wolfSSL_CTX_load_verify_locations
  1007. \sa wolfSSL_CTX_load_verify_buffer
  1008. \sa wolfSSL_CTX_use_certificate_file
  1009. \sa wolfSSL_CTX_use_PrivateKey_file
  1010. \sa wolfSSL_CTX_use_certificate_chain_file
  1011. \sa wolfSSL_use_certificate_file
  1012. \sa wolfSSL_use_PrivateKey_file
  1013. \sa wolfSSL_use_certificate_chain_file
  1014. */
  1015. int wolfSSL_CTX_load_verify_locations_ex(WOLFSSL_CTX* ctx, const char* file,
  1016. const char* path, unsigned int flags);
  1017. /*!
  1018. \ingroup CertsKeys
  1019. \brief This function returns a pointer to an array of strings representing
  1020. directories wolfSSL will search for system CA certs when
  1021. wolfSSL_CTX_load_system_CA_certs is called. On systems that don't store
  1022. certificates in an accessible system directory (such as Apple platforms),
  1023. this function will always return NULL.
  1024. \return Valid pointer on success.
  1025. \return NULL pointer on failure.
  1026. \param num pointer to a word32 that will be populated with the length of the
  1027. array of strings.
  1028. _Example_
  1029. \code
  1030. WOLFSSL_CTX* ctx;
  1031. const char** dirs;
  1032. word32 numDirs;
  1033. dirs = wolfSSL_get_system_CA_dirs(&numDirs);
  1034. for (int i = 0; i < numDirs; ++i) {
  1035. printf("Potential system CA dir: %s\n", dirs[i]);
  1036. }
  1037. ...
  1038. \endcode
  1039. \sa wolfSSL_CTX_load_system_CA_certs
  1040. \sa wolfSSL_CTX_load_verify_locations
  1041. \sa wolfSSL_CTX_load_verify_locations_ex
  1042. */
  1043. const char** wolfSSL_get_system_CA_dirs(word32* num);
  1044. /*!
  1045. \ingroup CertsKeys
  1046. \brief On most platforms (including Linux and Windows), this function
  1047. attempts to load CA certificates into a WOLFSSL_CTX from an OS-dependent
  1048. CA certificate store. Loaded certificates will be trusted.
  1049. On Apple platforms (excluding macOS), certificates can't be obtained from
  1050. the system, and therefore cannot be loaded into the wolfSSL certificate
  1051. manager. For these platforms, this function enables TLS connections bound to
  1052. the WOLFSSL_CTX to use the native system trust APIs to verify authenticity
  1053. of the peer certificate chain if the authenticity of the peer cannot first
  1054. be authenticated against certificates loaded by the user.
  1055. The platforms supported and tested are: Linux (Debian, Ubuntu,
  1056. Gentoo, Fedora, RHEL), Windows 10/11, Android, macOS, and iOS.
  1057. \return WOLFSSL_SUCCESS on success.
  1058. \return WOLFSSL_BAD_PATH if no system CA certs were loaded.
  1059. \return WOLFSSL_FAILURE for other failure types (e.g. Windows cert store
  1060. wasn't properly closed).
  1061. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  1062. _Example_
  1063. \code
  1064. int ret = 0;
  1065. WOLFSSL_CTX* ctx;
  1066. ...
  1067. ret = wolfSSL_CTX_load_system_CA_certs(ctx,);
  1068. if (ret != WOLFSSL_SUCCESS) {
  1069. // error loading system CA certs
  1070. }
  1071. ...
  1072. \endcode
  1073. \sa wolfSSL_get_system_CA_dirs
  1074. \sa wolfSSL_CTX_load_verify_locations
  1075. \sa wolfSSL_CTX_load_verify_locations_ex
  1076. */
  1077. int wolfSSL_CTX_load_system_CA_certs(WOLFSSL_CTX* ctx);
  1078. /*!
  1079. \ingroup Setup
  1080. \brief This function loads a certificate to use for verifying a peer
  1081. when performing a TLS/SSL handshake. The peer certificate sent during the
  1082. handshake is compared by using the SKID when available and the signature.
  1083. If these two things do not match then any loaded CAs are used. Feature is
  1084. enabled by defining the macro WOLFSSL_TRUST_PEER_CERT. Please see the
  1085. examples for proper usage.
  1086. \return SSL_SUCCES upon success.
  1087. \return SSL_FAILURE will be returned if ctx is NULL, or if both file and
  1088. type are invalid.
  1089. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  1090. \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
  1091. read, or is corrupted.
  1092. \return MEMORY_E will be returned if an out of memory condition occurs.
  1093. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  1094. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  1095. \param file pointer to name of the file containing certificates
  1096. \param type type of certificate being loaded ie SSL_FILETYPE_ASN1
  1097. or SSL_FILETYPE_PEM.
  1098. _Example_
  1099. \code
  1100. int ret = 0;
  1101. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  1102. ...
  1103. ret = wolfSSL_CTX_trust_peer_cert(ctx, “./peer-cert.pem”,
  1104. SSL_FILETYPE_PEM);
  1105. if (ret != SSL_SUCCESS) {
  1106. // error loading trusted peer cert
  1107. }
  1108. ...
  1109. \endcode
  1110. \sa wolfSSL_CTX_load_verify_buffer
  1111. \sa wolfSSL_CTX_use_certificate_file
  1112. \sa wolfSSL_CTX_use_PrivateKey_file
  1113. \sa wolfSSL_CTX_use_certificate_chain_file
  1114. \sa wolfSSL_CTX_trust_peer_buffer
  1115. \sa wolfSSL_CTX_Unload_trust_peers
  1116. \sa wolfSSL_use_certificate_file
  1117. \sa wolfSSL_use_PrivateKey_file
  1118. \sa wolfSSL_use_certificate_chain_file
  1119. */
  1120. int wolfSSL_CTX_trust_peer_cert(WOLFSSL_CTX* ctx, const char* file, int type);
  1121. /*!
  1122. \ingroup CertsKeys
  1123. \brief This function loads a chain of certificates into the SSL
  1124. context (WOLFSSL_CTX). The file containing the certificate chain
  1125. is provided by the file argument, and must contain PEM-formatted
  1126. certificates. This function will process up to MAX_CHAIN_DEPTH
  1127. (default = 9, defined in internal.h) certificates, plus the subject cert.
  1128. \return SSL_SUCCESS upon success
  1129. \return SSL_FAILURE If the function call fails, possible causes might
  1130. include the file is in the wrong format, or the wrong format has been
  1131. given using the “format” argument, file doesn’t exist, can’t be read,
  1132. or is corrupted, an out of memory condition occurs.
  1133. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  1134. wolfSSL_CTX_new()
  1135. \param file a pointer to the name of the file containing the chain of
  1136. certificates to be loaded into the wolfSSL SSL context. Certificates
  1137. must be in PEM format.
  1138. _Example_
  1139. \code
  1140. int ret = 0;
  1141. WOLFSSL_CTX* ctx;
  1142. ...
  1143. ret = wolfSSL_CTX_use_certificate_chain_file(ctx, “./cert-chain.pem”);
  1144. if (ret != SSL_SUCCESS) {
  1145. // error loading cert file
  1146. }
  1147. ...
  1148. \endcode
  1149. \sa wolfSSL_CTX_use_certificate_file
  1150. \sa wolfSSL_CTX_use_certificate_buffer
  1151. \sa wolfSSL_use_certificate_file
  1152. \sa wolfSSL_use_certificate_buffer
  1153. */
  1154. int wolfSSL_CTX_use_certificate_chain_file(WOLFSSL_CTX *ctx,
  1155. const char *file);
  1156. /*!
  1157. \ingroup openSSL
  1158. \brief This function loads the private RSA key used in the SSL connection
  1159. into the SSL context (WOLFSSL_CTX). This function is only available when
  1160. wolfSSL has been compiled with the OpenSSL compatibility layer enabled
  1161. (--enable-opensslExtra, #define OPENSSL_EXTRA), and is identical to the
  1162. more-typically used wolfSSL_CTX_use_PrivateKey_file() function. The file
  1163. argument contains a pointer to the RSA private key file, in the format
  1164. specified by format.
  1165. \return SSL_SUCCESS upon success.
  1166. \return SSL_FAILURE If the function call fails, possible causes might
  1167. include: The input key file is in the wrong format, or the wrong format
  1168. has been given using the “format” argument, file doesn’t exist, can’t
  1169. be read, or is corrupted, an out of memory condition occurs.
  1170. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  1171. wolfSSL_CTX_new()
  1172. \param file a pointer to the name of the file containing the RSA private
  1173. key to be loaded into the wolfSSL SSL context, with format as specified
  1174. by format.
  1175. \param format the encoding type of the RSA private key specified by file.
  1176. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.
  1177. _Example_
  1178. \code
  1179. int ret = 0;
  1180. WOLFSSL_CTX* ctx;
  1181. ...
  1182. ret = wolfSSL_CTX_use_RSAPrivateKey_file(ctx, “./server-key.pem”,
  1183. SSL_FILETYPE_PEM);
  1184. if (ret != SSL_SUCCESS) {
  1185. // error loading private key file
  1186. }
  1187. ...
  1188. \endcode
  1189. \sa wolfSSL_CTX_use_PrivateKey_buffer
  1190. \sa wolfSSL_CTX_use_PrivateKey_file
  1191. \sa wolfSSL_use_RSAPrivateKey_file
  1192. \sa wolfSSL_use_PrivateKey_buffer
  1193. \sa wolfSSL_use_PrivateKey_file
  1194. */
  1195. int wolfSSL_CTX_use_RSAPrivateKey_file(WOLFSSL_CTX* ctx, const char* file, int format);
  1196. /*!
  1197. \ingroup IO
  1198. \brief This function returns the maximum chain depth allowed, which is 9 by
  1199. default, for a valid session i.e. there is a non-null session object (ssl).
  1200. \return MAX_CHAIN_DEPTH returned if the WOLFSSL structure is not
  1201. NULL. By default the value is 9.
  1202. \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.
  1203. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  1204. _Example_
  1205. \code
  1206. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  1207. WOLFSSL* ssl = wolfSSL_new(ctx);
  1208. ...
  1209. long sslDep = wolfSSL_get_verify_depth(ssl);
  1210. if(sslDep > EXPECTED){
  1211. // The verified depth is greater than what was expected
  1212. } else {
  1213. // The verified depth is smaller or equal to the expected value
  1214. }
  1215. \endcode
  1216. \sa wolfSSL_CTX_get_verify_depth
  1217. */
  1218. long wolfSSL_get_verify_depth(WOLFSSL* ssl);
  1219. /*!
  1220. \ingroup Setup
  1221. \brief This function gets the certificate chaining depth using the
  1222. CTX structure.
  1223. \return MAX_CHAIN_DEPTH returned if the CTX struct is not NULL. The
  1224. constant representation of the max certificate chain peer depth.
  1225. \return BAD_FUNC_ARG returned if the CTX structure is NULL.
  1226. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  1227. wolfSSL_CTX_new().
  1228. _Example_
  1229. \code
  1230. WOLFSSL_METHOD method; // protocol method
  1231. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);
  1232. long ret = wolfSSL_CTX_get_verify_depth(ctx);
  1233. if(ret == EXPECTED){
  1234. // You have the expected value
  1235. } else {
  1236. // Handle an unexpected depth
  1237. }
  1238. \endcode
  1239. \sa wolfSSL_CTX_use_certificate_chain_file
  1240. \sa wolfSSL_get_verify_depth
  1241. */
  1242. long wolfSSL_CTX_get_verify_depth(WOLFSSL_CTX* ctx);
  1243. /*!
  1244. \ingroup openSSL
  1245. \brief This function loads a certificate file into the SSL session
  1246. (WOLFSSL structure). The certificate file is provided by the file
  1247. argument. The format argument specifies the format type of the file -
  1248. either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
  1249. \return SSL_SUCCESS upon success
  1250. \return SSL_FAILURE If the function call fails, possible causes might
  1251. include: The file is in the wrong format, or the wrong format has been
  1252. given using the “format” argument, file doesn’t exist, can’t be read,
  1253. or is corrupted, an out of memory condition occurs, Base16 decoding
  1254. fails on the file
  1255. \param ssl a pointer to a WOLFSSL structure, created with wolfSSL_new().
  1256. \param file a pointer to the name of the file containing the certificate to
  1257. be loaded into the wolfSSL SSL session, with format as specified by format.
  1258. \param format the encoding type of the certificate specified by file.
  1259. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.
  1260. _Example_
  1261. \code
  1262. int ret = 0;
  1263. WOLFSSL* ssl;
  1264. ...
  1265. ret = wolfSSL_use_certificate_file(ssl, “./client-cert.pem”,
  1266. SSL_FILETYPE_PEM);
  1267. if (ret != SSL_SUCCESS) {
  1268. // error loading cert file
  1269. }
  1270. ...
  1271. \endcode
  1272. \sa wolfSSL_CTX_use_certificate_buffer
  1273. \sa wolfSSL_CTX_use_certificate_file
  1274. \sa wolfSSL_use_certificate_buffer
  1275. */
  1276. int wolfSSL_use_certificate_file(WOLFSSL* ssl, const char* file, int format);
  1277. /*!
  1278. \ingroup openSSL
  1279. \brief This function loads a private key file into the SSL session
  1280. (WOLFSSL structure). The key file is provided by the file argument.
  1281. The format argument specifies the format type of the file -
  1282. SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
  1283. If using an external key store and do not have the private key you can
  1284. instead provide the public key and register the crypro callback to handle
  1285. the signing. For this you can build with either build with crypto callbacks
  1286. or PK callbacks. To enable crypto callbacks use --enable-cryptocb or
  1287. WOLF_CRYPTO_CB and register a crypto callback using
  1288. wc_CryptoCb_RegisterDevice and set the associated devId using
  1289. wolfSSL_SetDevId.
  1290. \return SSL_SUCCESS upon success.
  1291. \return SSL_FAILURE If the function call fails, possible causes might
  1292. include: The file is in the wrong format, or the wrong format has been
  1293. given using the “format” argument, The file doesn’t exist, can’t be read,
  1294. or is corrupted, An out of memory condition occurs, Base16 decoding
  1295. fails on the file, The key file is encrypted but no password is provided
  1296. \param ssl a pointer to a WOLFSSL structure, created with wolfSSL_new().
  1297. \param file a pointer to the name of the file containing the key file to
  1298. be loaded into the wolfSSL SSL session, with format as specified by format.
  1299. \param format the encoding type of the key specified by file. Possible
  1300. values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.
  1301. _Example_
  1302. \code
  1303. int ret = 0;
  1304. WOLFSSL* ssl;
  1305. ...
  1306. ret = wolfSSL_use_PrivateKey_file(ssl, “./server-key.pem”,
  1307. SSL_FILETYPE_PEM);
  1308. if (ret != SSL_SUCCESS) {
  1309. // error loading key file
  1310. }
  1311. ...
  1312. \endcode
  1313. \sa wolfSSL_CTX_use_PrivateKey_buffer
  1314. \sa wolfSSL_CTX_use_PrivateKey_file
  1315. \sa wolfSSL_use_PrivateKey_buffer
  1316. \sa wc_CryptoCb_RegisterDevice
  1317. \sa wolfSSL_SetDevId
  1318. */
  1319. int wolfSSL_use_PrivateKey_file(WOLFSSL* ssl, const char* file, int format);
  1320. /*!
  1321. \ingroup openSSL
  1322. \brief This function loads a chain of certificates into the SSL
  1323. session (WOLFSSL structure). The file containing the certificate
  1324. chain is provided by the file argument, and must contain PEM-formatted
  1325. certificates. This function will process up to MAX_CHAIN_DEPTH
  1326. (default = 9, defined in internal.h) certificates, plus the
  1327. subject certificate.
  1328. \return SSL_SUCCESS upon success.
  1329. \return SSL_FAILURE If the function call fails, possible causes
  1330. might include: The file is in the wrong format, or the wrong format
  1331. has been given using the “format” argument, file doesn’t exist,
  1332. can’t be read, or is corrupted, an out of memory condition occurs
  1333. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new()
  1334. \param file a pointer to the name of the file containing the chain
  1335. of certificates to be loaded into the wolfSSL SSL session.
  1336. Certificates must be in PEM format.
  1337. _Example_
  1338. \code
  1339. int ret = 0;
  1340. WOLFSSL* ctx;
  1341. ...
  1342. ret = wolfSSL_use_certificate_chain_file(ssl, “./cert-chain.pem”);
  1343. if (ret != SSL_SUCCESS) {
  1344. // error loading cert file
  1345. }
  1346. ...
  1347. \endcode
  1348. \sa wolfSSL_CTX_use_certificate_chain_file
  1349. \sa wolfSSL_CTX_use_certificate_chain_buffer
  1350. \sa wolfSSL_use_certificate_chain_buffer
  1351. */
  1352. int wolfSSL_use_certificate_chain_file(WOLFSSL* ssl, const char *file);
  1353. /*!
  1354. \ingroup openSSL
  1355. \brief This function loads the private RSA key used in the SSL
  1356. connection into the SSL session (WOLFSSL structure). This
  1357. function is only available when wolfSSL has been compiled with
  1358. the OpenSSL compatibility layer enabled (--enable-opensslExtra,
  1359. #define OPENSSL_EXTRA), and is identical to the more-typically
  1360. used wolfSSL_use_PrivateKey_file() function. The file argument
  1361. contains a pointer to the RSA private key file, in the format
  1362. specified by format.
  1363. \return SSL_SUCCESS upon success
  1364. \return SSL_FAILURE If the function call fails, possible causes might
  1365. include: The input key file is in the wrong format, or the wrong format
  1366. has been given using the “format” argument, file doesn’t exist, can’t
  1367. be read, or is corrupted, an out of memory condition occurs
  1368. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new()
  1369. \param file a pointer to the name of the file containing the RSA private
  1370. key to be loaded into the wolfSSL SSL session, with format as specified
  1371. by format.
  1372. \param format the encoding type of the RSA private key specified by file.
  1373. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.
  1374. _Example_
  1375. \code
  1376. int ret = 0;
  1377. WOLFSSL* ssl;
  1378. ...
  1379. ret = wolfSSL_use_RSAPrivateKey_file(ssl, “./server-key.pem”,
  1380. SSL_FILETYPE_PEM);
  1381. if (ret != SSL_SUCCESS) {
  1382. // error loading private key file
  1383. }
  1384. ...
  1385. \endcode
  1386. \sa wolfSSL_CTX_use_RSAPrivateKey_file
  1387. \sa wolfSSL_CTX_use_PrivateKey_buffer
  1388. \sa wolfSSL_CTX_use_PrivateKey_file
  1389. \sa wolfSSL_use_PrivateKey_buffer
  1390. \sa wolfSSL_use_PrivateKey_file
  1391. */
  1392. int wolfSSL_use_RSAPrivateKey_file(WOLFSSL* ssl, const char* file, int format);
  1393. /*!
  1394. \ingroup CertsKeys
  1395. \brief This function is similar to wolfSSL_CTX_load_verify_locations,
  1396. but allows the loading of DER-formatted CA files into the SSL context
  1397. (WOLFSSL_CTX). It may still be used to load PEM-formatted CA files as
  1398. well. These certificates will be treated as trusted root certificates
  1399. and used to verify certs received from peers during the SSL handshake.
  1400. The root certificate file, provided by the file argument, may be a single
  1401. certificate or a file containing multiple certificates. If multiple CA
  1402. certs are included in the same file, wolfSSL will load them in the same
  1403. order they are presented in the file. The format argument specifies the
  1404. format which the certificates are in either, SSL_FILETYPE_PEM or
  1405. SSL_FILETYPE_ASN1 (DER). Unlike wolfSSL_CTX_load_verify_locations,
  1406. this function does not allow the loading of CA certificates from a given
  1407. directory path. Note that this function is only available when the wolfSSL
  1408. library was compiled with WOLFSSL_DER_LOAD defined.
  1409. \return SSL_SUCCESS upon success.
  1410. \return SSL_FAILURE upon failure.
  1411. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  1412. wolfSSL_CTX_new()
  1413. \param file a pointer to the name of the file containing the CA
  1414. certificates to be loaded into the wolfSSL SSL context, with format
  1415. as specified by format.
  1416. \param format the encoding type of the certificates specified by file.
  1417. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.
  1418. _Example_
  1419. \code
  1420. int ret = 0;
  1421. WOLFSSL_CTX* ctx;
  1422. ...
  1423. ret = wolfSSL_CTX_der_load_verify_locations(ctx, “./ca-cert.der”,
  1424. SSL_FILETYPE_ASN1);
  1425. if (ret != SSL_SUCCESS) {
  1426. // error loading CA certs
  1427. }
  1428. ...
  1429. \endcode
  1430. \sa wolfSSL_CTX_load_verify_locations
  1431. \sa wolfSSL_CTX_load_verify_buffer
  1432. */
  1433. int wolfSSL_CTX_der_load_verify_locations(WOLFSSL_CTX* ctx,
  1434. const char* file, int format);
  1435. /*!
  1436. \ingroup Setup
  1437. \brief This function creates a new SSL context, taking a desired
  1438. SSL/TLS protocol method for input.
  1439. \return pointer If successful the call will return a pointer to the
  1440. newly-created WOLFSSL_CTX.
  1441. \return NULL upon failure.
  1442. \param method pointer to the desired WOLFSSL_METHOD to use for the SSL
  1443. context. This is created using one of the wolfSSLvXX_XXXX_method()
  1444. functions to specify SSL/TLS/DTLS protocol level.
  1445. _Example_
  1446. \code
  1447. WOLFSSL_CTX* ctx = 0;
  1448. WOLFSSL_METHOD* method = 0;
  1449. method = wolfSSLv3_client_method();
  1450. if (method == NULL) {
  1451. // unable to get method
  1452. }
  1453. ctx = wolfSSL_CTX_new(method);
  1454. if (ctx == NULL) {
  1455. // context creation failed
  1456. }
  1457. \endcode
  1458. \sa wolfSSL_new
  1459. */
  1460. WOLFSSL_CTX* wolfSSL_CTX_new(WOLFSSL_METHOD*);
  1461. /*!
  1462. \ingroup Setup
  1463. \brief This function creates a new SSL session, taking an already
  1464. created SSL context as input.
  1465. \return * If successful the call will return a pointer to the
  1466. newly-created wolfSSL structure.
  1467. \return NULL Upon failure.
  1468. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  1469. _Example_
  1470. \code
  1471. #include <wolfssl/ssl.h>
  1472. WOLFSSL* ssl = NULL;
  1473. WOLFSSL_CTX* ctx = 0;
  1474. ctx = wolfSSL_CTX_new(method);
  1475. if (ctx == NULL) {
  1476. // context creation failed
  1477. }
  1478. ssl = wolfSSL_new(ctx);
  1479. if (ssl == NULL) {
  1480. // SSL object creation failed
  1481. }
  1482. \endcode
  1483. \sa wolfSSL_CTX_new
  1484. */
  1485. WOLFSSL* wolfSSL_new(WOLFSSL_CTX*);
  1486. /*!
  1487. \ingroup Setup
  1488. \brief This function assigns a file descriptor (fd) as the
  1489. input/output facility for the SSL connection. Typically this will be
  1490. a socket file descriptor.
  1491. \return SSL_SUCCESS upon success.
  1492. \return BAD_FUNC_ARG upon failure.
  1493. \param ssl pointer to the SSL session, created with wolfSSL_new().
  1494. \param fd file descriptor to use with SSL/TLS connection.
  1495. _Example_
  1496. \code
  1497. int sockfd;
  1498. WOLFSSL* ssl = 0;
  1499. ...
  1500. ret = wolfSSL_set_fd(ssl, sockfd);
  1501. if (ret != SSL_SUCCESS) {
  1502. // failed to set SSL file descriptor
  1503. }
  1504. \endcode
  1505. \sa wolfSSL_CTX_SetIOSend
  1506. \sa wolfSSL_CTX_SetIORecv
  1507. \sa wolfSSL_SetIOReadCtx
  1508. \sa wolfSSL_SetIOWriteCtx
  1509. */
  1510. int wolfSSL_set_fd(WOLFSSL* ssl, int fd);
  1511. /*!
  1512. \ingroup Setup
  1513. \brief This function assigns a file descriptor (fd) as the
  1514. input/output facility for the SSL connection. Typically this will be
  1515. a socket file descriptor. This is a DTLS specific API because it marks that
  1516. the socket is connected. recvfrom and sendto calls on this fd will have the
  1517. addr and addr_len parameters set to NULL.
  1518. \return SSL_SUCCESS upon success.
  1519. \return BAD_FUNC_ARG upon failure.
  1520. \param ssl pointer to the SSL session, created with wolfSSL_new().
  1521. \param fd file descriptor to use with SSL/TLS connection.
  1522. _Example_
  1523. \code
  1524. int sockfd;
  1525. WOLFSSL* ssl = 0;
  1526. ...
  1527. if (connect(sockfd, peer_addr, peer_addr_len) != 0) {
  1528. // handle connect error
  1529. }
  1530. ...
  1531. ret = wolfSSL_set_dtls_fd_connected(ssl, sockfd);
  1532. if (ret != SSL_SUCCESS) {
  1533. // failed to set SSL file descriptor
  1534. }
  1535. \endcode
  1536. \sa wolfSSL_CTX_SetIOSend
  1537. \sa wolfSSL_CTX_SetIORecv
  1538. \sa wolfSSL_SetIOReadCtx
  1539. \sa wolfSSL_SetIOWriteCtx
  1540. \sa wolfDTLS_SetChGoodCb
  1541. */
  1542. int wolfSSL_set_dtls_fd_connected(WOLFSSL* ssl, int fd);
  1543. /*!
  1544. \ingroup Setup
  1545. \brief Allows setting a callback for a correctly processed and verified DTLS
  1546. client hello. When using a cookie exchange mechanism (either the
  1547. HelloVerifyRequest in DTLS 1.2 or the HelloRetryRequest with a cookie
  1548. extension in DTLS 1.3) this callback is called after the cookie
  1549. exchange has succeeded. This is useful to use one WOLFSSL object as
  1550. the listener for new connections and being able to isolate the
  1551. WOLFSSL object once the ClientHello is verified (either through a
  1552. cookie exchange or just checking if the ClientHello had the correct
  1553. format).
  1554. DTLS 1.2:
  1555. https://datatracker.ietf.org/doc/html/rfc6347#section-4.2.1
  1556. DTLS 1.3:
  1557. https://www.rfc-editor.org/rfc/rfc8446#section-4.2.2
  1558. \return SSL_SUCCESS upon success.
  1559. \return BAD_FUNC_ARG upon failure.
  1560. \param ssl pointer to the SSL session, created with wolfSSL_new().
  1561. \param fd file descriptor to use with SSL/TLS connection.
  1562. _Example_
  1563. \code
  1564. // Called when we have verified a connection
  1565. static int chGoodCb(WOLFSSL* ssl, void* arg)
  1566. {
  1567. // setup peer and file descriptors
  1568. }
  1569. if (wolfDTLS_SetChGoodCb(ssl, chGoodCb, NULL) != WOLFSSL_SUCCESS) {
  1570. // error setting callback
  1571. }
  1572. \endcode
  1573. \sa wolfSSL_set_dtls_fd_connected
  1574. */
  1575. int wolfDTLS_SetChGoodCb(WOLFSSL* ssl, ClientHelloGoodCb cb, void* user_ctx);
  1576. /*!
  1577. \ingroup IO
  1578. \brief Get the name of cipher at priority level passed in.
  1579. \return string Success
  1580. \return 0 Priority is either out of bounds or not valid.
  1581. \param priority Integer representing the priority level of a cipher.
  1582. _Example_
  1583. \code
  1584. printf("The cipher at 1 is %s", wolfSSL_get_cipher_list(1));
  1585. \endcode
  1586. \sa wolfSSL_CIPHER_get_name
  1587. \sa wolfSSL_get_current_cipher
  1588. */
  1589. char* wolfSSL_get_cipher_list(int priority);
  1590. /*!
  1591. \ingroup IO
  1592. \brief This function gets the ciphers enabled in wolfSSL.
  1593. \return SSL_SUCCESS returned if the function executed without error.
  1594. \return BAD_FUNC_ARG returned if the buf parameter was NULL or if the
  1595. len argument was less than or equal to zero.
  1596. \return BUFFER_E returned if the buffer is not large enough and
  1597. will overflow.
  1598. \param buf a char pointer representing the buffer.
  1599. \param len the length of the buffer.
  1600. _Example_
  1601. \code
  1602. static void ShowCiphers(void){
  1603. char* ciphers;
  1604. int ret = wolfSSL_get_ciphers(ciphers, (int)sizeof(ciphers));
  1605. if(ret == SSL_SUCCES){
  1606. printf(“%s\n”, ciphers);
  1607. }
  1608. }
  1609. \endcode
  1610. \sa GetCipherNames
  1611. \sa wolfSSL_get_cipher_list
  1612. \sa ShowCiphers
  1613. */
  1614. int wolfSSL_get_ciphers(char* buf, int len);
  1615. /*!
  1616. \ingroup IO
  1617. \brief This function gets the cipher name in the format DHE-RSA by
  1618. passing through argument to wolfSSL_get_cipher_name_internal.
  1619. \return string This function returns the string representation of the
  1620. cipher suite that was matched.
  1621. \return NULL error or cipher not found.
  1622. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  1623. _Example_
  1624. \code
  1625. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  1626. WOLFSSL* ssl = wolfSSL_new(ctx);
  1627. char* cipherS = wolfSSL_get_cipher_name(ssl);
  1628. if(cipher == NULL){
  1629. // There was not a cipher suite matched
  1630. } else {
  1631. // There was a cipher suite matched
  1632. printf(“%s\n”, cipherS);
  1633. }
  1634. \endcode
  1635. \sa wolfSSL_CIPHER_get_name
  1636. \sa wolfSSL_get_current_cipher
  1637. \sa wolfSSL_get_cipher_name_internal
  1638. */
  1639. const char* wolfSSL_get_cipher_name(WOLFSSL* ssl);
  1640. /*!
  1641. \ingroup IO
  1642. \brief This function returns the file descriptor (fd) used as the
  1643. input/output facility for the SSL connection. Typically this
  1644. will be a socket file descriptor.
  1645. \return fd If successful the call will return the SSL session file
  1646. descriptor.
  1647. \param ssl pointer to the SSL session, created with wolfSSL_new().
  1648. _Example_
  1649. \code
  1650. int sockfd;
  1651. WOLFSSL* ssl = 0;
  1652. ...
  1653. sockfd = wolfSSL_get_fd(ssl);
  1654. ...
  1655. \endcode
  1656. \sa wolfSSL_set_fd
  1657. */
  1658. int wolfSSL_get_fd(const WOLFSSL*);
  1659. /*!
  1660. \ingroup Setup
  1661. \brief This function informs the WOLFSSL object that the underlying
  1662. I/O is non-blocking. After an application creates a WOLFSSL object,
  1663. if it will be used with a non-blocking socket, call
  1664. wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know
  1665. that receiving EWOULDBLOCK means that the recvfrom call would
  1666. block rather than that it timed out.
  1667. \return none No return.
  1668. \param ssl pointer to the SSL session, created with wolfSSL_new().
  1669. \param nonblock value used to set non-blocking flag on WOLFSSL object.
  1670. Use 1 to specify non-blocking, otherwise 0.
  1671. _Example_
  1672. \code
  1673. WOLFSSL* ssl = 0;
  1674. ...
  1675. wolfSSL_set_using_nonblock(ssl, 1);
  1676. \endcode
  1677. \sa wolfSSL_get_using_nonblock
  1678. \sa wolfSSL_dtls_got_timeout
  1679. \sa wolfSSL_dtls_get_current_timeout
  1680. */
  1681. void wolfSSL_set_using_nonblock(WOLFSSL* ssl, int nonblock);
  1682. /*!
  1683. \ingroup IO
  1684. \brief This function allows the application to determine if wolfSSL is
  1685. using non-blocking I/O. If wolfSSL is using non-blocking I/O, this
  1686. function will return 1, otherwise 0. After an application creates a
  1687. WOLFSSL object, if it will be used with a non-blocking socket, call
  1688. wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know
  1689. that receiving EWOULDBLOCK means that the recvfrom call would block
  1690. rather than that it timed out.
  1691. \return 0 underlying I/O is blocking.
  1692. \return 1 underlying I/O is non-blocking.
  1693. \param ssl pointer to the SSL session, created with wolfSSL_new().
  1694. _Example_
  1695. \code
  1696. int ret = 0;
  1697. WOLFSSL* ssl = 0;
  1698. ...
  1699. ret = wolfSSL_get_using_nonblock(ssl);
  1700. if (ret == 1) {
  1701. // underlying I/O is non-blocking
  1702. }
  1703. ...
  1704. \endcode
  1705. \sa wolfSSL_set_session
  1706. */
  1707. int wolfSSL_get_using_nonblock(WOLFSSL*);
  1708. /*!
  1709. \ingroup IO
  1710. \brief This function writes sz bytes from the buffer, data, to the SSL
  1711. connection, ssl. If necessary, wolfSSL_write() will negotiate an SSL/TLS
  1712. session if the handshake has not already been performed yet by
  1713. wolfSSL_connect() or wolfSSL_accept(). When using (D)TLSv1.3 and early data
  1714. feature is compiled in, this function progresses the handshake only up to
  1715. the point when it is possible to send data. Next invokations of
  1716. wolfSSL_Connect()/wolfSSL_Accept()/wolfSSL_read() will complete the
  1717. handshake. wolfSSL_write() works with both blocking and non-blocking I/O.
  1718. When the underlying I/O is non-blocking, wolfSSL_write() will return when
  1719. the underlying I/O could not satisfy the needs of wolfSSL_write() to
  1720. continue. In this case, a call to wolfSSL_get_error() will yield either
  1721. SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then
  1722. repeat the call to wolfSSL_write() when the underlying I/O is ready. If the
  1723. underlying I/O is blocking, wolfSSL_write() will only return once the buffer
  1724. data of size sz has been completely written or an error occurred.
  1725. \return >0 the number of bytes written upon success.
  1726. \return 0 will be returned upon failure. Call wolfSSL_get_error() for
  1727. the specific error code.
  1728. \return SSL_FATAL_ERROR will be returned upon failure when either an error
  1729. occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or
  1730. SSL_ERROR_WANT_WRITE error was received and and the application needs to
  1731. call wolfSSL_write() again. Use wolfSSL_get_error() to get a specific
  1732. error code.
  1733. \param ssl pointer to the SSL session, created with wolfSSL_new().
  1734. \param data data buffer which will be sent to peer.
  1735. \param sz size, in bytes, of data to send to the peer (data).
  1736. _Example_
  1737. \code
  1738. WOLFSSL* ssl = 0;
  1739. char msg[64] = “hello wolfssl!”;
  1740. int msgSz = (int)strlen(msg);
  1741. int flags;
  1742. int ret;
  1743. ...
  1744. ret = wolfSSL_write(ssl, msg, msgSz);
  1745. if (ret <= 0) {
  1746. // wolfSSL_write() failed, call wolfSSL_get_error()
  1747. }
  1748. \endcode
  1749. \sa wolfSSL_send
  1750. \sa wolfSSL_read
  1751. \sa wolfSSL_recv
  1752. */
  1753. int wolfSSL_write(WOLFSSL* ssl, const void* data, int sz);
  1754. /*!
  1755. \ingroup IO
  1756. \brief This function reads sz bytes from the SSL session (ssl)
  1757. internal read buffer into the buffer data. The bytes read are removed
  1758. from the internal receive buffer. If necessary wolfSSL_read() will
  1759. negotiate an SSL/TLS session if the handshake has not already been
  1760. performed yet by wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS
  1761. protocol uses SSL records which have a maximum size of 16kB (the max
  1762. record size can be controlled by the MAX_RECORD_SIZE define in
  1763. <wolfssl_root>/wolfssl/internal.h). As such, wolfSSL needs to read an
  1764. entire SSL record internally before it is able to process and decrypt the
  1765. record. Because of this, a call to wolfSSL_read() will only be able to
  1766. return the maximum buffer size which has been decrypted at the time of
  1767. calling. There may be additional not-yet-decrypted data waiting in the
  1768. internal wolfSSL receive buffer which will be retrieved and decrypted with
  1769. the next call to wolfSSL_read(). If sz is larger than the number of bytes
  1770. in the internal read buffer, SSL_read() will return the bytes available in
  1771. the internal read buffer. If no bytes are buffered in the internal read
  1772. buffer yet, a call to wolfSSL_read() will trigger processing of the next
  1773. record.
  1774. \return >0 the number of bytes read upon success.
  1775. \return 0 will be returned upon failure. This may be caused by a either a
  1776. clean (close notify alert) shutdown or just that the peer closed the
  1777. connection. Call wolfSSL_get_error() for the specific error code.
  1778. \return SSL_FATAL_ERROR will be returned upon failure when either an error
  1779. occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or
  1780. SSL_ERROR_WANT_WRITE error was received and and the application needs to
  1781. call wolfSSL_read() again. Use wolfSSL_get_error() to get a specific
  1782. error code.
  1783. \param ssl pointer to the SSL session, created with wolfSSL_new().
  1784. \param data buffer where wolfSSL_read() will place data read.
  1785. \param sz number of bytes to read into data.
  1786. _Example_
  1787. \code
  1788. WOLFSSL* ssl = 0;
  1789. char reply[1024];
  1790. ...
  1791. input = wolfSSL_read(ssl, reply, sizeof(reply));
  1792. if (input > 0) {
  1793. // “input” number of bytes returned into buffer “reply”
  1794. }
  1795. See wolfSSL examples (client, server, echoclient, echoserver) for more
  1796. complete examples of wolfSSL_read().
  1797. \endcode
  1798. \sa wolfSSL_recv
  1799. \sa wolfSSL_write
  1800. \sa wolfSSL_peek
  1801. \sa wolfSSL_pending
  1802. */
  1803. int wolfSSL_read(WOLFSSL* ssl, void* data, int sz);
  1804. /*!
  1805. \ingroup IO
  1806. \brief This function copies sz bytes from the SSL session (ssl) internal
  1807. read buffer into the buffer data. This function is identical to
  1808. wolfSSL_read() except that the data in the internal SSL session
  1809. receive buffer is not removed or modified. If necessary, like
  1810. wolfSSL_read(), wolfSSL_peek() will negotiate an SSL/TLS session if
  1811. the handshake has not already been performed yet by wolfSSL_connect()
  1812. or wolfSSL_accept(). The SSL/TLS protocol uses SSL records which have a
  1813. maximum size of 16kB (the max record size can be controlled by the
  1814. MAX_RECORD_SIZE define in <wolfssl_root>/wolfssl/internal.h). As such,
  1815. wolfSSL needs to read an entire SSL record internally before it is able
  1816. to process and decrypt the record. Because of this, a call to
  1817. wolfSSL_peek() will only be able to return the maximum buffer size which
  1818. has been decrypted at the time of calling. There may be additional
  1819. not-yet-decrypted data waiting in the internal wolfSSL receive buffer
  1820. which will be retrieved and decrypted with the next call to
  1821. wolfSSL_peek() / wolfSSL_read(). If sz is larger than the number of bytes
  1822. in the internal read buffer, SSL_peek() will return the bytes available
  1823. in the internal read buffer. If no bytes are buffered in the internal
  1824. read buffer yet, a call to wolfSSL_peek() will trigger processing of the
  1825. next record.
  1826. \return >0 the number of bytes read upon success.
  1827. \return 0 will be returned upon failure. This may be caused by a either
  1828. a clean (close notify alert) shutdown or just that the peer closed the
  1829. connection. Call wolfSSL_get_error() for the specific error code.
  1830. \return SSL_FATAL_ERROR will be returned upon failure when either an
  1831. error occurred or, when using non-blocking sockets, the
  1832. SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and
  1833. the application needs to call wolfSSL_peek() again. Use
  1834. wolfSSL_get_error() to get a specific error code.
  1835. \param ssl pointer to the SSL session, created with wolfSSL_new().
  1836. \param data buffer where wolfSSL_peek() will place data read.
  1837. \param sz number of bytes to read into data.
  1838. _Example_
  1839. \code
  1840. WOLFSSL* ssl = 0;
  1841. char reply[1024];
  1842. ...
  1843. input = wolfSSL_peek(ssl, reply, sizeof(reply));
  1844. if (input > 0) {
  1845. // “input” number of bytes returned into buffer “reply”
  1846. }
  1847. \endcode
  1848. \sa wolfSSL_read
  1849. */
  1850. int wolfSSL_peek(WOLFSSL* ssl, void* data, int sz);
  1851. /*!
  1852. \ingroup IO
  1853. \brief This function is called on the server side and waits for an SSL
  1854. client to initiate the SSL/TLS handshake. When this function is called,
  1855. the underlying communication channel has already been set up.
  1856. wolfSSL_accept() works with both blocking and non-blocking I/O.
  1857. When the underlying I/O is non-blocking, wolfSSL_accept() will return
  1858. when the underlying I/O could not satisfy the needs of wolfSSL_accept
  1859. to continue the handshake. In this case, a call to wolfSSL_get_error()
  1860. will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.
  1861. The calling process must then repeat the call to wolfSSL_accept when
  1862. data is available to read and wolfSSL will pick up where it left off.
  1863. When using a non-blocking socket, nothing needs to be done, but select()
  1864. can be used to check for the required condition. If the underlying I/O
  1865. is blocking, wolfSSL_accept() will only return once the handshake has
  1866. been finished or an error occurred.
  1867. \return SSL_SUCCESS upon success.
  1868. \return SSL_FATAL_ERROR will be returned if an error occurred. To get a
  1869. more detailed error code, call wolfSSL_get_error().
  1870. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  1871. _Example_
  1872. \code
  1873. int ret = 0;
  1874. int err = 0;
  1875. WOLFSSL* ssl;
  1876. char buffer[80];
  1877. ...
  1878. ret = wolfSSL_accept(ssl);
  1879. if (ret != SSL_SUCCESS) {
  1880. err = wolfSSL_get_error(ssl, ret);
  1881. printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
  1882. }
  1883. \endcode
  1884. \sa wolfSSL_get_error
  1885. \sa wolfSSL_connect
  1886. */
  1887. int wolfSSL_accept(WOLFSSL*);
  1888. /*!
  1889. \ingroup Setup
  1890. \brief This function frees an allocated WOLFSSL_CTX object. This
  1891. function decrements the CTX reference count and only frees the context
  1892. when the reference count has reached 0.
  1893. \return none No return.
  1894. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  1895. _Example_
  1896. \code
  1897. WOLFSSL_CTX* ctx = 0;
  1898. ...
  1899. wolfSSL_CTX_free(ctx);
  1900. \endcode
  1901. \sa wolfSSL_CTX_new
  1902. \sa wolfSSL_new
  1903. \sa wolfSSL_free
  1904. */
  1905. void wolfSSL_CTX_free(WOLFSSL_CTX*);
  1906. /*!
  1907. \ingroup Setup
  1908. \brief This function frees an allocated wolfSSL object.
  1909. \return none No return.
  1910. \param ssl pointer to the SSL object, created with wolfSSL_new().
  1911. _Example_
  1912. \code
  1913. #include <wolfssl/ssl.h>
  1914. WOLFSSL* ssl = 0;
  1915. ...
  1916. wolfSSL_free(ssl);
  1917. \endcode
  1918. \sa wolfSSL_CTX_new
  1919. \sa wolfSSL_new
  1920. \sa wolfSSL_CTX_free
  1921. */
  1922. void wolfSSL_free(WOLFSSL*);
  1923. /*!
  1924. \ingroup TLS
  1925. \brief This function shuts down an active SSL/TLS connection using
  1926. the SSL session, ssl. This function will try to send a “close notify”
  1927. alert to the peer. The calling application can choose to wait for the
  1928. peer to send its “close notify” alert in response or just go ahead
  1929. and shut down the underlying connection after directly calling
  1930. wolfSSL_shutdown (to save resources). Either option is allowed by
  1931. the TLS specification. If the underlying connection will be used
  1932. again in the future, the complete two-directional shutdown procedure
  1933. must be performed to keep synchronization intact between the peers.
  1934. wolfSSL_shutdown() works with both blocking and non-blocking I/O.
  1935. When the underlying I/O is non-blocking, wolfSSL_shutdown() will
  1936. return an error if the underlying I/O could not satisfy the needs of
  1937. wolfSSL_shutdown() to continue. In this case, a call to
  1938. wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or
  1939. SSL_ERROR_WANT_WRITE. The calling process must then repeat the call
  1940. to wolfSSL_shutdown() when the underlying I/O is ready.
  1941. \return SSL_SUCCESS will be returned upon success.
  1942. \return SSL_SHUTDOWN_NOT_DONE will be returned when shutdown has not
  1943. finished, and the function should be called again.
  1944. \return SSL_FATAL_ERROR will be returned upon failure. Call
  1945. wolfSSL_get_error() for a more specific error code.
  1946. \param ssl pointer to the SSL session created with wolfSSL_new().
  1947. _Example_
  1948. \code
  1949. #include <wolfssl/ssl.h>
  1950. int ret = 0;
  1951. WOLFSSL* ssl = 0;
  1952. ...
  1953. ret = wolfSSL_shutdown(ssl);
  1954. if (ret != 0) {
  1955. // failed to shut down SSL connection
  1956. }
  1957. \endcode
  1958. \sa wolfSSL_free
  1959. \sa wolfSSL_CTX_free
  1960. */
  1961. int wolfSSL_shutdown(WOLFSSL*);
  1962. /*!
  1963. \ingroup IO
  1964. \brief This function writes sz bytes from the buffer, data, to the SSL
  1965. connection, ssl, using the specified flags for the underlying write
  1966. operation. If necessary wolfSSL_send() will negotiate an SSL/TLS session
  1967. if the handshake has not already been performed yet by wolfSSL_connect()
  1968. or wolfSSL_accept(). wolfSSL_send() works with both blocking and
  1969. non-blocking I/O. When the underlying I/O is non-blocking, wolfSSL_send()
  1970. will return when the underlying I/O could not satisfy the needs of
  1971. wolfSSL_send to continue. In this case, a call to wolfSSL_get_error()
  1972. will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.
  1973. The calling process must then repeat the call to wolfSSL_send() when
  1974. the underlying I/O is ready. If the underlying I/O is blocking,
  1975. wolfSSL_send() will only return once the buffer data of size sz has
  1976. been completely written or an error occurred.
  1977. \return >0 the number of bytes written upon success.
  1978. \return 0 will be returned upon failure. Call wolfSSL_get_error() for
  1979. the specific error code.
  1980. \return SSL_FATAL_ERROR will be returned upon failure when either an error
  1981. occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or
  1982. SSL_ERROR_WANT_WRITE error was received and and the application needs to
  1983. call wolfSSL_send() again. Use wolfSSL_get_error() to get a specific
  1984. error code.
  1985. \param ssl pointer to the SSL session, created with wolfSSL_new().
  1986. \param data data buffer to send to peer.
  1987. \param sz size, in bytes, of data to be sent to peer.
  1988. \param flags the send flags to use for the underlying send operation.
  1989. _Example_
  1990. \code
  1991. WOLFSSL* ssl = 0;
  1992. char msg[64] = “hello wolfssl!”;
  1993. int msgSz = (int)strlen(msg);
  1994. int flags = ... ;
  1995. ...
  1996. input = wolfSSL_send(ssl, msg, msgSz, flags);
  1997. if (input != msgSz) {
  1998. // wolfSSL_send() failed
  1999. }
  2000. \endcode
  2001. \sa wolfSSL_write
  2002. \sa wolfSSL_read
  2003. \sa wolfSSL_recv
  2004. */
  2005. int wolfSSL_send(WOLFSSL* ssl, const void* data, int sz, int flags);
  2006. /*!
  2007. \ingroup IO
  2008. \brief This function reads sz bytes from the SSL session (ssl) internal
  2009. read buffer into the buffer data using the specified flags for the
  2010. underlying recv operation. The bytes read are removed from the internal
  2011. receive buffer. This function is identical to wolfSSL_read() except
  2012. that it allows the application to set the recv flags for the underlying
  2013. read operation. If necessary wolfSSL_recv() will negotiate an SSL/TLS
  2014. session if the handshake has not already been performed yet by
  2015. wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS protocol uses
  2016. SSL records which have a maximum size of 16kB (the max record size
  2017. can be controlled by the MAX_RECORD_SIZE define in
  2018. <wolfssl_root>/wolfssl/internal.h). As such, wolfSSL needs to read an
  2019. entire SSL record internally before it is able to process and decrypt
  2020. the record. Because of this, a call to wolfSSL_recv() will only be
  2021. able to return the maximum buffer size which has been decrypted at
  2022. the time of calling. There may be additional not-yet-decrypted data
  2023. waiting in the internal wolfSSL receive buffer which will be
  2024. retrieved and decrypted with the next call to wolfSSL_recv(). If sz
  2025. is larger than the number of bytes in the internal read buffer,
  2026. SSL_recv() will return the bytes available in the internal read buffer.
  2027. If no bytes are buffered in the internal read buffer yet, a call to
  2028. wolfSSL_recv() will trigger processing of the next record.
  2029. \return >0 the number of bytes read upon success.
  2030. \return 0 will be returned upon failure. This may be caused by a either
  2031. a clean (close notify alert) shutdown or just that the peer closed the
  2032. connection. Call wolfSSL_get_error() for the specific error code.
  2033. \return SSL_FATAL_ERROR will be returned upon failure when either an error
  2034. occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or
  2035. SSL_ERROR_WANT_WRITE error was received and and the application needs to
  2036. call wolfSSL_recv() again. Use wolfSSL_get_error() to get a specific
  2037. error code.
  2038. \param ssl pointer to the SSL session, created with wolfSSL_new().
  2039. \param data buffer where wolfSSL_recv() will place data read.
  2040. \param sz number of bytes to read into data.
  2041. \param flags the recv flags to use for the underlying recv operation.
  2042. _Example_
  2043. \code
  2044. WOLFSSL* ssl = 0;
  2045. char reply[1024];
  2046. int flags = ... ;
  2047. ...
  2048. input = wolfSSL_recv(ssl, reply, sizeof(reply), flags);
  2049. if (input > 0) {
  2050. // “input” number of bytes returned into buffer “reply”
  2051. }
  2052. \endcode
  2053. \sa wolfSSL_read
  2054. \sa wolfSSL_write
  2055. \sa wolfSSL_peek
  2056. \sa wolfSSL_pending
  2057. */
  2058. int wolfSSL_recv(WOLFSSL* ssl, void* data, int sz, int flags);
  2059. /*!
  2060. \ingroup Debug
  2061. \brief This function returns a unique error code describing why the
  2062. previous API function call (wolfSSL_connect, wolfSSL_accept, wolfSSL_read,
  2063. wolfSSL_write, etc.) resulted in an error return code (SSL_FAILURE).
  2064. The return value of the previous function is passed to wolfSSL_get_error
  2065. through ret. After wolfSSL_get_error is called and returns the unique
  2066. error code, wolfSSL_ERR_error_string() may be called to get a
  2067. human-readable error string. See wolfSSL_ERR_error_string() for more
  2068. information.
  2069. \return On successful completion, this function will return the
  2070. unique error code describing why the previous API function failed.
  2071. \return SSL_ERROR_NONE will be returned if ret > 0. For ret <= 0, there are
  2072. some cases when this value can also be returned when a previous API appeared
  2073. to return an error code but no error actually occurred. An example is
  2074. calling wolfSSL_read() with a zero sz parameter. A 0 return from
  2075. wolfSSL_read() usually indicates an error but in this case no error
  2076. occurred. If wolfSSL_get_error() is called afterwards, SSL_ERROR_NONE will
  2077. be returned.
  2078. \param ssl pointer to the SSL object, created with wolfSSL_new().
  2079. \param ret return value of the previous function that resulted in an error
  2080. return code.
  2081. _Example_
  2082. \code
  2083. int err = 0;
  2084. WOLFSSL* ssl;
  2085. char buffer[80];
  2086. ...
  2087. err = wolfSSL_get_error(ssl, 0);
  2088. wolfSSL_ERR_error_string(err, buffer);
  2089. printf(“err = %d, %s\n”, err, buffer);
  2090. \endcode
  2091. \sa wolfSSL_ERR_error_string
  2092. \sa wolfSSL_ERR_error_string_n
  2093. \sa wolfSSL_ERR_print_errors_fp
  2094. \sa wolfSSL_load_error_strings
  2095. */
  2096. int wolfSSL_get_error(WOLFSSL* ssl, int ret);
  2097. /*!
  2098. \ingroup IO
  2099. \brief This function gets the alert history.
  2100. \return SSL_SUCCESS returned when the function completed successfully.
  2101. Either there was alert history or there wasn’t, either way, the
  2102. return value is SSL_SUCCESS.
  2103. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  2104. \param h a pointer to a WOLFSSL_ALERT_HISTORY structure that will hold the
  2105. WOLFSSL struct’s alert_history member’s value.
  2106. _Example_
  2107. \code
  2108. WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
  2109. WOLFSSL* ssl = wolfSSL_new(ctx);
  2110. WOLFSSL_ALERT_HISTORY* h;
  2111. ...
  2112. wolfSSL_get_alert_history(ssl, h);
  2113. // h now has a copy of the ssl->alert_history contents
  2114. \endcode
  2115. \sa wolfSSL_get_error
  2116. */
  2117. int wolfSSL_get_alert_history(WOLFSSL* ssl, WOLFSSL_ALERT_HISTORY *h);
  2118. /*!
  2119. \ingroup Setup
  2120. \brief This function sets the session to be used when the SSL object,
  2121. ssl, is used to establish a SSL/TLS connection. For session resumption,
  2122. before calling wolfSSL_shutdown() with your session object, an application
  2123. should save the session ID from the object with a call to
  2124. wolfSSL_get1_session(), which returns a pointer to the session.
  2125. Later, the application should create a new WOLFSSL object and assign
  2126. the saved session with wolfSSL_set_session(). At this point, the
  2127. application may call wolfSSL_connect() and wolfSSL will try to resume
  2128. the session. The wolfSSL server code allows session resumption by default.
  2129. The object returned by wolfSSL_get1_session() needs to be freed after the
  2130. application is done with it by calling wolfSSL_SESSION_free() on it.
  2131. \return SSL_SUCCESS will be returned upon successfully setting the session.
  2132. \return SSL_FAILURE will be returned on failure. This could be caused
  2133. by the session cache being disabled, or if the session has timed out.
  2134. \return When OPENSSL_EXTRA and WOLFSSL_ERROR_CODE_OPENSSL are defined,
  2135. SSL_SUCCESS will be returned even if the session has timed out.
  2136. \param ssl pointer to the SSL object, created with wolfSSL_new().
  2137. \param session pointer to the WOLFSSL_SESSION used to set the session
  2138. for ssl.
  2139. _Example_
  2140. \code
  2141. int ret;
  2142. WOLFSSL* ssl;
  2143. WOLFSSL_SESSION* session;
  2144. ...
  2145. session = wolfSSL_get1_session(ssl);
  2146. if (session == NULL) {
  2147. // failed to get session object from ssl object
  2148. }
  2149. ...
  2150. ret = wolfSSL_set_session(ssl, session);
  2151. if (ret != SSL_SUCCESS) {
  2152. // failed to set the SSL session
  2153. }
  2154. wolfSSL_SESSION_free(session);
  2155. ...
  2156. \endcode
  2157. \sa wolfSSL_get1_session
  2158. */
  2159. int wolfSSL_set_session(WOLFSSL* ssl, WOLFSSL_SESSION* session);
  2160. /*!
  2161. \ingroup IO
  2162. \brief When NO_SESSION_CACHE_REF is defined this function returns a pointer
  2163. to the current session (WOLFSSL_SESSION) used in ssl. This function returns
  2164. a non-persistent pointer to the WOLFSSL_SESSION object. The pointer returned
  2165. will be freed when wolfSSL_free is called. This call should only be used to
  2166. inspect or modify the current session. For session resumption it is
  2167. recommended to use wolfSSL_get1_session(). For backwards compatibility when
  2168. NO_SESSION_CACHE_REF is not defined this function returns a persistent
  2169. session object pointer that is stored in the local cache. The cache size is
  2170. finite and there is a risk that the session object will be overwritten by
  2171. another ssl connection by the time the application calls
  2172. wolfSSL_set_session() on it. It is recommended to define
  2173. NO_SESSION_CACHE_REF in your application and to use wolfSSL_get1_session()
  2174. for session resumption.
  2175. \return pointer If successful the call will return a pointer to the the
  2176. current SSL session object.
  2177. \return NULL will be returned if ssl is NULL, the SSL session cache is
  2178. disabled, wolfSSL doesn’t have the Session ID available, or mutex
  2179. functions fail.
  2180. \param ssl pointer to the SSL session, created with wolfSSL_new().
  2181. _Example_
  2182. \code
  2183. WOLFSSL* ssl;
  2184. WOLFSSL_SESSION* session;
  2185. ...
  2186. session = wolfSSL_get_session(ssl);
  2187. if (session == NULL) {
  2188. // failed to get session pointer
  2189. }
  2190. ...
  2191. \endcode
  2192. \sa wolfSSL_get1_session
  2193. \sa wolfSSL_set_session
  2194. */
  2195. WOLFSSL_SESSION* wolfSSL_get_session(WOLFSSL* ssl);
  2196. /*!
  2197. \ingroup IO
  2198. \brief This function flushes session from the session cache which
  2199. have expired. The time, tm, is used for the time comparison. Note
  2200. that wolfSSL currently uses a static table for sessions, so no flushing
  2201. is needed. As such, this function is currently just a stub. This
  2202. function provides OpenSSL compatibility (SSL_flush_sessions) when
  2203. wolfSSL is compiled with the OpenSSL compatibility layer.
  2204. \return none No returns.
  2205. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  2206. wolfSSL_CTX_new().
  2207. \param tm time used in session expiration comparison.
  2208. _Example_
  2209. \code
  2210. WOLFSSL_CTX* ssl;
  2211. ...
  2212. wolfSSL_flush_sessions(ctx, time(0));
  2213. \endcode
  2214. \sa wolfSSL_get1_session
  2215. \sa wolfSSL_set_session
  2216. */
  2217. void wolfSSL_flush_sessions(WOLFSSL_CTX* ctx, long tm);
  2218. /*!
  2219. \ingroup TLS
  2220. \brief This function associates the client session with the server id.
  2221. If the newSession flag is on, an existing session won’t be reused.
  2222. \return SSL_SUCCESS returned if the function executed without error.
  2223. \return BAD_FUNC_ARG returned if the WOLFSSL struct or id parameter
  2224. is NULL or if len is not greater than zero.
  2225. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  2226. \param id a constant byte pointer that will be copied to the
  2227. serverID member of the WOLFSSL_SESSION structure.
  2228. \param len an int type representing the length of the session id parameter.
  2229. \param newSession an int type representing the flag to denote whether
  2230. to reuse a session or not.
  2231. _Example_
  2232. \code
  2233. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol );
  2234. WOLFSSL* ssl = WOLFSSL_new(ctx);
  2235. const byte id[MAX_SIZE]; // or dynamically create space
  2236. int len = 0; // initialize length
  2237. int newSession = 0; // flag to allow
  2238. int ret = wolfSSL_SetServerID(ssl, id, len, newSession);
  2239. if (ret == WOLFSSL_SUCCESS) {
  2240. // The Id was successfully set
  2241. }
  2242. \endcode
  2243. \sa wolfSSL_set_session
  2244. */
  2245. int wolfSSL_SetServerID(WOLFSSL* ssl, const unsigned char* id,
  2246. int len, int newSession);
  2247. /*!
  2248. \ingroup IO
  2249. \brief This function gets the session index of the WOLFSSL structure.
  2250. \return int The function returns an int type representing the
  2251. sessionIndex within the WOLFSSL struct.
  2252. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  2253. _Example_
  2254. \code
  2255. WOLFSSL_CTX_new( protocol method );
  2256. WOLFSSL* ssl = WOLFSSL_new(ctx);
  2257. ...
  2258. int sesIdx = wolfSSL_GetSessionIndex(ssl);
  2259. if(sesIdx < 0 || sesIdx > sizeof(ssl->sessionIndex)/sizeof(int)){
  2260. // You have an out of bounds index number and something is not right.
  2261. }
  2262. \endcode
  2263. \sa wolfSSL_GetSessionAtIndex
  2264. */
  2265. int wolfSSL_GetSessionIndex(WOLFSSL* ssl);
  2266. /*!
  2267. \ingroup IO
  2268. \brief This function gets the session at specified index of the session
  2269. cache and copies it into memory. The WOLFSSL_SESSION structure holds
  2270. the session information.
  2271. \return SSL_SUCCESS returned if the function executed successfully and
  2272. no errors were thrown.
  2273. \return BAD_MUTEX_E returned if there was an unlock or lock mutex error.
  2274. \return SSL_FAILURE returned if the function did not execute successfully.
  2275. \param idx an int type representing the session index.
  2276. \param session a pointer to the WOLFSSL_SESSION structure.
  2277. _Example_
  2278. \code
  2279. int idx; // The index to locate the session.
  2280. WOLFSSL_SESSION* session; // Buffer to copy to.
  2281. ...
  2282. if(wolfSSL_GetSessionAtIndex(idx, session) != SSL_SUCCESS){
  2283. // Failure case.
  2284. }
  2285. \endcode
  2286. \sa UnLockMutex
  2287. \sa LockMutex
  2288. \sa wolfSSL_GetSessionIndex
  2289. */
  2290. int wolfSSL_GetSessionAtIndex(int index, WOLFSSL_SESSION* session);
  2291. /*!
  2292. \ingroup IO
  2293. \brief Returns the peer certificate chain from the WOLFSSL_SESSION struct.
  2294. \return pointer A pointer to a WOLFSSL_X509_CHAIN structure that
  2295. contains the peer certification chain.
  2296. \param session a pointer to a WOLFSSL_SESSION structure.
  2297. _Example_
  2298. \code
  2299. WOLFSSL_SESSION* session;
  2300. WOLFSSL_X509_CHAIN* chain;
  2301. ...
  2302. chain = wolfSSL_SESSION_get_peer_chain(session);
  2303. if(!chain){
  2304. // There was no chain. Failure case.
  2305. }
  2306. \endcode
  2307. \sa wolfSSL_GetSessionAtIndex
  2308. \sa wolfSSL_GetSessionIndex
  2309. \sa AddSession
  2310. */
  2311. WOLFSSL_X509_CHAIN* wolfSSL_SESSION_get_peer_chain(WOLFSSL_SESSION* session);
  2312. /*!
  2313. \ingroup Setup
  2314. \brief This function sets the verification method for remote peers and
  2315. also allows a verify callback to be registered with the SSL context.
  2316. The verify callback will be called only when a verification failure has
  2317. occurred. If no verify callback is desired, the NULL pointer can be used
  2318. for verify_callback. The verification mode of peer certificates is a
  2319. logically OR’d list of flags. The possible flag values include:
  2320. SSL_VERIFY_NONE Client mode: the client will not verify the certificate
  2321. received from the server and the handshake will continue as normal.
  2322. Server mode: the server will not send a certificate request to the client.
  2323. As such, client verification will not be enabled. SSL_VERIFY_PEER Client
  2324. mode: the client will verify the certificate received from the server
  2325. during the handshake. This is turned on by default in wolfSSL, therefore,
  2326. using this option has no effect. Server mode: the server will send a
  2327. certificate request to the client and verify the client certificate
  2328. received. SSL_VERIFY_FAIL_IF_NO_PEER_CERT Client mode: no effect when
  2329. used on the client side. Server mode: the verification will fail on the
  2330. server side if the client fails to send a certificate when requested to
  2331. do so (when using SSL_VERIFY_PEER on the SSL server).
  2332. SSL_VERIFY_FAIL_EXCEPT_PSK Client mode: no effect when used on the client
  2333. side. Server mode: the verification is the same as
  2334. SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK connection.
  2335. If a PSK connection is being made then the connection will go through
  2336. without a peer cert.
  2337. \return none No return.
  2338. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  2339. \param mode flags indicating verification mode for peer's cert.
  2340. \param verify_callback callback to be called when verification fails.
  2341. If no callback is desired, the NULL pointer can be used for
  2342. verify_callback.
  2343. _Example_
  2344. \code
  2345. WOLFSSL_CTX* ctx = 0;
  2346. ...
  2347. wolfSSL_CTX_set_verify(ctx, (WOLFSSL_VERIFY_PEER |
  2348. WOLFSSL_VERIFY_FAIL_IF_NO_PEER_CERT), NULL);
  2349. \endcode
  2350. \sa wolfSSL_set_verify
  2351. */
  2352. void wolfSSL_CTX_set_verify(WOLFSSL_CTX* ctx, int mode,
  2353. VerifyCallback verify_callback);
  2354. /*!
  2355. \ingroup Setup
  2356. \brief This function sets the verification method for remote peers and
  2357. also allows a verify callback to be registered with the SSL session.
  2358. The verify callback will be called only when a verification failure has
  2359. occurred. If no verify callback is desired, the NULL pointer can be used
  2360. for verify_callback. The verification mode of peer certificates is a
  2361. logically OR’d list of flags. The possible flag values include:
  2362. SSL_VERIFY_NONE Client mode: the client will not verify the certificate
  2363. received from the server and the handshake will continue as normal. Server
  2364. mode: the server will not send a certificate request to the client.
  2365. As such, client verification will not be enabled. SSL_VERIFY_PEER Client
  2366. mode: the client will verify the certificate received from the server
  2367. during the handshake. This is turned on by default in wolfSSL, therefore,
  2368. using this option has no effect. Server mode: the server will send a
  2369. certificate request to the client and verify the client certificate
  2370. received. SSL_VERIFY_FAIL_IF_NO_PEER_CERT Client mode: no effect when
  2371. used on the client side. Server mode: the verification will fail on the
  2372. server side if the client fails to send a certificate when requested to do
  2373. so (when using SSL_VERIFY_PEER on the SSL server).
  2374. SSL_VERIFY_FAIL_EXCEPT_PSK Client mode: no effect when used on the client
  2375. side. Server mode: the verification is the same as
  2376. SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK connection.
  2377. If a PSK connection is being made then the connection will go through
  2378. without a peer cert.
  2379. \return none No return.
  2380. \param ssl pointer to the SSL session, created with wolfSSL_new().
  2381. \param mode flags indicating verification mode for peer's cert.
  2382. \param verify_callback callback to be called when verification fails.
  2383. If no callback is desired, the NULL pointer can
  2384. be used for verify_callback.
  2385. _Example_
  2386. \code
  2387. WOLFSSL* ssl = 0;
  2388. ...
  2389. wolfSSL_set_verify(ssl, SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, 0);
  2390. \endcode
  2391. \sa wolfSSL_CTX_set_verify
  2392. */
  2393. void wolfSSL_set_verify(WOLFSSL* ssl, int mode, VerifyCallback verify_callback);
  2394. /*!
  2395. \ingroup CertsKeys
  2396. \brief This function stores user CTX object information for verify callback.
  2397. \return none No return.
  2398. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  2399. \param ctx a void pointer that is set to WOLFSSL structure’s verifyCbCtx
  2400. member’s value.
  2401. _Example_
  2402. \code
  2403. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  2404. WOLFSSL* ssl = wolfSSL_new(ctx);
  2405. (void*)ctx;
  2406. ...
  2407. if(ssl != NULL){
  2408. wolfSSL_SetCertCbCtx(ssl, ctx);
  2409. } else {
  2410. // Error case, the SSL is not initialized properly.
  2411. }
  2412. \endcode
  2413. \sa wolfSSL_CTX_save_cert_cache
  2414. \sa wolfSSL_CTX_restore_cert_cache
  2415. \sa wolfSSL_CTX_set_verify
  2416. */
  2417. void wolfSSL_SetCertCbCtx(WOLFSSL* ssl, void* ctx);
  2418. /*!
  2419. \ingroup CertsKeys
  2420. \brief This function stores user CTX object information for verify callback.
  2421. \return none No return.
  2422. \param ctx a pointer to a WOLFSSL_CTX structure.
  2423. \param userCtx a void pointer that is used to set WOLFSSL_CTX structure’s
  2424. verifyCbCtx member’s value.
  2425. _Example_
  2426. \code
  2427. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  2428. void* userCtx = NULL; // Assign some user defined context
  2429. ...
  2430. if(ctx != NULL){
  2431. wolfSSL_SetCertCbCtx(ctx, userCtx);
  2432. } else {
  2433. // Error case, the SSL is not initialized properly.
  2434. }
  2435. \endcode
  2436. \sa wolfSSL_CTX_save_cert_cache
  2437. \sa wolfSSL_CTX_restore_cert_cache
  2438. \sa wolfSSL_CTX_set_verify
  2439. */
  2440. void wolfSSL_CTX_SetCertCbCtx(WOLFSSL_CTX* ctx, void* userCtx);
  2441. /*!
  2442. \ingroup IO
  2443. \brief This function returns the number of bytes which are buffered and
  2444. available in the SSL object to be read by wolfSSL_read().
  2445. \return int This function returns the number of bytes pending.
  2446. \param ssl pointer to the SSL session, created with wolfSSL_new().
  2447. _Example_
  2448. \code
  2449. int pending = 0;
  2450. WOLFSSL* ssl = 0;
  2451. ...
  2452. pending = wolfSSL_pending(ssl);
  2453. printf(“There are %d bytes buffered and available for reading”, pending);
  2454. \endcode
  2455. \sa wolfSSL_recv
  2456. \sa wolfSSL_read
  2457. \sa wolfSSL_peek
  2458. */
  2459. int wolfSSL_pending(WOLFSSL*);
  2460. /*!
  2461. \ingroup Debug
  2462. \brief This function is for OpenSSL compatibility (SSL_load_error_string)
  2463. only and takes no action.
  2464. \return none No returns.
  2465. \param none No parameters.
  2466. _Example_
  2467. \code
  2468. wolfSSL_load_error_strings();
  2469. \endcode
  2470. \sa wolfSSL_get_error
  2471. \sa wolfSSL_ERR_error_string
  2472. \sa wolfSSL_ERR_error_string_n
  2473. \sa wolfSSL_ERR_print_errors_fp
  2474. \sa wolfSSL_load_error_strings
  2475. */
  2476. void wolfSSL_load_error_strings(void);
  2477. /*!
  2478. \ingroup TLS
  2479. \brief This function is called internally in wolfSSL_CTX_new(). This
  2480. function is a wrapper around wolfSSL_Init() and exists for OpenSSL
  2481. compatibility (SSL_library_init) when wolfSSL has been compiled with
  2482. OpenSSL compatibility layer. wolfSSL_Init() is the more typically-used
  2483. wolfSSL initialization function.
  2484. \return SSL_SUCCESS If successful the call will return.
  2485. \return SSL_FATAL_ERROR is returned upon failure.
  2486. \param none No parameters.
  2487. _Example_
  2488. \code
  2489. int ret = 0;
  2490. ret = wolfSSL_library_init();
  2491. if (ret != SSL_SUCCESS) {
  2492. failed to initialize wolfSSL
  2493. }
  2494. ...
  2495. \endcode
  2496. \sa wolfSSL_Init
  2497. \sa wolfSSL_Cleanup
  2498. */
  2499. int wolfSSL_library_init(void);
  2500. /*!
  2501. \brief This function sets the Device Id at the WOLFSSL session level.
  2502. \return WOLFSSL_SUCCESS upon success.
  2503. \return BAD_FUNC_ARG if ssl is NULL.
  2504. \param ssl pointer to a SSL object, created with wolfSSL_new().
  2505. \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
  2506. _Example_
  2507. \code
  2508. WOLFSSL* ssl;
  2509. int DevId = -2;
  2510. wolfSSL_SetDevId(ssl, devId);
  2511. \endcode
  2512. \sa wolfSSL_CTX_SetDevId
  2513. \sa wolfSSL_CTX_GetDevId
  2514. */
  2515. int wolfSSL_SetDevId(WOLFSSL* ssl, int devId);
  2516. /*!
  2517. \brief This function sets the Device Id at the WOLFSSL_CTX context level.
  2518. \return WOLFSSL_SUCCESS upon success.
  2519. \return BAD_FUNC_ARG if ssl is NULL.
  2520. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  2521. \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
  2522. _Example_
  2523. \code
  2524. WOLFSSL_CTX* ctx;
  2525. int DevId = -2;
  2526. wolfSSL_CTX_SetDevId(ctx, devId);
  2527. \endcode
  2528. \sa wolfSSL_SetDevId
  2529. \sa wolfSSL_CTX_GetDevId
  2530. */
  2531. int wolfSSL_CTX_SetDevId(WOLFSSL_CTX* ctx, int devId);
  2532. /*!
  2533. \brief This function retrieves the Device Id.
  2534. \return devId upon success.
  2535. \return INVALID_DEVID if both ssl and ctx are NULL.
  2536. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  2537. \param ssl pointer to a SSL object, created with wolfSSL_new().
  2538. _Example_
  2539. \code
  2540. WOLFSSL_CTX* ctx;
  2541. wolfSSL_CTX_GetDevId(ctx, ssl);
  2542. \endcode
  2543. \sa wolfSSL_SetDevId
  2544. \sa wolfSSL_CTX_SetDevId
  2545. */
  2546. int wolfSSL_CTX_GetDevId(WOLFSSL_CTX* ctx, WOLFSSL* ssl);
  2547. /*!
  2548. \ingroup Setup
  2549. \brief This function enables or disables SSL session caching.
  2550. Behavior depends on the value used for mode. The following values
  2551. for mode are available: SSL_SESS_CACHE_OFF- disable session caching.
  2552. Session caching is turned on by default. SSL_SESS_CACHE_NO_AUTO_CLEAR -
  2553. Disable auto-flushing of the session cache. Auto-flushing is turned on
  2554. by default.
  2555. \return SSL_SUCCESS will be returned upon success.
  2556. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  2557. \param mode modifier used to change behavior of the session cache.
  2558. _Example_
  2559. \code
  2560. WOLFSSL_CTX* ctx = 0;
  2561. ...
  2562. ret = wolfSSL_CTX_set_session_cache_mode(ctx, SSL_SESS_CACHE_OFF);
  2563. if (ret != SSL_SUCCESS) {
  2564. // failed to turn SSL session caching off
  2565. }
  2566. \endcode
  2567. \sa wolfSSL_flush_sessions
  2568. \sa wolfSSL_get1_session
  2569. \sa wolfSSL_set_session
  2570. \sa wolfSSL_get_sessionID
  2571. \sa wolfSSL_CTX_set_timeout
  2572. */
  2573. long wolfSSL_CTX_set_session_cache_mode(WOLFSSL_CTX* ctx, long mode);
  2574. /*!
  2575. \brief This function sets the session secret callback function. The
  2576. SessionSecretCb type has the signature: int (*SessionSecretCb)(WOLFSSL* ssl,
  2577. void* secret, int* secretSz, void* ctx). The sessionSecretCb member of
  2578. the WOLFSSL struct is set to the parameter cb.
  2579. \return SSL_SUCCESS returned if the execution of the function did not
  2580. return an error.
  2581. \return SSL_FATAL_ERROR returned if the WOLFSSL structure is NULL.
  2582. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  2583. \param cb a SessionSecretCb type that is a function pointer with the above
  2584. signature.
  2585. \param ctx a pointer to the user context to be stored
  2586. _Example_
  2587. \code
  2588. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  2589. WOLFSSL* ssl = wolfSSL_new(ctx);
  2590. // Signature of SessionSecretCb
  2591. int SessionSecretCB (WOLFSSL* ssl, void* secret, int* secretSz,
  2592. void* ctx) = SessionSecretCb;
  2593. int wolfSSL_set_session_secret_cb(ssl, SessionSecretCB, (void*)ssl->ctx){
  2594. // Function body.
  2595. }
  2596. \endcode
  2597. \sa SessionSecretCb
  2598. */
  2599. int wolfSSL_set_session_secret_cb(WOLFSSL* ssl, SessionSecretCb cb, void* ctx);
  2600. /*!
  2601. \ingroup IO
  2602. \brief This function persists the session cache to file. It doesn’t use
  2603. memsave because of additional memory use.
  2604. \return SSL_SUCCESS returned if the function executed without error.
  2605. The session cache has been written to a file.
  2606. \return SSL_BAD_FILE returned if fname cannot be opened or is otherwise
  2607. corrupt.
  2608. \return FWRITE_ERROR returned if XFWRITE failed to write to the file.
  2609. \return BAD_MUTEX_E returned if there was a mutex lock failure.
  2610. \param fname is a constant char pointer that points to a file for writing.
  2611. _Example_
  2612. \code
  2613. const char* fname;
  2614. ...
  2615. if(wolfSSL_save_session_cache(fname) != SSL_SUCCESS){
  2616. // Fail to write to file.
  2617. }
  2618. \endcode
  2619. \sa XFWRITE
  2620. \sa wolfSSL_restore_session_cache
  2621. \sa wolfSSL_memrestore_session_cache
  2622. */
  2623. int wolfSSL_save_session_cache(const char* fname);
  2624. /*!
  2625. \ingroup IO
  2626. \brief This function restores the persistent session cache from file. It
  2627. does not use memstore because of additional memory use.
  2628. \return SSL_SUCCESS returned if the function executed without error.
  2629. \return SSL_BAD_FILE returned if the file passed into the function was
  2630. corrupted and could not be opened by XFOPEN.
  2631. \return FREAD_ERROR returned if the file had a read error from XFREAD.
  2632. \return CACHE_MATCH_ERROR returned if the session cache header match
  2633. failed.
  2634. \return BAD_MUTEX_E returned if there was a mutex lock failure.
  2635. \param fname a constant char pointer file input that will be read.
  2636. _Example_
  2637. \code
  2638. const char *fname;
  2639. ...
  2640. if(wolfSSL_restore_session_cache(fname) != SSL_SUCCESS){
  2641. // Failure case. The function did not return SSL_SUCCESS.
  2642. }
  2643. \endcode
  2644. \sa XFREAD
  2645. \sa XFOPEN
  2646. */
  2647. int wolfSSL_restore_session_cache(const char* fname);
  2648. /*!
  2649. \ingroup IO
  2650. \brief This function persists session cache to memory.
  2651. \return SSL_SUCCESS returned if the function executed without error.
  2652. The session cache has been successfully persisted to memory.
  2653. \return BAD_MUTEX_E returned if there was a mutex lock error.
  2654. \return BUFFER_E returned if the buffer size was too small.
  2655. \param mem a void pointer representing the destination for the memory
  2656. copy, XMEMCPY().
  2657. \param sz an int type representing the size of mem.
  2658. _Example_
  2659. \code
  2660. void* mem;
  2661. int sz; // Max size of the memory buffer.
  2662. if(wolfSSL_memsave_session_cache(mem, sz) != SSL_SUCCESS){
  2663. // Failure case, you did not persist the session cache to memory
  2664. }
  2665. \endcode
  2666. \sa XMEMCPY
  2667. \sa wolfSSL_get_session_cache_memsize
  2668. */
  2669. int wolfSSL_memsave_session_cache(void* mem, int sz);
  2670. /*!
  2671. \ingroup IO
  2672. \brief This function restores the persistent session cache from memory.
  2673. \return SSL_SUCCESS returned if the function executed without an error.
  2674. \return BUFFER_E returned if the memory buffer is too small.
  2675. \return BAD_MUTEX_E returned if the session cache mutex lock failed.
  2676. \return CACHE_MATCH_ERROR returned if the session cache header match
  2677. failed.
  2678. \param mem a constant void pointer containing the source of the
  2679. restoration.
  2680. \param sz an integer representing the size of the memory buffer.
  2681. _Example_
  2682. \code
  2683. const void* memoryFile;
  2684. int szMf;
  2685. ...
  2686. if(wolfSSL_memrestore_session_cache(memoryFile, szMf) != SSL_SUCCESS){
  2687. // Failure case. SSL_SUCCESS was not returned.
  2688. }
  2689. \endcode
  2690. \sa wolfSSL_save_session_cache
  2691. */
  2692. int wolfSSL_memrestore_session_cache(const void* mem, int sz);
  2693. /*!
  2694. \ingroup IO
  2695. \brief This function returns how large the session cache save buffer
  2696. should be.
  2697. \return int This function returns an integer that represents the size of
  2698. the session cache save buffer.
  2699. \param none No parameters.
  2700. _Example_
  2701. \code
  2702. int sz = // Minimum size for error checking;
  2703. ...
  2704. if(sz < wolfSSL_get_session_cache_memsize()){
  2705. // Memory buffer is too small
  2706. }
  2707. \endcode
  2708. \sa wolfSSL_memrestore_session_cache
  2709. */
  2710. int wolfSSL_get_session_cache_memsize(void);
  2711. /*!
  2712. \ingroup CertsKeys
  2713. \brief This function writes the cert cache from memory to file.
  2714. \return SSL_SUCCESS if CM_SaveCertCache exits normally.
  2715. \return BAD_FUNC_ARG is returned if either of the arguments are NULL.
  2716. \return SSL_BAD_FILE if the cert cache save file could not be opened.
  2717. \return BAD_MUTEX_E if the lock mutex failed.
  2718. \return MEMORY_E the allocation of memory failed.
  2719. \return FWRITE_ERROR Certificate cache file write failed.
  2720. \param ctx a pointer to a WOLFSSL_CTX structure, holding the
  2721. certificate information.
  2722. \param fname a constant char pointer that points to a file for writing.
  2723. _Example_
  2724. \code
  2725. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol def );
  2726. const char* fname;
  2727. ...
  2728. if(wolfSSL_CTX_save_cert_cache(ctx, fname)){
  2729. // file was written.
  2730. }
  2731. \endcode
  2732. \sa CM_SaveCertCache
  2733. \sa DoMemSaveCertCache
  2734. */
  2735. int wolfSSL_CTX_save_cert_cache(WOLFSSL_CTX* ctx, const char* fname);
  2736. /*!
  2737. \ingroup CertsKeys
  2738. \brief This function persistes certificate cache from a file.
  2739. \return SSL_SUCCESS returned if the function, CM_RestoreCertCache,
  2740. executes normally.
  2741. \return SSL_BAD_FILE returned if XFOPEN returns XBADFILE. The file is
  2742. corrupted.
  2743. \return MEMORY_E returned if the allocated memory for the temp buffer
  2744. fails.
  2745. \return BAD_FUNC_ARG returned if fname or ctx have a NULL value.
  2746. \param ctx a pointer to a WOLFSSL_CTX structure, holding the certificate
  2747. information.
  2748. \param fname a constant char pointer that points to a file for reading.
  2749. _Example_
  2750. \code
  2751. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  2752. WOLFSSL* ssl = wolfSSL_new(ctx);
  2753. const char* fname = "path to file";
  2754. ...
  2755. if(wolfSSL_CTX_restore_cert_cache(ctx, fname)){
  2756. // check to see if the execution was successful
  2757. }
  2758. \endcode
  2759. \sa CM_RestoreCertCache
  2760. \sa XFOPEN
  2761. */
  2762. int wolfSSL_CTX_restore_cert_cache(WOLFSSL_CTX* ctx, const char* fname);
  2763. /*!
  2764. \ingroup CertsKeys
  2765. \brief This function persists the certificate cache to memory.
  2766. \return SSL_SUCCESS returned on successful execution of the function.
  2767. No errors were thrown.
  2768. \return BAD_MUTEX_E mutex error where the WOLFSSL_CERT_MANAGER member
  2769. caLock was not 0 (zero).
  2770. \return BAD_FUNC_ARG returned if ctx, mem, or used is NULL or if sz
  2771. is less than or equal to 0 (zero).
  2772. \return BUFFER_E output buffer mem was too small.
  2773. \param ctx a pointer to a WOLFSSL_CTX structure, created
  2774. using wolfSSL_CTX_new().
  2775. \param mem a void pointer to the destination (output buffer).
  2776. \param sz the size of the output buffer.
  2777. \param used a pointer to size of the cert cache header.
  2778. _Example_
  2779. \code
  2780. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol );
  2781. void* mem;
  2782. int sz;
  2783. int* used;
  2784. ...
  2785. if(wolfSSL_CTX_memsave_cert_cache(ctx, mem, sz, used) != SSL_SUCCESS){
  2786. // The function returned with an error
  2787. }
  2788. \endcode
  2789. \sa DoMemSaveCertCache
  2790. \sa GetCertCacheMemSize
  2791. \sa CM_MemRestoreCertCache
  2792. \sa CM_GetCertCacheMemSize
  2793. */
  2794. int wolfSSL_CTX_memsave_cert_cache(WOLFSSL_CTX* ctx, void* mem, int sz, int* used);
  2795. /*!
  2796. \ingroup Setup
  2797. \brief This function restores the certificate cache from memory.
  2798. \return SSL_SUCCESS returned if the function and subroutines
  2799. executed without an error.
  2800. \return BAD_FUNC_ARG returned if the ctx or mem parameters are
  2801. NULL or if the sz parameter is less than or equal to zero.
  2802. \return BUFFER_E returned if the cert cache memory buffer is too small.
  2803. \return CACHE_MATCH_ERROR returned if there was a cert cache
  2804. header mismatch.
  2805. \return BAD_MUTEX_E returned if the lock mutex on failed.
  2806. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  2807. wolfSSL_CTX_new().
  2808. \param mem a void pointer with a value that will be restored to
  2809. the certificate cache.
  2810. \param sz an int type that represents the size of the mem parameter.
  2811. _Example_
  2812. \code
  2813. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
  2814. WOLFSSL* ssl = WOLFSSL_new(ctx);
  2815. void* mem;
  2816. int sz = (*int) sizeof(mem);
  2817. if(wolfSSL_CTX_memrestore_cert_cache(ssl->ctx, mem, sz)){
  2818. // The success case
  2819. }
  2820. \endcode
  2821. \sa CM_MemRestoreCertCache
  2822. */
  2823. int wolfSSL_CTX_memrestore_cert_cache(WOLFSSL_CTX* ctx, const void* mem, int sz);
  2824. /*!
  2825. \ingroup CertsKeys
  2826. \brief Returns the size the certificate cache save buffer needs to be.
  2827. \return int integer value returned representing the memory size
  2828. upon success.
  2829. \return BAD_FUNC_ARG is returned if the WOLFSSL_CTX struct is NULL.
  2830. \return BAD_MUTEX_E - returned if there was a mutex lock error.
  2831. \param ctx a pointer to a wolfSSL_CTX structure, created using
  2832. wolfSSL_CTX_new().
  2833. _Example_
  2834. \code
  2835. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(protocol);
  2836. ...
  2837. int certCacheSize = wolfSSL_CTX_get_cert_cache_memsize(ctx);
  2838. if(certCacheSize != BAD_FUNC_ARG || certCacheSize != BAD_MUTEX_E){
  2839. // Successfully retrieved the memory size.
  2840. }
  2841. \endcode
  2842. \sa CM_GetCertCacheMemSize
  2843. */
  2844. int wolfSSL_CTX_get_cert_cache_memsize(WOLFSSL_CTX* ctx);
  2845. /*!
  2846. \ingroup Setup
  2847. \brief This function sets cipher suite list for a given WOLFSSL_CTX.
  2848. This cipher suite list becomes the default list for any new SSL sessions
  2849. (WOLFSSL) created using this context. The ciphers in the list should be
  2850. sorted in order of preference from highest to lowest. Each call to
  2851. wolfSSL_CTX_set_cipher_list() resets the cipher suite list for the
  2852. specific SSL context to the provided list each time the function is
  2853. called. The cipher suite list, list, is a null-terminated text string,
  2854. and a colon-delimited list. For example, one value for list may be
  2855. "DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256" Valid cipher
  2856. values are the full name values from the cipher_names[] array in
  2857. src/internal.c (for a definite list of valid cipher values check
  2858. src/internal.c)
  2859. \return SSL_SUCCESS will be returned upon successful function completion.
  2860. \return SSL_FAILURE will be returned on failure.
  2861. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  2862. \param list null-terminated text string and a colon-delimited list of
  2863. cipher suites to use with the specified SSL context.
  2864. _Example_
  2865. \code
  2866. WOLFSSL_CTX* ctx = 0;
  2867. ...
  2868. ret = wolfSSL_CTX_set_cipher_list(ctx,
  2869. “DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256”);
  2870. if (ret != SSL_SUCCESS) {
  2871. // failed to set cipher suite list
  2872. }
  2873. \endcode
  2874. \sa wolfSSL_set_cipher_list
  2875. \sa wolfSSL_CTX_new
  2876. */
  2877. int wolfSSL_CTX_set_cipher_list(WOLFSSL_CTX* ctx, const char* list);
  2878. /*!
  2879. \ingroup Setup
  2880. \brief This function sets cipher suite list for a given WOLFSSL object
  2881. (SSL session). The ciphers in the list should be sorted in order of
  2882. preference from highest to lowest. Each call to wolfSSL_set_cipher_list()
  2883. resets the cipher suite list for the specific SSL session to the provided
  2884. list each time the function is called. The cipher suite list, list, is a
  2885. null-terminated text string, and a colon-delimited list. For example, one
  2886. value for list may be
  2887. "DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256".
  2888. Valid cipher values are the full name values from the cipher_names[]
  2889. array in src/internal.c (for a definite list of valid cipher values
  2890. check src/internal.c)
  2891. \return SSL_SUCCESS will be returned upon successful function completion.
  2892. \return SSL_FAILURE will be returned on failure.
  2893. \param ssl pointer to the SSL session, created with wolfSSL_new().
  2894. \param list null-terminated text string and a colon-delimited list of
  2895. cipher suites to use with the specified SSL session.
  2896. _Example_
  2897. \code
  2898. int ret = 0;
  2899. WOLFSSL* ssl = 0;
  2900. ...
  2901. ret = wolfSSL_set_cipher_list(ssl,
  2902. “DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256”);
  2903. if (ret != SSL_SUCCESS) {
  2904. // failed to set cipher suite list
  2905. }
  2906. \endcode
  2907. \sa wolfSSL_CTX_set_cipher_list
  2908. \sa wolfSSL_new
  2909. */
  2910. int wolfSSL_set_cipher_list(WOLFSSL* ssl, const char* list);
  2911. /*!
  2912. \brief This function informs the WOLFSSL DTLS object that the underlying
  2913. UDP I/O is non-blocking. After an application creates a WOLFSSL object,
  2914. if it will be used with a non-blocking UDP socket, call
  2915. wolfSSL_dtls_set_using_nonblock() on it. This lets the WOLFSSL object know
  2916. that receiving EWOULDBLOCK means that the recvfrom call would
  2917. block rather than that it timed out.
  2918. \return none No return.
  2919. \param ssl pointer to the DTLS session, created with wolfSSL_new().
  2920. \param nonblock value used to set non-blocking flag on WOLFSSL object.
  2921. Use 1 to specify non-blocking, otherwise 0.
  2922. _Example_
  2923. \code
  2924. WOLFSSL* ssl = 0;
  2925. ...
  2926. wolfSSL_dtls_set_using_nonblock(ssl, 1);
  2927. \endcode
  2928. \sa wolfSSL_dtls_get_using_nonblock
  2929. \sa wolfSSL_dtls_got_timeout
  2930. \sa wolfSSL_dtls_get_current_timeout
  2931. */
  2932. void wolfSSL_dtls_set_using_nonblock(WOLFSSL* ssl, int nonblock);
  2933. /*!
  2934. \brief This function allows the application to determine if wolfSSL is
  2935. using non-blocking I/O with UDP. If wolfSSL is using non-blocking I/O, this
  2936. function will return 1, otherwise 0. After an application creates a
  2937. WOLFSSL object, if it will be used with a non-blocking UDP socket, call
  2938. wolfSSL_dtls_set_using_nonblock() on it. This lets the WOLFSSL object know
  2939. that receiving EWOULDBLOCK means that the recvfrom call would block
  2940. rather than that it timed out. This function is only meaningful to DTLS
  2941. sessions.
  2942. \return 0 underlying I/O is blocking.
  2943. \return 1 underlying I/O is non-blocking.
  2944. \param ssl pointer to the DTLS session, created with wolfSSL_new().
  2945. _Example_
  2946. \code
  2947. int ret = 0;
  2948. WOLFSSL* ssl = 0;
  2949. ...
  2950. ret = wolfSSL_dtls_get_using_nonblock(ssl);
  2951. if (ret == 1) {
  2952. // underlying I/O is non-blocking
  2953. }
  2954. ...
  2955. \endcode
  2956. \sa wolfSSL_dtls_set_using_nonblock
  2957. \sa wolfSSL_dtls_got_timeout
  2958. \sa wolfSSL_dtls_set_using_nonblock
  2959. */
  2960. int wolfSSL_dtls_get_using_nonblock(WOLFSSL* ssl);
  2961. /*!
  2962. \brief This function returns the current timeout value in seconds for
  2963. the WOLFSSL object. When using non-blocking sockets, something in the user
  2964. code needs to decide when to check for available recv data and how long
  2965. it has been waiting. The value returned by this function indicates how
  2966. long the application should wait.
  2967. \return seconds The current DTLS timeout value in seconds
  2968. \return NOT_COMPILED_IN if wolfSSL was not built with DTLS support.
  2969. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  2970. _Example_
  2971. \code
  2972. int timeout = 0;
  2973. WOLFSSL* ssl;
  2974. ...
  2975. timeout = wolfSSL_get_dtls_current_timeout(ssl);
  2976. printf(“DTLS timeout (sec) = %d\n”, timeout);
  2977. \endcode
  2978. \sa wolfSSL_dtls
  2979. \sa wolfSSL_dtls_get_peer
  2980. \sa wolfSSL_dtls_got_timeout
  2981. \sa wolfSSL_dtls_set_peer
  2982. */
  2983. int wolfSSL_dtls_get_current_timeout(WOLFSSL* ssl);
  2984. /*!
  2985. \brief This function returns true if the application should setup a quicker
  2986. timeout. When using non-blocking sockets, something in the user code needs
  2987. to decide when to check for available data and how long it needs to wait. If
  2988. this function returns true, it means that the library already detected some
  2989. disruption in the communication, but it wants to wait for a little longer in
  2990. case some messages from the other peers are still in flight. Is up to the
  2991. application to fine tune the value of this timer, a good one may be
  2992. dtls_get_current_timeout() / 4.
  2993. \return true if the application code should setup a quicker timeout
  2994. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  2995. \sa wolfSSL_dtls
  2996. \sa wolfSSL_dtls_get_peer
  2997. \sa wolfSSL_dtls_got_timeout
  2998. \sa wolfSSL_dtls_set_peer
  2999. \sa wolfSSL_dtls13_set_send_more_acks
  3000. */
  3001. int wolfSSL_dtls13_use_quick_timeout(WOLFSSL *ssl);
  3002. /*!
  3003. \ingroup Setup
  3004. \brief This function sets whether the library should send ACKs to the other
  3005. peer immediately when detecting disruption or not. Sending ACKs immediately
  3006. assures minimum latency but it may consume more bandwidth than necessary. If
  3007. the application manages the timer by itself and this option is set to 0 then
  3008. application code can use wolfSSL_dtls13_use_quick_timeout() to determine if
  3009. it should setup a quicker timeout to send those delayed ACKs.
  3010. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  3011. \param value 1 to set the option, 0 to disable the option
  3012. \sa wolfSSL_dtls
  3013. \sa wolfSSL_dtls_get_peer
  3014. \sa wolfSSL_dtls_got_timeout
  3015. \sa wolfSSL_dtls_set_peer
  3016. \sa wolfSSL_dtls13_use_quick_timeout
  3017. */
  3018. void wolfSSL_dtls13_set_send_more_acks(WOLFSSL *ssl, int value);
  3019. /*!
  3020. \ingroup Setup
  3021. \brief This function sets the dtls timeout.
  3022. \return SSL_SUCCESS returned if the function executes without an error.
  3023. The dtls_timeout_init and the dtls_timeout members of SSL have been set.
  3024. \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if
  3025. the timeout is not greater than 0. It will also return if the timeout
  3026. argument exceeds the maximum value allowed.
  3027. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  3028. \param timeout an int type that will be set to the dtls_timeout_init
  3029. member of the WOLFSSL structure.
  3030. _Example_
  3031. \code
  3032. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  3033. WOLFSSL* ssl = wolfSSL_new(ctx);
  3034. int timeout = TIMEOUT;
  3035. ...
  3036. if(wolfSSL_dtls_set_timeout_init(ssl, timeout)){
  3037. // the dtls timeout was set
  3038. } else {
  3039. // Failed to set DTLS timeout.
  3040. }
  3041. \endcode
  3042. \sa wolfSSL_dtls_set_timeout_max
  3043. \sa wolfSSL_dtls_got_timeout
  3044. */
  3045. int wolfSSL_dtls_set_timeout_init(WOLFSSL* ssl, int);
  3046. /*!
  3047. \brief This function sets the maximum dtls timeout.
  3048. \return SSL_SUCCESS returned if the function executed without an error.
  3049. \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if
  3050. the timeout argument is not greater than zero or is less than the
  3051. dtls_timeout_init member of the WOLFSSL structure.
  3052. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  3053. \param timeout an int type representing the dtls maximum timeout.
  3054. _Example_
  3055. \code
  3056. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  3057. WOLFSSL* ssl = wolfSSL_new(ctx);
  3058. int timeout = TIMEOUTVAL;
  3059. ...
  3060. int ret = wolfSSL_dtls_set_timeout_max(ssl);
  3061. if(!ret){
  3062. // Failed to set the max timeout
  3063. }
  3064. \endcode
  3065. \sa wolfSSL_dtls_set_timeout_init
  3066. \sa wolfSSL_dtls_got_timeout
  3067. */
  3068. int wolfSSL_dtls_set_timeout_max(WOLFSSL* ssl, int);
  3069. /*!
  3070. \brief When using non-blocking sockets with DTLS, this function should
  3071. be called on the WOLFSSL object when the controlling code thinks the
  3072. transmission has timed out. It performs the actions needed to retry
  3073. the last transmit, including adjusting the timeout value. If it
  3074. has been too long, this will return a failure.
  3075. \return SSL_SUCCESS will be returned upon success
  3076. \return SSL_FATAL_ERROR will be returned if there have been too many
  3077. retransmissions/timeouts without getting a response from the peer.
  3078. \return NOT_COMPILED_IN will be returned if wolfSSL was not compiled with
  3079. DTLS support.
  3080. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  3081. _Example_
  3082. \code
  3083. See the following files for usage examples:
  3084. <wolfssl_root>/examples/client/client.c
  3085. <wolfssl_root>/examples/server/server.c
  3086. \endcode
  3087. \sa wolfSSL_dtls_get_current_timeout
  3088. \sa wolfSSL_dtls_get_peer
  3089. \sa wolfSSL_dtls_set_peer
  3090. \sa wolfSSL_dtls
  3091. */
  3092. int wolfSSL_dtls_got_timeout(WOLFSSL* ssl);
  3093. /*!
  3094. \brief When using non-blocking sockets with DTLS, this function retransmits
  3095. the last handshake flight ignoring the expected timeout value and
  3096. retransmit count. It is useful for applications that are using DTLS and
  3097. need to manage even the timeout and retry count.
  3098. \return SSL_SUCCESS will be returned upon success
  3099. \return SSL_FATAL_ERROR will be returned if there have been too many
  3100. retransmissions/timeouts without getting a response from the peer.
  3101. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  3102. _Example_
  3103. \code
  3104. int ret = 0;
  3105. WOLFSSL* ssl;
  3106. ...
  3107. ret = wolfSSL_dtls_retransmit(ssl);
  3108. \endcode
  3109. \sa wolfSSL_dtls_get_current_timeout
  3110. \sa wolfSSL_dtls_got_timeout
  3111. \sa wolfSSL_dtls
  3112. */
  3113. int wolfSSL_dtls_retransmit(WOLFSSL* ssl);
  3114. /*!
  3115. \brief This function is used to determine if the SSL session has been
  3116. configured to use DTLS.
  3117. \return 1 If the SSL session (ssl) has been configured to use DTLS, this
  3118. function will return 1.
  3119. \return 0 otherwise.
  3120. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  3121. _Example_
  3122. \code
  3123. int ret = 0;
  3124. WOLFSSL* ssl;
  3125. ...
  3126. ret = wolfSSL_dtls(ssl);
  3127. if (ret) {
  3128. // SSL session has been configured to use DTLS
  3129. }
  3130. \endcode
  3131. \sa wolfSSL_dtls_get_current_timeout
  3132. \sa wolfSSL_dtls_get_peer
  3133. \sa wolfSSL_dtls_got_timeout
  3134. \sa wolfSSL_dtls_set_peer
  3135. */
  3136. int wolfSSL_dtls(WOLFSSL* ssl);
  3137. /*!
  3138. \brief This function sets the DTLS peer, peer (sockaddr_in) with size of
  3139. peerSz.
  3140. \return SSL_SUCCESS will be returned upon success.
  3141. \return SSL_FAILURE will be returned upon failure.
  3142. \return SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled
  3143. with DTLS support.
  3144. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  3145. \param peer pointer to peer’s sockaddr_in structure. If NULL then the peer
  3146. information in ssl is cleared.
  3147. \param peerSz size of the sockaddr_in structure pointed to by peer. If 0
  3148. then the peer information in ssl is cleared.
  3149. _Example_
  3150. \code
  3151. int ret = 0;
  3152. WOLFSSL* ssl;
  3153. sockaddr_in addr;
  3154. ...
  3155. ret = wolfSSL_dtls_set_peer(ssl, &addr, sizeof(addr));
  3156. if (ret != SSL_SUCCESS) {
  3157. // failed to set DTLS peer
  3158. }
  3159. \endcode
  3160. \sa wolfSSL_dtls_get_current_timeout
  3161. \sa wolfSSL_dtls_get_peer
  3162. \sa wolfSSL_dtls_got_timeout
  3163. \sa wolfSSL_dtls
  3164. */
  3165. int wolfSSL_dtls_set_peer(WOLFSSL* ssl, void* peer, unsigned int peerSz);
  3166. /*!
  3167. \brief This function gets the sockaddr_in (of size peerSz) of the current
  3168. DTLS peer. The function will compare peerSz to the actual DTLS peer size
  3169. stored in the SSL session. If the peer will fit into peer, the peer’s
  3170. sockaddr_in will be copied into peer, with peerSz set to the size of peer.
  3171. \return SSL_SUCCESS will be returned upon success.
  3172. \return SSL_FAILURE will be returned upon failure.
  3173. \return SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled
  3174. with DTLS support.
  3175. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  3176. \param peer pointer to memory location to store peer’s sockaddr_in
  3177. structure.
  3178. \param peerSz input/output size. As input, the size of the allocated memory
  3179. pointed to by peer. As output, the size of the actual sockaddr_in structure
  3180. pointed to by peer.
  3181. _Example_
  3182. \code
  3183. int ret = 0;
  3184. WOLFSSL* ssl;
  3185. sockaddr_in addr;
  3186. ...
  3187. ret = wolfSSL_dtls_get_peer(ssl, &addr, sizeof(addr));
  3188. if (ret != SSL_SUCCESS) {
  3189. // failed to get DTLS peer
  3190. }
  3191. \endcode
  3192. \sa wolfSSL_dtls_get_current_timeout
  3193. \sa wolfSSL_dtls_got_timeout
  3194. \sa wolfSSL_dtls_set_peer
  3195. \sa wolfSSL_dtls
  3196. */
  3197. int wolfSSL_dtls_get_peer(WOLFSSL* ssl, void* peer, unsigned int* peerSz);
  3198. /*!
  3199. \ingroup Debug
  3200. \brief This function converts an error code returned by
  3201. wolfSSL_get_error() into a more human-readable error string.
  3202. errNumber is the error code returned by wolfSSL_get_error() and data
  3203. is the storage buffer which the error string will be placed in.
  3204. The maximum length of data is 80 characters by default, as defined by
  3205. MAX_ERROR_SZ is wolfssl/wolfcrypt/error.h.
  3206. \return success On successful completion, this function returns the same
  3207. string as is returned in data.
  3208. \return failure Upon failure, this function returns a string with the
  3209. appropriate failure reason, msg.
  3210. \param errNumber error code returned by wolfSSL_get_error().
  3211. \param data output buffer containing human-readable error string matching
  3212. errNumber.
  3213. _Example_
  3214. \code
  3215. int err = 0;
  3216. WOLFSSL* ssl;
  3217. char buffer[80];
  3218. ...
  3219. err = wolfSSL_get_error(ssl, 0);
  3220. wolfSSL_ERR_error_string(err, buffer);
  3221. printf(“err = %d, %s\n”, err, buffer);
  3222. \endcode
  3223. \sa wolfSSL_get_error
  3224. \sa wolfSSL_ERR_error_string_n
  3225. \sa wolfSSL_ERR_print_errors_fp
  3226. \sa wolfSSL_load_error_strings
  3227. */
  3228. char* wolfSSL_ERR_error_string(unsigned long errNumber, char* data);
  3229. /*!
  3230. \ingroup Debug
  3231. \brief This function is a version of wolfSSL_ERR_error_string() where
  3232. len specifies the maximum number of characters that may be written to buf.
  3233. Like wolfSSL_ERR_error_string(), this function converts an error code
  3234. returned from wolfSSL_get_error() into a more human-readable error string.
  3235. The human-readable string is placed in buf.
  3236. \return none No returns.
  3237. \param e error code returned by wolfSSL_get_error().
  3238. \param buff output buffer containing human-readable error string matching e.
  3239. \param len maximum length in characters which may be written to buf.
  3240. _Example_
  3241. \code
  3242. int err = 0;
  3243. WOLFSSL* ssl;
  3244. char buffer[80];
  3245. ...
  3246. err = wolfSSL_get_error(ssl, 0);
  3247. wolfSSL_ERR_error_string_n(err, buffer, 80);
  3248. printf(“err = %d, %s\n”, err, buffer);
  3249. \endcode
  3250. \sa wolfSSL_get_error
  3251. \sa wolfSSL_ERR_error_string
  3252. \sa wolfSSL_ERR_print_errors_fp
  3253. \sa wolfSSL_load_error_strings
  3254. */
  3255. void wolfSSL_ERR_error_string_n(unsigned long e, char* buf,
  3256. unsigned long sz);
  3257. /*!
  3258. \ingroup TLS
  3259. \brief This function checks the shutdown conditions in closeNotify or
  3260. connReset or sentNotify members of the Options structure. The Options
  3261. structure is within the WOLFSSL structure.
  3262. \return 1 SSL_SENT_SHUTDOWN is returned.
  3263. \return 2 SSL_RECEIVED_SHUTDOWN is returned.
  3264. \param ssl a constant pointer to a WOLFSSL structure, created using
  3265. wolfSSL_new().
  3266. _Example_
  3267. \code
  3268. #include <wolfssl/ssl.h>
  3269. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
  3270. WOLFSSL* ssl = WOLFSSL_new(ctx);
  3271. int ret;
  3272. ret = wolfSSL_get_shutdown(ssl);
  3273. if(ret == 1){
  3274. SSL_SENT_SHUTDOWN
  3275. } else if(ret == 2){
  3276. SSL_RECEIVED_SHUTDOWN
  3277. } else {
  3278. Fatal error.
  3279. }
  3280. \endcode
  3281. \sa wolfSSL_SESSION_free
  3282. */
  3283. int wolfSSL_get_shutdown(const WOLFSSL* ssl);
  3284. /*!
  3285. \ingroup IO
  3286. \brief This function returns the resuming member of the options struct. The
  3287. flag indicates whether or not to reuse a session. If not, a new session must
  3288. be established.
  3289. \return This function returns an int type held in the Options structure
  3290. representing the flag for session reuse.
  3291. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  3292. _Example_
  3293. \code
  3294. WOLFSSL* ssl = wolfSSL_new(ctx);
  3295. if(!wolfSSL_session_reused(sslResume)){
  3296. // No session reuse allowed.
  3297. }
  3298. \endcode
  3299. \sa wolfSSL_SESSION_free
  3300. \sa wolfSSL_GetSessionIndex
  3301. \sa wolfSSL_memsave_session_cache
  3302. */
  3303. int wolfSSL_session_reused(WOLFSSL* ssl);
  3304. /*!
  3305. \ingroup TLS
  3306. \brief This function checks to see if the connection is established.
  3307. \return 0 returned if the connection is not established, i.e. the WOLFSSL
  3308. struct is NULL or the handshake is not done.
  3309. \return 1 returned if the connection is established i.e. the WOLFSSL
  3310. handshake is done.
  3311. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  3312. _EXAMPLE_
  3313. \code
  3314. #include <wolfssl/ssl.h>
  3315. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  3316. WOLFSSL* ssl = wolfSSL_new(ctx);
  3317. ...
  3318. if(wolfSSL_is_init_finished(ssl)){
  3319. Handshake is done and connection is established
  3320. }
  3321. \endcode
  3322. \sa wolfSSL_set_accept_state
  3323. \sa wolfSSL_get_keys
  3324. \sa wolfSSL_set_shutdown
  3325. */
  3326. int wolfSSL_is_init_finished(WOLFSSL* ssl);
  3327. /*!
  3328. \ingroup IO
  3329. \brief Returns the SSL version being used as a string.
  3330. \return "SSLv3" Using SSLv3
  3331. \return "TLSv1" Using TLSv1
  3332. \return "TLSv1.1" Using TLSv1.1
  3333. \return "TLSv1.2" Using TLSv1.2
  3334. \return "TLSv1.3" Using TLSv1.3
  3335. \return "DTLS": Using DTLS
  3336. \return "DTLSv1.2" Using DTLSv1.2
  3337. \return "unknown" There was a problem determining which version of TLS
  3338. being used.
  3339. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  3340. _Example_
  3341. \code
  3342. wolfSSL_Init();
  3343. WOLFSSL_CTX* ctx;
  3344. WOLFSSL* ssl;
  3345. WOLFSSL_METHOD method = // Some wolfSSL method
  3346. ctx = wolfSSL_CTX_new(method);
  3347. ssl = wolfSSL_new(ctx);
  3348. printf(wolfSSL_get_version("Using version: %s", ssl));
  3349. \endcode
  3350. \sa wolfSSL_lib_version
  3351. */
  3352. const char* wolfSSL_get_version(WOLFSSL* ssl);
  3353. /*!
  3354. \ingroup IO
  3355. \brief Returns the current cipher suit an ssl session is using.
  3356. \return ssl->options.cipherSuite An integer representing the current
  3357. cipher suite.
  3358. \return 0 The ssl session provided is null.
  3359. \param ssl The SSL session to check.
  3360. _Example_
  3361. \code
  3362. wolfSSL_Init();
  3363. WOLFSSL_CTX* ctx;
  3364. WOLFSSL* ssl;
  3365. WOLFSSL_METHOD method = // Some wolfSSL method
  3366. ctx = wolfSSL_CTX_new(method);
  3367. ssl = wolfSSL_new(ctx);
  3368. if(wolfSSL_get_current_cipher_suite(ssl) == 0)
  3369. {
  3370. // Error getting cipher suite
  3371. }
  3372. \endcode
  3373. \sa wolfSSL_CIPHER_get_name
  3374. \sa wolfSSL_get_current_cipher
  3375. \sa wolfSSL_get_cipher_list
  3376. */
  3377. int wolfSSL_get_current_cipher_suite(WOLFSSL* ssl);
  3378. /*!
  3379. \ingroup IO
  3380. \brief This function returns a pointer to the current cipher in the
  3381. ssl session.
  3382. \return The function returns the address of the cipher member of the
  3383. WOLFSSL struct. This is a pointer to the WOLFSSL_CIPHER structure.
  3384. \return NULL returned if the WOLFSSL structure is NULL.
  3385. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  3386. _Example_
  3387. \code
  3388. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  3389. WOLFSSL* ssl = wolfSSL_new(ctx);
  3390. WOLFSSL_CIPHER* cipherCurr = wolfSSL_get_current_cipher;
  3391. if(!cipherCurr){
  3392. // Failure case.
  3393. } else {
  3394. // The cipher was returned to cipherCurr
  3395. }
  3396. \endcode
  3397. \sa wolfSSL_get_cipher
  3398. \sa wolfSSL_get_cipher_name_internal
  3399. \sa wolfSSL_get_cipher_name
  3400. */
  3401. WOLFSSL_CIPHER* wolfSSL_get_current_cipher(WOLFSSL* ssl);
  3402. /*!
  3403. \ingroup IO
  3404. \brief This function matches the cipher suite in the SSL object with
  3405. the available suites and returns the string representation.
  3406. \return string This function returns the string representation of the
  3407. matched cipher suite.
  3408. \return none It will return “None” if there are no suites matched.
  3409. \param cipher a constant pointer to a WOLFSSL_CIPHER structure.
  3410. _Example_
  3411. \code
  3412. // gets cipher name in the format DHE_RSA ...
  3413. const char* wolfSSL_get_cipher_name_internal(WOLFSSL* ssl){
  3414. WOLFSSL_CIPHER* cipher;
  3415. const char* fullName;
  3416. cipher = wolfSSL_get_curent_cipher(ssl);
  3417. fullName = wolfSSL_CIPHER_get_name(cipher);
  3418. if(fullName){
  3419. // sanity check on returned cipher
  3420. }
  3421. \endcode
  3422. \sa wolfSSL_get_cipher
  3423. \sa wolfSSL_get_current_cipher
  3424. \sa wolfSSL_get_cipher_name_internal
  3425. \sa wolfSSL_get_cipher_name
  3426. */
  3427. const char* wolfSSL_CIPHER_get_name(const WOLFSSL_CIPHER* cipher);
  3428. /*!
  3429. \ingroup IO
  3430. \brief This function matches the cipher suite in the SSL object with
  3431. the available suites.
  3432. \return This function returns the string value of the suite matched. It
  3433. will return “None” if there are no suites matched.
  3434. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  3435. _Example_
  3436. \code
  3437. #ifdef WOLFSSL_DTLS
  3438. // make sure a valid suite is used
  3439. if(wolfSSL_get_cipher(ssl) == NULL){
  3440. WOLFSSL_MSG(“Can not match cipher suite imported”);
  3441. return MATCH_SUITE_ERROR;
  3442. }
  3443. #endif // WOLFSSL_DTLS
  3444. \endcode
  3445. \sa wolfSSL_CIPHER_get_name
  3446. \sa wolfSSL_get_current_cipher
  3447. */
  3448. const char* wolfSSL_get_cipher(WOLFSSL*);
  3449. /*!
  3450. \ingroup Setup
  3451. \brief This function returns the WOLFSSL_SESSION from the WOLFSSL structure
  3452. as a reference type. This requires calling wolfSSL_SESSION_free to release
  3453. the session reference. The WOLFSSL_SESSION pointed to contains all the
  3454. necessary information required to perform a session resumption and
  3455. reestablish the connection without a new handshake. For
  3456. session resumption, before calling wolfSSL_shutdown() with your session
  3457. object, an application should save the session ID from the object with a
  3458. call to wolfSSL_get1_session(), which returns a pointer to the session.
  3459. Later, the application should create a new WOLFSSL object and assign the
  3460. saved session with wolfSSL_set_session(). At this point, the application
  3461. may call wolfSSL_connect() and wolfSSL will try to resume the session.
  3462. The wolfSSL server code allows session resumption by default. The object
  3463. returned by wolfSSL_get1_session() needs to be freed after the application
  3464. is done with it by calling wolfSSL_SESSION_free() on it.
  3465. \return WOLFSSL_SESSION On success return session pointer.
  3466. \return NULL will be returned if ssl is NULL, the SSL session cache is
  3467. disabled, wolfSSL doesn’t have the Session ID available, or mutex
  3468. functions fail.
  3469. \param ssl WOLFSSL structure to get session from.
  3470. _Example_
  3471. \code
  3472. WOLFSSL* ssl;
  3473. WOLFSSL_SESSION* ses;
  3474. // attempt/complete handshake
  3475. wolfSSL_connect(ssl);
  3476. ses = wolfSSL_get1_session(ssl);
  3477. // check ses information
  3478. // disconnect / setup new SSL instance
  3479. wolfSSL_set_session(ssl, ses);
  3480. // attempt/resume handshake
  3481. wolfSSL_SESSION_free(ses);
  3482. \endcode
  3483. \sa wolfSSL_new
  3484. \sa wolfSSL_free
  3485. \sa wolfSSL_SESSION_free
  3486. */
  3487. WOLFSSL_SESSION* wolfSSL_get1_session(WOLFSSL* ssl);
  3488. /*!
  3489. \ingroup Setup
  3490. \brief The wolfSSLv23_client_method() function is used to indicate that
  3491. the application is a client and will support the highest protocol
  3492. version supported by the server between SSL 3.0 - TLS 1.3. This function
  3493. allocates memory for and initializes a new WOLFSSL_METHOD structure
  3494. to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
  3495. Both wolfSSL clients and servers have robust version downgrade capability.
  3496. If a specific protocol version method is used on either side, then only
  3497. that version will be negotiated or an error will be returned. For
  3498. example, a client that uses TLSv1 and tries to connect to a SSLv3 only
  3499. server will fail, likewise connecting to a TLSv1.1 will fail as well.
  3500. To resolve this issue, a client that uses the wolfSSLv23_client_method()
  3501. function will use the highest protocol version supported by the server and
  3502. downgrade to SSLv3 if needed. In this case, the client will be able to
  3503. connect to a server running SSLv3 - TLSv1.3.
  3504. \return pointer upon success a pointer to a WOLFSSL_METHOD.
  3505. \return Failure If memory allocation fails when calling XMALLOC,
  3506. the failure value of the underlying malloc() implementation will be
  3507. returned (typically NULL with errno will be set to ENOMEM).
  3508. \param none No parameters
  3509. _Example_
  3510. \code
  3511. WOLFSSL_METHOD* method;
  3512. WOLFSSL_CTX* ctx;
  3513. method = wolfSSLv23_client_method();
  3514. if (method == NULL) {
  3515. // unable to get method
  3516. }
  3517. ctx = wolfSSL_CTX_new(method);
  3518. ...
  3519. \endcode
  3520. \sa wolfSSLv3_client_method
  3521. \sa wolfTLSv1_client_method
  3522. \sa wolfTLSv1_1_client_method
  3523. \sa wolfTLSv1_2_client_method
  3524. \sa wolfTLSv1_3_client_method
  3525. \sa wolfDTLSv1_client_method
  3526. \sa wolfSSL_CTX_new
  3527. */
  3528. WOLFSSL_METHOD* wolfSSLv23_client_method(void);
  3529. /*!
  3530. \ingroup IO
  3531. \brief This is used to set a byte pointer to the start of the
  3532. internal memory buffer.
  3533. \return size On success the size of the buffer is returned
  3534. \return SSL_FATAL_ERROR If an error case was encountered.
  3535. \param bio WOLFSSL_BIO structure to get memory buffer of.
  3536. \param p byte pointer to set to memory buffer.
  3537. _Example_
  3538. \code
  3539. WOLFSSL_BIO* bio;
  3540. const byte* p;
  3541. int ret;
  3542. bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
  3543. ret = wolfSSL_BIO_get_mem_data(bio, &p);
  3544. // check ret value
  3545. \endcode
  3546. \sa wolfSSL_BIO_new
  3547. \sa wolfSSL_BIO_s_mem
  3548. \sa wolfSSL_BIO_set_fp
  3549. \sa wolfSSL_BIO_free
  3550. */
  3551. int wolfSSL_BIO_get_mem_data(WOLFSSL_BIO* bio,void* p);
  3552. /*!
  3553. \ingroup IO
  3554. \brief Sets the file descriptor for bio to use.
  3555. \return SSL_SUCCESS(1) upon success.
  3556. \param bio WOLFSSL_BIO structure to set fd.
  3557. \param fd file descriptor to use.
  3558. \param closeF flag for behavior when closing fd.
  3559. _Example_
  3560. \code
  3561. WOLFSSL_BIO* bio;
  3562. int fd;
  3563. // setup bio
  3564. wolfSSL_BIO_set_fd(bio, fd, BIO_NOCLOSE);
  3565. \endcode
  3566. \sa wolfSSL_BIO_new
  3567. \sa wolfSSL_BIO_free
  3568. */
  3569. long wolfSSL_BIO_set_fd(WOLFSSL_BIO* b, int fd, int flag);
  3570. /*!
  3571. \ingroup IO
  3572. \brief Sets the close flag, used to indicate that the i/o stream should be
  3573. closed when the BIO is freed
  3574. \return SSL_SUCCESS(1) upon success.
  3575. \param bio WOLFSSL_BIO structure.
  3576. \param flag flag for behavior when closing i/o stream.
  3577. _Example_
  3578. \code
  3579. WOLFSSL_BIO* bio;
  3580. // setup bio
  3581. wolfSSL_BIO_set_close(bio, BIO_NOCLOSE);
  3582. \endcode
  3583. \sa wolfSSL_BIO_new
  3584. \sa wolfSSL_BIO_free
  3585. */
  3586. int wolfSSL_BIO_set_close(WOLFSSL_BIO *b, long flag);
  3587. /*!
  3588. \ingroup IO
  3589. \brief This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD.
  3590. \return WOLFSSL_BIO_METHOD pointer to a WOLFSSL_BIO_METHOD structure
  3591. that is a socket type
  3592. \param none No parameters.
  3593. _Example_
  3594. \code
  3595. WOLFSSL_BIO* bio;
  3596. bio = wolfSSL_BIO_new(wolfSSL_BIO_s_socket);
  3597. \endcode
  3598. \sa wolfSSL_BIO_new
  3599. \sa wolfSSL_BIO_s_mem
  3600. */
  3601. WOLFSSL_BIO_METHOD *wolfSSL_BIO_s_socket(void);
  3602. /*!
  3603. \ingroup IO
  3604. \brief This is used to set the size of write buffer for a
  3605. WOLFSSL_BIO. If write buffer has been previously set this
  3606. function will free it when resetting the size. It is similar to
  3607. wolfSSL_BIO_reset in that it resets read and write indexes to 0.
  3608. \return SSL_SUCCESS On successfully setting the write buffer.
  3609. \return SSL_FAILURE If an error case was encountered.
  3610. \param bio WOLFSSL_BIO structure to set fd.
  3611. \param size size of buffer to allocate.
  3612. _Example_
  3613. \code
  3614. WOLFSSL_BIO* bio;
  3615. int ret;
  3616. bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
  3617. ret = wolfSSL_BIO_set_write_buf_size(bio, 15000);
  3618. // check return value
  3619. \endcode
  3620. \sa wolfSSL_BIO_new
  3621. \sa wolfSSL_BIO_s_mem
  3622. \sa wolfSSL_BIO_free
  3623. */
  3624. int wolfSSL_BIO_set_write_buf_size(WOLFSSL_BIO *b, long size);
  3625. /*!
  3626. \ingroup IO
  3627. \brief This is used to pair two bios together. A pair of bios acts
  3628. similar to a two way pipe writing to one can be read by the other
  3629. and vice versa. It is expected that both bios be in the same thread,
  3630. this function is not thread safe. Freeing one of the two bios removes
  3631. both from being paired. If a write buffer size was not previously
  3632. set for either of the bios it is set to a default size of 17000
  3633. (WOLFSSL_BIO_SIZE) before being paired.
  3634. \return SSL_SUCCESS On successfully pairing the two bios.
  3635. \return SSL_FAILURE If an error case was encountered.
  3636. \param b1 WOLFSSL_BIO structure to set pair.
  3637. \param b2 second WOLFSSL_BIO structure to complete pair.
  3638. _Example_
  3639. \code
  3640. WOLFSSL_BIO* bio;
  3641. WOLFSSL_BIO* bio2;
  3642. int ret;
  3643. bio = wolfSSL_BIO_new(wolfSSL_BIO_s_bio());
  3644. bio2 = wolfSSL_BIO_new(wolfSSL_BIO_s_bio());
  3645. ret = wolfSSL_BIO_make_bio_pair(bio, bio2);
  3646. // check ret value
  3647. \endcode
  3648. \sa wolfSSL_BIO_new
  3649. \sa wolfSSL_BIO_s_mem
  3650. \sa wolfSSL_BIO_free
  3651. */
  3652. int wolfSSL_BIO_make_bio_pair(WOLFSSL_BIO *b1, WOLFSSL_BIO *b2);
  3653. /*!
  3654. \ingroup IO
  3655. \brief This is used to set the read request flag back to 0.
  3656. \return SSL_SUCCESS On successfully setting value.
  3657. \return SSL_FAILURE If an error case was encountered.
  3658. \param bio WOLFSSL_BIO structure to set read request flag.
  3659. _Example_
  3660. \code
  3661. WOLFSSL_BIO* bio;
  3662. int ret;
  3663. ...
  3664. ret = wolfSSL_BIO_ctrl_reset_read_request(bio);
  3665. // check ret value
  3666. \endcode
  3667. \sa wolfSSL_BIO_new, wolfSSL_BIO_s_mem
  3668. \sa wolfSSL_BIO_new, wolfSSL_BIO_free
  3669. */
  3670. int wolfSSL_BIO_ctrl_reset_read_request(WOLFSSL_BIO *bio);
  3671. /*!
  3672. \ingroup IO
  3673. \brief This is used to get a buffer pointer for reading from. Unlike
  3674. wolfSSL_BIO_nread the internal read index is not advanced by the number
  3675. returned from the function call. Reading past the value returned can
  3676. result in reading out of array bounds.
  3677. \return >=0 on success return the number of bytes to read
  3678. \param bio WOLFSSL_BIO structure to read from.
  3679. \param buf pointer to set at beginning of read array.
  3680. _Example_
  3681. \code
  3682. WOLFSSL_BIO* bio;
  3683. char* bufPt;
  3684. int ret;
  3685. // set up bio
  3686. ret = wolfSSL_BIO_nread0(bio, &bufPt); // read as many bytes as possible
  3687. // handle negative ret check
  3688. // read ret bytes from bufPt
  3689. \endcode
  3690. \sa wolfSSL_BIO_new
  3691. \sa wolfSSL_BIO_nwrite0
  3692. */
  3693. int wolfSSL_BIO_nread0(WOLFSSL_BIO *bio, char **buf);
  3694. /*!
  3695. \ingroup IO
  3696. \brief This is used to get a buffer pointer for reading from. The internal
  3697. read index is advanced by the number returned from the function call with
  3698. buf being pointed to the beginning of the buffer to read from. In the
  3699. case that less bytes are in the read buffer than the value requested with
  3700. num the lesser value is returned. Reading past the value returned can
  3701. result in reading out of array bounds.
  3702. \return >=0 on success return the number of bytes to read
  3703. \return WOLFSSL_BIO_ERROR(-1) on error case with nothing to read return -1
  3704. \param bio WOLFSSL_BIO structure to read from.
  3705. \param buf pointer to set at beginning of read array.
  3706. \param num number of bytes to try and read.
  3707. _Example_
  3708. \code
  3709. WOLFSSL_BIO* bio;
  3710. char* bufPt;
  3711. int ret;
  3712. // set up bio
  3713. ret = wolfSSL_BIO_nread(bio, &bufPt, 10); // try to read 10 bytes
  3714. // handle negative ret check
  3715. // read ret bytes from bufPt
  3716. \endcode
  3717. \sa wolfSSL_BIO_new
  3718. \sa wolfSSL_BIO_nwrite
  3719. */
  3720. int wolfSSL_BIO_nread(WOLFSSL_BIO *bio, char **buf, int num);
  3721. /*!
  3722. \ingroup IO
  3723. \brief Gets a pointer to the buffer for writing as many bytes as returned by
  3724. the function. Writing more bytes to the pointer returned then the value
  3725. returned can result in writing out of bounds.
  3726. \return int Returns the number of bytes that can be written to the buffer
  3727. pointer returned.
  3728. \return WOLFSSL_BIO_UNSET(-2) in the case that is not part of a bio pair
  3729. \return WOLFSSL_BIO_ERROR(-1) in the case that there is no more room to
  3730. write to
  3731. \param bio WOLFSSL_BIO structure to write to.
  3732. \param buf pointer to buffer to write to.
  3733. \param num number of bytes desired to be written.
  3734. _Example_
  3735. \code
  3736. WOLFSSL_BIO* bio;
  3737. char* bufPt;
  3738. int ret;
  3739. // set up bio
  3740. ret = wolfSSL_BIO_nwrite(bio, &bufPt, 10); // try to write 10 bytes
  3741. // handle negative ret check
  3742. // write ret bytes to bufPt
  3743. \endcode
  3744. \sa wolfSSL_BIO_new
  3745. \sa wolfSSL_BIO_free
  3746. \sa wolfSSL_BIO_nread
  3747. */
  3748. int wolfSSL_BIO_nwrite(WOLFSSL_BIO *bio, char **buf, int num);
  3749. /*!
  3750. \ingroup IO
  3751. \brief Resets bio to an initial state. As an example for type BIO_BIO
  3752. this resets the read and write index.
  3753. \return 0 On successfully resetting the bio.
  3754. \return WOLFSSL_BIO_ERROR(-1) Returned on bad input or unsuccessful reset.
  3755. \param bio WOLFSSL_BIO structure to reset.
  3756. _Example_
  3757. \code
  3758. WOLFSSL_BIO* bio;
  3759. // setup bio
  3760. wolfSSL_BIO_reset(bio);
  3761. //use pt
  3762. \endcode
  3763. \sa wolfSSL_BIO_new
  3764. \sa wolfSSL_BIO_free
  3765. */
  3766. int wolfSSL_BIO_reset(WOLFSSL_BIO *bio);
  3767. /*!
  3768. \ingroup IO
  3769. \brief This function adjusts the file pointer to the offset given. This
  3770. is the offset from the head of the file.
  3771. \return 0 On successfully seeking.
  3772. \return -1 If an error case was encountered.
  3773. \param bio WOLFSSL_BIO structure to set.
  3774. \param ofs offset into file.
  3775. _Example_
  3776. \code
  3777. WOLFSSL_BIO* bio;
  3778. XFILE fp;
  3779. int ret;
  3780. bio = wolfSSL_BIO_new(wolfSSL_BIO_s_file());
  3781. ret = wolfSSL_BIO_set_fp(bio, &fp);
  3782. // check ret value
  3783. ret = wolfSSL_BIO_seek(bio, 3);
  3784. // check ret value
  3785. \endcode
  3786. \sa wolfSSL_BIO_new
  3787. \sa wolfSSL_BIO_s_mem
  3788. \sa wolfSSL_BIO_set_fp
  3789. \sa wolfSSL_BIO_free
  3790. */
  3791. int wolfSSL_BIO_seek(WOLFSSL_BIO *bio, int ofs);
  3792. /*!
  3793. \ingroup IO
  3794. \brief This is used to set and write to a file. WIll overwrite any data
  3795. currently in the file and is set to close the file when the bio is freed.
  3796. \return SSL_SUCCESS On successfully opening and setting file.
  3797. \return SSL_FAILURE If an error case was encountered.
  3798. \param bio WOLFSSL_BIO structure to set file.
  3799. \param name name of file to write to.
  3800. _Example_
  3801. \code
  3802. WOLFSSL_BIO* bio;
  3803. int ret;
  3804. bio = wolfSSL_BIO_new(wolfSSL_BIO_s_file());
  3805. ret = wolfSSL_BIO_write_filename(bio, “test.txt”);
  3806. // check ret value
  3807. \endcode
  3808. \sa wolfSSL_BIO_new
  3809. \sa wolfSSL_BIO_s_file
  3810. \sa wolfSSL_BIO_set_fp
  3811. \sa wolfSSL_BIO_free
  3812. */
  3813. int wolfSSL_BIO_write_filename(WOLFSSL_BIO *bio, char *name);
  3814. /*!
  3815. \ingroup IO
  3816. \brief This is used to set the end of file value. Common value is -1 so
  3817. as not to get confused with expected positive values.
  3818. \return 0 returned on completion
  3819. \param bio WOLFSSL_BIO structure to set end of file value.
  3820. \param v value to set in bio.
  3821. _Example_
  3822. \code
  3823. WOLFSSL_BIO* bio;
  3824. int ret;
  3825. bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
  3826. ret = wolfSSL_BIO_set_mem_eof_return(bio, -1);
  3827. // check ret value
  3828. \endcode
  3829. \sa wolfSSL_BIO_new
  3830. \sa wolfSSL_BIO_s_mem
  3831. \sa wolfSSL_BIO_set_fp
  3832. \sa wolfSSL_BIO_free
  3833. */
  3834. long wolfSSL_BIO_set_mem_eof_return(WOLFSSL_BIO *bio, int v);
  3835. /*!
  3836. \ingroup IO
  3837. \brief This is a getter function for WOLFSSL_BIO memory pointer.
  3838. \return SSL_SUCCESS On successfully getting the pointer SSL_SUCCESS is
  3839. returned (currently value of 1).
  3840. \return SSL_FAILURE Returned if NULL arguments are passed in (currently
  3841. value of 0).
  3842. \param bio pointer to the WOLFSSL_BIO structure for getting memory pointer.
  3843. \param ptr structure that is currently a char*. Is set to point to
  3844. bio’s memory.
  3845. _Example_
  3846. \code
  3847. WOLFSSL_BIO* bio;
  3848. WOLFSSL_BUF_MEM* pt;
  3849. // setup bio
  3850. wolfSSL_BIO_get_mem_ptr(bio, &pt);
  3851. //use pt
  3852. \endcode
  3853. \sa wolfSSL_BIO_new
  3854. \sa wolfSSL_BIO_s_mem
  3855. */
  3856. long wolfSSL_BIO_get_mem_ptr(WOLFSSL_BIO *bio, WOLFSSL_BUF_MEM **m);
  3857. /*!
  3858. \ingroup CertsKeys
  3859. \brief This function copies the name of the x509 into a buffer.
  3860. \return A char pointer to the buffer with the WOLFSSL_X509_NAME structures
  3861. name member’s data is returned if the function executed normally.
  3862. \param name a pointer to a WOLFSSL_X509 structure.
  3863. \param in a buffer to hold the name copied from the
  3864. WOLFSSL_X509_NAME structure.
  3865. \param sz the maximum size of the buffer.
  3866. _Example_
  3867. \code
  3868. WOLFSSL_X509 x509;
  3869. char* name;
  3870. ...
  3871. name = wolfSSL_X509_NAME_oneline(wolfSSL_X509_get_issuer_name(x509), 0, 0);
  3872. if(name <= 0){
  3873. // There’s nothing in the buffer.
  3874. }
  3875. \endcode
  3876. \sa wolfSSL_X509_get_subject_name
  3877. \sa wolfSSL_X509_get_issuer_name
  3878. \sa wolfSSL_X509_get_isCA
  3879. \sa wolfSSL_get_peer_certificate
  3880. \sa wolfSSL_X509_version
  3881. */
  3882. char* wolfSSL_X509_NAME_oneline(WOLFSSL_X509_NAME* name, char* in, int sz);
  3883. /*!
  3884. \ingroup CertsKeys
  3885. \brief This function returns the name of the certificate issuer.
  3886. \return point a pointer to the WOLFSSL_X509 struct’s issuer member is
  3887. returned.
  3888. \return NULL if the cert passed in is NULL.
  3889. \param cert a pointer to a WOLFSSL_X509 structure.
  3890. _Example_
  3891. \code
  3892. WOLFSSL_X509* x509;
  3893. WOLFSSL_X509_NAME issuer;
  3894. ...
  3895. issuer = wolfSSL_X509_NAME_oneline(wolfSSL_X509_get_issuer_name(x509), 0, 0);
  3896. if(!issuer){
  3897. // NULL was returned
  3898. } else {
  3899. // issuer hods the name of the certificate issuer.
  3900. }
  3901. \endcode
  3902. \sa wolfSSL_X509_get_subject_name
  3903. \sa wolfSSL_X509_get_isCA
  3904. \sa wolfSSL_get_peer_certificate
  3905. \sa wolfSSL_X509_NAME_oneline
  3906. */
  3907. WOLFSSL_X509_NAME* wolfSSL_X509_get_issuer_name(WOLFSSL_X509* cert);
  3908. /*!
  3909. \ingroup CertsKeys
  3910. \brief This function returns the subject member of the WOLFSSL_X509
  3911. structure.
  3912. \return pointer a pointer to the WOLFSSL_X509_NAME structure. The pointer
  3913. may be NULL if the WOLFSSL_X509 struct is NULL or if the subject member of
  3914. the structure is NULL.
  3915. \param cert a pointer to a WOLFSSL_X509 structure.
  3916. _Example_
  3917. \code
  3918. WOLFSSL_X509* cert;
  3919. WOLFSSL_X509_NAME name;
  3920. name = wolfSSL_X509_get_subject_name(cert);
  3921. if(name == NULL){
  3922. // Deal with the NULL cacse
  3923. }
  3924. \endcode
  3925. \sa wolfSSL_X509_get_issuer_name
  3926. \sa wolfSSL_X509_get_isCA
  3927. \sa wolfSSL_get_peer_certificate
  3928. */
  3929. WOLFSSL_X509_NAME* wolfSSL_X509_get_subject_name(WOLFSSL_X509* cert);
  3930. /*!
  3931. \ingroup CertsKeys
  3932. \brief Checks the isCa member of the WOLFSSL_X509 structure and returns
  3933. the value.
  3934. \return isCA returns the value in the isCA member of the WOLFSSL_X509
  3935. structure is returned.
  3936. \return 0 returned if there is not a valid x509 structure passed in.
  3937. \param cert a pointer to a WOLFSSL_X509 structure.
  3938. _Example_
  3939. \code
  3940. WOLFSSL* ssl;
  3941. ...
  3942. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  3943. WOLFSSL* ssl = wolfSSL_new(ctx);
  3944. ...
  3945. if(wolfSSL_X509_get_isCA(ssl)){
  3946. // This is the CA
  3947. }else {
  3948. // Failure case
  3949. }
  3950. \endcode
  3951. \sa wolfSSL_X509_get_issuer_name
  3952. \sa wolfSSL_X509_get_isCA
  3953. */
  3954. int wolfSSL_X509_get_isCA(WOLFSSL_X509* cert);
  3955. /*!
  3956. \ingroup CertsKeys
  3957. \brief This function gets the text related to the passed in NID value.
  3958. \return int returns the size of the text buffer.
  3959. \param name WOLFSSL_X509_NAME to search for text.
  3960. \param nid NID to search for.
  3961. \param buf buffer to hold text when found.
  3962. \param len length of buffer.
  3963. _Example_
  3964. \code
  3965. WOLFSSL_X509_NAME* name;
  3966. char buffer[100];
  3967. int bufferSz;
  3968. int ret;
  3969. // get WOLFSSL_X509_NAME
  3970. ret = wolfSSL_X509_NAME_get_text_by_NID(name, NID_commonName,
  3971. buffer, bufferSz);
  3972. //check ret value
  3973. \endcode
  3974. \sa none
  3975. */
  3976. int wolfSSL_X509_NAME_get_text_by_NID(WOLFSSL_X509_NAME* name, int nid,
  3977. char* buf, int len);
  3978. /*!
  3979. \ingroup CertsKeys
  3980. \brief This function returns the value stored in the sigOID
  3981. member of the WOLFSSL_X509 structure.
  3982. \return 0 returned if the WOLFSSL_X509 structure is NULL.
  3983. \return int an integer value is returned which was retrieved from
  3984. the x509 object.
  3985. \param cert a pointer to a WOLFSSL_X509 structure.
  3986. _Example_
  3987. \code
  3988. WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
  3989. DYNAMIC_TYPE_X509);
  3990. ...
  3991. int x509SigType = wolfSSL_X509_get_signature_type(x509);
  3992. if(x509SigType != EXPECTED){
  3993. // Deal with an unexpected value
  3994. }
  3995. \endcode
  3996. \sa wolfSSL_X509_get_signature
  3997. \sa wolfSSL_X509_version
  3998. \sa wolfSSL_X509_get_der
  3999. \sa wolfSSL_X509_get_serial_number
  4000. \sa wolfSSL_X509_notBefore
  4001. \sa wolfSSL_X509_notAfter
  4002. \sa wolfSSL_X509_free
  4003. */
  4004. int wolfSSL_X509_get_signature_type(WOLFSSL_X509* cert);
  4005. /*!
  4006. \brief This function frees a WOLFSSL_X509 structure.
  4007. \param x509 a pointer to the WOLFSSL_X509 struct.
  4008. _Example_
  4009. \code
  4010. WOLFSSL_X509* x509 = (WOLFSSL_X509*)XMALOC(sizeof(WOLFSSL_X509), NULL,
  4011. DYNAMIC_TYPE_X509) ;
  4012. wolfSSL_X509_free(x509);
  4013. \endcode
  4014. \sa wolfSSL_X509_get_signature
  4015. \sa wolfSSL_X509_version
  4016. \sa wolfSSL_X509_get_der
  4017. \sa wolfSSL_X509_get_serial_number
  4018. \sa wolfSSL_X509_notBefore
  4019. \sa wolfSSL_X509_notAfter
  4020. */
  4021. void wolfSSL_X509_free(WOLFSSL_X509* x509);
  4022. /*!
  4023. \ingroup CertsKeys
  4024. \brief Gets the X509 signature and stores it in the buffer.
  4025. \return SSL_SUCCESS returned if the function successfully executes.
  4026. The signature is loaded into the buffer.
  4027. \return SSL_FATAL_ERRROR returns if the x509 struct or the bufSz member
  4028. is NULL. There is also a check for the length member of the sig structure
  4029. (sig is a member of x509).
  4030. \param x509 pointer to a WOLFSSL_X509 structure.
  4031. \param buf a char pointer to the buffer.
  4032. \param bufSz an integer pointer to the size of the buffer.
  4033. _Example_
  4034. \code
  4035. WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL,
  4036. DYNAMIC_TYPE_X509);
  4037. unsigned char* buf; // Initialize
  4038. int* bufSz = sizeof(buf)/sizeof(unsigned char);
  4039. ...
  4040. if(wolfSSL_X509_get_signature(x509, buf, bufSz) != SSL_SUCCESS){
  4041. // The function did not execute successfully.
  4042. } else{
  4043. // The buffer was written to correctly.
  4044. }
  4045. \endcode
  4046. \sa wolfSSL_X509_get_serial_number
  4047. \sa wolfSSL_X509_get_signature_type
  4048. \sa wolfSSL_X509_get_device_type
  4049. */
  4050. int wolfSSL_X509_get_signature(WOLFSSL_X509* x509, unsigned char* buf, int* bufSz);
  4051. /*!
  4052. \ingroup CertsKeys
  4053. \brief This function adds a certificate to the WOLFSSL_X509_STRE structure.
  4054. \return SSL_SUCCESS If certificate is added successfully.
  4055. \return SSL_FATAL_ERROR: If certificate is not added successfully.
  4056. \param str certificate store to add the certificate to.
  4057. \param x509 certificate to add.
  4058. _Example_
  4059. \code
  4060. WOLFSSL_X509_STORE* str;
  4061. WOLFSSL_X509* x509;
  4062. int ret;
  4063. ret = wolfSSL_X509_STORE_add_cert(str, x509);
  4064. //check ret value
  4065. \endcode
  4066. \sa wolfSSL_X509_free
  4067. */
  4068. int wolfSSL_X509_STORE_add_cert(WOLFSSL_X509_STORE* store, WOLFSSL_X509* x509);
  4069. /*!
  4070. \ingroup CertsKeys
  4071. \brief This function is a getter function for chain variable
  4072. in WOLFSSL_X509_STORE_CTX structure. Currently chain is not populated.
  4073. \return pointer if successful returns WOLFSSL_STACK
  4074. (same as STACK_OF(WOLFSSL_X509)) pointer
  4075. \return Null upon failure
  4076. \param ctx certificate store ctx to get parse chain from.
  4077. _Example_
  4078. \code
  4079. WOLFSSL_STACK* sk;
  4080. WOLFSSL_X509_STORE_CTX* ctx;
  4081. sk = wolfSSL_X509_STORE_CTX_get_chain(ctx);
  4082. //check sk for NULL and then use it. sk needs freed after done.
  4083. \endcode
  4084. \sa wolfSSL_sk_X509_free
  4085. */
  4086. WOLFSSL_STACK* wolfSSL_X509_STORE_CTX_get_chain(
  4087. WOLFSSL_X509_STORE_CTX* ctx);
  4088. /*!
  4089. \ingroup CertsKeys
  4090. \brief This function takes in a flag to change the behavior of the
  4091. WOLFSSL_X509_STORE structure passed in. An example of a flag used
  4092. is WOLFSSL_CRL_CHECK.
  4093. \return SSL_SUCCESS If no errors were encountered when setting the flag.
  4094. \return <0 a negative value will be returned upon failure.
  4095. \param str certificate store to set flag in.
  4096. \param flag flag for behavior.
  4097. _Example_
  4098. \code
  4099. WOLFSSL_X509_STORE* str;
  4100. int ret;
  4101. // create and set up str
  4102. ret = wolfSSL_X509_STORE_set_flags(str, WOLFSSL_CRL_CHECKALL);
  4103. If (ret != SSL_SUCCESS) {
  4104. //check ret value and handle error case
  4105. }
  4106. \endcode
  4107. \sa wolfSSL_X509_STORE_new
  4108. \sa wolfSSL_X509_STORE_free
  4109. */
  4110. int wolfSSL_X509_STORE_set_flags(WOLFSSL_X509_STORE* store,
  4111. unsigned long flag);
  4112. /*!
  4113. \ingroup CertsKeys
  4114. \brief This function the certificate "not before" validity encoded as
  4115. a byte array.
  4116. \return NULL returned if the WOLFSSL_X509 structure is NULL.
  4117. \return byte is returned that contains the notBeforeData.
  4118. \param x509 pointer to a WOLFSSL_X509 structure.
  4119. _Example_
  4120. \code
  4121. WOLFSSL_X509* x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
  4122. DYNAMIC_TYPE_X509);
  4123. ...
  4124. byte* notBeforeData = wolfSSL_X509_notBefore(x509);
  4125. \endcode
  4126. \sa wolfSSL_X509_get_signature
  4127. \sa wolfSSL_X509_version
  4128. \sa wolfSSL_X509_get_der
  4129. \sa wolfSSL_X509_get_serial_number
  4130. \sa wolfSSL_X509_notAfter
  4131. \sa wolfSSL_X509_free
  4132. */
  4133. const byte* wolfSSL_X509_notBefore(WOLFSSL_X509* x509);
  4134. /*!
  4135. \ingroup CertsKeys
  4136. \brief This function the certificate "not after" validity encoded as
  4137. a byte array.
  4138. \return NULL returned if the WOLFSSL_X509 structure is NULL.
  4139. \return byte is returned that contains the notAfterData.
  4140. \param x509 pointer to a WOLFSSL_X509 structure.
  4141. _Example_
  4142. \code
  4143. WOLFSSL_X509* x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
  4144. DYNAMIC_TYPE_X509);
  4145. ...
  4146. byte* notAfterData = wolfSSL_X509_notAfter(x509);
  4147. \endcode
  4148. \sa wolfSSL_X509_get_signature
  4149. \sa wolfSSL_X509_version
  4150. \sa wolfSSL_X509_get_der
  4151. \sa wolfSSL_X509_get_serial_number
  4152. \sa wolfSSL_X509_notBefore
  4153. \sa wolfSSL_X509_free
  4154. */
  4155. const byte* wolfSSL_X509_notAfter(WOLFSSL_X509* x509);
  4156. /*!
  4157. \ingroup Setup
  4158. \brief This function is used to copy a WOLFSSL_ASN1_INTEGER
  4159. value to a WOLFSSL_BIGNUM structure.
  4160. \return pointer On successfully copying the WOLFSSL_ASN1_INTEGER
  4161. value a WOLFSSL_BIGNUM pointer is returned.
  4162. \return Null upon failure.
  4163. \param ai WOLFSSL_ASN1_INTEGER structure to copy from.
  4164. \param bn if wanting to copy into an already existing
  4165. WOLFSSL_BIGNUM struct then pass in a pointer to it.
  4166. Optionally this can be NULL and a new WOLFSSL_BIGNUM
  4167. structure will be created.
  4168. _Example_
  4169. \code
  4170. WOLFSSL_ASN1_INTEGER* ai;
  4171. WOLFSSL_BIGNUM* bn;
  4172. // create ai
  4173. bn = wolfSSL_ASN1_INTEGER_to_BN(ai, NULL);
  4174. // or if having already created bn and wanting to reuse structure
  4175. // wolfSSL_ASN1_INTEGER_to_BN(ai, bn);
  4176. // check bn is or return value is not NULL
  4177. \endcode
  4178. \sa none
  4179. */
  4180. WOLFSSL_BIGNUM *wolfSSL_ASN1_INTEGER_to_BN(const WOLFSSL_ASN1_INTEGER *ai,
  4181. WOLFSSL_BIGNUM *bn);
  4182. /*!
  4183. \ingroup Setup
  4184. \brief This function adds the certificate to the internal chain
  4185. being built in the WOLFSSL_CTX structure.
  4186. \return SSL_SUCCESS after successfully adding the certificate.
  4187. \return SSL_FAILURE if failing to add the certificate to the chain.
  4188. \param ctx WOLFSSL_CTX structure to add certificate to.
  4189. \param x509 certificate to add to the chain.
  4190. _Example_
  4191. \code
  4192. WOLFSSL_CTX* ctx;
  4193. WOLFSSL_X509* x509;
  4194. int ret;
  4195. // create ctx
  4196. ret = wolfSSL_CTX_add_extra_chain_cert(ctx, x509);
  4197. // check ret value
  4198. \endcode
  4199. \sa wolfSSL_CTX_new
  4200. \sa wolfSSL_CTX_free
  4201. */
  4202. long wolfSSL_CTX_add_extra_chain_cert(WOLFSSL_CTX* ctx, WOLFSSL_X509* x509);
  4203. /*!
  4204. \ingroup Setup
  4205. \brief This function returns the get read ahead flag from a
  4206. WOLFSSL_CTX structure.
  4207. \return flag On success returns the read ahead flag.
  4208. \return SSL_FAILURE If ctx is NULL then SSL_FAILURE is returned.
  4209. \param ctx WOLFSSL_CTX structure to get read ahead flag from.
  4210. _Example_
  4211. \code
  4212. WOLFSSL_CTX* ctx;
  4213. int flag;
  4214. // setup ctx
  4215. flag = wolfSSL_CTX_get_read_ahead(ctx);
  4216. //check flag
  4217. \endcode
  4218. \sa wolfSSL_CTX_new
  4219. \sa wolfSSL_CTX_free
  4220. \sa wolfSSL_CTX_set_read_ahead
  4221. */
  4222. int wolfSSL_CTX_get_read_ahead(WOLFSSL_CTX* ctx);
  4223. /*!
  4224. \ingroup Setup
  4225. \brief This function sets the read ahead flag in the WOLFSSL_CTX structure.
  4226. \return SSL_SUCCESS If ctx read ahead flag set.
  4227. \return SSL_FAILURE If ctx is NULL then SSL_FAILURE is returned.
  4228. \param ctx WOLFSSL_CTX structure to set read ahead flag.
  4229. \param v read ahead flag
  4230. _Example_
  4231. \code
  4232. WOLFSSL_CTX* ctx;
  4233. int flag;
  4234. int ret;
  4235. // setup ctx
  4236. ret = wolfSSL_CTX_set_read_ahead(ctx, flag);
  4237. // check return value
  4238. \endcode
  4239. \sa wolfSSL_CTX_new
  4240. \sa wolfSSL_CTX_free
  4241. \sa wolfSSL_CTX_get_read_ahead
  4242. */
  4243. int wolfSSL_CTX_set_read_ahead(WOLFSSL_CTX* ctx, int v);
  4244. /*!
  4245. \ingroup Setup
  4246. \brief This function sets the options argument to use with OCSP.
  4247. \return SSL_FAILURE If ctx or it’s cert manager is NULL.
  4248. \return SSL_SUCCESS If successfully set.
  4249. \param ctx WOLFSSL_CTX structure to set user argument.
  4250. \param arg user argument.
  4251. _Example_
  4252. \code
  4253. WOLFSSL_CTX* ctx;
  4254. void* data;
  4255. int ret;
  4256. // setup ctx
  4257. ret = wolfSSL_CTX_set_tlsext_status_arg(ctx, data);
  4258. //check ret value
  4259. \endcode
  4260. \sa wolfSSL_CTX_new
  4261. \sa wolfSSL_CTX_free
  4262. */
  4263. long wolfSSL_CTX_set_tlsext_status_arg(WOLFSSL_CTX* ctx, void* arg);
  4264. /*!
  4265. \ingroup Setup
  4266. \brief This function sets the optional argument to be passed to
  4267. the PRF callback.
  4268. \return SSL_FAILURE If ctx is NULL.
  4269. \return SSL_SUCCESS If successfully set.
  4270. \param ctx WOLFSSL_CTX structure to set user argument.
  4271. \param arg user argument.
  4272. _Example_
  4273. \code
  4274. WOLFSSL_CTX* ctx;
  4275. void* data;
  4276. int ret;
  4277. // setup ctx
  4278. ret = wolfSSL_CTX_set_tlsext_opaques_prf_input_callback_arg(ctx, data);
  4279. //check ret value
  4280. \endcode
  4281. \sa wolfSSL_CTX_new
  4282. \sa wolfSSL_CTX_free
  4283. */
  4284. long wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg(
  4285. WOLFSSL_CTX* ctx, void* arg);
  4286. /*!
  4287. \ingroup Setup
  4288. \brief This function sets the options mask in the ssl.
  4289. Some valid options are, SSL_OP_ALL, SSL_OP_COOKIE_EXCHANGE,
  4290. SSL_OP_NO_SSLv2, SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1,
  4291. SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_2, SSL_OP_NO_COMPRESSION.
  4292. \return val Returns the updated options mask value stored in ssl.
  4293. \param s WOLFSSL structure to set options mask.
  4294. \param op This function sets the options mask in the ssl.
  4295. Some valid options are:
  4296. SSL_OP_ALL
  4297. SSL_OP_COOKIE_EXCHANGE
  4298. SSL_OP_NO_SSLv2
  4299. SSL_OP_NO_SSLv3
  4300. SSL_OP_NO_TLSv1
  4301. SSL_OP_NO_TLSv1_1
  4302. SSL_OP_NO_TLSv1_2
  4303. SSL_OP_NO_COMPRESSION
  4304. _Example_
  4305. \code
  4306. WOLFSSL* ssl;
  4307. unsigned long mask;
  4308. mask = SSL_OP_NO_TLSv1
  4309. mask = wolfSSL_set_options(ssl, mask);
  4310. // check mask
  4311. \endcode
  4312. \sa wolfSSL_new
  4313. \sa wolfSSL_free
  4314. \sa wolfSSL_get_options
  4315. */
  4316. long wolfSSL_set_options(WOLFSSL *s, long op);
  4317. /*!
  4318. \ingroup Setup
  4319. \brief This function returns the current options mask.
  4320. \return val Returns the mask value stored in ssl.
  4321. \param ssl WOLFSSL structure to get options mask from.
  4322. _Example_
  4323. \code
  4324. WOLFSSL* ssl;
  4325. unsigned long mask;
  4326. mask = wolfSSL_get_options(ssl);
  4327. // check mask
  4328. \endcode
  4329. \sa wolfSSL_new
  4330. \sa wolfSSL_free
  4331. \sa wolfSSL_set_options
  4332. */
  4333. long wolfSSL_get_options(const WOLFSSL *ssl);
  4334. /*!
  4335. \ingroup Setup
  4336. \brief This is used to set the debug argument passed around.
  4337. \return SSL_SUCCESS On successful setting argument.
  4338. \return SSL_FAILURE If an NULL ssl passed in.
  4339. \param ssl WOLFSSL structure to set argument in.
  4340. \param arg argument to use.
  4341. _Example_
  4342. \code
  4343. WOLFSSL* ssl;
  4344. void* args;
  4345. int ret;
  4346. // create ssl object
  4347. ret = wolfSSL_set_tlsext_debug_arg(ssl, args);
  4348. // check ret value
  4349. \endcode
  4350. \sa wolfSSL_new
  4351. \sa wolfSSL_free
  4352. */
  4353. long wolfSSL_set_tlsext_debug_arg(WOLFSSL *ssl, void *arg);
  4354. /*!
  4355. \ingroup openSSL
  4356. \brief This function is called when the client application request
  4357. that a server send back an OCSP status response (also known as
  4358. OCSP stapling).Currently, the only supported type is
  4359. TLSEXT_STATUSTYPE_ocsp.
  4360. \return 1 upon success.
  4361. \return 0 upon error.
  4362. \param s pointer to WOLFSSL struct which is created by SSL_new() function
  4363. \param type ssl extension type which TLSEXT_STATUSTYPE_ocsp is
  4364. only supported.
  4365. _Example_
  4366. \code
  4367. WOLFSSL *ssl;
  4368. WOLFSSL_CTX *ctx;
  4369. int ret;
  4370. ctx = wolfSSL_CTX_new(wolfSSLv23_server_method());
  4371. ssl = wolfSSL_new(ctx);
  4372. ret = WolfSSL_set_tlsext_status_type(ssl,TLSEXT_STATUSTYPE_ocsp);
  4373. wolfSSL_free(ssl);
  4374. wolfSSL_CTX_free(ctx);
  4375. \endcode
  4376. \sa wolfSSL_new
  4377. \sa wolfSSL_CTX_new
  4378. \sa wolfSSL_free
  4379. \sa wolfSSL_CTX_free
  4380. */
  4381. long wolfSSL_set_tlsext_status_type(WOLFSSL *s, int type);
  4382. /*!
  4383. \ingroup Setup
  4384. \brief This is used to get the results after trying to verify the peer's
  4385. certificate.
  4386. \return X509_V_OK On successful verification.
  4387. \return SSL_FAILURE If an NULL ssl passed in.
  4388. \param ssl WOLFSSL structure to get verification results from.
  4389. _Example_
  4390. \code
  4391. WOLFSSL* ssl;
  4392. long ret;
  4393. // attempt/complete handshake
  4394. ret = wolfSSL_get_verify_result(ssl);
  4395. // check ret value
  4396. \endcode
  4397. \sa wolfSSL_new
  4398. \sa wolfSSL_free
  4399. */
  4400. long wolfSSL_get_verify_result(const WOLFSSL *ssl);
  4401. /*!
  4402. \ingroup Debug
  4403. \brief This function converts an error code returned by
  4404. wolfSSL_get_error() into a more human-readable error string
  4405. and prints that string to the output file - fp. err is the
  4406. error code returned by wolfSSL_get_error() and fp is the
  4407. file which the error string will be placed in.
  4408. \return none No returns.
  4409. \param fp output file for human-readable error string to be written to.
  4410. \param err error code returned by wolfSSL_get_error().
  4411. _Example_
  4412. \code
  4413. int err = 0;
  4414. WOLFSSL* ssl;
  4415. FILE* fp = ...
  4416. ...
  4417. err = wolfSSL_get_error(ssl, 0);
  4418. wolfSSL_ERR_print_errors_fp(fp, err);
  4419. \endcode
  4420. \sa wolfSSL_get_error
  4421. \sa wolfSSL_ERR_error_string
  4422. \sa wolfSSL_ERR_error_string_n
  4423. \sa wolfSSL_load_error_strings
  4424. */
  4425. void wolfSSL_ERR_print_errors_fp(XFILE fp, int err);
  4426. /*!
  4427. \ingroup Debug
  4428. \brief This function uses the provided callback to handle error reporting.
  4429. The callback function is executed for each error line. The string, length,
  4430. and userdata are passed into the callback parameters.
  4431. \return none No returns.
  4432. \param cb the callback function.
  4433. \param u userdata to pass into the callback function.
  4434. _Example_
  4435. \code
  4436. int error_cb(const char *str, size_t len, void *u)
  4437. { fprintf((FILE*)u, "%-*.*s\n", (int)len, (int)len, str); return 0; }
  4438. ...
  4439. FILE* fp = ...
  4440. wolfSSL_ERR_print_errors_cb(error_cb, fp);
  4441. \endcode
  4442. \sa wolfSSL_get_error
  4443. \sa wolfSSL_ERR_error_string
  4444. \sa wolfSSL_ERR_error_string_n
  4445. \sa wolfSSL_load_error_strings
  4446. */
  4447. void wolfSSL_ERR_print_errors_cb (
  4448. int (*cb)(const char *str, size_t len, void *u), void *u);
  4449. /*!
  4450. \brief The function sets the client_psk_cb member of the
  4451. WOLFSSL_CTX structure.
  4452. \return none No returns.
  4453. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  4454. wolfSSL_CTX_new().
  4455. \param cb wc_psk_client_callback is a function pointer that will be
  4456. stored in the WOLFSSL_CTX structure. Return value is the key length on
  4457. success or zero on error.
  4458. unsigned int (*wc_psk_client_callback)
  4459. PSK client callback parameters:
  4460. WOLFSSL* ssl - Pointer to the wolfSSL structure
  4461. const char* hint - A stored string that could be displayed to provide a
  4462. hint to the user.
  4463. char* identity - The ID will be stored here.
  4464. unsigned int id_max_len - Size of the ID buffer.
  4465. unsigned char* key - The key will be stored here.
  4466. unsigned int key_max_len - The max size of the key.
  4467. _Example_
  4468. \code
  4469. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol def );
  4470. static WC_INLINE unsigned int my_psk_client_cb(WOLFSSL* ssl, const char* hint,
  4471. char* identity, unsigned int id_max_len, unsigned char* key,
  4472. Unsigned int key_max_len){
  4473. wolfSSL_CTX_set_psk_client_callback(ctx, my_psk_client_cb);
  4474. \endcode
  4475. \sa wolfSSL_set_psk_client_callback
  4476. \sa wolfSSL_set_psk_server_callback
  4477. \sa wolfSSL_CTX_set_psk_server_callback
  4478. \sa wolfSSL_CTX_set_psk_client_callback
  4479. */
  4480. void wolfSSL_CTX_set_psk_client_callback(WOLFSSL_CTX* ctx,
  4481. wc_psk_client_callback cb);
  4482. /*!
  4483. \brief Sets the PSK client side callback.
  4484. \return none No returns.
  4485. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  4486. \param cb a function pointer to type wc_psk_client_callback. Return value
  4487. is the key length on success or zero on error.
  4488. unsigned int (*wc_psk_client_callback)
  4489. PSK client callback parameters:
  4490. WOLFSSL* ssl - Pointer to the wolfSSL structure
  4491. const char* hint - A stored string that could be displayed to provide a
  4492. hint to the user.
  4493. char* identity - The ID will be stored here.
  4494. unsigned int id_max_len - Size of the ID buffer.
  4495. unsigned char* key - The key will be stored here.
  4496. unsigned int key_max_len - The max size of the key.
  4497. _Example_
  4498. \code
  4499. WOLFSSL* ssl;
  4500. static WC_INLINE unsigned int my_psk_client_cb(WOLFSSL* ssl, const char* hint,
  4501. char* identity, unsigned int id_max_len, unsigned char* key,
  4502. Unsigned int key_max_len){
  4503. if(ssl){
  4504. wolfSSL_set_psk_client_callback(ssl, my_psk_client_cb);
  4505. } else {
  4506. // could not set callback
  4507. }
  4508. \endcode
  4509. \sa wolfSSL_CTX_set_psk_client_callback
  4510. \sa wolfSSL_CTX_set_psk_server_callback
  4511. \sa wolfSSL_set_psk_server_callback
  4512. */
  4513. void wolfSSL_set_psk_client_callback(WOLFSSL* ssl,
  4514. wc_psk_client_callback);
  4515. /*!
  4516. \ingroup CertsKeys
  4517. \brief This function returns the psk identity hint.
  4518. \return pointer a const char pointer to the value that was stored in
  4519. the arrays member of the WOLFSSL structure is returned.
  4520. \return NULL returned if the WOLFSSL or Arrays structures are NULL.
  4521. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  4522. _Example_
  4523. \code
  4524. WOLFSSL* ssl = wolfSSL_new(ctx);
  4525. char* idHint;
  4526. ...
  4527. idHint = wolfSSL_get_psk_identity_hint(ssl);
  4528. if(idHint){
  4529. // The hint was retrieved
  4530. return idHint;
  4531. } else {
  4532. // Hint wasn’t successfully retrieved
  4533. }
  4534. \endcode
  4535. \sa wolfSSL_get_psk_identity
  4536. */
  4537. const char* wolfSSL_get_psk_identity_hint(const WOLFSSL*);
  4538. /*!
  4539. \ingroup CertsKeys
  4540. \brief The function returns a constant pointer to the client_identity
  4541. member of the Arrays structure.
  4542. \return string the string value of the client_identity member of the
  4543. Arrays structure.
  4544. \return NULL if the WOLFSSL structure is NULL or if the Arrays member of
  4545. the WOLFSSL structure is NULL.
  4546. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  4547. _Example_
  4548. \code
  4549. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  4550. WOLFSSL* ssl = wolfSSL_new(ctx);
  4551. const char* pskID;
  4552. ...
  4553. pskID = wolfSSL_get_psk_identity(ssl);
  4554. if(pskID == NULL){
  4555. // There is not a value in pskID
  4556. }
  4557. \endcode
  4558. \sa wolfSSL_get_psk_identity_hint
  4559. \sa wolfSSL_use_psk_identity_hint
  4560. */
  4561. const char* wolfSSL_get_psk_identity(const WOLFSSL*);
  4562. /*!
  4563. \ingroup CertsKeys
  4564. \brief This function stores the hint argument in the server_hint
  4565. member of the WOLFSSL_CTX structure.
  4566. \return SSL_SUCCESS returned for successful execution of the function.
  4567. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  4568. wolfSSL_CTX_new().
  4569. \param hint a constant char pointer that will be copied to the
  4570. WOLFSSL_CTX structure.
  4571. _Example_
  4572. \code
  4573. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  4574. const char* hint;
  4575. int ret;
  4576. ret = wolfSSL_CTX_use_psk_identity_hint(ctx, hint);
  4577. if(ret == SSL_SUCCESS){
  4578. // Function was successful.
  4579. return ret;
  4580. } else {
  4581. // Failure case.
  4582. }
  4583. \endcode
  4584. \sa wolfSSL_use_psk_identity_hint
  4585. */
  4586. int wolfSSL_CTX_use_psk_identity_hint(WOLFSSL_CTX* ctx, const char* hint);
  4587. /*!
  4588. \ingroup CertsKeys
  4589. \brief This function stores the hint argument in the server_hint member
  4590. of the Arrays structure within the WOLFSSL structure.
  4591. \return SSL_SUCCESS returned if the hint was successfully stored in the
  4592. WOLFSSL structure.
  4593. \return SSL_FAILURE returned if the WOLFSSL or Arrays structures are NULL.
  4594. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  4595. \param hint a constant character pointer that holds the hint to be saved
  4596. in memory.
  4597. _Example_
  4598. \code
  4599. WOLFSSL* ssl = wolfSSL_new(ctx);
  4600. const char* hint;
  4601. ...
  4602. if(wolfSSL_use_psk_identity_hint(ssl, hint) != SSL_SUCCESS){
  4603. // Handle failure case.
  4604. }
  4605. \endcode
  4606. \sa wolfSSL_CTX_use_psk_identity_hint
  4607. */
  4608. int wolfSSL_use_psk_identity_hint(WOLFSSL* ssl, const char* hint);
  4609. /*!
  4610. \brief This function sets the psk callback for the server side in
  4611. the WOLFSSL_CTX structure.
  4612. \return none No returns.
  4613. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  4614. \param cb a function pointer for the callback and will be stored in
  4615. the WOLFSSL_CTX structure. Return value is the key length on success or
  4616. zero on error.
  4617. unsigned int (*wc_psk_server_callback)
  4618. PSK server callback parameters
  4619. WOLFSSL* ssl - Pointer to the wolfSSL structure
  4620. char* identity - The ID will be stored here.
  4621. unsigned char* key - The key will be stored here.
  4622. unsigned int key_max_len - The max size of the key.
  4623. _Example_
  4624. \code
  4625. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  4626. WOLFSSL* ssl = wolfSSL_new(ctx);
  4627. static unsigned int my_psk_server_cb(WOLFSSL* ssl, const char* identity,
  4628. unsigned char* key, unsigned int key_max_len)
  4629. {
  4630. // Function body.
  4631. }
  4632. if(ctx != NULL){
  4633. wolfSSL_CTX_set_psk_server_callback(ctx, my_psk_server_cb);
  4634. } else {
  4635. // The CTX object was not properly initialized.
  4636. }
  4637. \endcode
  4638. \sa wc_psk_server_callback
  4639. \sa wolfSSL_set_psk_client_callback
  4640. \sa wolfSSL_set_psk_server_callback
  4641. \sa wolfSSL_CTX_set_psk_client_callback
  4642. */
  4643. void wolfSSL_CTX_set_psk_server_callback(WOLFSSL_CTX* ctx,
  4644. wc_psk_server_callback cb);
  4645. /*!
  4646. \brief Sets the psk callback for the server side by setting the
  4647. WOLFSSL structure options members.
  4648. \return none No returns.
  4649. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  4650. \param cb a function pointer for the callback and will be stored in
  4651. the WOLFSSL structure. Return value is the key length on success or zero
  4652. on error.
  4653. unsigned int (*wc_psk_server_callback)
  4654. PSK server callback parameters
  4655. WOLFSSL* ssl - Pointer to the wolfSSL structure
  4656. char* identity - The ID will be stored here.
  4657. unsigned char* key - The key will be stored here.
  4658. unsigned int key_max_len - The max size of the key.
  4659. _Example_
  4660. \code
  4661. WOLFSSL_CTX* ctx;
  4662. WOLFSSL* ssl;
  4663. static unsigned int my_psk_server_cb(WOLFSSL* ssl, const char* identity,
  4664. unsigned char* key, unsigned int key_max_len)
  4665. {
  4666. // Function body.
  4667. }
  4668. if(ssl != NULL && cb != NULL){
  4669. wolfSSL_set_psk_server_callback(ssl, my_psk_server_cb);
  4670. }
  4671. \endcode
  4672. \sa wolfSSL_set_psk_client_callback
  4673. \sa wolfSSL_CTX_set_psk_server_callback
  4674. \sa wolfSSL_CTX_set_psk_client_callback
  4675. \sa wolfSSL_get_psk_identity_hint
  4676. \sa wc_psk_server_callback
  4677. \sa InitSuites
  4678. */
  4679. void wolfSSL_set_psk_server_callback(WOLFSSL* ssl,
  4680. wc_psk_server_callback cb);
  4681. /*!
  4682. \brief Sets a PSK user context in the WOLFSSL structure options member.
  4683. \return WOLFSSL_SUCCESS or WOLFSSL_FAILURE
  4684. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  4685. \param psk_ctx void pointer to user PSK context
  4686. \sa wolfSSL_get_psk_callback_ctx
  4687. \sa wolfSSL_CTX_set_psk_callback_ctx
  4688. \sa wolfSSL_CTX_get_psk_callback_ctx
  4689. */
  4690. int wolfSSL_set_psk_callback_ctx(WOLFSSL* ssl, void* psk_ctx);
  4691. /*!
  4692. \brief Sets a PSK user context in the WOLFSSL_CTX structure.
  4693. \return WOLFSSL_SUCCESS or WOLFSSL_FAILURE
  4694. \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
  4695. \param psk_ctx void pointer to user PSK context
  4696. \sa wolfSSL_set_psk_callback_ctx
  4697. \sa wolfSSL_get_psk_callback_ctx
  4698. \sa wolfSSL_CTX_get_psk_callback_ctx
  4699. */
  4700. int wolfSSL_CTX_set_psk_callback_ctx(WOLFSSL_CTX* ctx, void* psk_ctx);
  4701. /*!
  4702. \brief Get a PSK user context in the WOLFSSL structure options member.
  4703. \return void pointer to user PSK context
  4704. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  4705. \sa wolfSSL_set_psk_callback_ctx
  4706. \sa wolfSSL_CTX_set_psk_callback_ctx
  4707. \sa wolfSSL_CTX_get_psk_callback_ctx
  4708. */
  4709. void* wolfSSL_get_psk_callback_ctx(WOLFSSL* ssl);
  4710. /*!
  4711. \brief Get a PSK user context in the WOLFSSL_CTX structure.
  4712. \return void pointer to user PSK context
  4713. \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
  4714. \sa wolfSSL_CTX_set_psk_callback_ctx
  4715. \sa wolfSSL_set_psk_callback_ctx
  4716. \sa wolfSSL_get_psk_callback_ctx
  4717. */
  4718. void* wolfSSL_CTX_get_psk_callback_ctx(WOLFSSL_CTX* ctx);
  4719. /*!
  4720. \ingroup Setup
  4721. \brief This function enables the havAnon member of the CTX structure if
  4722. HAVE_ANON is defined during compilation.
  4723. \return SSL_SUCCESS returned if the function executed successfully and the
  4724. haveAnnon member of the CTX is set to 1.
  4725. \return SSL_FAILURE returned if the CTX structure was NULL.
  4726. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  4727. wolfSSL_CTX_new().
  4728. _Example_
  4729. \code
  4730. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  4731. WOLFSSL* ssl = wolfSSL_new(ctx);
  4732. ...
  4733. #ifdef HAVE_ANON
  4734. if(cipherList == NULL){
  4735. wolfSSL_CTX_allow_anon_cipher(ctx);
  4736. if(wolfSSL_CTX_set_cipher_list(ctx, “ADH_AES128_SHA”) != SSL_SUCCESS){
  4737. // failure case
  4738. }
  4739. }
  4740. #endif
  4741. \endcode
  4742. \sa none
  4743. */
  4744. int wolfSSL_CTX_allow_anon_cipher(WOLFSSL_CTX*);
  4745. /*!
  4746. \ingroup Setup
  4747. \brief The wolfSSLv23_server_method() function is used to indicate
  4748. that the application is a server and will support clients connecting
  4749. with protocol version from SSL 3.0 - TLS 1.3. This function allocates
  4750. memory for and initializes a new WOLFSSL_METHOD structure to be used when
  4751. creating the SSL/TLS context with wolfSSL_CTX_new().
  4752. \return pointer If successful, the call will return a pointer to the newly
  4753. created WOLFSSL_METHOD structure.
  4754. \return Failure If memory allocation fails when calling XMALLOC, the
  4755. failure value of the underlying malloc() implementation will be returned
  4756. (typically NULL with errno will be set to ENOMEM).
  4757. \param none No parameters
  4758. _Example_
  4759. \code
  4760. WOLFSSL_METHOD* method;
  4761. WOLFSSL_CTX* ctx;
  4762. method = wolfSSLv23_server_method();
  4763. if (method == NULL) {
  4764. // unable to get method
  4765. }
  4766. ctx = wolfSSL_CTX_new(method);
  4767. ...
  4768. \endcode
  4769. \sa wolfSSLv3_server_method
  4770. \sa wolfTLSv1_server_method
  4771. \sa wolfTLSv1_1_server_method
  4772. \sa wolfTLSv1_2_server_method
  4773. \sa wolfTLSv1_3_server_method
  4774. \sa wolfDTLSv1_server_method
  4775. \sa wolfSSL_CTX_new
  4776. */
  4777. WOLFSSL_METHOD *wolfSSLv23_server_method(void);
  4778. /*!
  4779. \ingroup Setup
  4780. \brief This is used to get the internal error state of the WOLFSSL structure.
  4781. \return wolfssl_error returns ssl error state, usually a negative
  4782. \return BAD_FUNC_ARG if ssl is NULL.
  4783. \return ssl WOLFSSL structure to get state from.
  4784. _Example_
  4785. \code
  4786. WOLFSSL* ssl;
  4787. int ret;
  4788. // create ssl object
  4789. ret = wolfSSL_state(ssl);
  4790. // check ret value
  4791. \endcode
  4792. \sa wolfSSL_new
  4793. \sa wolfSSL_free
  4794. */
  4795. int wolfSSL_state(WOLFSSL* ssl);
  4796. /*!
  4797. \ingroup CertsKeys
  4798. \brief This function gets the peer’s certificate.
  4799. \return pointer a pointer to the peerCert member of the WOLFSSL_X509
  4800. structure if it exists.
  4801. \return 0 returned if the peer certificate issuer size is not defined.
  4802. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  4803. _Example_
  4804. \code
  4805. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  4806. WOLFSSL* ssl = wolfSSL_new(ctx);
  4807. ...
  4808. WOLFSSL_X509* peerCert = wolfSSL_get_peer_certificate(ssl);
  4809. if(peerCert){
  4810. // You have a pointer peerCert to the peer certification
  4811. }
  4812. \endcode
  4813. \sa wolfSSL_X509_get_issuer_name
  4814. \sa wolfSSL_X509_get_subject_name
  4815. \sa wolfSSL_X509_get_isCA
  4816. */
  4817. WOLFSSL_X509* wolfSSL_get_peer_certificate(WOLFSSL* ssl);
  4818. /*!
  4819. \ingroup Debug
  4820. \brief This function is similar to calling wolfSSL_get_error() and
  4821. getting SSL_ERROR_WANT_READ in return. If the underlying error state
  4822. is SSL_ERROR_WANT_READ, this function will return 1, otherwise, 0.
  4823. \return 1 wolfSSL_get_error() would return SSL_ERROR_WANT_READ, the
  4824. underlying I/O has data available for reading.
  4825. \return 0 There is no SSL_ERROR_WANT_READ error state.
  4826. \param ssl pointer to the SSL session, created with wolfSSL_new().
  4827. _Example_
  4828. \code
  4829. int ret;
  4830. WOLFSSL* ssl = 0;
  4831. ...
  4832. ret = wolfSSL_want_read(ssl);
  4833. if (ret == 1) {
  4834. // underlying I/O has data available for reading (SSL_ERROR_WANT_READ)
  4835. }
  4836. \endcode
  4837. \sa wolfSSL_want_write
  4838. \sa wolfSSL_get_error
  4839. */
  4840. int wolfSSL_want_read(WOLFSSL*);
  4841. /*!
  4842. \ingroup Debug
  4843. \brief This function is similar to calling wolfSSL_get_error() and getting
  4844. SSL_ERROR_WANT_WRITE in return. If the underlying error state is
  4845. SSL_ERROR_WANT_WRITE, this function will return 1, otherwise, 0.
  4846. \return 1 wolfSSL_get_error() would return SSL_ERROR_WANT_WRITE, the
  4847. underlying I/O needs data to be written in order for progress to be
  4848. made in the underlying SSL connection.
  4849. \return 0 There is no SSL_ERROR_WANT_WRITE error state.
  4850. \param ssl pointer to the SSL session, created with wolfSSL_new().
  4851. _Example_
  4852. \code
  4853. int ret;
  4854. WOLFSSL* ssl = 0;
  4855. ...
  4856. ret = wolfSSL_want_write(ssl);
  4857. if (ret == 1) {
  4858. // underlying I/O needs data to be written (SSL_ERROR_WANT_WRITE)
  4859. }
  4860. \endcode
  4861. \sa wolfSSL_want_read
  4862. \sa wolfSSL_get_error
  4863. */
  4864. int wolfSSL_want_write(WOLFSSL*);
  4865. /*!
  4866. \ingroup Setup
  4867. \brief wolfSSL by default checks the peer certificate for a valid date
  4868. range and a verified signature. Calling this function before
  4869. wolfSSL_connect() or wolfSSL_accept() will add a domain name check to
  4870. the list of checks to perform. dn holds the domain name to check
  4871. against the peer certificate when it’s received.
  4872. \return SSL_SUCCESS upon success.
  4873. \return SSL_FAILURE will be returned if a memory error was encountered.
  4874. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  4875. \param dn domain name to check against the peer certificate when received.
  4876. _Example_
  4877. \code
  4878. int ret = 0;
  4879. WOLFSSL* ssl;
  4880. char* domain = (char*) “www.yassl.com”;
  4881. ...
  4882. ret = wolfSSL_check_domain_name(ssl, domain);
  4883. if (ret != SSL_SUCCESS) {
  4884. // failed to enable domain name check
  4885. }
  4886. \endcode
  4887. \sa none
  4888. */
  4889. int wolfSSL_check_domain_name(WOLFSSL* ssl, const char* dn);
  4890. /*!
  4891. \ingroup TLS
  4892. \brief Initializes the wolfSSL library for use. Must be called once per
  4893. application and before any other call to the library.
  4894. \return SSL_SUCCESS If successful the call will return.
  4895. \return BAD_MUTEX_E is an error that may be returned.
  4896. \return WC_INIT_E wolfCrypt initialization error returned.
  4897. _Example_
  4898. \code
  4899. int ret = 0;
  4900. ret = wolfSSL_Init();
  4901. if (ret != SSL_SUCCESS) {
  4902. failed to initialize wolfSSL library
  4903. }
  4904. \endcode
  4905. \sa wolfSSL_Cleanup
  4906. */
  4907. int wolfSSL_Init(void);
  4908. /*!
  4909. \ingroup TLS
  4910. \brief Un-initializes the wolfSSL library from further use. Doesn’t have
  4911. to be called, though it will free any resources used by the library.
  4912. \return SSL_SUCCESS return no errors.
  4913. \return BAD_MUTEX_E a mutex error return.]
  4914. _Example_
  4915. \code
  4916. wolfSSL_Cleanup();
  4917. \endcode
  4918. \sa wolfSSL_Init
  4919. */
  4920. int wolfSSL_Cleanup(void);
  4921. /*!
  4922. \ingroup IO
  4923. \brief This function returns the current library version.
  4924. \return LIBWOLFSSL_VERSION_STRING a const char pointer defining the
  4925. version.
  4926. \param none No parameters.
  4927. _Example_
  4928. \code
  4929. char version[MAXSIZE];
  4930. version = wolfSSL_KeepArrays();
  4931. if(version != ExpectedVersion){
  4932. // Handle the mismatch case
  4933. }
  4934. \endcode
  4935. \sa word32_wolfSSL_lib_version_hex
  4936. */
  4937. const char* wolfSSL_lib_version(void);
  4938. /*!
  4939. \ingroup IO
  4940. \brief This function returns the current library version in hexadecimal
  4941. notation.
  4942. \return LILBWOLFSSL_VERSION_HEX returns the hexadecimal version defined in
  4943. wolfssl/version.h.
  4944. \param none No parameters.
  4945. _Example_
  4946. \code
  4947. word32 libV;
  4948. libV = wolfSSL_lib_version_hex();
  4949. if(libV != EXPECTED_HEX){
  4950. // How to handle an unexpected value
  4951. } else {
  4952. // The expected result for libV
  4953. }
  4954. \endcode
  4955. \sa wolfSSL_lib_version
  4956. */
  4957. word32 wolfSSL_lib_version_hex(void);
  4958. /*!
  4959. \ingroup IO
  4960. \brief Performs the actual connect or accept based on the side of the SSL
  4961. method. If called from the client side then an wolfSSL_connect() is done
  4962. while a wolfSSL_accept() is performed if called from the server side.
  4963. \return SSL_SUCCESS will be returned if successful. (Note, older versions
  4964. will return 0.)
  4965. \return SSL_FATAL_ERROR will be returned if the underlying call resulted
  4966. in an error. Use wolfSSL_get_error() to get a specific error code.
  4967. \param ssl pointer to the SSL session, created with wolfSSL_new().
  4968. _Example_
  4969. \code
  4970. int ret = SSL_FATAL_ERROR;
  4971. WOLFSSL* ssl = 0;
  4972. ...
  4973. ret = wolfSSL_negotiate(ssl);
  4974. if (ret == SSL_FATAL_ERROR) {
  4975. // SSL establishment failed
  4976. int error_code = wolfSSL_get_error(ssl);
  4977. ...
  4978. }
  4979. ...
  4980. \endcode
  4981. \sa SSL_connect
  4982. \sa SSL_accept
  4983. */
  4984. int wolfSSL_negotiate(WOLFSSL* ssl);
  4985. /*!
  4986. \ingroup Setup
  4987. \brief Turns on the ability to use compression for the SSL connection.
  4988. Both sides must have compression turned on otherwise compression will not be
  4989. used. The zlib library performs the actual data compression. To compile
  4990. into the library use --with-libz for the configure system and define
  4991. HAVE_LIBZ otherwise. Keep in mind that while compressing data before
  4992. sending decreases the actual size of the messages being sent and received,
  4993. the amount of data saved by compression usually takes longer in time to
  4994. analyze than it does to send it raw on all but the slowest of networks.
  4995. \return SSL_SUCCESS upon success.
  4996. \return NOT_COMPILED_IN will be returned if compression support wasn’t
  4997. built into the library.
  4998. \param ssl pointer to the SSL session, created with wolfSSL_new().
  4999. _Example_
  5000. \code
  5001. int ret = 0;
  5002. WOLFSSL* ssl = 0;
  5003. ...
  5004. ret = wolfSSL_set_compression(ssl);
  5005. if (ret == SSL_SUCCESS) {
  5006. // successfully enabled compression for SSL session
  5007. }
  5008. \endcode
  5009. \sa none
  5010. */
  5011. int wolfSSL_set_compression(WOLFSSL* ssl);
  5012. /*!
  5013. \ingroup Setup
  5014. \brief This function sets the SSL session timeout value in seconds.
  5015. \return SSL_SUCCESS will be returned upon successfully setting the session.
  5016. \return BAD_FUNC_ARG will be returned if ssl is NULL.
  5017. \param ssl pointer to the SSL object, created with wolfSSL_new().
  5018. \param to value, in seconds, used to set the SSL session timeout.
  5019. _Example_
  5020. \code
  5021. int ret = 0;
  5022. WOLFSSL* ssl = 0;
  5023. ...
  5024. ret = wolfSSL_set_timeout(ssl, 500);
  5025. if (ret != SSL_SUCCESS) {
  5026. // failed to set session timeout value
  5027. }
  5028. ...
  5029. \endcode
  5030. \sa wolfSSL_get1_session
  5031. \sa wolfSSL_set_session
  5032. */
  5033. int wolfSSL_set_timeout(WOLFSSL* ssl, unsigned int to);
  5034. /*!
  5035. \ingroup Setup
  5036. \brief This function sets the timeout value for SSL sessions, in seconds,
  5037. for the specified SSL context.
  5038. \return the previous timeout value, if WOLFSSL_ERROR_CODE_OPENSSL is
  5039. \return defined on success. If not defined, SSL_SUCCESS will be returned.
  5040. \return BAD_FUNC_ARG will be returned when the input context (ctx) is null.
  5041. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  5042. \param to session timeout value in seconds.
  5043. _Example_
  5044. \code
  5045. WOLFSSL_CTX* ctx = 0;
  5046. ...
  5047. ret = wolfSSL_CTX_set_timeout(ctx, 500);
  5048. if (ret != SSL_SUCCESS) {
  5049. // failed to set session timeout value
  5050. }
  5051. \endcode
  5052. \sa wolfSSL_flush_sessions
  5053. \sa wolfSSL_get1_session
  5054. \sa wolfSSL_set_session
  5055. \sa wolfSSL_get_sessionID
  5056. \sa wolfSSL_CTX_set_session_cache_mode
  5057. */
  5058. int wolfSSL_CTX_set_timeout(WOLFSSL_CTX* ctx, unsigned int to);
  5059. /*!
  5060. \ingroup openSSL
  5061. \brief Retrieves the peer’s certificate chain.
  5062. \return chain If successful the call will return the peer’s
  5063. certificate chain.
  5064. \return 0 will be returned if an invalid WOLFSSL pointer is passed to the
  5065. function.
  5066. \param ssl pointer to a valid WOLFSSL structure.
  5067. _Example_
  5068. \code
  5069. none
  5070. \endcode
  5071. \sa wolfSSL_get_chain_count
  5072. \sa wolfSSL_get_chain_length
  5073. \sa wolfSSL_get_chain_cert
  5074. \sa wolfSSL_get_chain_cert_pem
  5075. */
  5076. WOLFSSL_X509_CHAIN* wolfSSL_get_peer_chain(WOLFSSL* ssl);
  5077. /*!
  5078. \ingroup openSSL
  5079. \brief Retrieve's the peers certificate chain count.
  5080. \return Success If successful the call will return the peer’s certificate
  5081. chain count.
  5082. \return 0 will be returned if an invalid chain pointer is passed to
  5083. the function.
  5084. \param chain pointer to a valid WOLFSSL_X509_CHAIN structure.
  5085. _Example_
  5086. \code
  5087. none
  5088. \endcode
  5089. \sa wolfSSL_get_peer_chain
  5090. \sa wolfSSL_get_chain_length
  5091. \sa wolfSSL_get_chain_cert
  5092. \sa wolfSSL_get_chain_cert_pem
  5093. */
  5094. int wolfSSL_get_chain_count(WOLFSSL_X509_CHAIN* chain);
  5095. /*!
  5096. \ingroup openSSL
  5097. \brief Retrieves the peer’s ASN1.DER certificate length in bytes
  5098. at index (idx).
  5099. \return Success If successful the call will return the peer’s
  5100. certificate length in bytes by index.
  5101. \return 0 will be returned if an invalid chain pointer is passed
  5102. to the function.
  5103. \param chain pointer to a valid WOLFSSL_X509_CHAIN structure.
  5104. \param idx index to start of chain.
  5105. _Example_
  5106. \code
  5107. none
  5108. \endcode
  5109. \sa wolfSSL_get_peer_chain
  5110. \sa wolfSSL_get_chain_count
  5111. \sa wolfSSL_get_chain_cert
  5112. \sa wolfSSL_get_chain_cert_pem
  5113. */
  5114. int wolfSSL_get_chain_length(WOLFSSL_X509_CHAIN* chain, int idx);
  5115. /*!
  5116. \ingroup openSSL
  5117. \brief Retrieves the peer’s ASN1.DER certificate at index (idx).
  5118. \return Success If successful the call will return the peer’s
  5119. certificate by index.
  5120. \return 0 will be returned if an invalid chain pointer is passed
  5121. to the function.
  5122. \param chain pointer to a valid WOLFSSL_X509_CHAIN structure.
  5123. \param idx index to start of chain.
  5124. _Example_
  5125. \code
  5126. none
  5127. \endcode
  5128. \sa wolfSSL_get_peer_chain
  5129. \sa wolfSSL_get_chain_count
  5130. \sa wolfSSL_get_chain_length
  5131. \sa wolfSSL_get_chain_cert_pem
  5132. */
  5133. unsigned char* wolfSSL_get_chain_cert(WOLFSSL_X509_CHAIN* chain, int idx);
  5134. /*!
  5135. \ingroup CertsKeys
  5136. \brief This function gets the peer’s wolfSSL_X509_certificate at
  5137. index (idx) from the chain of certificates.
  5138. \return pointer returns a pointer to a WOLFSSL_X509 structure.
  5139. \param chain a pointer to the WOLFSSL_X509_CHAIN used for no dynamic
  5140. memory SESSION_CACHE.
  5141. \param idx the index of the WOLFSSL_X509 certificate.
  5142. Note that it is the user's responsibility to free the returned memory
  5143. by calling wolfSSL_FreeX509().
  5144. _Example_
  5145. \code
  5146. WOLFSSL_X509_CHAIN* chain = &session->chain;
  5147. int idx = 999; // set idx
  5148. ...
  5149. WOLFSSL_X509_CHAIN ptr;
  5150. prt = wolfSSL_get_chain_X509(chain, idx);
  5151. if(ptr != NULL){
  5152. // ptr contains the cert at the index specified
  5153. wolfSSL_FreeX509(ptr);
  5154. } else {
  5155. // ptr is NULL
  5156. }
  5157. \endcode
  5158. \sa InitDecodedCert
  5159. \sa ParseCertRelative
  5160. \sa CopyDecodedToX509
  5161. */
  5162. WOLFSSL_X509* wolfSSL_get_chain_X509(WOLFSSL_X509_CHAIN* chain, int idx);
  5163. /*!
  5164. \ingroup openSSL
  5165. \brief Retrieves the peer’s PEM certificate at index (idx).
  5166. \return Success If successful the call will return the peer’s
  5167. certificate by index.
  5168. \return 0 will be returned if an invalid chain pointer is passed to
  5169. the function.
  5170. \param chain pointer to a valid WOLFSSL_X509_CHAIN structure.
  5171. \param idx indexto start of chain.
  5172. _Example_
  5173. \code
  5174. none
  5175. \endcode
  5176. \sa wolfSSL_get_peer_chain
  5177. \sa wolfSSL_get_chain_count
  5178. \sa wolfSSL_get_chain_length
  5179. \sa wolfSSL_get_chain_cert
  5180. */
  5181. int wolfSSL_get_chain_cert_pem(WOLFSSL_X509_CHAIN* chain, int idx,
  5182. unsigned char* buf, int inLen, int* outLen);
  5183. /*!
  5184. \ingroup openSSL
  5185. \brief Retrieves the session’s ID. The session ID is always 32 bytes long.
  5186. \return id The session ID.
  5187. \param session pointer to a valid wolfssl session.
  5188. _Example_
  5189. \code
  5190. none
  5191. \endcode
  5192. \sa SSL_get_session
  5193. */
  5194. const unsigned char* wolfSSL_get_sessionID(const WOLFSSL_SESSION* s);
  5195. /*!
  5196. \ingroup openSSL
  5197. \brief Retrieves the peer’s certificate serial number. The serial
  5198. number buffer (in) should be at least 32 bytes long and be provided
  5199. as the *inOutSz argument as input. After calling the function *inOutSz
  5200. will hold the actual length in bytes written to the in buffer.
  5201. \return SSL_SUCCESS upon success.
  5202. \return BAD_FUNC_ARG will be returned if a bad function argument
  5203. was encountered.
  5204. \param in The serial number buffer and should be at least 32 bytes long
  5205. \param inOutSz will hold the actual length in bytes written to the
  5206. in buffer.
  5207. _Example_
  5208. \code
  5209. none
  5210. \endcode
  5211. \sa SSL_get_peer_certificate
  5212. */
  5213. int wolfSSL_X509_get_serial_number(WOLFSSL_X509* x509, unsigned char* in,
  5214. int* inOutSz);
  5215. /*!
  5216. \ingroup CertsKeys
  5217. \brief Returns the common name of the subject from the certificate.
  5218. \return NULL returned if the x509 structure is null
  5219. \return string a string representation of the subject's common
  5220. name is returned upon success
  5221. \param x509 a pointer to a WOLFSSL_X509 structure containing
  5222. certificate information.
  5223. _Example_
  5224. \code
  5225. WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
  5226. DYNAMIC_TYPE_X509);
  5227. ...
  5228. int x509Cn = wolfSSL_X509_get_subjectCN(x509);
  5229. if(x509Cn == NULL){
  5230. // Deal with NULL case
  5231. } else {
  5232. // x509Cn contains the common name
  5233. }
  5234. \endcode
  5235. \sa wolfSSL_X509_Name_get_entry
  5236. \sa wolfSSL_X509_get_next_altname
  5237. \sa wolfSSL_X509_get_issuer_name
  5238. \sa wolfSSL_X509_get_subject_name
  5239. */
  5240. char* wolfSSL_X509_get_subjectCN(WOLFSSL_X509*);
  5241. /*!
  5242. \ingroup CertsKeys
  5243. \brief This function gets the DER encoded certificate in the
  5244. WOLFSSL_X509 struct.
  5245. \return buffer This function returns the DerBuffer structure’s
  5246. buffer member, which is of type byte.
  5247. \return NULL returned if the x509 or outSz parameter is NULL.
  5248. \param x509 a pointer to a WOLFSSL_X509 structure containing
  5249. certificate information.
  5250. \param outSz length of the derBuffer member of the WOLFSSL_X509 struct.
  5251. _Example_
  5252. \code
  5253. WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
  5254. DYNAMIC_TYPE_X509);
  5255. int* outSz; // initialize
  5256. ...
  5257. byte* x509Der = wolfSSL_X509_get_der(x509, outSz);
  5258. if(x509Der == NULL){
  5259. // Failure case one of the parameters was NULL
  5260. }
  5261. \endcode
  5262. \sa wolfSSL_X509_version
  5263. \sa wolfSSL_X509_Name_get_entry
  5264. \sa wolfSSL_X509_get_next_altname
  5265. \sa wolfSSL_X509_get_issuer_name
  5266. \sa wolfSSL_X509_get_subject_name
  5267. */
  5268. const unsigned char* wolfSSL_X509_get_der(WOLFSSL_X509* x509, int* outSz);
  5269. /*!
  5270. \ingroup CertsKeys
  5271. \brief This function checks to see if x509 is NULL and if it’s not,
  5272. it returns the notAfter member of the x509 struct.
  5273. \return pointer to struct with ASN1_TIME to the notAfter
  5274. member of the x509 struct.
  5275. \return NULL returned if the x509 object is NULL.
  5276. \param x509 a pointer to the WOLFSSL_X509 struct.
  5277. _Example_
  5278. \code
  5279. WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL,
  5280. DYNAMIC_TYPE_X509) ;
  5281. ...
  5282. const WOLFSSL_ASN1_TIME* notAfter = wolfSSL_X509_get_notAfter(x509);
  5283. if(notAfter == NULL){
  5284. // Failure case, the x509 object is null.
  5285. }
  5286. \endcode
  5287. \sa wolfSSL_X509_get_notBefore
  5288. */
  5289. WOLFSSL_ASN1_TIME* wolfSSL_X509_get_notAfter(WOLFSSL_X509*);
  5290. /*!
  5291. \ingroup CertsKeys
  5292. \brief This function retrieves the version of the X509 certificate.
  5293. \return 0 returned if the x509 structure is NULL.
  5294. \return version the version stored in the x509 structure will be returned.
  5295. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  5296. _Example_
  5297. \code
  5298. WOLFSSL_X509* x509;
  5299. int version;
  5300. ...
  5301. version = wolfSSL_X509_version(x509);
  5302. if(!version){
  5303. // The function returned 0, failure case.
  5304. }
  5305. \endcode
  5306. \sa wolfSSL_X509_get_subject_name
  5307. \sa wolfSSL_X509_get_issuer_name
  5308. \sa wolfSSL_X509_get_isCA
  5309. \sa wolfSSL_get_peer_certificate
  5310. */
  5311. int wolfSSL_X509_version(WOLFSSL_X509*);
  5312. /*!
  5313. \ingroup CertsKeys
  5314. \brief If NO_STDIO_FILESYSTEM is defined this function will allocate
  5315. heap memory, initialize a WOLFSSL_X509 structure and return a pointer to it.
  5316. \return *WOLFSSL_X509 WOLFSSL_X509 structure pointer is returned if
  5317. the function executes successfully.
  5318. \return NULL if the call to XFTELL macro returns a negative value.
  5319. \param x509 a pointer to a WOLFSSL_X509 pointer.
  5320. \param file a defined type that is a pointer to a FILE.
  5321. _Example_
  5322. \code
  5323. WOLFSSL_X509* x509a = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
  5324. DYNAMIC_TYPE_X509);
  5325. WOLFSSL_X509** x509 = x509a;
  5326. XFILE file; (mapped to struct fs_file*)
  5327. ...
  5328. WOLFSSL_X509* newX509 = wolfSSL_X509_d2i_fp(x509, file);
  5329. if(newX509 == NULL){
  5330. // The function returned NULL
  5331. }
  5332. \endcode
  5333. \sa wolfSSL_X509_d2i
  5334. \sa XFTELL
  5335. \sa XREWIND
  5336. \sa XFSEEK
  5337. */
  5338. WOLFSSL_X509*
  5339. wolfSSL_X509_d2i_fp(WOLFSSL_X509** x509, FILE* file);
  5340. /*!
  5341. \ingroup CertsKeys
  5342. \brief The function loads the x509 certificate into memory.
  5343. \return pointer a successful execution returns pointer to a
  5344. WOLFSSL_X509 structure.
  5345. \return NULL returned if the certificate was not able to be written.
  5346. \param fname the certificate file to be loaded.
  5347. \param format the format of the certificate.
  5348. _Example_
  5349. \code
  5350. #define cliCert “certs/client-cert.pem”
  5351. X509* x509;
  5352. x509 = wolfSSL_X509_load_certificate_file(cliCert, SSL_FILETYPE_PEM);
  5353. AssertNotNull(x509);
  5354. \endcode
  5355. \sa InitDecodedCert
  5356. \sa PemToDer
  5357. \sa wolfSSL_get_certificate
  5358. \sa AssertNotNull
  5359. */
  5360. WOLFSSL_X509*
  5361. wolfSSL_X509_load_certificate_file(const char* fname, int format);
  5362. /*!
  5363. \ingroup CertsKeys
  5364. \brief This function copies the device type from the x509 structure
  5365. to the buffer.
  5366. \return pointer returns a byte pointer holding the device type from
  5367. the x509 structure.
  5368. \return NULL returned if the buffer size is NULL.
  5369. \param x509 pointer to a WOLFSSL_X509 structure, created with
  5370. WOLFSSL_X509_new().
  5371. \param in a pointer to a byte type that will hold the device type
  5372. (the buffer).
  5373. \param inOutSz the minimum of either the parameter inOutSz or the
  5374. deviceTypeSz member of the x509 structure.
  5375. _Example_
  5376. \code
  5377. WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL,
  5378. DYNAMIC_TYPE_X509);
  5379. byte* in;
  5380. int* inOutSz;
  5381. ...
  5382. byte* deviceType = wolfSSL_X509_get_device_type(x509, in, inOutSz);
  5383. if(!deviceType){
  5384. // Failure case, NULL was returned.
  5385. }
  5386. \endcode
  5387. \sa wolfSSL_X509_get_hw_type
  5388. \sa wolfSSL_X509_get_hw_serial_number
  5389. \sa wolfSSL_X509_d2i
  5390. */
  5391. unsigned char*
  5392. wolfSSL_X509_get_device_type(WOLFSSL_X509* x509, unsigned char* in,
  5393. int* inOutSz);
  5394. /*!
  5395. \ingroup CertsKeys
  5396. \brief The function copies the hwType member of the WOLFSSL_X509
  5397. structure to the buffer.
  5398. \return byte The function returns a byte type of the data previously held
  5399. in the hwType member of the WOLFSSL_X509 structure.
  5400. \return NULL returned if inOutSz is NULL.
  5401. \param x509 a pointer to a WOLFSSL_X509 structure containing certificate
  5402. information.
  5403. \param in pointer to type byte that represents the buffer.
  5404. \param inOutSz pointer to type int that represents the size of the buffer.
  5405. _Example_
  5406. \code
  5407. WOLFSSL_X509* x509; // X509 certificate
  5408. byte* in; // initialize the buffer
  5409. int* inOutSz; // holds the size of the buffer
  5410. ...
  5411. byte* hwType = wolfSSL_X509_get_hw_type(x509, in, inOutSz);
  5412. if(hwType == NULL){
  5413. // Failure case function returned NULL.
  5414. }
  5415. \endcode
  5416. \sa wolfSSL_X509_get_hw_serial_number
  5417. \sa wolfSSL_X509_get_device_type
  5418. */
  5419. unsigned char*
  5420. wolfSSL_X509_get_hw_type(WOLFSSL_X509* x509, unsigned char* in,
  5421. int* inOutSz);
  5422. /*!
  5423. \ingroup CertsKeys
  5424. \brief This function returns the hwSerialNum member of the x509 object.
  5425. \return pointer the function returns a byte pointer to the in buffer that
  5426. will contain the serial number loaded from the x509 object.
  5427. \param x509 pointer to a WOLFSSL_X509 structure containing certificate
  5428. information.
  5429. \param in a pointer to the buffer that will be copied to.
  5430. \param inOutSz a pointer to the size of the buffer.
  5431. _Example_
  5432. \code
  5433. char* serial;
  5434. byte* in;
  5435. int* inOutSz;
  5436. WOLFSSL_X509 x509;
  5437. ...
  5438. serial = wolfSSL_X509_get_hw_serial_number(x509, in, inOutSz);
  5439. if(serial == NULL || serial <= 0){
  5440. // Failure case
  5441. }
  5442. \endcode
  5443. \sa wolfSSL_X509_get_subject_name
  5444. \sa wolfSSL_X509_get_issuer_name
  5445. \sa wolfSSL_X509_get_isCA
  5446. \sa wolfSSL_get_peer_certificate
  5447. \sa wolfSSL_X509_version
  5448. */
  5449. unsigned char*
  5450. wolfSSL_X509_get_hw_serial_number(WOLFSSL_X509* x509,
  5451. unsigned char* in, int* inOutSz);
  5452. /*!
  5453. \ingroup IO
  5454. \brief This function is called on the client side and initiates an
  5455. SSL/TLS handshake with a server only long enough to get the peer’s
  5456. certificate chain. When this function is called, the underlying
  5457. communication channel has already been set up. wolfSSL_connect_cert()
  5458. works with both blocking and non-blocking I/O. When the underlying I/O
  5459. is non-blocking, wolfSSL_connect_cert() will return when the underlying
  5460. I/O could not satisfy the needs of wolfSSL_connect_cert() to continue the
  5461. handshake. In this case, a call to wolfSSL_get_error() will yield either
  5462. SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then
  5463. repeat the call to wolfSSL_connect_cert() when the underlying I/O is ready
  5464. and wolfSSL will pick up where it left off. When using a non-blocking
  5465. socket, nothing needs to be done, but select() can be used to check for
  5466. the required condition. If the underlying I/O is blocking,
  5467. wolfSSL_connect_cert() will only return once the peer’s certificate chain
  5468. has been received.
  5469. \return SSL_SUCCESS upon success.
  5470. \return SSL_FAILURE will be returned if the SSL session parameter is NULL.
  5471. \return SSL_FATAL_ERROR will be returned if an error occurred. To get a more
  5472. detailed error code, call wolfSSL_get_error().
  5473. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  5474. _Example_
  5475. \code
  5476. int ret = 0;
  5477. int err = 0;
  5478. WOLFSSL* ssl;
  5479. char buffer[80];
  5480. ...
  5481. ret = wolfSSL_connect_cert(ssl);
  5482. if (ret != SSL_SUCCESS) {
  5483. err = wolfSSL_get_error(ssl, ret);
  5484. printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
  5485. }
  5486. \endcode
  5487. \sa wolfSSL_get_error
  5488. \sa wolfSSL_connect
  5489. \sa wolfSSL_accept
  5490. */
  5491. int wolfSSL_connect_cert(WOLFSSL* ssl);
  5492. /*!
  5493. \ingroup openSSL
  5494. \brief wolfSSL_d2i_PKCS12_bio (d2i_PKCS12_bio) copies in the PKCS12
  5495. information from WOLFSSL_BIO to the structure WC_PKCS12. The information
  5496. is divided up in the structure as a list of Content Infos along with a
  5497. structure to hold optional MAC information. After the information has been
  5498. divided into chunks (but not decrypted) in the structure WC_PKCS12, it can
  5499. then be parsed and decrypted by calling.
  5500. \return WC_PKCS12 pointer to a WC_PKCS12 structure.
  5501. \return Failure If function failed it will return NULL.
  5502. \param bio WOLFSSL_BIO structure to read PKCS12 buffer from.
  5503. \param pkcs12 WC_PKCS12 structure pointer for new PKCS12 structure created.
  5504. Can be NULL
  5505. _Example_
  5506. \code
  5507. WC_PKCS12* pkcs;
  5508. WOLFSSL_BIO* bio;
  5509. WOLFSSL_X509* cert;
  5510. WOLFSSL_EVP_PKEY* pkey;
  5511. STACK_OF(X509) certs;
  5512. //bio loads in PKCS12 file
  5513. wolfSSL_d2i_PKCS12_bio(bio, &pkcs);
  5514. wolfSSL_PKCS12_parse(pkcs, “a password”, &pkey, &cert, &certs)
  5515. wc_PKCS12_free(pkcs)
  5516. //use cert, pkey, and optionally certs stack
  5517. \endcode
  5518. \sa wolfSSL_PKCS12_parse
  5519. \sa wc_PKCS12_free
  5520. */
  5521. WC_PKCS12* wolfSSL_d2i_PKCS12_bio(WOLFSSL_BIO* bio,
  5522. WC_PKCS12** pkcs12);
  5523. /*!
  5524. \ingroup openSSL
  5525. \brief wolfSSL_i2d_PKCS12_bio (i2d_PKCS12_bio) copies in the cert
  5526. information from the structure WC_PKCS12 to WOLFSSL_BIO.
  5527. \return 1 for success.
  5528. \return Failure 0.
  5529. \param bio WOLFSSL_BIO structure to write PKCS12 buffer to.
  5530. \param pkcs12 WC_PKCS12 structure for PKCS12 structure as input.
  5531. _Example_
  5532. \code
  5533. WC_PKCS12 pkcs12;
  5534. FILE *f;
  5535. byte buffer[5300];
  5536. char file[] = "./test.p12";
  5537. int bytes;
  5538. WOLFSSL_BIO* bio;
  5539. pkcs12 = wc_PKCS12_new();
  5540. f = fopen(file, "rb");
  5541. bytes = (int)fread(buffer, 1, sizeof(buffer), f);
  5542. fclose(f);
  5543. //convert the DER file into an internal structure
  5544. wc_d2i_PKCS12(buffer, bytes, pkcs12);
  5545. bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
  5546. //convert PKCS12 structure into bio
  5547. wolfSSL_i2d_PKCS12_bio(bio, pkcs12);
  5548. wc_PKCS12_free(pkcs)
  5549. //use bio
  5550. \endcode
  5551. \sa wolfSSL_PKCS12_parse
  5552. \sa wc_PKCS12_free
  5553. */
  5554. WC_PKCS12* wolfSSL_i2d_PKCS12_bio(WOLFSSL_BIO* bio,
  5555. WC_PKCS12* pkcs12);
  5556. /*!
  5557. \ingroup openSSL
  5558. \brief PKCS12 can be enabled with adding –enable-opensslextra to the
  5559. configure command. It can use triple DES and RC4 for decryption so would
  5560. recommend also enabling these features when enabling opensslextra
  5561. (--enable-des3 –enable-arc4). wolfSSL does not currently support RC2 so
  5562. decryption with RC2 is currently not available. This may be noticeable
  5563. with default encryption schemes used by OpenSSL command line to create
  5564. .p12 files. wolfSSL_PKCS12_parse (PKCS12_parse). The first thing this
  5565. function does is check the MAC is correct if present. If the MAC fails
  5566. then the function returns and does not try to decrypt any of the stored
  5567. Content Infos. This function then parses through each Content Info
  5568. looking for a bag type, if the bag type is known it is decrypted as
  5569. needed and either stored in the list of certificates being built or as
  5570. a key found. After parsing through all bags the key found is then
  5571. compared with the certificate list until a matching pair is found.
  5572. This matching pair is then returned as the key and certificate,
  5573. optionally the certificate list found is returned as a STACK_OF
  5574. certificates. At the moment a CRL, Secret or SafeContents bag will be
  5575. skipped over and not parsed. It can be seen if these or other “Unknown”
  5576. bags are skipped over by viewing the debug print out. Additional attributes
  5577. such as friendly name are skipped over when parsing a PKCS12 file.
  5578. \return SSL_SUCCESS On successfully parsing PKCS12.
  5579. \return SSL_FAILURE If an error case was encountered.
  5580. \param pkcs12 WC_PKCS12 structure to parse.
  5581. \param paswd password for decrypting PKCS12.
  5582. \param pkey structure to hold private key decoded from PKCS12.
  5583. \param cert structure to hold certificate decoded from PKCS12.
  5584. \param stack optional stack of extra certificates.
  5585. _Example_
  5586. \code
  5587. WC_PKCS12* pkcs;
  5588. WOLFSSL_BIO* bio;
  5589. WOLFSSL_X509* cert;
  5590. WOLFSSL_EVP_PKEY* pkey;
  5591. STACK_OF(X509) certs;
  5592. //bio loads in PKCS12 file
  5593. wolfSSL_d2i_PKCS12_bio(bio, &pkcs);
  5594. wolfSSL_PKCS12_parse(pkcs, “a password”, &pkey, &cert, &certs)
  5595. wc_PKCS12_free(pkcs)
  5596. //use cert, pkey, and optionally certs stack
  5597. \endcode
  5598. \sa wolfSSL_d2i_PKCS12_bio
  5599. \sa wc_PKCS12_free
  5600. */
  5601. int wolfSSL_PKCS12_parse(WC_PKCS12* pkcs12, const char* psw,
  5602. WOLFSSL_EVP_PKEY** pkey, WOLFSSL_X509** cert, WOLF_STACK_OF(WOLFSSL_X509)** ca);
  5603. /*!
  5604. \ingroup CertsKeys
  5605. \brief Server Diffie-Hellman Ephemeral parameters setting. This function
  5606. sets up the group parameters to be used if the server negotiates a cipher
  5607. suite that uses DHE.
  5608. \return SSL_SUCCESS upon success.
  5609. \return MEMORY_ERROR will be returned if a memory error was encountered.
  5610. \return SIDE_ERROR will be returned if this function is called on an SSL
  5611. client instead of an SSL server.
  5612. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  5613. \param p Diffie-Hellman prime number parameter.
  5614. \param pSz size of p.
  5615. \param g Diffie-Hellman “generator” parameter.
  5616. \param gSz size of g.
  5617. _Example_
  5618. \code
  5619. WOLFSSL* ssl;
  5620. static unsigned char p[] = {...};
  5621. static unsigned char g[] = {...};
  5622. ...
  5623. wolfSSL_SetTmpDH(ssl, p, sizeof(p), g, sizeof(g));
  5624. \endcode
  5625. \sa SSL_accept
  5626. */
  5627. int wolfSSL_SetTmpDH(WOLFSSL* ssl, const unsigned char* p, int pSz,
  5628. const unsigned char* g, int gSz);
  5629. /*!
  5630. \ingroup CertsKeys
  5631. \brief The function calls the wolfSSL_SetTMpDH_buffer_wrapper,
  5632. which is a wrapper for Diffie-Hellman parameters.
  5633. \return SSL_SUCCESS on successful execution.
  5634. \return SSL_BAD_FILETYPE if the file type is not PEM and is not
  5635. ASN.1. It will also be returned if the wc_DhParamsLoad does not
  5636. return normally.
  5637. \return SSL_NO_PEM_HEADER returns from PemToDer if there is not
  5638. a PEM header.
  5639. \return SSL_BAD_FILE returned if there is a file error in PemToDer.
  5640. \return SSL_FATAL_ERROR returned from PemToDer if there was a copy error.
  5641. \return MEMORY_E - if there was a memory allocation error.
  5642. \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if
  5643. there was otherwise a NULL argument passed to a subroutine.
  5644. \return DH_KEY_SIZE_E is returned if their is a key size error in
  5645. wolfSSL_SetTmpDH() or in wolfSSL_CTX_SetTmpDH().
  5646. \return SIDE_ERROR returned if it is not the server side
  5647. in wolfSSL_SetTmpDH.
  5648. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  5649. \param buf allocated buffer passed in from wolfSSL_SetTMpDH_file_wrapper.
  5650. \param sz a long int that holds the size of the file
  5651. (fname within wolfSSL_SetTmpDH_file_wrapper).
  5652. \param format an integer type passed through from
  5653. wolfSSL_SetTmpDH_file_wrapper() that is a representation of the certificate
  5654. format.
  5655. _Example_
  5656. \code
  5657. Static int wolfSSL_SetTmpDH_file_wrapper(WOLFSSL_CTX* ctx, WOLFSSL* ssl,
  5658. Const char* fname, int format);
  5659. long sz = 0;
  5660. byte* myBuffer = staticBuffer[FILE_BUFFER_SIZE];
  5661. if(ssl)
  5662. ret = wolfSSL_SetTmpDH_buffer(ssl, myBuffer, sz, format);
  5663. \endcode
  5664. \sa wolfSSL_SetTmpDH_buffer_wrapper
  5665. \sa wc_DhParamsLoad
  5666. \sa wolfSSL_SetTmpDH
  5667. \sa PemToDer
  5668. \sa wolfSSL_CTX_SetTmpDH
  5669. \sa wolfSSL_CTX_SetTmpDH_file
  5670. */
  5671. int wolfSSL_SetTmpDH_buffer(WOLFSSL* ssl, const unsigned char* b, long sz,
  5672. int format);
  5673. /*!
  5674. \ingroup CertsKeys
  5675. \brief This function calls wolfSSL_SetTmpDH_file_wrapper to set server
  5676. Diffie-Hellman parameters.
  5677. \return SSL_SUCCESS returned on successful completion of this function
  5678. and its subroutines.
  5679. \return MEMORY_E returned if a memory allocation failed in this function
  5680. or a subroutine.
  5681. \return SIDE_ERROR if the side member of the Options structure found
  5682. in the WOLFSSL struct is not the server side.
  5683. \return SSL_BAD_FILETYPE returns if the certificate fails a set of checks.
  5684. \return DH_KEY_SIZE_E returned if the DH parameter's key size is less than
  5685. the value of the minDhKeySz member in the WOLFSSL struct.
  5686. \return DH_KEY_SIZE_E returned if the DH parameter's key size is greater
  5687. than the value of the maxDhKeySz member in the WOLFSSL struct.
  5688. \return BAD_FUNC_ARG returns if an argument value is NULL that is not
  5689. permitted such as, the WOLFSSL structure.
  5690. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  5691. \param fname a constant char pointer holding the certificate.
  5692. \param format an integer type that holds the format of the certification.
  5693. _Example_
  5694. \code
  5695. WOLFSSL* ssl = wolfSSL_new(ctx);
  5696. const char* dhParam;
  5697. AssertIntNE(SSL_SUCCESS,
  5698. wolfSSL_SetTmpDH_file(ssl, dhParam, SSL_FILETYPE_PEM));
  5699. \endcode
  5700. \sa wolfSSL_CTX_SetTmpDH_file
  5701. \sa wolfSSL_SetTmpDH_file_wrapper
  5702. \sa wolfSSL_SetTmpDH_buffer
  5703. \sa wolfSSL_CTX_SetTmpDH_buffer
  5704. \sa wolfSSL_SetTmpDH_buffer_wrapper
  5705. \sa wolfSSL_SetTmpDH
  5706. \sa wolfSSL_CTX_SetTmpDH
  5707. */
  5708. int wolfSSL_SetTmpDH_file(WOLFSSL* ssl, const char* f, int format);
  5709. /*!
  5710. \ingroup CertsKeys
  5711. \brief Sets the parameters for the server CTX Diffie-Hellman.
  5712. \return SSL_SUCCESS returned if the function and all subroutines
  5713. return without error.
  5714. \return BAD_FUNC_ARG returned if the CTX, p or g parameters are NULL.
  5715. \return DH_KEY_SIZE_E returned if the DH parameter's key size is less than
  5716. the value of the minDhKeySz member of the WOLFSSL_CTX struct.
  5717. \return DH_KEY_SIZE_E returned if the DH parameter's key size is greater
  5718. than the value of the maxDhKeySz member of the WOLFSSL_CTX struct.
  5719. \return MEMORY_E returned if the allocation of memory failed in this
  5720. function or a subroutine.
  5721. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  5722. wolfSSL_CTX_new().
  5723. \param p a constant unsigned char pointer loaded into the buffer
  5724. member of the serverDH_P struct.
  5725. \param pSz an int type representing the size of p, initialized
  5726. to MAX_DH_SIZE.
  5727. \param g a constant unsigned char pointer loaded into the buffer
  5728. member of the serverDH_G struct.
  5729. \param gSz an int type representing the size of g, initialized to
  5730. MAX_DH_SIZE.
  5731. _Exmaple_
  5732. \code
  5733. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol );
  5734. byte* p;
  5735. byte* g;
  5736. word32 pSz = (word32)sizeof(p)/sizeof(byte);
  5737. word32 gSz = (word32)sizeof(g)/sizeof(byte);
  5738. int ret = wolfSSL_CTX_SetTmpDH(ctx, p, pSz, g, gSz);
  5739. if(ret != SSL_SUCCESS){
  5740. // Failure case
  5741. }
  5742. \endcode
  5743. \sa wolfSSL_SetTmpDH
  5744. \sa wc_DhParamsLoad
  5745. */
  5746. int wolfSSL_CTX_SetTmpDH(WOLFSSL_CTX* ctx, const unsigned char* p,
  5747. int pSz, const unsigned char* g, int gSz);
  5748. /*!
  5749. \ingroup CertsKeys
  5750. \brief A wrapper function that calls wolfSSL_SetTmpDH_buffer_wrapper
  5751. \return 0 returned for a successful execution.
  5752. \return BAD_FUNC_ARG returned if the ctx or buf parameters are NULL.
  5753. \return MEMORY_E if there is a memory allocation error.
  5754. \return SSL_BAD_FILETYPE returned if format is not correct.
  5755. \param ctx a pointer to a WOLFSSL structure, created using
  5756. wolfSSL_CTX_new().
  5757. \param buf a pointer to a constant unsigned char type that is
  5758. allocated as the buffer and passed through to
  5759. wolfSSL_SetTmpDH_buffer_wrapper.
  5760. \param sz a long integer type that is derived from the fname parameter
  5761. in wolfSSL_SetTmpDH_file_wrapper().
  5762. \param format an integer type passed through from
  5763. wolfSSL_SetTmpDH_file_wrapper().
  5764. _Example_
  5765. \code
  5766. static int wolfSSL_SetTmpDH_file_wrapper(WOLFSSL_CTX* ctx, WOLFSSL* ssl,
  5767. Const char* fname, int format);
  5768. #ifdef WOLFSSL_SMALL_STACK
  5769. byte staticBuffer[1]; // force heap usage
  5770. #else
  5771. byte* staticBuffer;
  5772. long sz = 0;
  5773. if(ssl){
  5774. ret = wolfSSL_SetTmpDH_buffer(ssl, myBuffer, sz, format);
  5775. } else {
  5776. ret = wolfSSL_CTX_SetTmpDH_buffer(ctx, myBuffer, sz, format);
  5777. }
  5778. \endcode
  5779. \sa wolfSSL_SetTmpDH_buffer_wrapper
  5780. \sa wolfSSL_SetTMpDH_buffer
  5781. \sa wolfSSL_SetTmpDH_file_wrapper
  5782. \sa wolfSSL_CTX_SetTmpDH_file
  5783. */
  5784. int wolfSSL_CTX_SetTmpDH_buffer(WOLFSSL_CTX* ctx, const unsigned char* b,
  5785. long sz, int format);
  5786. /*!
  5787. \ingroup CertsKeys
  5788. \brief The function calls wolfSSL_SetTmpDH_file_wrapper to set the server
  5789. Diffie-Hellman parameters.
  5790. \return SSL_SUCCESS returned if the wolfSSL_SetTmpDH_file_wrapper or any
  5791. of its subroutines return successfully.
  5792. \return MEMORY_E returned if an allocation of dynamic memory fails in a
  5793. subroutine.
  5794. \return BAD_FUNC_ARG returned if the ctx or fname parameters are NULL or
  5795. if
  5796. a subroutine is passed a NULL argument.
  5797. \return SSL_BAD_FILE returned if the certificate file is unable to open or
  5798. if the a set of checks on the file fail from wolfSSL_SetTmpDH_file_wrapper.
  5799. \return SSL_BAD_FILETYPE returned if the format is not PEM or ASN.1 from
  5800. wolfSSL_SetTmpDH_buffer_wrapper().
  5801. \return DH_KEY_SIZE_E returned if the DH parameter's key size is less than
  5802. the value of the minDhKeySz member of the WOLFSSL_CTX struct.
  5803. \return DH_KEY_SIZE_E returned if the DH parameter's key size is greater
  5804. than the value of the maxDhKeySz member of the WOLFSSL_CTX struct.
  5805. \return SIDE_ERROR returned in wolfSSL_SetTmpDH() if the side is not the
  5806. server end.
  5807. \return SSL_NO_PEM_HEADER returned from PemToDer if there is no PEM header.
  5808. \return SSL_FATAL_ERROR returned from PemToDer if there is a memory copy
  5809. failure.
  5810. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  5811. wolfSSL_CTX_new().
  5812. \param fname a constant character pointer to a certificate file.
  5813. \param format an integer type passed through from
  5814. wolfSSL_SetTmpDH_file_wrapper() that is a representation of
  5815. the certificate format.
  5816. _Example_
  5817. \code
  5818. #define dhParam “certs/dh2048.pem”
  5819. #DEFINE aSSERTiNTne(x, y) AssertInt(x, y, !=, ==)
  5820. WOLFSSL_CTX* ctx;
  5821. AssertNotNull(ctx = wolfSSL_CTX_new(wolfSSLv23_client_method()))
  5822. AssertIntNE(SSL_SUCCESS, wolfSSL_CTX_SetTmpDH_file(NULL, dhParam,
  5823. SSL_FILETYPE_PEM));
  5824. \endcode
  5825. \sa wolfSSL_SetTmpDH_buffer_wrapper
  5826. \sa wolfSSL_SetTmpDH
  5827. \sa wolfSSL_CTX_SetTmpDH
  5828. \sa wolfSSL_SetTmpDH_buffer
  5829. \sa wolfSSL_CTX_SetTmpDH_buffer
  5830. \sa wolfSSL_SetTmpDH_file_wrapper
  5831. \sa AllocDer
  5832. \sa PemToDer
  5833. */
  5834. int wolfSSL_CTX_SetTmpDH_file(WOLFSSL_CTX* ctx, const char* f,
  5835. int format);
  5836. /*!
  5837. \ingroup CertsKeys
  5838. \brief This function sets the minimum size (in bits) of the Diffie Hellman
  5839. key size by accessing the minDhKeySz member in the WOLFSSL_CTX structure.
  5840. \return SSL_SUCCESS returned if the function completes successfully.
  5841. \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or if
  5842. the keySz_bits is greater than 16,000 or not divisible by 8.
  5843. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  5844. \param keySz_bits a word16 type used to set the minimum DH key size in bits.
  5845. The WOLFSSL_CTX struct holds this information in the minDhKeySz member.
  5846. _Example_
  5847. \code
  5848. public static int CTX_SetMinDhKey_Sz(IntPtr ctx, short minDhKey){
  5849. return wolfSSL_CTX_SetMinDhKey_Sz(local_ctx, minDhKeyBits);
  5850. \endcode
  5851. \sa wolfSSL_SetMinDhKey_Sz
  5852. \sa wolfSSL_CTX_SetMaxDhKey_Sz
  5853. \sa wolfSSL_SetMaxDhKey_Sz
  5854. \sa wolfSSL_GetDhKey_Sz
  5855. \sa wolfSSL_CTX_SetTMpDH_file
  5856. */
  5857. int wolfSSL_CTX_SetMinDhKey_Sz(WOLFSSL_CTX* ctx, word16);
  5858. /*!
  5859. \ingroup CertsKeys
  5860. \brief Sets the minimum size (in bits) for a Diffie-Hellman key in the
  5861. WOLFSSL structure.
  5862. \return SSL_SUCCESS the minimum size was successfully set.
  5863. \return BAD_FUNC_ARG the WOLFSSL structure was NULL or if the keySz_bits is
  5864. greater than 16,000 or not divisible by 8.
  5865. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  5866. \param keySz_bits a word16 type used to set the minimum DH key size in bits.
  5867. The WOLFSSL_CTX struct holds this information in the minDhKeySz member.
  5868. _Example_
  5869. \code
  5870. WOLFSSL* ssl = wolfSSL_new(ctx);
  5871. word16 keySz_bits;
  5872. ...
  5873. if(wolfSSL_SetMinDhKey_Sz(ssl, keySz_bits) != SSL_SUCCESS){
  5874. // Failed to set.
  5875. }
  5876. \endcode
  5877. \sa wolfSSL_CTX_SetMinDhKey_Sz
  5878. \sa wolfSSL_GetDhKey_Sz
  5879. */
  5880. int wolfSSL_SetMinDhKey_Sz(WOLFSSL* ssl, word16 keySz_bits);
  5881. /*!
  5882. \ingroup CertsKeys
  5883. \brief This function sets the maximum size (in bits) of the Diffie Hellman
  5884. key size by accessing the maxDhKeySz member in the WOLFSSL_CTX structure.
  5885. \return SSL_SUCCESS returned if the function completes successfully.
  5886. \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or if
  5887. the keySz_bits is greater than 16,000 or not divisible by 8.
  5888. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  5889. \param keySz_bits a word16 type used to set the maximum DH key size in bits.
  5890. The WOLFSSL_CTX struct holds this information in the maxDhKeySz member.
  5891. _Example_
  5892. \code
  5893. public static int CTX_SetMaxDhKey_Sz(IntPtr ctx, short maxDhKey){
  5894. return wolfSSL_CTX_SetMaxDhKey_Sz(local_ctx, keySz_bits);
  5895. \endcode
  5896. \sa wolfSSL_SetMinDhKey_Sz
  5897. \sa wolfSSL_CTX_SetMinDhKey_Sz
  5898. \sa wolfSSL_SetMaxDhKey_Sz
  5899. \sa wolfSSL_GetDhKey_Sz
  5900. \sa wolfSSL_CTX_SetTMpDH_file
  5901. */
  5902. int wolfSSL_CTX_SetMaxDhKey_Sz(WOLFSSL_CTX* ctx, word16 keySz_bits);
  5903. /*!
  5904. \ingroup CertsKeys
  5905. \brief Sets the maximum size (in bits) for a Diffie-Hellman key in the
  5906. WOLFSSL structure.
  5907. \return SSL_SUCCESS the maximum size was successfully set.
  5908. \return BAD_FUNC_ARG the WOLFSSL structure was NULL or the keySz parameter
  5909. was greater than the allowable size or not divisible by 8.
  5910. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  5911. \param keySz a word16 type representing the bit size of the maximum DH key.
  5912. _Example_
  5913. \code
  5914. WOLFSSL* ssl = wolfSSL_new(ctx);
  5915. word16 keySz;
  5916. ...
  5917. if(wolfSSL_SetMaxDhKey(ssl, keySz) != SSL_SUCCESS){
  5918. // Failed to set.
  5919. }
  5920. \endcode
  5921. \sa wolfSSL_CTX_SetMaxDhKey_Sz
  5922. \sa wolfSSL_GetDhKey_Sz
  5923. */
  5924. int wolfSSL_SetMaxDhKey_Sz(WOLFSSL* ssl, word16 keySz_bits);
  5925. /*!
  5926. \ingroup CertsKeys
  5927. \brief Returns the value of dhKeySz (in bits) that is a member of the
  5928. options structure. This value represents the Diffie-Hellman key size in
  5929. bytes.
  5930. \return dhKeySz returns the value held in ssl->options.dhKeySz which is an
  5931. integer value representing a size in bits.
  5932. \return BAD_FUNC_ARG returns if the WOLFSSL struct is NULL.
  5933. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  5934. _Example_
  5935. \code
  5936. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  5937. WOLFSSL* ssl = wolfSSL_new(ctx);
  5938. int dhKeySz;
  5939. ...
  5940. dhKeySz = wolfSSL_GetDhKey_Sz(ssl);
  5941. if(dhKeySz == BAD_FUNC_ARG || dhKeySz <= 0){
  5942. // Failure case
  5943. } else {
  5944. // dhKeySz holds the size of the key.
  5945. }
  5946. \endcode
  5947. \sa wolfSSL_SetMinDhKey_sz
  5948. \sa wolfSSL_CTX_SetMinDhKey_Sz
  5949. \sa wolfSSL_CTX_SetTmpDH
  5950. \sa wolfSSL_SetTmpDH
  5951. \sa wolfSSL_CTX_SetTmpDH_file
  5952. */
  5953. int wolfSSL_GetDhKey_Sz(WOLFSSL*);
  5954. /*!
  5955. \ingroup CertsKeys
  5956. \brief Sets the minimum RSA key size in both the WOLFSSL_CTX structure
  5957. and the WOLFSSL_CERT_MANAGER structure.
  5958. \return SSL_SUCCESS returned on successful execution of the function.
  5959. \return BAD_FUNC_ARG returned if the ctx structure is NULL or the keySz
  5960. is less than zero or not divisible by 8.
  5961. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  5962. wolfSSL_CTX_new().
  5963. \param keySz a short integer type stored in minRsaKeySz in the ctx
  5964. structure and the cm structure converted to bytes.
  5965. _Example_
  5966. \code
  5967. WOLFSSL_CTX* ctx = SSL_CTX_new(method);
  5968. (void)minDhKeyBits;
  5969. ourCert = myoptarg;
  5970. minDhKeyBits = atoi(myoptarg);
  5971. if(wolfSSL_CTX_SetMinRsaKey_Sz(ctx, minRsaKeyBits) != SSL_SUCCESS){
  5972. \endcode
  5973. \sa wolfSSL_SetMinRsaKey_Sz
  5974. */
  5975. int wolfSSL_CTX_SetMinRsaKey_Sz(WOLFSSL_CTX* ctx, short keySz);
  5976. /*!
  5977. \ingroup CertsKeys
  5978. \brief Sets the minimum allowable key size in bits for RSA located in the
  5979. WOLFSSL structure.
  5980. \return SSL_SUCCESS the minimum was set successfully.
  5981. \return BAD_FUNC_ARG returned if the ssl structure is NULL or if the ksySz
  5982. is less than zero or not divisible by 8.
  5983. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  5984. \param keySz a short integer value representing the the minimum key in bits.
  5985. _Example_
  5986. \code
  5987. WOLFSSL* ssl = wolfSSL_new(ctx);
  5988. short keySz;
  5989. int isSet = wolfSSL_SetMinRsaKey_Sz(ssl, keySz);
  5990. if(isSet != SSL_SUCCESS){
  5991. Failed to set.
  5992. }
  5993. \endcode
  5994. \sa wolfSSL_CTX_SetMinRsaKey_Sz
  5995. */
  5996. int wolfSSL_SetMinRsaKey_Sz(WOLFSSL* ssl, short keySz);
  5997. /*!
  5998. \ingroup CertsKeys
  5999. \brief Sets the minimum size in bits for the ECC key in the WOLF_CTX
  6000. structure and the WOLFSSL_CERT_MANAGER structure.
  6001. \return SSL_SUCCESS returned for a successful execution and the minEccKeySz
  6002. member is set.
  6003. \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or if
  6004. the keySz is negative or not divisible by 8.
  6005. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  6006. wolfSSL_CTX_new().
  6007. \param keySz a short integer type that represents the minimum ECC key
  6008. size in bits.
  6009. _Example_
  6010. \code
  6011. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  6012. short keySz; // minimum key size
  6013. if(wolfSSL_CTX_SetMinEccKey(ctx, keySz) != SSL_SUCCESS){
  6014. // Failed to set min key size
  6015. }
  6016. \endcode
  6017. \sa wolfSSL_SetMinEccKey_Sz
  6018. */
  6019. int wolfSSL_CTX_SetMinEccKey_Sz(WOLFSSL_CTX* ssl, short keySz);
  6020. /*!
  6021. \ingroup CertsKeys
  6022. \brief Sets the value of the minEccKeySz member of the options structure.
  6023. The options struct is a member of the WOLFSSL structure and is
  6024. accessed through the ssl parameter.
  6025. \return SSL_SUCCESS if the function successfully set the minEccKeySz
  6026. member of the options structure.
  6027. \return BAD_FUNC_ARG if the WOLFSSL_CTX structure is NULL or if the
  6028. key size (keySz) is less than 0 (zero) or not divisible by 8.
  6029. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  6030. \param keySz value used to set the minimum ECC key size. Sets
  6031. value in the options structure.
  6032. _Example_
  6033. \code
  6034. WOLFSSL* ssl = wolfSSL_new(ctx); // New session
  6035. short keySz = 999; // should be set to min key size allowable
  6036. ...
  6037. if(wolfSSL_SetMinEccKey_Sz(ssl, keySz) != SSL_SUCCESS){
  6038. // Failure case.
  6039. }
  6040. \endcode
  6041. \sa wolfSSL_CTX_SetMinEccKey_Sz
  6042. \sa wolfSSL_CTX_SetMinRsaKey_Sz
  6043. \sa wolfSSL_SetMinRsaKey_Sz
  6044. */
  6045. int wolfSSL_SetMinEccKey_Sz(WOLFSSL* ssl, short keySz);
  6046. /*!
  6047. \ingroup CertsKeys
  6048. \brief This function is used by EAP_TLS and EAP-TTLS to derive
  6049. keying material from the master secret.
  6050. \return BUFFER_E returned if the actual size of the buffer exceeds
  6051. the maximum size allowable.
  6052. \return MEMORY_E returned if there is an error with memory allocation.
  6053. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  6054. \param msk a void pointer variable that will hold the result
  6055. of the p_hash function.
  6056. \param len an unsigned integer that represents the length of
  6057. the msk variable.
  6058. \param label a constant char pointer that is copied from in wc_PRF().
  6059. _Example_
  6060. \code
  6061. WOLFSSL* ssl = wolfSSL_new(ctx);;
  6062. void* msk;
  6063. unsigned int len;
  6064. const char* label;
  6065. return wolfSSL_make_eap_keys(ssl, msk, len, label);
  6066. \endcode
  6067. \sa wc_PRF
  6068. \sa wc_HmacFinal
  6069. \sa wc_HmacUpdate
  6070. */
  6071. int wolfSSL_make_eap_keys(WOLFSSL* ssl, void* key, unsigned int len,
  6072. const char* label);
  6073. /*!
  6074. \ingroup IO
  6075. \brief Simulates writev semantics but doesn’t actually do block at a time
  6076. because of SSL_write() behavior and because front adds may be small.
  6077. Makes porting into software that uses writev easier.
  6078. \return >0 the number of bytes written upon success.
  6079. \return 0 will be returned upon failure. Call wolfSSL_get_error() for
  6080. the specific error code.
  6081. \return MEMORY_ERROR will be returned if a memory error was encountered.
  6082. \return SSL_FATAL_ERROR will be returned upon failure when either an error
  6083. occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or
  6084. SSL_ERROR_WANT_WRITE error was received and and the application needs to
  6085. call wolfSSL_write() again. Use wolfSSL_get_error() to get a specific
  6086. error code.
  6087. \param ssl pointer to the SSL session, created with wolfSSL_new().
  6088. \param iov array of I/O vectors to write
  6089. \param iovcnt number of vectors in iov array.
  6090. _Example_
  6091. \code
  6092. WOLFSSL* ssl = 0;
  6093. char *bufA = “hello\n”;
  6094. char *bufB = “hello world\n”;
  6095. int iovcnt;
  6096. struct iovec iov[2];
  6097. iov[0].iov_base = buffA;
  6098. iov[0].iov_len = strlen(buffA);
  6099. iov[1].iov_base = buffB;
  6100. iov[1].iov_len = strlen(buffB);
  6101. iovcnt = 2;
  6102. ...
  6103. ret = wolfSSL_writev(ssl, iov, iovcnt);
  6104. // wrote “ret” bytes, or error if <= 0.
  6105. \endcode
  6106. \sa wolfSSL_write
  6107. */
  6108. int wolfSSL_writev(WOLFSSL* ssl, const struct iovec* iov,
  6109. int iovcnt);
  6110. /*!
  6111. \ingroup Setup
  6112. \brief This function unloads the CA signer list and frees
  6113. the whole signer table.
  6114. \return SSL_SUCCESS returned on successful execution of the function.
  6115. \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or there
  6116. are otherwise unpermitted argument values passed in a subroutine.
  6117. \return BAD_MUTEX_E returned if there was a mutex error. The LockMutex()
  6118. did not return 0.
  6119. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  6120. wolfSSL_CTX_new().
  6121. _Example_
  6122. \code
  6123. WOLFSSL_METHOD method = wolfTLSv1_2_client_method();
  6124. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);
  6125. if(wolfSSL_CTX_UnloadCAs(ctx) != SSL_SUCCESS){
  6126. // The function did not unload CAs
  6127. }
  6128. \endcode
  6129. \sa wolfSSL_CertManagerUnloadCAs
  6130. \sa LockMutex
  6131. \sa UnlockMutex
  6132. */
  6133. int wolfSSL_CTX_UnloadCAs(WOLFSSL_CTX*);
  6134. /*!
  6135. \ingroup Setup
  6136. \brief This function unloads intermediate certificates added to the CA
  6137. signer list and frees them.
  6138. \return SSL_SUCCESS returned on successful execution of the function.
  6139. \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or there
  6140. are otherwise unpermitted argument values passed in a subroutine.
  6141. \return BAD_STATE_E returned if the WOLFSSL_CTX has a reference count > 1.
  6142. \return BAD_MUTEX_E returned if there was a mutex error. The LockMutex()
  6143. did not return 0.
  6144. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  6145. wolfSSL_CTX_new().
  6146. _Example_
  6147. \code
  6148. WOLFSSL_METHOD method = wolfTLSv1_2_client_method();
  6149. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);
  6150. if(wolfSSL_CTX_UnloadIntermediateCerts(ctx) != NULL){
  6151. // The function did not unload CAs
  6152. }
  6153. \endcode
  6154. \sa wolfSSL_CTX_UnloadCAs
  6155. \sa wolfSSL_CertManagerUnloadIntermediateCerts
  6156. */
  6157. int wolfSSL_CTX_UnloadIntermediateCerts(WOLFSSL_CTX* ctx);
  6158. /*!
  6159. \ingroup Setup
  6160. \brief This function is used to unload all previously loaded trusted peer
  6161. certificates. Feature is enabled by defining the macro
  6162. WOLFSSL_TRUST_PEER_CERT.
  6163. \return SSL_SUCCESS upon success.
  6164. \return BAD_FUNC_ARG will be returned if ctx is NULL.
  6165. \return SSL_BAD_FILE will be returned if the file doesn’t exist,
  6166. can’t be read, or is corrupted.
  6167. \return MEMORY_E will be returned if an out of memory condition occurs.
  6168. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  6169. _Example_
  6170. \code
  6171. int ret = 0;
  6172. WOLFSSL_CTX* ctx;
  6173. ...
  6174. ret = wolfSSL_CTX_Unload_trust_peers(ctx);
  6175. if (ret != SSL_SUCCESS) {
  6176. // error unloading trusted peer certs
  6177. }
  6178. ...
  6179. \endcode
  6180. \sa wolfSSL_CTX_trust_peer_buffer
  6181. \sa wolfSSL_CTX_trust_peer_cert
  6182. */
  6183. int wolfSSL_CTX_Unload_trust_peers(WOLFSSL_CTX*);
  6184. /*!
  6185. \ingroup Setup
  6186. \brief This function loads a certificate to use for verifying a peer
  6187. when performing a TLS/SSL handshake. The peer certificate sent during
  6188. the handshake is compared by using the SKID when available and the
  6189. signature. If these two things do not match then any loaded CAs are used.
  6190. Is the same functionality as wolfSSL_CTX_trust_peer_cert except is from
  6191. a buffer instead of a file. Feature is enabled by defining the macro
  6192. WOLFSSL_TRUST_PEER_CERT Please see the examples for proper usage.
  6193. \return SSL_SUCCESS upon success
  6194. \return SSL_FAILURE will be returned if ctx is NULL, or if both file and
  6195. type are invalid.
  6196. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  6197. \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
  6198. read, or is corrupted.
  6199. \return MEMORY_E will be returned if an out of memory condition occurs.
  6200. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  6201. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  6202. \param buffer pointer to the buffer containing certificates.
  6203. \param sz length of the buffer input.
  6204. \param type type of certificate being loaded i.e. SSL_FILETYPE_ASN1 or
  6205. SSL_FILETYPE_PEM.
  6206. _Example_
  6207. \code
  6208. int ret = 0;
  6209. WOLFSSL_CTX* ctx;
  6210. ...
  6211. ret = wolfSSL_CTX_trust_peer_buffer(ctx, bufferPtr, bufferSz,
  6212. SSL_FILETYPE_PEM);
  6213. if (ret != SSL_SUCCESS) {
  6214. // error loading trusted peer cert
  6215. }
  6216. ...
  6217. \endcode
  6218. \sa wolfSSL_CTX_load_verify_buffer
  6219. \sa wolfSSL_CTX_use_certificate_file
  6220. \sa wolfSSL_CTX_use_PrivateKey_file
  6221. \sa wolfSSL_CTX_use_certificate_chain_file
  6222. \sa wolfSSL_CTX_trust_peer_cert
  6223. \sa wolfSSL_CTX_Unload_trust_peers
  6224. \sa wolfSSL_use_certificate_file
  6225. \sa wolfSSL_use_PrivateKey_file
  6226. \sa wolfSSL_use_certificate_chain_file
  6227. */
  6228. int wolfSSL_CTX_trust_peer_buffer(WOLFSSL_CTX* ctx, const unsigned char* in,
  6229. long sz, int format);
  6230. /*!
  6231. \ingroup CertsKeys
  6232. \brief This function loads a CA certificate buffer into the WOLFSSL
  6233. Context. It behaves like the non-buffered version, only differing in
  6234. its ability to be called with a buffer as input instead of a file.
  6235. The buffer is provided by the in argument of size sz. format specifies
  6236. the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
  6237. More than one CA certificate may be loaded per buffer as long as the
  6238. format is in PEM. Please see the examples for proper usage.
  6239. \return SSL_SUCCESS upon success
  6240. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  6241. \return SSL_BAD_FILE will be returned if the file doesn’t exist,
  6242. can’t be read, or is corrupted.
  6243. \return MEMORY_E will be returned if an out of memory condition occurs.
  6244. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  6245. \return BUFFER_E will be returned if a chain buffer is bigger than
  6246. the receiving buffer.
  6247. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  6248. \param in pointer to the CA certificate buffer.
  6249. \param sz size of the input CA certificate buffer, in.
  6250. \param format format of the buffer certificate, either SSL_FILETYPE_ASN1
  6251. or SSL_FILETYPE_PEM.
  6252. _Example_
  6253. \code
  6254. int ret = 0;
  6255. int sz = 0;
  6256. WOLFSSL_CTX* ctx;
  6257. byte certBuff[...];
  6258. ...
  6259. ret = wolfSSL_CTX_load_verify_buffer(ctx, certBuff, sz, SSL_FILETYPE_PEM);
  6260. if (ret != SSL_SUCCESS) {
  6261. // error loading CA certs from buffer
  6262. }
  6263. ...
  6264. \endcode
  6265. \sa wolfSSL_CTX_load_verify_locations
  6266. \sa wolfSSL_CTX_use_certificate_buffer
  6267. \sa wolfSSL_CTX_use_PrivateKey_buffer
  6268. \sa wolfSSL_CTX_use_certificate_chain_buffer
  6269. \sa wolfSSL_use_certificate_buffer
  6270. \sa wolfSSL_use_PrivateKey_buffer
  6271. \sa wolfSSL_use_certificate_chain_buffer
  6272. */
  6273. int wolfSSL_CTX_load_verify_buffer(WOLFSSL_CTX* ctx, const unsigned char* in,
  6274. long sz, int format);
  6275. /*!
  6276. \ingroup CertsKeys
  6277. \brief This function loads a CA certificate buffer into the WOLFSSL
  6278. Context. It behaves like the non-buffered version, only differing in
  6279. its ability to be called with a buffer as input instead of a file.
  6280. The buffer is provided by the in argument of size sz. format specifies
  6281. the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
  6282. More than one CA certificate may be loaded per buffer as long as the
  6283. format is in PEM. The _ex version was added in PR 2413 and supports
  6284. additional arguments for userChain and flags.
  6285. \return SSL_SUCCESS upon success
  6286. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  6287. \return SSL_BAD_FILE will be returned if the file doesn’t exist,
  6288. can’t be read, or is corrupted.
  6289. \return MEMORY_E will be returned if an out of memory condition occurs.
  6290. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  6291. \return BUFFER_E will be returned if a chain buffer is bigger than
  6292. the receiving buffer.
  6293. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  6294. \param in pointer to the CA certificate buffer.
  6295. \param sz size of the input CA certificate buffer, in.
  6296. \param format format of the buffer certificate, either SSL_FILETYPE_ASN1
  6297. or SSL_FILETYPE_PEM.
  6298. \param userChain If using format WOLFSSL_FILETYPE_ASN1 this set to non-zero
  6299. indicates a chain of DER's is being presented.
  6300. \param flags: See ssl.h around WOLFSSL_LOAD_VERIFY_DEFAULT_FLAGS.
  6301. _Example_
  6302. \code
  6303. int ret = 0;
  6304. int sz = 0;
  6305. WOLFSSL_CTX* ctx;
  6306. byte certBuff[...];
  6307. ...
  6308. // Example for force loading an expired certificate
  6309. ret = wolfSSL_CTX_load_verify_buffer_ex(ctx, certBuff, sz, SSL_FILETYPE_PEM,
  6310. 0, (WOLFSSL_LOAD_FLAG_DATE_ERR_OKAY));
  6311. if (ret != SSL_SUCCESS) {
  6312. // error loading CA certs from buffer
  6313. }
  6314. ...
  6315. \endcode
  6316. \sa wolfSSL_CTX_load_verify_buffer
  6317. \sa wolfSSL_CTX_load_verify_locations
  6318. \sa wolfSSL_CTX_use_certificate_buffer
  6319. \sa wolfSSL_CTX_use_PrivateKey_buffer
  6320. \sa wolfSSL_CTX_use_certificate_chain_buffer
  6321. \sa wolfSSL_use_certificate_buffer
  6322. \sa wolfSSL_use_PrivateKey_buffer
  6323. \sa wolfSSL_use_certificate_chain_buffer
  6324. */
  6325. int wolfSSL_CTX_load_verify_buffer_ex(WOLFSSL_CTX* ctx,
  6326. const unsigned char* in, long sz,
  6327. int format, int userChain, word32 flags);
  6328. /*!
  6329. \ingroup CertsKeys
  6330. \brief This function loads a CA certificate chain buffer into the WOLFSSL
  6331. Context. It behaves like the non-buffered version, only differing in
  6332. its ability to be called with a buffer as input instead of a file.
  6333. The buffer is provided by the in argument of size sz. format specifies
  6334. the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
  6335. More than one CA certificate may be loaded per buffer as long as the
  6336. format is in PEM. Please see the examples for proper usage.
  6337. \return SSL_SUCCESS upon success
  6338. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  6339. \return SSL_BAD_FILE will be returned if the file doesn’t exist,
  6340. can’t be read, or is corrupted.
  6341. \return MEMORY_E will be returned if an out of memory condition occurs.
  6342. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  6343. \return BUFFER_E will be returned if a chain buffer is bigger than
  6344. the receiving buffer.
  6345. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  6346. \param in pointer to the CA certificate buffer.
  6347. \param sz size of the input CA certificate buffer, in.
  6348. \param format format of the buffer certificate, either SSL_FILETYPE_ASN1
  6349. or SSL_FILETYPE_PEM.
  6350. _Example_
  6351. \code
  6352. int ret = 0;
  6353. int sz = 0;
  6354. WOLFSSL_CTX* ctx;
  6355. byte certBuff[...];
  6356. ...
  6357. ret = wolfSSL_CTX_load_verify_chain_buffer_format(ctx,
  6358. certBuff, sz, WOLFSSL_FILETYPE_ASN1);
  6359. if (ret != SSL_SUCCESS) {
  6360. // error loading CA certs from buffer
  6361. }
  6362. ...
  6363. \endcode
  6364. \sa wolfSSL_CTX_load_verify_locations
  6365. \sa wolfSSL_CTX_use_certificate_buffer
  6366. \sa wolfSSL_CTX_use_PrivateKey_buffer
  6367. \sa wolfSSL_CTX_use_certificate_chain_buffer
  6368. \sa wolfSSL_use_certificate_buffer
  6369. \sa wolfSSL_use_PrivateKey_buffer
  6370. \sa wolfSSL_use_certificate_chain_buffer
  6371. */
  6372. int wolfSSL_CTX_load_verify_chain_buffer_format(WOLFSSL_CTX* ctx,
  6373. const unsigned char* in,
  6374. long sz, int format);
  6375. /*!
  6376. \ingroup CertsKeys
  6377. \brief This function loads a certificate buffer into the WOLFSSL Context.
  6378. It behaves like the non-buffered version, only differing in its ability
  6379. to be called with a buffer as input instead of a file. The buffer is
  6380. provided by the in argument of size sz. format specifies the format
  6381. type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please
  6382. see the examples for proper usage.
  6383. \return SSL_SUCCESS upon success
  6384. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  6385. \return SSL_BAD_FILE will be returned if the file doesn’t exist,
  6386. can’t be read, or is corrupted.
  6387. \return MEMORY_E will be returned if an out of memory condition occurs.
  6388. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  6389. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  6390. \param in the input buffer containing the certificate to be loaded.
  6391. \param sz the size of the input buffer.
  6392. \param format the format of the certificate located in the input
  6393. buffer (in). Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
  6394. _Example_
  6395. \code
  6396. int ret = 0;
  6397. int sz = 0;
  6398. WOLFSSL_CTX* ctx;
  6399. byte certBuff[...];
  6400. ...
  6401. ret = wolfSSL_CTX_use_certificate_buffer(ctx, certBuff, sz, SSL_FILETYPE_PEM);
  6402. if (ret != SSL_SUCCESS) {
  6403. // error loading certificate from buffer
  6404. }
  6405. ...
  6406. \endcode
  6407. \sa wolfSSL_CTX_load_verify_buffer
  6408. \sa wolfSSL_CTX_use_PrivateKey_buffer
  6409. \sa wolfSSL_CTX_use_certificate_chain_buffer
  6410. \sa wolfSSL_use_certificate_buffer
  6411. \sa wolfSSL_use_PrivateKey_buffer
  6412. \sa wolfSSL_use_certificate_chain_buffer
  6413. */
  6414. int wolfSSL_CTX_use_certificate_buffer(WOLFSSL_CTX* ctx,
  6415. const unsigned char* in, long sz,
  6416. int format);
  6417. /*!
  6418. \ingroup CertsKeys
  6419. \brief This function loads a private key buffer into the SSL Context.
  6420. It behaves like the non-buffered version, only differing in its ability
  6421. to be called with a buffer as input instead of a file. The buffer is
  6422. provided by the in argument of size sz. format specifies the format type
  6423. of the buffer; SSL_FILETYPE_ASN1or SSL_FILETYPE_PEM. Please see the
  6424. examples for proper usage.
  6425. \return SSL_SUCCESS upon success
  6426. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  6427. \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
  6428. read, or is corrupted.
  6429. \return MEMORY_E will be returned if an out of memory condition occurs.
  6430. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  6431. \return NO_PASSWORD will be returned if the key file is encrypted but no
  6432. password is provided.
  6433. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  6434. \param in the input buffer containing the private key to be loaded.
  6435. \param sz the size of the input buffer.
  6436. \param format the format of the private key located in the input
  6437. buffer (in). Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
  6438. _Example_
  6439. \code
  6440. int ret = 0;
  6441. int sz = 0;
  6442. WOLFSSL_CTX* ctx;
  6443. byte keyBuff[...];
  6444. ...
  6445. ret = wolfSSL_CTX_use_PrivateKey_buffer(ctx, keyBuff, sz, SSL_FILETYPE_PEM);
  6446. if (ret != SSL_SUCCESS) {
  6447. // error loading private key from buffer
  6448. }
  6449. ...
  6450. \endcode
  6451. \sa wolfSSL_CTX_load_verify_buffer
  6452. \sa wolfSSL_CTX_use_certificate_buffer
  6453. \sa wolfSSL_CTX_use_certificate_chain_buffer
  6454. \sa wolfSSL_use_certificate_buffer
  6455. \sa wolfSSL_use_PrivateKey_buffer
  6456. \sa wolfSSL_use_certificate_chain_buffer
  6457. */
  6458. int wolfSSL_CTX_use_PrivateKey_buffer(WOLFSSL_CTX* ctx,
  6459. const unsigned char* in, long sz,
  6460. int format);
  6461. /*!
  6462. \ingroup CertsKeys
  6463. \brief This function loads a certificate chain buffer into the WOLFSSL
  6464. Context. It behaves like the non-buffered version, only differing in
  6465. its ability to be called with a buffer as input instead of a file.
  6466. The buffer is provided by the in argument of size sz. The buffer must
  6467. be in PEM format and start with the subject’s certificate, ending with
  6468. the root certificate. Please see the examples for proper usage.
  6469. \return SSL_SUCCESS upon success
  6470. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  6471. \return SSL_BAD_FILE will be returned if the file doesn’t exist,
  6472. can’t be read, or is corrupted.
  6473. \return MEMORY_E will be returned if an out of memory condition occurs.
  6474. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  6475. \return BUFFER_E will be returned if a chain buffer is bigger than
  6476. the receiving buffer.
  6477. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  6478. \param in the input buffer containing the PEM-formatted certificate
  6479. chain to be loaded.
  6480. \param sz the size of the input buffer.
  6481. _Example_
  6482. \code
  6483. int ret = 0;
  6484. int sz = 0;
  6485. WOLFSSL_CTX* ctx;
  6486. byte certChainBuff[...];
  6487. ...
  6488. ret = wolfSSL_CTX_use_certificate_chain_buffer(ctx, certChainBuff, sz);
  6489. if (ret != SSL_SUCCESS) {
  6490. // error loading certificate chain from buffer
  6491. }
  6492. ...
  6493. \endcode
  6494. \sa wolfSSL_CTX_load_verify_buffer
  6495. \sa wolfSSL_CTX_use_certificate_buffer
  6496. \sa wolfSSL_CTX_use_PrivateKey_buffer
  6497. \sa wolfSSL_use_certificate_buffer
  6498. \sa wolfSSL_use_PrivateKey_buffer
  6499. \sa wolfSSL_use_certificate_chain_buffer
  6500. */
  6501. int wolfSSL_CTX_use_certificate_chain_buffer(WOLFSSL_CTX* ctx,
  6502. const unsigned char* in, long sz);
  6503. /*!
  6504. \ingroup CertsKeys
  6505. \brief This function loads a certificate buffer into the WOLFSSL object.
  6506. It behaves like the non-buffered version, only differing in its ability
  6507. to be called with a buffer as input instead of a file. The buffer
  6508. is provided by the in argument of size sz. format specifies the format
  6509. type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
  6510. Please see the examples for proper usage.
  6511. \return SSL_SUCCESS upon success.
  6512. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  6513. \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t
  6514. be read, or is corrupted.
  6515. \return MEMORY_E will be returned if an out of memory condition occurs.
  6516. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  6517. \param ssl pointer to the SSL session, created with wolfSSL_new().
  6518. \param in buffer containing certificate to load.
  6519. \param sz size of the certificate located in buffer.
  6520. \param format format of the certificate to be loaded.
  6521. Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
  6522. _Example_
  6523. \code
  6524. int buffSz;
  6525. int ret;
  6526. byte certBuff[...];
  6527. WOLFSSL* ssl = 0;
  6528. ...
  6529. ret = wolfSSL_use_certificate_buffer(ssl, certBuff, buffSz, SSL_FILETYPE_PEM);
  6530. if (ret != SSL_SUCCESS) {
  6531. // failed to load certificate from buffer
  6532. }
  6533. \endcode
  6534. \sa wolfSSL_CTX_load_verify_buffer
  6535. \sa wolfSSL_CTX_use_certificate_buffer
  6536. \sa wolfSSL_CTX_use_PrivateKey_buffer
  6537. \sa wolfSSL_CTX_use_certificate_chain_buffer
  6538. \sa wolfSSL_use_PrivateKey_buffer
  6539. \sa wolfSSL_use_certificate_chain_buffer
  6540. */
  6541. int wolfSSL_use_certificate_buffer(WOLFSSL* ssl, const unsigned char* in,
  6542. long sz, int format);
  6543. /*!
  6544. \ingroup CertsKeys
  6545. \brief This function loads a private key buffer into the WOLFSSL object.
  6546. It behaves like the non-buffered version, only differing in its ability
  6547. to be called with a buffer as input instead of a file. The buffer is
  6548. provided by the in argument of size sz. format specifies the format
  6549. type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please
  6550. see the examples for proper usage.
  6551. \return SSL_SUCCESS upon success.
  6552. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  6553. \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
  6554. read, or is corrupted.
  6555. \return MEMORY_E will be returned if an out of memory condition occurs.
  6556. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  6557. \return NO_PASSWORD will be returned if the key file is encrypted but no
  6558. password is provided.
  6559. \param ssl pointer to the SSL session, created with wolfSSL_new().
  6560. \param in buffer containing private key to load.
  6561. \param sz size of the private key located in buffer.
  6562. \param format format of the private key to be loaded. Possible values are
  6563. SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
  6564. _Example_
  6565. \code
  6566. int buffSz;
  6567. int ret;
  6568. byte keyBuff[...];
  6569. WOLFSSL* ssl = 0;
  6570. ...
  6571. ret = wolfSSL_use_PrivateKey_buffer(ssl, keyBuff, buffSz, SSL_FILETYPE_PEM);
  6572. if (ret != SSL_SUCCESS) {
  6573. // failed to load private key from buffer
  6574. }
  6575. \endcode
  6576. \sa wolfSSL_use_PrivateKey
  6577. \sa wolfSSL_CTX_load_verify_buffer
  6578. \sa wolfSSL_CTX_use_certificate_buffer
  6579. \sa wolfSSL_CTX_use_PrivateKey_buffer
  6580. \sa wolfSSL_CTX_use_certificate_chain_buffer
  6581. \sa wolfSSL_use_certificate_buffer
  6582. \sa wolfSSL_use_certificate_chain_buffer
  6583. */
  6584. int wolfSSL_use_PrivateKey_buffer(WOLFSSL* ssl, const unsigned char* in,
  6585. long sz, int format);
  6586. /*!
  6587. \ingroup CertsKeys
  6588. \brief This function loads a certificate chain buffer into the WOLFSSL
  6589. object. It behaves like the non-buffered version, only differing in its
  6590. ability to be called with a buffer as input instead of a file. The buffer
  6591. is provided by the in argument of size sz. The buffer must be in PEM format
  6592. and start with the subject’s certificate, ending with the root certificate.
  6593. Please see the examples for proper usage.
  6594. \return SSL_SUCCES upon success.
  6595. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  6596. \return SSL_BAD_FILE will be returned if the file doesn’t exist,
  6597. can’t be read, or is corrupted.
  6598. \return MEMORY_E will be returned if an out of memory condition occurs.
  6599. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  6600. \return BUFFER_E will be returned if a chain buffer is bigger than
  6601. the receiving buffer.
  6602. \param ssl pointer to the SSL session, created with wolfSSL_new().
  6603. \param in buffer containing certificate to load.
  6604. \param sz size of the certificate located in buffer.
  6605. _Example_
  6606. \code
  6607. int buffSz;
  6608. int ret;
  6609. byte certChainBuff[...];
  6610. WOLFSSL* ssl = 0;
  6611. ...
  6612. ret = wolfSSL_use_certificate_chain_buffer(ssl, certChainBuff, buffSz);
  6613. if (ret != SSL_SUCCESS) {
  6614. // failed to load certificate chain from buffer
  6615. }
  6616. \endcode
  6617. \sa wolfSSL_CTX_load_verify_buffer
  6618. \sa wolfSSL_CTX_use_certificate_buffer
  6619. \sa wolfSSL_CTX_use_PrivateKey_buffer
  6620. \sa wolfSSL_CTX_use_certificate_chain_buffer
  6621. \sa wolfSSL_use_certificate_buffer
  6622. \sa wolfSSL_use_PrivateKey_buffer
  6623. */
  6624. int wolfSSL_use_certificate_chain_buffer(WOLFSSL* ssl,
  6625. const unsigned char* in, long sz);
  6626. /*!
  6627. \ingroup CertsKeys
  6628. \brief This function unloads any certificates or keys that SSL owns.
  6629. \return SSL_SUCCESS - returned if the function executed successfully.
  6630. \return BAD_FUNC_ARG - returned if the WOLFSSL object is NULL.
  6631. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  6632. _Example_
  6633. \code
  6634. WOLFSSL* ssl = wolfSSL_new(ctx);
  6635. ...
  6636. int unloadKeys = wolfSSL_UnloadCertsKeys(ssl);
  6637. if(unloadKeys != SSL_SUCCESS){
  6638. // Failure case.
  6639. }
  6640. \endcode
  6641. \sa wolfSSL_CTX_UnloadCAs
  6642. */
  6643. int wolfSSL_UnloadCertsKeys(WOLFSSL*);
  6644. /*!
  6645. \ingroup Setup
  6646. \brief This function turns on grouping of handshake messages where possible.
  6647. \return SSL_SUCCESS will be returned upon success.
  6648. \return BAD_FUNC_ARG will be returned if the input context is null.
  6649. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  6650. _Example_
  6651. \code
  6652. WOLFSSL_CTX* ctx = 0;
  6653. ...
  6654. ret = wolfSSL_CTX_set_group_messages(ctx);
  6655. if (ret != SSL_SUCCESS) {
  6656. // failed to set handshake message grouping
  6657. }
  6658. \endcode
  6659. \sa wolfSSL_set_group_messages
  6660. \sa wolfSSL_CTX_new
  6661. */
  6662. int wolfSSL_CTX_set_group_messages(WOLFSSL_CTX*);
  6663. /*!
  6664. \ingroup Setup
  6665. \brief This function turns on grouping of handshake messages where possible.
  6666. \return SSL_SUCCESS will be returned upon success.
  6667. \return BAD_FUNC_ARG will be returned if the input context is null.
  6668. \param ssl pointer to the SSL session, created with wolfSSL_new().
  6669. _Example_
  6670. \code
  6671. WOLFSSL* ssl = 0;
  6672. ...
  6673. ret = wolfSSL_set_group_messages(ssl);
  6674. if (ret != SSL_SUCCESS) {
  6675. // failed to set handshake message grouping
  6676. }
  6677. \endcode
  6678. \sa wolfSSL_CTX_set_group_messages
  6679. \sa wolfSSL_new
  6680. */
  6681. int wolfSSL_set_group_messages(WOLFSSL*);
  6682. /*!
  6683. \brief This function sets the fuzzer callback.
  6684. \return none No returns.
  6685. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  6686. \param cbf a CallbackFuzzer type that is a function pointer of the form:
  6687. int (*CallbackFuzzer)(WOLFSSL* ssl, const unsigned char* buf, int sz, int
  6688. type, void* fuzzCtx);
  6689. \param fCtx a void pointer type that will be set to the fuzzerCtx member of
  6690. the WOLFSSL structure.
  6691. _Example_
  6692. \code
  6693. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  6694. WOLFSSL* ssl = wolfSSL_new(ctx);
  6695. void* fCtx;
  6696. int callbackFuzzerCB(WOLFSSL* ssl, const unsigned char* buf, int sz,
  6697. int type, void* fuzzCtx){
  6698. // function definition
  6699. }
  6700. wolfSSL_SetFuzzerCb(ssl, callbackFuzzerCB, fCtx);
  6701. \endcode
  6702. \sa CallbackFuzzer
  6703. */
  6704. void wolfSSL_SetFuzzerCb(WOLFSSL* ssl, CallbackFuzzer cbf, void* fCtx);
  6705. /*!
  6706. \brief This function sets a new dtls cookie secret.
  6707. \return 0 returned if the function executed without an error.
  6708. \return BAD_FUNC_ARG returned if there was an argument passed
  6709. to the function with an unacceptable value.
  6710. \return COOKIE_SECRET_SZ returned if the secret size is 0.
  6711. \return MEMORY_ERROR returned if there was a problem allocating
  6712. memory for a new cookie secret.
  6713. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  6714. \param secret a constant byte pointer representing the secret buffer.
  6715. \param secretSz the size of the buffer.
  6716. _Example_
  6717. \code
  6718. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  6719. WOLFSSL* ssl = wolfSSL_new(ctx);
  6720. const* byte secret;
  6721. word32 secretSz; // size of secret
  6722. if(!wolfSSL_DTLS_SetCookieSecret(ssl, secret, secretSz)){
  6723. // Code block for failure to set DTLS cookie secret
  6724. } else {
  6725. // Success! Cookie secret is set.
  6726. }
  6727. \endcode
  6728. \sa ForceZero
  6729. \sa wc_RNG_GenerateBlock
  6730. */
  6731. int wolfSSL_DTLS_SetCookieSecret(WOLFSSL* ssl,
  6732. const unsigned char* secret,
  6733. unsigned int secretSz);
  6734. /*!
  6735. \brief This function retrieves the random number.
  6736. \return rng upon success.
  6737. \return NULL if ssl is NULL.
  6738. \param ssl pointer to a SSL object, created with wolfSSL_new().
  6739. _Example_
  6740. \code
  6741. WOLFSSL* ssl;
  6742. wolfSSL_GetRNG(ssl);
  6743. \endcode
  6744. \sa wolfSSL_CTX_new_rng
  6745. */
  6746. WC_RNG* wolfSSL_GetRNG(WOLFSSL* ssl);
  6747. /*!
  6748. \ingroup Setup
  6749. \brief This function sets the minimum downgrade version allowed.
  6750. Applicable only when the connection allows downgrade using
  6751. (wolfSSLv23_client_method or wolfSSLv23_server_method).
  6752. \return SSL_SUCCESS returned if the function returned without
  6753. error and the minimum version is set.
  6754. \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure was
  6755. NULL or if the minimum version is not supported.
  6756. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  6757. wolfSSL_CTX_new().
  6758. \param version an integer representation of the version to be set as the
  6759. minimum: WOLFSSL_SSLV3 = 0, WOLFSSL_TLSV1 = 1, WOLFSSL_TLSV1_1 = 2 or
  6760. WOLFSSL_TLSV1_2 = 3.
  6761. _Example_
  6762. \code
  6763. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
  6764. WOLFSSL* ssl = WOLFSSL_new(ctx);
  6765. int version; // macrop representation
  6766. if(wolfSSL_CTX_SetMinVersion(ssl->ctx, version) != SSL_SUCCESS){
  6767. // Failed to set min version
  6768. }
  6769. \endcode
  6770. \sa SetMinVersionHelper
  6771. */
  6772. int wolfSSL_CTX_SetMinVersion(WOLFSSL_CTX* ctx, int version);
  6773. /*!
  6774. \ingroup TLS
  6775. \brief This function sets the minimum downgrade version allowed.
  6776. Applicable only when the connection allows downgrade using
  6777. (wolfSSLv23_client_method or wolfSSLv23_server_method).
  6778. \return SSL_SUCCESS returned if this function and its subroutine executes
  6779. without error.
  6780. \return BAD_FUNC_ARG returned if the SSL object is NULL. In
  6781. the subroutine this error is thrown if there is not a good version match.
  6782. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  6783. \param version an integer representation of the version to be set as the
  6784. minimum: WOLFSSL_SSLV3 = 0, WOLFSSL_TLSV1 = 1, WOLFSSL_TLSV1_1 = 2 or
  6785. WOLFSSL_TLSV1_2 = 3.
  6786. _Example_
  6787. \code
  6788. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(protocol method);
  6789. WOLFSSL* ssl = WOLFSSL_new(ctx);
  6790. int version; macro representation
  6791. if(wolfSSL_CTX_SetMinVersion(ssl->ctx, version) != SSL_SUCCESS){
  6792. Failed to set min version
  6793. }
  6794. \endcode
  6795. \sa SetMinVersionHelper
  6796. */
  6797. int wolfSSL_SetMinVersion(WOLFSSL* ssl, int version);
  6798. /*!
  6799. \brief This function returns the size of the WOLFSSL object and will be
  6800. dependent on build options and settings. If SHOW_SIZES has been defined
  6801. when building wolfSSL, this function will also print the sizes of individual
  6802. objects within the WOLFSSL object (Suites, Ciphers, etc.) to stdout.
  6803. \return size This function returns the size of the WOLFSSL object.
  6804. \param none No parameters.
  6805. _Example_
  6806. \code
  6807. int size = 0;
  6808. size = wolfSSL_GetObjectSize();
  6809. printf(“sizeof(WOLFSSL) = %d\n”, size);
  6810. \endcode
  6811. \sa wolfSSL_new
  6812. */
  6813. int wolfSSL_GetObjectSize(void); /* object size based on build */
  6814. /*!
  6815. \brief Returns the record layer size of the plaintext input. This is helpful
  6816. when an application wants to know how many bytes will be sent across the
  6817. Transport layer, given a specified plaintext input size. This function
  6818. must be called after the SSL/TLS handshake has been completed.
  6819. \return size Upon success, the requested size will be returned
  6820. \return INPUT_SIZE_E will be returned if the input size is greater than the
  6821. maximum TLS fragment size (see wolfSSL_GetMaxOutputSize())
  6822. \return BAD_FUNC_ARG will be returned upon invalid function argument, or if
  6823. the SSL/TLS handshake has not been completed yet
  6824. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  6825. \param inSz size of plaintext data.
  6826. _Example_
  6827. \code
  6828. none
  6829. \endcode
  6830. \sa wolfSSL_GetMaxOutputSize
  6831. */
  6832. int wolfSSL_GetOutputSize(WOLFSSL* ssl, int inSz);
  6833. /*!
  6834. \brief Returns the maximum record layer size for plaintext data. This
  6835. will correspond to either the maximum SSL/TLS record size as specified
  6836. by the protocol standard, the maximum TLS fragment size as set by the
  6837. TLS Max Fragment Length extension. This function is helpful when the
  6838. application has called wolfSSL_GetOutputSize() and received a INPUT_SIZE_E
  6839. error. This function must be called after the SSL/TLS handshake has been
  6840. completed.
  6841. \return size Upon success, the maximum output size will be returned
  6842. \return BAD_FUNC_ARG will be returned upon invalid function argument,
  6843. or if the SSL/TLS handshake has not been completed yet.
  6844. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  6845. _Example_
  6846. \code
  6847. none
  6848. \endcode
  6849. \sa wolfSSL_GetOutputSize
  6850. */
  6851. int wolfSSL_GetMaxOutputSize(WOLFSSL*);
  6852. /*!
  6853. \ingroup Setup
  6854. \brief This function sets the SSL/TLS protocol version for the specified
  6855. SSL session (WOLFSSL object) using the version as specified by version.
  6856. This will override the protocol setting for the SSL session (ssl) -
  6857. originally defined and set by the SSL context (wolfSSL_CTX_new())
  6858. method type.
  6859. \return SSL_SUCCESS upon success.
  6860. \return BAD_FUNC_ARG will be returned if the input SSL object is
  6861. NULL or an incorrect protocol version is given for version.
  6862. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  6863. \param version SSL/TLS protocol version. Possible values include
  6864. WOLFSSL_SSLV3, WOLFSSL_TLSV1, WOLFSSL_TLSV1_1, WOLFSSL_TLSV1_2.
  6865. _Example_
  6866. \code
  6867. int ret = 0;
  6868. WOLFSSL* ssl;
  6869. ...
  6870. ret = wolfSSL_SetVersion(ssl, WOLFSSL_TLSV1);
  6871. if (ret != SSL_SUCCESS) {
  6872. // failed to set SSL session protocol version
  6873. }
  6874. \endcode
  6875. \sa wolfSSL_CTX_new
  6876. */
  6877. int wolfSSL_SetVersion(WOLFSSL* ssl, int version);
  6878. /*!
  6879. \brief Allows caller to set the Atomic User Record Processing
  6880. Mac/Encrypt Callback. The callback should return 0 for success
  6881. or < 0 for an error. The ssl and ctx pointers are available
  6882. for the user’s convenience. macOut is the output buffer where
  6883. the result of the mac should be stored. macIn is the mac input
  6884. buffer and macInSz notes the size of the buffer. macContent
  6885. and macVerify are needed for wolfSSL_SetTlsHmacInner() and be
  6886. passed along as is. encOut is the output buffer where the result
  6887. on the encryption should be stored. encIn is the input buffer to
  6888. encrypt while encSz is the size of the input. An example callback
  6889. can be found wolfssl/test.h myMacEncryptCb().
  6890. \return none No return.
  6891. \param No parameters.
  6892. _Example_
  6893. \code
  6894. none
  6895. \endcode
  6896. \sa wolfSSL_SetMacEncryptCtx
  6897. \sa wolfSSL_GetMacEncryptCtx
  6898. */
  6899. void wolfSSL_CTX_SetMacEncryptCb(WOLFSSL_CTX* ctx, CallbackMacEncrypti cb);
  6900. /*!
  6901. \brief Allows caller to set the Atomic User Record Processing Mac/Encrypt
  6902. Callback Context to ctx.
  6903. \return none No return.
  6904. \param none No parameters.
  6905. _Example_
  6906. \code
  6907. none
  6908. \endcode
  6909. \sa wolfSSL_CTX_SetMacEncryptCb
  6910. \sa wolfSSL_GetMacEncryptCtx
  6911. */
  6912. void wolfSSL_SetMacEncryptCtx(WOLFSSL* ssl, void *ctx);
  6913. /*!
  6914. \brief Allows caller to retrieve the Atomic User Record Processing
  6915. Mac/Encrypt Callback Context previously stored with
  6916. wolfSSL_SetMacEncryptCtx().
  6917. \return pointer If successful the call will return a valid pointer
  6918. to the context.
  6919. \return NULL will be returned for a blank context.
  6920. \param none No parameters.
  6921. _Example_
  6922. \code
  6923. none
  6924. \endcode
  6925. \sa wolfSSL_CTX_SetMacEncryptCb
  6926. \sa wolfSSL_SetMacEncryptCtx
  6927. */
  6928. void* wolfSSL_GetMacEncryptCtx(WOLFSSL* ssl);
  6929. /*!
  6930. \brief Allows caller to set the Atomic User Record Processing
  6931. Decrypt/Verify Callback. The callback should return 0 for success
  6932. or < 0 for an error. The ssl and ctx pointers are available for
  6933. the user’s convenience. decOut is the output buffer where the result
  6934. of the decryption should be stored. decIn is the encrypted input
  6935. buffer and decInSz notes the size of the buffer. content and verify
  6936. are needed for wolfSSL_SetTlsHmacInner() and be passed along as is.
  6937. padSz is an output variable that should be set with the total value
  6938. of the padding. That is, the mac size plus any padding and pad bytes.
  6939. An example callback can be found wolfssl/test.h myDecryptVerifyCb().
  6940. \return none No returns.
  6941. \param none No parameters.
  6942. _Example_
  6943. \code
  6944. none
  6945. \endcode
  6946. \sa wolfSSL_SetMacEncryptCtx
  6947. \sa wolfSSL_GetMacEncryptCtx
  6948. */
  6949. void wolfSSL_CTX_SetDecryptVerifyCb(WOLFSSL_CTX* ctx,
  6950. CallbackDecryptVerify cb);
  6951. /*!
  6952. \brief Allows caller to set the Atomic User Record Processing
  6953. Decrypt/Verify Callback Context to ctx.
  6954. \return none No returns.
  6955. \param none No parameters.
  6956. _Example_
  6957. \code
  6958. none
  6959. \endcode
  6960. \sa wolfSSL_CTX_SetDecryptVerifyCb
  6961. \sa wolfSSL_GetDecryptVerifyCtx
  6962. */
  6963. void wolfSSL_SetDecryptVerifyCtx(WOLFSSL* ssl, void *ctx);
  6964. /*!
  6965. \brief Allows caller to retrieve the Atomic User Record Processing
  6966. Decrypt/Verify Callback Context previously stored with
  6967. wolfSSL_SetDecryptVerifyCtx().
  6968. \return pointer If successful the call will return a valid pointer to the
  6969. context.
  6970. \return NULL will be returned for a blank context.
  6971. \param none No parameters.
  6972. _Example_
  6973. \code
  6974. none
  6975. \endcode
  6976. \sa wolfSSL_CTX_SetDecryptVerifyCb
  6977. \sa wolfSSL_SetDecryptVerifyCtx
  6978. */
  6979. void* wolfSSL_GetDecryptVerifyCtx(WOLFSSL* ssl);
  6980. /*!
  6981. \brief Allows retrieval of the Hmac/Mac secret from the handshake process.
  6982. The verify parameter specifies whether this is for verification of a
  6983. peer message.
  6984. \return pointer If successful the call will return a valid pointer to the
  6985. secret. The size of the secret can be obtained from wolfSSL_GetHmacSize().
  6986. \return NULL will be returned for an error state.
  6987. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  6988. \param verify specifies whether this is for verification of a peer message.
  6989. _Example_
  6990. \code
  6991. none
  6992. \endcode
  6993. \sa wolfSSL_GetHmacSize
  6994. */
  6995. const unsigned char* wolfSSL_GetMacSecret(WOLFSSL* ssl, int verify);
  6996. /*!
  6997. \brief Allows retrieval of the client write key from the handshake process.
  6998. \return pointer If successful the call will return a valid pointer to the
  6999. key. The size of the key can be obtained from wolfSSL_GetKeySize().
  7000. \return NULL will be returned for an error state.
  7001. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7002. _Example_
  7003. \code
  7004. none
  7005. \endcode
  7006. \sa wolfSSL_GetKeySize
  7007. \sa wolfSSL_GetClientWriteIV
  7008. */
  7009. const unsigned char* wolfSSL_GetClientWriteKey(WOLFSSL*);
  7010. /*!
  7011. \brief Allows retrieval of the client write IV (initialization vector)
  7012. from the handshake process.
  7013. \return pointer If successful the call will return a valid pointer to the
  7014. IV. The size of the IV can be obtained from wolfSSL_GetCipherBlockSize().
  7015. \return NULL will be returned for an error state.
  7016. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7017. _Example_
  7018. \code
  7019. none
  7020. \endcode
  7021. \sa wolfSSL_GetCipherBlockSize()
  7022. \sa wolfSSL_GetClientWriteKey()
  7023. */
  7024. const unsigned char* wolfSSL_GetClientWriteIV(WOLFSSL*);
  7025. /*!
  7026. \brief Allows retrieval of the server write key from the handshake process.
  7027. \return pointer If successful the call will return a valid pointer to the
  7028. key. The size of the key can be obtained from wolfSSL_GetKeySize().
  7029. \return NULL will be returned for an error state.
  7030. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7031. _Example_
  7032. \code
  7033. none
  7034. \endcode
  7035. \sa wolfSSL_GetKeySize
  7036. \sa wolfSSL_GetServerWriteIV
  7037. */
  7038. const unsigned char* wolfSSL_GetServerWriteKey(WOLFSSL*);
  7039. /*!
  7040. \brief Allows retrieval of the server write IV (initialization vector)
  7041. from the handshake process.
  7042. \return pointer If successful the call will return a valid pointer to the
  7043. IV. The size of the IV can be obtained from wolfSSL_GetCipherBlockSize().
  7044. \return NULL will be returned for an error state.
  7045. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7046. \sa wolfSSL_GetCipherBlockSize
  7047. \sa wolfSSL_GetClientWriteKey
  7048. */
  7049. const unsigned char* wolfSSL_GetServerWriteIV(WOLFSSL*);
  7050. /*!
  7051. \brief Allows retrieval of the key size from the handshake process.
  7052. \return size If successful the call will return the key size in bytes.
  7053. \return BAD_FUNC_ARG will be returned for an error state.
  7054. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7055. _Example_
  7056. \code
  7057. none
  7058. \endcode
  7059. \sa wolfSSL_GetClientWriteKey
  7060. \sa wolfSSL_GetServerWriteKey
  7061. */
  7062. int wolfSSL_GetKeySize(WOLFSSL*);
  7063. /*!
  7064. \ingroup CertsKeys
  7065. \brief Returns the iv_size member of the specs structure
  7066. held in the WOLFSSL struct.
  7067. \return iv_size returns the value held in ssl->specs.iv_size.
  7068. \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.
  7069. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  7070. _Example_
  7071. \code
  7072. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  7073. WOLFSSL* ssl = wolfSSL_new(ctx);
  7074. int ivSize;
  7075. ...
  7076. ivSize = wolfSSL_GetIVSize(ssl);
  7077. if(ivSize > 0){
  7078. // ivSize holds the specs.iv_size value.
  7079. }
  7080. \endcode
  7081. \sa wolfSSL_GetKeySize
  7082. \sa wolfSSL_GetClientWriteIV
  7083. \sa wolfSSL_GetServerWriteIV
  7084. */
  7085. int wolfSSL_GetIVSize(WOLFSSL*);
  7086. /*!
  7087. \brief Allows retrieval of the side of this WOLFSSL connection.
  7088. \return success If successful the call will return either
  7089. WOLFSSL_SERVER_END or WOLFSSL_CLIENT_END depending on the
  7090. side of WOLFSSL object.
  7091. \return BAD_FUNC_ARG will be returned for an error state.
  7092. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7093. _Example_
  7094. \code
  7095. none
  7096. \endcode
  7097. \sa wolfSSL_GetClientWriteKey
  7098. \sa wolfSSL_GetServerWriteKey
  7099. */
  7100. int wolfSSL_GetSide(WOLFSSL*);
  7101. /*!
  7102. \brief Allows caller to determine if the negotiated protocol version
  7103. is at least TLS version 1.1 or greater.
  7104. \return true/false If successful the call will return 1 for true or
  7105. 0 for false.
  7106. \return BAD_FUNC_ARG will be returned for an error state.
  7107. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7108. _Example_
  7109. \code
  7110. none
  7111. \endcode
  7112. \sa wolfSSL_GetSide
  7113. */
  7114. int wolfSSL_IsTLSv1_1(WOLFSSL*);
  7115. /*!
  7116. \brief Allows caller to determine the negotiated bulk cipher algorithm
  7117. from the handshake.
  7118. \return If successful the call will return one of the following:
  7119. wolfssl_cipher_null, wolfssl_des, wolfssl_triple_des, wolfssl_aes,
  7120. wolfssl_aes_gcm, wolfssl_aes_ccm, wolfssl_camellia.
  7121. \return BAD_FUNC_ARG will be returned for an error state.
  7122. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7123. _Example_
  7124. \code
  7125. none
  7126. \endcode
  7127. \sa wolfSSL_GetCipherBlockSize
  7128. \sa wolfSSL_GetKeySize
  7129. */
  7130. int wolfSSL_GetBulkCipher(WOLFSSL*);
  7131. /*!
  7132. \brief Allows caller to determine the negotiated cipher block size from
  7133. the handshake.
  7134. \return size If successful the call will return the size in bytes of the
  7135. cipher block size.
  7136. \return BAD_FUNC_ARG will be returned for an error state.
  7137. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7138. _Example_
  7139. \code
  7140. none
  7141. \endcode
  7142. \sa wolfSSL_GetBulkCipher
  7143. \sa wolfSSL_GetKeySize
  7144. */
  7145. int wolfSSL_GetCipherBlockSize(WOLFSSL*);
  7146. /*!
  7147. \brief Allows caller to determine the negotiated aead mac size from the
  7148. handshake. For cipher type WOLFSSL_AEAD_TYPE.
  7149. \return size If successful the call will return the size in bytes of the
  7150. aead mac size.
  7151. \return BAD_FUNC_ARG will be returned for an error state.
  7152. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7153. _Example_
  7154. \code
  7155. none
  7156. \endcode
  7157. \sa wolfSSL_GetBulkCipher
  7158. \sa wolfSSL_GetKeySize
  7159. */
  7160. int wolfSSL_GetAeadMacSize(WOLFSSL*);
  7161. /*!
  7162. \brief Allows caller to determine the negotiated (h)mac size from the
  7163. handshake. For cipher types except WOLFSSL_AEAD_TYPE.
  7164. \return size If successful the call will return the size in bytes of
  7165. the (h)mac size.
  7166. \return BAD_FUNC_ARG will be returned for an error state.
  7167. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7168. _Example_
  7169. \code
  7170. none
  7171. \endcode
  7172. \sa wolfSSL_GetBulkCipher
  7173. \sa wolfSSL_GetHmacType
  7174. */
  7175. int wolfSSL_GetHmacSize(WOLFSSL*);
  7176. /*!
  7177. \brief Allows caller to determine the negotiated (h)mac type from the
  7178. handshake. For cipher types except WOLFSSL_AEAD_TYPE.
  7179. \return If successful the call will return one of the following:
  7180. MD5, SHA, SHA256, SHA384.
  7181. \return BAD_FUNC_ARG may be returned for an error state.
  7182. \return SSL_FATAL_ERROR may also be returned for an error state.
  7183. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7184. _Example_
  7185. \code
  7186. none
  7187. \endcode
  7188. \sa wolfSSL_GetBulkCipher
  7189. \sa wolfSSL_GetHmacSize
  7190. */
  7191. int wolfSSL_GetHmacType(WOLFSSL*);
  7192. /*!
  7193. \brief Allows caller to determine the negotiated cipher type
  7194. from the handshake.
  7195. \return If successful the call will return one of the following:
  7196. WOLFSSL_BLOCK_TYPE, WOLFSSL_STREAM_TYPE, WOLFSSL_AEAD_TYPE.
  7197. \return BAD_FUNC_ARG will be returned for an error state.
  7198. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7199. _Example_
  7200. \code
  7201. none
  7202. \endcode
  7203. \sa wolfSSL_GetBulkCipher
  7204. \sa wolfSSL_GetHmacType
  7205. */
  7206. int wolfSSL_GetCipherType(WOLFSSL*);
  7207. /*!
  7208. \brief Allows caller to set the Hmac Inner vector for message
  7209. sending/receiving. The result is written to inner which should
  7210. be at least wolfSSL_GetHmacSize() bytes. The size of the message
  7211. is specified by sz, content is the type of message, and verify
  7212. specifies whether this is a verification of a peer message. Valid
  7213. for cipher types excluding WOLFSSL_AEAD_TYPE.
  7214. \return 1 upon success.
  7215. \return BAD_FUNC_ARG will be returned for an error state.
  7216. \param none No parameters.
  7217. _Example_
  7218. \code
  7219. none
  7220. \endcode
  7221. \sa wolfSSL_GetBulkCipher
  7222. \sa wolfSSL_GetHmacType
  7223. */
  7224. int wolfSSL_SetTlsHmacInner(WOLFSSL* ssl, byte* inner,
  7225. word32 sz, int content, int verify);
  7226. /*!
  7227. \brief Allows caller to set the Public Key Callback for ECC Signing.
  7228. The callback should return 0 for success or < 0 for an error.
  7229. The ssl and ctx pointers are available for the user’s convenience.
  7230. in is the input buffer to sign while inSz denotes the length of the input.
  7231. out is the output buffer where the result of the signature should be stored.
  7232. outSz is an input/output variable that specifies the size of the output
  7233. buffer upon invocation and the actual size of the signature should be stored
  7234. there before returning. keyDer is the ECC Private key in ASN1 format and
  7235. keySz is the length of the key in bytes. An example callback can be found
  7236. wolfssl/test.h myEccSign().
  7237. \return none No returns.
  7238. \param none No parameters.
  7239. _Example_
  7240. \code
  7241. none
  7242. \endcode
  7243. \sa wolfSSL_SetEccSignCtx
  7244. \sa wolfSSL_GetEccSignCtx
  7245. */
  7246. void wolfSSL_CTX_SetEccSignCb(WOLFSSL_CTX* ctx, CallbackEccSign cb);
  7247. /*!
  7248. \brief Allows caller to set the Public Key Ecc Signing Callback
  7249. Context to ctx.
  7250. \return none No returns.
  7251. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7252. \param ctx a pointer to the user context to be stored
  7253. _Example_
  7254. \code
  7255. none
  7256. \endcode
  7257. \sa wolfSSL_CTX_SetEccSignCb
  7258. \sa wolfSSL_GetEccSignCtx
  7259. */
  7260. void wolfSSL_SetEccSignCtx(WOLFSSL* ssl, void *ctx);
  7261. /*!
  7262. \brief Allows caller to retrieve the Public Key Ecc Signing Callback
  7263. Context previously stored with wolfSSL_SetEccSignCtx().
  7264. \return pointer If successful the call will return a valid pointer
  7265. to the context.
  7266. \return NULL will be returned for a blank context.
  7267. \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
  7268. _Example_
  7269. \code
  7270. none
  7271. \endcode
  7272. \sa wolfSSL_CTX_SetEccSignCb
  7273. \sa wolfSSL_SetEccSignCtx
  7274. */
  7275. void* wolfSSL_GetEccSignCtx(WOLFSSL* ssl);
  7276. /*!
  7277. \brief Allows caller to set the Public Key Ecc Signing Callback
  7278. Context to ctx.
  7279. \return none No returns.
  7280. \param ctx a pointer to a WOLFSSL_CTX structure, created
  7281. with wolfSSL_CTX_new().
  7282. \param ctx a pointer to the user context to be stored
  7283. _Example_
  7284. \code
  7285. none
  7286. \endcode
  7287. \sa wolfSSL_CTX_SetEccSignCb
  7288. \sa wolfSSL_CTX_GetEccSignCtx
  7289. */
  7290. void wolfSSL_CTX_SetEccSignCtx(WOLFSSL_CTX* ctx, void *userCtx);
  7291. /*!
  7292. \brief Allows caller to retrieve the Public Key Ecc Signing Callback
  7293. Context previously stored with wolfSSL_SetEccSignCtx().
  7294. \return pointer If successful the call will return a valid pointer
  7295. to the context.
  7296. \return NULL will be returned for a blank context.
  7297. \param ctx a pointer to a WOLFSSL_CTX structure, created
  7298. with wolfSSL_CTX_new().
  7299. _Example_
  7300. \code
  7301. none
  7302. \endcode
  7303. \sa wolfSSL_CTX_SetEccSignCb
  7304. \sa wolfSSL_CTX_SetEccSignCtx
  7305. */
  7306. void* wolfSSL_CTX_GetEccSignCtx(WOLFSSL_CTX* ctx);
  7307. /*!
  7308. \brief Allows caller to set the Public Key Callback for ECC Verification.
  7309. The callback should return 0 for success or < 0 for an error.
  7310. The ssl and ctx pointers are available for the user’s convenience.
  7311. sig is the signature to verify and sigSz denotes the length of the
  7312. signature. hash is an input buffer containing the digest of the message
  7313. and hashSz denotes the length in bytes of the hash. result is an output
  7314. variable where the result of the verification should be stored, 1 for
  7315. success and 0 for failure. keyDer is the ECC Private key in ASN1
  7316. format and keySz is the length of the key in bytes. An example
  7317. callback can be found wolfssl/test.h myEccVerify().
  7318. \return none No returns.
  7319. \param none No parameters.
  7320. _Example_
  7321. \code
  7322. none
  7323. \endcode
  7324. \sa wolfSSL_SetEccVerifyCtx
  7325. \sa wolfSSL_GetEccVerifyCtx
  7326. */
  7327. void wolfSSL_CTX_SetEccVerifyCb(WOLFSSL_CTX* ctx, CallbackEccVerify cb);
  7328. /*!
  7329. \brief Allows caller to set the Public Key Ecc Verification Callback
  7330. Context to ctx.
  7331. \return none No returns.
  7332. \param none No parameters.
  7333. _Example_
  7334. \code
  7335. none
  7336. \endcode
  7337. \sa wolfSSL_CTX_SetEccVerifyCb
  7338. \sa wolfSSL_GetEccVerifyCtx
  7339. */
  7340. void wolfSSL_SetEccVerifyCtx(WOLFSSL* ssl, void *ctx);
  7341. /*!
  7342. \brief Allows caller to retrieve the Public Key Ecc Verification Callback
  7343. Context previously stored with wolfSSL_SetEccVerifyCtx().
  7344. \return pointer If successful the call will return a valid pointer to the
  7345. context.
  7346. \return NULL will be returned for a blank context.
  7347. \param none No parameters.
  7348. _Example_
  7349. \code
  7350. none
  7351. \endcode
  7352. \sa wolfSSL_CTX_SetEccVerifyCb
  7353. \sa wolfSSL_SetEccVerifyCtx
  7354. */
  7355. void* wolfSSL_GetEccVerifyCtx(WOLFSSL* ssl);
  7356. /*!
  7357. \brief Allows caller to set the Public Key Callback for RSA Signing.
  7358. The callback should return 0 for success or < 0 for an error.
  7359. The ssl and ctx pointers are available for the user’s convenience.
  7360. in is the input buffer to sign while inSz denotes the length of the input.
  7361. out is the output buffer where the result of the signature should be stored.
  7362. outSz is an input/output variable that specifies the size of the output
  7363. buffer upon invocation and the actual size of the signature should be
  7364. stored there before returning. keyDer is the RSA Private key in ASN1 format
  7365. and keySz is the length of the key in bytes. An example callback can be
  7366. found wolfssl/test.h myRsaSign().
  7367. \return none No returns.
  7368. \param none No parameters.
  7369. _Example_
  7370. \code
  7371. none
  7372. \endcode
  7373. \sa wolfSSL_SetRsaSignCtx
  7374. \sa wolfSSL_GetRsaSignCtx
  7375. */
  7376. void wolfSSL_CTX_SetRsaSignCb(WOLFSSL_CTX* ctx, CallbackRsaSign cb);
  7377. /*!
  7378. \brief Allows caller to set the Public Key RSA Signing Callback Context
  7379. to ctx.
  7380. \return none No Returns.
  7381. \param none No parameters.
  7382. _Example_
  7383. \code
  7384. none
  7385. \endcode
  7386. \sa wolfSSL_CTX_SetRsaSignCb
  7387. \sa wolfSSL_GetRsaSignCtx
  7388. */
  7389. void wolfSSL_SetRsaSignCtx(WOLFSSL* ssl, void *ctx);
  7390. /*!
  7391. \brief Allows caller to retrieve the Public Key RSA Signing Callback
  7392. Context previously stored with wolfSSL_SetRsaSignCtx().
  7393. \return pointer If successful the call will return a valid pointer to the
  7394. context.
  7395. \return NULL will be returned for a blank context.
  7396. \param none No parameters.
  7397. \param none No parameters.
  7398. _Example_
  7399. \code
  7400. none
  7401. \endcode
  7402. \sa wolfSSL_CTX_SetRsaSignCb
  7403. \sa wolfSSL_SetRsaSignCtx
  7404. */
  7405. void* wolfSSL_GetRsaSignCtx(WOLFSSL* ssl);
  7406. /*!
  7407. \brief Allows caller to set the Public Key Callback for RSA Verification.
  7408. The callback should return the number of plaintext bytes for success or
  7409. < 0 for an error. The ssl and ctx pointers are available for the user’s
  7410. convenience. sig is the signature to verify and sigSz denotes the length
  7411. of the signature. out should be set to the beginning of the verification
  7412. buffer after the decryption process and any padding. keyDer is the RSA
  7413. Public key in ASN1 format and keySz is the length of the key in bytes.
  7414. An example callback can be found wolfssl/test.h myRsaVerify().
  7415. \return none No returns.
  7416. \param none No parameters.
  7417. \sa wolfSSL_SetRsaVerifyCtx
  7418. \sa wolfSSL_GetRsaVerifyCtx
  7419. */
  7420. void wolfSSL_CTX_SetRsaVerifyCb(WOLFSSL_CTX* ctx, CallbackRsaVerify cb);
  7421. /*!
  7422. \brief Allows caller to set the Public Key RSA Verification Callback
  7423. Context to ctx.
  7424. \return none No returns.
  7425. \param none No parameters.
  7426. _Example_
  7427. \code
  7428. none
  7429. \endcode
  7430. \sa wolfSSL_CTX_SetRsaVerifyCb
  7431. \sa wolfSSL_GetRsaVerifyCtx
  7432. */
  7433. void wolfSSL_SetRsaVerifyCtx(WOLFSSL* ssl, void *ctx);
  7434. /*!
  7435. \brief Allows caller to retrieve the Public Key RSA Verification Callback
  7436. Context previously stored with wolfSSL_SetRsaVerifyCtx().
  7437. \return pointer If successful the call will return a valid pointer to
  7438. the context.
  7439. \return NULL will be returned for a blank context.
  7440. \param none No parameters.
  7441. _Example_
  7442. \code
  7443. none
  7444. \endcode
  7445. \sa wolfSSL_CTX_SetRsaVerifyCb
  7446. \sa wolfSSL_SetRsaVerifyCtx
  7447. */
  7448. void* wolfSSL_GetRsaVerifyCtx(WOLFSSL* ssl);
  7449. /*!
  7450. \brief Allows caller to set the Public Key Callback for RSA Public
  7451. Encrypt. The callback should return 0 for success or < 0 for an error.
  7452. The ssl and ctx pointers are available for the user’s convenience.
  7453. in is the input buffer to encrypt while inSz denotes the length of
  7454. the input. out is the output buffer where the result of the encryption
  7455. should be stored. outSz is an input/output variable that specifies
  7456. the size of the output buffer upon invocation and the actual size of
  7457. the encryption should be stored there before returning. keyDer is the
  7458. RSA Public key in ASN1 format and keySz is the length of the key in
  7459. bytes. An example callback can be found wolfssl/test.h myRsaEnc().
  7460. \return none No returns.
  7461. \param none No parameters.
  7462. _Examples_
  7463. \code
  7464. none
  7465. \endcode
  7466. \sa wolfSSL_SetRsaEncCtx
  7467. \sa wolfSSL_GetRsaEncCtx
  7468. */
  7469. void wolfSSL_CTX_SetRsaEncCb(WOLFSSL_CTX* ctx, CallbackRsaEnc cb);
  7470. /*!
  7471. \brief Allows caller to set the Public Key RSA Public Encrypt
  7472. Callback Context to ctx.
  7473. \return none No returns.
  7474. \param none No parameters.
  7475. _Example_
  7476. \code
  7477. none
  7478. \endcode
  7479. \sa wolfSSL_CTX_SetRsaEncCb
  7480. \sa wolfSSL_GetRsaEncCtx
  7481. */
  7482. void wolfSSL_SetRsaEncCtx(WOLFSSL* ssl, void *ctx);
  7483. /*!
  7484. \brief Allows caller to retrieve the Public Key RSA Public Encrypt
  7485. Callback Context previously stored with wolfSSL_SetRsaEncCtx().
  7486. \return pointer If successful the call will return a valid pointer
  7487. to the context.
  7488. \return NULL will be returned for a blank context.
  7489. \param none No parameters.
  7490. _Example_
  7491. \code
  7492. none
  7493. \endcode
  7494. \sa wolfSSL_CTX_SetRsaEncCb
  7495. \sa wolfSSL_SetRsaEncCtx
  7496. */
  7497. void* wolfSSL_GetRsaEncCtx(WOLFSSL* ssl);
  7498. /*!
  7499. \brief Allows caller to set the Public Key Callback for RSA Private
  7500. Decrypt. The callback should return the number of plaintext bytes
  7501. for success or < 0 for an error. The ssl and ctx pointers are available
  7502. for the user’s convenience. in is the input buffer to decrypt and inSz
  7503. denotes the length of the input. out should be set to the beginning
  7504. of the decryption buffer after the decryption process and any padding.
  7505. keyDer is the RSA Private key in ASN1 format and keySz is the length
  7506. of the key in bytes. An example callback can be found
  7507. wolfssl/test.h myRsaDec().
  7508. \return none No returns.
  7509. \param none No parameters.
  7510. _Example_
  7511. \code
  7512. none
  7513. \endcode
  7514. \sa wolfSSL_SetRsaDecCtx
  7515. \sa wolfSSL_GetRsaDecCtx
  7516. */
  7517. void wolfSSL_CTX_SetRsaDecCb(WOLFSSL_CTX* ctx, CallbackRsaDec cb);
  7518. /*!
  7519. \brief Allows caller to set the Public Key RSA Private Decrypt
  7520. Callback Context to ctx.
  7521. \return none No returns.
  7522. \param none No parameters.
  7523. _Example_
  7524. \code
  7525. none
  7526. \endcode
  7527. \sa wolfSSL_CTX_SetRsaDecCb
  7528. \sa wolfSSL_GetRsaDecCtx
  7529. */
  7530. void wolfSSL_SetRsaDecCtx(WOLFSSL* ssl, void *ctx);
  7531. /*!
  7532. \brief Allows caller to retrieve the Public Key RSA Private Decrypt
  7533. Callback Context previously stored with wolfSSL_SetRsaDecCtx().
  7534. \return pointer If successful the call will return a valid pointer
  7535. to the context.
  7536. \return NULL will be returned for a blank context.
  7537. \param none No parameters.
  7538. _Example_
  7539. \code
  7540. none
  7541. \endcode
  7542. \sa wolfSSL_CTX_SetRsaDecCb
  7543. \sa wolfSSL_SetRsaDecCtx
  7544. */
  7545. void* wolfSSL_GetRsaDecCtx(WOLFSSL* ssl);
  7546. /*!
  7547. \brief This function registers a callback with the SSL context
  7548. (WOLFSSL_CTX) to be called when a new CA certificate is loaded
  7549. into wolfSSL. The callback is given a buffer with the DER-encoded
  7550. certificate.
  7551. \return none No return.
  7552. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  7553. \param callback function to be registered as the CA callback for the
  7554. wolfSSL context, ctx. The signature of this function must follow that
  7555. as shown above in the Synopsis section.
  7556. _Example_
  7557. \code
  7558. WOLFSSL_CTX* ctx = 0;
  7559. // CA callback prototype
  7560. int MyCACallback(unsigned char *der, int sz, int type);
  7561. // Register the custom CA callback with the SSL context
  7562. wolfSSL_CTX_SetCACb(ctx, MyCACallback);
  7563. int MyCACallback(unsigned char* der, int sz, int type)
  7564. {
  7565. // custom CA callback function, DER-encoded cert
  7566. // located in “der” of size “sz” with type “type”
  7567. }
  7568. \endcode
  7569. \sa wolfSSL_CTX_load_verify_locations
  7570. */
  7571. void wolfSSL_CTX_SetCACb(WOLFSSL_CTX* ctx, CallbackCACache cb);
  7572. /*!
  7573. \ingroup CertManager
  7574. \brief Allocates and initializes a new Certificate Manager context.
  7575. This context may be used independent of SSL needs. It may be used to
  7576. load certificates, verify certificates, and check the revocation status.
  7577. \return WOLFSSL_CERT_MANAGER If successful the call will return a valid
  7578. WOLFSSL_CERT_MANAGER pointer.
  7579. \return NULL will be returned for an error state.
  7580. \param none No parameters.
  7581. \sa wolfSSL_CertManagerFree
  7582. */
  7583. WOLFSSL_CERT_MANAGER* wolfSSL_CertManagerNew_ex(void* heap);
  7584. /*!
  7585. \ingroup CertManager
  7586. \brief Allocates and initializes a new Certificate Manager context.
  7587. This context may be used independent of SSL needs. It may be used to
  7588. load certificates, verify certificates, and check the revocation status.
  7589. \return WOLFSSL_CERT_MANAGER If successful the call will return a
  7590. valid WOLFSSL_CERT_MANAGER pointer.
  7591. \return NULL will be returned for an error state.
  7592. \param none No parameters.
  7593. _Example_
  7594. \code
  7595. #import <wolfssl/ssl.h>
  7596. WOLFSSL_CERT_MANAGER* cm;
  7597. cm = wolfSSL_CertManagerNew();
  7598. if (cm == NULL) {
  7599. // error creating new cert manager
  7600. }
  7601. \endcode
  7602. \sa wolfSSL_CertManagerFree
  7603. */
  7604. WOLFSSL_CERT_MANAGER* wolfSSL_CertManagerNew(void);
  7605. /*!
  7606. \ingroup CertManager
  7607. \brief Frees all resources associated with the Certificate Manager
  7608. context. Call this when you no longer need to use the Certificate Manager.
  7609. \return none
  7610. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
  7611. wolfSSL_CertManagerNew().
  7612. _Example_
  7613. \code
  7614. #include <wolfssl/ssl.h>
  7615. WOLFSSL_CERT_MANAGER* cm;
  7616. ...
  7617. wolfSSL_CertManagerFree(cm);
  7618. \endcode
  7619. \sa wolfSSL_CertManagerNew
  7620. */
  7621. void wolfSSL_CertManagerFree(WOLFSSL_CERT_MANAGER*);
  7622. /*!
  7623. \ingroup CertManager
  7624. \brief Specifies the locations for CA certificate loading into the
  7625. manager context. The PEM certificate CAfile may contain several
  7626. trusted CA certificates. If CApath is not NULL it specifies a
  7627. directory containing CA certificates in PEM format.
  7628. \return SSL_SUCCESS If successful the call will return.
  7629. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  7630. \return SSL_BAD_FILE will be returned if the file doesn’t exist,
  7631. can’t be read, or is corrupted.
  7632. \return MEMORY_E will be returned if an out of memory condition occurs.
  7633. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  7634. \return BAD_FUNC_ARG is the error that will be returned if a
  7635. pointer is not provided.
  7636. \return SSL_FATAL_ERROR - will be returned upon failure.
  7637. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created
  7638. using wolfSSL_CertManagerNew().
  7639. \param file pointer to the name of the file containing CA
  7640. certificates to load.
  7641. \param path pointer to the name of a directory path containing CA c
  7642. ertificates to load. The NULL pointer may be used if no
  7643. certificate directory is desired.
  7644. _Example_
  7645. \code
  7646. #include <wolfssl/ssl.h>
  7647. int ret = 0;
  7648. WOLFSSL_CERT_MANAGER* cm;
  7649. ...
  7650. ret = wolfSSL_CertManagerLoadCA(cm, “path/to/cert-file.pem”, 0);
  7651. if (ret != SSL_SUCCESS) {
  7652. // error loading CA certs into cert manager
  7653. }
  7654. \endcode
  7655. \sa wolfSSL_CertManagerVerify
  7656. */
  7657. int wolfSSL_CertManagerLoadCA(WOLFSSL_CERT_MANAGER* cm, const char* f,
  7658. const char* d);
  7659. /*!
  7660. \ingroup CertManager
  7661. \brief Loads the CA Buffer by calling wolfSSL_CTX_load_verify_buffer and
  7662. returning that result using a temporary cm so as not to lose the information
  7663. in the cm passed into the function.
  7664. \return SSL_FATAL_ERROR is returned if the WOLFSSL_CERT_MANAGER struct is
  7665. NULL or if wolfSSL_CTX_new() returns NULL.
  7666. \return SSL_SUCCESS is returned for a successful execution.
  7667. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
  7668. wolfSSL_CertManagerNew().
  7669. \param in buffer for cert information.
  7670. \param sz length of the buffer.
  7671. \param format certificate format, either PEM or DER.
  7672. _Example_
  7673. \code
  7674. WOLFSSL_CERT_MANAGER* cm = (WOLFSSL_CERT_MANAGER*)vp;
  7675. const unsigned char* in;
  7676. long sz;
  7677. int format;
  7678. if(wolfSSL_CertManagerLoadCABuffer(vp, sz, format) != SSL_SUCCESS){
  7679. Error returned. Failure case code block.
  7680. }
  7681. \endcode
  7682. \sa wolfSSL_CTX_load_verify_buffer
  7683. \sa ProcessChainBuffer
  7684. \sa ProcessBuffer
  7685. \sa cm_pick_method
  7686. */
  7687. int wolfSSL_CertManagerLoadCABuffer(WOLFSSL_CERT_MANAGER* cm,
  7688. const unsigned char* in, long sz, int format);
  7689. /*!
  7690. \ingroup CertManager
  7691. \brief This function unloads the CA signer list.
  7692. \return SSL_SUCCESS returned on successful execution of the function.
  7693. \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL.
  7694. \return BAD_MUTEX_E returned if there was a mutex error.
  7695. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure,
  7696. created using wolfSSL_CertManagerNew().
  7697. _Example_
  7698. \code
  7699. #include <wolfssl/ssl.h>
  7700. WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
  7701. WOLFSSL_CERT_MANAGER* cm = wolfSSL_CTX_GetCertManager(ctx);
  7702. ...
  7703. if(wolfSSL_CertManagerUnloadCAs(cm) != SSL_SUCCESS){
  7704. Failure case.
  7705. }
  7706. \endcode
  7707. \sa UnlockMutex
  7708. */
  7709. int wolfSSL_CertManagerUnloadCAs(WOLFSSL_CERT_MANAGER* cm);
  7710. /*!
  7711. \ingroup CertManager
  7712. \brief This function unloads intermediate certificates add to the CA
  7713. signer list.
  7714. \return SSL_SUCCESS returned on successful execution of the function.
  7715. \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL.
  7716. \return BAD_MUTEX_E returned if there was a mutex error.
  7717. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure,
  7718. created using wolfSSL_CertManagerNew().
  7719. _Example_
  7720. \code
  7721. #include <wolfssl/ssl.h>
  7722. WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
  7723. WOLFSSL_CERT_MANAGER* cm = wolfSSL_CTX_GetCertManager(ctx);
  7724. ...
  7725. if(wolfSSL_CertManagerUnloadIntermediateCerts(cm) != SSL_SUCCESS){
  7726. Failure case.
  7727. }
  7728. \endcode
  7729. \sa UnlockMutex
  7730. */
  7731. int wolfSSL_CertManagerUnloadIntermediateCerts(WOLFSSL_CERT_MANAGER* cm);
  7732. /*!
  7733. \ingroup CertManager
  7734. \brief The function will free the Trusted Peer linked list and unlocks
  7735. the trusted peer list.
  7736. \return SSL_SUCCESS if the function completed normally.
  7737. \return BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER is NULL.
  7738. \return BAD_MUTEX_E mutex error if tpLock, a member of the
  7739. WOLFSSL_CERT_MANAGER struct, is 0 (nill).
  7740. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
  7741. wolfSSL_CertManagerNew().
  7742. _Example_
  7743. \code
  7744. #include <wolfssl/ssl.h>
  7745. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(Protocol define);
  7746. WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew();
  7747. ...
  7748. if(wolfSSL_CertManagerUnload_trust_peers(cm) != SSL_SUCCESS){
  7749. The function did not execute successfully.
  7750. }
  7751. \endcode
  7752. \sa UnLockMutex
  7753. */
  7754. int wolfSSL_CertManagerUnload_trust_peers(WOLFSSL_CERT_MANAGER* cm);
  7755. /*!
  7756. \ingroup CertManager
  7757. \brief Specifies the certificate to verify with the Certificate Manager
  7758. context. The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1.
  7759. \return SSL_SUCCESS If successful.
  7760. \return ASN_SIG_CONFIRM_E will be returned if the signature could not be
  7761. verified.
  7762. \return ASN_SIG_OID_E will be returned if the signature type is not
  7763. supported.
  7764. \return CRL_CERT_REVOKED is an error that is returned if this certificate
  7765. has been revoked.
  7766. \return CRL_MISSING is an error that is returned if a current issuer CRL is
  7767. not available.
  7768. \return ASN_BEFORE_DATE_E will be returned if the current date is before the
  7769. before date.
  7770. \return ASN_AFTER_DATE_E will be returned if the current date is after the
  7771. after date.
  7772. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  7773. \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
  7774. read, or is corrupted.
  7775. \return MEMORY_E will be returned if an out of memory condition occurs.
  7776. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  7777. \return BAD_FUNC_ARG is the error that will be returned if a pointer is
  7778. not provided.
  7779. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
  7780. wolfSSL_CertManagerNew().
  7781. \param fname pointer to the name of the file containing the certificates
  7782. to verify.
  7783. \param format format of the certificate to verify - either
  7784. SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
  7785. _Example_
  7786. \code
  7787. int ret = 0;
  7788. WOLFSSL_CERT_MANAGER* cm;
  7789. ...
  7790. ret = wolfSSL_CertManagerVerify(cm, “path/to/cert-file.pem”,
  7791. SSL_FILETYPE_PEM);
  7792. if (ret != SSL_SUCCESS) {
  7793. error verifying certificate
  7794. }
  7795. \endcode
  7796. \sa wolfSSL_CertManagerLoadCA
  7797. \sa wolfSSL_CertManagerVerifyBuffer
  7798. */
  7799. int wolfSSL_CertManagerVerify(WOLFSSL_CERT_MANAGER* cm, const char* f,
  7800. int format);
  7801. /*!
  7802. \ingroup CertManager
  7803. \brief Specifies the certificate buffer to verify with the Certificate
  7804. Manager context. The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1.
  7805. \return SSL_SUCCESS If successful.
  7806. \return ASN_SIG_CONFIRM_E will be returned if the signature could not
  7807. be verified.
  7808. \return ASN_SIG_OID_E will be returned if the signature type is not
  7809. supported.
  7810. \return CRL_CERT_REVOKED is an error that is returned if this certificate
  7811. has been revoked.
  7812. \return CRL_MISSING is an error that is returned if a current issuer CRL
  7813. is not available.
  7814. \return ASN_BEFORE_DATE_E will be returned if the current date is before
  7815. the before date.
  7816. \return ASN_AFTER_DATE_E will be returned if the current date is after
  7817. the after date.
  7818. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
  7819. \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t
  7820. be read, or is corrupted.
  7821. \return MEMORY_E will be returned if an out of memory condition occurs.
  7822. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
  7823. \return BAD_FUNC_ARG is the error that will be returned if a pointer
  7824. is not provided.
  7825. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
  7826. wolfSSL_CertManagerNew().
  7827. \param buff buffer containing the certificates to verify.
  7828. \param sz size of the buffer, buf.
  7829. \param format format of the certificate to verify, located in buf - either
  7830. SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
  7831. _Example_
  7832. \code
  7833. #include <wolfssl/ssl.h>
  7834. int ret = 0;
  7835. int sz = 0;
  7836. WOLFSSL_CERT_MANAGER* cm;
  7837. byte certBuff[...];
  7838. ...
  7839. ret = wolfSSL_CertManagerVerifyBuffer(cm, certBuff, sz, SSL_FILETYPE_PEM);
  7840. if (ret != SSL_SUCCESS) {
  7841. error verifying certificate
  7842. }
  7843. \endcode
  7844. \sa wolfSSL_CertManagerLoadCA
  7845. \sa wolfSSL_CertManagerVerify
  7846. */
  7847. int wolfSSL_CertManagerVerifyBuffer(WOLFSSL_CERT_MANAGER* cm,
  7848. const unsigned char* buff, long sz, int format);
  7849. /*!
  7850. \ingroup CertManager
  7851. \brief The function sets the verifyCallback function in the Certificate
  7852. Manager. If present, it will be called for each cert loaded. If there is
  7853. a verification error, the verify callback can be used to over-ride the
  7854. error.
  7855. \return none No return.
  7856. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
  7857. wolfSSL_CertManagerNew().
  7858. \param vc a VerifyCallback function pointer to the callback routine
  7859. _Example_
  7860. \code
  7861. #include <wolfssl/ssl.h>
  7862. int myVerify(int preverify, WOLFSSL_X509_STORE_CTX* store)
  7863. { // do custom verification of certificate }
  7864. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(Protocol define);
  7865. WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew();
  7866. ...
  7867. wolfSSL_CertManagerSetVerify(cm, myVerify);
  7868. \endcode
  7869. \sa wolfSSL_CertManagerVerify
  7870. */
  7871. void wolfSSL_CertManagerSetVerify(WOLFSSL_CERT_MANAGER* cm,
  7872. VerifyCallback vc);
  7873. /*!
  7874. \brief Check CRL if the option is enabled and compares the cert to the
  7875. CRL list.
  7876. \return SSL_SUCCESS returns if the function returned as expected. If
  7877. the crlEnabled member of the WOLFSSL_CERT_MANAGER struct is turned on.
  7878. \return MEMORY_E returns if the allocated memory failed.
  7879. \return BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER is NULL.
  7880. \param cm a pointer to a WOLFSSL_CERT_MANAGER struct.
  7881. \param der pointer to a DER formatted certificate.
  7882. \param sz size of the certificate.
  7883. _Example_
  7884. \code
  7885. WOLFSSL_CERT_MANAGER* cm;
  7886. byte* der;
  7887. int sz; // size of der
  7888. ...
  7889. if(wolfSSL_CertManagerCheckCRL(cm, der, sz) != SSL_SUCCESS){
  7890. // Error returned. Deal with failure case.
  7891. }
  7892. \endcode
  7893. \sa CheckCertCRL
  7894. \sa ParseCertRelative
  7895. \sa wolfSSL_CertManagerSetCRL_CB
  7896. \sa InitDecodedCert
  7897. */
  7898. int wolfSSL_CertManagerCheckCRL(WOLFSSL_CERT_MANAGER* cm,
  7899. unsigned char* der, int sz);
  7900. /*!
  7901. \ingroup CertManager
  7902. \brief Turns on Certificate Revocation List checking when verifying
  7903. certificates with the Certificate Manager. By default, CRL checking
  7904. is off. options include WOLFSSL_CRL_CHECKALL which performs CRL
  7905. checking on each certificate in the chain versus the Leaf certificate
  7906. only which is the default.
  7907. \return SSL_SUCCESS If successful the call will return.
  7908. \return NOT_COMPILED_IN will be returned if wolfSSL was not built with
  7909. CRL enabled.
  7910. \return MEMORY_E will be returned if an out of memory condition occurs.
  7911. \return BAD_FUNC_ARG is the error that will be returned if a pointer
  7912. is not provided.
  7913. \return SSL_FAILURE will be returned if the CRL context cannot be
  7914. initialized properly.
  7915. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
  7916. wolfSSL_CertManagerNew().
  7917. \param options options to use when enabling the Certification Manager, cm.
  7918. _Example_
  7919. \code
  7920. #include <wolfssl/ssl.h>
  7921. int ret = 0;
  7922. WOLFSSL_CERT_MANAGER* cm;
  7923. ...
  7924. ret = wolfSSL_CertManagerEnableCRL(cm, 0);
  7925. if (ret != SSL_SUCCESS) {
  7926. error enabling cert manager
  7927. }
  7928. ...
  7929. \endcode
  7930. \sa wolfSSL_CertManagerDisableCRL
  7931. */
  7932. int wolfSSL_CertManagerEnableCRL(WOLFSSL_CERT_MANAGER* cm,
  7933. int options);
  7934. /*!
  7935. \ingroup CertManager
  7936. \brief Turns off Certificate Revocation List checking when verifying
  7937. certificates with the Certificate Manager. By default, CRL checking is
  7938. off. You can use this function to temporarily or permanently disable CRL
  7939. checking with this Certificate Manager context that previously had CRL
  7940. checking enabled.
  7941. \return SSL_SUCCESS If successful the call will return.
  7942. \return BAD_FUNC_ARG is the error that will be returned if a function
  7943. pointer is not provided.
  7944. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
  7945. wolfSSL_CertManagerNew().
  7946. _Example_
  7947. \code
  7948. #include <wolfssl/ssl.h>
  7949. int ret = 0;
  7950. WOLFSSL_CERT_MANAGER* cm;
  7951. ...
  7952. ret = wolfSSL_CertManagerDisableCRL(cm);
  7953. if (ret != SSL_SUCCESS) {
  7954. error disabling cert manager
  7955. }
  7956. ...
  7957. \endcode
  7958. \sa wolfSSL_CertManagerEnableCRL
  7959. */
  7960. int wolfSSL_CertManagerDisableCRL(WOLFSSL_CERT_MANAGER*);
  7961. /*!
  7962. \ingroup CertManager
  7963. \brief Error checks and passes through to LoadCRL() in order to load the
  7964. cert into the CRL for revocation checking. An updated CRL can be loaded by
  7965. first calling wolfSSL_CertManagerFreeCRL, then loading the new CRL.
  7966. \return SSL_SUCCESS if there is no error in wolfSSL_CertManagerLoadCRL and
  7967. if LoadCRL returns successfully.
  7968. \return BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER struct is NULL.
  7969. \return SSL_FATAL_ERROR if wolfSSL_CertManagerEnableCRL returns anything
  7970. other than SSL_SUCCESS.
  7971. \return BAD_PATH_ERROR if the path is NULL.
  7972. \return MEMORY_E if LoadCRL fails to allocate heap memory.
  7973. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
  7974. wolfSSL_CertManagerNew().
  7975. \param path a constant char pointer holding the CRL path.
  7976. \param type type of certificate to be loaded.
  7977. \param monitor requests monitoring in LoadCRL().
  7978. _Example_
  7979. \code
  7980. #include <wolfssl/ssl.h>
  7981. int wolfSSL_LoadCRL(WOLFSSL* ssl, const char* path, int type,
  7982. int monitor);
  7983. wolfSSL_CertManagerLoadCRL(SSL_CM(ssl), path, type, monitor);
  7984. \endcode
  7985. \sa wolfSSL_CertManagerEnableCRL
  7986. \sa wolfSSL_LoadCRL
  7987. \sa wolfSSL_CertManagerFreeCRL
  7988. */
  7989. int wolfSSL_CertManagerLoadCRL(WOLFSSL_CERT_MANAGER* cm,
  7990. const char* path, int type, int monitor);
  7991. /*!
  7992. \ingroup CertManager
  7993. \brief The function loads the CRL file by calling BufferLoadCRL.
  7994. \return SSL_SUCCESS returned if the function completed without errors.
  7995. \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL.
  7996. \return SSL_FATAL_ERROR returned if there is an error associated
  7997. with the WOLFSSL_CERT_MANAGER.
  7998. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure.
  7999. \param buff a constant byte type and is the buffer.
  8000. \param sz a long int representing the size of the buffer.
  8001. \param type a long integer that holds the certificate type.
  8002. _Example_
  8003. \code
  8004. #include <wolfssl/ssl.h>
  8005. WOLFSSL_CERT_MANAGER* cm;
  8006. const unsigned char* buff;
  8007. long sz; size of buffer
  8008. int type; cert type
  8009. ...
  8010. int ret = wolfSSL_CertManagerLoadCRLBuffer(cm, buff, sz, type);
  8011. if(ret == SSL_SUCCESS){
  8012. return ret;
  8013. } else {
  8014. Failure case.
  8015. }
  8016. \endcode
  8017. \sa BufferLoadCRL
  8018. \sa wolfSSL_CertManagerEnableCRL
  8019. */
  8020. int wolfSSL_CertManagerLoadCRLBuffer(WOLFSSL_CERT_MANAGER* cm,
  8021. const unsigned char* buff, long sz,
  8022. int type);
  8023. /*!
  8024. \ingroup CertManager
  8025. \brief This function sets the CRL Certificate Manager callback. If
  8026. HAVE_CRL is defined and a matching CRL record is not found then the
  8027. cbMissingCRL is called (set via wolfSSL_CertManagerSetCRL_Cb). This
  8028. allows you to externally retrieve the CRL and load it.
  8029. \return SSL_SUCCESS returned upon successful execution of the function and
  8030. subroutines.
  8031. \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL.
  8032. \param cm the WOLFSSL_CERT_MANAGER structure holding the information for
  8033. the certificate.
  8034. \param cb a function pointer to (*CbMissingCRL) that is set to the
  8035. cbMissingCRL member of the WOLFSSL_CERT_MANAGER.
  8036. _Example_
  8037. \code
  8038. #include <wolfssl/ssl.h>
  8039. WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
  8040. WOLFSSL* ssl = wolfSSL_new(ctx);
  8041. void cb(const char* url){
  8042. Function body.
  8043. }
  8044. CbMissingCRL cb = CbMissingCRL;
  8045. if(ctx){
  8046. return wolfSSL_CertManagerSetCRL_Cb(SSL_CM(ssl), cb);
  8047. }
  8048. \endcode
  8049. \sa CbMissingCRL
  8050. \sa wolfSSL_SetCRL_Cb
  8051. */
  8052. int wolfSSL_CertManagerSetCRL_Cb(WOLFSSL_CERT_MANAGER* cm,
  8053. CbMissingCRL cb);
  8054. /*!
  8055. \ingroup CertManager
  8056. \brief This function frees the CRL stored in the Cert Manager. An
  8057. application can update the CRL by calling wolfSSL_CertManagerFreeCRL
  8058. and then loading the new CRL.
  8059. \return SSL_SUCCESS returned upon successful execution of the function and
  8060. subroutines.
  8061. \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL.
  8062. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
  8063. wolfSSL_CertManagerNew().
  8064. _Example_
  8065. \code
  8066. #include <wolfssl/ssl.h>
  8067. const char* crl1 = "./certs/crl/crl.pem";
  8068. WOLFSSL_CERT_MANAGER* cm = NULL;
  8069. cm = wolfSSL_CertManagerNew();
  8070. wolfSSL_CertManagerLoadCRL(cm, crl1, WOLFSSL_FILETYPE_PEM, 0);
  8071. wolfSSL_CertManagerFreeCRL(cm);
  8072. \endcode
  8073. \sa wolfSSL_CertManagerLoadCRL
  8074. */
  8075. int wolfSSL_CertManagerFreeCRL(WOLFSSL_CERT_MANAGER* cm);
  8076. /*!
  8077. \ingroup CertManager
  8078. \brief The function enables the WOLFSSL_CERT_MANAGER’s member, ocspEnabled
  8079. to signify that the OCSP check option is enabled.
  8080. \return SSL_SUCCESS returned on successful execution of the function. The
  8081. ocspEnabled member of the WOLFSSL_CERT_MANAGER is enabled.
  8082. \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is
  8083. NULL or if an argument value that is not allowed is passed to a subroutine.
  8084. \return MEMORY_E returned if there is an error allocating memory within
  8085. this function or a subroutine.
  8086. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
  8087. wolfSSL_CertManagerNew().
  8088. \param der a byte pointer to the certificate.
  8089. \param sz an int type representing the size of the DER cert.
  8090. _Example_
  8091. \code
  8092. #import <wolfssl/ssl.h>
  8093. WOLFSSL* ssl = wolfSSL_new(ctx);
  8094. byte* der;
  8095. int sz; size of der
  8096. ...
  8097. if(wolfSSL_CertManagerCheckOCSP(cm, der, sz) != SSL_SUCCESS){
  8098. Failure case.
  8099. }
  8100. \endcode
  8101. \sa ParseCertRelative
  8102. \sa CheckCertOCSP
  8103. */
  8104. int wolfSSL_CertManagerCheckOCSP(WOLFSSL_CERT_MANAGER* cm,
  8105. unsigned char* der, int sz);
  8106. /*!
  8107. \ingroup CertManager
  8108. \brief Turns on OCSP if it’s turned off and if compiled with the
  8109. set option available.
  8110. \return SSL_SUCCESS returned if the function call is successful.
  8111. \return BAD_FUNC_ARG if cm struct is NULL.
  8112. \return MEMORY_E if WOLFSSL_OCSP struct value is NULL.
  8113. \return SSL_FAILURE initialization of WOLFSSL_OCSP struct fails
  8114. to initialize.
  8115. \return NOT_COMPILED_IN build not compiled with correct feature enabled.
  8116. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
  8117. wolfSSL_CertManagerNew().
  8118. \param options used to set values in WOLFSSL_CERT_MANAGER struct.
  8119. _Example_
  8120. \code
  8121. #include <wolfssl/ssl.h>
  8122. WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
  8123. WOLFSSL* ssl = wolfSSL_new(ctx);
  8124. WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew();
  8125. int options;
  8126. if(wolfSSL_CertManagerEnableOCSP(SSL_CM(ssl), options) != SSL_SUCCESS){
  8127. Failure case.
  8128. }
  8129. \endcode
  8130. \sa wolfSSL_CertManagerNew
  8131. */
  8132. int wolfSSL_CertManagerEnableOCSP(WOLFSSL_CERT_MANAGER* cm,
  8133. int options);
  8134. /*!
  8135. \ingroup CertManager
  8136. \brief Disables OCSP certificate revocation.
  8137. \return SSL_SUCCESS wolfSSL_CertMangerDisableCRL successfully disabled the
  8138. crlEnabled member of the WOLFSSL_CERT_MANAGER structure.
  8139. \return BAD_FUNC_ARG the WOLFSSL structure was NULL.
  8140. \param ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8141. _Example_
  8142. \code
  8143. #include <wolfssl/ssl.h>
  8144. WOLFSSL_CTX* ctx = wolfSSL_CTX_new(method);
  8145. WOLFSSL* ssl = wolfSSL_new(ctx);
  8146. ...
  8147. if(wolfSSL_CertManagerDisableOCSP(ssl) != SSL_SUCCESS){
  8148. Fail case.
  8149. }
  8150. \endcode
  8151. \sa wolfSSL_DisableCRL
  8152. */
  8153. int wolfSSL_CertManagerDisableOCSP(WOLFSSL_CERT_MANAGER*);
  8154. /*!
  8155. \ingroup CertManager
  8156. \brief The function copies the url to the ocspOverrideURL member of the
  8157. WOLFSSL_CERT_MANAGER structure.
  8158. \return SSL_SUCCESS the function was able to execute as expected.
  8159. \return BAD_FUNC_ARG the WOLFSSL_CERT_MANAGER struct is NULL.
  8160. \return MEMEORY_E Memory was not able to be allocated for the
  8161. ocspOverrideURL member of the certificate manager.
  8162. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8163. _Example_
  8164. \code
  8165. #include <wolfssl/ssl.h>
  8166. WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew();
  8167. const char* url;
  8168. int wolfSSL_SetOCSP_OverrideURL(WOLFSSL* ssl, const char* url)
  8169. if(wolfSSL_CertManagerSetOCSPOverrideURL(SSL_CM(ssl), url) != SSL_SUCCESS){
  8170. Failure case.
  8171. }
  8172. \endcode
  8173. \sa ocspOverrideURL
  8174. \sa wolfSSL_SetOCSP_OverrideURL
  8175. */
  8176. int wolfSSL_CertManagerSetOCSPOverrideURL(WOLFSSL_CERT_MANAGER* cm,
  8177. const char* url);
  8178. /*!
  8179. \ingroup CertManager
  8180. \brief The function sets the OCSP callback in the WOLFSSL_CERT_MANAGER.
  8181. \return SSL_SUCCESS returned on successful execution. The arguments are
  8182. saved in the WOLFSSL_CERT_MANAGER structure.
  8183. \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL.
  8184. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure.
  8185. \param ioCb a function pointer of type CbOCSPIO.
  8186. \param respFreeCb - a function pointer of type CbOCSPRespFree.
  8187. \param ioCbCtx - a void pointer variable to the I/O callback user
  8188. registered context.
  8189. _Example_
  8190. \code
  8191. #include <wolfssl/ssl.h>
  8192. wolfSSL_SetOCSP_Cb(WOLFSSL* ssl, CbOCSPIO ioCb,
  8193. CbOCSPRespFree respFreeCb, void* ioCbCtx){
  8194. return wolfSSL_CertManagerSetOCSP_Cb(SSL_CM(ssl), ioCb, respFreeCb, ioCbCtx);
  8195. \endcode
  8196. \sa wolfSSL_CertManagerSetOCSPOverrideURL
  8197. \sa wolfSSL_CertManagerCheckOCSP
  8198. \sa wolfSSL_CertManagerEnableOCSPStapling
  8199. \sa wolfSSL_EnableOCSP
  8200. \sa wolfSSL_DisableOCSP
  8201. \sa wolfSSL_SetOCSP_Cb
  8202. */
  8203. int wolfSSL_CertManagerSetOCSP_Cb(WOLFSSL_CERT_MANAGER* cm,
  8204. CbOCSPIO ioCb, CbOCSPRespFree respFreeCb,
  8205. void* ioCbCtx);
  8206. /*!
  8207. \ingroup CertManager
  8208. \brief This function turns on OCSP stapling if it is not turned on as well
  8209. as set the options.
  8210. \return SSL_SUCCESS returned if there were no errors and the function
  8211. executed successfully.
  8212. \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is
  8213. NULL or otherwise if there was a unpermitted argument value passed to
  8214. a subroutine.
  8215. \return MEMORY_E returned if there was an issue allocating memory.
  8216. \return SSL_FAILURE returned if the initialization of the OCSP
  8217. structure failed.
  8218. \return NOT_COMPILED_IN returned if wolfSSL was not compiled with
  8219. HAVE_CERTIFICATE_STATUS_REQUEST option.
  8220. \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, a member of the
  8221. WOLFSSL_CTX structure.
  8222. _Example_
  8223. \code
  8224. int wolfSSL_CTX_EnableOCSPStapling(WOLFSSL_CTX* ctx){
  8225. return wolfSSL_CertManagerEnableOCSPStapling(ctx->cm);
  8226. \endcode
  8227. \sa wolfSSL_CTX_EnableOCSPStapling
  8228. */
  8229. int wolfSSL_CertManagerEnableOCSPStapling(
  8230. WOLFSSL_CERT_MANAGER* cm);
  8231. /*!
  8232. \brief Enables CRL certificate revocation.
  8233. \return SSL_SUCCESS the function and subroutines returned with no errors.
  8234. \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.
  8235. \return MEMORY_E returned if the allocation of memory failed.
  8236. \return SSL_FAILURE returned if the InitCRL function does not return
  8237. successfully.
  8238. \return NOT_COMPILED_IN HAVE_CRL was not enabled during the compiling.
  8239. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8240. \param options an integer that is used to determine the setting of
  8241. crlCheckAll member of the WOLFSSL_CERT_MANAGER structure.
  8242. _Example_
  8243. \code
  8244. WOLFSSL* ssl = wolfSSL_new(ctx);
  8245. if (wolfSSL_EnableCRL(ssl, WOLFSSL_CRL_CHECKALL) != SSL_SUCCESS){
  8246. // Failure case. SSL_SUCCESS was not returned by this function or
  8247. a subroutine
  8248. }
  8249. \endcode
  8250. \sa wolfSSL_CertManagerEnableCRL
  8251. \sa InitCRL
  8252. */
  8253. int wolfSSL_EnableCRL(WOLFSSL* ssl, int options);
  8254. /*!
  8255. \brief Disables CRL certificate revocation.
  8256. \return SSL_SUCCESS wolfSSL_CertMangerDisableCRL successfully disabled
  8257. the crlEnabled member of the WOLFSSL_CERT_MANAGER structure.
  8258. \return BAD_FUNC_ARG the WOLFSSL structure was NULL.
  8259. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8260. _Example_
  8261. \code
  8262. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  8263. WOLFSSL* ssl = wolfSSL_new(ctx);
  8264. ...
  8265. if(wolfSSL_DisableCRL(ssl) != SSL_SUCCESS){
  8266. // Failure case
  8267. }
  8268. \endcode
  8269. \sa wolfSSL_CertManagerDisableCRL
  8270. \sa wolfSSL_CertManagerDisableOCSP
  8271. */
  8272. int wolfSSL_DisableCRL(WOLFSSL* ssl);
  8273. /*!
  8274. \brief A wrapper function that ends up calling LoadCRL to load the
  8275. certificate for revocation checking.
  8276. \return WOLFSSL_SUCCESS returned if the function and all of the
  8277. subroutines executed without error.
  8278. \return SSL_FATAL_ERROR returned if one of the subroutines does not
  8279. return successfully.
  8280. \return BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER or the WOLFSSL
  8281. structure are NULL.
  8282. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8283. \param path a constant character pointer that holds the path to the
  8284. crl file.
  8285. \param type an integer representing the type of certificate.
  8286. \param monitor an integer variable used to verify the monitor path if
  8287. requested.
  8288. _Example_
  8289. \code
  8290. WOLFSSL* ssl = wolfSSL_new(ctx);
  8291. const char* crlPemDir;
  8292. if(wolfSSL_LoadCRL(ssl, crlPemDir, SSL_FILETYPE_PEM, 0) != SSL_SUCCESS){
  8293. // Failure case. Did not return SSL_SUCCESS.
  8294. }
  8295. \endcode
  8296. \sa wolfSSL_CertManagerLoadCRL
  8297. \sa wolfSSL_CertManagerEnableCRL
  8298. \sa LoadCRL
  8299. */
  8300. int wolfSSL_LoadCRL(WOLFSSL* ssl, const char* path, int type, int monitor);
  8301. /*!
  8302. \brief Sets the CRL callback in the WOLFSSL_CERT_MANAGER structure.
  8303. \return SSL_SUCCESS returned if the function or subroutine executes
  8304. without error. The cbMissingCRL member of the WOLFSSL_CERT_MANAGER is set.
  8305. \return BAD_FUNC_ARG returned if the WOLFSSL or WOLFSSL_CERT_MANAGER
  8306. structure is NULL.
  8307. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8308. \param cb a function pointer to CbMissingCRL.
  8309. _Example_
  8310. \code
  8311. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  8312. WOLFSSL* ssl = wolfSSL_new(ctx);
  8313. void cb(const char* url) // required signature
  8314. {
  8315. // Function body
  8316. }
  8317. int crlCb = wolfSSL_SetCRL_Cb(ssl, cb);
  8318. if(crlCb != SSL_SUCCESS){
  8319. // The callback was not set properly
  8320. }
  8321. \endcode
  8322. \sa CbMissingCRL
  8323. \sa wolfSSL_CertManagerSetCRL_Cb
  8324. */
  8325. int wolfSSL_SetCRL_Cb(WOLFSSL* ssl, CbMissingCRL cb);
  8326. /*!
  8327. \brief This function enables OCSP certificate verification. The value of
  8328. options if formed by or’ing one or more of the following options:
  8329. WOLFSSL_OCSP_URL_OVERRIDE - use the override URL instead of the URL in
  8330. certificates. The override URL is specified using the
  8331. wolfSSL_CTX_SetOCSP_OverrideURL() function.
  8332. WOLFSSL_OCSP_CHECKALL - Set all OCSP checks on
  8333. WOLFSSL_OCSP_NO_NONCE - Set nonce option for creating OCSP requests
  8334. \return SSL_SUCCESS returned if the function and subroutines executes
  8335. without errors.
  8336. \return BAD_FUNC_ARG returned if an argument in this function or any
  8337. subroutine receives an invalid argument value.
  8338. \return MEMORY_E returned if there was an error allocating memory for
  8339. a structure or other variable.
  8340. \return NOT_COMPILED_IN returned if wolfSSL was not compiled with the
  8341. HAVE_OCSP option.
  8342. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8343. \param options an integer type passed to wolfSSL_CertMangerENableOCSP()
  8344. used for settings check.
  8345. _Example_
  8346. \code
  8347. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  8348. WOLFSSL* ssl = wolfSSL_new(ctx);
  8349. int options; // initialize to option constant
  8350. int ret = wolfSSL_EnableOCSP(ssl, options);
  8351. if(ret != SSL_SUCCESS){
  8352. // OCSP is not enabled
  8353. }
  8354. \endcode
  8355. \sa wolfSSL_CertManagerEnableOCSP
  8356. */
  8357. int wolfSSL_EnableOCSP(WOLFSSL* ssl, int options);
  8358. /*!
  8359. \brief Disables the OCSP certificate revocation option.
  8360. \return SSL_SUCCESS returned if the function and its subroutine return with
  8361. no errors. The ocspEnabled member of the WOLFSSL_CERT_MANAGER structure was
  8362. successfully set.
  8363. \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.
  8364. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8365. _Example_
  8366. \code
  8367. WOLFSSL* ssl = wolfSSL_new(ctx);
  8368. if(wolfSSL_DisableOCSP(ssl) != SSL_SUCCESS){
  8369. // Returned with an error. Failure case in this block.
  8370. }
  8371. \endcode
  8372. \sa wolfSSL_CertManagerDisableOCSP
  8373. */
  8374. int wolfSSL_DisableOCSP(WOLFSSL*);
  8375. /*!
  8376. \brief This function sets the ocspOverrideURL member in the
  8377. WOLFSSL_CERT_MANAGER structure.
  8378. \return SSL_SUCCESS returned on successful execution of the function.
  8379. \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if a
  8380. unpermitted argument was passed to a subroutine.
  8381. \return MEMORY_E returned if there was an error allocating memory in the
  8382. subroutine.
  8383. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8384. \param url a constant char pointer to the url that will be stored in the
  8385. ocspOverrideURL member of the WOLFSSL_CERT_MANAGER structure.
  8386. _Example_
  8387. \code
  8388. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  8389. WOLFSSL* ssl = wolfSSL_new(ctx);
  8390. char url[URLSZ];
  8391. ...
  8392. if(wolfSSL_SetOCSP_OverrideURL(ssl, url)){
  8393. // The override url is set to the new value
  8394. }
  8395. \endcode
  8396. \sa wolfSSL_CertManagerSetOCSPOverrideURL
  8397. */
  8398. int wolfSSL_SetOCSP_OverrideURL(WOLFSSL* ssl, const char* url);
  8399. /*!
  8400. \brief This function sets the OCSP callback in the
  8401. WOLFSSL_CERT_MANAGER structure.
  8402. \return SSL_SUCCESS returned if the function executes without error.
  8403. The ocspIOCb, ocspRespFreeCb, and ocspIOCtx members of the CM are set.
  8404. \return BAD_FUNC_ARG returned if the WOLFSSL or WOLFSSL_CERT_MANAGER
  8405. structures are NULL.
  8406. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8407. \param ioCb a function pointer to type CbOCSPIO.
  8408. \param respFreeCb a function pointer to type CbOCSPRespFree which is the
  8409. call to free the response memory.
  8410. \param ioCbCtx a void pointer that will be held in the ocspIOCtx member
  8411. of the CM.
  8412. _Example_
  8413. \code
  8414. WOLFSSL* ssl = wolfSSL_new(ctx);
  8415. int OCSPIO_CB(void* , const char*, int , unsigned char* , int,
  8416. unsigned char**){ // must have this signature
  8417. // Function Body
  8418. }
  8419. void OCSPRespFree_CB(void* , unsigned char* ){ // must have this signature
  8420. // function body
  8421. }
  8422. void* ioCbCtx;
  8423. CbOCSPRespFree CB_OCSPRespFree;
  8424. if(wolfSSL_SetOCSP_Cb(ssl, OCSPIO_CB( pass args ), CB_OCSPRespFree,
  8425. ioCbCtx) != SSL_SUCCESS){
  8426. // Callback not set
  8427. }
  8428. \endcode
  8429. \sa wolfSSL_CertManagerSetOCSP_Cb
  8430. \sa CbOCSPIO
  8431. \sa CbOCSPRespFree
  8432. */
  8433. int wolfSSL_SetOCSP_Cb(WOLFSSL* ssl, CbOCSPIO ioCb, CbOCSPRespFree respFreeCb,
  8434. void* ioCbCtx);
  8435. /*!
  8436. \brief Enables CRL certificate verification through the CTX.
  8437. \return SSL_SUCCESS returned if this function and it’s subroutines
  8438. execute without errors.
  8439. \return BAD_FUNC_ARG returned if the CTX struct is NULL or there
  8440. was otherwise an invalid argument passed in a subroutine.
  8441. \return MEMORY_E returned if there was an error allocating
  8442. memory during execution of the function.
  8443. \return SSL_FAILURE returned if the crl member of the
  8444. WOLFSSL_CERT_MANAGER fails to initialize correctly.
  8445. \return NOT_COMPILED_IN wolfSSL was not compiled with the HAVE_CRL option.
  8446. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8447. _Example_
  8448. \code
  8449. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  8450. WOLFSSL* ssl = wolfSSL_new(ctx);
  8451. ...
  8452. if(wolfSSL_CTX_EnableCRL(ssl->ctx, options) != SSL_SUCCESS){
  8453. // The function failed
  8454. }
  8455. \endcode
  8456. \sa wolfSSL_CertManagerEnableCRL
  8457. \sa InitCRL
  8458. \sa wolfSSL_CTX_DisableCRL
  8459. */
  8460. int wolfSSL_CTX_EnableCRL(WOLFSSL_CTX* ctx, int options);
  8461. /*!
  8462. \brief This function disables CRL verification in the CTX structure.
  8463. \return SSL_SUCCESS returned if the function executes without error.
  8464. The crlEnabled member of the WOLFSSL_CERT_MANAGER struct is set to 0.
  8465. \return BAD_FUNC_ARG returned if either the CTX struct or the CM
  8466. struct has a NULL value.
  8467. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  8468. wolfSSL_CTX_new().
  8469. _Example_
  8470. \code
  8471. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  8472. WOLFSSL* ssl = wolfSSL_new(ctx);
  8473. ...
  8474. if(wolfSSL_CTX_DisableCRL(ssl->ctx) != SSL_SUCCESS){
  8475. // Failure case.
  8476. }
  8477. \endcode
  8478. \sa wolfSSL_CertManagerDisableCRL
  8479. */
  8480. int wolfSSL_CTX_DisableCRL(WOLFSSL_CTX* ctx);
  8481. /*!
  8482. \brief This function loads CRL into the WOLFSSL_CTX structure through
  8483. wolfSSL_CertManagerLoadCRL().
  8484. \return SSL_SUCCESS - returned if the function and its subroutines
  8485. execute without error.
  8486. \return BAD_FUNC_ARG - returned if this function or any subroutines
  8487. are passed NULL structures.
  8488. \return BAD_PATH_ERROR - returned if the path variable opens as NULL.
  8489. \return MEMORY_E - returned if an allocation of memory failed.
  8490. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  8491. wolfSSL_CTX_new().
  8492. \param path the path to the certificate.
  8493. \param type an integer variable holding the type of certificate.
  8494. \param monitor an integer variable used to determine if the monitor
  8495. path is requested.
  8496. _Example_
  8497. \code
  8498. WOLFSSL_CTX* ctx;
  8499. const char* path;
  8500. return wolfSSL_CTX_LoadCRL(ctx, path, SSL_FILETYPE_PEM, 0);
  8501. \endcode
  8502. \sa wolfSSL_CertManagerLoadCRL
  8503. \sa LoadCRL
  8504. */
  8505. int wolfSSL_CTX_LoadCRL(WOLFSSL_CTX* ctx, const char* path, int type, int monitor);
  8506. /*!
  8507. \brief This function will set the callback argument to the cbMissingCRL
  8508. member of the WOLFSSL_CERT_MANAGER structure by calling
  8509. wolfSSL_CertManagerSetCRL_Cb.
  8510. \return SSL_SUCCESS returned for a successful execution. The
  8511. WOLFSSL_CERT_MANAGER structure’s member cbMssingCRL was successfully
  8512. set to cb.
  8513. \return BAD_FUNC_ARG returned if WOLFSSL_CTX or WOLFSSL_CERT_MANAGER
  8514. are NULL.
  8515. \param ctx a pointer to a WOLFSSL_CTX structure, created with
  8516. wolfSSL_CTX_new().
  8517. \param cb a pointer to a callback function of type CbMissingCRL.
  8518. Signature requirement:
  8519. void (*CbMissingCRL)(const char* url);
  8520. _Example_
  8521. \code
  8522. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  8523. void cb(const char* url) // Required signature
  8524. {
  8525. // Function body
  8526. }
  8527. if (wolfSSL_CTX_SetCRL_Cb(ctx, cb) != SSL_SUCCESS){
  8528. // Failure case, cb was not set correctly.
  8529. }
  8530. \endcode
  8531. \sa wolfSSL_CertManagerSetCRL_Cb
  8532. \sa CbMissingCRL
  8533. */
  8534. int wolfSSL_CTX_SetCRL_Cb(WOLFSSL_CTX* ctx, CbMissingCRL cb);
  8535. /*!
  8536. \brief This function sets options to configure behavior of OCSP
  8537. functionality in wolfSSL. The value of options if formed by or’ing
  8538. one or more of the following options:
  8539. WOLFSSL_OCSP_URL_OVERRIDE - use the override URL instead of the URL in
  8540. certificates. The override URL is specified using the
  8541. wolfSSL_CTX_SetOCSP_OverrideURL() function.
  8542. WOLFSSL_OCSP_CHECKALL - Set all OCSP checks on
  8543. WOLFSSL_OCSP_NO_NONCE - Set nonce option for creating OCSP requests
  8544. This function only sets the OCSP options when wolfSSL has been compiled with
  8545. OCSP support (--enable-ocsp, #define HAVE_OCSP).
  8546. \return SSL_SUCCESS is returned upon success.
  8547. \return SSL_FAILURE is returned upon failure.
  8548. \return NOT_COMPILED_IN is returned when this function has been called,
  8549. but OCSP support was not enabled when wolfSSL was compiled.
  8550. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  8551. \param options value used to set the OCSP options.
  8552. _Example_
  8553. \code
  8554. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  8555. int options; // initialize to option constant
  8556. int ret = wolfSSL_CTX_EnableOCSP(ctx, options);
  8557. if(ret != SSL_SUCCESS){
  8558. // OCSP is not enabled
  8559. }
  8560. \endcode
  8561. \sa wolfSSL_CertManagerEnableOCSP
  8562. \sa wolfSSL_EnableOCSP
  8563. */
  8564. int wolfSSL_CTX_EnableOCSP(WOLFSSL_CTX* ctx, int options);
  8565. /*!
  8566. \brief This function disables OCSP certificate revocation checking by
  8567. affecting the ocspEnabled member of the WOLFSSL_CERT_MANAGER structure.
  8568. \return SSL_SUCCESS returned if the function executes without error.
  8569. The ocspEnabled member of the CM has been disabled.
  8570. \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL.
  8571. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  8572. wolfSSL_CTX_new().
  8573. _Example_
  8574. \code
  8575. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  8576. WOLFSSL* ssl = wolfSSL_new(ctx);
  8577. ...
  8578. if(!wolfSSL_CTX_DisableOCSP(ssl->ctx)){
  8579. // OCSP is not disabled
  8580. }
  8581. \endcode
  8582. \sa wolfSSL_DisableOCSP
  8583. \sa wolfSSL_CertManagerDisableOCSP
  8584. */
  8585. int wolfSSL_CTX_DisableOCSP(WOLFSSL_CTX*);
  8586. /*!
  8587. \brief This function manually sets the URL for OCSP to use. By default,
  8588. OCSP will use the URL found in the individual certificate unless the
  8589. WOLFSSL_OCSP_URL_OVERRIDE option is set using the wolfSSL_CTX_EnableOCSP.
  8590. \return SSL_SUCCESS is returned upon success.
  8591. \return SSL_FAILURE is returned upon failure.
  8592. \return NOT_COMPILED_IN is returned when this function has been called,
  8593. but OCSP support was not enabled when wolfSSL was compiled.
  8594. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  8595. \param url pointer to the OCSP URL for wolfSSL to use.
  8596. _Example_
  8597. \code
  8598. WOLFSSL_CTX* ctx = 0;
  8599. ...
  8600. wolfSSL_CTX_OCSP_set_override_url(ctx, “custom-url-here”);
  8601. \endcode
  8602. \sa wolfSSL_CTX_OCSP_set_options
  8603. */
  8604. int wolfSSL_CTX_SetOCSP_OverrideURL(WOLFSSL_CTX* ctx, const char* url);
  8605. /*!
  8606. \brief Sets the callback for the OCSP in the WOLFSSL_CTX structure.
  8607. \return SSL_SUCCESS returned if the function executed successfully. The
  8608. ocspIOCb, ocspRespFreeCb, and ocspIOCtx members in the CM were
  8609. successfully set.
  8610. \return BAD_FUNC_ARG returned if the WOLFSSL_CTX or
  8611. WOLFSSL_CERT_MANAGER structure is NULL.
  8612. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8613. \param ioCb a CbOCSPIO type that is a function pointer.
  8614. \param respFreeCb a CbOCSPRespFree type that is a function pointer.
  8615. \param ioCbCtx a void pointer that will be held in the WOLFSSL_CERT_MANAGER.
  8616. _Example_
  8617. \code
  8618. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  8619. CbOCSPIO ocspIOCb;
  8620. CbOCSPRespFree ocspRespFreeCb;
  8621. void* ioCbCtx;
  8622. int isSetOCSP = wolfSSL_CTX_SetOCSP_Cb(ctx, ocspIOCb,
  8623. ocspRespFreeCb, ioCbCtx);
  8624. if(isSetOCSP != SSL_SUCCESS){
  8625. // The function did not return successfully.
  8626. }
  8627. \endcode
  8628. \sa wolfSSL_CertManagerSetOCSP_Cb
  8629. \sa CbOCSPIO
  8630. \sa CbOCSPRespFree
  8631. */
  8632. int wolfSSL_CTX_SetOCSP_Cb(WOLFSSL_CTX* ctx,
  8633. CbOCSPIO ioCb, CbOCSPRespFree respFreeCb,
  8634. void* ioCbCtx);
  8635. /*!
  8636. \brief This function enables OCSP stapling by calling
  8637. wolfSSL_CertManagerEnableOCSPStapling().
  8638. \return SSL_SUCCESS returned if there were no errors and the function
  8639. executed successfully.
  8640. \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or
  8641. otherwise if there was a unpermitted argument value passed to a subroutine.
  8642. \return MEMORY_E returned if there was an issue allocating memory.
  8643. \return SSL_FAILURE returned if the initialization of the OCSP
  8644. structure failed.
  8645. \return NOT_COMPILED_IN returned if wolfSSL was not compiled with
  8646. HAVE_CERTIFICATE_STATUS_REQUEST option.
  8647. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  8648. wolfSSL_CTX_new().
  8649. _Example_
  8650. \code
  8651. WOLFSSL* ssl = WOLFSSL_new();
  8652. ssl->method.version; // set to desired protocol
  8653. ...
  8654. if(!wolfSSL_CTX_EnableOCSPStapling(ssl->ctx)){
  8655. // OCSP stapling is not enabled
  8656. }
  8657. \endcode
  8658. \sa wolfSSL_CertManagerEnableOCSPStapling
  8659. \sa InitOCSP
  8660. */
  8661. int wolfSSL_CTX_EnableOCSPStapling(WOLFSSL_CTX*);
  8662. /*!
  8663. \ingroup CertsKeys
  8664. \brief Normally, at the end of the SSL handshake, wolfSSL frees
  8665. temporary arrays. Calling this function before the handshake begins
  8666. will prevent wolfSSL from freeing temporary arrays. Temporary arrays
  8667. may be needed for things such as wolfSSL_get_keys() or PSK hints.
  8668. When the user is done with temporary arrays, either wolfSSL_FreeArrays()
  8669. may be called to free the resources immediately, or alternatively the
  8670. resources will be freed when the associated SSL object is freed.
  8671. \return none No return.
  8672. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8673. _Example_
  8674. \code
  8675. WOLFSSL* ssl;
  8676. ...
  8677. wolfSSL_KeepArrays(ssl);
  8678. \endcode
  8679. \sa wolfSSL_FreeArrays
  8680. */
  8681. void wolfSSL_KeepArrays(WOLFSSL*);
  8682. /*!
  8683. \ingroup CertsKeys
  8684. \brief Normally, at the end of the SSL handshake, wolfSSL frees temporary
  8685. arrays. If wolfSSL_KeepArrays() has been called before the handshake,
  8686. wolfSSL will not free temporary arrays. This function explicitly frees
  8687. temporary arrays and should be called when the user is done with temporary
  8688. arrays and does not want to wait for the SSL object to be freed to free
  8689. these resources.
  8690. \return none No return.
  8691. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8692. _Example_
  8693. \code
  8694. WOLFSSL* ssl;
  8695. ...
  8696. wolfSSL_FreeArrays(ssl);
  8697. \endcode
  8698. \sa wolfSSL_KeepArrays
  8699. */
  8700. void wolfSSL_FreeArrays(WOLFSSL*);
  8701. /*!
  8702. \brief This function enables the use of Server Name Indication in the SSL
  8703. object passed in the 'ssl' parameter. It means that the SNI extension will
  8704. be sent on ClientHello by wolfSSL client and wolfSSL server will respond
  8705. ClientHello + SNI with either ServerHello + blank SNI or alert fatal in
  8706. case of SNI mismatch.
  8707. \return WOLFSSL_SUCCESS upon success.
  8708. \return BAD_FUNC_ARG is the error that will be returned in one of these
  8709. cases: ssl is NULL, data is NULL, type is a unknown value. (see below)
  8710. \return MEMORY_E is the error returned when there is not enough memory.
  8711. \param ssl pointer to a SSL object, created with wolfSSL_new().
  8712. \param type indicates which type of server name is been passed in data.
  8713. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
  8714. \param data pointer to the server name data.
  8715. \param size size of the server name data.
  8716. _Example_
  8717. \code
  8718. int ret = 0;
  8719. WOLFSSL_CTX* ctx = 0;
  8720. WOLFSSL* ssl = 0;
  8721. ctx = wolfSSL_CTX_new(method);
  8722. if (ctx == NULL) {
  8723. // context creation failed
  8724. }
  8725. ssl = wolfSSL_new(ctx);
  8726. if (ssl == NULL) {
  8727. // ssl creation failed
  8728. }
  8729. ret = wolfSSL_UseSNI(ssl, WOLFSSL_SNI_HOST_NAME, "www.yassl.com",
  8730. strlen("www.yassl.com"));
  8731. if (ret != WOLFSSL_SUCCESS) {
  8732. // sni usage failed
  8733. }
  8734. \endcode
  8735. \sa wolfSSL_new
  8736. \sa wolfSSL_CTX_UseSNI
  8737. */
  8738. int wolfSSL_UseSNI(WOLFSSL* ssl, unsigned char type,
  8739. const void* data, unsigned short size);
  8740. /*!
  8741. \brief This function enables the use of Server Name Indication for SSL
  8742. objects created from the SSL context passed in the 'ctx' parameter. It
  8743. means that the SNI extension will be sent on ClientHello by wolfSSL
  8744. clients and wolfSSL servers will respond ClientHello + SNI with either
  8745. ServerHello + blank SNI or alert fatal in case of SNI mismatch.
  8746. \return WOLFSSL_SUCCESS upon success.
  8747. \return BAD_FUNC_ARG is the error that will be returned in one of these
  8748. cases: ctx is NULL, data is NULL, type is a unknown value. (see below)
  8749. \return MEMORY_E is the error returned when there is not enough memory.
  8750. \param ctx pointer to a SSL context, created with wolfSSL_CTX_new().
  8751. \param type indicates which type of server name is been passed in data.
  8752. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
  8753. \param data pointer to the server name data.
  8754. \param size size of the server name data.
  8755. _Example_
  8756. \code
  8757. int ret = 0;
  8758. WOLFSSL_CTX* ctx = 0;
  8759. ctx = wolfSSL_CTX_new(method);
  8760. if (ctx == NULL) {
  8761. // context creation failed
  8762. }
  8763. ret = wolfSSL_CTX_UseSNI(ctx, WOLFSSL_SNI_HOST_NAME, "www.yassl.com",
  8764. strlen("www.yassl.com"));
  8765. if (ret != WOLFSSL_SUCCESS) {
  8766. // sni usage failed
  8767. }
  8768. \endcode
  8769. \sa wolfSSL_CTX_new
  8770. \sa wolfSSL_UseSNI
  8771. */
  8772. int wolfSSL_CTX_UseSNI(WOLFSSL_CTX* ctx, unsigned char type,
  8773. const void* data, unsigned short size);
  8774. /*!
  8775. \brief This function is called on the server side to configure the
  8776. behavior of the SSL session using Server Name Indication in the SSL
  8777. object passed in the 'ssl' parameter. The options are explained below.
  8778. \return none No returns.
  8779. \param ssl pointer to a SSL object, created with wolfSSL_new().
  8780. \param type indicates which type of server name is been passed in data.
  8781. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
  8782. \param options a bitwise semaphore with the chosen options. The available
  8783. options are: enum { WOLFSSL_SNI_CONTINUE_ON_MISMATCH = 0x01,
  8784. WOLFSSL_SNI_ANSWER_ON_MISMATCH = 0x02 }; Normally the server will abort the
  8785. handshake by sending a fatal-level unrecognized_name(112) alert if the
  8786. hostname provided by the client mismatch with the servers.
  8787. \param WOLFSSL_SNI_CONTINUE_ON_MISMATCH With this option set, the server
  8788. will not send a SNI response instead of aborting the session.
  8789. \param WOLFSSL_SNI_ANSWER_ON_MISMATCH - With this option set, the server
  8790. will send a SNI response as if the host names match instead of aborting
  8791. the session.
  8792. _Example_
  8793. \code
  8794. int ret = 0;
  8795. WOLFSSL_CTX* ctx = 0;
  8796. WOLFSSL* ssl = 0;
  8797. ctx = wolfSSL_CTX_new(method);
  8798. if (ctx == NULL) {
  8799. // context creation failed
  8800. }
  8801. ssl = wolfSSL_new(ctx);
  8802. if (ssl == NULL) {
  8803. // ssl creation failed
  8804. }
  8805. ret = wolfSSL_UseSNI(ssl, 0, "www.yassl.com", strlen("www.yassl.com"));
  8806. if (ret != WOLFSSL_SUCCESS) {
  8807. // sni usage failed
  8808. }
  8809. wolfSSL_SNI_SetOptions(ssl, WOLFSSL_SNI_HOST_NAME,
  8810. WOLFSSL_SNI_CONTINUE_ON_MISMATCH);
  8811. \endcode
  8812. \sa wolfSSL_new
  8813. \sa wolfSSL_UseSNI
  8814. \sa wolfSSL_CTX_SNI_SetOptions
  8815. */
  8816. void wolfSSL_SNI_SetOptions(WOLFSSL* ssl, unsigned char type,
  8817. unsigned char options);
  8818. /*!
  8819. \brief This function is called on the server side to configure the behavior
  8820. of the SSL sessions using Server Name Indication for SSL objects created
  8821. from the SSL context passed in the 'ctx' parameter. The options are
  8822. explained below.
  8823. \return none No returns.
  8824. \param ctx pointer to a SSL context, created with wolfSSL_CTX_new().
  8825. \param type indicates which type of server name is been passed in data.
  8826. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
  8827. \param options a bitwise semaphore with the chosen options. The available
  8828. options are: enum { WOLFSSL_SNI_CONTINUE_ON_MISMATCH = 0x01,
  8829. WOLFSSL_SNI_ANSWER_ON_MISMATCH = 0x02 }; Normally the server will abort
  8830. the handshake by sending a fatal-level unrecognized_name(112) alert if the
  8831. hostname provided by the client mismatch with the servers.
  8832. \param WOLFSSL_SNI_CONTINUE_ON_MISMATCH With this option set, the
  8833. server will not send a SNI response instead of aborting the session.
  8834. \param WOLFSSL_SNI_ANSWER_ON_MISMATCH With this option set, the server
  8835. will send a SNI response as if the host names match instead of aborting
  8836. the session.
  8837. _Example_
  8838. \code
  8839. int ret = 0;
  8840. WOLFSSL_CTX* ctx = 0;
  8841. ctx = wolfSSL_CTX_new(method);
  8842. if (ctx == NULL) {
  8843. // context creation failed
  8844. }
  8845. ret = wolfSSL_CTX_UseSNI(ctx, 0, "www.yassl.com", strlen("www.yassl.com"));
  8846. if (ret != WOLFSSL_SUCCESS) {
  8847. // sni usage failed
  8848. }
  8849. wolfSSL_CTX_SNI_SetOptions(ctx, WOLFSSL_SNI_HOST_NAME,
  8850. WOLFSSL_SNI_CONTINUE_ON_MISMATCH);
  8851. \endcode
  8852. \sa wolfSSL_CTX_new
  8853. \sa wolfSSL_CTX_UseSNI
  8854. \sa wolfSSL_SNI_SetOptions
  8855. */
  8856. void wolfSSL_CTX_SNI_SetOptions(WOLFSSL_CTX* ctx,
  8857. unsigned char type, unsigned char options);
  8858. /*!
  8859. \brief This function is called on the server side to retrieve the Server
  8860. Name Indication provided by the client from the Client Hello message sent
  8861. by the client to start a session. It does not requires context or session
  8862. setup to retrieve the SNI.
  8863. \return WOLFSSL_SUCCESS upon success.
  8864. \return BAD_FUNC_ARG is the error that will be returned in one of this
  8865. cases: buffer is NULL, bufferSz <= 0, sni is NULL, inOutSz is NULL or <= 0
  8866. \return BUFFER_ERROR is the error returned when there is a malformed
  8867. Client Hello message.
  8868. \return INCOMPLETE_DATA is the error returned when there is not enough
  8869. data to complete the extraction.
  8870. \param buffer pointer to the data provided by the client (Client Hello).
  8871. \param bufferSz size of the Client Hello message.
  8872. \param type indicates which type of server name is been retrieved
  8873. from the buffer. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
  8874. \param sni pointer to where the output is going to be stored.
  8875. \param inOutSz pointer to the output size, this value will be updated
  8876. to MIN("SNI's length", inOutSz).
  8877. _Example_
  8878. \code
  8879. unsigned char buffer[1024] = {0};
  8880. unsigned char result[32] = {0};
  8881. int length = 32;
  8882. // read Client Hello to buffer...
  8883. ret = wolfSSL_SNI_GetFromBuffer(buffer, sizeof(buffer), 0, result, &length));
  8884. if (ret != WOLFSSL_SUCCESS) {
  8885. // sni retrieve failed
  8886. }
  8887. \endcode
  8888. \sa wolfSSL_UseSNI
  8889. \sa wolfSSL_CTX_UseSNI
  8890. \sa wolfSSL_SNI_GetRequest
  8891. */
  8892. int wolfSSL_SNI_GetFromBuffer(
  8893. const unsigned char* clientHello, unsigned int helloSz,
  8894. unsigned char type, unsigned char* sni, unsigned int* inOutSz);
  8895. /*!
  8896. \ingroup IO
  8897. \brief This function gets the status of an SNI object.
  8898. \return value This function returns the byte value of the SNI struct’s
  8899. status member if the SNI is not NULL.
  8900. \return 0 if the SNI object is NULL.
  8901. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  8902. \param type the SNI type.
  8903. _Example_
  8904. \code
  8905. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  8906. WOLFSSL* ssl = wolfSSL_new(ctx);
  8907. #define AssertIntEQ(x, y) AssertInt(x, y, ==, !=)
  8908. Byte type = WOLFSSL_SNI_HOST_NAME;
  8909. char* request = (char*)&type;
  8910. AssertIntEQ(WOLFSSL_SNI_NO_MATCH, wolfSSL_SNI_Status(ssl, type));
  8911. \endcode
  8912. \sa TLSX_SNI_Status
  8913. \sa TLSX_SNI_find
  8914. \sa TLSX_Find
  8915. */
  8916. unsigned char wolfSSL_SNI_Status(WOLFSSL* ssl, unsigned char type);
  8917. /*!
  8918. \brief This function is called on the server side to retrieve the
  8919. Server Name Indication provided by the client in a SSL session.
  8920. \return size the size of the provided SNI data.
  8921. \param ssl pointer to a SSL object, created with wolfSSL_new().
  8922. \param type indicates which type of server name is been retrieved in
  8923. data. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
  8924. \param data pointer to the data provided by the client.
  8925. _Example_
  8926. \code
  8927. int ret = 0;
  8928. WOLFSSL_CTX* ctx = 0;
  8929. WOLFSSL* ssl = 0;
  8930. ctx = wolfSSL_CTX_new(method);
  8931. if (ctx == NULL) {
  8932. // context creation failed
  8933. }
  8934. ssl = wolfSSL_new(ctx);
  8935. if (ssl == NULL) {
  8936. // ssl creation failed
  8937. }
  8938. ret = wolfSSL_UseSNI(ssl, 0, "www.yassl.com", strlen("www.yassl.com"));
  8939. if (ret != WOLFSSL_SUCCESS) {
  8940. // sni usage failed
  8941. }
  8942. if (wolfSSL_accept(ssl) == SSL_SUCCESS) {
  8943. void *data = NULL;
  8944. unsigned short size = wolfSSL_SNI_GetRequest(ssl, 0, &data);
  8945. }
  8946. \endcode
  8947. \sa wolfSSL_UseSNI
  8948. \sa wolfSSL_CTX_UseSNI
  8949. */
  8950. unsigned short wolfSSL_SNI_GetRequest(WOLFSSL *ssl,
  8951. unsigned char type, void** data);
  8952. /*!
  8953. \ingroup Setup
  8954. \brief Setup ALPN use for a wolfSSL session.
  8955. \return WOLFSSL_SUCCESS: upon success.
  8956. \return BAD_FUNC_ARG Returned if ssl or protocol_name_list
  8957. is null or protocol_name_listSz is too large or options
  8958. contain something not supported.
  8959. \return MEMORY_ERROR Error allocating memory for protocol list.
  8960. \return SSL_FAILURE upon failure.
  8961. \param ssl The wolfSSL session to use.
  8962. \param protocol_name_list List of protocol names to use.
  8963. Comma delimited string is required.
  8964. \param protocol_name_listSz Size of the list of protocol names.
  8965. \param options WOLFSSL_ALPN_CONTINUE_ON_MISMATCH or
  8966. WOLFSSL_ALPN_FAILED_ON_MISMATCH.
  8967. _Example_
  8968. \code
  8969. wolfSSL_Init();
  8970. WOLFSSL_CTX* ctx;
  8971. WOLFSSL* ssl;
  8972. WOLFSSL_METHOD method = // Some wolfSSL method
  8973. ctx = wolfSSL_CTX_new(method);
  8974. ssl = wolfSSL_new(ctx);
  8975. char alpn_list[] = {};
  8976. if (wolfSSL_UseALPN(ssl, alpn_list, sizeof(alpn_list),
  8977. WOLFSSL_APN_FAILED_ON_MISMATCH) != WOLFSSL_SUCCESS)
  8978. {
  8979. // Error setting session ticket
  8980. }
  8981. \endcode
  8982. \sa TLSX_UseALPN
  8983. */
  8984. int wolfSSL_UseALPN(WOLFSSL* ssl, char *protocol_name_list,
  8985. unsigned int protocol_name_listSz,
  8986. unsigned char options);
  8987. /*!
  8988. \ingroup TLS
  8989. \brief This function gets the protocol name set by the server.
  8990. \return SSL_SUCCESS returned on successful execution where no
  8991. errors were thrown.
  8992. \return SSL_FATAL_ERROR returned if the extension was not found or
  8993. if there was no protocol match with peer. There will also be an
  8994. error thrown if there is more than one protocol name accepted.
  8995. \return SSL_ALPN_NOT_FOUND returned signifying that no protocol
  8996. match with peer was found.
  8997. \return BAD_FUNC_ARG returned if there was a NULL argument passed
  8998. into the function.
  8999. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  9000. \param protocol_name a pointer to a char that represents the protocol
  9001. name and will be held in the ALPN structure.
  9002. \param size a word16 type that represents the size of the protocol_name.
  9003. _Example_
  9004. \code
  9005. WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
  9006. WOLFSSL* ssl = WOLFSSL_new(ctx);
  9007. ...
  9008. int err;
  9009. char* protocol_name = NULL;
  9010. Word16 protocol_nameSz = 0;
  9011. err = wolfSSL_ALPN_GetProtocol(ssl, &protocol_name, &protocol_nameSz);
  9012. if(err == SSL_SUCCESS){
  9013. // Sent ALPN protocol
  9014. }
  9015. \endcode
  9016. \sa TLSX_ALPN_GetRequest
  9017. \sa TLSX_Find
  9018. */
  9019. int wolfSSL_ALPN_GetProtocol(WOLFSSL* ssl, char **protocol_name,
  9020. unsigned short *size);
  9021. /*!
  9022. \ingroup TLS
  9023. \brief This function copies the alpn_client_list data from the SSL
  9024. object to the buffer.
  9025. \return SSL_SUCCESS returned if the function executed without error. The
  9026. alpn_client_list member of the SSL object has been copied to the
  9027. list parameter.
  9028. \return BAD_FUNC_ARG returned if the list or listSz parameter is NULL.
  9029. \return BUFFER_ERROR returned if there will be a problem with the
  9030. list buffer (either it’s NULL or the size is 0).
  9031. \return MEMORY_ERROR returned if there was a problem dynamically
  9032. allocating memory.
  9033. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  9034. \param list a pointer to the buffer. The data from the SSL object will
  9035. be copied into it.
  9036. \param listSz the buffer size.
  9037. _Example_
  9038. \code
  9039. #import <wolfssl/ssl.h>
  9040. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method);
  9041. WOLFSSL* ssl = wolfSSL_new(ctx);
  9042. #ifdef HAVE_ALPN
  9043. char* list = NULL;
  9044. word16 listSz = 0;
  9045. err = wolfSSL_ALPN_GetPeerProtocol(ssl, &list, &listSz);
  9046. if(err == SSL_SUCCESS){
  9047. List of protocols names sent by client
  9048. }
  9049. \endcode
  9050. \sa wolfSSL_UseALPN
  9051. */
  9052. int wolfSSL_ALPN_GetPeerProtocol(WOLFSSL* ssl, char **list,
  9053. unsigned short *listSz);
  9054. /*!
  9055. \brief This function is called on the client side to enable the use of
  9056. Maximum Fragment Length in the SSL object passed in the 'ssl' parameter.
  9057. It means that the Maximum Fragment Length extension will be sent on
  9058. ClientHello by wolfSSL clients.
  9059. \return SSL_SUCCESS upon success.
  9060. \return BAD_FUNC_ARG is the error that will be returned in one of
  9061. these cases: ssl is NULL, mfl is out of range.
  9062. \return MEMORY_E is the error returned when there is not enough memory.
  9063. \param ssl pointer to a SSL object, created with wolfSSL_new().
  9064. \param mfl indicates witch is the Maximum Fragment Length requested for the
  9065. session. The available options are: enum { WOLFSSL_MFL_2_9 = 1, 512 bytes
  9066. WOLFSSL_MFL_2_10 = 2, 1024 bytes WOLFSSL_MFL_2_11 = 3, 2048 bytes
  9067. WOLFSSL_MFL_2_12 = 4, 4096 bytes WOLFSSL_MFL_2_13 = 5, 8192
  9068. bytes wolfSSL ONLY!!! };
  9069. _Example_
  9070. \code
  9071. int ret = 0;
  9072. WOLFSSL_CTX* ctx = 0;
  9073. WOLFSSL* ssl = 0;
  9074. ctx = wolfSSL_CTX_new(method);
  9075. if (ctx == NULL) {
  9076. // context creation failed
  9077. }
  9078. ssl = wolfSSL_new(ctx);
  9079. if (ssl == NULL) {
  9080. // ssl creation failed
  9081. }
  9082. ret = wolfSSL_UseMaxFragment(ssl, WOLFSSL_MFL_2_11);
  9083. if (ret != 0) {
  9084. // max fragment usage failed
  9085. }
  9086. \endcode
  9087. \sa wolfSSL_new
  9088. \sa wolfSSL_CTX_UseMaxFragment
  9089. */
  9090. int wolfSSL_UseMaxFragment(WOLFSSL* ssl, unsigned char mfl);
  9091. /*!
  9092. \brief This function is called on the client side to enable the use
  9093. of Maximum Fragment Length for SSL objects created from the SSL context
  9094. passed in the 'ctx' parameter. It means that the Maximum Fragment Length
  9095. extension will be sent on ClientHello by wolfSSL clients.
  9096. \return SSL_SUCCESS upon success.
  9097. \return BAD_FUNC_ARG is the error that will be returned in one of
  9098. these cases: ctx is NULL, mfl is out of range.
  9099. \return MEMORY_E is the error returned when there is not enough memory.
  9100. \param ctx pointer to a SSL context, created with wolfSSL_CTX_new().
  9101. \param mfl indicates which is the Maximum Fragment Length requested
  9102. for the session. The available options are:
  9103. enum { WOLFSSL_MFL_2_9 = 1 512 bytes, WOLFSSL_MFL_2_10 = 2 1024 bytes,
  9104. WOLFSSL_MFL_2_11 = 3 2048 bytes WOLFSSL_MFL_2_12 = 4 4096 bytes,
  9105. WOLFSSL_MFL_2_13 = 5 8192 bytes wolfSSL ONLY!!!,
  9106. WOLFSSL_MFL_2_13 = 6 256 bytes wolfSSL ONLY!!!
  9107. };
  9108. _Example_
  9109. \code
  9110. int ret = 0;
  9111. WOLFSSL_CTX* ctx = 0;
  9112. ctx = wolfSSL_CTX_new(method);
  9113. if (ctx == NULL) {
  9114. // context creation failed
  9115. }
  9116. ret = wolfSSL_CTX_UseMaxFragment(ctx, WOLFSSL_MFL_2_11);
  9117. if (ret != 0) {
  9118. // max fragment usage failed
  9119. }
  9120. \endcode
  9121. \sa wolfSSL_CTX_new
  9122. \sa wolfSSL_UseMaxFragment
  9123. */
  9124. int wolfSSL_CTX_UseMaxFragment(WOLFSSL_CTX* ctx, unsigned char mfl);
  9125. /*!
  9126. \brief This function is called on the client side to enable the use of
  9127. Truncated HMAC in the SSL object passed in the 'ssl' parameter. It
  9128. means that the Truncated HMAC extension will be sent on ClientHello
  9129. by wolfSSL clients.
  9130. \return SSL_SUCCESS upon success.
  9131. \return BAD_FUNC_ARG is the error that will be returned in one of
  9132. these cases: ssl is NULL
  9133. \return MEMORY_E is the error returned when there is not enough memory.
  9134. \param ssl pointer to a SSL object, created with wolfSSL_new()
  9135. _Example_
  9136. \code
  9137. int ret = 0;
  9138. WOLFSSL_CTX* ctx = 0;
  9139. WOLFSSL* ssl = 0;
  9140. ctx = wolfSSL_CTX_new(method);
  9141. if (ctx == NULL) {
  9142. // context creation failed
  9143. }
  9144. ssl = wolfSSL_new(ctx);
  9145. if (ssl == NULL) {
  9146. // ssl creation failed
  9147. }
  9148. ret = wolfSSL_UseTruncatedHMAC(ssl);
  9149. if (ret != 0) {
  9150. // truncated HMAC usage failed
  9151. }
  9152. \endcode
  9153. \sa wolfSSL_new
  9154. \sa wolfSSL_CTX_UseMaxFragment
  9155. */
  9156. int wolfSSL_UseTruncatedHMAC(WOLFSSL* ssl);
  9157. /*!
  9158. \brief This function is called on the client side to enable the use of
  9159. Truncated HMAC for SSL objects created from the SSL context passed in
  9160. the 'ctx' parameter. It means that the Truncated HMAC extension will
  9161. be sent on ClientHello by wolfSSL clients.
  9162. \return SSL_SUCCESS upon success.
  9163. \return BAD_FUNC_ARG is the error that will be returned in one of
  9164. these cases: ctx is NULL
  9165. \return MEMORY_E is the error returned when there is not enough memory.
  9166. \param ctx pointer to a SSL context, created with wolfSSL_CTX_new().
  9167. _Example_
  9168. \code
  9169. int ret = 0;
  9170. WOLFSSL_CTX* ctx = 0;
  9171. ctx = wolfSSL_CTX_new(method);
  9172. if (ctx == NULL) {
  9173. // context creation failed
  9174. }
  9175. ret = wolfSSL_CTX_UseTruncatedHMAC(ctx);
  9176. if (ret != 0) {
  9177. // truncated HMAC usage failed
  9178. }
  9179. \endcode
  9180. \sa wolfSSL_CTX_new
  9181. \sa wolfSSL_UseMaxFragment
  9182. */
  9183. int wolfSSL_CTX_UseTruncatedHMAC(WOLFSSL_CTX* ctx);
  9184. /*!
  9185. \brief Stapling eliminates the need to contact the CA. Stapling
  9186. lowers the cost of certificate revocation check presented in OCSP.
  9187. \return SSL_SUCCESS returned if TLSX_UseCertificateStatusRequest
  9188. executes without error.
  9189. \return MEMORY_E returned if there is an error with the allocation
  9190. of memory.
  9191. \return BAD_FUNC_ARG returned if there is an argument that has a
  9192. NULL or otherwise unacceptable value passed into the function.
  9193. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  9194. \param status_type a byte type that is passed through to
  9195. TLSX_UseCertificateStatusRequest() and stored in the
  9196. CertificateStatusRequest structure.
  9197. \param options a byte type that is passed through to
  9198. TLSX_UseCertificateStatusRequest() and stored in the
  9199. CertificateStatusRequest structure.
  9200. _Example_
  9201. \code
  9202. WOLFSSL* ssl = wolfSSL_new(ctx);
  9203. if (wolfSSL_UseOCSPStapling(ssl, WOLFSSL_CSR2_OCSP,
  9204. WOLFSSL_CSR2_OCSP_USE_NONCE) != SSL_SUCCESS){
  9205. // Failed case.
  9206. }
  9207. \endcode
  9208. \sa TLSX_UseCertificateStatusRequest
  9209. \sa wolfSSL_CTX_UseOCSPStapling
  9210. */
  9211. int wolfSSL_UseOCSPStapling(WOLFSSL* ssl,
  9212. unsigned char status_type, unsigned char options);
  9213. /*!
  9214. \brief This function requests the certificate status during the handshake.
  9215. \return SSL_SUCCESS returned if the function and subroutines execute
  9216. without error.
  9217. \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or
  9218. otherwise if a unpermitted value is passed to a subroutine.
  9219. \return MEMORY_E returned if the function or subroutine failed to properly
  9220. allocate memory.
  9221. \param ctx a pointer to a WOLFSSL_CTX structure,
  9222. created using wolfSSL_CTX_new().
  9223. \param status_type a byte type that is passed through to
  9224. TLSX_UseCertificateStatusRequest() and stored in the
  9225. CertificateStatusRequest structure.
  9226. \param options a byte type that is passed through to
  9227. TLSX_UseCertificateStatusRequest() and stored in the
  9228. CertificateStatusRequest structure.
  9229. _Example_
  9230. \code
  9231. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  9232. WOLFSSL* ssl = wolfSSL_new(ctx);
  9233. byte statusRequest = 0; // Initialize status request
  9234. switch(statusRequest){
  9235. case WOLFSSL_CSR_OCSP:
  9236. if(wolfSSL_CTX_UseOCSPStapling(ssl->ctx, WOLFSSL_CSR_OCSP,
  9237. WOLF_CSR_OCSP_USE_NONCE) != SSL_SUCCESS){
  9238. // UseCertificateStatusRequest failed
  9239. }
  9240. // Continue switch cases
  9241. \endcode
  9242. \sa wolfSSL_UseOCSPStaplingV2
  9243. \sa wolfSSL_UseOCSPStapling
  9244. \sa TLSX_UseCertificateStatusRequest
  9245. */
  9246. int wolfSSL_CTX_UseOCSPStapling(WOLFSSL_CTX* ctx,
  9247. unsigned char status_type, unsigned char options);
  9248. /*!
  9249. \brief The function sets the status type and options for OCSP.
  9250. \return SSL_SUCCESS - returned if the function and subroutines
  9251. executed without error.
  9252. \return MEMORY_E - returned if there was an allocation of memory error.
  9253. \return BAD_FUNC_ARG - returned if a NULL or otherwise unaccepted
  9254. argument was passed to the function or a subroutine.
  9255. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  9256. \param status_type a byte type that loads the OCSP status type.
  9257. \param options a byte type that holds the OCSP options, set in
  9258. wolfSSL_SNI_SetOptions() and wolfSSL_CTX_SNI_SetOptions().
  9259. _Example_
  9260. \code
  9261. WOLFSSL* ssl = wolfSSL_new(ctx);
  9262. ...
  9263. if (wolfSSL_UseOCSPStaplingV2(ssl, WOLFSSL_CSR2_OCSP_MULTI, 0) != SSL_SUCCESS){
  9264. // Did not execute properly. Failure case code block.
  9265. }
  9266. \endcode
  9267. \sa TLSX_UseCertificatStatusRequestV2
  9268. \sa wolfSSL_SNI_SetOptions
  9269. \sa wolfSSL_CTX_SNI_SetOptions
  9270. */
  9271. int wolfSSL_UseOCSPStaplingV2(WOLFSSL* ssl,
  9272. unsigned char status_type, unsigned char options);
  9273. /*!
  9274. \brief Creates and initializes the certificate status request
  9275. for OCSP Stapling.
  9276. \return SSL_SUCCESS if the function and subroutines executed without error.
  9277. \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or if
  9278. the side variable is not client side.
  9279. \return MEMORY_E returned if the allocation of memory failed.
  9280. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  9281. wolfSSL_CTX_new().
  9282. \param status_type a byte type that is located in the
  9283. CertificatStatusRequest structure and must be either WOLFSSL_CSR2_OCSP
  9284. or WOLFSSL_CSR2_OCSP_MULTI.
  9285. \param options a byte type that will be held in
  9286. CertificateStatusRequestItemV2 struct.
  9287. _Example_
  9288. \code
  9289. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  9290. byte status_type;
  9291. byte options;
  9292. ...
  9293. if(wolfSSL_CTX_UseOCSPStaplingV2(ctx, status_type, options); != SSL_SUCCESS){
  9294. // Failure case.
  9295. }
  9296. \endcode
  9297. \sa TLSX_UseCertificateStatusRequestV2
  9298. \sa wc_RNG_GenerateBlock
  9299. \sa TLSX_Push
  9300. */
  9301. int wolfSSL_CTX_UseOCSPStaplingV2(WOLFSSL_CTX* ctx,
  9302. unsigned char status_type, unsigned char options);
  9303. /*!
  9304. \brief This function is called on the client side to enable the use of
  9305. Supported Elliptic Curves Extension in the SSL object passed in the 'ssl'
  9306. parameter. It means that the supported curves enabled will be sent on
  9307. ClientHello by wolfSSL clients. This function can be called more than
  9308. one time to enable multiple curves.
  9309. \return SSL_SUCCESS upon success.
  9310. \return BAD_FUNC_ARG is the error that will be returned in one of these
  9311. cases: ssl is NULL, name is a unknown value. (see below)
  9312. \return MEMORY_E is the error returned when there is not enough memory.
  9313. \param ssl pointer to a SSL object, created with wolfSSL_new().
  9314. \param name indicates which curve will be supported for the session. The
  9315. available options are: enum { WOLFSSL_ECC_SECP160R1 = 0x10,
  9316. WOLFSSL_ECC_SECP192R1 = 0x13, WOLFSSL_ECC_SECP224R1 = 0x15,
  9317. WOLFSSL_ECC_SECP256R1 = 0x17, WOLFSSL_ECC_SECP384R1 = 0x18,
  9318. WOLFSSL_ECC_SECP521R1 = 0x19 };
  9319. _Example_
  9320. \code
  9321. int ret = 0;
  9322. WOLFSSL_CTX* ctx = 0;
  9323. WOLFSSL* ssl = 0;
  9324. ctx = wolfSSL_CTX_new(method);
  9325. if (ctx == NULL) {
  9326. // context creation failed
  9327. }
  9328. ssl = wolfSSL_new(ctx);
  9329. if (ssl == NULL) {
  9330. // ssl creation failed
  9331. }
  9332. ret = wolfSSL_UseSupportedCurve(ssl, WOLFSSL_ECC_SECP256R1);
  9333. if (ret != 0) {
  9334. // Elliptic Curve Extension usage failed
  9335. }
  9336. \endcode
  9337. \sa wolfSSL_CTX_new
  9338. \sa wolfSSL_CTX_UseSupportedCurve
  9339. */
  9340. int wolfSSL_UseSupportedCurve(WOLFSSL* ssl, word16 name);
  9341. /*!
  9342. \brief This function is called on the client side to enable the use of
  9343. Supported Elliptic Curves Extension for SSL objects created from the SSL
  9344. context passed in the 'ctx' parameter. It means that the supported curves
  9345. enabled will be sent on ClientHello by wolfSSL clients. This function can
  9346. be called more than one time to enable multiple curves.
  9347. \return SSL_SUCCESS upon success.
  9348. \return BAD_FUNC_ARG is the error that will be returned in one of these
  9349. cases: ctx is NULL, name is a unknown value. (see below)
  9350. \return MEMORY_E is the error returned when there is not enough memory.
  9351. \param ctx pointer to a SSL context, created with wolfSSL_CTX_new().
  9352. \param name indicates which curve will be supported for the session.
  9353. The available options are: enum { WOLFSSL_ECC_SECP160R1 = 0x10,
  9354. WOLFSSL_ECC_SECP192R1 = 0x13, WOLFSSL_ECC_SECP224R1 = 0x15,
  9355. WOLFSSL_ECC_SECP256R1 = 0x17, WOLFSSL_ECC_SECP384R1 = 0x18,
  9356. WOLFSSL_ECC_SECP521R1 = 0x19 };
  9357. _Example_
  9358. \code
  9359. int ret = 0;
  9360. WOLFSSL_CTX* ctx = 0;
  9361. ctx = wolfSSL_CTX_new(method);
  9362. if (ctx == NULL) {
  9363. // context creation failed
  9364. }
  9365. ret = wolfSSL_CTX_UseSupportedCurve(ctx, WOLFSSL_ECC_SECP256R1);
  9366. if (ret != 0) {
  9367. // Elliptic Curve Extension usage failed
  9368. }
  9369. \endcode
  9370. \sa wolfSSL_CTX_new
  9371. \sa wolfSSL_UseSupportedCurve
  9372. */
  9373. int wolfSSL_CTX_UseSupportedCurve(WOLFSSL_CTX* ctx,
  9374. word16 name);
  9375. /*!
  9376. \ingroup IO
  9377. \brief This function forces secure renegotiation for the supplied
  9378. WOLFSSL structure. This is not recommended.
  9379. \return SSL_SUCCESS Successfully set secure renegotiation.
  9380. \return BAD_FUNC_ARG Returns error if ssl is null.
  9381. \return MEMORY_E Returns error if unable to allocate memory for secure
  9382. renegotiation.
  9383. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  9384. _Example_
  9385. \code
  9386. wolfSSL_Init();
  9387. WOLFSSL_CTX* ctx;
  9388. WOLFSSL* ssl;
  9389. WOLFSSL_METHOD method = // Some wolfSSL method
  9390. ctx = wolfSSL_CTX_new(method);
  9391. ssl = wolfSSL_new(ctx);
  9392. if(wolfSSL_UseSecureRenegotiation(ssl) != SSL_SUCCESS)
  9393. {
  9394. // Error setting secure renegotiation
  9395. }
  9396. \endcode
  9397. \sa TLSX_Find
  9398. \sa TLSX_UseSecureRenegotiation
  9399. */
  9400. int wolfSSL_UseSecureRenegotiation(WOLFSSL* ssl);
  9401. /*!
  9402. \ingroup IO
  9403. \brief This function executes a secure renegotiation handshake; this is user
  9404. forced as wolfSSL discourages this functionality.
  9405. \return SSL_SUCCESS returned if the function executed without error.
  9406. \return BAD_FUNC_ARG returned if the WOLFSSL structure was NULL or otherwise
  9407. if an unacceptable argument was passed in a subroutine.
  9408. \return SECURE_RENEGOTIATION_E returned if there was an error with
  9409. renegotiating the handshake.
  9410. \return SSL_FATAL_ERROR returned if there was an error with the
  9411. server or client configuration and the renegotiation could
  9412. not be completed. See wolfSSL_negotiate().
  9413. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  9414. _Example_
  9415. \code
  9416. WOLFSSL* ssl = wolfSSL_new(ctx);
  9417. ...
  9418. if(wolfSSL_Rehandshake(ssl) != SSL_SUCCESS){
  9419. // There was an error and the rehandshake is not successful.
  9420. }
  9421. \endcode
  9422. \sa wolfSSL_negotiate
  9423. \sa wc_InitSha512
  9424. \sa wc_InitSha384
  9425. \sa wc_InitSha256
  9426. \sa wc_InitSha
  9427. \sa wc_InitMd5
  9428. */
  9429. int wolfSSL_Rehandshake(WOLFSSL* ssl);
  9430. /*!
  9431. \ingroup IO
  9432. \brief Force provided WOLFSSL structure to use session ticket. The
  9433. constant HAVE_SESSION_TICKET should be defined and the constant
  9434. NO_WOLFSSL_CLIENT should not be defined to use this function.
  9435. \return SSL_SUCCESS Successfully set use session ticket.
  9436. \return BAD_FUNC_ARG Returned if ssl is null.
  9437. \return MEMORY_E Error allocating memory for setting session ticket.
  9438. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  9439. _Example_
  9440. \code
  9441. wolfSSL_Init();
  9442. WOLFSSL_CTX* ctx;
  9443. WOLFSSL* ssl;
  9444. WOLFSSL_METHOD method = // Some wolfSSL method
  9445. ctx = wolfSSL_CTX_new(method);
  9446. ssl = wolfSSL_new(ctx);
  9447. if(wolfSSL_UseSessionTicket(ssl) != SSL_SUCCESS)
  9448. {
  9449. // Error setting session ticket
  9450. }
  9451. \endcode
  9452. \sa TLSX_UseSessionTicket
  9453. */
  9454. int wolfSSL_UseSessionTicket(WOLFSSL* ssl);
  9455. /*!
  9456. \ingroup Setup
  9457. \brief This function sets wolfSSL context to use a session ticket.
  9458. \return SSL_SUCCESS Function executed successfully.
  9459. \return BAD_FUNC_ARG Returned if ctx is null.
  9460. \return MEMORY_E Error allocating memory in internal function.
  9461. \param ctx The WOLFSSL_CTX structure to use.
  9462. _Example_
  9463. \code
  9464. wolfSSL_Init();
  9465. WOLFSSL_CTX* ctx;
  9466. WOLFSSL_METHOD method = // Some wolfSSL method ;
  9467. ctx = wolfSSL_CTX_new(method);
  9468. if(wolfSSL_CTX_UseSessionTicket(ctx) != SSL_SUCCESS)
  9469. {
  9470. // Error setting session ticket
  9471. }
  9472. \endcode
  9473. \sa TLSX_UseSessionTicket
  9474. */
  9475. int wolfSSL_CTX_UseSessionTicket(WOLFSSL_CTX* ctx);
  9476. /*!
  9477. \ingroup IO
  9478. \brief This function copies the ticket member of the Session structure to
  9479. the buffer.
  9480. \return SSL_SUCCESS returned if the function executed without error.
  9481. \return BAD_FUNC_ARG returned if one of the arguments was NULL or if the
  9482. bufSz argument was 0.
  9483. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  9484. \param buf a byte pointer representing the memory buffer.
  9485. \param bufSz a word32 pointer representing the buffer size.
  9486. _Example_
  9487. \code
  9488. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  9489. WOLFSSL* ssl = wolfSSL_new(ctx);
  9490. byte* buf;
  9491. word32 bufSz; // Initialize with buf size
  9492. if(wolfSSL_get_SessionTicket(ssl, buf, bufSz) <= 0){
  9493. // Nothing was written to the buffer
  9494. } else {
  9495. // the buffer holds the content from ssl->session->ticket
  9496. }
  9497. \endcode
  9498. \sa wolfSSL_UseSessionTicket
  9499. \sa wolfSSL_set_SessionTicket
  9500. */
  9501. int wolfSSL_get_SessionTicket(WOLFSSL* ssl, unsigned char* buf, word32* bufSz);
  9502. /*!
  9503. \ingroup IO
  9504. \brief This function sets the ticket member of the WOLFSSL_SESSION
  9505. structure within the WOLFSSL struct. The buffer passed into the function
  9506. is copied to memory.
  9507. \return SSL_SUCCESS returned on successful execution of the function.
  9508. The function returned without errors.
  9509. \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL. This will
  9510. also be thrown if the buf argument is NULL but the bufSz argument
  9511. is not zero.
  9512. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  9513. \param buf a byte pointer that gets loaded into the ticket member
  9514. of the session structure.
  9515. \param bufSz a word32 type that represents the size of the buffer.
  9516. _Example_
  9517. \code
  9518. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  9519. WOLFSSL* ssl = wolfSSL_new(ctx);
  9520. byte* buffer; // File to load
  9521. word32 bufSz;
  9522. ...
  9523. if(wolfSSL_KeepArrays(ssl, buffer, bufSz) != SSL_SUCCESS){
  9524. // There was an error loading the buffer to memory.
  9525. }
  9526. \endcode
  9527. \sa wolfSSL_set_SessionTicket_cb
  9528. */
  9529. int wolfSSL_set_SessionTicket(WOLFSSL* ssl, const unsigned char* buf,
  9530. word32 bufSz);
  9531. /*!
  9532. \brief This function sets the session ticket callback. The type
  9533. CallbackSessionTicket is a function pointer with the signature of:
  9534. int (*CallbackSessionTicket)(WOLFSSL*, const unsigned char*, int, void*)
  9535. \return SSL_SUCCESS returned if the function executed without error.
  9536. \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.
  9537. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  9538. \param cb a function pointer to the type CallbackSessionTicket.
  9539. \param ctx a void pointer to the session_ticket_ctx member of the
  9540. WOLFSSL structure.
  9541. _Example_
  9542. \code
  9543. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  9544. WOLFSSL* ssl = wolfSSL_new(ctx);
  9545. int sessionTicketCB(WOLFSSL* ssl, const unsigned char* ticket, int ticketSz,
  9546. void* ctx){ … }
  9547. wolfSSL_set_SessionTicket_cb(ssl, sessionTicketCB, (void*)”initial session”);
  9548. \endcode
  9549. \sa wolfSSL_get_SessionTicket
  9550. \sa CallbackSessionTicket
  9551. \sa sessionTicketCB
  9552. */
  9553. int wolfSSL_set_SessionTicket_cb(WOLFSSL* ssl,
  9554. CallbackSessionTicket cb, void* ctx);
  9555. /*!
  9556. \brief This function sends a session ticket to the client after a TLS v1.3
  9557. handhsake has been established.
  9558. \return WOLFSSL_SUCCESS returned if a new session ticket was sent.
  9559. \return BAD_FUNC_ARG returned if WOLFSSL structure is NULL, or not using
  9560. TLS v1.3.
  9561. \return SIDE_ERROR returned if not a server.
  9562. \return NOT_READY_ERROR returned if the handshake has not completed.
  9563. \return WOLFSSL_FATAL_ERROR returned if creating or sending message fails.
  9564. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  9565. _Example_
  9566. \code
  9567. int ret;
  9568. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  9569. WOLFSSL* ssl = wolfSSL_new(ctx);
  9570. ret = wolfSSL_send_SessionTicket(ssl);
  9571. if (ret != WOLFSSL_SUCCESS) {
  9572. // New session ticket not sent.
  9573. }
  9574. \endcode
  9575. \sa wolfSSL_get_SessionTicket
  9576. \sa CallbackSessionTicket
  9577. \sa sessionTicketCB
  9578. */
  9579. int wolfSSL_send_SessionTicket(WOLFSSL* ssl);
  9580. /*!
  9581. \brief This function sets the session ticket key encrypt callback function
  9582. for a server to support session tickets as specified in RFC 5077.
  9583. \return SSL_SUCCESS will be returned upon successfully setting the session.
  9584. \return BAD_FUNC_ARG will be returned on failure. This is caused by passing
  9585. invalid arguments to the function.
  9586. \param ctx pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new().
  9587. \param cb user callback function to encrypt/decrypt session tickets
  9588. \param ssl(Callback) pointer to the WOLFSSL object, created with
  9589. wolfSSL_new()
  9590. \param key_name(Callback) unique key name for this ticket context, should
  9591. be randomly generated
  9592. \param iv(Callback) unique IV for this ticket, up to 128 bits, should
  9593. be randomly generated
  9594. \param mac(Callback) up to 256 bit mac for this ticket
  9595. \param enc(Callback) if this encrypt parameter is true the user should fill
  9596. in key_name, iv, mac, and encrypt the ticket in-place of length inLen and
  9597. set the resulting output length in *outLen. Returning WOLFSSL_TICKET_RET_OK
  9598. tells wolfSSL that the encryption was successful. If this encrypt parameter
  9599. is false, the user should perform a decrypt of the ticket in-place of length
  9600. inLen using key_name, iv, and mac. The resulting decrypt length should be
  9601. set in *outLen. Returning WOLFSSL_TICKET_RET_OK tells wolfSSL to proceed
  9602. using the decrypted ticket. Returning WOLFSSL_TICKET_RET_CREATE tells
  9603. wolfSSL to use the decrypted ticket but also to generate a new one to
  9604. send to the client, helpful if recently rolled keys and don’t want to
  9605. force a full handshake. Returning WOLFSSL_TICKET_RET_REJECT tells
  9606. wolfSSL to reject this ticket, perform a full handshake, and create
  9607. a new standard session ID for normal session resumption. Returning
  9608. WOLFSSL_TICKET_RET_FATAL tells wolfSSL to end the connection
  9609. attempt with a fatal error.
  9610. \param ticket(Callback) the input/output buffer for the encrypted ticket.
  9611. See the enc parameter
  9612. \param inLen(Callback) the input length of the ticket parameter
  9613. \param outLen(Callback) the resulting output length of the ticket parameter.
  9614. When entering the callback outLen will indicate the maximum size available
  9615. in the ticket buffer.
  9616. \param userCtx(Callback) the user context set with
  9617. wolfSSL_CTX_set_TicketEncCtx()
  9618. _Example_
  9619. \code
  9620. See wolfssl/test.h myTicketEncCb() used by the example
  9621. server and example echoserver.
  9622. \endcode
  9623. \sa wolfSSL_CTX_set_TicketHint
  9624. \sa wolfSSL_CTX_set_TicketEncCtx
  9625. */
  9626. int wolfSSL_CTX_set_TicketEncCb(WOLFSSL_CTX* ctx,
  9627. SessionTicketEncCb);
  9628. /*!
  9629. \brief This function sets the session ticket hint relayed to the client.
  9630. For server side use.
  9631. \return SSL_SUCCESS will be returned upon successfully setting the session.
  9632. \return BAD_FUNC_ARG will be returned on failure. This is caused by passing
  9633. invalid arguments to the function.
  9634. \param ctx pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new().
  9635. \param hint number of seconds the ticket might be valid for. Hint to client.
  9636. _Example_
  9637. \code
  9638. none
  9639. \endcode
  9640. \sa wolfSSL_CTX_set_TicketEncCb
  9641. */
  9642. int wolfSSL_CTX_set_TicketHint(WOLFSSL_CTX* ctx, int);
  9643. /*!
  9644. \brief This function sets the session ticket encrypt user context for the
  9645. callback. For server side use.
  9646. \return SSL_SUCCESS will be returned upon successfully setting the session.
  9647. \return BAD_FUNC_ARG will be returned on failure. This is caused by
  9648. passing invalid arguments to the function.
  9649. \param ctx pointer to the WOLFSSL_CTX object, created
  9650. with wolfSSL_CTX_new().
  9651. \param userCtx the user context for the callback
  9652. _Example_
  9653. \code
  9654. none
  9655. \endcode
  9656. \sa wolfSSL_CTX_set_TicketEncCb
  9657. */
  9658. int wolfSSL_CTX_set_TicketEncCtx(WOLFSSL_CTX* ctx, void*);
  9659. /*!
  9660. \brief This function gets the session ticket encrypt user context for the
  9661. callback. For server side use.
  9662. \return userCtx will be returned upon successfully getting the session.
  9663. \return NULL will be returned on failure. This is caused by
  9664. passing invalid arguments to the function, or when the user context has
  9665. not been set.
  9666. \param ctx pointer to the WOLFSSL_CTX object, created
  9667. with wolfSSL_CTX_new().
  9668. _Example_
  9669. \code
  9670. none
  9671. \endcode
  9672. \sa wolfSSL_CTX_set_TicketEncCtx
  9673. */
  9674. void* wolfSSL_CTX_get_TicketEncCtx(WOLFSSL_CTX* ctx);
  9675. /*!
  9676. \brief This function sets the handshake done callback. The hsDoneCb and
  9677. hsDoneCtx members of the WOLFSSL structure are set in this function.
  9678. \return SSL_SUCCESS returned if the function executed without an error.
  9679. The hsDoneCb and hsDoneCtx members of the WOLFSSL struct are set.
  9680. \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL.
  9681. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  9682. \param cb a function pointer of type HandShakeDoneCb with the signature of
  9683. the form: int (*HandShakeDoneCb)(WOLFSSL*, void*);
  9684. \param user_ctx a void pointer to the user registered context.
  9685. _Example_
  9686. \code
  9687. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  9688. WOLFSSL* ssl = wolfSSL_new(ctx);
  9689. int myHsDoneCb(WOLFSSL* ssl, void* user_ctx){
  9690. // callback function
  9691. }
  9692. wolfSSL_SetHsDoneCb(ssl, myHsDoneCb, NULL);
  9693. \endcode
  9694. \sa HandShakeDoneCb
  9695. */
  9696. int wolfSSL_SetHsDoneCb(WOLFSSL* ssl, HandShakeDoneCb cb, void* user_ctx);
  9697. /*!
  9698. \ingroup IO
  9699. \brief This function prints the statistics from the session.
  9700. \return SSL_SUCCESS returned if the function and subroutines return without
  9701. error. The session stats have been successfully retrieved and printed.
  9702. \return BAD_FUNC_ARG returned if the subroutine wolfSSL_get_session_stats()
  9703. was passed an unacceptable argument.
  9704. \return BAD_MUTEX_E returned if there was a mutex error in the subroutine.
  9705. \param none No parameters.
  9706. _Example_
  9707. \code
  9708. // You will need to have a session object to retrieve stats from.
  9709. if(wolfSSL_PrintSessionStats(void) != SSL_SUCCESS ){
  9710. // Did not print session stats
  9711. }
  9712. \endcode
  9713. \sa wolfSSL_get_session_stats
  9714. */
  9715. int wolfSSL_PrintSessionStats(void);
  9716. /*!
  9717. \ingroup IO
  9718. \brief This function gets the statistics for the session.
  9719. \return SSL_SUCCESS returned if the function and subroutines return without
  9720. error. The session stats have been successfully retrieved and printed.
  9721. \return BAD_FUNC_ARG returned if the subroutine wolfSSL_get_session_stats()
  9722. was passed an unacceptable argument.
  9723. \return BAD_MUTEX_E returned if there was a mutex error in the subroutine.
  9724. \param active a word32 pointer representing the total current sessions.
  9725. \param total a word32 pointer representing the total sessions.
  9726. \param peak a word32 pointer representing the peak sessions.
  9727. \param maxSessions a word32 pointer representing the maximum sessions.
  9728. _Example_
  9729. \code
  9730. int wolfSSL_PrintSessionStats(void){
  9731. ret = wolfSSL_get_session_stats(&totalSessionsNow,
  9732. &totalSessionsSeen, &peak, &maxSessions);
  9733. return ret;
  9734. \endcode
  9735. \sa wolfSSL_PrintSessionStats
  9736. */
  9737. int wolfSSL_get_session_stats(unsigned int* active,
  9738. unsigned int* total,
  9739. unsigned int* peak,
  9740. unsigned int* maxSessions);
  9741. /*!
  9742. \ingroup TLS
  9743. \brief This function copies the values of cr and sr then passes through to
  9744. wc_PRF (pseudo random function) and returns that value.
  9745. \return 0 on success
  9746. \return BUFFER_E returned if there will be an error
  9747. with the size of the buffer.
  9748. \return MEMORY_E returned if a subroutine failed
  9749. to allocate dynamic memory.
  9750. \param ms the master secret held in the Arrays structure.
  9751. \param msLen the length of the master secret.
  9752. \param pms the pre-master secret held in the Arrays structure.
  9753. \param pmsLen the length of the pre-master secret.
  9754. \param cr the client random.
  9755. \param sr the server random.
  9756. \param tls1_2 signifies that the version is at least tls version 1.2.
  9757. \param hash_type signifies the hash type.
  9758. _Example_
  9759. \code
  9760. WOLFSSL* ssl;
  9761. called in MakeTlsMasterSecret and retrieves the necessary
  9762. information as follows:
  9763. int MakeTlsMasterSecret(WOLFSSL* ssl){
  9764. int ret;
  9765. ret = wolfSSL_makeTlsMasterSecret(ssl->arrays->masterSecret, SECRET_LEN,
  9766. ssl->arrays->preMasterSecret, ssl->arrays->preMasterSz,
  9767. ssl->arrays->clientRandom, ssl->arrays->serverRandom,
  9768. IsAtLeastTLSv1_2(ssl), ssl->specs.mac_algorithm);
  9769. return ret;
  9770. }
  9771. \endcode
  9772. \sa wc_PRF
  9773. \sa MakeTlsMasterSecret
  9774. */
  9775. int wolfSSL_MakeTlsMasterSecret(unsigned char* ms, word32 msLen,
  9776. const unsigned char* pms, word32 pmsLen,
  9777. const unsigned char* cr, const unsigned char* sr,
  9778. int tls1_2, int hash_type);
  9779. /*!
  9780. \ingroup CertsKeys
  9781. \brief An external facing wrapper to derive TLS Keys.
  9782. \return 0 returned on success.
  9783. \return BUFFER_E returned if the sum of labLen and
  9784. seedLen (computes total size) exceeds the maximum size.
  9785. \return MEMORY_E returned if the allocation of memory failed.
  9786. \param key_data a byte pointer that is allocateded in DeriveTlsKeys
  9787. and passed through to wc_PRF to hold the final hash.
  9788. \param keyLen a word32 type that is derived in DeriveTlsKeys
  9789. from the WOLFSSL structure’s specs member.
  9790. \param ms a constant pointer type holding the master secret
  9791. held in the arrays structure within the WOLFSSL structure.
  9792. \param msLen a word32 type that holds the length of the
  9793. master secret in an enumerated define, SECRET_LEN.
  9794. \param sr a constant byte pointer to the serverRandom
  9795. member of the arrays structure within the WOLFSSL structure.
  9796. \param cr a constant byte pointer to the clientRandom
  9797. member of the arrays structure within the WOLFSSL structure.
  9798. \param tls1_2 an integer type returned from IsAtLeastTLSv1_2().
  9799. \param hash_type an integer type held in the WOLFSSL structure.
  9800. _Example_
  9801. \code
  9802. int DeriveTlsKeys(WOLFSSL* ssl){
  9803. int ret;
  9804. ret = wolfSSL_DeriveTlsKeys(key_data, length, ssl->arrays->masterSecret,
  9805. SECRET_LEN, ssl->arrays->clientRandom,
  9806. IsAtLeastTLSv1_2(ssl), ssl->specs.mac_algorithm);
  9807. }
  9808. \endcode
  9809. \sa wc_PRF
  9810. \sa DeriveTlsKeys
  9811. \sa IsAtLeastTLSv1_2
  9812. */
  9813. int wolfSSL_DeriveTlsKeys(unsigned char* key_data, word32 keyLen,
  9814. const unsigned char* ms, word32 msLen,
  9815. const unsigned char* sr, const unsigned char* cr,
  9816. int tls1_2, int hash_type);
  9817. /*!
  9818. \brief wolfSSL_connect_ex() is an extension that allows
  9819. a HandShake Callback to be set. This can be useful in
  9820. embedded systems for debugging support when a debugger isn’t
  9821. available and sniffing is impractical. The HandShake Callback
  9822. will be called whether or not a handshake error occurred.
  9823. No dynamic memory is used since the maximum number of SSL
  9824. packets is known. Packet names can be accessed through packetNames[].
  9825. The connect extension also allows a Timeout Callback to be set along
  9826. with a timeout value. This is useful if the user doesn’t want
  9827. to wait for the TCP stack to timeout. This extension can be called
  9828. with either, both, or neither callbacks.
  9829. \return SSL_SUCCESS upon success.
  9830. \return GETTIME_ERROR will be returned if gettimeofday()
  9831. encountered an error.
  9832. \return SETITIMER_ERROR will be returned if setitimer()
  9833. encountered an error.
  9834. \return SIGACT_ERROR will be returned if sigaction() encountered an error.
  9835. \return SSL_FATAL_ERROR will be returned if the underlying SSL_connect()
  9836. call encountered an error.
  9837. \param none No parameters.
  9838. _Example_
  9839. \code
  9840. none
  9841. \endcode
  9842. \sa wolfSSL_accept_ex
  9843. */
  9844. int wolfSSL_connect_ex(WOLFSSL* ssl, HandShakeCallBack hsCb,
  9845. TimeoutCallBack toCb, WOLFSSL_TIMEVAL timeout);
  9846. /*!
  9847. \brief wolfSSL_accept_ex() is an extension that allows a HandShake Callback
  9848. to be set. This can be useful in embedded systems for debugging support
  9849. when a debugger isn’t available and sniffing is impractical. The HandShake
  9850. Callback will be called whether or not a handshake error occurred.
  9851. No dynamic memory is used since the maximum number of SSL packets is known.
  9852. Packet names can be accessed through packetNames[]. The connect extension
  9853. also allows a Timeout Callback to be set along with a timeout value.
  9854. This is useful if the user doesn’t want to wait for the TCP stack to timeout.
  9855. This extension can be called with either, both, or neither callbacks.
  9856. \return SSL_SUCCESS upon success.
  9857. \return GETTIME_ERROR will be returned if gettimeofday()
  9858. encountered an error.
  9859. \return SETITIMER_ERROR will be returned if setitimer()
  9860. encountered an error.
  9861. \return SIGACT_ERROR will be returned if sigaction() encountered an error.
  9862. \return SSL_FATAL_ERROR will be returned if the underlying
  9863. SSL_accept() call encountered an error.
  9864. \param none No parameters.
  9865. _Example_
  9866. \code
  9867. none
  9868. \endcode
  9869. \sa wolfSSL_connect_ex
  9870. */
  9871. int wolfSSL_accept_ex(WOLFSSL* ssl, HandShakeCallBacki hsCb,
  9872. TimeoutCallBack toCb, WOLFSSL_TIMEVAL timeout);
  9873. /*!
  9874. \ingroup IO
  9875. \brief This is used to set the internal file pointer for a BIO.
  9876. \return SSL_SUCCESS On successfully setting file pointer.
  9877. \return SSL_FAILURE If an error case was encountered.
  9878. \param bio WOLFSSL_BIO structure to set pair.
  9879. \param fp file pointer to set in bio.
  9880. \param c close file behavior flag.
  9881. _Example_
  9882. \code
  9883. WOLFSSL_BIO* bio;
  9884. XFILE fp;
  9885. int ret;
  9886. bio = wolfSSL_BIO_new(wolfSSL_BIO_s_file());
  9887. ret = wolfSSL_BIO_set_fp(bio, fp, BIO_CLOSE);
  9888. // check ret value
  9889. \endcode
  9890. \sa wolfSSL_BIO_new
  9891. \sa wolfSSL_BIO_s_mem
  9892. \sa wolfSSL_BIO_get_fp
  9893. \sa wolfSSL_BIO_free
  9894. */
  9895. long wolfSSL_BIO_set_fp(WOLFSSL_BIO *bio, XFILE fp, int c);
  9896. /*!
  9897. \ingroup IO
  9898. \brief This is used to get the internal file pointer for a BIO.
  9899. \return SSL_SUCCESS On successfully getting file pointer.
  9900. \return SSL_FAILURE If an error case was encountered.
  9901. \param bio WOLFSSL_BIO structure to set pair.
  9902. \param fp file pointer to set in bio.
  9903. _Example_
  9904. \code
  9905. WOLFSSL_BIO* bio;
  9906. XFILE fp;
  9907. int ret;
  9908. bio = wolfSSL_BIO_new(wolfSSL_BIO_s_file());
  9909. ret = wolfSSL_BIO_get_fp(bio, &fp);
  9910. // check ret value
  9911. \endcode
  9912. \sa wolfSSL_BIO_new
  9913. \sa wolfSSL_BIO_s_mem
  9914. \sa wolfSSL_BIO_set_fp
  9915. \sa wolfSSL_BIO_free
  9916. */
  9917. long wolfSSL_BIO_get_fp(WOLFSSL_BIO *bio, XFILE* fp);
  9918. /*!
  9919. \ingroup Setup
  9920. \brief This function checks that the private key is a match
  9921. with the certificate being used.
  9922. \return SSL_SUCCESS On successfully match.
  9923. \return SSL_FAILURE If an error case was encountered.
  9924. \return <0 All error cases other than SSL_FAILURE are negative values.
  9925. \param ssl WOLFSSL structure to check.
  9926. _Example_
  9927. \code
  9928. WOLFSSL* ssl;
  9929. int ret;
  9930. // create and set up ssl
  9931. ret = wolfSSL_check_private_key(ssl);
  9932. // check ret value
  9933. \endcode
  9934. \sa wolfSSL_new
  9935. \sa wolfSSL_free
  9936. */
  9937. int wolfSSL_check_private_key(const WOLFSSL* ssl);
  9938. /*!
  9939. \ingroup CertsKeys
  9940. \brief This function looks for and returns the extension index
  9941. matching the passed in NID value.
  9942. \return >= 0 If successful the extension index is returned.
  9943. \return -1 If extension is not found or error is encountered.
  9944. \param x509 certificate to get parse through for extension.
  9945. \param nid extension OID to be found.
  9946. \param lastPos start search from extension after lastPos.
  9947. Set to -1 initially.
  9948. _Example_
  9949. \code
  9950. const WOLFSSL_X509* x509;
  9951. int lastPos = -1;
  9952. int idx;
  9953. idx = wolfSSL_X509_get_ext_by_NID(x509, NID_basic_constraints, lastPos);
  9954. \endcode
  9955. */
  9956. int wolfSSL_X509_get_ext_by_NID(const WOLFSSL_X509* x509,
  9957. int nid, int lastPos);
  9958. /*!
  9959. \ingroup CertsKeys
  9960. \brief This function looks for and returns the extension
  9961. matching the passed in NID value.
  9962. \return pointer If successful a STACK_OF(WOLFSSL_ASN1_OBJECT)
  9963. pointer is returned.
  9964. \return NULL If extension is not found or error is encountered.
  9965. \param x509 certificate to get parse through for extension.
  9966. \param nid extension OID to be found.
  9967. \param c if not NULL is set to -2 for multiple extensions found -1
  9968. if not found, 0 if found and not critical and 1 if found and critical.
  9969. \param idx if NULL return first extension matched otherwise if not
  9970. stored in x509 start at idx.
  9971. _Example_
  9972. \code
  9973. const WOLFSSL_X509* x509;
  9974. int c;
  9975. int idx = 0;
  9976. STACK_OF(WOLFSSL_ASN1_OBJECT)* sk;
  9977. sk = wolfSSL_X509_get_ext_d2i(x509, NID_basic_constraints, &c, &idx);
  9978. //check sk for NULL and then use it. sk needs freed after done.
  9979. \endcode
  9980. \sa wolfSSL_sk_ASN1_OBJECT_free
  9981. */
  9982. void* wolfSSL_X509_get_ext_d2i(const WOLFSSL_X509* x509,
  9983. int nid, int* c, int* idx);
  9984. /*!
  9985. \ingroup CertsKeys
  9986. \brief This function returns the hash of the DER certificate.
  9987. \return SSL_SUCCESS On successfully creating a hash.
  9988. \return SSL_FAILURE Returned on bad input or unsuccessful hash.
  9989. \param x509 certificate to get the hash of.
  9990. \param digest the hash algorithm to use.
  9991. \param buf buffer to hold hash.
  9992. \param len length of buffer.
  9993. _Example_
  9994. \code
  9995. WOLFSSL_X509* x509;
  9996. unsigned char buffer[64];
  9997. unsigned int bufferSz;
  9998. int ret;
  9999. ret = wolfSSL_X509_digest(x509, wolfSSL_EVP_sha256(), buffer, &bufferSz);
  10000. //check ret value
  10001. \endcode
  10002. \sa none
  10003. */
  10004. int wolfSSL_X509_digest(const WOLFSSL_X509* x509,
  10005. const WOLFSSL_EVP_MD* digest, unsigned char* buf, unsigned int* len);
  10006. /*!
  10007. \ingroup Setup
  10008. \brief his is used to set the certificate for WOLFSSL structure to use
  10009. during a handshake.
  10010. \return SSL_SUCCESS On successful setting argument.
  10011. \return SSL_FAILURE If a NULL argument passed in.
  10012. \param ssl WOLFSSL structure to set certificate in.
  10013. \param x509 certificate to use.
  10014. _Example_
  10015. \code WOLFSSL* ssl;
  10016. WOLFSSL_X509* x509
  10017. int ret;
  10018. // create ssl object and x509
  10019. ret = wolfSSL_use_certificate(ssl, x509);
  10020. // check ret value
  10021. \endcode
  10022. \sa wolfSSL_new
  10023. \sa wolfSSL_free
  10024. */
  10025. int wolfSSL_use_certificate(WOLFSSL* ssl, WOLFSSL_X509* x509);
  10026. /*!
  10027. \ingroup Setup
  10028. \brief This is used to set the certificate for WOLFSSL structure
  10029. to use during a handshake. A DER formatted buffer is expected.
  10030. \return SSL_SUCCESS On successful setting argument.
  10031. \return SSL_FAILURE If a NULL argument passed in.
  10032. \param ssl WOLFSSL structure to set certificate in.
  10033. \param der DER certificate to use.
  10034. \param derSz size of the DER buffer passed in.
  10035. _Example_
  10036. \code
  10037. WOLFSSL* ssl;
  10038. unsigned char* der;
  10039. int derSz;
  10040. int ret;
  10041. // create ssl object and set DER variables
  10042. ret = wolfSSL_use_certificate_ASN1(ssl, der, derSz);
  10043. // check ret value
  10044. \endcode
  10045. \sa wolfSSL_new
  10046. \sa wolfSSL_free
  10047. */
  10048. int wolfSSL_use_certificate_ASN1(WOLFSSL* ssl, unsigned char* der,
  10049. int derSz);
  10050. /*!
  10051. \ingroup CertsKeys
  10052. \brief This is used to set the private key for the WOLFSSL structure.
  10053. \return SSL_SUCCESS On successful setting argument.
  10054. \return SSL_FAILURE If a NULL ssl passed in. All error
  10055. cases will be negative values.
  10056. \param ssl WOLFSSL structure to set argument in.
  10057. \param pkey private key to use.
  10058. _Example_
  10059. \code
  10060. WOLFSSL* ssl;
  10061. WOLFSSL_EVP_PKEY* pkey;
  10062. int ret;
  10063. // create ssl object and set up private key
  10064. ret = wolfSSL_use_PrivateKey(ssl, pkey);
  10065. // check ret value
  10066. \endcode
  10067. \sa wolfSSL_new
  10068. \sa wolfSSL_free
  10069. */
  10070. int wolfSSL_use_PrivateKey(WOLFSSL* ssl, WOLFSSL_EVP_PKEY* pkey);
  10071. /*!
  10072. \ingroup CertsKeys
  10073. \brief This is used to set the private key for the WOLFSSL
  10074. structure. A DER formatted key buffer is expected.
  10075. \return SSL_SUCCESS On successful setting parsing and
  10076. setting the private key.
  10077. \return SSL_FAILURE If an NULL ssl passed in. All error cases
  10078. will be negative values.
  10079. \param pri type of private key.
  10080. \param ssl WOLFSSL structure to set argument in.
  10081. \param der buffer holding DER key.
  10082. \param derSz size of der buffer.
  10083. _Example_
  10084. \code
  10085. WOLFSSL* ssl;
  10086. unsigned char* pkey;
  10087. long pkeySz;
  10088. int ret;
  10089. // create ssl object and set up private key
  10090. ret = wolfSSL_use_PrivateKey_ASN1(1, ssl, pkey, pkeySz);
  10091. // check ret value
  10092. \endcode
  10093. \sa wolfSSL_new
  10094. \sa wolfSSL_free
  10095. \sa wolfSSL_use_PrivateKey
  10096. */
  10097. int wolfSSL_use_PrivateKey_ASN1(int pri, WOLFSSL* ssl,
  10098. unsigned char* der, long derSz);
  10099. /*!
  10100. \ingroup CertsKeys
  10101. \brief This is used to set the private key for the WOLFSSL
  10102. structure. A DER formatted RSA key buffer is expected.
  10103. \return SSL_SUCCESS On successful setting parsing and setting
  10104. the private key.
  10105. \return SSL_FAILURE If an NULL ssl passed in. All error cases
  10106. will be negative values.
  10107. \param ssl WOLFSSL structure to set argument in.
  10108. \param der buffer holding DER key.
  10109. \param derSz size of der buffer.
  10110. _Example_
  10111. \code
  10112. WOLFSSL* ssl;
  10113. unsigned char* pkey;
  10114. long pkeySz;
  10115. int ret;
  10116. // create ssl object and set up RSA private key
  10117. ret = wolfSSL_use_RSAPrivateKey_ASN1(ssl, pkey, pkeySz);
  10118. // check ret value
  10119. \endcode
  10120. \sa wolfSSL_new
  10121. \sa wolfSSL_free
  10122. \sa wolfSSL_use_PrivateKey
  10123. */
  10124. int wolfSSL_use_RSAPrivateKey_ASN1(WOLFSSL* ssl, unsigned char* der,
  10125. long derSz);
  10126. /*!
  10127. \ingroup CertsKeys
  10128. \brief This function duplicates the parameters in dsa to a
  10129. newly created WOLFSSL_DH structure.
  10130. \return WOLFSSL_DH If duplicated returns WOLFSSL_DH structure
  10131. \return NULL upon failure
  10132. \param dsa WOLFSSL_DSA structure to duplicate.
  10133. _Example_
  10134. \code
  10135. WOLFSSL_DH* dh;
  10136. WOLFSSL_DSA* dsa;
  10137. // set up dsa
  10138. dh = wolfSSL_DSA_dup_DH(dsa);
  10139. // check dh is not null
  10140. \endcode
  10141. \sa none
  10142. */
  10143. WOLFSSL_DH *wolfSSL_DSA_dup_DH(const WOLFSSL_DSA *r);
  10144. /*!
  10145. \ingroup Setup
  10146. \brief This is used to get the master key after completing a handshake.
  10147. \return >0 On successfully getting data returns a value greater than 0
  10148. \return 0 If no random data buffer or an error state returns 0
  10149. \return max If outSz passed in is 0 then the maximum buffer
  10150. size needed is returned
  10151. \param ses WOLFSSL_SESSION structure to get master secret buffer from.
  10152. \param out buffer to hold data.
  10153. \param outSz size of out buffer passed in. (if 0 function will
  10154. return max buffer size needed)
  10155. _Example_
  10156. \code
  10157. WOLFSSL_SESSION ssl;
  10158. unsigned char* buffer;
  10159. size_t bufferSz;
  10160. size_t ret;
  10161. // complete handshake and get session structure
  10162. bufferSz = wolfSSL_SESSION_get_master_secret(ses, NULL, 0);
  10163. buffer = malloc(bufferSz);
  10164. ret = wolfSSL_SESSION_get_master_secret(ses, buffer, bufferSz);
  10165. // check ret value
  10166. \endcode
  10167. \sa wolfSSL_new
  10168. \sa wolfSSL_free
  10169. */
  10170. int wolfSSL_SESSION_get_master_key(const WOLFSSL_SESSION* ses,
  10171. unsigned char* out, int outSz);
  10172. /*!
  10173. \ingroup Setup
  10174. \brief This is used to get the master secret key length.
  10175. \return size Returns master secret key size.
  10176. \param ses WOLFSSL_SESSION structure to get master secret buffer from.
  10177. _Example_
  10178. \code
  10179. WOLFSSL_SESSION ssl;
  10180. unsigned char* buffer;
  10181. size_t bufferSz;
  10182. size_t ret;
  10183. // complete handshake and get session structure
  10184. bufferSz = wolfSSL_SESSION_get_master_secret_length(ses);
  10185. buffer = malloc(bufferSz);
  10186. // check ret value
  10187. \endcode
  10188. \sa wolfSSL_new
  10189. \sa wolfSSL_free
  10190. */
  10191. int wolfSSL_SESSION_get_master_key_length(const WOLFSSL_SESSION* ses);
  10192. /*!
  10193. \ingroup Setup
  10194. \brief This is a setter function for the WOLFSSL_X509_STORE
  10195. structure in ctx.
  10196. \return none No return.
  10197. \param ctx pointer to the WOLFSSL_CTX structure for setting
  10198. cert store pointer.
  10199. \param str pointer to the WOLFSSL_X509_STORE to set in ctx.
  10200. _Example_
  10201. \code
  10202. WOLFSSL_CTX ctx;
  10203. WOLFSSL_X509_STORE* st;
  10204. // setup ctx and st
  10205. st = wolfSSL_CTX_set_cert_store(ctx, st);
  10206. //use st
  10207. \endcode
  10208. \sa wolfSSL_CTX_new
  10209. \sa wolfSSL_CTX_free
  10210. */
  10211. void wolfSSL_CTX_set_cert_store(WOLFSSL_CTX* ctx,
  10212. WOLFSSL_X509_STORE* str);
  10213. /*!
  10214. \ingroup CertsKeys
  10215. \brief This function get the DER buffer from bio and converts it
  10216. to a WOLFSSL_X509 structure.
  10217. \return pointer returns a WOLFSSL_X509 structure pointer on success.
  10218. \return Null returns NULL on failure
  10219. \param bio pointer to the WOLFSSL_BIO structure that has the DER
  10220. certificate buffer.
  10221. \param x509 pointer that get set to new WOLFSSL_X509 structure created.
  10222. _Example_
  10223. \code
  10224. WOLFSSL_BIO* bio;
  10225. WOLFSSL_X509* x509;
  10226. // load DER into bio
  10227. x509 = wolfSSL_d2i_X509_bio(bio, NULL);
  10228. Or
  10229. wolfSSL_d2i_X509_bio(bio, &x509);
  10230. // use x509 returned (check for NULL)
  10231. \endcode
  10232. \sa none
  10233. */
  10234. WOLFSSL_X509* wolfSSL_d2i_X509_bio(WOLFSSL_BIO* bio, WOLFSSL_X509** x509);
  10235. /*!
  10236. \ingroup Setup
  10237. \brief This is a getter function for the WOLFSSL_X509_STORE
  10238. structure in ctx.
  10239. \return WOLFSSL_X509_STORE* On successfully getting the pointer.
  10240. \return NULL Returned if NULL arguments are passed in.
  10241. \param ctx pointer to the WOLFSSL_CTX structure for getting cert
  10242. store pointer.
  10243. _Example_
  10244. \code
  10245. WOLFSSL_CTX ctx;
  10246. WOLFSSL_X509_STORE* st;
  10247. // setup ctx
  10248. st = wolfSSL_CTX_get_cert_store(ctx);
  10249. //use st
  10250. \endcode
  10251. \sa wolfSSL_CTX_new
  10252. \sa wolfSSL_CTX_free
  10253. \sa wolfSSL_CTX_set_cert_store
  10254. */
  10255. WOLFSSL_X509_STORE* wolfSSL_CTX_get_cert_store(WOLFSSL_CTX* ctx);
  10256. /*!
  10257. \ingroup IO
  10258. \brief Gets the number of pending bytes to read. If BIO type is BIO_BIO
  10259. then is the number to read from pair. If BIO contains an SSL object then
  10260. is pending data from SSL object (wolfSSL_pending(ssl)). If is BIO_MEMORY
  10261. type then returns the size of memory buffer.
  10262. \return >=0 number of pending bytes.
  10263. \param bio pointer to the WOLFSSL_BIO structure that has already
  10264. been created.
  10265. _Example_
  10266. \code
  10267. WOLFSSL_BIO* bio;
  10268. int pending;
  10269. bio = wolfSSL_BIO_new();
  10270. pending = wolfSSL_BIO_ctrl_pending(bio);
  10271. \endcode
  10272. \sa wolfSSL_BIO_make_bio_pair
  10273. \sa wolfSSL_BIO_new
  10274. */
  10275. size_t wolfSSL_BIO_ctrl_pending(WOLFSSL_BIO *b);
  10276. /*!
  10277. \ingroup Setup
  10278. \brief This is used to get the random data sent by the server
  10279. during the handshake.
  10280. \return >0 On successfully getting data returns a value greater than 0
  10281. \return 0 If no random data buffer or an error state returns 0
  10282. \return max If outSz passed in is 0 then the maximum buffer size
  10283. needed is returned
  10284. \param ssl WOLFSSL structure to get clients random data buffer from.
  10285. \param out buffer to hold random data.
  10286. \param outSz size of out buffer passed in. (if 0 function will return max
  10287. buffer size needed)
  10288. _Example_
  10289. \code
  10290. WOLFSSL ssl;
  10291. unsigned char* buffer;
  10292. size_t bufferSz;
  10293. size_t ret;
  10294. bufferSz = wolfSSL_get_server_random(ssl, NULL, 0);
  10295. buffer = malloc(bufferSz);
  10296. ret = wolfSSL_get_server_random(ssl, buffer, bufferSz);
  10297. // check ret value
  10298. \endcode
  10299. \sa wolfSSL_new
  10300. \sa wolfSSL_free
  10301. */
  10302. size_t wolfSSL_get_server_random(const WOLFSSL *ssl,
  10303. unsigned char *out, size_t outlen);
  10304. /*!
  10305. \ingroup Setup
  10306. \brief This is used to get the random data sent by the client during
  10307. the handshake.
  10308. \return >0 On successfully getting data returns a value greater than 0
  10309. \return 0 If no random data buffer or an error state returns 0
  10310. \return max If outSz passed in is 0 then the maximum buffer size needed
  10311. is returned
  10312. \param ssl WOLFSSL structure to get clients random data buffer from.
  10313. \param out buffer to hold random data.
  10314. \param outSz size of out buffer passed in. (if 0 function will return max
  10315. buffer size needed)
  10316. _Example_
  10317. \code
  10318. WOLFSSL ssl;
  10319. unsigned char* buffer;
  10320. size_t bufferSz;
  10321. size_t ret;
  10322. bufferSz = wolfSSL_get_client_random(ssl, NULL, 0);
  10323. buffer = malloc(bufferSz);
  10324. ret = wolfSSL_get_client_random(ssl, buffer, bufferSz);
  10325. // check ret value
  10326. \endcode
  10327. \sa wolfSSL_new
  10328. \sa wolfSSL_free
  10329. */
  10330. size_t wolfSSL_get_client_random(const WOLFSSL* ssl,
  10331. unsigned char* out, size_t outSz);
  10332. /*!
  10333. \ingroup Setup
  10334. \brief This is a getter function for the password callback set in ctx.
  10335. \return func On success returns the callback function.
  10336. \return NULL If ctx is NULL then NULL is returned.
  10337. \param ctx WOLFSSL_CTX structure to get call back from.
  10338. _Example_
  10339. \code
  10340. WOLFSSL_CTX* ctx;
  10341. wc_pem_password_cb cb;
  10342. // setup ctx
  10343. cb = wolfSSL_CTX_get_default_passwd_cb(ctx);
  10344. //use cb
  10345. \endcode
  10346. \sa wolfSSL_CTX_new
  10347. \sa wolfSSL_CTX_free
  10348. */
  10349. wc_pem_password_cb* wolfSSL_CTX_get_default_passwd_cb(WOLFSSL_CTX*
  10350. ctx);
  10351. /*!
  10352. \ingroup Setup
  10353. \brief This is a getter function for the password callback user
  10354. data set in ctx.
  10355. \return pointer On success returns the user data pointer.
  10356. \return NULL If ctx is NULL then NULL is returned.
  10357. \param ctx WOLFSSL_CTX structure to get user data from.
  10358. _Example_
  10359. \code
  10360. WOLFSSL_CTX* ctx;
  10361. void* data;
  10362. // setup ctx
  10363. data = wolfSSL_CTX_get_default_passwd_cb(ctx);
  10364. //use data
  10365. \endcode
  10366. \sa wolfSSL_CTX_new
  10367. \sa wolfSSL_CTX_free
  10368. */
  10369. void *wolfSSL_CTX_get_default_passwd_cb_userdata(WOLFSSL_CTX *ctx);
  10370. /*!
  10371. \ingroup CertsKeys
  10372. \brief This function behaves the same as wolfSSL_PEM_read_bio_X509.
  10373. AUX signifies containing extra information such as trusted/rejected use
  10374. cases and friendly name for human readability.
  10375. \return WOLFSSL_X509 on successfully parsing the PEM buffer a WOLFSSL_X509
  10376. structure is returned.
  10377. \return Null if failed to parse PEM buffer.
  10378. \param bp WOLFSSL_BIO structure to get PEM buffer from.
  10379. \param x if setting WOLFSSL_X509 by function side effect.
  10380. \param cb password callback.
  10381. \param u NULL terminated user password.
  10382. _Example_
  10383. \code
  10384. WOLFSSL_BIO* bio;
  10385. WOLFSSL_X509* x509;
  10386. // setup bio
  10387. X509 = wolfSSL_PEM_read_bio_X509_AUX(bio, NULL, NULL, NULL);
  10388. //check x509 is not null and then use it
  10389. \endcode
  10390. \sa wolfSSL_PEM_read_bio_X509
  10391. */
  10392. WOLFSSL_X509 *wolfSSL_PEM_read_bio_X509_AUX
  10393. (WOLFSSL_BIO *bp, WOLFSSL_X509 **x, wc_pem_password_cb *cb, void *u);
  10394. /*!
  10395. \ingroup CertsKeys
  10396. \brief Initializes the WOLFSSL_CTX structure’s dh member with the
  10397. Diffie-Hellman parameters.
  10398. \return SSL_SUCCESS returned if the function executed successfully.
  10399. \return BAD_FUNC_ARG returned if the ctx or dh structures are NULL.
  10400. \return SSL_FATAL_ERROR returned if there was an error setting a
  10401. structure value.
  10402. \return MEMORY_E returned if their was a failure to allocate memory.
  10403. \param ctx a pointer to a WOLFSSL_CTX structure, created using
  10404. wolfSSL_CTX_new().
  10405. \param dh a pointer to a WOLFSSL_DH structure.
  10406. _Example_
  10407. \code
  10408. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  10409. WOLFSSL_DH* dh;
  10410. return wolfSSL_CTX_set_tmp_dh(ctx, dh);
  10411. \endcode
  10412. \sa wolfSSL_BN_bn2bin
  10413. */
  10414. long wolfSSL_CTX_set_tmp_dh(WOLFSSL_CTX* ctx, WOLFSSL_DH* dh);
  10415. /*!
  10416. \ingroup CertsKeys
  10417. \brief This function get the DSA parameters from a PEM buffer in bio.
  10418. \return WOLFSSL_DSA on successfully parsing the PEM buffer a WOLFSSL_DSA
  10419. structure is created and returned.
  10420. \return Null if failed to parse PEM buffer.
  10421. \param bio pointer to the WOLFSSL_BIO structure for getting PEM
  10422. memory pointer.
  10423. \param x pointer to be set to new WOLFSSL_DSA structure.
  10424. \param cb password callback function.
  10425. \param u null terminated password string.
  10426. _Example_
  10427. \code
  10428. WOLFSSL_BIO* bio;
  10429. WOLFSSL_DSA* dsa;
  10430. // setup bio
  10431. dsa = wolfSSL_PEM_read_bio_DSAparams(bio, NULL, NULL, NULL);
  10432. // check dsa is not NULL and then use dsa
  10433. \endcode
  10434. \sa none
  10435. */
  10436. WOLFSSL_DSA *wolfSSL_PEM_read_bio_DSAparams(WOLFSSL_BIO *bp,
  10437. WOLFSSL_DSA **x, wc_pem_password_cb *cb, void *u);
  10438. /*!
  10439. \ingroup Debug
  10440. \brief This function returns the absolute value of the last error from
  10441. WOLFSSL_ERROR encountered.
  10442. \return error Returns absolute value of last error.
  10443. \param none No parameters.
  10444. _Example_
  10445. \code
  10446. unsigned long err;
  10447. ...
  10448. err = wolfSSL_ERR_peek_last_error();
  10449. // inspect err value
  10450. \endcode
  10451. \sa wolfSSL_ERR_print_errors_fp
  10452. */
  10453. unsigned long wolfSSL_ERR_peek_last_error(void);
  10454. /*!
  10455. \ingroup CertsKeys
  10456. \brief This function gets the peer’s certificate chain.
  10457. \return pointer returns a pointer to the peer’s Certificate stack.
  10458. \return NULL returned if no peer certificate.
  10459. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10460. _Example_
  10461. \code
  10462. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  10463. WOLFSSL* ssl = wolfSSL_new(ctx);
  10464. ...
  10465. wolfSSL_connect(ssl);
  10466. STACK_OF(WOLFSSL_X509)* chain = wolfSSL_get_peer_cert_chain(ssl);
  10467. ifchain){
  10468. // You have a pointer to the peer certificate chain
  10469. }
  10470. \endcode
  10471. \sa wolfSSL_X509_get_issuer_name
  10472. \sa wolfSSL_X509_get_subject_name
  10473. \sa wolfSSL_X509_get_isCA
  10474. */
  10475. WOLF_STACK_OF(WOLFSSL_X509)* wolfSSL_get_peer_cert_chain(const WOLFSSL*);
  10476. /*!
  10477. \ingroup Setup
  10478. \brief This function resets option bits of WOLFSSL_CTX object.
  10479. \return option new option bits
  10480. \param ctx pointer to the SSL context.
  10481. _Example_
  10482. \code
  10483. WOLFSSL_CTX* ctx = 0;
  10484. ...
  10485. wolfSSL_CTX_clear_options(ctx, SSL_OP_NO_TLSv1);
  10486. \endcode
  10487. \sa wolfSSL_CTX_new
  10488. \sa wolfSSL_new
  10489. \sa wolfSSL_free
  10490. */
  10491. long wolfSSL_CTX_clear_options(WOLFSSL_CTX* ctx, long opt);
  10492. /*!
  10493. \ingroup IO
  10494. \brief This function sets the jObjectRef member of the WOLFSSL structure.
  10495. \return SSL_SUCCESS returned if jObjectRef is properly set to objPtr.
  10496. \return SSL_FAILURE returned if the function did not properly execute and
  10497. jObjectRef is not set.
  10498. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10499. \param objPtr a void pointer that will be set to jObjectRef.
  10500. _Example_
  10501. \code
  10502. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  10503. WOLFSSL* ssl = WOLFSSL_new();
  10504. void* objPtr = &obj;
  10505. ...
  10506. if(wolfSSL_set_jobject(ssl, objPtr)){
  10507. // The success case
  10508. }
  10509. \endcode
  10510. \sa wolfSSL_get_jobject
  10511. */
  10512. int wolfSSL_set_jobject(WOLFSSL* ssl, void* objPtr);
  10513. /*!
  10514. \ingroup IO
  10515. \brief This function returns the jObjectRef member of the WOLFSSL structure.
  10516. \return value If the WOLFSSL struct is not NULL, the function returns the
  10517. jObjectRef value.
  10518. \return NULL returned if the WOLFSSL struct is NULL.
  10519. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10520. _Example_
  10521. \code
  10522. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  10523. WOLFSSL* ssl = wolfSSL(ctx);
  10524. ...
  10525. void* jobject = wolfSSL_get_jobject(ssl);
  10526. if(jobject != NULL){
  10527. // Success case
  10528. }
  10529. \endcode
  10530. \sa wolfSSL_set_jobject
  10531. */
  10532. void* wolfSSL_get_jobject(WOLFSSL* ssl);
  10533. /*!
  10534. \ingroup Setup
  10535. \brief This function sets a callback in the ssl. The callback is to
  10536. observe handshake messages. NULL value of cb resets the callback.
  10537. \return SSL_SUCCESS On success.
  10538. \return SSL_FAILURE If an NULL ssl passed in.
  10539. \param ssl WOLFSSL structure to set callback argument.
  10540. _Example_
  10541. \code
  10542. static cb(int write_p, int version, int content_type,
  10543. const void *buf, size_t len, WOLFSSL *ssl, void *arg)
  10544. WOLFSSL* ssl;
  10545. ret = wolfSSL_set_msg_callback(ssl, cb);
  10546. // check ret
  10547. \endcode
  10548. \sa wolfSSL_set_msg_callback_arg
  10549. */
  10550. int wolfSSL_set_msg_callback(WOLFSSL *ssl, SSL_Msg_Cb cb);
  10551. /*!
  10552. \ingroup Setup
  10553. \brief This function sets associated callback context value in the ssl.
  10554. The value is handed over to the callback argument.
  10555. \return none No return.
  10556. \param ssl WOLFSSL structure to set callback argument.
  10557. _Example_
  10558. \code
  10559. static cb(int write_p, int version, int content_type,
  10560. const void *buf, size_t len, WOLFSSL *ssl, void *arg)
  10561. WOLFSSL* ssl;
  10562. ret = wolfSSL_set_msg_callback(ssl, cb);
  10563. // check ret
  10564. wolfSSL_set_msg_callback(ssl, arg);
  10565. \endcode
  10566. \sa wolfSSL_set_msg_callback
  10567. */
  10568. int wolfSSL_set_msg_callback_arg(WOLFSSL *ssl, void* arg);
  10569. /*!
  10570. \ingroup CertsKeys
  10571. \brief This function returns the next, if any, altname from the peer certificate.
  10572. \return NULL if there is not a next altname.
  10573. \return cert->altNamesNext->name from the WOLFSSL_X509 structure that is a
  10574. string value from the altName list is returned if it exists.
  10575. \param cert a pointer to the wolfSSL_X509 structure.
  10576. _Example_
  10577. \code
  10578. WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
  10579. DYNAMIC_TYPE_X509);
  10580. int x509NextAltName = wolfSSL_X509_get_next_altname(x509);
  10581. if(x509NextAltName == NULL){
  10582. //There isn’t another alt name
  10583. }
  10584. \endcode
  10585. \sa wolfSSL_X509_get_issuer_name
  10586. \sa wolfSSL_X509_get_subject_name
  10587. */
  10588. char* wolfSSL_X509_get_next_altname(WOLFSSL_X509*);
  10589. /*!
  10590. \ingroup CertsKeys
  10591. \brief The function checks to see if x509 is NULL and if it’s not, it
  10592. returns the notBefore member of the x509 struct.
  10593. \return pointer to struct with ASN1_TIME to the notBefore
  10594. member of the x509 struct.
  10595. \return NULL the function returns NULL if the x509 structure is NULL.
  10596. \param x509 a pointer to the WOLFSSL_X509 struct.
  10597. _Example_
  10598. \code
  10599. WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALLOC(sizeof(WOLFSSL_X509), NULL,
  10600. DYNAMIC_TYPE_X509) ;
  10601. const WOLFSSL_ASN1_TIME* notAfter = wolfSSL_X509_get_notBefore(x509);
  10602. if(notAfter == NULL){
  10603. //The x509 object was NULL
  10604. }
  10605. \endcode
  10606. \sa wolfSSL_X509_get_notAfter
  10607. */
  10608. WOLFSSL_ASN1_TIME* wolfSSL_X509_get_notBefore(WOLFSSL_X509*);
  10609. /*!
  10610. \ingroup IO
  10611. \brief This function is called on the client side and initiates an SSL/TLS
  10612. handshake with a server. When this function is called, the underlying
  10613. communication channel has already been set up.
  10614. wolfSSL_connect() works with both blocking and non-blocking I/O. When the
  10615. underlying I/O is non-blocking, wolfSSL_connect() will return when the
  10616. underlying I/O could not satisfy the needs of wolfSSL_connect to continue
  10617. the handshake. In this case, a call to wolfSSL_get_error() will yield
  10618. either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process
  10619. must then repeat the call to wolfSSL_connect() when the underlying I/O is
  10620. ready and wolfSSL will pick up where it left off. When using a non-blocking
  10621. socket, nothing needs to be done, but select() can be used to check for the
  10622. required condition.
  10623. If the underlying I/O is blocking, wolfSSL_connect() will only return once
  10624. the handshake has been finished or an error occurred.
  10625. wolfSSL takes a different approach to certificate verification than OpenSSL
  10626. does. The default policy for the client is to verify the server, this
  10627. means that if you don't load CAs to verify the server you'll get a connect
  10628. error, unable to verify (-155). It you want to mimic OpenSSL behavior of
  10629. having SSL_connect succeed even if verifying the server fails and reducing
  10630. security you can do this by calling:
  10631. SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling SSL_new();
  10632. Though it's not recommended.
  10633. \return SSL_SUCCESS If successful.
  10634. \return SSL_FATAL_ERROR will be returned if an error occurred. To get a
  10635. more detailed error code, call wolfSSL_get_error().
  10636. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10637. _Example_
  10638. \code
  10639. int ret = 0;
  10640. int err = 0;
  10641. WOLFSSL* ssl;
  10642. char buffer[80];
  10643. ...
  10644. ret = wolfSSL_connect(ssl);
  10645. if (ret != SSL_SUCCESS) {
  10646. err = wolfSSL_get_error(ssl, ret);
  10647. printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
  10648. }
  10649. \endcode
  10650. \sa wolfSSL_get_error
  10651. \sa wolfSSL_accept
  10652. */
  10653. int wolfSSL_connect(WOLFSSL* ssl);
  10654. /*!
  10655. \ingroup Setup
  10656. \brief This function is called on the server side to indicate that a
  10657. HelloRetryRequest message must contain a Cookie and, in case of using
  10658. protocol DTLS v1.3, that the handshake will always include a cookie
  10659. exchange. Please note that when using protocol DTLS v1.3, the cookie
  10660. exchange is enabled by default. The Cookie holds a hash of the current
  10661. transcript so that another server process can handle the ClientHello in
  10662. reply. The secret is used when generating the integrity check on the Cookie
  10663. data.
  10664. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10665. \param [in] secret a pointer to a buffer holding the secret.
  10666. Passing NULL indicates to generate a new random secret.
  10667. \param [in] secretSz Size of the secret in bytes.
  10668. Passing 0 indicates to use the default size: WC_SHA256_DIGEST_SIZE (or WC_SHA_DIGEST_SIZE when SHA-256 not available).
  10669. \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
  10670. \return SIDE_ERROR if called with a client.
  10671. \return WOLFSSL_SUCCESS if successful.
  10672. \return MEMORY_ERROR if allocating dynamic memory for storing secret failed.
  10673. \return Another -ve value on internal error.
  10674. _Example_
  10675. \code
  10676. int ret;
  10677. WOLFSSL* ssl;
  10678. char secret[32];
  10679. ...
  10680. ret = wolfSSL__send_hrr_cookie(ssl, secret, sizeof(secret));
  10681. if (ret != WOLFSSL_SUCCESS) {
  10682. // failed to set use of Cookie and secret
  10683. }
  10684. \endcode
  10685. \sa wolfSSL_new
  10686. \sa wolfSSL_disable_hrr_cookie
  10687. */
  10688. int wolfSSL_send_hrr_cookie(WOLFSSL* ssl,
  10689. const unsigned char* secret, unsigned int secretSz);
  10690. /*!
  10691. \ingroup Setup
  10692. \brief This function is called on the server side to indicate that a
  10693. HelloRetryRequest message must NOT contain a Cookie and that, if using
  10694. protocol DTLS v1.3, a cookie exchange will not be included in the
  10695. handshake. Please note that not doing a cookie exchange when using protocol
  10696. DTLS v1.3 can make the server susceptible to DoS/Amplification attacks.
  10697. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10698. \return WOLFSSL_SUCCESS if successful
  10699. \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3
  10700. \return SIDE_ERROR if invoked on client
  10701. \sa wolfSSL_send_hrr_cookie
  10702. */
  10703. int wolfSSL_disable_hrr_cookie(WOLFSSL* ssl);
  10704. /*!
  10705. \ingroup Setup
  10706. \brief This function is called on the server to stop it from sending
  10707. a resumption session ticket once the handshake is complete.
  10708. \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
  10709. with wolfSSL_CTX_new().
  10710. \return BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3.
  10711. \return SIDE_ERROR if called with a client.
  10712. \return 0 if successful.
  10713. _Example_
  10714. \code
  10715. int ret;
  10716. WOLFSSL_CTX* ctx;
  10717. ...
  10718. ret = wolfSSL_CTX_no_ticket_TLSv13(ctx);
  10719. if (ret != 0) {
  10720. // failed to set no ticket
  10721. }
  10722. \endcode
  10723. \sa wolfSSL_no_ticket_TLSv13
  10724. */
  10725. int wolfSSL_CTX_no_ticket_TLSv13(WOLFSSL_CTX* ctx);
  10726. /*!
  10727. \ingroup Setup
  10728. \brief This function is called on the server to stop it from sending
  10729. a resumption session ticket once the handshake is complete.
  10730. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10731. \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
  10732. \return SIDE_ERROR if called with a client.
  10733. \return 0 if successful.
  10734. _Example_
  10735. \code
  10736. int ret;
  10737. WOLFSSL* ssl;
  10738. ...
  10739. ret = wolfSSL_no_ticket_TLSv13(ssl);
  10740. if (ret != 0) {
  10741. // failed to set no ticket
  10742. }
  10743. \endcode
  10744. \sa wolfSSL_CTX_no_ticket_TLSv13
  10745. */
  10746. int wolfSSL_no_ticket_TLSv13(WOLFSSL* ssl);
  10747. /*!
  10748. \ingroup Setup
  10749. \brief This function is called on a TLS v1.3 wolfSSL context to disallow
  10750. Diffie-Hellman (DH) style key exchanges when handshakes are using
  10751. pre-shared keys for authentication.
  10752. \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
  10753. with wolfSSL_CTX_new().
  10754. \return BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3.
  10755. \return 0 if successful.
  10756. _Example_
  10757. \code
  10758. int ret;
  10759. WOLFSSL_CTX* ctx;
  10760. ...
  10761. ret = wolfSSL_CTX_no_dhe_psk(ctx);
  10762. if (ret != 0) {
  10763. // failed to set no DHE for PSK handshakes
  10764. }
  10765. \endcode
  10766. \sa wolfSSL_no_dhe_psk
  10767. */
  10768. int wolfSSL_CTX_no_dhe_psk(WOLFSSL_CTX* ctx);
  10769. /*!
  10770. \ingroup Setup
  10771. \brief This function is called on a TLS v1.3 client or server wolfSSL to
  10772. disallow Diffie-Hellman (DH) style key exchanges when handshakes are using
  10773. pre-shared keys for authentication.
  10774. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10775. \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
  10776. \return 0 if successful.
  10777. _Example_
  10778. \code
  10779. int ret;
  10780. WOLFSSL* ssl;
  10781. ...
  10782. ret = wolfSSL_no_dhe_psk(ssl);
  10783. if (ret != 0) {
  10784. // failed to set no DHE for PSK handshakes
  10785. }
  10786. \endcode
  10787. \sa wolfSSL_CTX_no_dhe_psk
  10788. */
  10789. int wolfSSL_no_dhe_psk(WOLFSSL* ssl);
  10790. /*!
  10791. \ingroup IO
  10792. \brief This function is called on a TLS v1.3 client or server wolfSSL to
  10793. force the rollover of keys. A KeyUpdate message is sent to the peer and
  10794. new keys are calculated for encryption. The peer will send back a KeyUpdate
  10795. message and the new decryption keys will then be calculated.
  10796. This function can only be called after a handshake has been completed.
  10797. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10798. \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
  10799. \return WANT_WRITE if the writing is not ready.
  10800. \return WOLFSSL_SUCCESS if successful.
  10801. _Example_
  10802. \code
  10803. int ret;
  10804. WOLFSSL* ssl;
  10805. ...
  10806. ret = wolfSSL_update_keys(ssl);
  10807. if (ret == WANT_WRITE) {
  10808. // need to call again when I/O ready
  10809. }
  10810. else if (ret != WOLFSSL_SUCCESS) {
  10811. // failed to send key update
  10812. }
  10813. \endcode
  10814. \sa wolfSSL_write
  10815. */
  10816. int wolfSSL_update_keys(WOLFSSL* ssl);
  10817. /*!
  10818. \ingroup IO
  10819. \brief This function is called on a TLS v1.3 client or server wolfSSL to
  10820. determine whether a rollover of keys is in progress. When
  10821. wolfSSL_update_keys() is called, a KeyUpdate message is sent and the
  10822. encryption key is updated. The decryption key is updated when the response
  10823. is received.
  10824. \param [in] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10825. \param [out] required 0 when no key update response required. 1 when no key update response required.
  10826. \return 0 on successful.
  10827. \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
  10828. _Example_
  10829. \code
  10830. int ret;
  10831. WOLFSSL* ssl;
  10832. int required;
  10833. ...
  10834. ret = wolfSSL_key_update_response(ssl, &required);
  10835. if (ret != 0) {
  10836. // bad parameters
  10837. }
  10838. if (required) {
  10839. // encrypt Key updated, awaiting response to change decrypt key
  10840. }
  10841. \endcode
  10842. \sa wolfSSL_update_keys
  10843. */
  10844. int wolfSSL_key_update_response(WOLFSSL* ssl, int* required);
  10845. /*!
  10846. \ingroup Setup
  10847. \brief This function is called on a TLS v1.3 client wolfSSL context to allow
  10848. a client certificate to be sent post handshake upon request from server.
  10849. This is useful when connecting to a web server that has some pages that
  10850. require client authentication and others that don't.
  10851. \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
  10852. with wolfSSL_CTX_new().
  10853. \return BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3.
  10854. \return SIDE_ERROR if called with a server.
  10855. \return 0 if successful.
  10856. _Example_
  10857. \code
  10858. int ret;
  10859. WOLFSSL_CTX* ctx;
  10860. ...
  10861. ret = wolfSSL_allow_post_handshake_auth(ctx);
  10862. if (ret != 0) {
  10863. // failed to allow post handshake authentication
  10864. }
  10865. \endcode
  10866. \sa wolfSSL_allow_post_handshake_auth
  10867. \sa wolfSSL_request_certificate
  10868. */
  10869. int wolfSSL_CTX_allow_post_handshake_auth(WOLFSSL_CTX* ctx);
  10870. /*!
  10871. \ingroup Setup
  10872. \brief This function is called on a TLS v1.3 client wolfSSL to allow
  10873. a client certificate to be sent post handshake upon request from server.
  10874. A Post-Handshake Client Authentication extension is sent in the ClientHello.
  10875. This is useful when connecting to a web server that has some pages that
  10876. require client authentication and others that don't.
  10877. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10878. \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
  10879. \return SIDE_ERROR if called with a server.
  10880. \return 0 if successful.
  10881. _Example_
  10882. \code
  10883. int ret;
  10884. WOLFSSL* ssl;
  10885. ...
  10886. ret = wolfSSL_allow_post_handshake_auth(ssl);
  10887. if (ret != 0) {
  10888. // failed to allow post handshake authentication
  10889. }
  10890. \endcode
  10891. \sa wolfSSL_CTX_allow_post_handshake_auth
  10892. \sa wolfSSL_request_certificate
  10893. */
  10894. int wolfSSL_allow_post_handshake_auth(WOLFSSL* ssl);
  10895. /*!
  10896. \ingroup IO
  10897. \brief This function requests a client certificate from the TLS v1.3 client.
  10898. This is useful when a web server is serving some pages that require client
  10899. authentication and others that don't.
  10900. A maximum of 256 requests can be sent on a connection.
  10901. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10902. \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
  10903. \return WANT_WRITE if the writing is not ready.
  10904. \return SIDE_ERROR if called with a client.
  10905. \return NOT_READY_ERROR if called when the handshake is not finished.
  10906. \return POST_HAND_AUTH_ERROR if posthandshake authentication is disallowed.
  10907. \return MEMORY_E if dynamic memory allocation fails.
  10908. \return WOLFSSL_SUCCESS if successful.
  10909. _Example_
  10910. \code
  10911. int ret;
  10912. WOLFSSL* ssl;
  10913. ...
  10914. ret = wolfSSL_request_certificate(ssl);
  10915. if (ret == WANT_WRITE) {
  10916. // need to call again when I/O ready
  10917. }
  10918. else if (ret != WOLFSSL_SUCCESS) {
  10919. // failed to request a client certificate
  10920. }
  10921. \endcode
  10922. \sa wolfSSL_allow_post_handshake_auth
  10923. \sa wolfSSL_write
  10924. */
  10925. int wolfSSL_request_certificate(WOLFSSL* ssl);
  10926. /*!
  10927. \ingroup Setup
  10928. \brief This function sets the list of elliptic curve groups to allow on
  10929. a wolfSSL context in order of preference.
  10930. The list is a null-terminated text string, and a colon-delimited list.
  10931. Call this function to set the key exchange elliptic curve parameters to
  10932. use with the TLS v1.3 connections.
  10933. \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
  10934. with wolfSSL_CTX_new().
  10935. \param [in] list a string that is a colon-delimited list of elliptic curve
  10936. groups.
  10937. \return WOLFSSL_FAILURE if pointer parameters are NULL, there are more than
  10938. WOLFSSL_MAX_GROUP_COUNT groups, a group name is not recognized or not
  10939. using TLS v1.3.
  10940. \return WOLFSSL_SUCCESS if successful.
  10941. _Example_
  10942. \code
  10943. int ret;
  10944. WOLFSSL_CTX* ctx;
  10945. const char* list = "P-384:P-256";
  10946. ...
  10947. ret = wolfSSL_CTX_set1_groups_list(ctx, list);
  10948. if (ret != WOLFSSL_SUCCESS) {
  10949. // failed to set group list
  10950. }
  10951. \endcode
  10952. \sa wolfSSL_set1_groups_list
  10953. \sa wolfSSL_CTX_set_groups
  10954. \sa wolfSSL_set_groups
  10955. \sa wolfSSL_UseKeyShare
  10956. \sa wolfSSL_preferred_group
  10957. */
  10958. int wolfSSL_CTX_set1_groups_list(WOLFSSL_CTX *ctx, char *list);
  10959. /*!
  10960. \ingroup Setup
  10961. \brief This function sets the list of elliptic curve groups to allow on
  10962. a wolfSSL in order of preference.
  10963. The list is a null-terminated text string, and a colon-delimited list.
  10964. Call this function to set the key exchange elliptic curve parameters to
  10965. use with the TLS v1.3 connections.
  10966. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10967. \param [in] list a string that is a colon separated list of key exchange
  10968. groups.
  10969. \return WOLFSSL_FAILURE if pointer parameters are NULL, there are more than
  10970. WOLFSSL_MAX_GROUP_COUNT groups, a group name is not recognized or not
  10971. using TLS v1.3.
  10972. \return WOLFSSL_SUCCESS if successful.
  10973. _Example_
  10974. \code
  10975. int ret;
  10976. WOLFSSL* ssl;
  10977. const char* list = "P-384:P-256";
  10978. ...
  10979. ret = wolfSSL_CTX_set1_groups_list(ssl, list);
  10980. if (ret != WOLFSSL_SUCCESS) {
  10981. // failed to set group list
  10982. }
  10983. \endcode
  10984. \sa wolfSSL_CTX_set1_groups_list
  10985. \sa wolfSSL_CTX_set_groups
  10986. \sa wolfSSL_set_groups
  10987. \sa wolfSSL_UseKeyShare
  10988. \sa wolfSSL_preferred_group
  10989. */
  10990. int wolfSSL_set1_groups_list(WOLFSSL *ssl, char *list);
  10991. /*!
  10992. \ingroup TLS
  10993. \brief This function returns the key exchange group the client prefers to
  10994. use in the TLS v1.3 handshake.
  10995. Call this function to after a handshake is complete to determine which
  10996. group the server prefers so that this information can be used in future
  10997. connections to pre-generate a key pair for key exchange.
  10998. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  10999. \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
  11000. \return SIDE_ERROR if called with a server.
  11001. \return NOT_READY_ERROR if called before handshake is complete.
  11002. \return Group identifier if successful.
  11003. _Example_
  11004. \code
  11005. int ret;
  11006. int group;
  11007. WOLFSSL* ssl;
  11008. ...
  11009. ret = wolfSSL_CTX_set1_groups_list(ssl)
  11010. if (ret < 0) {
  11011. // failed to get group
  11012. }
  11013. group = ret;
  11014. \endcode
  11015. \sa wolfSSL_UseKeyShare
  11016. \sa wolfSSL_CTX_set_groups
  11017. \sa wolfSSL_set_groups
  11018. \sa wolfSSL_CTX_set1_groups_list
  11019. \sa wolfSSL_set1_groups_list
  11020. */
  11021. int wolfSSL_preferred_group(WOLFSSL* ssl);
  11022. /*!
  11023. \ingroup Setup
  11024. \brief This function sets the list of elliptic curve groups to allow on
  11025. a wolfSSL context in order of preference.
  11026. The list is an array of group identifiers with the number of identifiers
  11027. specified in count.
  11028. Call this function to set the key exchange elliptic curve parameters to
  11029. use with the TLS v1.3 connections.
  11030. \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
  11031. with wolfSSL_CTX_new().
  11032. \param [in] groups a list of key exchange groups by identifier.
  11033. \param [in] count the number of key exchange groups in groups.
  11034. \return BAD_FUNC_ARG if a pointer parameter is null, the number of groups
  11035. exceeds WOLFSSL_MAX_GROUP_COUNT or not using TLS v1.3.
  11036. \return WOLFSSL_SUCCESS if successful.
  11037. _Example_
  11038. \code
  11039. int ret;
  11040. WOLFSSL_CTX* ctx;
  11041. int* groups = { WOLFSSL_ECC_X25519, WOLFSSL_ECC_SECP256R1 };
  11042. int count = 2;
  11043. ...
  11044. ret = wolfSSL_CTX_set1_groups_list(ctx, groups, count);
  11045. if (ret != WOLFSSL_SUCCESS) {
  11046. // failed to set group list
  11047. }
  11048. \endcode
  11049. \sa wolfSSL_set_groups
  11050. \sa wolfSSL_UseKeyShare
  11051. \sa wolfSSL_CTX_set_groups
  11052. \sa wolfSSL_set_groups
  11053. \sa wolfSSL_CTX_set1_groups_list
  11054. \sa wolfSSL_set1_groups_list
  11055. \sa wolfSSL_preferred_group
  11056. */
  11057. int wolfSSL_CTX_set_groups(WOLFSSL_CTX* ctx, int* groups,
  11058. int count);
  11059. /*!
  11060. \ingroup Setup
  11061. \brief This function sets the list of elliptic curve groups to allow on
  11062. a wolfSSL.
  11063. The list is an array of group identifiers with the number of identifiers
  11064. specified in count.
  11065. Call this function to set the key exchange elliptic curve parameters to
  11066. use with the TLS v1.3 connections.
  11067. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  11068. \param [in] groups a list of key exchange groups by identifier.
  11069. \param [in] count the number of key exchange groups in groups.
  11070. \return BAD_FUNC_ARG if a pointer parameter is null, the number of groups
  11071. exceeds WOLFSSL_MAX_GROUP_COUNT, any of the identifiers are unrecognized or
  11072. not using TLS v1.3.
  11073. \return WOLFSSL_SUCCESS if successful.
  11074. _Example_
  11075. \code
  11076. int ret;
  11077. WOLFSSL* ssl;
  11078. int* groups = { WOLFSSL_ECC_X25519, WOLFSSL_ECC_SECP256R1 };
  11079. int count = 2;
  11080. ...
  11081. ret = wolfSSL_set_groups(ssl, groups, count);
  11082. if (ret != WOLFSSL_SUCCESS) {
  11083. // failed to set group list
  11084. }
  11085. \endcode
  11086. \sa wolfSSL_CTX_set_groups
  11087. \sa wolfSSL_UseKeyShare
  11088. \sa wolfSSL_CTX_set_groups
  11089. \sa wolfSSL_set_groups
  11090. \sa wolfSSL_CTX_set1_groups_list
  11091. \sa wolfSSL_set1_groups_list
  11092. \sa wolfSSL_preferred_group
  11093. */
  11094. int wolfSSL_set_groups(WOLFSSL* ssl, int* groups, int count);
  11095. /*!
  11096. \ingroup IO
  11097. \brief This function is called on the client side and initiates a
  11098. TLS v1.3 handshake with a server. When this function is called, the
  11099. underlying communication channel has already been set up.
  11100. wolfSSL_connect() works with both blocking and non-blocking I/O.
  11101. When the underlying I/O is non-blocking, wolfSSL_connect() will return
  11102. when the underlying I/O could not satisfy the needs of wolfSSL_connect
  11103. to continue the handshake. In this case, a call to wolfSSL_get_error()
  11104. will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The
  11105. calling process must then repeat the call to wolfSSL_connect() when
  11106. the underlying I/O is ready and wolfSSL will pick up where it left off.
  11107. When using a non-blocking socket, nothing needs to be done, but select()
  11108. can be used to check for the required condition. If the underlying I/O is
  11109. blocking, wolfSSL_connect() will only return once the handshake has been
  11110. finished or an error occurred. wolfSSL takes a different approach to
  11111. certificate verification than OpenSSL does. The default policy for the
  11112. client is to verify the server, this means that if you don't load CAs to
  11113. verify the server you'll get a connect error, unable to verify (-155). It
  11114. you want to mimic OpenSSL behavior of having SSL_connect succeed even if
  11115. verifying the server fails and reducing security you can do this by
  11116. calling: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling
  11117. SSL_new(); Though it's not recommended.
  11118. \return SSL_SUCCESS upon success.
  11119. \return SSL_FATAL_ERROR will be returned if an error occurred. To get a
  11120. more detailed error code, call wolfSSL_get_error().
  11121. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  11122. _Example_
  11123. \code
  11124. int ret = 0;
  11125. int err = 0;
  11126. WOLFSSL* ssl;
  11127. char buffer[80];
  11128. ...
  11129. ret = wolfSSL_connect_TLSv13(ssl);
  11130. if (ret != SSL_SUCCESS) {
  11131. err = wolfSSL_get_error(ssl, ret);
  11132. printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
  11133. }
  11134. \endcode
  11135. \sa wolfSSL_get_error
  11136. \sa wolfSSL_connect
  11137. \sa wolfSSL_accept_TLSv13
  11138. \sa wolfSSL_accept
  11139. */
  11140. int wolfSSL_connect_TLSv13(WOLFSSL*);
  11141. /*!
  11142. \ingroup IO
  11143. \brief This function is called on the server side and waits for a SSL/TLS
  11144. client to initiate the SSL/TLS handshake. When this function is called,
  11145. the underlying communication channel has already been set up.
  11146. wolfSSL_accept() works with both blocking and non-blocking I/O.
  11147. When the underlying I/O is non-blocking, wolfSSL_accept() will return
  11148. when the underlying I/O could not satisfy the needs of wolfSSL_accept
  11149. to continue the handshake. In this case, a call to wolfSSL_get_error()
  11150. will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.
  11151. The calling process must then repeat the call to wolfSSL_accept when
  11152. data is available to read and wolfSSL will pick up where it left off.
  11153. When using a non-blocking socket, nothing needs to be done, but select()
  11154. can be used to check for the required condition. If the underlying I/O
  11155. is blocking, wolfSSL_accept() will only return once the handshake has
  11156. been finished or an error occurred.
  11157. Call this function when expecting a TLS v1.3 connection though older
  11158. version ClientHello messages are supported.
  11159. \return SSL_SUCCESS upon success.
  11160. \return SSL_FATAL_ERROR will be returned if an error occurred. To get a
  11161. more detailed error code, call wolfSSL_get_error().
  11162. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  11163. _Example_
  11164. \code
  11165. int ret = 0;
  11166. int err = 0;
  11167. WOLFSSL* ssl;
  11168. char buffer[80];
  11169. ...
  11170. ret = wolfSSL_accept_TLSv13(ssl);
  11171. if (ret != SSL_SUCCESS) {
  11172. err = wolfSSL_get_error(ssl, ret);
  11173. printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
  11174. }
  11175. \endcode
  11176. \sa wolfSSL_get_error
  11177. \sa wolfSSL_connect_TLSv13
  11178. \sa wolfSSL_connect
  11179. \sa wolfSSL_accept_TLSv13
  11180. \sa wolfSSL_accept
  11181. */
  11182. wolfSSL_accept_TLSv13(WOLFSSL* ssl);
  11183. /*!
  11184. \ingroup Setup
  11185. \brief This function sets the maximum amount of early data that a
  11186. TLS v1.3 client or server is willing to exchange using the wolfSSL context.
  11187. Call this function to limit the amount of early data to process to mitigate
  11188. replay attacks. Early data is protected by keys derived from those of the
  11189. connection that the session ticket was sent and therefore will be the same
  11190. every time a session ticket is used in resumption.
  11191. The value is included in the session ticket for resumption.
  11192. A server value of zero indicates no early data is to be sent by client using
  11193. session tickets. A client value of zero indicates that the client will
  11194. not send any early data.
  11195. It is recommended that the number of early data bytes be kept as low as
  11196. practically possible in the application.
  11197. \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
  11198. with wolfSSL_CTX_new().
  11199. \param [in] sz the amount of early data to accept in bytes.
  11200. \return BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3.
  11201. \return 0 if successful.
  11202. _Example_
  11203. \code
  11204. int ret;
  11205. WOLFSSL_CTX* ctx;
  11206. ...
  11207. ret = wolfSSL_CTX_set_max_early_data(ctx, 128);
  11208. if (ret != WOLFSSL_SUCCESS) {
  11209. // failed to set group list
  11210. }
  11211. \endcode
  11212. \sa wolfSSL_set_max_early_data
  11213. \sa wolfSSL_write_early_data
  11214. \sa wolfSSL_read_early_data
  11215. */
  11216. int wolfSSL_CTX_set_max_early_data(WOLFSSL_CTX* ctx,
  11217. unsigned int sz);
  11218. /*!
  11219. \ingroup Setup
  11220. \brief This function sets the maximum amount of early data that a
  11221. TLS v1.3 client or server is willing to exchange.
  11222. Call this function to limit the amount of early data to process to mitigate
  11223. replay attacks. Early data is protected by keys derived from those of the
  11224. connection that the session ticket was sent and therefore will be the same
  11225. every time a session ticket is used in resumption.
  11226. The value is included in the session ticket for resumption.
  11227. A server value of zero indicates no early data is to be sent by client using
  11228. session tickets. A client value of zero indicates that the client will
  11229. not send any early data.
  11230. It is recommended that the number of early data bytes be kept as low as
  11231. practically possible in the application.
  11232. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  11233. \param [in] sz the amount of early data to accept from client in bytes.
  11234. \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
  11235. \return 0 if successful.
  11236. _Example_
  11237. \code
  11238. int ret;
  11239. WOLFSSL* ssl;
  11240. ...
  11241. ret = wolfSSL_set_max_early_data(ssl, 128);
  11242. if (ret != WOLFSSL_SUCCESS) {
  11243. // failed to set group list
  11244. }
  11245. \endcode
  11246. \sa wolfSSL_CTX_set_max_early_data
  11247. \sa wolfSSL_write_early_data
  11248. \sa wolfSSL_read_early_data
  11249. */
  11250. int wolfSSL_set_max_early_data(WOLFSSL* ssl, unsigned int sz);
  11251. /*!
  11252. \ingroup IO
  11253. \brief This function writes early data to the server on resumption.
  11254. Call this function instead of wolfSSL_connect() or wolfSSL_connect_TLSv13()
  11255. to connect to the server and send the data in the handshake.
  11256. This function is only used with clients.
  11257. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  11258. \param [in] data the buffer holding the early data to write to server.
  11259. \param [in] sz the amount of early data to write in bytes.
  11260. \param [out] outSz the amount of early data written in bytes.
  11261. \return BAD_FUNC_ARG if a pointer parameter is NULL, sz is less than 0 or
  11262. not using TLSv1.3.
  11263. \return SIDE_ERROR if called with a server.
  11264. \return WOLFSSL_FATAL_ERROR if the connection is not made.
  11265. \return WOLFSSL_SUCCESS if successful.
  11266. _Example_
  11267. \code
  11268. int ret = 0;
  11269. int err = 0;
  11270. WOLFSSL* ssl;
  11271. byte earlyData[] = { early data };
  11272. int outSz;
  11273. char buffer[80];
  11274. ...
  11275. ret = wolfSSL_write_early_data(ssl, earlyData, sizeof(earlyData), &outSz);
  11276. if (ret != WOLFSSL_SUCCESS) {
  11277. err = wolfSSL_get_error(ssl, ret);
  11278. printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
  11279. goto err_label;
  11280. }
  11281. if (outSz < sizeof(earlyData)) {
  11282. // not all early data was sent
  11283. }
  11284. ret = wolfSSL_connect_TLSv13(ssl);
  11285. if (ret != SSL_SUCCESS) {
  11286. err = wolfSSL_get_error(ssl, ret);
  11287. printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
  11288. }
  11289. \endcode
  11290. \sa wolfSSL_read_early_data
  11291. \sa wolfSSL_connect
  11292. \sa wolfSSL_connect_TLSv13
  11293. */
  11294. int wolfSSL_write_early_data(WOLFSSL* ssl, const void* data,
  11295. int sz, int* outSz);
  11296. /*!
  11297. \ingroup IO
  11298. \brief This function reads any early data from a client on resumption.
  11299. Call this function instead of wolfSSL_accept() or wolfSSL_accept_TLSv13()
  11300. to accept a client and read any early data in the handshake. The function
  11301. should be invoked until wolfSSL_is_init_finished() returns true. Early data
  11302. may be sent by the client in multiple messsages. If there is no early data
  11303. then the handshake will be processed as normal. This function is only used
  11304. with servers.
  11305. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  11306. \param [out] data a buffer to hold the early data read from client.
  11307. \param [in] sz size of the buffer in bytes.
  11308. \param [out] outSz number of bytes of early data read.
  11309. \return BAD_FUNC_ARG if a pointer parameter is NULL, sz is less than 0 or
  11310. not using TLSv1.3.
  11311. \return SIDE_ERROR if called with a client.
  11312. \return WOLFSSL_FATAL_ERROR if accepting a connection fails.
  11313. \return Number of early data bytes read (may be zero).
  11314. _Example_
  11315. \code
  11316. int ret = 0;
  11317. int err = 0;
  11318. WOLFSSL* ssl;
  11319. byte earlyData[128];
  11320. int outSz;
  11321. char buffer[80];
  11322. ...
  11323. do {
  11324. ret = wolfSSL_read_early_data(ssl, earlyData, sizeof(earlyData), &outSz);
  11325. if (ret < 0) {
  11326. err = wolfSSL_get_error(ssl, ret);
  11327. printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
  11328. }
  11329. if (outSz > 0) {
  11330. // early data available
  11331. }
  11332. } while (!wolfSSL_is_init_finished(ssl));
  11333. \endcode
  11334. \sa wolfSSL_write_early_data
  11335. \sa wolfSSL_accept
  11336. \sa wolfSSL_accept_TLSv13
  11337. */
  11338. int wolfSSL_read_early_data(WOLFSSL* ssl, void* data, int sz,
  11339. int* outSz);
  11340. /*!
  11341. \ingroup Setup
  11342. \brief This function sets the Pre-Shared Key (PSK) client side callback
  11343. for TLS v1.3 connections.
  11344. The callback is used to find a PSK identity and return its key and
  11345. the name of the cipher to use for the handshake.
  11346. The function sets the client_psk_tls13_cb member of the
  11347. WOLFSSL_CTX structure.
  11348. \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
  11349. with wolfSSL_CTX_new().
  11350. \param [in] cb a Pre-Shared Key (PSK) callback for a TLS 1.3 client.
  11351. _Example_
  11352. \code
  11353. WOLFSSL_CTX* ctx;
  11354. ...
  11355. wolfSSL_CTX_set_psk_client_tls13_callback(ctx, my_psk_client_tls13_cb);
  11356. \endcode
  11357. \sa wolfSSL_set_psk_client_tls13_callback
  11358. \sa wolfSSL_CTX_set_psk_server_tls13_callback
  11359. \sa wolfSSL_set_psk_server_tls13_callback
  11360. */
  11361. void wolfSSL_CTX_set_psk_client_tls13_callback(WOLFSSL_CTX* ctx,
  11362. wc_psk_client_tls13_callback cb);
  11363. /*!
  11364. \ingroup Setup
  11365. \brief This function sets the Pre-Shared Key (PSK) client side callback
  11366. for TLS v1.3 connections.
  11367. The callback is used to find a PSK identity and return its key and
  11368. the name of the cipher to use for the handshake.
  11369. The function sets the client_psk_tls13_cb member of the options field in
  11370. WOLFSSL structure.
  11371. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  11372. \param [in] cb a Pre-Shared Key (PSK) callback for a TLS 1.3 client.
  11373. _Example_
  11374. \code
  11375. WOLFSSL* ssl;
  11376. ...
  11377. wolfSSL_set_psk_client_tls13_callback(ssl, my_psk_client_tls13_cb);
  11378. \endcode
  11379. \sa wolfSSL_CTX_set_psk_client_tls13_callback
  11380. \sa wolfSSL_CTX_set_psk_server_tls13_callback
  11381. \sa wolfSSL_set_psk_server_tls13_callback
  11382. */
  11383. void wolfSSL_set_psk_client_tls13_callback(WOLFSSL* ssl,
  11384. wc_psk_client_tls13_callback cb);
  11385. /*!
  11386. \ingroup Setup
  11387. \brief This function sets the Pre-Shared Key (PSK) server side callback
  11388. for TLS v1.3 connections.
  11389. The callback is used to find a PSK identity and return its key and
  11390. the name of the cipher to use for the handshake.
  11391. The function sets the server_psk_tls13_cb member of the
  11392. WOLFSSL_CTX structure.
  11393. \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
  11394. with wolfSSL_CTX_new().
  11395. \param [in] cb a Pre-Shared Key (PSK) callback for a TLS 1.3 server.
  11396. _Example_
  11397. \code
  11398. WOLFSSL_CTX* ctx;
  11399. ...
  11400. wolfSSL_CTX_set_psk_server_tls13_callback(ctx, my_psk_client_tls13_cb);
  11401. \endcode
  11402. \sa wolfSSL_CTX_set_psk_client_tls13_callback
  11403. \sa wolfSSL_set_psk_client_tls13_callback
  11404. \sa wolfSSL_set_psk_server_tls13_callback
  11405. */
  11406. void wolfSSL_CTX_set_psk_server_tls13_callback(WOLFSSL_CTX* ctx,
  11407. wc_psk_server_tls13_callback cb);
  11408. /*!
  11409. \ingroup Setup
  11410. \brief This function sets the Pre-Shared Key (PSK) server side callback
  11411. for TLS v1.3 connections.
  11412. The callback is used to find a PSK identity and return its key and
  11413. the name of the cipher to use for the handshake.
  11414. The function sets the server_psk_tls13_cb member of the options field in
  11415. WOLFSSL structure.
  11416. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  11417. \param [in] cb a Pre-Shared Key (PSK) callback for a TLS 1.3 server.
  11418. _Example_
  11419. \code
  11420. WOLFSSL* ssl;
  11421. ...
  11422. wolfSSL_set_psk_server_tls13_callback(ssl, my_psk_server_tls13_cb);
  11423. \endcode
  11424. \sa wolfSSL_CTX_set_psk_client_tls13_callback
  11425. \sa wolfSSL_set_psk_client_tls13_callback
  11426. \sa wolfSSL_CTX_set_psk_server_tls13_callback
  11427. */
  11428. void wolfSSL_set_psk_server_tls13_callback(WOLFSSL* ssl,
  11429. wc_psk_server_tls13_callback cb);
  11430. /*!
  11431. \ingroup Setup
  11432. \brief This function creates a key share entry from the group including
  11433. generating a key pair.
  11434. The KeyShare extension contains all the generated public keys for key
  11435. exchange. If this function is called, then only the groups specified will
  11436. be included.
  11437. Call this function when a preferred group has been previously established
  11438. for the server.
  11439. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  11440. \param [in] group a key exchange group identifier.
  11441. \return BAD_FUNC_ARG if ssl is NULL.
  11442. \return MEMORY_E when dynamic memory allocation fails.
  11443. \return WOLFSSL_SUCCESS if successful.
  11444. _Example_
  11445. \code
  11446. int ret;
  11447. WOLFSSL* ssl;
  11448. ...
  11449. ret = wolfSSL_UseKeyShare(ssl, WOLFSSL_ECC_X25519);
  11450. if (ret != WOLFSSL_SUCCESS) {
  11451. // failed to set key share
  11452. }
  11453. \endcode
  11454. \sa wolfSSL_preferred_group
  11455. \sa wolfSSL_CTX_set1_groups_list
  11456. \sa wolfSSL_set1_groups_list
  11457. \sa wolfSSL_CTX_set_groups
  11458. \sa wolfSSL_set_groups
  11459. \sa wolfSSL_NoKeyShares
  11460. */
  11461. int wolfSSL_UseKeyShare(WOLFSSL* ssl, word16 group);
  11462. /*!
  11463. \ingroup Setup
  11464. \brief This function is called to ensure no key shares are sent in the
  11465. ClientHello. This will force the server to respond with a HelloRetryRequest
  11466. if a key exchange is required in the handshake.
  11467. Call this function when the expected key exchange group is not known and
  11468. to avoid the generation of keys unnecessarily.
  11469. Note that an extra round-trip will be required to complete the handshake
  11470. when a key exchange is required.
  11471. \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  11472. \return BAD_FUNC_ARG if ssl is NULL.
  11473. \return SIDE_ERROR if called with a server.
  11474. \return WOLFSSL_SUCCESS if successful.
  11475. _Example_
  11476. \code
  11477. int ret;
  11478. WOLFSSL* ssl;
  11479. ...
  11480. ret = wolfSSL_NoKeyShares(ssl);
  11481. if (ret != WOLFSSL_SUCCESS) {
  11482. // failed to set no key shares
  11483. }
  11484. \endcode
  11485. \sa wolfSSL_UseKeyShare
  11486. */
  11487. int wolfSSL_NoKeyShares(WOLFSSL* ssl);
  11488. /*!
  11489. \ingroup Setup
  11490. \brief This function is used to indicate
  11491. that the application is a server and will only support the TLS 1.3
  11492. protocol. This function allocates memory for and initializes a new
  11493. wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  11494. with wolfSSL_CTX_new().
  11495. \param [in] heap a pointer to a buffer that the static memory allocator will use during dynamic memory allocation.
  11496. \return If successful, the call will return a pointer to the newly
  11497. created WOLFSSL_METHOD structure.
  11498. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  11499. value of the underlying malloc() implementation will be returned
  11500. (typically NULL with errno will be set to ENOMEM).
  11501. _Example_
  11502. \code
  11503. #include <wolfssl/ssl.h>
  11504. WOLFSSL_METHOD* method;
  11505. WOLFSSL_CTX* ctx;
  11506. method = wolfTLSv1_3_server_method_ex(NULL);
  11507. if (method == NULL) {
  11508. // unable to get method
  11509. }
  11510. ctx = wolfSSL_CTX_new(method);
  11511. ...
  11512. \endcode
  11513. \sa wolfSSLv3_server_method
  11514. \sa wolfTLSv1_server_method
  11515. \sa wolfTLSv1_1_server_method
  11516. \sa wolfTLSv1_2_server_method
  11517. \sa wolfTLSv1_3_server_method
  11518. \sa wolfDTLSv1_server_method
  11519. \sa wolfSSLv23_server_method
  11520. \sa wolfSSL_CTX_new
  11521. */
  11522. WOLFSSL_METHOD *wolfTLSv1_3_server_method_ex(void* heap);
  11523. /*!
  11524. \ingroup Setup
  11525. \brief This function is used to indicate
  11526. that the application is a client and will only support the TLS 1.3
  11527. protocol. This function allocates memory for and initializes a new
  11528. wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  11529. with wolfSSL_CTX_new().
  11530. \param [in] heap a pointer to a buffer that the static memory allocator will use during dynamic memory allocation.
  11531. \return If successful, the call will return a pointer to the newly
  11532. created WOLFSSL_METHOD structure.
  11533. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  11534. value of the underlying malloc() implementation will be returned
  11535. (typically NULL with errno will be set to ENOMEM).
  11536. _Example_
  11537. \code
  11538. #include <wolfssl/ssl.h>
  11539. WOLFSSL_METHOD* method;
  11540. WOLFSSL_CTX* ctx;
  11541. method = wolfTLSv1_3_client_method_ex(NULL);
  11542. if (method == NULL) {
  11543. // unable to get method
  11544. }
  11545. ctx = wolfSSL_CTX_new(method);
  11546. ...
  11547. \endcode
  11548. \sa wolfSSLv3_client_method
  11549. \sa wolfTLSv1_client_method
  11550. \sa wolfTLSv1_1_client_method
  11551. \sa wolfTLSv1_2_client_method
  11552. \sa wolfTLSv1_3_client_method
  11553. \sa wolfDTLSv1_client_method
  11554. \sa wolfSSLv23_client_method
  11555. \sa wolfSSL_CTX_new
  11556. */
  11557. WOLFSSL_METHOD *wolfTLSv1_3_client_method_ex(void* heap);
  11558. /*!
  11559. \ingroup Setup
  11560. \brief This function is used to indicate
  11561. that the application is a server and will only support the TLS 1.3
  11562. protocol. This function allocates memory for and initializes a new
  11563. wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  11564. with wolfSSL_CTX_new().
  11565. \return If successful, the call will return a pointer to the newly
  11566. created WOLFSSL_METHOD structure.
  11567. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  11568. value of the underlying malloc() implementation will be returned
  11569. (typically NULL with errno will be set to ENOMEM).
  11570. _Example_
  11571. \code
  11572. #include <wolfssl/ssl.h>
  11573. WOLFSSL_METHOD* method;
  11574. WOLFSSL_CTX* ctx;
  11575. method = wolfTLSv1_3_server_method();
  11576. if (method == NULL) {
  11577. // unable to get method
  11578. }
  11579. ctx = wolfSSL_CTX_new(method);
  11580. ...
  11581. \endcode
  11582. \sa wolfSSLv3_server_method
  11583. \sa wolfTLSv1_server_method
  11584. \sa wolfTLSv1_1_server_method
  11585. \sa wolfTLSv1_2_server_method
  11586. \sa wolfTLSv1_3_server_method_ex
  11587. \sa wolfDTLSv1_server_method
  11588. \sa wolfSSLv23_server_method
  11589. \sa wolfSSL_CTX_new
  11590. */
  11591. WOLFSSL_METHOD *wolfTLSv1_3_server_method(void);
  11592. /*!
  11593. \ingroup Setup
  11594. \brief This function is used to indicate
  11595. that the application is a client and will only support the TLS 1.3
  11596. protocol. This function allocates memory for and initializes a new
  11597. wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  11598. with wolfSSL_CTX_new().
  11599. \return If successful, the call will return a pointer to the newly
  11600. created WOLFSSL_METHOD structure.
  11601. \return FAIL If memory allocation fails when calling XMALLOC, the failure
  11602. value of the underlying malloc() implementation will be returned
  11603. (typically NULL with errno will be set to ENOMEM).
  11604. _Example_
  11605. \code
  11606. #include <wolfssl/ssl.h>
  11607. WOLFSSL_METHOD* method;
  11608. WOLFSSL_CTX* ctx;
  11609. method = wolfTLSv1_3_client_method();
  11610. if (method == NULL) {
  11611. // unable to get method
  11612. }
  11613. ctx = wolfSSL_CTX_new(method);
  11614. ...
  11615. \endcode
  11616. \sa wolfSSLv3_client_method
  11617. \sa wolfTLSv1_client_method
  11618. \sa wolfTLSv1_1_client_method
  11619. \sa wolfTLSv1_2_client_method
  11620. \sa wolfTLSv1_3_client_method_ex
  11621. \sa wolfDTLSv1_client_method
  11622. \sa wolfSSLv23_client_method
  11623. \sa wolfSSL_CTX_new
  11624. */
  11625. WOLFSSL_METHOD *wolfTLSv1_3_client_method(void);
  11626. /*!
  11627. \ingroup Setup
  11628. \brief This function returns a WOLFSSL_METHOD similar to
  11629. wolfTLSv1_3_client_method except that it is not determined
  11630. which side yet (server/client).
  11631. \param [in] heap a pointer to a buffer that the static memory allocator will use during dynamic memory allocation.
  11632. \return WOLFSSL_METHOD On successful creations returns a WOLFSSL_METHOD
  11633. pointer
  11634. \return NULL Null if memory allocation error or failure to create method
  11635. _Example_
  11636. \code
  11637. WOLFSSL* ctx;
  11638. ctx = wolfSSL_CTX_new(wolfTLSv1_3_method_ex(NULL));
  11639. // check ret value
  11640. \endcode
  11641. \sa wolfSSL_new
  11642. \sa wolfSSL_free
  11643. */
  11644. WOLFSSL_METHOD *wolfTLSv1_3_method_ex(void* heap);
  11645. /*!
  11646. \ingroup Setup
  11647. \brief This function returns a WOLFSSL_METHOD similar to
  11648. wolfTLSv1_3_client_method except that it is not determined
  11649. which side yet (server/client).
  11650. \return WOLFSSL_METHOD On successful creations returns a WOLFSSL_METHOD
  11651. pointer
  11652. \return NULL Null if memory allocation error or failure to create method
  11653. _Example_
  11654. \code
  11655. WOLFSSL* ctx;
  11656. ctx = wolfSSL_CTX_new(wolfTLSv1_3_method());
  11657. // check ret value
  11658. \endcode
  11659. \sa wolfSSL_new
  11660. \sa wolfSSL_free
  11661. */
  11662. WOLFSSL_METHOD *wolfTLSv1_3_method(void);
  11663. /*!
  11664. \ingroup SSL
  11665. \brief This function sets a fixed / static ephemeral key for testing only
  11666. \return 0 Key loaded successfully
  11667. \param ctx A WOLFSSL_CTX context pointer
  11668. \param keyAlgo enum wc_PkType like WC_PK_TYPE_DH and WC_PK_TYPE_ECDH
  11669. \param key key file path (if keySz == 0) or actual key buffer (PEM or ASN.1)
  11670. \param keySz key size (should be 0 for "key" arg is file path)
  11671. \param format WOLFSSL_FILETYPE_ASN1 or WOLFSSL_FILETYPE_PEM
  11672. \sa wolfSSL_CTX_get_ephemeral_key
  11673. */
  11674. int wolfSSL_CTX_set_ephemeral_key(WOLFSSL_CTX* ctx, int keyAlgo, const char* key, unsigned int keySz, int format);
  11675. /*!
  11676. \ingroup SSL
  11677. \brief This function sets a fixed / static ephemeral key for testing only
  11678. \return 0 Key loaded successfully
  11679. \param ssl A WOLFSSL object pointer
  11680. \param keyAlgo enum wc_PkType like WC_PK_TYPE_DH and WC_PK_TYPE_ECDH
  11681. \param key key file path (if keySz == 0) or actual key buffer (PEM or ASN.1)
  11682. \param keySz key size (should be 0 for "key" arg is file path)
  11683. \param format WOLFSSL_FILETYPE_ASN1 or WOLFSSL_FILETYPE_PEM
  11684. \sa wolfSSL_get_ephemeral_key
  11685. */
  11686. int wolfSSL_set_ephemeral_key(WOLFSSL* ssl, int keyAlgo, const char* key, unsigned int keySz, int format);
  11687. /*!
  11688. \ingroup SSL
  11689. \brief This function returns pointer to loaded key as ASN.1/DER
  11690. \return 0 Key returned successfully
  11691. \param ctx A WOLFSSL_CTX context pointer
  11692. \param keyAlgo enum wc_PkType like WC_PK_TYPE_DH and WC_PK_TYPE_ECDH
  11693. \param key key buffer pointer
  11694. \param keySz key size pointer
  11695. \sa wolfSSL_CTX_set_ephemeral_key
  11696. */
  11697. int wolfSSL_CTX_get_ephemeral_key(WOLFSSL_CTX* ctx, int keyAlgo,
  11698. const unsigned char** key, unsigned int* keySz);
  11699. /*!
  11700. \ingroup SSL
  11701. \brief This function returns pointer to loaded key as ASN.1/DER
  11702. \return 0 Key returned successfully
  11703. \param ssl A WOLFSSL object pointer
  11704. \param keyAlgo enum wc_PkType like WC_PK_TYPE_DH and WC_PK_TYPE_ECDH
  11705. \param key key buffer pointer
  11706. \param keySz key size pointer
  11707. \sa wolfSSL_set_ephemeral_key
  11708. */
  11709. int wolfSSL_get_ephemeral_key(WOLFSSL* ssl, int keyAlgo,
  11710. const unsigned char** key, unsigned int* keySz);
  11711. /*!
  11712. \ingroup SSL
  11713. \brief Sign a message with the chosen message digest, padding, and RSA key
  11714. \return WOLFSSL_SUCCESS on success and c on error
  11715. \param type Hash NID
  11716. \param m Message to sign. Most likely this will be the digest of
  11717. the message to sign
  11718. \param mLen Length of message to sign
  11719. \param sigRet Output buffer
  11720. \param sigLen On Input: length of sigRet buffer
  11721. On Output: length of data written to sigRet
  11722. \param rsa RSA key used to sign the input
  11723. \param flag 1: Output the signature
  11724. 0: Output the value that the unpadded signature should be
  11725. compared to. Note: for RSA_PKCS1_PSS_PADDING the
  11726. wc_RsaPSS_CheckPadding_ex function should be used to check
  11727. the output of a *Verify* function.
  11728. \param padding Padding to use. Only RSA_PKCS1_PSS_PADDING and
  11729. RSA_PKCS1_PADDING are currently supported for signing.
  11730. */
  11731. int wolfSSL_RSA_sign_generic_padding(int type, const unsigned char* m,
  11732. unsigned int mLen, unsigned char* sigRet,
  11733. unsigned int* sigLen, WOLFSSL_RSA* rsa,
  11734. int flag, int padding);
  11735. /*!
  11736. \brief checks if DTLSv1.3 stack has some messages sent but not yet acknowledged
  11737. by the other peer
  11738. \return 1 if there are pending messages, 0 otherwise
  11739. \param ssl A WOLFSSL object pointer
  11740. */
  11741. int wolfSSL_dtls13_has_pending_msg(WOLFSSL *ssl);
  11742. /*!
  11743. \ingroup SSL
  11744. \brief Get the maximum size of Early Data from a session.
  11745. \param [in] s the WOLFSSL_SESSION instance.
  11746. \return the value of max_early_data that was configured in the WOLFSSL* the session
  11747. was derived from.
  11748. \sa wolfSSL_set_max_early_data
  11749. \sa wolfSSL_write_early_data
  11750. \sa wolfSSL_read_early_data
  11751. */
  11752. unsigned int wolfSSL_SESSION_get_max_early_data(const WOLFSSL_SESSION *s);
  11753. /*!
  11754. \ingroup SSL
  11755. \brief Get a new index for external data. This entry applies also for the
  11756. following API:
  11757. - wolfSSL_CTX_get_ex_new_index
  11758. - wolfSSL_get_ex_new_index
  11759. - wolfSSL_SESSION_get_ex_new_index
  11760. - wolfSSL_X509_get_ex_new_index
  11761. \param [in] All input parameters are ignored. The callback functions are not
  11762. supported with wolfSSL.
  11763. \return The new index value to be used with the external data API for this
  11764. object class.
  11765. */
  11766. int wolfSSL_CRYPTO_get_ex_new_index(int, void*, void*, void*, void*);
  11767. /*!
  11768. \ingroup Setup
  11769. \brief In case this function is called in a client side, set certificate types
  11770. that can be sent to its peer. In case called in a server side,
  11771. set certificate types that can be acceptable from its peer. Put cert types in the
  11772. buffer with prioritised order. To reset the settings to default, pass NULL
  11773. for the buffer or pass zero for len. By default, certificate type is only X509.
  11774. In case both side intend to send or accept "Raw public key" cert,
  11775. WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
  11776. \return WOLFSSL_SUCCESS if cert types set successfully
  11777. \return BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as
  11778. cert type, buf size exceed MAX_CLIENT_CERT_TYPE_CNT was specified or
  11779. a duplicate value is found in buf.
  11780. \param ctx WOLFSSL_CTX object pointer
  11781. \param buf A buffer where certificate types are stored
  11782. \param len buf size in bytes (same as number of certificate types included)
  11783. _Example_
  11784. \code
  11785. int ret;
  11786. WOLFSSL_CTX* ctx;
  11787. char buf[] = {WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509};
  11788. int len = sizeof(buf)/sizeof(char);
  11789. ...
  11790. ret = wolfSSL_CTX_set_client_cert_type(ctx, buf, len);
  11791. \endcode
  11792. \sa wolfSSL_set_client_cert_type
  11793. \sa wolfSSL_CTX_set_server_cert_type
  11794. \sa wolfSSL_set_server_cert_type
  11795. \sa wolfSSL_get_negotiated_client_cert_type
  11796. \sa wolfSSL_get_negotiated_server_cert_type
  11797. */
  11798. int wolfSSL_CTX_set_client_cert_type(WOLFSSL_CTX* ctx, const char* buf, int len);
  11799. /*!
  11800. \ingroup Setup
  11801. \brief In case this function is called in a server side, set certificate types
  11802. that can be sent to its peer. In case called in a client side,
  11803. set certificate types that can be acceptable from its peer. Put cert types in the
  11804. buffer with prioritised order. To reset the settings to default, pass NULL
  11805. for the buffer or pass zero for len. By default, certificate type is only X509.
  11806. In case both side intend to send or accept "Raw public key" cert,
  11807. WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
  11808. \return WOLFSSL_SUCCESS if cert types set successfully
  11809. \return BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as
  11810. cert type, buf size exceed MAX_SERVER_CERT_TYPE_CNT was specified or
  11811. a duplicate value is found in buf.
  11812. \param ctx WOLFSSL_CTX object pointer
  11813. \param buf A buffer where certificate types are stored
  11814. \param len buf size in bytes (same as number of certificate types included)
  11815. _Example_
  11816. \code
  11817. int ret;
  11818. WOLFSSL_CTX* ctx;
  11819. char buf[] = {WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509};
  11820. int len = sizeof(buf)/sizeof(char);
  11821. ...
  11822. ret = wolfSSL_CTX_set_server_cert_type(ctx, buf, len);
  11823. \endcode
  11824. \sa wolfSSL_set_client_cert_type
  11825. \sa wolfSSL_CTX_set_client_cert_type
  11826. \sa wolfSSL_set_server_cert_type
  11827. \sa wolfSSL_get_negotiated_client_cert_type
  11828. \sa wolfSSL_get_negotiated_server_cert_type
  11829. */
  11830. int wolfSSL_CTX_set_server_cert_type(WOLFSSL_CTX* ctx, const char* buf, int len);
  11831. /*!
  11832. \ingroup Setup
  11833. \brief In case this function is called in a client side, set certificate types
  11834. that can be sent to its peer. In case called in a server side,
  11835. set certificate types that can be acceptable from its peer. Put cert types in the
  11836. buffer with prioritised order. To reset the settings to default, pass NULL
  11837. for the buffer or pass zero for len. By default, certificate type is only X509.
  11838. In case both side intend to send or accept "Raw public key" cert,
  11839. WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
  11840. \return WOLFSSL_SUCCESS if cert types set successfully
  11841. \return BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as
  11842. cert type, buf size exceed MAX_CLIENT_CERT_TYPE_CNT was specified or
  11843. a duplicate value is found in buf.
  11844. \param ssl WOLFSSL object pointer
  11845. \param buf A buffer where certificate types are stored
  11846. \param len buf size in bytes (same as number of certificate types included)
  11847. _Example_
  11848. \code
  11849. int ret;
  11850. WOLFSSL* ssl;
  11851. char buf[] = {WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509};
  11852. int len = sizeof(buf)/sizeof(char);
  11853. ...
  11854. ret = wolfSSL_set_client_cert_type(ssl, buf, len);
  11855. \endcode
  11856. \sa wolfSSL_CTX_set_client_cert_type
  11857. \sa wolfSSL_CTX_set_server_cert_type
  11858. \sa wolfSSL_set_server_cert_type
  11859. \sa wolfSSL_get_negotiated_client_cert_type
  11860. \sa wolfSSL_get_negotiated_server_cert_type
  11861. */
  11862. int wolfSSL_set_client_cert_type(WOLFSSL* ssl, const char* buf, int len);
  11863. /*!
  11864. \ingroup Setup
  11865. \brief In case this function is called in a server side, set certificate types
  11866. that can be sent to its peer. In case called in a client side,
  11867. set certificate types that can be acceptable from its peer. Put cert types in the
  11868. buffer with prioritised order. To reset the settings to default, pass NULL
  11869. for the buffer or pass zero for len. By default, certificate type is only X509.
  11870. In case both side intend to send or accept "Raw public key" cert,
  11871. WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
  11872. \return WOLFSSL_SUCCESS if cert types set successfully
  11873. \return BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as
  11874. cert type, buf size exceed MAX_SERVER_CERT_TYPE_CNT was specified or
  11875. a duplicate value is found in buf.
  11876. \param ctx WOLFSSL_CTX object pointer
  11877. \param buf A buffer where certificate types are stored
  11878. \param len buf size in bytes (same as number of certificate types included)
  11879. _Example_
  11880. \code
  11881. int ret;
  11882. WOLFSSL* ssl;
  11883. char buf[] = {WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509};
  11884. int len = sizeof(buf)/sizeof(char);
  11885. ...
  11886. ret = wolfSSL_set_server_cert_type(ssl, buf, len);
  11887. \endcode
  11888. \sa wolfSSL_set_client_cert_type
  11889. \sa wolfSSL_CTX_set_server_cert_type
  11890. \sa wolfSSL_set_server_cert_type
  11891. \sa wolfSSL_get_negotiated_client_cert_type
  11892. \sa wolfSSL_get_negotiated_server_cert_type
  11893. */
  11894. int wolfSSL_set_server_cert_type(WOLFSSL* ssl, const char* buf, int len);
  11895. /*!
  11896. \ingroup SSL
  11897. \brief This function returns the result of the client certificate type
  11898. negotiation done in ClientHello and ServerHello. WOLFSSL_SUCCESS is returned as
  11899. a return value if no negotiation occurs and WOLFSSL_CERT_TYPE_UNKNOWN is
  11900. returned as the certificate type.
  11901. \return WOLFSSL_SUCCESS if a negotiated certificate type could be got
  11902. \return BAD_FUNC_ARG if NULL was passed for ctx or tp
  11903. \param ssl WOLFSSL object pointer
  11904. \param tp A buffer where a certificate type is to be returned. One of three
  11905. certificate types will be returned: WOLFSSL_CERT_TYPE_RPK,
  11906. WOLFSSL_CERT_TYPE_X509 or WOLFSSL_CERT_TYPE_UNKNOWN.
  11907. _Example_
  11908. \code
  11909. int ret;
  11910. WOLFSSL* ssl;
  11911. int tp;
  11912. ...
  11913. ret = wolfSSL_get_negotiated_client_cert_type(ssl, &tp);
  11914. \endcode
  11915. \sa wolfSSL_set_client_cert_type
  11916. \sa wolfSSL_CTX_set_client_cert_type
  11917. \sa wolfSSL_set_server_cert_type
  11918. \sa wolfSSL_CTX_set_server_cert_type
  11919. \sa wolfSSL_get_negotiated_server_cert_type
  11920. */
  11921. int wolfSSL_get_negotiated_client_cert_type(WOLFSSL* ssl, int* tp);
  11922. /*!
  11923. \ingroup SSL
  11924. \brief This function returns the result of the server certificate type
  11925. negotiation done in ClientHello and ServerHello. WOLFSSL_SUCCESS is returned as
  11926. a return value if no negotiation occurs and WOLFSSL_CERT_TYPE_UNKNOWN is
  11927. returned as the certificate type.
  11928. \return WOLFSSL_SUCCESS if a negotiated certificate type could be got
  11929. \return BAD_FUNC_ARG if NULL was passed for ctx or tp
  11930. \param ssl WOLFSSL object pointer
  11931. \param tp A buffer where a certificate type is to be returned. One of three
  11932. certificate types will be returned: WOLFSSL_CERT_TYPE_RPK,
  11933. WOLFSSL_CERT_TYPE_X509 or WOLFSSL_CERT_TYPE_UNKNOWN.
  11934. _Example_
  11935. \code
  11936. int ret;
  11937. WOLFSSL* ssl;
  11938. int tp;
  11939.  ...
  11940. ret = wolfSSL_get_negotiated_server_cert_type(ssl, &tp);
  11941. \endcode
  11942. \sa wolfSSL_set_client_cert_type
  11943. \sa wolfSSL_CTX_set_client_cert_type
  11944. \sa wolfSSL_set_server_cert_type
  11945. \sa wolfSSL_CTX_set_server_cert_type
  11946. \sa wolfSSL_get_negotiated_client_cert_type
  11947. */
  11948. int wolfSSL_get_negotiated_server_cert_type(WOLFSSL* ssl, int* tp);
  11949. /*!
  11950. \brief Enable use of ConnectionID extensions for the SSL object. See RFC 9146
  11951. and RFC 9147
  11952. \return WOLFSSL_SUCCESS on success, error code otherwise
  11953. \param ssl A WOLFSSL object pointer
  11954. \sa wolfSSL_dtls_cid_is_enabled
  11955. \sa wolfSSL_dtls_cid_set
  11956. \sa wolfSSL_dtls_cid_get_rx_size
  11957. \sa wolfSSL_dtls_cid_get_rx
  11958. \sa wolfSSL_dtls_cid_get_tx_size
  11959. \sa wolfSSL_dtls_cid_get_tx
  11960. */
  11961. int wolfSSL_dtls_cid_use(WOLFSSL* ssl);
  11962. /*!
  11963. \brief If invoked after the handshake is complete it checks if ConnectionID was
  11964. successfully negotiated for the SSL object. See RFC 9146 and RFC 9147
  11965. \return 1 if ConnectionID was correctly negotiated, 0 otherwise
  11966. \param ssl A WOLFSSL object pointer
  11967. \sa wolfSSL_dtls_cid_use
  11968. \sa wolfSSL_dtls_cid_set
  11969. \sa wolfSSL_dtls_cid_get_rx_size
  11970. \sa wolfSSL_dtls_cid_get_rx
  11971. \sa wolfSSL_dtls_cid_get_tx_size
  11972. \sa wolfSSL_dtls_cid_get_tx
  11973. */
  11974. int wolfSSL_dtls_cid_is_enabled(WOLFSSL* ssl);
  11975. /*!
  11976. \brief Set the ConnectionID used by the other peer to send records in this
  11977. connection. See RFC 9146 and RFC 9147. The ConnectionID must be at maximum
  11978. DTLS_CID_MAX_SIZE, that is an tunable compile time define, and it can't
  11979. never be bigger than 255 bytes.
  11980. \return WOLFSSL_SUCCESS if ConnectionID was correctly set, error code otherwise
  11981. \param ssl A WOLFSSL object pointern
  11982. \param cid the ConnectionID to be used
  11983. \param size of the ConnectionID provided
  11984. \sa wolfSSL_dtls_cid_use
  11985. \sa wolfSSL_dtls_cid_is_enabled
  11986. \sa wolfSSL_dtls_cid_get_rx_size
  11987. \sa wolfSSL_dtls_cid_get_rx
  11988. \sa wolfSSL_dtls_cid_get_tx_size
  11989. \sa wolfSSL_dtls_cid_get_tx
  11990. */
  11991. int wolfSSL_dtls_cid_set(WOLFSSL* ssl, unsigned char* cid,
  11992. unsigned int size);
  11993. /*!
  11994. \brief Get the size of the ConnectionID used by the other peer to send records
  11995. in this connection. See RFC 9146 and RFC 9147. The size is stored in the
  11996. parameter size.
  11997. \return WOLFSSL_SUCCESS if ConnectionID was correctly negotiated, error code
  11998. otherwise
  11999. \param ssl A WOLFSSL object pointern
  12000. \param size a pointer to an unsigned int where the size will be stored
  12001. \sa wolfSSL_dtls_cid_use
  12002. \sa wolfSSL_dtls_cid_is_enabled
  12003. \sa wolfSSL_dtls_cid_set
  12004. \sa wolfSSL_dtls_cid_get_rx
  12005. \sa wolfSSL_dtls_cid_get_tx_size
  12006. \sa wolfSSL_dtls_cid_get_tx
  12007. */
  12008. int wolfSSL_dtls_cid_get_rx_size(WOLFSSL* ssl,
  12009. unsigned int* size);
  12010. /*!
  12011. \brief Copy the ConnectionID used by the other peer to send records in this
  12012. connection into the buffer pointed by the parameter buffer. See RFC 9146 and RFC
  12013. 9147. The available space in the buffer need to be provided in bufferSz.
  12014. \return WOLFSSL_SUCCESS if ConnectionID was correctly copied, error code
  12015. otherwise
  12016. \param ssl A WOLFSSL object pointern
  12017. \param buffer A buffer where the ConnectionID will be copied
  12018. \param bufferSz available space in buffer
  12019. \sa wolfSSL_dtls_cid_use
  12020. \sa wolfSSL_dtls_cid_is_enabled
  12021. \sa wolfSSL_dtls_cid_set
  12022. \sa wolfSSL_dtls_cid_get_rx_size
  12023. \sa wolfSSL_dtls_cid_get_tx_size
  12024. \sa wolfSSL_dtls_cid_get_tx
  12025. */
  12026. int wolfSSL_dtls_cid_get_rx(WOLFSSL* ssl, unsigned char* buffer,
  12027. unsigned int bufferSz);
  12028. /*!
  12029. \brief Get the size of the ConnectionID used to send records in this
  12030. connection. See RFC 9146 and RFC 9147. The size is stored in the parameter size.
  12031. \return WOLFSSL_SUCCESS if ConnectionID size was correctly stored, error
  12032. code otherwise
  12033. \param ssl A WOLFSSL object pointern
  12034. \param size a pointer to an unsigned int where the size will be stored
  12035. \sa wolfSSL_dtls_cid_use
  12036. \sa wolfSSL_dtls_cid_is_enabled
  12037. \sa wolfSSL_dtls_cid_set
  12038. \sa wolfSSL_dtls_cid_get_rx_size
  12039. \sa wolfSSL_dtls_cid_get_rx
  12040. \sa wolfSSL_dtls_cid_get_tx
  12041. */
  12042. int wolfSSL_dtls_cid_get_tx_size(WOLFSSL* ssl, unsigned int* size);
  12043. /*!
  12044. \brief Copy the ConnectionID used when sending records in this connection into
  12045. the buffer pointer by the parameter buffer. See RFC 9146 and RFC 9147. The
  12046. available size need to be provided in bufferSz.
  12047. \return WOLFSSL_SUCCESS if ConnectionID was correctly copied, error code
  12048. otherwise
  12049. \param ssl A WOLFSSL object pointern
  12050. \param buffer A buffer where the ConnectionID will be copied
  12051. \param bufferSz available space in buffer
  12052. \sa wolfSSL_dtls_cid_use
  12053. \sa wolfSSL_dtls_cid_is_enabled
  12054. \sa wolfSSL_dtls_cid_set
  12055. \sa wolfSSL_dtls_cid_get_rx_size
  12056. \sa wolfSSL_dtls_cid_get_rx
  12057. \sa wolfSSL_dtls_cid_get_tx_size
  12058. */
  12059. int wolfSSL_dtls_cid_get_tx(WOLFSSL* ssl, unsigned char* buffer,
  12060. unsigned int bufferSz);
  12061. /*!
  12062. \ingroup TLS
  12063. \brief This function returns the raw list of ciphersuites and signature
  12064. algorithms offered by the client. The lists are only stored and returned
  12065. inside a callback setup with wolfSSL_CTX_set_cert_cb(). This is useful to
  12066. be able to dynamically load certificates and keys based on the available
  12067. ciphersuites and signature algorithms.
  12068. \param [in] ssl The WOLFSSL object to extract the lists from.
  12069. \param [out] optional suites Raw and unfiltered list of client ciphersuites
  12070. \param [out] optional suiteSz Size of suites in bytes
  12071. \param [out] optional hashSigAlgo Raw and unfiltered list of client
  12072. signature algorithms
  12073. \param [out] optional hashSigAlgoSz Size of hashSigAlgo in bytes
  12074. \return WOLFSSL_SUCCESS when suites available
  12075. \return WOLFSSL_FAILURE when suites not available
  12076. _Example_
  12077. \code
  12078. int certCB(WOLFSSL* ssl, void* arg)
  12079. {
  12080. const byte* suites = NULL;
  12081. word16 suiteSz = 0;
  12082. const byte* hashSigAlgo = NULL;
  12083. word16 hashSigAlgoSz = 0;
  12084. wolfSSL_get_client_suites_sigalgs(ssl, &suites, &suiteSz, &hashSigAlgo,
  12085. &hashSigAlgoSz);
  12086. // Choose certificate to load based on ciphersuites and sigalgs
  12087. }
  12088. WOLFSSL* ctx;
  12089. ctx = wolfSSL_CTX_new(wolfTLSv1_3_method_ex(NULL));
  12090. wolfSSL_CTX_set_cert_cb(ctx, certCB, NULL);
  12091. \endcode
  12092. \sa wolfSSL_get_ciphersuite_info
  12093. \sa wolfSSL_get_sigalg_info
  12094. */
  12095. int wolfSSL_get_client_suites_sigalgs(const WOLFSSL* ssl,
  12096. const byte** suites, word16* suiteSz,
  12097. const byte** hashSigAlgo, word16* hashSigAlgoSz);
  12098. /*!
  12099. \ingroup TLS
  12100. \brief This returns information about the ciphersuite directly from the
  12101. raw ciphersuite bytes.
  12102. \param [in] first First byte of the ciphersuite
  12103. \param [in] second Second byte of the ciphersuite
  12104. \return WOLFSSL_CIPHERSUITE_INFO A struct containing information about the
  12105. type of authentication used in the ciphersuite.
  12106. _Example_
  12107. \code
  12108. WOLFSSL_CIPHERSUITE_INFO info =
  12109. wolfSSL_get_ciphersuite_info(suites[0], suites[1]);
  12110. if (info.rsaAuth)
  12111. haveRSA = 1;
  12112. else if (info.eccAuth)
  12113. haveECC = 1;
  12114. \endcode
  12115. \sa wolfSSL_get_client_suites_sigalgs
  12116. \sa wolfSSL_get_sigalg_info
  12117. */
  12118. WOLFSSL_CIPHERSUITE_INFO wolfSSL_get_ciphersuite_info(byte first,
  12119. byte second);
  12120. /*!
  12121. \ingroup TLS
  12122. \brief This returns information about the hash and signature algorithm
  12123. directly from the raw ciphersuite bytes.
  12124. \param [in] first First byte of the hash and signature algorithm
  12125. \param [in] second Second byte of the hash and signature algorithm
  12126. \param [out] hashAlgo The enum wc_HashType of the MAC algorithm
  12127. \param [out] sigAlgo The enum Key_Sum of the authentication algorithm
  12128. \return 0 when info was correctly set
  12129. \return BAD_FUNC_ARG when either input paramters are NULL or the bytes
  12130. are not a recognized sigalg suite
  12131. _Example_
  12132. \code
  12133. enum wc_HashType hashAlgo;
  12134. enum Key_Sum sigAlgo;
  12135. wolfSSL_get_sigalg_info(hashSigAlgo[idx+0], hashSigAlgo[idx+1],
  12136. &hashAlgo, &sigAlgo);
  12137. if (sigAlgo == RSAk || sigAlgo == RSAPSSk)
  12138. haveRSA = 1;
  12139. else if (sigAlgo == ECDSAk)
  12140. haveECC = 1;
  12141. \endcode
  12142. \sa wolfSSL_get_client_suites_sigalgs
  12143. \sa wolfSSL_get_ciphersuite_info
  12144. */
  12145. int wolfSSL_get_sigalg_info(byte first, byte second,
  12146. int* hashAlgo, int* sigAlgo);