Google Git
Sign in
eclipse / gerrit / www.eclipse.org / cognicrypt / 1cfa597265f40e32192d8368beab07d3ac3a46b0 / . / documentation / codegen / index.html
blob: 013b543a46c078fb4103c7eb219ed32624ab6541 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Code Generation | CogniCrypt</title>
<meta property="og:title" content="Code Generation | CogniCrypt" />
<meta name="twitter:title" content="Code Generation | CogniCrypt" />
<meta name="description" content="* { margin: 0; padding: 0; } .imgbox { display: grid; height: 100%; } .center-fit { max-width: 100%; max-height: 100vh; margin: auto; } This tutorial page describes how one would use CogniCrypt&rsquo;s code-generation feature. For a more technical description of how the code generation works in the background, please refer to Tool Paper on CogniCrypt published at ASE 2017.
Launching the Code Generator CogniCrypt&rsquo;s code generator can most easily be triggered by clicking the CogniCrypt button in the Eclipse tool bar.">
<meta property="og:description" content="* { margin: 0; padding: 0; } .imgbox { display: grid; height: 100%; } .center-fit { max-width: 100%; max-height: 100vh; margin: auto; } This tutorial page describes how one would use CogniCrypt&rsquo;s code-generation feature. For a more technical description of how the code generation works in the background, please refer to Tool Paper on CogniCrypt published at ASE 2017.
Launching the Code Generator CogniCrypt&rsquo;s code generator can most easily be triggered by clicking the CogniCrypt button in the Eclipse tool bar.">
<meta name="twitter:description" content="* { margin: 0; padding: 0; } .imgbox { display: grid; height: 100%; } .center-fit { max-width: 100%; max-height: 100vh; margin: auto; } This tutorial page describes how one would use …">
<meta name="author" content="Eclipse Foundation"/>
<link href='https://www.eclipse.org/cognicrypt/favicon.ico' rel='icon' type='image/x-icon'/>
<meta name="twitter:card" content="summary" />
<meta property="og:url" content="https://www.eclipse.org/cognicrypt/documentation/codegen/" />
<meta property="og:type" content="website" />
<meta property="og:site_name" content="Securely using Cryptography with CogniCrypt" />
<meta name="keywords" content="">
<meta name="generator" content="Hugo 0.42.1" />
<link rel="canonical" href="https://www.eclipse.org/cognicrypt/documentation/codegen/" />
<link rel="alternate" href="https://www.eclipse.org/cognicrypt/documentation/codegen/index.xml" type="application/rss+xml" title="Securely using Cryptography with CogniCrypt">
<link rel="stylesheet" href="https://www.eclipse.org/cognicrypt/assets/css/bootstrap.css">
<link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
<link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
<link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
<link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
<link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
<link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
<link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
<link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
<link rel="icon" type="image/png" sizes="192x192" href="/android-icon-192x192.png">
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="96x96" href="/favicon-96x96.png">
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
<link rel="manifest" href="/manifest.json">
<meta name="msapplication-TileColor" content="#ffffff">
<meta name="msapplication-TileImage" content="/ms-icon-144x144.png">
<meta name="theme-color" content="#ffffff">
<link href="//fonts.googleapis.com/css?family=Libre+Franklin:400,700,300,600,100" rel="stylesheet" type="text/css">
</head>
<body>
<header class="homepage">
<nav class="navbar navbar-default">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="https://www.eclipse.org/cognicrypt/">
<img alt="Eclipse CogniCrypt" src="https://www.eclipse.org/cognicrypt//assets/images/cognicrypt-logo.png">
</a>
</div>
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav navbar-right">
<li>
<a class="" href="/cognicrypt/publications/">
Publications
</a>
</li>
<li>
<a class="" href="/cognicrypt/downloads/">
Downloads
</a>
</li>
<li class="dropdown">
<a href="#" data-toggle="dropdown" class="dropdown-toggle">
<span>Documentation</span>
<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li class="active"><a href="/cognicrypt/documentation/codegen/">Code Generation</a> </li>
<li><a href="/cognicrypt/documentation/crysl/">CrySL Language</a> </li>
<li><a href="/cognicrypt/documentation/codeanalysis/">Static Code Analysis</a> </li>
</ul>
</li>
<li class="dropdown">
<a href="#" data-toggle="dropdown" class="dropdown-toggle">
<span>Contributing</span>
<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li><a href="/cognicrypt/contributing#bugs">Bugs and Feature Requests</a> </li>
<li><a href="/cognicrypt/contributing#code">Code Contributions</a> </li>
<li><a href="/cognicrypt/contributing#prim">Cryptographic Primitives</a> </li>
<li><a href="/cognicrypt/contributing#tasks">Cryptographic Tasks</a> </li>
</ul>
</li>
<li>
<a class="" href="/cognicrypt/news/">
News
</a>
</li>
<li class="dropdown eclipse-more hidden-xs">
<a data-toggle="dropdown" class="dropdown-toggle" role="button">More<b class="caret"></b></a>
<ul class="dropdown-menu">
<li>
<div class="yamm-content">
<div class="row">
<ul class="col-sm-8 list-unstyled">
<li>
<p><strong>Community</strong></p>
</li>
<li><a href="http://marketplace.eclipse.org">Marketplace</a></li>
<li><a href="http://events.eclipse.org">Events</a></li>
<li><a href="http://www.planeteclipse.org/">Planet Eclipse</a></li>
<li><a href="https://www.eclipse.org/community/eclipse_newsletter/">Newsletter</a></li>
<li><a href="https://www.youtube.com/user/EclipseFdn">Videos</a></li>
<li><a href="https://blogs.eclipse.org">Blogs</a></li>
</ul>
<ul class="col-sm-8 list-unstyled">
<li>
<p><strong>Participate</strong></p>
</li>
<li><a href="https://bugs.eclipse.org/bugs/">Report a Bug</a></li>
<li><a href="https://www.eclipse.org/forums/">Forums</a></li>
<li><a href="https://www.eclipse.org/mail/">Mailing Lists</a></li>
<li><a href="https://wiki.eclipse.org/">Wiki</a></li>
<li><a href="https://wiki.eclipse.org/IRC">IRC</a></li>
</ul>
<ul class="col-sm-8 list-unstyled">
<li>
<p><strong>Eclipse IDE</strong></p>
</li>
<li><a href="https://www.eclipse.org/downloads">Download</a></li>
<li><a href="https://help.eclipse.org">Documentation</a></li>
<li><a href="https://www.eclipse.org/getting_started">Getting Started / Support</a></li>
<li><a href="https://www.eclipse.org/contribute/">How to Contribute</a></li>
<li><a href="https://www.eclipse.org/ide/">IDE and Tools</a></li>
<li><a href="https://www.eclipse.org/forums/index.php/f/89/">Newcomer Forum</a></li>
</ul>
</div>
</div>
</li>
</ul>
</li>
<li style="min-width: 100px; padding-top: 12px; padding-left: 50px; margin-left:-35px">
<a href="https://twitter.com/cognicrypt?ref_src=twsrc%5Etfw" class="twitter-follow-button" data-show-count="false" data-show-screen-name="false"></a><script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
</li>
</ul>
</div>
</div>
</nav>
<section class="container">
<div class="row">
<div class="col-md-8 col-sm-12">
<h1><span class="green">Eclipse</span> <span class="green">CogniCrypt</span></h1>
<p>Eclipse CogniCrypt is an intelligent open-source platform ensuring the secure usage of crypto components.</p>
</div>
</div>
</section>
</header>
<main class="main">
<section class="first">
<div class="container">
<div class="row">
<div class="col-md-10">
<h3><span class="green">Code Generation</span></h3>
</div>
</div>
</div>
</section>
<section class="second">
<div class="container">
<div class="col-md-10">
<style>
* {
margin: 0;
padding: 0;
}
.imgbox {
display: grid;
height: 100%;
}
.center-fit {
max-width: 100%;
max-height: 100vh;
margin: auto;
}
</style>
<p>This tutorial page describes how one would use CogniCrypt&rsquo;s code-generation feature. For a more technical description of how the code generation works in the background, please refer to <a href="http://bodden.de/pubs/knr+17cognicrypt.pdf">Tool Paper on CogniCrypt</a> published at ASE 2017.</p>
<h1 id="launching-the-code-generator">Launching the Code Generator</h1>
<p>CogniCrypt&rsquo;s code generator can most easily be triggered by clicking the CogniCrypt button in the Eclipse tool bar. In this case, CogniCrypt applies a number of heuristics to determine which project the code should be generated into. First and foremost, if a Java file is opened in the editor when the button is being clicked, CogniCrypt selects its project for code generation. Another way of triggering the code generator is through opening the context menu on the respective project and select the entry &ldquo;Launch CogniCrypt&rdquo; as displayed in the screenshot below.
<div class="imgbox">
<img class="center-fit" src='https://raw.githubusercontent.com/CROSSINGTUD/CogniCrypt/master/documentation/Images%20for%20Tutorial/02Context.png' alt="CogniCrypt Context Menu">
</div></p>
<h1 id="selecting-a-task">Selecting a Task</h1>
<p>When CogniCrypt launches, the following window pops up:
<div class="imgbox">
<img class="center-fit" src='https://raw.githubusercontent.com/CROSSINGTUD/CogniCrypt/master/documentation/Images%20for%20Tutorial/03MainMenu.png' alt="CogniCrypt Main Menu">
</div></p>
<p>Here, the user first has to select in the upper dropdown menu which project it wants CogniCrypt to generate the code into. The dropdown menu is populated with all Java projects in the workspace. If CogniCrypt was launched by means of the context menu, it auto-selects the respective project. Otherwise, CogniCrypt runs the heuristics sketched above. The second dropdown menu allows the user to select a cryptographic programming task. Currently, seven tasks are supported. The text box, below the second dropdown, shows a brief description of the task that is selected from the dropdown. Once the user has selected both a project and a task they can continue.</p>
<h1 id="configuring-a-solution">Configuring a Solution</h1>
<p>For each task, CogniCrypt asks the user a number of questions. These questions help CogniCrypt configure the solution it provides the user with in the end. For the task &ldquo;Encrypt Data Using a Secret Key&rdquo;(hereafter referred to as Encryption Task), CogniCrypt needs the user to answer the questions shown in the following screenshots:</p>
<div class="imgbox">
<img class="center-fit" src='https://raw.githubusercontent.com/CROSSINGTUD/CogniCrypt/master/documentation/Images%20for%20Tutorial/04Questions.png' alt="Questions for Encryption Task">
</div>
<div class="imgbox">
<img class="center-fit" src='https://raw.githubusercontent.com/CROSSINGTUD/CogniCrypt/master/documentation/Images%20for%20Tutorial/04Questions1.png' alt="Questions for Encryption Task">
</div>
<p>The first question relates to the required security level as stronger security often impedes the performance of a given solution. Question 2 allows for an easier key generation by giving the user of the generated solution the opportunity to provide a password from which the key is derived. If &lsquo;no&rsquo; is selected, CogniCrypt generates code that employs the regular key generation mechanism of the JCA. If &lsquo;yes&rsquo; is selected, then handling the key should be taken care of by the user himself. The consequence of selecting an answer is specified in the form of &ldquo;Note&rdquo;, below the question. The third question, which appears in the next page, asks if the user has to encrypt large data regularly. The final question allows CogniCrypt&rsquo;s user to specify an input type for the encryption. The default data type are byte arrays. Should the user pick any other type, the generated code takes care of the type conversion for the user.</p>
<h1 id="selecting-a-solution">Selecting a Solution</h1>
<p>When the user has answered all questions, CogniCrypt configures a number of solutions for them. But, the most secure solution is provided to the user as a default solution, as shown in the screenshot below. The preview of the code that will be newly generated is also shown in the same page. If the user has a Java file open, then the code gets generated into the same file. So, the preview also shows the newly generated method inside the user&rsquo;s Java file. If a file is not open then the preview of the new class, that gets created, is shown in the preview. If the user wants to view more algorithm combinations matching his requirements, then the check box below the code preview should be checked and the user can click &ldquo;Next&rdquo;. If not, the user can click &ldquo;Finish&rdquo; to generate the code in his Java project.</p>
<div class="imgbox">
<img class="center-fit" src='https://raw.githubusercontent.com/CROSSINGTUD/CogniCrypt/master/documentation/Images%20for%20Tutorial/05ConfigurationSelection.png' alt="Final Screen for Solution Selection">
</div>
<p>If the user chooses to view other solutions, then a page, as shown in the screenshot below, appears on clicking &ldquo;Next&rdquo;. These algorithm combinations and their variations are ordered by security in descending order, but they are all secure and also fulfill the constraints the user has specified through their answers on the previous page(s). Thus, the user may pick any of the proposed solutions by selecting it in the dropdown menu. CogniCrypt auto-selects the most secure solution (the one which is shown in the previous page) by default. When the user has chosen an algorithm combination from the dropdown, he can view its variations(if any) with the help of &ldquo;&lt;&rdquo; and &ldquo;&gt;&rdquo; buttons. The properties of the chosen variation is shown in the &ldquo;Instance Details&rdquo; panel. They can select a variation of the algorithm combination and hit &ldquo;Finish&rdquo;, which prompts CogniCrypt to generate the solution under the chosen configuration into the user&rsquo;s project.</p>
<div class="imgbox">
<img class="center-fit" src='https://raw.githubusercontent.com/CROSSINGTUD/CogniCrypt/master/documentation/Images%20for%20Tutorial/05ConfigurationSelection-Alternatives.png' alt="Final Screen for Solution Selection">
</div>
<p>Additionally, the user can also view the preview of the code for the selected solution, by clicking the button in the same page. This opens a new dialog,as in below screenshot, which presents a comparison between the user&rsquo;s file, before and after the code generation. If no file is open in the user’s end, then a comparison between an empty file and the newly created class file is shown. The dialog shows the code comparison in the same way as that of the &ldquo;Compare Editor&rdquo;
of eclipse.</p>
<div class="imgbox">
<img class="center-fit" src='https://raw.githubusercontent.com/CROSSINGTUD/CogniCrypt/master/documentation/Images%20for%20Tutorial/05ConfigurationSelection-CodeComparison.png' alt="Final Screen for Solution Selection">
</div>
<p>Further, there is also a new wizard that opens on clicking &ldquo;Compare Algorithms&rdquo; button. This allows the user to compare two algorithms of his choice. This wizard has two combo boxes and two corresponding panels to display the properties of the chosen algorithms. Initially, both the combo boxes have the first element selected by default. Since the elements in the combo boxes are same, their properties will also be identical. If two different algorithm combinations are selected for comparison, then the properties that differ in their values will be highlighted.</p>
<div class="imgbox">
<img class="center-fit" src='https://raw.githubusercontent.com/CROSSINGTUD/CogniCrypt/master/documentation/Images%20for%20Tutorial/05ConfigurationSelection-AlgorithmComparison.png' alt="Final Screen for Solution Selection">
</div>
<h1 id="integrating-the-solution-into-the-application">Integrating the Solution into the Application</h1>
<p>For the each task, CogniCrypt generates two code artefacts. First, there is the actual implementation. It is always generated into a package called &ldquo;Crypto&rdquo;. The encryption task is rather simple and merely comprises of one class as shown below. Other tasks might be more compley and require more code, though.
<div class="imgbox">
<img class="center-fit" src='https://raw.githubusercontent.com/CROSSINGTUD/CogniCrypt/master/documentation/Images%20for%20Tutorial/07Encryption.png' alt="Actual Implementation of Encryption Task">
</div></p>
<p>The second artefact is a glue-code method called &ldquo;templateUsage&rdquo; showcasing to the developer how to properly use the implementation in their application. If, at the time of launching CogniCrypt, there is a Java file open in the Eclipse Editor that also belongs to the project the user selects on CogniCrypt&rsquo;s first screen, CogniCrypt generates the method into this class assuming that it is the right context for it. Is either of those two conditions not met, i.e., either no Java is opened or the file&rsquo;s project does not match the selected project, CogniCrypt generates the method into a class Output, also under the &ldquo;Crypto&rdquo; package.
<div class="imgbox">
<img class="center-fit" src='https://raw.githubusercontent.com/CROSSINGTUD/CogniCrypt/master/documentation/Images%20for%20Tutorial/06TemplateUsage.png' alt="Sample Method showcasing usage of Wrapper Code">
</div></p>
<p>Finally, to integrate the generated code into their application, the user may choose to simply call the &ldquo;templateUsage&rdquo; method or copy-paste the statements from the method they need in their code to the right place. By means of its <a href="../code-analysis">Code analysis</a>, CogniCrypt will ensure its user does not break the security during integration.</p>
</div>
</div>
</section>
</main>
<footer id="solstice-footer">
<div class="container">
<div class="row">
<section class="col-sm-3 hidden-print" id="footer-eclipse-foundation">
<h2 class="section-title" style="color:#fff;">Eclipse Foundation</h2>
<ul class="nav">
<li><a href="https://www.eclipse.org/org/">About Us</a></li>
<li><a href="https://www.eclipse.org/org/foundation/contact.php">Contact
Us</a></li>
<li><a href="https://www.eclipse.org/donate">Donate</a></li>
<li><a href="https://www.eclipse.org/org/documents/">Governance</a></li>
<li><a href="https://www.eclipse.org/artwork/">Logo and
Artwork</a></li>
<li><a
href="https://www.eclipse.org/org/foundation/directors.php"
>Board of Directors</a></li>
</ul>
</section>
<section class="col-sm-3 hidden-print" id="footer-legal">
<h2 class="section-title" style="color:#fff;">Legal</h2>
<ul class="nav">
<li><a href="https://www.eclipse.org/legal/privacy.php">Privacy
Policy</a></li>
<li><a href="https://www.eclipse.org/legal/termsofuse.php">Terms
of Use</a></li>
<li><a href="https://www.eclipse.org/legal/copyright.php">Copyright
Agent</a></li>
<li><a href="https://www.eclipse.org/legal/epl-2.0/">Eclipse
Public License</a></li>
<li><a href="https://www.eclipse.org/legal/">Legal Resources
</a></li>
</ul>
</section>
<section class="col-sm-3 hidden-print" id="footer-useful-links">
<h2 class="section-title" style="color:#fff;">Useful Links</h2>
<ul class="nav">
<li><a href="https://bugs.eclipse.org/bugs/">Report a Bug</a></li>
<li><a href="//help.eclipse.org/">Documentation</a></li>
<li><a href="https://www.eclipse.org/contribute/">How to
Contribute</a></li>
<li><a href="https://www.eclipse.org/mail/">Mailing Lists</a></li>
<li><a href="https://www.eclipse.org/forums/">Forums</a></li>
<li><a href="//marketplace.eclipse.org">Marketplace</a></li>
</ul>
</section>
<section class="col-sm-3 hidden-print" id="footer-other">
<h2 class="section-title" style="color:#fff;">Other</h2>
<ul class="nav">
<li><a href="https://www.eclipse.org/ide/">IDE and Tools</a></li>
<li><a href="https://www.eclipse.org/projects">Community of
Projects</a></li>
<li><a href="https://www.eclipse.org/org/workinggroups/">Working
Groups</a></li>
<li><a href="https://www.eclipse.org/org/research/">Research@Eclipse</a></li>
<li><a href="https://status.eclipse.org">Service Status</a></li>
</ul>
</section>
<div class="col-sm-12 margin-top-20">
<div class="row">
<div id="copyright" class="col-md-8">
<p id="copyright-text" style="color:#fff;">Copyright © Eclipse Foundation, Inc. All
Rights Reserved.</p>
</div>
<div class="col-md-4 social-media">
<ul class="list-inline text-right">
<li><a class="social-media-link fa-stack fa-lg"
href="https://twitter.com/cognicrypt"
> <i class="fa fa-circle-thin fa-stack-2x"></i> <i
class="fa fa-twitter fa-stack-1x"
></i>
</a></li>
<li><a class="social-media-link fa-stack fa-lg"
href="https://www.youtube.com/channel/UCNKzeZzhIMOhWm9eqlP15kw"
> <i class="fa fa-circle-thin fa-stack-2x"></i> <i
class="fa fa-youtube fa-stack-1x"
></i>
</a></li>
<li><a class="social-media-link fa-stack fa-lg"
href="https://www.linkedin.com/company/eclipse-foundation"
> <i class="fa fa-circle-thin fa-stack-2x"></i> <i
class="fa fa-linkedin fa-stack-1x"
></i>
</a></li>
</ul>
</div>
</div>
</div>
</div>
</div>
</footer>
<script src="https://www.eclipse.org/cognicrypt/assets/js/main.js"></script>
<script src="js/shuffle.js"></script>
<script src="js/index.js"></script>
</body>
</html>